Krikos NPM

Universal, zero-runtime-dependency NPM library and CLI for agent identity: a registry, capability declaration, an enforced lifecycle, and an append-only, hash-chained audit trail. The IAM primitive for fleets of Massive Intelligence (IM) agents and non-human entities (NHE).

krikos is the control plane for your agent fleet. You issue an identity for each agent; it gets a deterministic fingerprint and, optionally, a cryptographic Ed25519 identity. The agent declares the capabilities it may exercise, moves through an enforced lifecycle (provisioned, active, suspended, revoked, expired, archived), and leaves a hash-chained audit trail behind every operation. Authorization is fail-closed. Packaged surfaces for A2A Signed Agent Cards, Model Context Protocol identity validation, Vercel AI SDK tool authorization, structural registry adapters, and bridges for Hermes Agent, Mastra, and LangChain. A CLI when you do not want to embed.

Core promise: zero required runtime dependencies, single-function setup, ergonomic TypeScript types, ESM + CJS dual distribution, SLSA provenance on every release.

Install

pnpm add @takk/krikos
# or: npm install @takk/krikos
# or: yarn add @takk/krikos
# or: bun add @takk/krikos

Sibling integrations use optional peer dependencies. Install only the ones you actually wire up:

pnpm add @takk/keymesh      # revoke an agent's credentials on revocation
pnpm add @takk/gaptime      # record agent lifecycle as bi-temporal facts

The core (@takk/krikos), the cryptographic a2a surface, and every guard run with no runtime dependencies at all.

Quickstart - issue, authorize, audit

// src/example.ts
import { createKrikos } from '@takk/krikos';

const krikos = createKrikos();

// Issue an identity for an agent and activate it.
const agent = krikos.issue({
  name: 'billing-reconciler',
  issuer: { id: 'platform-team' },
  capabilities: [{ name: 'payments', actions: ['read', 'refund'], resources: ['/invoices/*'] }],
  activate: true,
});

// Fail-closed authorization at the boundary, recorded in the audit trail.
if (krikos.authorize(agent.id, 'payments', 'refund', '/invoices/2026-06')) {
  // ... perform the refund
}

// Lifecycle: suspend, resume, rotate the credential, revoke.
krikos.suspend(agent.id, 'incident review');
krikos.resume(agent.id);
krikos.rotate(agent.id); // new fingerprint, old signature cleared
krikos.revoke(agent.id, 'offboarded'); // permanent; can() now returns false

// The full, append-only, hash-chained operation history.
console.log(krikos.verifyAuditChain()); // true

A revoked, suspended, expired, or provisioned agent can never authorize. can() is the pure check; authorize() is the same decision, recorded.

Quickstart - cryptographic identity and A2A Signed Agent Card

// src/example-a2a.ts
import { createKrikos } from '@takk/krikos';
import { issueSigned, nodeSigner, toAgentCard, verifyAgentCard } from '@takk/krikos/a2a';

const krikos = createKrikos();
const signer = nodeSigner();

// Issue, generate an Ed25519 key pair, sign the passport, attach the signature.
const { agent, keyPair } = await issueSigned(
  krikos,
  { name: 'web-researcher', issuer: { id: 'platform-team' }, activate: true },
  signer,
);
// Persist keyPair.privateKey in your own secret store; publish keyPair.publicKey as the issuer key.
// Krikos never retains the private key.

// Export a Signed Agent Card and verify it against the PINNED issuer key, no registry needed.
// Verification requires a trust anchor: the public key you trust, obtained out of band. A card
// signed by any other key is rejected, which is what defeats impersonation.
const card = toAgentCard(agent);
console.log(await verifyAgentCard(card, signer, keyPair.publicKey)); // true
console.log(await verifyAgentCard(card, signer, 'some-other-key')); // false

The same card verifies under webSigner() in a browser or an edge runtime, because the key encoding is byte-identical across runtimes. Without a pinned trust anchor there is no verifiable identity, only self-consistency (verifyCardConsistency); never trust the public key embedded in a card you received.

Lifecycle states

| State | Meaning | Can authorize | |---|---|---| | provisioned | Issued, not yet activated | No | | active | Live | Yes (unless past expiry) | | suspended | Temporarily disabled by an operator | No | | revoked | Permanently invalidated | No | | expired | Past its expiration instant | No | | archived | Retired record kept for audit | No |

