@kya-os/mcp 1.7.0 → 1.9.0

package/CHANGELOG.md

@@ -7,6 +7,75 @@ Versioning: https://semver.org/spec/v2.0.0.html
 
 ## [Unreleased]
 
+## [1.9.0] - 2026-07-07
+
+Entity Card (`@kya-os/mcp/card`) — a typed, DID-anchored, per-request
+holder-of-key identity layer that rides existing rails (MCP server-card `_meta`,
+A2A extension, NANDA AgentFacts) instead of a new well-known doc. Additive.
+
+First npm release since 1.7.0 (the prepared 1.8.0 was never published). See the
+BREAKING status-list note below — persisted 1.x status lists MUST be
+regenerated on upgrade.
+
+### Added
+
+- **`./card`** — the `card()` builder, `withKyaOsCard` / `requireProof`
+  middleware, and `buildCard` / `resolveCard` / `verifyCard`. Conformance is
+  recomputed on verify, never self-claimed.
+- **Stateless proof (`org.kya-os/proof@1`)** and a **VC 2.0 / ZCAP-LD**
+  delegation profile with Bitstring Status List v1.0 revocation. Both run
+  alongside the legacy session proof + delegation for all of 1.x; the legacy
+  paths drop at 2.0.
+- **CIMD L1 on-ramp** — `client_id ⇄ did:web`, so an OAuth `private_key_jwt`
+  doubles as a DID-key proof (RFC 9449 `cnf.jkt` sender-constrains it).
+- Conformance vectors + a cross-language verifier folded into the existing
+  `conformance/` harness (new `card-proof` / `entity-card` categories).
+- **Proof crypto agility (`ES256`)** — the per-request proof now accepts an
+  ALLOW-LIST of two signing algorithms, `EdDSA` (Ed25519) and `ES256` (ECDSA
+  P-256, FIPS-eligible via HSM/KMS), never negotiated. `alg` is a signed covered
+  claim and the resolved key type MUST match it (`alg_key_mismatch`), so adding a
+  second curve introduces no algorithm-confusion surface. `es256SignerFromJwk`
+  ships alongside `ed25519SignerFromJwk`; the RFC 9421 sibling carries the
+  matching `ecdsa-p256-sha256` label. (CIMD DID-keyed JWKS extraction stays
+  Ed25519-only for now — a P-256 verifier supplies its own `resolveDidKeys`.)
+- **VC-JWT verification (`./delegation`)** — `DelegationCredentialVerifier.verifyDelegationJwt()`
+  verifies the JWT serialization of a Verifiable Credential (compact JWS, where
+  the envelope signature over `header.payload` IS the proof — no embedded
+  `proof` block), so credentials minted by browser / passkey wallets verify
+  without a hand-rolled path. `algorithms` is pinned to `EdDSA`, and the
+  credential `issuer` must equal the signed `iss`. Additive; the Data Integrity
+  path is unchanged.
+- **Multi-key did:web documents** — `buildDidWebDocument` now accepts
+  `Identity | Identity[]`, emitting one verification method per key under a
+  single controller DID. This is the basis for multi-device identity: a device
+  is added or removed by adding or removing a verification method, and a
+  verifier selects the signing key by `kid`. Backward-compatible — a lone
+  identity yields the same single-method document as before.
+
+### Changed — BREAKING for persisted status lists
+
+- **Status-list bit order corrected to W3C MSB-first.** `BitstringManager`
+  (StatusList2021 / Bitstring Status List) now reads and writes bits
+  most-significant-first (`0x80 >> i`), matching the W3C spec and the Digital
+  Bazaar reference — and the Entity Card revocation reader — so both code paths
+  read an identical `encodedList` to the same verdict. The prior LSB-first order
+  was self-consistent but non-interoperable with any standard tool.
+  - **⚠️ MIGRATION — READ THIS.** A status list generated by a 1.x release is
+    encoded LSB-first. Read by this release it is **misread silently**: a
+    **revoked credential can read as LIVE** (the bit mirrors within its byte, so
+    e.g. revoked index 42 → clear, and phantom index 45 → revoked). The W3C
+    credential carries no bit-order/version field, so old lists **cannot be
+    auto-detected**. You MUST **regenerate every persisted status list** on
+    upgrade; do not read 1.x-encoded lists with this release. (Tracking a
+    KYA-OS-side encoding-version marker + a bit-reverse migration helper as a
+    follow-up so future changes are detectable.)
+- **Fail-closed hardening.** `isIndexSet` / `BitstringManager.getBit` now throw
+  on an out-of-range or `NaN` index (were fail-open), `BitstringManager.decode`
+  caps the inflated bitstring at 16 MiB (decompression-bomb guard), and the card
+  `statusListIndex` must be a canonical decimal (a whitespace/hex value no longer
+  silently reads bit 0). IPv6 NAT64 / 6to4 / Teredo / site-local addresses are
+  now treated as non-public by the SSRF guard.
+
 ## [1.7.0] - 2026-06-17
 
 Durable consent persistence. Pluggable `GrantStore` / `PendingFlowStore` /

