@kya-os/mcp-i-cloudflare 1.9.7 → 1.10.0

package/dist/delegation-http/challenge-middleware.js

@@ -0,0 +1,190 @@
+/**
+ * draft-kya-http-02 delegation layer — §8.1 challenge emitter middleware.
+ *
+ * Triggers on JSON-RPC responses whose `result._meta.errorType ===
+ * "authorization_required"` (the existing `DelegationRequiredError` → `result._meta`
+ * mapping in `adapter.ts`), mints a sid, creates the pickup anchor (which MUST exist
+ * before the 401 leaves), signs the `challenge_proof`, and emits the §8.1 401 in
+ * `negotiated`/`always` mode. Returns `null` to pass the original response through.
+ *
+ * @module @kya-os/mcp-i-cloudflare/delegation-http/challenge-middleware
+ */
+import { sha256Hex } from "./hash";
+import { INTERNAL_PICKUP_CREATE } from "./constants";
+import { buildChallengeResponse, buildFetcherChallengeResponse, buildConsentUri, signChallengeProof, } from "./challenge";
+/**
+ * Inspect a cloned JSON-RPC response body for the `authorization_required` trigger.
+ * Returns the parsed meta when present, otherwise `null` (pass through untouched).
+ */
+async function readAuthorizationRequiredMeta(response) {
+    let parsed;
+    try {
+        parsed = await response.clone().json();
+    }
+    catch {
+        // Non-JSON or unreadable body: not a delegation error.
+        return null;
+    }
+    const result = parsed
+        ?.result;
+    const meta = result?._meta;
+    if (!meta || meta.errorType !== "authorization_required") {
+        return null;
+    }
+    return meta;
+}
+/**
+ * INTERACTIVE AI-agent fetcher User-Agents — agents that fetch on behalf of a human in
+ * a live session (so they can relay a consent link) but collapse 4xx/5xx bodies and
+ * never surface a 401 challenge to the LLM. Deliberately EXCLUDES indexing crawlers
+ * (e.g. GPTBot, OAI-SearchBot, PerplexityBot): a crawler has no user to relay consent
+ * to, so it stays on the spec path — matching the engine PEPs' `ai_agent` (NOT bot)
+ * contract. TRANSITIONAL worker-local heuristic; the durable signal is the
+ * `KYA-Accept-Challenge` opt-in header, and this list retires as frameworks adopt it.
+ */
+const AI_AGENT_FETCHER_UA = /\b(claude-user|chatgpt-user)\b/i;
+/**
+ * A cooperative agent fetcher that should receive the body-readable HTTP 200 envelope
+ * instead of a 401 it would silently drop: the caller opts in via `KYA-Accept-Challenge`
+ * (any non-empty value — the durable, primary signal), OR its User-Agent matches a known
+ * agent fetcher (the transitional heuristic). Mirrors the other PEPs' `serveBodyReadable200`
+ * predicate. A cooperative-UX bridge, NOT an access control.
+ */
+function callerWantsBodyReadable200(request) {
+    const accept = request.headers.get("KYA-Accept-Challenge");
+    if (accept && accept.trim().length > 0) {
+        return true;
+    }
+    const ua = request.headers.get("User-Agent") ?? "";
+    return AI_AGENT_FETCHER_UA.test(ua);
+}
+/**
+ * A signature-capable caller (RFC 9421 `Signature-Input` with a `kya` label) that can
+ * read a 4xx and handle the dual `WWW-Authenticate` wire — it keeps the spec 401.
+ */
+function callerIsSignatureCapable(request) {
+    const signatureInput = request.headers.get("Signature-Input");
+    return !!signatureInput && /(^|,)\s*kya\s*=/.test(signatureInput);
+}
+/** Pull the required scopes out of the adapter meta, defaulting to an empty list. */
+function readRequiredScopes(meta) {
+    if (Array.isArray(meta.requiredScopes)) {
+        return meta.requiredScopes.filter((scope) => typeof scope === "string");
+    }
+    return [];
+}
+/**
+ * Derive a deterministic anchor sid (`kya-` + 32 hex) from the MCP session, the
+ * required scopes, AND the `minAssurance` (W1 creation-bounding). Repeated
+ * `authorization_required` results for the same caller+scopes+assurance reuse one
+ * `pickup:<sid>` anchor instead of minting a fresh durable object per request. A
+ * session-less caller collapses to one anchor per (scope-set, assurance); the MCP
+ * session id (when present) separates clients.
+ *
+ * `minAssurance` is part of the key because `reduceCreate` reuses a still-live anchor
+ * without mutating its fields: if it were omitted, a later challenge advertising a new
+ * `min_assurance` would reuse an anchor (and consent surface) still carrying the old
+ * value — so a changed assurance MUST derive a distinct anchor.
+ */
+function deriveAnchorSid(request, requiredScopes, minAssurance) {
+    const session = request.headers.get("mcp-session-id") ?? "";
+    const scopeKey = [...requiredScopes].sort().join(" ");
+    return `kya-${sha256Hex(`${session}\n${scopeKey}\n${minAssurance ?? ""}`).slice(0, 32)}`;
+}
+/**
+ * Emit a §8.1 delegation challenge in place of an `authorization_required` MCP
+ * response, or return `null` to pass the original response through untouched.
+ *
+ * `negotiated` (default): when the caller is NOT kya-capable, the ORIGINAL MCP error
+ * response is returned (so existing MCP/OAuth clients still see the unmodified error),
+ * never a 401. `always`: every `authorization_required` becomes a 401.
+ */
+export async function maybeEmitDelegationChallenge(request, response, env, cfg, deps) {
+    const meta = await readAuthorizationRequiredMeta(response);
+    if (!meta) {
+        // Not a delegation error — pass through untouched.
+        return null;
+    }
+    // Selection: a cooperative agent fetcher gets the body-readable 200; a
+    // signature-capable client gets the spec 401. In `negotiated` mode a caller that is
+    // NEITHER is handed back the original MCP error (never a challenge it can't read).
+    const wantsBodyReadable200 = callerWantsBodyReadable200(request);
+    const signatureCapable = callerIsSignatureCapable(request);
+    if (cfg.mode === "negotiated" && !wantsBodyReadable200 && !signatureCapable) {
+        return response;
+    }
+    // W4: pin the challenge host to the configured realm when set, falling back to the
+    // request Host only when unset — so a Host-header-reflecting deployment cannot get
+    // an org-signed challenge (and consent/pickup links) pointing at an attacker host.
+    const host = cfg.realm || new URL(request.url).host;
+    const requiredScopes = readRequiredScopes(meta);
+    const minAssurance = typeof meta.minAssurance === "string" ? meta.minAssurance : undefined;
+    const sid = deriveAnchorSid(request, requiredScopes, minAssurance);
+    const verdict = {
+        requiredScopes,
+        minAssurance,
+        authorizationHost: host,
+        realm: host,
+        sid,
+        pollIntervalS: cfg.pollIntervalS,
+    };
+    // The anchor MUST exist before the 401 leaves: a caller could poll the pickup URL
+    // the instant it reads the challenge. Create-then-respond ordering is enforced here
+    // by awaiting the DO create — AND verifying it persisted (201) — before
+    // signing/building the response. If the create fails (non-201) or the durable
+    // object is unreachable, we suppress the challenge and fall through (return null)
+    // to the original MCP `authorization_required` error rather than advertise a
+    // consent/pickup URI for an anchor that was never persisted (clients would poll a
+    // §13 404/invalid-session forever).
+    const anchorStub = deps.getAnchorStub(env, sid);
+    let anchorPersisted = false;
+    try {
+        const createResponse = await anchorStub.fetch(`https://do${INTERNAL_PICKUP_CREATE}`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                sid,
+                requiredScopes: verdict.requiredScopes,
+                ...(verdict.minAssurance !== undefined
+                    ? { minAssurance: verdict.minAssurance }
+                    : {}),
+                pollIntervalS: cfg.pollIntervalS,
+                anchorTtlS: cfg.anchorTtlS,
+                delegationExpiresInS: cfg.delegationExpiresInS,
+            }),
+        });
+        // reduceCreate returns 201 for both a fresh anchor and the idempotent reuse of a
+        // still-live one (W1 deterministic sid), so 201 is the only success status.
+        anchorPersisted = createResponse.status === 201;
+        if (!anchorPersisted) {
+            console.warn(`[kya-http] pickup anchor create returned ${createResponse.status} (sid=${sid}); suppressing §8.1 challenge`);
+        }
+    }
+    catch (error) {
+        console.warn(`[kya-http] pickup anchor create failed (sid=${sid}); suppressing §8.1 challenge:`, error instanceof Error ? error.message : String(error));
+        anchorPersisted = false;
+    }
+    if (!anchorPersisted) {
+        return null;
+    }
+    try {
+        const challengeProof = await signChallengeProof(await deps.proofGenerator(), {
+            sid,
+            consent_uri: buildConsentUri(verdict),
+            required_scopes: verdict.requiredScopes,
+        });
+        // Cooperative fetchers get the body-readable 200; everyone else the spec 401.
+        return wantsBodyReadable200
+            ? buildFetcherChallengeResponse(verdict, challengeProof)
+            : buildChallengeResponse(verdict, challengeProof);
+    }
+    catch (error) {
+        // The anchor persisted, but signing/building the challenge failed (e.g. a proof
+        // generator outage). Suppress the 401 and fall through to the original MCP error
+        // rather than throwing into a bare 500 — symmetric with the create-failure path
+        // above. The orphaned anchor is harmless: it expires via its ≤600s TTL.
+        console.warn(`[kya-http] challenge proof signing failed (sid=${sid}); suppressing §8.1 challenge:`, error instanceof Error ? error.message : String(error));
+        return null;
+    }
+}
+//# sourceMappingURL=challenge-middleware.js.map

