@kya-os/mcp 1.6.1 → 1.9.0

package/dist/card/index.js

@@ -0,0 +1,46 @@
+/**
+ * KYA-OS Entity Card — v1.1 profile helpers
+ *
+ * Reference helpers for the typed, DID-anchored entity card. See
+ * `SPEC-ENTITY-CARD.md` and `schemas/kya-os-card.schema.json`. Three moves, each in a
+ * focused submodule re-exported here:
+ *   - buildCard   (./build):   EMIT this entity's card from its identity + declared facts.
+ *   - emit        (./emit):    PROJECT the card onto every discovery rail (DID service entry,
+ *                              MCP `_meta`, catalog, A2A extension, NANDA AgentFacts).
+ *   - resolveCard (./resolve): DISCOVER another entity's card (multi-surface, via SafeFetch).
+ *   - verifyCard  (./verify):  VERIFY the card's claims — RECOMPUTING the conformance
+ *                              level rather than trusting whatever the card declares.
+ *   - cimd        (./cimd):    BIND the L1 CIMD on-ramp — `client_id` ⇄ `did:web`, DID-keyed
+ *                              JWKS, and the fail-closed origin/`alsoKnownAs` substitution graft.
+ *   - proof       (./proof):   MINT + VERIFY the stateless per-request holder-of-key proof
+ *                              (`org.kya-os/proof@1`) — sender-constrained, fail-closed.
+ *   - delegation  (./delegation): VALIDATE the W3C VC 2.0 + ZCAP-LD delegation chain — CRISP
+ *                              attenuation + continuity, `responsibleParty`/leaf-invoker, fail-closed.
+ *   - builder     (./builder):  the fluent `card()` chain — the 10-minute path to a valid card.
+ *   - middleware  (./middleware): `withKyaOsCard` (mount the discovery artifacts) + `requireProof`
+ *                              (the per-request holder-of-key guard, 401-shaped on fail).
+ *
+ * All cryptographic verification is injected via pluggable seams (the same pattern
+ * `validateLevel2` already uses for its `signatureVerifier`), so `@kya-os/mcp` stays
+ * free of any runtime (mcp-i-core) dependency. The conformance LEVEL is derived in
+ * `./verify`, never baked into a function name.
+ *
+ * The card shape is defined once as a zod schema in `./schema` (mirroring the
+ * published `schemas/kya-os-card.schema.json`); types are `z.infer`-derived.
+ */
+export * from './schema.js';
+export * from './build.js';
+export * from './emit.js';
+export * from './resolve.js';
+export * from './verify.js';
+export * from './cimd.js';
+export * from './proof/index.js';
+export * from './delegation.js';
+export * from './builder.js';
+export * from './middleware.js';
+export * from './revocation.js';
+// The SSRF-hardened fetch is the card's production wiring for resolveCard / status-list
+// resolution — export it (and the address classifier) so consumers can actually reach it,
+// not just the mocked-transport unit tests.
+export { createSafeFetch, fetchTransport, isBlockedAddress, } from '../utils/safe-fetch.js';
+//# sourceMappingURL=index.js.map

package/dist/card/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/card/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAEhC,wFAAwF;AACxF,0FAA0F;AAC1F,4CAA4C;AAC5C,OAAO,EACL,eAAe,EACf,cAAc,EACd,gBAAgB,GAQjB,MAAM,wBAAwB,CAAC"}

package/dist/card/middleware.d.ts