package/README.md

@@ -108,6 +108,44 @@ When an agent calls `checkout` without a delegation credential, it gets back a `
 
 ---
 
+## Typed, DID-anchored identity: the Entity Card
+
+Proofs answer *what an agent did*. The **Entity Card** answers *who is calling* — a typed, DID-anchored identity (`agent`, `mcp`, `client`, `verifier`, `human`) an entity publishes once and every discovery rail can index. It is claim-minimal: it asserts only identity, type, declared capabilities, and accountability locators. The trust **level** (L1/L2/L3) is never self-claimed — a verifier RECOMPUTES it from evidence. Three ergonomic calls, imported from the published `@kya-os/mcp/card` subpath:
+
+```typescript
+import { card, withKyaOsCard, requireProof, InMemoryNonceCache } from '@kya-os/mcp/card';
+
+// 1. BUILD — describe the agent, fluently. No conformanceLevel: a verifier derives it.
+const myCard = card({ did: 'did:web:acme.example:agents:pay', entityType: 'agent', name: 'Acme Pay' })
+  .capability('search')                                  // L1: bare-string, self-declared
+  .attestedCapability('payments.transfer', capabilityVc) // L2: VC-backed
+  .accountableTo('did:web:acme.example:org', { via: 'vc_root>del_123' })
+  .usesProof()
+  .build();
+
+// 2. EMIT — mount the three discovery artifacts (card.json, DID service entry, server.json _meta).
+const mount = withKyaOsCard(myCard);
+const serverJson = mount.mountServerJson({ name: 'acme-mcp', version: '1.0.0' });
+
+// 3. GUARD — verify a per-request holder-of-key proof, fail-closed.
+const nonces = new InMemoryNonceCache();     // ATOMIC replay defense — never hand-roll this seam
+const guard = requireProof({
+  resolveKey,                                // resolve the signing key from its kid (DID document)
+  expectedAudience: 'did:web:acme.example:mcp:server',
+  consumeNonceIfFresh: nonces.consume,       // test-AND-set; a replayed nonce is rejected
+});
+
+// Pass the EXACT body the client signed (without _meta) plus the _meta that carried the proof.
+const { _meta, ...signedBody } = incomingRequest;
+const verdict = await guard(signedBody, _meta); // { ok: true, did, level } or a 401-shaped reject
+```
+
+Miss the proof, replay a nonce, or tamper the body and `requireProof` fails closed. To go the other direction — DISCOVER and verify another entity's card — use `resolveCard` + `verifyCard` (the verifier recomputes the conformance floor rather than trusting the card).
+
+> Run the full 10-minute path end-to-end: [examples/entity-card](./examples/entity-card/) — `npm run example:entity-card:server` (build → emit → guard, with a valid proof accepted and a replay + tamper rejected) and `npm run example:entity-card` (the discover → resolve → verify walkthrough). See [SPEC-ENTITY-CARD.md](./SPEC-ENTITY-CARD.md) for normative detail.
+
+---
+
 ## See it in action
 
 ```bash