package/dist/delegation-http/challenge-middleware.js.map

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

package/dist/delegation-http/challenge.d.ts

@@ -0,0 +1,86 @@
+/**
+ * draft-kya-http-02 delegation layer — §8.1 challenge emitter (builders + signing).
+ *
+ * Byte-exact against the vendored golden fixture
+ * `src/__tests__/fixtures/kya-http/challenge.delegation.full.json`. The wire format
+ * is frozen: param order is `CHALLENGE_PARAM_ORDER`, the separator is `", "`, every
+ * value is a quoted string, `scope` is space-joined, and `min_assurance` is omitted
+ * ENTIRELY when absent (the whole `min_assurance="…"` token is dropped, not emitted
+ * empty).
+ *
+ * The worker is its own Tier-2 authorization host: `consent_uri`/`pickup_uri` point
+ * at `authorizationHost`, while the Bearer challenge's `resource_metadata` points at
+ * the `realm` (the protected resource origin).
+ *
+ * @module @kya-os/mcp-i-cloudflare/delegation-http/challenge
+ */
+import type { ChallengeVerdictInput } from "./types";
+import type { CloudflareProofGenerator } from "../proof-generator";
+/**
+ * Build the `WWW-Authenticate: Delegation …` header value (§8.1), byte-exact.
+ *
+ * Params are emitted in `CHALLENGE_PARAM_ORDER`, joined by `", "`, every value
+ * quoted. `min_assurance` is dropped entirely when `i.minAssurance` is absent.
+ */
+export declare function buildWWWAuthenticateDelegation(i: ChallengeVerdictInput): string;
+/**
+ * Build the companion `WWW-Authenticate: Bearer …` header value. `resource_metadata`
+ * points at the protected resource (`realm`), not the authorization host.
+ */
+export declare function buildWWWAuthenticateBearer(realm: string): string;
+/** The consent surface URL on the worker's authorization host: `…/consent?sid=<sid>`. */
+export declare function buildConsentUri(i: ChallengeVerdictInput): string;
+/** The pickup endpoint URL on the worker's authorization host: `…/api/delegation/pickup/<sid>`. */
+export declare function buildPickupUri(i: ChallengeVerdictInput): string;
+/**
+ * Build the human-facing `instructions` string (§8.1). Carries the four REQUIRED
+ * elements: (1) consent-uri relay, (2) pickup-uri + interval, (3) pinning
+ * requirement, (4) retry presentation. Byte-exact vs the fixture given its inputs.
+ */
+export declare function buildInstructions(i: ChallengeVerdictInput): string;
+/**
+ * Build the §8.1 401 JSON body. Key order mirrors the golden fixture's `http.body`.
+ * `min_assurance` is omitted when absent.
+ */
+export declare function buildChallengeBody(i: ChallengeVerdictInput, challengeProof: string): object;
+/**
+ * Build the full §8.1 401 `Response`: dual `WWW-Authenticate` challenges (Delegation
+ * first, then Bearer), `Retry-After`, JSON content type, and `Cache-Control:
+ * no-store`.
+ */
+export declare function buildChallengeResponse(i: ChallengeVerdictInput, challengeProof: string): Response;
+/**
+ * Build the body-readable §8.1 **200** `Response` for AI-agent fetchers that drop 4xx
+ * bodies (draft-kya-http-02 fetcher-compatibility envelope). REUSES `buildChallengeBody`
+ * so the JSON body is BYTE-IDENTICAL to the 401 — the org-signed `challenge_proof` binds
+ * the body content, not the HTTP envelope, so the same proof verifies at 200 or 401.
+ *
+ * Differs from the 401 (`buildChallengeResponse`) only in the envelope:
+ *  - status `200`, not `401`
+ *  - NO `WWW-Authenticate` (a 200 carrying it is reinterpreted as a 401 by some fetchers,
+ *    re-dropping the body)
+ *  - NO `Retry-After` (cadence lives in the body `poll_interval_s` + instructions)
+ *  - adds the consent hint headers `KYA-Auth-Required`/`KYA-Auth-Url`/`Link` and the
+ *    `KYA-Action: challenge` discriminator.
+ *
+ * The authoritative consent target is the proof-covered body `consent_uri`; the
+ * `KYA-Auth-Url`/`Link` headers are UNSIGNED hints for fetchers that only surface
+ * headers. Selection is a cooperative-UX bridge, NOT an access control.
+ */
+export declare function buildFetcherChallengeResponse(i: ChallengeVerdictInput, challengeProof: string): Response;
+/**
+ * Sign the `challenge_proof`: a verifiable 3-segment compact JWS whose `requestHash`
+ * commits to `{ sid, consent_uri, required_scopes }`.
+ *
+ * Implemented over the public `CloudflareProofGenerator.generateProof` seam: the
+ * challenge fields are canonicalized into the proof's request, so the signed
+ * `requestHash` cryptographically covers them. A verifier recomputes
+ * `sha256(canonical({ method: "kyaos/challenge", params }))` and checks it equals the
+ * payload's `requestHash`, then verifies the Ed25519 signature.
+ */
+export declare function signChallengeProof(gen: CloudflareProofGenerator, payload: {
+    sid: string;
+    consent_uri: string;
+    required_scopes: string[];
+}): Promise<string>;
+//# sourceMappingURL=challenge.d.ts.map

