@atlasauth/pca-gnap 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,697 @@
+"use strict";
+/**
+ * @atlasauth/pca-gnap — a GNAP (RFC 9635) bridge for Proof-Carrying Authority, defining the
+ * ================= AGENT-GNAP PROFILE =================
+ *
+ * GNAP (Grant Negotiation and Authorization Protocol, RFC 9635) negotiates an access grant between a
+ * client instance and an authorization server (AS) using a rich, structured `access` rights model,
+ * key-bound requests, and a stateful *continuation* handle. No agent-delegation profile of GNAP exists
+ * publicly yet. This package DEFINES one, because GNAP's primitives map almost 1:1 onto PCA's:
+ *
+ *   GNAP concept                          PCA concept
+ *   ------------------------------------  ---------------------------------------------------------
+ *   `access` rights array (§8)            Policy-envelope `Predicate[]` (verb/resource/where)
+ *     - type                               → resource namespace  `gnap:<type>:<location>`
+ *     - actions                            → predicate `verb` (list, or `*`)
+ *     - locations                          → predicate `resource` (exact / prefix)
+ *     - datatypes / identifier             → predicate `where` conditions on `action.params.*`
+ *   client instance key (§7.1)            Capability `holder` (the bound key, `cnf`)
+ *   grant request (§2)                    `mintGrant` (root) / `delegate` (a delegated hop)
+ *   grant response access_token (§3.2)    A verifiable PCA capability chain (bound, attenuated)
+ *   `continue` handle (§3.1, §5)          A PCA step-up: a FROST/CIBA co-signature folded into a PCActn
+ *   `interact` (§3.3, §4)                 The tier-2/3 human/guardian step-up prompt
+ *   key-bound proof `jwsd` (§7.3.4)       Detached-JWS proof that the request was signed by `holder`
+ *
+ * THE AGENT-GNAP PROFILE (multi-hop delegation). An agent-to-agent (A2A) task is a chain of grants:
+ * each hop is a GNAP grant request from one agent to the next, and the AS issues a PCA capability that
+ * is ATTENUATED — never wider than the issuing agent's own authority. Attenuation is structural: PCA
+ * capability caveats are append-only and conjunctive (see `@atlasauth/pca` capability.ts), so a child
+ * can only ever NARROW. Each hop records its granted `access` as a signed `gnap_access` caveat, and the
+ * EFFECTIVE authority of the chain is the INTERSECTION of the root policy envelope and every hop's
+ * recorded rights. A hop that requests more than its issuer held is clamped at issue time
+ * (`clampToIssuer`) AND denied at action time (the issuer's narrower rights still gate every action),
+ * so "never wider than the issuer" holds by construction across any number of hops.
+ *
+ * All verification FAILS CLOSED: a malformed token, a broken chain, a bad jwsd proof, a stale request,
+ * or an action outside the granted rights denies. The machine-readable profile spec is exported as
+ * {@link AGENT_GNAP_PROFILE}.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_GNAP_PROFILE = exports.GNAP_ACCESS_CAVEAT = exports.GNAP_GRANT_CAVEAT = exports.GnapError = void 0;
+exports.gnapActionResource = gnapActionResource;
+exports.normalizeAccess = normalizeAccess;
+exports.accessToPredicates = accessToPredicates;
+exports.accessContains = accessContains;
+exports.accessWithin = accessWithin;
+exports.clampAccess = clampAccess;
+exports.grantedAccessOf = grantedAccessOf;
+exports.resolveHolder = resolveHolder;
+exports.holderJwk = holderJwk;
+exports.grantRequestToCapability = grantRequestToCapability;
+exports.authorizeGnapAction = authorizeGnapAction;
+exports.encodeBoundToken = encodeBoundToken;
+exports.capabilityToGrantResponse = capabilityToGrantResponse;
+exports.verifyGnapToken = verifyGnapToken;
+exports.signGnapRequest = signGnapRequest;
+exports.verifyGnapRequest = verifyGnapRequest;
+exports.gnapRequestRequiresStepUp = gnapRequestRequiresStepUp;
+exports.beginGnapContinuation = beginGnapContinuation;
+exports.gnapStepUpShare = gnapStepUpShare;
+exports.completeGnapContinuation = completeGnapContinuation;
+const jose_1 = require("jose");
+const pca_1 = require("@atlasauth/pca");
+// ============================================================================================
+// Errors + small guards
+// ============================================================================================
+/** Thrown by the issuance paths on a malformed request (the verify paths fail closed instead). */
+class GnapError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GnapError';
+    }
+}
+exports.GnapError = GnapError;
+const isRecord = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
+const strArr = (u) => Array.isArray(u) ? u.filter((s) => typeof s === 'string') : undefined;
+/** A canonical, unpadded base64url Ed25519 public key (exactly 32 bytes), or null. */
+function asEd25519(x) {
+    return typeof x === 'string' && (0, pca_1.decodeB64uStrict)(x, 32) !== null ? x : null;
+}
+const GNAP_RESOURCE_PREFIX = 'gnap';
+/** The PCA `resource` string for a GNAP (type, location) pair — the namespace actions are matched in. */
+function gnapActionResource(type, location) {
+    return `${GNAP_RESOURCE_PREFIX}:${type}:${location}`;
+}
+// ============================================================================================
+// Access-rights normalization + mapping onto PCA predicates
+// ============================================================================================
+/** Total, fail-closed normalization of one access item. Returns null for anything malformed. */
+function tryNormalizeAccessItem(item) {
+    if (typeof item === 'string')
+        return item.length > 0 ? { type: item } : null;
+    if (!isRecord(item))
+        return null;
+    const type = item.type;
+    if (typeof type !== 'string' || type.length === 0)
+        return null;
+    const out = { type };
+    const actions = strArr(item.actions);
+    if (actions && actions.length > 0)
+        out.actions = actions;
+    const locations = strArr(item.locations);
+    if (locations && locations.length > 0)
+        out.locations = locations;
+    const datatypes = strArr(item.datatypes);
+    if (datatypes && datatypes.length > 0)
+        out.datatypes = datatypes;
+    if (typeof item.identifier === 'string')
+        out.identifier = item.identifier;
+    const privileges = strArr(item.privileges);
+    if (privileges && privileges.length > 0)
+        out.privileges = privileges;
+    return out;
+}
+/** Normalize one access item, THROWING on malformed input (issuance path). */
+function normalizeAccessItem(item) {
+    const n = tryNormalizeAccessItem(item);
+    if (n === null)
+        throw new GnapError('malformed access item (needs a non-empty string `type`)');
+    return n;
+}
+/** Normalize an access array for issuance (throws on any malformed entry). */
+function normalizeAccess(items) {
+    if (!Array.isArray(items))
+        throw new GnapError('access must be an array');
+    return items.map(normalizeAccessItem);
+}
+/** Total, fail-closed read of a stored access array (reading signed caveats). Skips malformed entries. */
+function readAccessArray(u) {
+    if (!Array.isArray(u))
+        return [];
+    const out = [];
+    for (const item of u) {
+        const n = tryNormalizeAccessItem(item);
+        if (n !== null)
+            out.push(n);
+    }
+    return out;
+}
+/**
+ * Map a GNAP access right onto PCA predicates (one per location). `type` namespaces the resource,
+ * `actions` become verbs, `locations` become resources, and `datatypes`/`identifier` become `where`
+ * conditions on the action's params. An absent `actions`/`locations` means "any" (verb `*` / a
+ * prefix-matching `*` resource).
+ */
+function accessToPredicates(access) {
+    const verb = access.actions && access.actions.length > 0 ? [...access.actions] : '*';
+    const locations = access.locations && access.locations.length > 0 ? access.locations : ['*'];
+    const where = [];
+    if (access.datatypes && access.datatypes.length > 0) {
+        where.push({ field: 'action.params.datatype', op: 'in', value: [...access.datatypes] });
+    }
+    if (typeof access.identifier === 'string') {
+        where.push({ field: 'action.params.identifier', op: 'eq', value: access.identifier });
+    }
+    return locations.map((loc) => {
+        const p = { verb, resource: gnapActionResource(access.type, loc) };
+        if (where.length > 0)
+            p.where = where.map((c) => ({ ...c }));
+        return p;
+    });
+}
+/** All predicates for an access array. */
+function accessArrayToPredicates(access) {
+    return access.flatMap(accessToPredicates);
+}
+// ============================================================================================
+// Access-level containment (the AS's "is this request within my authority?" check)
+// ============================================================================================
+function coversStrings(sup, sub) {
+    if (sup === undefined)
+        return true; // issuer allows all
+    if (sub === undefined)
+        return false; // request wants all, issuer has a concrete set
+    return sub.every((s) => sup.includes(s));
+}
+function coversLocations(sup, sub) {
+    if (sup === undefined)
+        return true;
+    if (sub === undefined)
+        return sup.includes('*');
+    return sub.every((s) => sup.some((g) => g === s || g === '*' || (g.endsWith('*') && s.startsWith(g.slice(0, -1)))));
+}
+/** Does the issuer's granted right `g` fully contain the requested right `r`? */
+function accessContains(g, r) {
+    if (g.type !== r.type)
+        return false;
+    if (!coversStrings(g.actions, r.actions))
+        return false;
+    if (!coversLocations(g.locations, r.locations))
+        return false;
+    if (!coversStrings(g.datatypes, r.datatypes))
+        return false;
+    if (r.identifier !== undefined && g.identifier !== undefined && g.identifier !== r.identifier)
+        return false;
+    return true;
+}
+/** Is `r` within the issuer's granted set `G` (covered by at least one of its rights)? */
+function accessWithin(G, r) {
+    return G.some((g) => accessContains(g, r));
+}
+/** Split a requested access array into the subset within the issuer's authority and the rest. */
+function clampAccess(issuerGranted, requested) {
+    const granted = [];
+    const dropped = [];
+    for (const r of requested)
+        (accessWithin(issuerGranted, r) ? granted : dropped).push(r);
+    return { granted, dropped };
+}
+// ============================================================================================
+// GNAP provenance caveats (recorded in the signed capability)
+// ============================================================================================
+/** The caveat recorded inside a ROOT GNAP grant's policy envelope (grant provenance). */
+exports.GNAP_GRANT_CAVEAT = 'gnap_grant';
+/** The caveat appended on each DELEGATED GNAP hop (the rights that hop was granted). */
+exports.GNAP_ACCESS_CAVEAT = 'gnap_access';
+/** Read the root grant's GNAP provenance caveat (inside the policy envelope), or null. */
+function readGnapGrant(root) {
+    const env = (0, pca_1.readEnvelope)(root);
+    const cv = env?.caveats.find((c) => c?.type === exports.GNAP_GRANT_CAVEAT);
+    if (!cv)
+        return null;
+    const clientId = cv.client_id;
+    const digest = cv.request_digest;
+    if (typeof clientId !== 'string' || typeof digest !== 'string')
+        return null;
+    return {
+        type: exports.GNAP_GRANT_CAVEAT,
+        client_id: clientId,
+        granted_access: readAccessArray(cv.granted_access),
+        request_digest: digest,
+        interacted: cv.interacted === true,
+        ts: typeof cv.ts === 'number' ? cv.ts : 0,
+    };
+}
+/**
+ * The EFFECTIVE granted access of a chain: the most-recent delegated hop's recorded rights, or (for a
+ * root-only grant) the root's recorded rights. Because every hop is clamped to its issuer at issue
+ * time, the leaf's recorded rights are the narrowest in the chain.
+ */
+function grantedAccessOf(chain) {
+    if (!Array.isArray(chain) || chain.length === 0)
+        return [];
+    const leaf = chain[chain.length - 1];
+    const caveats = Array.isArray(leaf.caveats) ? leaf.caveats : [];
+    for (let i = caveats.length - 1; i >= 0; i--) {
+        const cv = caveats[i];
+        if (cv?.type === exports.GNAP_ACCESS_CAVEAT)
+            return readAccessArray(cv.access);
+    }
+    const grant = readGnapGrant(chain[0]);
+    return grant ? grant.granted_access : [];
+}
+// ============================================================================================
+// Holder resolution (the GNAP client key becomes the PCA holder)
+// ============================================================================================
+/** Resolve the b64u Ed25519 holder key from a request's client key (or an explicit override). */
+function resolveHolder(req, holderOverride) {
+    if (holderOverride !== undefined) {
+        const h = asEd25519(holderOverride);
+        if (h === null)
+            throw new GnapError('holder override is not a canonical base64url Ed25519 public key');
+        return h;
+    }
+    const client = req.client;
+    const key = typeof client === 'object' && client !== null ? client.key : undefined;
+    if (key && typeof key === 'object' && key.jwk && key.jwk.kty === 'OKP' && key.jwk.crv === 'Ed25519') {
+        const x = asEd25519(key.jwk.x);
+        if (x !== null)
+            return x;
+    }
+    throw new GnapError('cannot resolve holder: supply client.key.jwk (OKP/Ed25519) or a holder override');
+}
+/** The holder key, rendered as a GNAP JWK (for a bound access-token response). */
+function holderJwk(holder) {
+    return { kty: 'OKP', crv: 'Ed25519', x: holder, use: 'sig', alg: 'EdDSA' };
+}
+function accessOf(req) {
+    const at = req.access_token;
+    if (isRecord(at) && Array.isArray(at.access))
+        return at.access;
+    throw new GnapError('grant request must carry access_token.access (single-token request)');
+}
+function requestDigestOf(holder, granted, interact) {
+    return (0, pca_1.hashCanonical)({
+        d: 'atlas-pca/gnap/request/v1',
+        client_id: holder,
+        access: granted,
+        interact: interact ?? null,
+    });
+}
+/**
+ * Convert a GNAP grant request into a PCA capability bound to the client key, ATTENUATED to never
+ * exceed the issuer. With no `parent` this MINTS a root grant whose policy-envelope predicates ARE the
+ * requested access rights. With a `parent` it DELEGATES a narrower hop, recording the (clamped) rights
+ * as an append-only `gnap_access` caveat — so the effective authority is the intersection of the whole
+ * chain, and no hop can widen.
+ */
+function grantRequestToCapability(req, opts) {
+    const holder = resolveHolder(req, opts.holder);
+    const requested = normalizeAccess(accessOf(req));
+    const now = Math.floor(opts.now ?? Date.now());
+    const interacted = opts.interacted === true;
+    let granted = requested;
+    let dropped = [];
+    if (opts.parent) {
+        const issuerChain = opts.issuerChain ?? [opts.parent];
+        if (opts.clampToIssuer !== false) {
+            const split = clampAccess(grantedAccessOf(issuerChain), requested);
+            granted = split.granted;
+            dropped = split.dropped;
+        }
+    }
+    const requestDigest = requestDigestOf(holder, granted, req.interact);
+    if (opts.parent) {
+        const issuerChain = opts.issuerChain ?? [opts.parent];
+        const provenance = {
+            type: exports.GNAP_ACCESS_CAVEAT,
+            access: granted,
+            predicates: accessArrayToPredicates(granted),
+            request_digest: requestDigest,
+            client_id: holder,
+            ts: now,
+        };
+        const child = (0, pca_1.delegate)(opts.parent, holder, [provenance], opts.issuerSecret);
+        return { grant: child, chain: [...issuerChain, child], holder, grantedAccess: granted, droppedAccess: dropped, provenance };
+    }
+    const provenance = {
+        type: exports.GNAP_GRANT_CAVEAT,
+        client_id: holder,
+        granted_access: granted,
+        request_digest: requestDigest,
+        interacted,
+        ts: now,
+    };
+    const { grant } = (0, pca_1.mintGrant)({
+        principalSecret: opts.issuerSecret,
+        principalPublic: opts.issuerPublic,
+        holder,
+        goal: opts.goal ?? `gnap:grant:${holder}`,
+        envelope: {
+            predicates: accessArrayToPredicates(granted),
+            caveats: [provenance],
+            agent_binding: opts.agentBinding ?? {},
+            risk_policy: opts.riskPolicy ?? pca_1.DEFAULT_RISK_POLICY,
+        },
+        ...(opts.salt !== undefined ? { salt: opts.salt } : {}),
+    });
+    return { grant, chain: [grant], holder, grantedAccess: granted, droppedAccess: dropped, provenance };
+}
+/**
+ * Decide whether `action` is authorized by a GNAP-issued capability chain. FAILS CLOSED. The chain must
+ * verify structurally, the root policy envelope must permit the action, AND every delegated hop's
+ * recorded `gnap_access` rights must permit it too (the per-hop intersection that enforces "never wider
+ * than the issuer" across the whole chain).
+ */
+function authorizeGnapAction(chain, action, opts = {}) {
+    if (!Array.isArray(chain) || chain.length === 0)
+        return { allowed: false, reason: 'empty chain' };
+    const vc = (0, pca_1.verifyChain)(chain, opts.expectedRootIssuer);
+    if (!vc.ok)
+        return { allowed: false, reason: `capability chain invalid: ${vc.reason ?? 'unknown'}` };
+    const env = (0, pca_1.readEnvelope)(chain[0]);
+    if (!env)
+        return { allowed: false, reason: 'root grant carries no policy envelope' };
+    const ctx = {
+        action: {
+            verb: action.verb,
+            resource: action.resource,
+            ...(action.params !== undefined ? { params: action.params } : {}),
+            ...(action.reversibility_class !== undefined ? { reversibility_class: action.reversibility_class } : {}),
+        },
+    };
+    const rootDecision = (0, pca_1.evaluatePredicates)(env.predicates, ctx);
+    if (!rootDecision.allowed) {
+        return { allowed: false, reason: `root authority denies: ${rootDecision.reason ?? 'no predicate matched'}` };
+    }
+    const leaf = chain[chain.length - 1];
+    const caveats = Array.isArray(leaf.caveats) ? leaf.caveats : [];
+    for (const cv of caveats) {
+        if (cv?.type !== exports.GNAP_ACCESS_CAVEAT)
+            continue;
+        const hopPreds = accessArrayToPredicates(readAccessArray(cv.access));
+        const hopDecision = (0, pca_1.evaluatePredicates)(hopPreds, ctx);
+        if (!hopDecision.allowed) {
+            return { allowed: false, reason: `delegated hop denies: ${hopDecision.reason ?? 'no predicate matched'}` };
+        }
+    }
+    return { allowed: true };
+}
+// ============================================================================================
+// Bound token: PCA capability chain ↔ GNAP access token
+// ============================================================================================
+/** Encode a capability chain as a GNAP access-token `value` (self-contained, re-verified on use). */
+function encodeBoundToken(chain) {
+    return (0, pca_1.b64u)((0, pca_1.utf8)(JSON.stringify(chain)));
+}
+/** Structural guard: the required shape of a serialized capability hop (verifyChain re-checks crypto). */
+function isCapabilityShape(x) {
+    if (!isRecord(x))
+        return false;
+    return (typeof x.id === 'string' &&
+        typeof x.issuer === 'string' &&
+        typeof x.holder === 'string' &&
+        typeof x.body_digest === 'string' &&
+        typeof x.sig === 'string' &&
+        Array.isArray(x.caveats) &&
+        (x.parent === undefined || typeof x.parent === 'string') &&
+        (x.alg === undefined || typeof x.alg === 'string') &&
+        (x.pq_pk === undefined || typeof x.pq_pk === 'string') &&
+        (x.pq_sig === undefined || typeof x.pq_sig === 'string'));
+}
+/** Total, fail-closed decode of a bound token back into a capability chain (null on any deviation). */
+function decodeBoundToken(value) {
+    try {
+        const text = new TextDecoder('utf-8', { fatal: true }).decode((0, pca_1.unb64u)(value));
+        const parsed = (0, pca_1.strictParse)(text);
+        if (!Array.isArray(parsed))
+            return null;
+        const chain = [];
+        for (const hop of parsed) {
+            if (!isCapabilityShape(hop))
+                return null;
+            chain.push(hop);
+        }
+        return chain;
+    }
+    catch {
+        return null;
+    }
+}
+/** Render a (verified) PCA capability chain as a GNAP grant response with a bound access token. */
+function capabilityToGrantResponse(chain, opts = {}) {
+    if (!Array.isArray(chain) || chain.length === 0)
+        throw new GnapError('capabilityToGrantResponse: empty chain');
+    const leaf = chain[chain.length - 1];
+    const token = {
+        value: encodeBoundToken(chain),
+        access: grantedAccessOf(chain),
+        key: opts.bearer === true ? false : holderJwk(leaf.holder),
+        ...(opts.expiresIn !== undefined ? { expires_in: opts.expiresIn } : {}),
+        ...(opts.manageUri !== undefined ? { manage: { uri: opts.manageUri } } : {}),
+    };
+    return {
+        access_token: token,
+        ...(opts.continue !== undefined ? { continue: opts.continue } : {}),
+        ...(opts.instanceId !== undefined ? { instance_id: opts.instanceId } : {}),
+    };
+}
+/**
+ * Verify an incoming GNAP bound token, mapping it back to a PCA principal + capability. FAILS CLOSED:
+ * a token that is not a decodable chain, or whose chain does not verify (optionally against
+ * `expectedRootIssuer`), returns `{ ok:false }`. The `principal` is the chain's root issuer key.
+ */
+function verifyGnapToken(value, opts = {}) {
+    if (typeof value !== 'string' || value.length === 0)
+        return { ok: false, reason: 'token value is empty' };
+    const chain = decodeBoundToken(value);
+    if (chain === null || chain.length === 0)
+        return { ok: false, reason: 'token is not a decodable PCA capability chain' };
+    const vc = (0, pca_1.verifyChain)(chain, opts.expectedRootIssuer);
+    if (!vc.ok)
+        return { ok: false, reason: `capability chain invalid: ${vc.reason ?? 'unknown'}` };
+    const root = chain[0];
+    const leaf = chain[chain.length - 1];
+    return { ok: true, principal: root.issuer, capability: leaf, chain, access: grantedAccessOf(chain) };
+}
+const JWSD_TYP = 'gnap-binding-jwsd';
+function athOf(accessTokenValue) {
+    return (0, pca_1.b64u)((0, pca_1.sha256)((0, pca_1.utf8)(accessTokenValue)));
+}
+function toPlain(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function canonicalPayloadBytes(body) {
+    return (0, pca_1.utf8)((0, pca_1.canonicalizeStrict)(toPlain(body)));
+}
+/**
+ * Produce a GNAP `jwsd` detached-JWS proof over `body`, signed by the client key (via `jose`). The JWS
+ * payload is the canonical body; the compact detached form (payload omitted) is what travels in the
+ * `Detached-JWS` header. The signing key's public half IS the PCA holder the grant binds to.
+ */
+async function signGnapRequest(args) {
+    const created = args.created ?? Math.floor(Date.now() / 1000);
+    const holder = (0, pca_1.b64u)(args.key.publicKey);
+    const header = {
+        alg: 'EdDSA',
+        typ: JWSD_TYP,
+        htm: args.htm.toUpperCase(),
+        uri: args.uri,
+        created,
+        ...(args.kid !== undefined ? { kid: args.kid } : {}),
+        ...(args.accessTokenValue !== undefined ? { ath: athOf(args.accessTokenValue) } : {}),
+    };
+    const payload = canonicalPayloadBytes(args.body);
+    const privateJwk = { kty: 'OKP', crv: 'Ed25519', x: holder, d: (0, pca_1.b64u)(args.key.secretKey) };
+    const signingKey = await (0, jose_1.importJWK)(privateJwk, 'EdDSA');
+    // JWSHeaderParameters carries an index signature; copy the typed header into an object literal that
+    // satisfies it (GnapJwsdHeader is a closed interface and is not directly assignable).
+    const protectedHeader = {
+        alg: header.alg,
+        typ: header.typ,
+        htm: header.htm,
+        uri: header.uri,
+        created: header.created,
+        ...(header.kid !== undefined ? { kid: header.kid } : {}),
+        ...(header.ath !== undefined ? { ath: header.ath } : {}),
+    };
+    const jws = await new jose_1.FlattenedSign(payload).setProtectedHeader(protectedHeader).sign(signingKey);
+    return { detachedJws: `${jws.protected}..${jws.signature}`, header, holder };
+}
+/**
+ * Verify a GNAP `jwsd` detached-JWS proof (via `jose`) and bind the request to the holder key. FAILS
+ * CLOSED on any deviation: a bad signature, a tampered body, a wrong holder, a mismatched `htm`/`uri`,
+ * a stale/future `created`, or an `ath` that does not bind the named access token.
+ */
+async function verifyGnapRequest(args) {
+    const fail = (reason) => ({ ok: false, reason });
+    try {
+        const parts = args.detachedJws.split('.');
+        if (parts.length !== 3)
+            return fail('not a compact JWS (expected three dot-separated parts)');
+        const [protectedB64u, mid, signature] = parts;
+        if (protectedB64u === undefined || signature === undefined || mid !== '')
+            return fail('not a DETACHED compact JWS');
+        const holder = asEd25519(args.holder);
+        if (holder === null)
+            return fail('holder is not a canonical base64url Ed25519 public key');
+        const payloadB64u = jose_1.base64url.encode(canonicalPayloadBytes(args.body));
+        const verifyKey = await (0, jose_1.importJWK)({ kty: 'OKP', crv: 'Ed25519', x: holder }, 'EdDSA');
+        let header;
+        try {
+            const res = await (0, jose_1.flattenedVerify)({ protected: protectedB64u, payload: payloadB64u, signature }, verifyKey);
+            header = res.protectedHeader;
+        }
+        catch {
+            return fail('jwsd signature does not verify under the holder key (or body was tampered)');
+        }
+        if (header === undefined)
+            return fail('jwsd carries no protected header');
+        if (header.typ !== JWSD_TYP)
+            return fail('unexpected typ (not gnap-binding-jwsd)');
+        if (header.alg !== 'EdDSA')
+            return fail('unexpected alg (not EdDSA)');
+        const htm = header.htm;
+        if (typeof htm !== 'string' || htm.toUpperCase() !== args.htm.toUpperCase())
+            return fail('htm does not match the request method');
+        const uri = header.uri;
+        if (typeof uri !== 'string' || uri !== args.uri)
+            return fail('uri does not match the request target');
+        const created = header.created;
+        if (typeof created !== 'number' || !Number.isFinite(created))
+            return fail('missing or malformed created');
+        const nowSec = Math.floor((args.now ?? Date.now()) / 1000);
+        const maxAge = args.maxAgeSec ?? 300;
+        if (created > nowSec + 60)
+            return fail('created is in the future');
+        if (nowSec - created > maxAge)
+            return fail('jwsd proof is stale');
+        const ath = header.ath;
+        if (args.accessTokenValue !== undefined) {
+            if (typeof ath !== 'string' || ath !== athOf(args.accessTokenValue))
+                return fail('ath does not bind the named access token');
+        }
+        const out = {
+            alg: 'EdDSA',
+            typ: JWSD_TYP,
+            htm,
+            uri,
+            created,
+            ...(typeof header.kid === 'string' ? { kid: header.kid } : {}),
+            ...(typeof ath === 'string' ? { ath } : {}),
+        };
+        return { ok: true, holder, header: out };
+    }
+    catch {
+        return fail('malformed jwsd request');
+    }
+}
+/**
+ * Decide whether a grant request needs a continuation/step-up: it does when GNAP interaction is
+ * requested, when an explicit higher tier is asked for, or when (given the issuer's chain) the request
+ * asks for rights BEYOND the issuer's own authority — which can only be unlocked by a human/guardian
+ * co-signature, not minted by the agent alone.
+ */
+function gnapRequestRequiresStepUp(req, opts = {}) {
+    const beyond = [];
+    if (opts.issuerChain) {
+        const G = grantedAccessOf(opts.issuerChain);
+        for (const r of normalizeAccess(accessOf(req)))
+            if (!accessWithin(G, r))
+                beyond.push(r);
+    }
+    const interactRequested = req.interact !== undefined && Array.isArray(req.interact.start) && req.interact.start.length > 0;
+    const required = interactRequested || beyond.length > 0 || (opts.tier !== undefined && opts.tier > 1);
+    const tier = opts.tier ?? (beyond.length > 0 ? 3 : 2);
+    const reason = !required
+        ? 'no step-up required'
+        : beyond.length > 0
+            ? `requested rights exceed the issuer's authority (${beyond.length} right(s) beyond)`
+            : interactRequested
+                ? 'GNAP interaction requested'
+                : `tier ${tier} step-up required`;
+    return { required, reason, beyond, tier };
+}
+/** Begin a GNAP continuation: emit the `continue` handle + the PCA step-up it resolves through. */
+function beginGnapContinuation(args) {
+    const cont = {
+        uri: args.continueUri,
+        access_token: { value: args.continueToken, bound: true },
+        ...(args.wait !== undefined ? { wait: args.wait } : {}),
+    };
+    return {
+        response: { continue: cont },
+        stepUp: {
+            tier: args.tier,
+            t: args.t,
+            signerSet: args.signerSet,
+            reason: args.reason ?? `tier ${args.tier} co-signature required to continue`,
+            continueToken: args.continueToken,
+        },
+    };
+}
+/**
+ * Produce one role's step-up co-signature share over the action's PCActn — the co-signature a
+ * guardian/principal device returns through the GNAP continuation. For 'guardian'/'principal' it binds
+ * the signer set + `t` (replay-safe); the 'agent' share is the PCActn's own leaf signature.
+ */
+function gnapStepUpShare(body, role, secret, signerSet, t) {
+    return (0, pca_1.signShare)(role, secret, (0, pca_1.thresholdMessage)(body), { signerSet, t });
+}
+/**
+ * Resolve a continuation: build the action's PCActn (agent leaf signature) and FOLD the step-up
+ * co-signatures into its `threshold`, then verify the threshold `t` is reached. This is the concrete
+ * realization of "a grant that needs more authority continues via a step-up co-signature folded into
+ * the PCActn" — the multi-signature carrier; a FROST aggregate share slots in the same `agent`/group
+ * position without changing the property.
+ */
+function completeGnapContinuation(args) {
+    if (!Array.isArray(args.chain) || args.chain.length === 0)
+        throw new GnapError('completeGnapContinuation: empty chain');
+    const pcactn = (0, pca_1.buildPCActn)({
+        grant: args.grant,
+        chain: args.chain,
+        plan: args.plan,
+        nodeId: args.nodeId,
+        counter: args.counter,
+        signerSecret: args.agentLeafSecret,
+        aud: args.aud,
+        ...(args.params !== undefined ? { params: args.params } : {}),
+        ...(args.now !== undefined ? { now: args.now } : {}),
+        ...(args.ttlMs !== undefined ? { ttlMs: args.ttlMs } : {}),
+    });
+    const message = (0, pca_1.thresholdMessage)(pcactn);
+    // The agent's vote is a role-bound share like every other (a bare leaf signature is valid under any signer set / t and is rejected).
+    const agentShare = (0, pca_1.signShare)('agent', args.agentLeafSecret, message, { signerSet: args.signerSet, t: args.t });
+    const cosignShares = args.cosignSecrets.map((cs) => (0, pca_1.signShare)(cs.role, cs.secret, message, { signerSet: args.signerSet, t: args.t }));
+    const threshold = (0, pca_1.assembleThreshold)([agentShare, ...cosignShares]);
+    const verdict = (0, pca_1.verifyThreshold)(threshold, message, args.signerSet, args.t);
+    return { pcactn: { ...pcactn, threshold }, threshold, verdict };
+}
+/** The machine-readable Agent-GNAP profile spec (see the module header for the full narrative). */
+exports.AGENT_GNAP_PROFILE = {
+    name: 'agent-gnap',
+    version: '1.0',
+    rfc: 'RFC 9635',
+    summary: 'A GNAP profile for autonomous-agent delegation: each A2A hop is a GNAP grant whose authority is ' +
+        'issued as an attenuated, key-bound PCA capability, never wider than the issuing agent.',
+    mapping: [
+        { gnap: 'access[].type', pca: 'predicate resource namespace gnap:<type>:<location>', note: 'the resource family the rights live in' },
+        { gnap: 'access[].actions', pca: 'predicate.verb (list, or * for any)', note: 'the operations permitted' },
+        { gnap: 'access[].locations', pca: 'predicate.resource (exact or trailing-* prefix)', note: 'the resource targets' },
+        { gnap: 'access[].datatypes / identifier', pca: "predicate.where on action.params.*", note: 'value-level constraints' },
+        { gnap: 'client.key.jwk (OKP/Ed25519)', pca: 'capability.holder (cnf-bound key)', note: 'the proof-of-possession key' },
+        { gnap: 'grant request (no prior grant)', pca: 'mintGrant → root capability', note: 'envelope predicates = requested access' },
+        { gnap: 'grant request (delegated hop)', pca: 'delegate → child capability + gnap_access caveat', note: 'append-only attenuation' },
+        { gnap: 'access_token (§3.2)', pca: 'a verifiable PCA capability chain (encodeBoundToken)', note: 'bound, self-verifying token' },
+        { gnap: 'continue (§3.1) + interact (§3.3)', pca: 'PCA step-up: FROST/threshold co-signature folded into a PCActn', note: 'tier-2/3 escalation' },
+        { gnap: 'jwsd detached JWS (§7.3.4)', pca: 'request proof binding the body to capability.holder', note: 'verified with jose' },
+    ],
+    proofMethods: ['jwsd'],
+    multiHop: 'An A2A task is a chain of GNAP grants. Each hop delegates from the issuing agent to the next, ' +
+        'recording its (clamped) rights as an append-only gnap_access caveat. Effective authority is the ' +
+        'intersection of the root policy envelope and every hop; PCA caveats are conjunctive and ' +
+        'append-only, so no hop can widen — "never wider than the issuer" holds across any depth.',
+    stepUp: 'A request for authority beyond the issuer (or an explicit interaction) returns a GNAP continue ' +
+        'handle instead of a token. The client returns with the action PCActn plus a guardian/principal ' +
+        'co-signature, which is folded into the PCActn threshold and verified at tier 2/3 (FROST or ' +
+        'multi-signature) before the action is admitted.',
+    security: [
+        'Attenuation is structural and append-only: a delegated hop can only ever narrow authority.',
+        'Every grant is key-bound (cnf): the holder key must prove possession via a jwsd detached JWS.',
+        'All verification fails closed: bad token, broken chain, bad proof, stale request, or out-of-scope action denies.',
+        'Rights beyond the issuer are clamped at issue time and denied at action time (defense in depth).',
+        'Elevation beyond the agent requires a human/guardian co-signature, not a self-minted grant.',
+    ],
+};
+//# sourceMappingURL=index.js.map