@@ -0,0 +1,112 @@
+/**
+ * KYA-OS Entity Card — DevX middleware (the 10-minute adoption path).
+ *
+ * Two ergonomic wrappers hide the RFC 9421 / 9449 / 8785 machinery behind one call each:
+ *
+ *   - `withKyaOsCard(card)` — the EMIT side. Bundles the three artifacts a server must publish
+ *     (the `card.json` body, the `KyaOsEntityCard` DID-document service entry, and the
+ *     `server.json` `_meta['org.kya-os/card']` fragment) and MOUNTS them onto existing objects —
+ *     merging the `_meta` into a server.json and appending the service entry to a DID document,
+ *     both immutably (a shallow clone; a stripped `_meta` degrades to a fetch, never a failure).
+ *
+ *   - `requireProof(deps, { minLevel? })` — the VERIFY side. Returns a per-request guard that
+ *     reads the holder-of-key proof from `_meta['org.kya-os/proof@1']`, RECOMPUTES it via
+ *     `./proof` ({@link verifyCardProof}) — every binding, fail-closed — enforces a minimum
+ *     assurance, and returns a 401-shaped result on any failure. The caller passes the exact
+ *     `{ method, params }` the client signed (i.e. WITHOUT `_meta`), so the recomputed
+ *     `requestHash` matches.
+ *
+ * Pure composition over the shipped engine — no new crypto, no runtime (`mcp-i-core`) dependency.
+ */
+import type { ToolRequest } from '../proof/generator.js';
+import { type DidServiceEntry, type ServerCardMeta } from './emit.js';
+import { type ProofAssurance, type VerifyProofDeps } from './proof/index.js';
+import type { EntityCard } from './schema.js';
+/** A structurally-typed MCP `server.json` (open shape; only `_meta` is read/merged). */
+export interface ServerJsonLike {
+    _meta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** A structurally-typed DID document (open shape; only `service[]` is read/appended). */
+export interface DidDocumentLike {
+    service?: unknown[];
+    [key: string]: unknown;
+}
+/** The three publishable artifacts of a card + immutable mounters for a server.json / DID doc. */
+export interface KyaOsCardMount {
+    /** Serve this at the entity's `card.json` endpoint (the canonical source of truth). */
+    cardJson: EntityCard;
+    /**
+     * Add this to the entity's `did:web` DID-document `service[]` (the card's canonical home).
+     * `undefined` for a `did:key` card, which has no HTTPS card endpoint — publish `serverMeta` instead.
+     */
+    didServiceEntry?: DidServiceEntry;
+    /** Merge this into an MCP `server.json` / catalog `_meta`. */
+    serverMeta: ServerCardMeta;
+    /** Return a shallow clone of `serverJson` with the card `_meta` merged in (other keys preserved). */
+    mountServerJson<T extends ServerJsonLike>(serverJson: T): T & {
+        _meta: Record<string, unknown>;
+    };
+    /** Return a shallow clone of `didDoc` with the `KyaOsEntityCard` service entry appended (dedup by id). */
+    mountDidDocument<T extends DidDocumentLike>(didDoc: T): T & {
+        service: unknown[];
+    };
+}
+/**
+ * Bundle a card into its three discovery artifacts and hand back immutable mounters. `opts.byRef`
+ * projects the `_meta` as a lazy-fetch `cardRef` instead of an inline summary. NOTE: the DID
+ * service entry (and a by-ref `_meta`) require a path-form `did:web` — a `did:key` dev card has no
+ * HTTPS card endpoint and this fails closed (see `didWebToCardUrl`).
+ */
+export declare function withKyaOsCard(card: EntityCard, opts?: {
+    byRef?: boolean;
+}): KyaOsCardMount;
+/** A minimum proof assurance the guard enforces. Default: any valid proof (`L3-minus`) passes. */
+export type MinProofLevel = ProofAssurance;
+/** A snake_case rejection code (aligned to the `./proof` reason vocabulary). */
+export type ProofGateCode = 'proof_missing' | 'proof_invalid' | 'proof_level_insufficient';
+/** A 401-shaped rejection: a stable `code`, a human message, and the raw recompute `reasons`. */
+export interface ProofGateError {
+    code: ProofGateCode;
+    message: string;
+    reasons: string[];
+}
+/** The guard verdict: a pass carries the accountable principal + assurance; a fail is 401-shaped. */
+export type ProofGateResult = {
+    ok: true;
+    did: string;
+    level: ProofAssurance;
+    warnings?: string[];
+} | {
+    ok: false;
+    status: 401;
+    error: ProofGateError;
+};
+/**
+ * A per-request holder-of-key guard. Pass the exact request the client SIGNED (`{ method, params }`
+ * without `_meta`) and the `_meta` bag that carried the proof; the guard recomputes every binding.
+ */
+export type ProofGuard = (req: ToolRequest, meta: unknown) => Promise<ProofGateResult>;
+/** Options for {@link requireProof}. */
+export interface RequireProofOptions {
+    /** Minimum assurance a valid proof must carry (`L3` requires the AS `cnf` fusion). */
+    minLevel?: MinProofLevel;
+}
+/**
+ * Build a per-request holder-of-key guard from the pre-bound proof-verification seams. The returned
+ * guard reads `_meta['org.kya-os/proof@1']`, RECOMPUTES it against the request via {@link verifyCardProof},
+ * enforces `opts.minLevel`, and returns `{ ok: true, did, level }` or a 401-shaped rejection. Fail-closed
+ * throughout: a missing proof, a broken binding, a throwing verifier, or an assurance below `minLevel`
+ * all reject.
+ *
+ * REPLAY DEFENSE (do NOT skip): `deps.consumeNonceIfFresh` MUST be an ATOMIC test-AND-set — it
+ * records the nonce and returns `false` on a replay (SPEC §12.2). A pure read that never persists
+ * the nonce is a replay hole. Wire the batteries-included `InMemoryNonceCache` (single-process,
+ * race-free) or `consumeFromNonceCacheProvider` (shared store); with neither seam supplied every
+ * request FAILS CLOSED (`nonce_seam_missing`).
+ */
+export declare function requireProof(deps: VerifyProofDeps, opts?: RequireProofOptions): ProofGuard;
+/** Read the card proof (`org.kya-os/proof@1`) out of a `_meta` record (undefined when absent / not an
+ *  object). A legacy session proof under `org.kya-os/proof` is a different key and is simply not seen. */
+export declare function readCardProof(meta: unknown): unknown;
+//# sourceMappingURL=middleware.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/card/middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAGL,KAAK,cAAc,EAEnB,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI9C,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,yFAAyF;AACzF,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,kGAAkG;AAClG,MAAM,WAAW,cAAc;IAC7B,uFAAuF;IACvF,QAAQ,EAAE,UAAU,CAAC;IACrB;;;OAGG;IACH,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,8DAA8D;IAC9D,UAAU,EAAE,cAAc,CAAC;IAC3B,qGAAqG;IACrG,eAAe,CAAC,CAAC,SAAS,cAAc,EAAE,UAAU,EAAE,CAAC,GAAG,CAAC,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IACjG,0GAA0G;IAC1G,gBAAgB,CAAC,CAAC,SAAS,eAAe,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG;QAAE,OAAO,EAAE,OAAO,EAAE,CAAA;KAAE,CAAC;CACpF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,cAAc,CA4B9F;AAsBD,kGAAkG;AAClG,MAAM,MAAM,aAAa,GAAG,cAAc,CAAC;AAE3C,gFAAgF;AAChF,MAAM,MAAM,aAAa,GAAG,eAAe,GAAG,eAAe,GAAG,0BAA0B,CAAC;AAE3F,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,qGAAqG;AACrG,MAAM,MAAM,eAAe,GACvB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,cAAc,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,GACrE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,GAAG,CAAC;IAAC,KAAK,EAAE,cAAc,CAAA;CAAE,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAEvF,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,sFAAsF;IACtF,QAAQ,CAAC,EAAE,aAAa,CAAC;CAC1B;AAKD;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,eAAe,EAAE,IAAI,GAAE,mBAAwB,GAAG,UAAU,CAsB9F;AAED;0GAC0G;AAC1G,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAEpD"}

package/dist/card/middleware.js

@@ -0,0 +1,121 @@
+/**
+ * KYA-OS Entity Card — DevX middleware (the 10-minute adoption path).
+ *
+ * Two ergonomic wrappers hide the RFC 9421 / 9449 / 8785 machinery behind one call each:
+ *
+ *   - `withKyaOsCard(card)` — the EMIT side. Bundles the three artifacts a server must publish
+ *     (the `card.json` body, the `KyaOsEntityCard` DID-document service entry, and the
+ *     `server.json` `_meta['org.kya-os/card']` fragment) and MOUNTS them onto existing objects —
+ *     merging the `_meta` into a server.json and appending the service entry to a DID document,
+ *     both immutably (a shallow clone; a stripped `_meta` degrades to a fetch, never a failure).
+ *
+ *   - `requireProof(deps, { minLevel? })` — the VERIFY side. Returns a per-request guard that
+ *     reads the holder-of-key proof from `_meta['org.kya-os/proof@1']`, RECOMPUTES it via
+ *     `./proof` ({@link verifyCardProof}) — every binding, fail-closed — enforces a minimum
+ *     assurance, and returns a 401-shaped result on any failure. The caller passes the exact
+ *     `{ method, params }` the client signed (i.e. WITHOUT `_meta`), so the recomputed
+ *     `requestHash` matches.
+ *
+ * Pure composition over the shipped engine — no new crypto, no runtime (`mcp-i-core`) dependency.
+ */
+import { isRecord } from '../utils/guards.js';
+import { toDidServiceEntry, toServerCardMeta, } from './emit.js';
+import { verifyCardProof, KYA_OS_CARD_PROOF_META_KEY, } from './proof/index.js';
+/**
+ * Bundle a card into its three discovery artifacts and hand back immutable mounters. `opts.byRef`
+ * projects the `_meta` as a lazy-fetch `cardRef` instead of an inline summary. NOTE: the DID
+ * service entry (and a by-ref `_meta`) require a path-form `did:web` — a `did:key` dev card has no
+ * HTTPS card endpoint and this fails closed (see `didWebToCardUrl`).
+ */
+export function withKyaOsCard(card, opts = {}) {
+    const isDidWeb = card.id.startsWith('did:web:');
+    if (opts.byRef && !isDidWeb) {
+        throw new Error(`withKyaOsCard: { byRef } needs an HTTPS card URL that only a did:web card has (got "${card.id}"); ` +
+            'use the default inline summary for a did:key card');
+    }
+    // The DID-document service entry anchors the card at an HTTPS endpoint — only a did:web card has
+    // one. A did:key dev card still projects an inline `serverMeta`; it just has no web service entry,
+    // so building one is skipped rather than thrown (the caller may only want `mountServerJson`).
+    const didServiceEntry = isDidWeb ? toDidServiceEntry(card) : undefined;
+    const serverMeta = toServerCardMeta(card, opts);
+    return {
+        cardJson: card,
+        didServiceEntry,
+        serverMeta,
+        mountServerJson: (serverJson) => mergeServerMeta(serverJson, serverMeta),
+        mountDidDocument: (didDoc) => {
+            if (!didServiceEntry) {
+                throw new Error(`withKyaOsCard: card "${card.id}" is not a did:web card, so it has no DID-document service ` +
+                    'entry to mount — publish its inline serverMeta with mountServerJson instead');
+            }
+            return appendService(didDoc, didServiceEntry);
+        },
+    };
+}
+/** Merge the card `_meta` fragment into a server.json `_meta` (shallow clone; card key wins). */
+function mergeServerMeta(serverJson, meta) {
+    return { ...serverJson, _meta: { ...(serverJson._meta ?? {}), ...meta } };
+}
+/** Append the `KyaOsEntityCard` service entry to a DID document's `service[]` (dedup by id, clone). */
+function appendService(didDoc, entry) {
+    const existing = Array.isArray(didDoc.service) ? didDoc.service : [];
+    const deduped = existing.filter((s) => !(isRecord(s) && s.id === entry.id));
+    return { ...didDoc, service: [...deduped, entry] };
+}
+/** Assurance ordering for the `minLevel` gate (`L3-minus` is the floor, `L3` the ceiling). */
+const ASSURANCE_RANK = { 'L3-minus': 1, L3: 2 };
+/**
+ * Build a per-request holder-of-key guard from the pre-bound proof-verification seams. The returned
+ * guard reads `_meta['org.kya-os/proof@1']`, RECOMPUTES it against the request via {@link verifyCardProof},
+ * enforces `opts.minLevel`, and returns `{ ok: true, did, level }` or a 401-shaped rejection. Fail-closed
+ * throughout: a missing proof, a broken binding, a throwing verifier, or an assurance below `minLevel`
+ * all reject.
+ *
+ * REPLAY DEFENSE (do NOT skip): `deps.consumeNonceIfFresh` MUST be an ATOMIC test-AND-set — it
+ * records the nonce and returns `false` on a replay (SPEC §12.2). A pure read that never persists
+ * the nonce is a replay hole. Wire the batteries-included `InMemoryNonceCache` (single-process,
+ * race-free) or `consumeFromNonceCacheProvider` (shared store); with neither seam supplied every
+ * request FAILS CLOSED (`nonce_seam_missing`).
+ */
+export function requireProof(deps, opts = {}) {
+    return async (req, meta) => {
+        const proof = readCardProof(meta);
+        if (proof === undefined) {
+            return fail('proof_missing', 'no org.kya-os/proof@1 in _meta', ['proof_missing']);
+        }
+        const result = await recompute(proof, req, deps);
+        if (!result.ok || result.did === undefined || result.level === undefined) {
+            return fail('proof_invalid', 'holder-of-key proof did not verify', result.reasons);
+        }
+        const level = result.level;
+        if (opts.minLevel && ASSURANCE_RANK[level] < ASSURANCE_RANK[opts.minLevel]) {
+            const message = `proof assurance ${level} is below the required ${opts.minLevel}`;
+            return fail('proof_level_insufficient', message, ['proof_level_insufficient']);
+        }
+        return {
+            ok: true,
+            did: result.did,
+            level,
+            ...(result.warnings ? { warnings: result.warnings } : {}),
+        };
+    };
+}
+/** Read the card proof (`org.kya-os/proof@1`) out of a `_meta` record (undefined when absent / not an
+ *  object). A legacy session proof under `org.kya-os/proof` is a different key and is simply not seen. */
+export function readCardProof(meta) {
+    return isRecord(meta) ? meta[KYA_OS_CARD_PROOF_META_KEY] : undefined;
+}
+/** Recompute the proof, fail-closed: a throwing verifier demotes to a rejected result (never escapes). */
+async function recompute(proof, req, deps) {
+    try {
+        return await verifyCardProof(proof, req, deps);
+    }
+    catch {
+        return { ok: false, reasons: ['proof_verifier_threw'] };
+    }
+}
+/** A 401-shaped rejection. */
+function fail(code, message, reasons) {
+    return { ok: false, status: 401, error: { code, message, reasons } };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/card/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/card/middleware.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,22 @@
+/**
+ * KYA-OS Entity Card proof — MINT (`buildCardProof`).
+ *
+ * Mint a stateless, sender-constrained `org.kya-os/proof@1` for one request and return it under the
+ * card proof's OWN `_meta` key ({@link KYA_OS_CARD_PROOF_META_KEY} = `org.kya-os/proof@1`), distinct
+ * from the legacy session proof's `org.kya-os/proof` so the two coexist. The proof binds:
+ * `requestHash` → THIS body (JCS), `audience` → THIS recipient, `nonce` + `created`/`expires` → NOW,
+ * `kid` → the signing DID key, and (optionally) `cnf.jkt` → the token's RFC 9449 sender-constraint.
+ * Crypto is entirely inside the injected {@link ProofSigner}.
+ */
+import type { ToolRequest } from '../../proof/generator.js';
+import { KYA_OS_CARD_PROOF_META_KEY, type BuildProofContext, type CardProofMeta, type ProofSigner } from './types.js';
+/**
+ * Mint an `org.kya-os/proof@1` for `req`, signed by `signer`, bound to `ctx`. Returns the proof
+ * keyed by {@link KYA_OS_CARD_PROOF_META_KEY} so it can be spread straight into an MCP request
+ * `_meta`. The `cnf.jkt` is `ctx.cnfJkt` when given, else the signer's own key thumbprint, else
+ * omitted (an L3-minus proof — still bound by request + audience + nonce + key).
+ */
+export declare function buildCardProof(req: ToolRequest, signer: ProofSigner, ctx: BuildProofContext): Promise<{
+    [KYA_OS_CARD_PROOF_META_KEY]: CardProofMeta;
+}>;
+//# sourceMappingURL=build.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"build.d.ts","sourceRoot":"","sources":["../../../src/card/proof/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAG5D,OAAO,EAEL,0BAA0B,EAG1B,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,WAAW,EAChB,MAAM,EAAE,WAAW,EACnB,GAAG,EAAE,iBAAiB,GACrB,OAAO,CAAC;IAAE,CAAC,0BAA0B,CAAC,EAAE,aAAa,CAAA;CAAE,CAAC,CAoC1D"}

package/dist/card/proof/build.js

@@ -0,0 +1,55 @@
+/**
+ * KYA-OS Entity Card proof — MINT (`buildCardProof`).
+ *
+ * Mint a stateless, sender-constrained `org.kya-os/proof@1` for one request and return it under the
+ * card proof's OWN `_meta` key ({@link KYA_OS_CARD_PROOF_META_KEY} = `org.kya-os/proof@1`), distinct
+ * from the legacy session proof's `org.kya-os/proof` so the two coexist. The proof binds:
+ * `requestHash` → THIS body (JCS), `audience` → THIS recipient, `nonce` + `created`/`expires` → NOW,
+ * `kid` → the signing DID key, and (optionally) `cnf.jkt` → the token's RFC 9449 sender-constraint.
+ * Crypto is entirely inside the injected {@link ProofSigner}.
+ */
+import { canonicalPayloadBytes, computeRequestHash } from './canonical.js';
+import { httpSignatureBaseBytes } from './http-sig.js';
+import { DEFAULT_TTL_SEC, KYA_OS_CARD_PROOF_META_KEY, MAX_TTL_SEC, PROOF_PROFILE_V1, } from './types.js';
+/**
+ * Mint an `org.kya-os/proof@1` for `req`, signed by `signer`, bound to `ctx`. Returns the proof
+ * keyed by {@link KYA_OS_CARD_PROOF_META_KEY} so it can be spread straight into an MCP request
+ * `_meta`. The `cnf.jkt` is `ctx.cnfJkt` when given, else the signer's own key thumbprint, else
+ * omitted (an L3-minus proof — still bound by request + audience + nonce + key).
+ */
+export async function buildCardProof(req, signer, ctx) {
+    const created = Math.floor((ctx.now?.() ?? Date.now()) / 1000);
+    const ttlSec = ctx.ttlSec ?? DEFAULT_TTL_SEC;
+    // Fail FAST at mint: a proof longer than the profile cap is guaranteed to be rejected by the
+    // verifier (ttl_too_long), so surface the caller's error here rather than emit a doomed proof.
+    // The verifier remains the authoritative enforcer; both reference the one shared MAX_TTL_SEC.
+    if (ttlSec > MAX_TTL_SEC) {
+        throw new Error(`buildCardProof: ttlSec ${ttlSec} exceeds the profile cap of ${MAX_TTL_SEC}s — mint a shorter-lived proof`);
+    }
+    const expires = created + ttlSec;
+    const requestHash = await computeRequestHash(req);
+    const jkt = ctx.cnfJkt ?? signer.jkt;
+    const unsigned = {
+        prf: PROOF_PROFILE_V1,
+        alg: signer.alg ?? 'EdDSA',
+        did: signer.did,
+        kid: signer.kid,
+        audience: ctx.audience,
+        nonce: ctx.nonce,
+        created,
+        expires,
+        requestHash,
+        ...(jkt !== undefined ? { cnf: { jkt } } : {}),
+        jws: '',
+    };
+    const jws = await signer.sign(canonicalPayloadBytes(unsigned));
+    const signed = { ...unsigned, jws };
+    // Dual carrier: when the signer exposes a raw-signature seam, ALSO sign the RFC 9421 base so the
+    // HTTP Message Signature sibling is genuinely cross-verifiable against the DID key. Absent it,
+    // the proof ships JWS-only and the sibling degrades away (never a failure).
+    if (!signer.signRaw)
+        return { [KYA_OS_CARD_PROOF_META_KEY]: signed };
+    const httpSig = await signer.signRaw(httpSignatureBaseBytes(signed));
+    return { [KYA_OS_CARD_PROOF_META_KEY]: { ...signed, httpSig } };
+}
+//# sourceMappingURL=build.js.map

package/dist/card/proof/build.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build.js","sourceRoot":"","sources":["../../../src/card/proof/build.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,EACL,eAAe,EACf,0BAA0B,EAC1B,WAAW,EACX,gBAAgB,GAIjB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAgB,EAChB,MAAmB,EACnB,GAAsB;IAEtB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,eAAe,CAAC;IAC7C,6FAA6F;IAC7F,+FAA+F;IAC/F,8FAA8F;IAC9F,IAAI,MAAM,GAAG,WAAW,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,0BAA0B,MAAM,+BAA+B,WAAW,gCAAgC,CAAC,CAAC;IAC9H,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,CAAC;IACjC,MAAM,WAAW,GAAG,MAAM,kBAAkB,CAAC,GAAG,CAAC,CAAC;IAClD,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,IAAI,MAAM,CAAC,GAAG,CAAC;IAErC,MAAM,QAAQ,GAAkB;QAC9B,GAAG,EAAE,gBAAgB;QACrB,GAAG,EAAE,MAAM,CAAC,GAAG,IAAI,OAAO;QAC1B,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,GAAG,EAAE,MAAM,CAAC,GAAG;QACf,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO;QACP,OAAO;QACP,WAAW;QACX,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9C,GAAG,EAAE,EAAE;KACR,CAAC;IAEF,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAkB,EAAE,GAAG,QAAQ,EAAE,GAAG,EAAE,CAAC;IAEnD,iGAAiG;IACjG,+FAA+F;IAC/F,4EAA4E;IAC5E,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC,0BAA0B,CAAC,EAAE,MAAM,EAAE,CAAC;IACrE,MAAM,OAAO,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,sBAAsB,CAAC,MAAM,CAAC,CAAC,CAAC;IACrE,OAAO,EAAE,CAAC,0BAA0B,CAAC,EAAE,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,EAAE,CAAC;AAClE,CAAC"}

package/dist/card/proof/canonical.d.ts

@@ -0,0 +1,66 @@
+/**
+ * KYA-OS Entity Card proof — canonicalization + hashing (the single source of truth).
+ *
+ * Both the minter ({@link buildCardProof}) and the verifier ({@link verifyCardProof}) derive
+ * their signing input from HERE, so the two can never drift. Reuses `json-canonicalize` (RFC
+ * 8785 / JCS) — the same canonicalizer `src/proof/generator.ts` uses — and the same
+ * `{ method, params }` request shape, so the `requestHash` is cross-implementation stable.
+ *
+ * `requestHash` is emitted in the RFC 9421 Content-Digest structured-field form
+ * (`sha-256=:<base64>:`) so the HTTP Message Signature sibling can carry it verbatim.
+ */
+import type { ToolRequest } from '../../proof/generator.js';
+import type { CardProofMeta } from './types.js';
+/** A signing JWK (Ed25519 OKP or P-256 EC; public, or private with `d`) — typed locally to avoid a
+ *  DOM lib dependency. `y` is present only for EC (P-256) keys. */
+export interface RawSigningJwk {
+    kty: string;
+    crv: string;
+    x: string;
+    y?: string;
+    d?: string;
+}
+/** SHA-256 over `bytes`. */
+export declare function sha256(bytes: Uint8Array): Promise<Uint8Array>;
+/**
+ * A RAW EdDSA signature (NOT JWS-framed) over `data` with an Ed25519 private JWK. This is the
+ * signature a stock RFC 9421 verifier expects over the signature base — distinct from the detached
+ * JWS, whose signature also covers the protected header and so can never satisfy a 9421 verifier.
+ */
+export declare function ed25519SignRaw(privateJwk: RawSigningJwk, data: Uint8Array): Promise<Uint8Array>;
+/** Verify a RAW EdDSA signature over `data` against an Ed25519 public JWK. Fail-closed on error. */
+export declare function ed25519VerifyRaw(publicJwk: RawSigningJwk, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+/**
+ * A RAW ES256 signature (ECDSA P-256 over SHA-256, `r||s` — NOT DER, NOT JWS-framed) over `data`
+ * with a P-256 private JWK. This is the RFC 9421 `ecdsa-p256-sha256` form a stock 9421 verifier
+ * reconstructs over the signature base — the FIPS-eligible sibling to {@link ed25519SignRaw}.
+ */
+export declare function es256SignRaw(privateJwk: RawSigningJwk, data: Uint8Array): Promise<Uint8Array>;
+/** Verify a RAW ES256 signature over `data` against a P-256 public JWK. Fail-closed on error. */
+export declare function es256VerifyRaw(publicJwk: RawSigningJwk, signature: Uint8Array, data: Uint8Array): Promise<boolean>;
+/**
+ * Bind a request to its `requestHash`: SHA-256 over `JCS({ method, params })`, emitted as the RFC
+ * 9421 Content-Digest structured field `sha-256=:<base64>:` (chosen so the HTTP Message Signature
+ * sibling can carry it verbatim, §8.3/§8.5).
+ *
+ * INPUT-SHAPE parity, OUTPUT-FORMAT difference: the JCS input mirrors the legacy hasher's
+ * `{ method, params }` shape, so the underlying digest BYTES are identical — but the legacy hasher
+ * ({@link computeCanonicalHashes}) emits `sha256:<hex>`, so the two STRINGS never compare equal.
+ * A card proof is verified ONLY by the card verifier (which recomputes this exact form); do not
+ * string-compare it against a legacy `sha256:<hex>` value — use {@link digestsEqual} to compare the
+ * underlying digests across formats.
+ */
+export declare function computeRequestHash(req: ToolRequest): Promise<string>;
+/**
+ * True iff two request-hash strings carry the SAME SHA-256 digest, accepting EITHER the card's RFC
+ * 9421 `sha-256=:<base64>:` form or the legacy `sha256:<hex>` form. The two forms are never
+ * string-equal for the same digest, so cross-format integrators MUST compare with this, not `===`.
+ */
+export declare function digestsEqual(a: string, b: string): boolean;
+/** The COVERED claims (every proof field except `jws`) — the object the JWS actually signs. */
+export declare function coveredClaims(meta: CardProofMeta): Record<string, unknown>;
+/** The JCS canonical bytes of the covered claims — the exact detached-JWS signing payload. */
+export declare function canonicalPayloadBytes(meta: CardProofMeta): Uint8Array;
+/** Re-encode a base64url value (a JWS signature) as standard base64 (an RFC 9421 byte sequence). */
+export declare function base64urlToBase64(b64url: string): string;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/card/proof/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../../src/card/proof/canonical.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD;mEACmE;AACnE,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,CAAC,CAAC,EAAE,MAAM,CAAC;CACZ;AAmCD,4BAA4B;AAC5B,wBAAsB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAEnE;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAIrG;AAED,oGAAoG;AACpG,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,UAAU,EACrB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,OAAO,CAAC,CAQlB;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAInG;AAED,iGAAiG;AACjG,wBAAsB,cAAc,CAClC,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,UAAU,EACrB,IAAI,EAAE,UAAU,GACf,OAAO,CAAC,OAAO,CAAC,CAclB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAM1E;AAaD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAa1E;AAED,8FAA8F;AAC9F,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAErE;AAED,oGAAoG;AACpG,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAExD"}

package/dist/card/proof/canonical.js

@@ -0,0 +1,131 @@
+/**
+ * KYA-OS Entity Card proof — canonicalization + hashing (the single source of truth).
+ *
+ * Both the minter ({@link buildCardProof}) and the verifier ({@link verifyCardProof}) derive
+ * their signing input from HERE, so the two can never drift. Reuses `json-canonicalize` (RFC
+ * 8785 / JCS) — the same canonicalizer `src/proof/generator.ts` uses — and the same
+ * `{ method, params }` request shape, so the `requestHash` is cross-implementation stable.
+ *
+ * `requestHash` is emitted in the RFC 9421 Content-Digest structured-field form
+ * (`sha-256=:<base64>:`) so the HTTP Message Signature sibling can carry it verbatim.
+ */
+import { canonicalize } from 'json-canonicalize';
+import { base64ToBytes, base64urlDecodeToBytes, bytesToBase64 } from '../../utils/base64.js';
+const encoder = new TextEncoder();
+const ED25519 = { name: 'Ed25519' };
+const ES256_IMPORT = { name: 'ECDSA', namedCurve: 'P-256' };
+const ES256_SIGN = { name: 'ECDSA', hash: 'SHA-256' };
+/** The WebCrypto subtle (Node ≥ 20 / Workers via `globalThis.crypto`), fail-closed when absent. */
+function subtle() {
+    const c = globalThis.crypto;
+    if (!c?.subtle)
+        throw new Error('card/proof: WebCrypto SubtleCrypto is unavailable');
+    return c.subtle;
+}
+/** SHA-256 over `bytes`. */
+export async function sha256(bytes) {
+    return new Uint8Array(await subtle().digest('SHA-256', bytes));
+}
+/**
+ * A RAW EdDSA signature (NOT JWS-framed) over `data` with an Ed25519 private JWK. This is the
+ * signature a stock RFC 9421 verifier expects over the signature base — distinct from the detached
+ * JWS, whose signature also covers the protected header and so can never satisfy a 9421 verifier.
+ */
+export async function ed25519SignRaw(privateJwk, data) {
+    const s = subtle();
+    const key = await s.importKey('jwk', privateJwk, ED25519, false, ['sign']);
+    return new Uint8Array(await s.sign(ED25519, key, data));
+}
+/** Verify a RAW EdDSA signature over `data` against an Ed25519 public JWK. Fail-closed on error. */
+export async function ed25519VerifyRaw(publicJwk, signature, data) {
+    try {
+        const s = subtle();
+        const key = await s.importKey('jwk', { kty: publicJwk.kty, crv: publicJwk.crv, x: publicJwk.x }, ED25519, false, ['verify']);
+        return await s.verify(ED25519, key, signature, data);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * A RAW ES256 signature (ECDSA P-256 over SHA-256, `r||s` — NOT DER, NOT JWS-framed) over `data`
+ * with a P-256 private JWK. This is the RFC 9421 `ecdsa-p256-sha256` form a stock 9421 verifier
+ * reconstructs over the signature base — the FIPS-eligible sibling to {@link ed25519SignRaw}.
+ */
+export async function es256SignRaw(privateJwk, data) {
+    const s = subtle();
+    const key = await s.importKey('jwk', privateJwk, ES256_IMPORT, false, ['sign']);
+    return new Uint8Array(await s.sign(ES256_SIGN, key, data));
+}
+/** Verify a RAW ES256 signature over `data` against a P-256 public JWK. Fail-closed on error. */
+export async function es256VerifyRaw(publicJwk, signature, data) {
+    try {
+        const s = subtle();
+        const key = await s.importKey('jwk', { kty: publicJwk.kty, crv: publicJwk.crv, x: publicJwk.x, y: publicJwk.y }, ES256_IMPORT, false, ['verify']);
+        return await s.verify(ES256_SIGN, key, signature, data);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Bind a request to its `requestHash`: SHA-256 over `JCS({ method, params })`, emitted as the RFC
+ * 9421 Content-Digest structured field `sha-256=:<base64>:` (chosen so the HTTP Message Signature
+ * sibling can carry it verbatim, §8.3/§8.5).
+ *
+ * INPUT-SHAPE parity, OUTPUT-FORMAT difference: the JCS input mirrors the legacy hasher's
+ * `{ method, params }` shape, so the underlying digest BYTES are identical — but the legacy hasher
+ * ({@link computeCanonicalHashes}) emits `sha256:<hex>`, so the two STRINGS never compare equal.
+ * A card proof is verified ONLY by the card verifier (which recomputes this exact form); do not
+ * string-compare it against a legacy `sha256:<hex>` value — use {@link digestsEqual} to compare the
+ * underlying digests across formats.
+ */
+export async function computeRequestHash(req) {
+    const canonicalRequest = { method: req.method, ...(req.params ? { params: req.params } : {}) };
+    const digest = await sha256(encoder.encode(canonicalize(canonicalRequest)));
+    return `sha-256=:${bytesToBase64(digest)}:`;
+}
+/** Hex of the SHA-256 digest carried by a `sha-256=:<base64>:` (RFC 9421) or `sha256:<hex>` (legacy)
+ *  string, or `null` if it is neither form. Lets integrators compare the two formats by digest. */
+function digestHex(value) {
+    const rfc9421 = /^sha-256=:([A-Za-z0-9+/=]+):$/.exec(value.trim());
+    if (rfc9421?.[1]) {
+        return Array.from(base64ToBytes(rfc9421[1]), (b) => b.toString(16).padStart(2, '0')).join('');
+    }
+    const legacy = /^sha256:([0-9a-fA-F]+)$/.exec(value.trim());
+    return legacy?.[1] ? legacy[1].toLowerCase() : null;
+}
+/**
+ * True iff two request-hash strings carry the SAME SHA-256 digest, accepting EITHER the card's RFC
+ * 9421 `sha-256=:<base64>:` form or the legacy `sha256:<hex>` form. The two forms are never
+ * string-equal for the same digest, so cross-format integrators MUST compare with this, not `===`.
+ */
+export function digestsEqual(a, b) {
+    const ha = digestHex(a);
+    const hb = digestHex(b);
+    return ha !== null && ha === hb;
+}
+/** The COVERED claims (every proof field except `jws`) — the object the JWS actually signs. */
+export function coveredClaims(meta) {
+    return {
+        prf: meta.prf,
+        alg: meta.alg,
+        did: meta.did,
+        kid: meta.kid,
+        audience: meta.audience,
+        nonce: meta.nonce,
+        created: meta.created,
+        expires: meta.expires,
+        requestHash: meta.requestHash,
+        ...(meta.cnf ? { cnf: meta.cnf } : {}),
+    };
+}
+/** The JCS canonical bytes of the covered claims — the exact detached-JWS signing payload. */
+export function canonicalPayloadBytes(meta) {
+    return encoder.encode(canonicalize(coveredClaims(meta)));
+}
+/** Re-encode a base64url value (a JWS signature) as standard base64 (an RFC 9421 byte sequence). */
+export function base64urlToBase64(b64url) {
+    return bytesToBase64(base64urlDecodeToBytes(b64url));
+}
+//# sourceMappingURL=canonical.js.map

package/dist/card/proof/canonical.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.js","sourceRoot":"","sources":["../../../src/card/proof/canonical.ts"],"names":[],"mappings":"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"}