package/dist/delegation-http/challenge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge.d.ts","sourceRoot":"","sources":["../../src/delegation-http/challenge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAUnE;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,CAAC,EAAE,qBAAqB,GACvB,MAAM,CAqBR;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhE;AAED,yFAAyF;AACzF,wBAAgB,eAAe,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAEhE;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAE/D;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAUlE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,qBAAqB,EACxB,cAAc,EAAE,MAAM,GACrB,MAAM,CAkBR;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,EAAE,qBAAqB,EACxB,cAAc,EAAE,MAAM,GACrB,QAAQ,CAYV;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,6BAA6B,CAC3C,CAAC,EAAE,qBAAqB,EACxB,cAAc,EAAE,MAAM,GACrB,QAAQ,CAcV;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,wBAAwB,EAC7B,OAAO,EAAE;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,eAAe,EAAE,MAAM,EAAE,CAAA;CAAE,GACvE,OAAO,CAAC,MAAM,CAAC,CAmBjB"}

package/dist/delegation-http/challenge.js

@@ -0,0 +1,173 @@
+/**
+ * draft-kya-http-02 delegation layer — §8.1 challenge emitter (builders + signing).
+ *
+ * Byte-exact against the vendored golden fixture
+ * `src/__tests__/fixtures/kya-http/challenge.delegation.full.json`. The wire format
+ * is frozen: param order is `CHALLENGE_PARAM_ORDER`, the separator is `", "`, every
+ * value is a quoted string, `scope` is space-joined, and `min_assurance` is omitted
+ * ENTIRELY when absent (the whole `min_assurance="…"` token is dropped, not emitted
+ * empty).
+ *
+ * The worker is its own Tier-2 authorization host: `consent_uri`/`pickup_uri` point
+ * at `authorizationHost`, while the Bearer challenge's `resource_metadata` points at
+ * the `realm` (the protected resource origin).
+ *
+ * @module @kya-os/mcp-i-cloudflare/delegation-http/challenge
+ */
+import { CHALLENGE_PARAM_ORDER, KYAOS_ERRORS } from "./constants";
+/**
+ * The JSON-RPC method label committed inside the `challenge_proof` JWS. The proof's
+ * `requestHash` is `sha256(canonical({ method, params: { sid, consent_uri,
+ * required_scopes } }))`, so the signed proof cryptographically covers the three
+ * challenge fields. Verifiers recompute this hash to confirm coverage.
+ */
+const CHALLENGE_PROOF_METHOD = "kyaos/challenge";
+/**
+ * Build the `WWW-Authenticate: Delegation …` header value (§8.1), byte-exact.
+ *
+ * Params are emitted in `CHALLENGE_PARAM_ORDER`, joined by `", "`, every value
+ * quoted. `min_assurance` is dropped entirely when `i.minAssurance` is absent.
+ */
+export function buildWWWAuthenticateDelegation(i) {
+    const values = {
+        realm: i.realm,
+        sid: i.sid,
+        consent_uri: buildConsentUri(i),
+        pickup_uri: buildPickupUri(i),
+        scope: i.requiredScopes.join(" "),
+        min_assurance: i.minAssurance,
+        interval: String(i.pollIntervalS),
+        kind: "delegation",
+    };
+    const params = CHALLENGE_PARAM_ORDER.filter(
+    // min_assurance is the only optional param: omit the whole token when absent.
+    (key) => values[key] !== undefined).map((key) => `${key}="${values[key]}"`);
+    return `Delegation ${params.join(", ")}`;
+}
+/**
+ * Build the companion `WWW-Authenticate: Bearer …` header value. `resource_metadata`
+ * points at the protected resource (`realm`), not the authorization host.
+ */
+export function buildWWWAuthenticateBearer(realm) {
+    return `Bearer resource_metadata="https://${realm}/.well-known/oauth-protected-resource"`;
+}
+/** The consent surface URL on the worker's authorization host: `…/consent?sid=<sid>`. */
+export function buildConsentUri(i) {
+    return `https://${i.authorizationHost}/consent?sid=${i.sid}`;
+}
+/** The pickup endpoint URL on the worker's authorization host: `…/api/delegation/pickup/<sid>`. */
+export function buildPickupUri(i) {
+    return `https://${i.authorizationHost}/api/delegation/pickup/${i.sid}`;
+}
+/**
+ * Build the human-facing `instructions` string (§8.1). Carries the four REQUIRED
+ * elements: (1) consent-uri relay, (2) pickup-uri + interval, (3) pinning
+ * requirement, (4) retry presentation. Byte-exact vs the fixture given its inputs.
+ */
+export function buildInstructions(i) {
+    const consentUri = buildConsentUri(i);
+    const pickupUri = buildPickupUri(i);
+    return (`This action requires human authorization. Show your user this link and ask them to approve: ${consentUri}. ` +
+        `Then poll ${pickupUri} every ${i.pollIntervalS} seconds. ` +
+        `If you can sign HTTP requests, sign each poll with an ephemeral did:key; ` +
+        `otherwise generate one random 32-byte token and send it as X-KYA-Pickup-Token on EVERY poll. ` +
+        `When the response status is 200, take the 'delegation' value and retry your original request with header 'Authorization: Bearer <delegation>'.`);
+}
+/**
+ * Build the §8.1 401 JSON body. Key order mirrors the golden fixture's `http.body`.
+ * `min_assurance` is omitted when absent.
+ */
+export function buildChallengeBody(i, challengeProof) {
+    const kyaos = {
+        sid: i.sid,
+        consent_uri: buildConsentUri(i),
+        pickup_uri: buildPickupUri(i),
+        required_scopes: i.requiredScopes,
+    };
+    if (i.minAssurance !== undefined) {
+        kyaos.min_assurance = i.minAssurance;
+    }
+    kyaos.poll_interval_s = i.pollIntervalS;
+    kyaos.challenge_proof = challengeProof;
+    return {
+        error: KYAOS_ERRORS.authorizationRequired,
+        kyaos,
+        instructions: buildInstructions(i),
+    };
+}
+/**
+ * Build the full §8.1 401 `Response`: dual `WWW-Authenticate` challenges (Delegation
+ * first, then Bearer), `Retry-After`, JSON content type, and `Cache-Control:
+ * no-store`.
+ */
+export function buildChallengeResponse(i, challengeProof) {
+    const headers = new Headers();
+    headers.append("WWW-Authenticate", buildWWWAuthenticateDelegation(i));
+    headers.append("WWW-Authenticate", buildWWWAuthenticateBearer(i.realm));
+    headers.set("Retry-After", String(i.pollIntervalS));
+    headers.set("Content-Type", "application/json");
+    headers.set("Cache-Control", "no-store");
+    return new Response(JSON.stringify(buildChallengeBody(i, challengeProof)), {
+        status: 401,
+        headers,
+    });
+}
+/**
+ * Build the body-readable §8.1 **200** `Response` for AI-agent fetchers that drop 4xx
+ * bodies (draft-kya-http-02 fetcher-compatibility envelope). REUSES `buildChallengeBody`
+ * so the JSON body is BYTE-IDENTICAL to the 401 — the org-signed `challenge_proof` binds
+ * the body content, not the HTTP envelope, so the same proof verifies at 200 or 401.
+ *
+ * Differs from the 401 (`buildChallengeResponse`) only in the envelope:
+ *  - status `200`, not `401`
+ *  - NO `WWW-Authenticate` (a 200 carrying it is reinterpreted as a 401 by some fetchers,
+ *    re-dropping the body)
+ *  - NO `Retry-After` (cadence lives in the body `poll_interval_s` + instructions)
+ *  - adds the consent hint headers `KYA-Auth-Required`/`KYA-Auth-Url`/`Link` and the
+ *    `KYA-Action: challenge` discriminator.
+ *
+ * The authoritative consent target is the proof-covered body `consent_uri`; the
+ * `KYA-Auth-Url`/`Link` headers are UNSIGNED hints for fetchers that only surface
+ * headers. Selection is a cooperative-UX bridge, NOT an access control.
+ */
+export function buildFetcherChallengeResponse(i, challengeProof) {
+    const consentUri = buildConsentUri(i);
+    const headers = new Headers();
+    headers.set("Content-Type", "application/json");
+    headers.set("Cache-Control", "no-store");
+    headers.set("KYA-Auth-Required", "true");
+    headers.set("KYA-Auth-Url", consentUri);
+    headers.set("Link", `<${consentUri}>; rel="kya-authorize"`);
+    headers.set("KYA-Action", "challenge");
+    return new Response(JSON.stringify(buildChallengeBody(i, challengeProof)), {
+        status: 200,
+        headers,
+    });
+}
+/**
+ * Sign the `challenge_proof`: a verifiable 3-segment compact JWS whose `requestHash`
+ * commits to `{ sid, consent_uri, required_scopes }`.
+ *
+ * Implemented over the public `CloudflareProofGenerator.generateProof` seam: the
+ * challenge fields are canonicalized into the proof's request, so the signed
+ * `requestHash` cryptographically covers them. A verifier recomputes
+ * `sha256(canonical({ method: "kyaos/challenge", params }))` and checks it equals the
+ * payload's `requestHash`, then verifies the Ed25519 signature.
+ */
+export async function signChallengeProof(gen, payload) {
+    const proof = await gen.generateProof({
+        method: CHALLENGE_PROOF_METHOD,
+        params: {
+            sid: payload.sid,
+            consent_uri: payload.consent_uri,
+            required_scopes: payload.required_scopes,
+        },
+    }, { data: { sid: payload.sid } }, {
+        // The session binds the proof to this anchor; sid is the natural nonce.
+        nonce: payload.sid,
+        audience: payload.consent_uri,
+        sessionId: payload.sid,
+    });
+    return proof.jws;
+}
+//# sourceMappingURL=challenge.js.map