The legal moves between states are a single table, src/lifecycle/transitions.ts. An illegal transition (resuming a revoked agent, activating an archived one) throws ERR_INVALID_TRANSITION and the registry is left untouched.

Surfaces

| Surface | Export | Use when | |---|---|---| | Core | @takk/krikos | Issue, list, lifecycle, capability authorization, audit | | A2A | @takk/krikos/a2a | Ed25519 signing, Signed Agent Card export and verification | | Vercel AI SDK | @takk/krikos/vercel | Authorize an agent's tool calls before they run | | MCP | @takk/krikos/mcp | Validate agent identity before honoring an MCP request | | Integrations | @takk/krikos/integrations | Register Hermes, Mastra, LangChain agents; sibling bridges | | Store | @takk/krikos/store | Write-through registry mirror to Postgres, SQLite, or KV | | Web | @takk/krikos/web | Browser surface with the Web Crypto signer | | Edge | @takk/krikos/edge | Stateless identity verification before execution |

CLI

krikos works as a local command over a JSON state file:

# Issue an active agent with a resource-scoped capability.
npx @takk/krikos issue --state fleet.json --name billing-bot --issuer platform-team \
  --cap payments:read,refund@/invoices/* --activate

# Fail-closed authorization check (exit 0 allow, 3 deny).
npx @takk/krikos can --state fleet.json --id <id> --capability payments --action refund

# Drive the lifecycle.
npx @takk/krikos revoke --state fleet.json --id <id> --reason "offboarded"

# Verify the audit hash chain (exit 0 intact, 4 broken).
npx @takk/krikos verify --state fleet.json

Inspect the fleet, or serve a hardened read-only API:

npx @takk/krikos inspect --state fleet.json
npx @takk/krikos serve --state fleet.json --port 4385 --token "$KRIKOS_TOKEN"

Run npx @takk/krikos help for the full command list. See examples/cli.md.

Authorization and lifecycle details

krikos.can(id, capability, action, resource?) returns true only when all of the following hold:

• the agent exists and its state is active;
• the agent is not past its expiresAt instant (enforced on the read, fail-closed, even before an explicit sweep);
• the agent declares a capability whose name matches, whose actions include action, and whose resource scope admits resource.

Resource patterns are deliberately small: * matches anything, a trailing * is a prefix match (/data/*), anything else is exact. No regex, no surprises.

Expiry is lazy on reads and explicit on writes: sweepExpired() transitions every past-expiry agent to expired and records each. rotate() bumps the credential version, recomputes the fingerprint, and clears any attached signature (which no longer attests to the new fingerprint). renew() extends expiry and can bring an expired agent back to active.

Telemetry

const off = krikos.on((event) => {
  switch (event.kind) {
    case 'agent.issued':
      log.info({ agentId: event.agentId });
      break;
    case 'agent.revoked':
      alerts.notify(`agent ${event.agentId} revoked`);
      break;
    case 'access.denied':
      metrics.increment('krikos.denied');
      break;
  }
});
off(); // unsubscribe

krikos does not depend on OpenTelemetry. A listener exception is swallowed and never reaches a caller; telemetry is best-effort.

Registry inspection

const stats = krikos.stats();
// {
//   total: 12,
//   byStatus: { provisioned: 2, active: 7, suspended: 1, revoked: 1, expired: 1, archived: 0 },
//   authorizable: 7,
//   issuers: 3,
//   auditEvents: 58
// }

const recent = krikos.auditTrail({ limit: 10 });
const intact = krikos.verifyAuditChain(); // recomputes the hash chain

The audit trail is append-only and is never pruned; prune(beforeArchivedAt) only drops archived agent records to bound the live registry, leaving the operation history intact.

Quality

• 126 tests across 16 suites, all passing under Vitest 4 on Node 22 and Node 24.
• Coverage: lines about 92%, statements about 92%, branches about 84%.
• Lint clean under Biome 2.
• Typecheck clean under TypeScript 6 in maximum strict mode (exactOptionalPropertyTypes, useUnknownInCatchVariables, noUncheckedIndexedAccess).
• publint clean, attw green across all eight entry points.
• An S1 to S10 fleet-governance scenario benchmark and a cross-bundle dist-parity smoke test.
• Published with --provenance (SLSA attestation by GitHub Actions).

See SPEC.md for the formal specification, public surface, and stability promise.

FAQ

How is this different from Auth0 or WorkOS? Those manage human identity. krikos manages non-human identity: agents, with capabilities they declare, an expiration, a credential to rotate, and an audit trail, governed the way a workforce identity platform governs employees.

How is this different from LangSmith, Braintrust, or Langfuse? Those are observability. They tell you what an agent did. krikos is identity and authorization: it decides what an agent may do, before it does it, and revokes that ability when the agent is retired.

Does it call out to any service? No. krikos runs entirely inside your own process. It makes no outbound calls, collects no telemetry, and ships no analytics.

Does this work in Cloudflare Workers / Vercel Edge / Bun / Deno / the browser? Yes. The core, a2a, web, and edge surfaces use only standard APIs (Web Crypto for signing off Node). The Node-only fileState backend is excluded from the web and edge entry points.

Where does the state live? By default, in-process memory. For durability use the file backend, or kvState over Redis, Upstash, or Cloudflare KV. For cross-process query, mirror the registry into Postgres, SQLite, or KV with @takk/krikos/store.

Is the audit trail cryptographically secure? The hash chain is tamper-evident integrity bookkeeping (it catches accidental corruption and naive edits), not cryptographic non-repudiation. For the latter, sign agents with the Ed25519 signer, or sign the snapshot out of band.

Contributing

See .github/CONTRIBUTING.md for the contributor guide. Substantive proposals open a GitHub Issue first; trivial fixes can go straight to a PR. All commits require DCO sign-off (git commit -s). Non-trivial contributions are governed by the Contributor License Agreement.

Community & support

• Issues & feature requests. Open a GitHub issue at davccavalcante/krikos/issues. For each report, include: the package version, a minimal reproduction, expected vs. actual behaviour, and (where relevant) the relevant telemetry events or a krikos.stats() snapshot.
• Security disclosures. Do NOT open public issues for vulnerabilities. Follow the responsible-disclosure flow in SECURITY.md, contacting [email protected] (or [email protected]) with the [SECURITY] prefix.
• Code of Conduct. This project follows the Contributor Covenant 2.1. Participation in any Krikos space (issues, PRs, discussions) implies agreement.
• Contributions. All non-trivial contributions go through the Contributor License Agreement. Tests, lint, typecheck, and build must be green before review (pnpm verify).

Author

Created by David C Cavalcante. [email protected] (preferred) · [email protected] (Takk relay) · linkedin.com/in/hellodav · x.com/davccavalcante · takk.ag

krikos is part of a broader portfolio of NPM packages targeting Massive Intelligence (IM) infrastructure for 2026-2030, built at Takk Innovate Studio.

Related research by the author

The architectural philosophy behind krikos, separating identity, capability, lifecycle, and audit into composable, independently-governed layers, echoes the author's research frameworks:

• MAIC (Massive Artificial Intelligence Consciousness), a systemic intelligence framework designed to coordinate, supervise, and govern large-scale intelligence ecosystems, providing global context awareness, alignment, and orchestration across multiple models, agents, and decision layers.
• HIM (Hybrid Entity Intelligence Model), a hybrid intelligence layer that integrates intelligence systems with human-defined logic, rules, heuristics, and strategic intent, interpreting objectives and structuring decision-making before and after model execution.
• NHE (Noumenal Higher-order Entity), a non-human cognitive entity with a defined functional identity and operational agency within an intelligence ecosystem, operating through coordinated intelligence layers while maintaining a non-anthropomorphic identity.

These frameworks are published independently of krikos and are separate works:

• Research papers: The Soul of the Machine · Beyond Consciousness in LLMs · The Cave of Silence.
• PhilPapers profile: David Cortes Cavalcante.
• Hugging Face: TeleologyHI.
• GitHub: davccavalcante · Takk8IS.

Sponsors

Join the journey as the portfolio continues to ship Massive Intelligence (IM) infrastructure. Your support is the cornerstone of this work.

• Sponsor on GitHub: github.com/sponsors/davccavalcante
• USDT (TRC-20): TS1vuhMAhFpbd7y68cu5ZtP9PsXVmZWmeh

Privacy

krikos runs entirely inside your own process and infrastructure. It makes no outbound calls to the author, collects no telemetry, and ships no analytics. The only data it holds is the agent registry and audit trail you build, persisted only through the state backend you configure. See PRIVACY.md for the full data-handling notice, including how the optional file backend persists state on disk and how cryptographic key material is handled.

License

Licensed under the Apache License 2.0. See LICENSE for the full text and NOTICE for attribution and third-party component licenses. You may use, modify, and distribute the code under the terms of that license, including its patent grant and attribution requirements.