@@ -125,7 +163,7 @@ This starts all example servers and opens [MCP Inspector](https://github.com/mod
 | 3003 | [consent-full](./examples/consent-full/) | Production consent UI ([@kya-os/consent](https://www.npmjs.com/package/@kya-os/consent)) |
 | 3004 | [context7-with-kya-os](./examples/context7-with-kya-os/) | 2-line migration of a real MCP server |
 
-Also available: [outbound-delegation](./examples/outbound-delegation/) (gateway pattern), [verify-proof](./examples/verify-proof/) (standalone verification), [statuslist](./examples/statuslist/) (revocation lifecycle).
+Also available: [outbound-delegation](./examples/outbound-delegation/) (gateway pattern), [verify-proof](./examples/verify-proof/) (standalone verification), [statuslist](./examples/statuslist/) (revocation lifecycle), [cheqd-dlr](./examples/cheqd-dlr/) (operator DID linkage + DLR publishing).
 
 ---
 
@@ -133,7 +171,8 @@ Also available: [outbound-delegation](./examples/outbound-delegation/) (gateway
 
 | Capability | How it works |
 |-----------|-------------|
-| **Cryptographic identity** | Ed25519 key pairs, `did:key` and `did:web` resolution |
+| **Cryptographic identity** | Ed25519 (EdDSA) and P-256 (ES256, FIPS-eligible) key pairs, `did:key` / `did:web` resolution, optional `did:cheqd` resolver support |
+| **Entity Card** | Typed, DID-anchored identity: fluent `card()` builder, `withKyaOsCard` discovery projections, `requireProof` per-request holder-of-key guard |
 | **Signed proofs** | Detached JWS over JCS-canonicalized request/response hashes |
 | **Delegation credentials** | W3C Verifiable Credentials with scope constraints, rooted at a Responsible Party |
 | **Revocation** | StatusList2021 bitstring with cascading revocation |
@@ -151,9 +190,186 @@ flows, and sessions are shared across instances and survive restarts.
 
 ---
 
+## Optional did:cheqd and DID-Linked Resources
+
+`did:cheqd` support is additive and opt-in. Existing `did:key` and `did:web`
+flows remain unchanged, and operators can keep `did:web` as their canonical
+identifier while linking to a cheqd DID over time.
+
+### Resolver configuration
+
+```typescript
+import { RuntimeFetchProvider, withKyaOs, NodeCryptoProvider } from '@kya-os/mcp';
+import { cheqdResolver } from '@kya-os/mcp/cheqd';
+
+const crypto = new NodeCryptoProvider();
+const fetchProvider = new RuntimeFetchProvider();
+const didResolvers = {
+  cheqd: cheqdResolver({ resolverUrl: 'https://resolver.cheqd.net' }),
+};
+
+await withKyaOs(server, {
+  crypto,
+  delegation: {
+    fetchProvider,
+    didResolvers,
+  },
+});
+```
+
+`did:cheqd` is resolved only when a resolver for the `cheqd` DID method is
+explicitly supplied. The core middleware and fetch provider use the generic
+`didResolvers` registry; cheqd-specific URL/cache/header options live in the
+`cheqdResolver()` factory from `@kya-os/mcp/cheqd`.
+`RuntimeFetchProvider` accepts the same registry when it is used directly by a
+standalone verifier or operator script.
+Unsupported methods, malformed DIDs, fetch failures, invalid JSON, malformed DID
+Documents, and DID id mismatches fail closed by returning `null`. The resolver
+accepts both raw DID Documents and Universal Resolver-style DID Resolution
+Results (`{ didDocument: ... }`).
+
+### Registrar writes
+
+Registrar writes are explicit operator/admin actions. The package exposes
+`CheqdDidRegistrarClient` for cheqd DID Registrar `/create`, `/update`, and
+`/{did}/create-resource` flows, using cheqd's client-managed-secret pattern:
+the registrar returns a serialized payload, your signer signs it, and the
+signature is submitted back. Private keys are not sent to the registrar.
+
+```typescript
+import {
+  CheqdDidRegistrarClient,
+  createLocalEd25519CheqdRegistrarSigner,
+} from '@kya-os/mcp/cheqd';
+import {
+  NodeCryptoProvider,
+} from '@kya-os/mcp';
+
+const crypto = new NodeCryptoProvider();
+const registrar = new CheqdDidRegistrarClient({
+  registrarUrl: 'https://did-registrar-staging.cheqd.net/1.0',
+  fetchProvider,
+  // Optional static or async auth headers for private registrar deployments.
+  // headers: async () => ({ Authorization: `Bearer ${token}` }),
+});
+
+const signer = createLocalEd25519CheqdRegistrarSigner({
+  cryptoProvider: crypto,
+  privateKey: process.env.CHEQD_DID_PRIVATE_KEY_BASE64!,
+  verificationMethodId: 'did:cheqd:testnet:...#key-1',
+  signatureEncoding: 'base64url',
+});
+```
+
+For mainnet, run or contract against your own fee-payer registrar deployment and
+provide the signer hook from your KMS/HSM boundary. The local Ed25519 helper is
+for simple controlled deployments and tests; it still signs locally and sends
+only signatures to the registrar.
+
+Runtime proof generation does not perform registrar writes. Create/update/DLR
+publishing should be triggered by an explicit operator workflow, deployment
+step, or admin tool.
+
+### DID linkage
+
+For `did:web` <-> `did:cheqd` binding, publish reciprocal `alsoKnownAs` values
+and verify both DID Documents with `verifyDidLinkage()`. `buildDidWebDocument`
+can include the `did:cheqd` reference on the `did:web` side, while
+`updateCheqdAlsoKnownAs()` updates the cheqd side through the registrar.
+
+```typescript
+import { verifyDidLinkage } from '@kya-os/mcp';
+import { updateCheqdAlsoKnownAs } from '@kya-os/mcp/cheqd';
+
+await updateCheqdAlsoKnownAs({
+  didWeb: 'did:web:agent.example.com',
+  didCheqd: 'did:cheqd:testnet:...',
+  resolver: cheqdResolver,
+  registrar,
+  signer,
+  verificationMethodId: 'did:cheqd:testnet:...#key-1',
+});
+
+const linkage = verifyDidLinkage({
+  primaryDid: 'did:web:agent.example.com',
+  secondaryDid: 'did:cheqd:testnet:...',
+  primaryDidDocument: didWebDocument,
+  secondaryDidDocument: didCheqdDocument,
+});
+```
+
+### DID-Linked Resource helpers
+
+DID-Linked Resource helpers are intended for durable manifests only. Supported
+artifact types are:
+
+- `CapabilityManifest`
+- `ConformanceManifest`
+- `AccessHashManifest`
+- `TrustConfigManifest`
+
+`prepareCheqdDlrResource()` validates the artifact, canonicalizes its `content`
+with JSON Canonicalization Scheme, computes or validates a `sha256:<64 hex>`
+content hash, and returns a registrar resource body. Updates are modeled as new
+resource versions under the same resource `name` and `type`; prior resources are
+not overwritten. Do not write high-volume tool calls, raw operational logs, or
+normal runtime proof events to cheqd; keep those in your normal audit/hash
+stores.
+
+```typescript
+import { prepareCheqdDlrResource } from '@kya-os/mcp/cheqd';
+
+const prepared = await prepareCheqdDlrResource({
+  type: 'TrustConfigManifest',
+  subjectDid: 'did:cheqd:testnet:...',
+  name: 'agent-trust-config',
+  resourceType: 'TrustConfigManifest',
+  version: '2026-06-01',
+  content: {
+    acceptedDidMethods: ['did:web', 'did:key', 'did:cheqd'],
+    requiredLinkage: { type: 'alsoKnownAs', bidirectional: true },
+  },
+}, crypto);
+
+await registrar.createResource({
+  did: 'did:cheqd:testnet:...',
+  resource: prepared.resource,
+  signer,
+  verificationMethodId: 'did:cheqd:testnet:...#key-1',
+});
+```
+
+See [examples/cheqd-dlr](./examples/cheqd-dlr/) for a complete operator flow.
+
+### Live cheqd registrar E2E tests
+
+Live registrar coverage is opt-in because it performs real writes to cheqd
+testnet. The default endpoint is the cheqd-published testnet staging registrar;
+override it only with another testnet registrar. The live test creates a testnet
+DID, adds a realistic `did:web` alias via `alsoKnownAs`, then publishes one
+resource for each supported KYA DLR artifact type.
+
+```powershell
+$env:KYA_OS_CHEQD_E2E = '1'
+npm run test:e2e:cheqd:testnet
+Remove-Item Env:\KYA_OS_CHEQD_E2E
+```
+
+Optional environment variables:
+
+| Variable | Default |
+| --- | --- |
+| `KYA_OS_CHEQD_TESTNET_REGISTRAR_URL` | `https://did-registrar-staging.cheqd.net/1.0` |
+| `KYA_OS_CHEQD_TESTNET_RESOLVER_URL` | `https://resolver.cheqd.net` |
+| `KYA_OS_CHEQD_E2E_TIMEOUT_MS` | `180000` |
+
+Out of scope for this package: replacing `did:web` as the canonical identity,
+writing runtime proof events on-chain, KYC/KYB issuance, reputation VC snapshot
+publication, status-list backend hosting, and external registry changes.
+
 ## Links
 
-- [Spec](./SPEC.md) | [Changelog](./CHANGELOG.md) | [DIF TAAWG](https://identity.foundation/working-groups/agent-and-authorization.html) | [npm](https://www.npmjs.com/package/@kya-os/mcp)
+- [Spec](./SPEC.md) | [Card Profile](./SPEC-ENTITY-CARD.md) | [Changelog](./CHANGELOG.md) | [DIF TAAWG](https://identity.foundation/working-groups/agent-and-authorization.html) | [npm](https://www.npmjs.com/package/@kya-os/mcp)
 - [CONTRIBUTING.md](./CONTRIBUTING.md) | [CONFORMANCE.md](./CONFORMANCE.md) | [SECURITY.md](./SECURITY.md) | [GOVERNANCE.md](./GOVERNANCE.md)
 
 ## License

package/dist/card/build.d.ts

@@ -0,0 +1,41 @@
+/**
+ * KYA-OS Entity Card — EMIT.
+ *
+ * `buildCard` projects this entity's identity + declared facts into a card. Pure,
+ * claim-minimal: it asserts only identity + type + declared capabilities (trust-bearing
+ * claims are proven by the referenced credentials, not minted here). `conformanceLevel`
+ * is intentionally omitted — it is a derived value a verifier recomputes.
+ */
+import type { Attestation, BitstringStatusListEntry, Capability, CimdBinding, Ed25519PublicJwk, EntityCard, EntityType, ProofProfile } from './schema.js';
+export interface BuildCardFacts {
+    entityType: EntityType;
+    name: string;
+    capabilities?: Capability[];
+    responsibleParty?: string;
+    principal?: string;
+    delegationRef?: string;
+    attestations?: Attestation[];
+    didDocument?: string;
+    /** Card's Ed25519 public JWK (for a card that inlines its verification key). */
+    publicKeyJwk?: Ed25519PublicJwk;
+    /** Names the per-request holder-of-key proof profile this entity's requests carry. */
+    proofProfile?: ProofProfile;
+    /** L1 CIMD on-ramp coordinates (client_id ⇄ did:web, jwks_uri ⇄ DID keys). */
+    cimd?: CimdBinding;
+    /** W3C Bitstring Status List revocation entry (the post-issuance kill switch). */
+    revocation?: BitstringStatusListEntry;
+}
+/** Minimal identity shape this helper needs (structurally compatible with `Identity`). */
+export interface CardIdentity {
+    did: string;
+    kid?: string;
+    createdAt?: string;
+}
+/**
+ * Build this entity's card from its identity + declared facts. Pure. Asserts only
+ * identity + type + declared capabilities (claim-minimalism — trust-bearing claims are
+ * proven by the referenced credentials, not minted here). `conformanceLevel` is
+ * intentionally omitted on emit: it is a derived value a verifier recomputes.
+ */
+export declare function buildCard(identity: CardIdentity, facts: BuildCardFacts): EntityCard;
+//# sourceMappingURL=build.d.ts.map

package/dist/card/build.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../src/card/build.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,wBAAwB,EACxB,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,UAAU,EACV,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,UAAU,EAAE,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gFAAgF;IAChF,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC,sFAAsF;IACtF,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,8EAA8E;IAC9E,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,kFAAkF;IAClF,UAAU,CAAC,EAAE,wBAAwB,CAAC;CACvC;AAED,0FAA0F;AAC1F,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,GAAG,UAAU,CAmBnF"}

package/dist/card/build.js

@@ -0,0 +1,47 @@
+/**
+ * KYA-OS Entity Card — EMIT.
+ *
+ * `buildCard` projects this entity's identity + declared facts into a card. Pure,
+ * claim-minimal: it asserts only identity + type + declared capabilities (trust-bearing
+ * claims are proven by the referenced credentials, not minted here). `conformanceLevel`
+ * is intentionally omitted — it is a derived value a verifier recomputes.
+ */
+/**
+ * Build this entity's card from its identity + declared facts. Pure. Asserts only
+ * identity + type + declared capabilities (claim-minimalism — trust-bearing claims are
+ * proven by the referenced credentials, not minted here). `conformanceLevel` is
+ * intentionally omitted on emit: it is a derived value a verifier recomputes.
+ */
+export function buildCard(identity, facts) {
+    const card = {
+        id: identity.did,
+        entityType: facts.entityType,
+        name: facts.name,
+    };
+    if (identity.kid !== undefined)
+        card.kid = identity.kid;
+    if (identity.createdAt !== undefined)
+        card.createdAt = identity.createdAt;
+    if (facts.capabilities !== undefined)
+        card.capabilities = facts.capabilities;
+    if (facts.responsibleParty !== undefined)
+        card.responsibleParty = facts.responsibleParty;
+    if (facts.principal !== undefined)
+        card.principal = facts.principal;
+    if (facts.delegationRef !== undefined)
+        card.delegationRef = facts.delegationRef;
+    if (facts.attestations !== undefined)
+        card.attestations = facts.attestations;
+    if (facts.didDocument !== undefined)
+        card.didDocument = facts.didDocument;
+    if (facts.publicKeyJwk !== undefined)
+        card.publicKeyJwk = facts.publicKeyJwk;
+    if (facts.proofProfile !== undefined)
+        card.proofProfile = facts.proofProfile;
+    if (facts.cimd !== undefined)
+        card.cimd = facts.cimd;
+    if (facts.revocation !== undefined)
+        card.revocation = facts.revocation;
+    return card;
+}
+//# sourceMappingURL=build.js.map

package/dist/card/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../src/card/build.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAuCH;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,QAAsB,EAAE,KAAqB;IACrE,MAAM,IAAI,GAAe;QACvB,EAAE,EAAE,QAAQ,CAAC,GAAG;QAChB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,IAAI,EAAE,KAAK,CAAC,IAAI;KACjB,CAAC;IACF,IAAI,QAAQ,CAAC,GAAG,KAAK,SAAS;QAAE,IAAI,CAAC,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC;IACxD,IAAI,QAAQ,CAAC,SAAS,KAAK,SAAS;QAAE,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC,SAAS,CAAC;IAC1E,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IAC7E,IAAI,KAAK,CAAC,gBAAgB,KAAK,SAAS;QAAE,IAAI,CAAC,gBAAgB,GAAG,KAAK,CAAC,gBAAgB,CAAC;IACzF,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC,SAAS,CAAC;IACpE,IAAI,KAAK,CAAC,aAAa,KAAK,SAAS;QAAE,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;IAChF,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IAC7E,IAAI,KAAK,CAAC,WAAW,KAAK,SAAS;QAAE,IAAI,CAAC,WAAW,GAAG,KAAK,CAAC,WAAW,CAAC;IAC1E,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IAC7E,IAAI,KAAK,CAAC,YAAY,KAAK,SAAS;QAAE,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IAC7E,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS;QAAE,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;IACrD,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS;QAAE,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IACvE,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/card/builder.d.ts

@@ -0,0 +1,99 @@
+/**
+ * KYA-OS Entity Card — fluent BUILDER (the 10-minute adoption path).
+ *
+ * `card({ did, entityType, name })` opens a fluent chain that accumulates declared facts and
+ * `.build()`s them into an `EntityCard` — a thin, ergonomic front over {@link buildCard} that
+ * hides the card shape behind readable, self-documenting calls:
+ *
+ *   card({ did, entityType: 'agent', name: 'Acme Pay' })
+ *     .capability('search')                              // L1 bare-string capability
+ *     .attestedCapability('payments.transfer', vc)       // L2 attested capability (VC-backed)
+ *     .accountableTo('did:web:acme.example', { via: 'vc_root>del_123' })
+ *     .build();
+ *
+ * Claim-minimal like `buildCard`: it asserts only identity + type + declared capabilities +
+ * accountability locators; trust-bearing claims are PROVEN by the referenced credentials, not
+ * minted here. The infrastructure coordinates it can ALSO carry — `.usesProof()` (proof profile),
+ * `.cimd()`, `.revocation()`, `.didDocument()`, `.publicKey()` — are self-descriptive pointers, not
+ * credential-proven claims, so the ergonomic path can emit a card that plugs into the proof / CIMD /
+ * revocation machinery. `conformanceLevel` is intentionally never set — a verifier RECOMPUTES it.
+ * Pure, no I/O, no crypto: no runtime (`mcp-i-core`) dependency leaks in.
+ */
+import type { Attestation, BitstringStatusListEntry, CapabilityAttestation, CimdBinding, Ed25519PublicJwk, EntityCard, EntityType } from './schema.js';
+/** A Verifiable Credential value (a compact VC-JWT string or a pre-parsed object). */
+export type VcInput = CapabilityAttestation['vc'];
+/** The identity + type coordinates a card chain opens with. */
+export interface CardBuilderInit {
+    did: string;
+    entityType: EntityType;
+    name: string;
+    kid?: string;
+    createdAt?: string;
+}
+/** Accountability locators for `accountableTo`: the delegation chain (`via`) + human `principal`. */
+export interface AccountableToOptions {
+    /** Compact delegation-chain locator (`delegationRef`, e.g. `vc_root>del_123`) — resolved, not inlined. */
+    via?: string;
+    /** The immediate human delegator DID (`principal`), when distinct from the responsible party. */
+    principal?: string;
+}
+/**
+ * A fluent accumulator over one card's declared facts. Mutable + chainable (each method returns
+ * `this`); `.build()` projects the accumulated facts through {@link buildCard}. Prefer the `card()`
+ * factory over `new CardBuilder(...)`.
+ */
+export declare class CardBuilder {
+    private readonly identity;
+    private readonly entityType;
+    private readonly name;
+    private readonly capabilities;
+    private readonly attestations;
+    private responsibleParty?;
+    private principal?;
+    private delegationRef?;
+    private proofProfile?;
+    private cimdBinding?;
+    private revocationEntry?;
+    private didDocumentUrl?;
+    private publicKeyJwk?;
+    constructor(init: CardBuilderInit);
+    /** Declare an L1 bare-string capability (self-asserted; a verifier floors it at L1). */
+    capability(name: string): this;
+    /**
+     * Declare an L2 capability backed by an attestation VC. Repeated calls for the SAME capability
+     * name accumulate onto its `attestations[]` (one capability, several proofs) rather than
+     * duplicating the entry.
+     */
+    attestedCapability(name: string, vc: VcInput): this;
+    /**
+     * Attach a standalone attestation (e.g. a KYC/KYB `IdentityVerification` VC on the responsible
+     * party) that is not tied to a single capability.
+     */
+    attestation(attestation: Attestation): this;
+    /**
+     * Declare the accountability edge: `responsibleParty` is the ultimately-accountable root (a
+     * KYC-able org), `opts.via` the compact `delegationRef` chain locator, and `opts.principal` the
+     * immediate human delegator. A verifier RECOMPUTES this edge (delegationRef → responsibleParty).
+     */
+    accountableTo(responsibleParty: string, opts?: AccountableToOptions): this;
+    /**
+     * Advertise the per-request holder-of-key proof profile (`org.kya-os/proof@1`). This only NAMES
+     * the profile — the proof itself is never on the static card; it rides per-request `_meta`.
+     */
+    usesProof(): this;
+    /** Bind the L1 CIMD on-ramp coordinates (`client_id` ⇄ `did:web`, `jwks_uri` ⇄ DID keys). */
+    cimd(binding: CimdBinding): this;
+    /** Attach the W3C Bitstring Status List revocation entry (the post-issuance kill switch). */
+    revocation(entry: BitstringStatusListEntry): this;
+    /** Record the entity's DID document URL (where the `KyaOsEntityCard` service entry lives). */
+    didDocument(url: string): this;
+    /** Inline the entity's Ed25519 public JWK (the card's self-contained verification key). */
+    publicKey(jwk: Ed25519PublicJwk): this;
+    /** Project the accumulated facts into an `EntityCard` (via {@link buildCard}). */
+    build(): EntityCard;
+    /** Find an already-declared attested capability by name (for attestation accumulation). */
+    private findAttested;
+}
+/** Open a fluent card-building chain (the ergonomic entry point). */
+export declare function card(init: CardBuilderInit): CardBuilder;
+//# sourceMappingURL=builder.d.ts.map

package/dist/card/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/card/builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EACV,WAAW,EACX,wBAAwB,EAExB,qBAAqB,EACrB,WAAW,EACX,gBAAgB,EAChB,UAAU,EACV,UAAU,EAGX,MAAM,aAAa,CAAC;AAKrB,sFAAsF;AACtF,MAAM,MAAM,OAAO,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;AAElD,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,UAAU,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,qGAAqG;AACrG,MAAM,WAAW,oBAAoB;IACnC,0GAA0G;IAC1G,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAoB;IACjD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,gBAAgB,CAAC,CAAS;IAClC,OAAO,CAAC,SAAS,CAAC,CAAS;IAC3B,OAAO,CAAC,aAAa,CAAC,CAAS;IAC/B,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,eAAe,CAAC,CAA2B;IACnD,OAAO,CAAC,cAAc,CAAC,CAAS;IAChC,OAAO,CAAC,YAAY,CAAC,CAAmB;gBAE5B,IAAI,EAAE,eAAe;IAQjC,wFAAwF;IACxF,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAK9B;;;;OAIG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,GAAG,IAAI;IAOnD;;;OAGG;IACH,WAAW,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAK3C;;;;OAIG;IACH,aAAa,CAAC,gBAAgB,EAAE,MAAM,EAAE,IAAI,GAAE,oBAAyB,GAAG,IAAI;IAO9E;;;OAGG;IACH,SAAS,IAAI,IAAI;IAKjB,6FAA6F;IAC7F,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAKhC,6FAA6F;IAC7F,UAAU,CAAC,KAAK,EAAE,wBAAwB,GAAG,IAAI;IAKjD,8FAA8F;IAC9F,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAK9B,2FAA2F;IAC3F,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI;IAKtC,kFAAkF;IAClF,KAAK,IAAI,UAAU;IAiBnB,2FAA2F;IAC3F,OAAO,CAAC,YAAY;CAKrB;AAED,qEAAqE;AACrE,wBAAgB,IAAI,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAEvD"}