package/dist/delegation-http/challenge.js.map

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

package/dist/delegation-http/consent-anchor-bridge.d.ts

@@ -0,0 +1,35 @@
+/**
+ * draft-kya-http-02 delegation layer — consent → pickup bridge.
+ *
+ * The worker is its own Tier-2 authorization host: the §8.1 challenge points the
+ * caller's user at `consent_uri = /consent?sid=kya-…`, served here. This module is
+ * the route-order interception that `register.ts` wires BEFORE the legacy `/consent`
+ * routes; it only ever handles requests whose query carries an anchor sid (the
+ * `next()` fall-through for everything else lives in `register.ts`), so the legacy
+ * consent service is untouched.
+ *
+ *  - `GET /consent?sid=kya-…` reads the anchor via `INTERNAL_PICKUP_INFO`. An unknown
+ *    sid → 404 page; an expired sid → a "link expired" page; otherwise a minimal
+ *    approve form (the consent-only scope list + a CSRF-protected POST).
+ *  - `POST /consent/approve?sid=kya-…` mints a delegation VC-JWT using the SAME
+ *    `@kya-os/mcp` primitives `consent.service.ts` uses (`wrapDelegationAsVC` →
+ *    `createUnsignedVCJWT` → sign → `completeVCJWT`) — calling them directly here, NOT
+ *    editing the service — then parks it on the anchor via `INTERNAL_PICKUP_APPROVE`.
+ *    If the anchor is gone (DO 410/404) the approval FAILS with an error page and
+ *    mints nothing reachable: consent on an EXPIRED anchor MUST fail.
+ *
+ * @module @kya-os/mcp-i-cloudflare/delegation-http/consent-anchor-bridge
+ */
+import type { HonoContext } from "../runtime/oauth-handler";
+import type { CloudflareEnv } from "../types";
+import type { HttpChallengeConfig } from "../config";
+/**
+ * Render the anchor consent surface for `GET /consent?sid=kya-…`.
+ */
+export declare function handleAnchorConsentGet(c: HonoContext, sid: string, env: CloudflareEnv, _cfg: Required<HttpChallengeConfig>): Promise<Response>;
+/**
+ * Handle anchor approval for `POST /consent/approve?sid=kya-…`. Mints a VC-JWT and
+ * parks it on the anchor; an expired/unknown anchor makes the approval FAIL.
+ */
+export declare function handleAnchorConsentApprove(c: HonoContext, sid: string, env: CloudflareEnv, cfg: Required<HttpChallengeConfig>): Promise<Response>;
+//# sourceMappingURL=consent-anchor-bridge.d.ts.map

package/dist/delegation-http/consent-anchor-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consent-anchor-bridge.d.ts","sourceRoot":"","sources":["../../src/delegation-http/consent-anchor-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAWH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAkWrD;;GAEG;AACH,wBAAsB,sBAAsB,CAC1C,CAAC,EAAE,WAAW,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,aAAa,EAClB,IAAI,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GAClC,OAAO,CAAC,QAAQ,CAAC,CAiBnB;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,CAAC,EAAE,WAAW,EACd,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GACjC,OAAO,CAAC,QAAQ,CAAC,CAyEnB"}