@adcp/sdk 16.1.0 → 16.2.0

package/dist/lib/governance/authorization.d.mts

@@ -12,7 +12,9 @@ import type { CheckGovernanceRequest, GovernancePhase, PlannedDelivery } from '.
 import type { JwksResolver } from '../signing/jwks.mjs';
 import type { ReplayStore } from '../signing/replay.mjs';
 import type { RevocationStore } from '../signing/revocation.mjs';
+import type { RevocationDetail } from '../identity-3.3/types.mjs';
 import { type HttpsJwksResolverOptions } from '../signing/jwks-https.mjs';
+import { type GovernanceKeyArchiveResolver, type JwsArtifactWebBotAuthOptions } from '../identity-3.3/jws-artifacts.mjs';
 export declare const GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS: readonly ["authorized_commitment", "authorized_task", "authorized_payload_hash"];
 export type GovernanceAuthorizationCriticalClaim = (typeof GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS)[number];
 export type GovernanceEnforcementMode = 'signed_context' | 'online_execution_check';
@@ -51,6 +53,12 @@ export interface GovernanceAuthorizationFailure {
     ok: false;
     error: GovernanceAuthorizationErrorCode;
     message: string;
+    /**
+     * Set when the failure is an outage (an issuer trust record, key directory,
+     * archive or revocation list could not be read), not a verdict on the
+     * token: the same token may verify on retry.
+     */
+    retryable?: true;
 }
 export type GovernanceAuthorizationResult = GovernanceAuthorizationSuccess | GovernanceAuthorizationFailure;
 export interface GovernanceReplayStore {
@@ -127,6 +135,18 @@ export interface VerifyGovernanceAuthorizationOptions {
     jwks?: JwksResolver;
     /** When supplied, discover keys from this exact authenticated buyer record. */
     buyerIdentity?: GovernanceBuyerIdentity;
+    /**
+     * AdCP 3.3 (`specs/agent-identity-3-3.md` R4): when the trust record derived
+     * from the issuer's origin lists that origin, verify the token with a key
+     * from the origin's Web Bot Auth key directory (`alg` `EdDSA`, `kid` the
+     * key's JWK thumbprint, no `use`/`key_ops`/`adcp_use` checks) and check
+     * revocation against the origin's list, never under the 3.2 profile. A
+     * trust-record fetch failure rejects the token; it never falls back to 3.2.
+     * An issuer no trust record lists stays on the 3.2 profile (`jwks` or
+     * `buyerIdentity`). Every other check is unchanged, including the
+     * `buyerIdentity` cross-check that the issuer is the buyer's governance agent.
+     */
+    webBotAuth?: JwsArtifactWebBotAuthOptions;
     replayStore: GovernanceReplayStore;
     /** Optional governance-key revocation source. */
     revocationStore?: RevocationStore;
@@ -187,6 +207,52 @@ export declare function targetDeclaresGovernanceEnforcement(capabilities: unknow
 export declare function targetDeclaresLegacyGovernanceAwareness(capabilities: unknown, task: string): boolean;
 /** Verify the published compact-JWS authorization profile and all service bindings. */
 export declare function verifyGovernanceAuthorization(options: VerifyGovernanceAuthorizationOptions): Promise<GovernanceAuthorizationResult>;
+export interface VerifyHistoricalGovernanceContextOptions {
+    token: unknown;
+    /** The governance agent the verifier expected to sign, from its own records. */
+    expectedIssuer: string;
+    /**
+     * The WBA components plus the governance key archive at the issuer's
+     * origin (`{origin}/.well-known/jwks-archive.json`, `security.mdx`
+     * §Revocation), which holds keys rotated out of the directory.
+     */
+    webBotAuth: JwsArtifactWebBotAuthOptions & {
+        archive: GovernanceKeyArchiveResolver;
+    };
+}
+export type HistoricalGovernanceContextResult = {
+    ok: true;
+    claims: GovernanceAuthorizationClaims;
+    protectedHeader: Record<string, unknown>;
+    /** The key was in the issuer's current directory, or only in its archive. */
+    keySource: 'directory' | 'archive';
+    /**
+     * The issuer origin's revocation status for the signing key: `current`
+     * (listed, not revoked), `absent` (the origin serves no list) or
+     * `revoked`. Online verification rejects every token a revoked key
+     * signed; an audit decides what a revocation means for a retained token
+     * from its detail (R9: only `keyCompromise` exposes, from its
+     * `invalidity_date`).
+     */
+    revocation: 'current' | 'absent' | 'revoked';
+    revocationDetail?: RevocationDetail;
+} | (GovernanceAuthorizationFailure & {
+    /** Set when the issuer is on the 3.2 profile, which this function does not verify. */
+    profile?: '3.2';
+});
+/**
+ * Historical (audit) verification of a retained governance context from a
+ * Web Bot Auth identity (R4): the key comes from the issuer origin's key
+ * directory or, once rotated out, from its governance key archive. Checks the
+ * token's shape, `typ`, `crit`, issuer, `alg` `EdDSA`, `kid` thumbprint and
+ * signature, and reports the origin's revocation status and detail for the
+ * key instead of rejecting a revoked one. It does not check expiry, audience,
+ * replay or the request binding, which only an online verification can.
+ *
+ * Profile selection is the same as online: an issuer whose origin no trust
+ * record lists is on the 3.2 profile, reported as `profile: '3.2'`.
+ */
+export declare function verifyHistoricalGovernanceContext(options: VerifyHistoricalGovernanceContextOptions): Promise<HistoricalGovernanceContextResult>;
 export declare class GovernanceAuthorizationError extends Error {
     readonly code: GovernanceAuthorizationErrorCode;
     constructor(result: GovernanceAuthorizationFailure);

package/dist/lib/governance/authorization.d.ts

@@ -12,7 +12,9 @@ import type { CheckGovernanceRequest, GovernancePhase, PlannedDelivery } from '.
 import type { JwksResolver } from '../signing/jwks';
 import type { ReplayStore } from '../signing/replay';
 import type { RevocationStore } from '../signing/revocation';
+import type { RevocationDetail } from '../identity-3.3/types';
 import { type HttpsJwksResolverOptions } from '../signing/jwks-https';
+import { type GovernanceKeyArchiveResolver, type JwsArtifactWebBotAuthOptions } from '../identity-3.3/jws-artifacts';
 export declare const GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS: readonly ["authorized_commitment", "authorized_task", "authorized_payload_hash"];
 export type GovernanceAuthorizationCriticalClaim = (typeof GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS)[number];
 export type GovernanceEnforcementMode = 'signed_context' | 'online_execution_check';
@@ -51,6 +53,12 @@ export interface GovernanceAuthorizationFailure {
     ok: false;
     error: GovernanceAuthorizationErrorCode;
     message: string;
+    /**
+     * Set when the failure is an outage (an issuer trust record, key directory,
+     * archive or revocation list could not be read), not a verdict on the
+     * token: the same token may verify on retry.
+     */
+    retryable?: true;
 }
 export type GovernanceAuthorizationResult = GovernanceAuthorizationSuccess | GovernanceAuthorizationFailure;
 export interface GovernanceReplayStore {
@@ -127,6 +135,18 @@ export interface VerifyGovernanceAuthorizationOptions {
     jwks?: JwksResolver;
     /** When supplied, discover keys from this exact authenticated buyer record. */
     buyerIdentity?: GovernanceBuyerIdentity;
+    /**
+     * AdCP 3.3 (`specs/agent-identity-3-3.md` R4): when the trust record derived
+     * from the issuer's origin lists that origin, verify the token with a key
+     * from the origin's Web Bot Auth key directory (`alg` `EdDSA`, `kid` the
+     * key's JWK thumbprint, no `use`/`key_ops`/`adcp_use` checks) and check
+     * revocation against the origin's list, never under the 3.2 profile. A
+     * trust-record fetch failure rejects the token; it never falls back to 3.2.
+     * An issuer no trust record lists stays on the 3.2 profile (`jwks` or
+     * `buyerIdentity`). Every other check is unchanged, including the
+     * `buyerIdentity` cross-check that the issuer is the buyer's governance agent.
+     */
+    webBotAuth?: JwsArtifactWebBotAuthOptions;
     replayStore: GovernanceReplayStore;
     /** Optional governance-key revocation source. */
     revocationStore?: RevocationStore;
@@ -187,6 +207,52 @@ export declare function targetDeclaresGovernanceEnforcement(capabilities: unknow
 export declare function targetDeclaresLegacyGovernanceAwareness(capabilities: unknown, task: string): boolean;
 /** Verify the published compact-JWS authorization profile and all service bindings. */
 export declare function verifyGovernanceAuthorization(options: VerifyGovernanceAuthorizationOptions): Promise<GovernanceAuthorizationResult>;
+export interface VerifyHistoricalGovernanceContextOptions {
+    token: unknown;
+    /** The governance agent the verifier expected to sign, from its own records. */
+    expectedIssuer: string;
+    /**
+     * The WBA components plus the governance key archive at the issuer's
+     * origin (`{origin}/.well-known/jwks-archive.json`, `security.mdx`
+     * §Revocation), which holds keys rotated out of the directory.
+     */
+    webBotAuth: JwsArtifactWebBotAuthOptions & {
+        archive: GovernanceKeyArchiveResolver;
+    };
+}
+export type HistoricalGovernanceContextResult = {
+    ok: true;
+    claims: GovernanceAuthorizationClaims;
+    protectedHeader: Record<string, unknown>;
+    /** The key was in the issuer's current directory, or only in its archive. */
+    keySource: 'directory' | 'archive';
+    /**
+     * The issuer origin's revocation status for the signing key: `current`
+     * (listed, not revoked), `absent` (the origin serves no list) or
+     * `revoked`. Online verification rejects every token a revoked key
+     * signed; an audit decides what a revocation means for a retained token
+     * from its detail (R9: only `keyCompromise` exposes, from its
+     * `invalidity_date`).
+     */
+    revocation: 'current' | 'absent' | 'revoked';
+    revocationDetail?: RevocationDetail;
+} | (GovernanceAuthorizationFailure & {
+    /** Set when the issuer is on the 3.2 profile, which this function does not verify. */
+    profile?: '3.2';
+});
+/**
+ * Historical (audit) verification of a retained governance context from a
+ * Web Bot Auth identity (R4): the key comes from the issuer origin's key
+ * directory or, once rotated out, from its governance key archive. Checks the
+ * token's shape, `typ`, `crit`, issuer, `alg` `EdDSA`, `kid` thumbprint and
+ * signature, and reports the origin's revocation status and detail for the
+ * key instead of rejecting a revoked one. It does not check expiry, audience,
+ * replay or the request binding, which only an online verification can.
+ *
+ * Profile selection is the same as online: an issuer whose origin no trust
+ * record lists is on the 3.2 profile, reported as `profile: '3.2'`.
+ */
+export declare function verifyHistoricalGovernanceContext(options: VerifyHistoricalGovernanceContextOptions): Promise<HistoricalGovernanceContextResult>;
 export declare class GovernanceAuthorizationError extends Error {
     readonly code: GovernanceAuthorizationErrorCode;
     constructor(result: GovernanceAuthorizationFailure);

package/dist/lib/governance/authorization.js

@@ -35,7 +35,8 @@ __export(authorization_exports, {
   governanceTaskRequiresProposedCommitment: () => governanceTaskRequiresProposedCommitment,
   targetDeclaresGovernanceEnforcement: () => targetDeclaresGovernanceEnforcement,
   targetDeclaresLegacyGovernanceAwareness: () => targetDeclaresLegacyGovernanceAwareness,
-  verifyGovernanceAuthorization: () => verifyGovernanceAuthorization
+  verifyGovernanceAuthorization: () => verifyGovernanceAuthorization,
+  verifyHistoricalGovernanceContext: () => verifyHistoricalGovernanceContext
 });
 module.exports = __toCommonJS(authorization_exports);
 var import_node_crypto = require("node:crypto");
@@ -44,11 +45,18 @@ var import_jcs = require('../utils/jcs.js');
 var import_jwks_https = require('../signing/jwks-https.js');
 var import_select_agent = require('../signing/agent-resolver/select-agent.js');
 var import_strict_json = require('../signing/agent-resolver/strict-json.js');
+var import_jws_artifacts = require('../identity-3.3/jws-artifacts.js');
 const GOVERNANCE_AUTHORIZATION_CRITICAL_CLAIMS = Object.freeze([
   "authorized_commitment",
   "authorized_task",
   "authorized_payload_hash"
 ]);
+const GOVERNANCE_JWS_TYP = "adcp-gov+jws";
+const GOVERNANCE_CRIT = {
+  authorized_commitment: true,
+  authorized_task: true,
+  authorized_payload_hash: true
+};
 class GovernanceReplayStoreAdapter {
   constructor(replayStore) {
     this.replayStore = replayStore;
@@ -282,27 +290,19 @@ function targetDeclaresLegacyGovernanceAwareness(capabilities, task) {
   const mediaBuy = isRecord(root?.media_buy) ? root.media_buy : void 0;
   return mediaBuy?.governance_aware === true;
 }
-async function verifyGovernanceAuthorization(options) {
+function parseGovernanceJws(token, expectedIssuer) {
   const reject = (error, message) => ({
     ok: false,
     error,
     message
   });
-  if (!options.authenticatedCaller) {
-    return reject("governance_token_invalid", "Authenticated caller is required");
-  }
-  try {
-    buildGovernanceCommitment(options.actualCommitment.amount, options.actualCommitment.currency);
-  } catch (error) {
-    return reject("governance_token_invalid", error.message);
-  }
-  if (typeof options.token !== "string" || options.token.length === 0) {
+  if (typeof token !== "string" || token.length === 0) {
     return reject("governance_token_invalid", "governance_context is required");
   }
-  if (options.token.length > 4096) {
+  if (token.length > 4096) {
     return reject("governance_token_invalid", "governance_context exceeds the protocol size limit");
   }
-  const parts = options.token.split(".");
+  const parts = token.split(".");
   if (parts.length !== 3 || parts.some((part) => !part || !/^[A-Za-z0-9_-]+$/.test(part))) {
     return reject("governance_token_invalid", "governance_context is not a compact JWS");
   }
@@ -315,7 +315,7 @@ async function verifyGovernanceAuthorization(options) {
   if (alg !== "EdDSA" && alg !== "ES256") {
     return reject("governance_token_invalid", "Unsupported governance JWS algorithm");
   }
-  if (protectedHeader.typ !== "adcp-gov+jws") {
+  if (protectedHeader.typ !== GOVERNANCE_JWS_TYP) {
     return reject("governance_token_invalid", "Invalid governance JWS typ");
   }
   const critical = protectedHeader.crit;
@@ -343,35 +343,71 @@ async function verifyGovernanceAuthorization(options) {
   try {
     if (typeof decodedClaims.iss !== "string") throw new TypeError("Missing issuer");
     canonicalIssuer = (0, import_select_agent.canonicalAgentUrl)(decodedClaims.iss);
-    if (canonicalIssuer !== (0, import_select_agent.canonicalAgentUrl)(options.expectedIssuer)) throw new TypeError("Issuer mismatch");
+    if (canonicalIssuer !== (0, import_select_agent.canonicalAgentUrl)(expectedIssuer)) throw new TypeError("Issuer mismatch");
   } catch {
     return reject("governance_token_invalid", "Governance token issuer mismatch");
   }
-  const kid = typeof protectedHeader.kid === "string" ? protectedHeader.kid : "";
-  if (!kid) return reject("governance_key_unknown", "Governance signing kid is missing");
-  let jwk;
+  return { ok: true, token, protectedHeader, decodedClaims, canonicalIssuer, alg };
+}
+async function verifyGovernanceAuthorization(options) {
+  const reject = (error, message) => ({
+    ok: false,
+    error,
+    message
+  });
+  if (!options.authenticatedCaller) {
+    return reject("governance_token_invalid", "Authenticated caller is required");
+  }
   try {
-    const resolver = options.buyerIdentity ? createGovernanceAgentJwksResolver(canonicalIssuer, options.buyerIdentity) : options.jwks;
-    if (!resolver) return reject("governance_key_unknown", "No governance key resolver or buyer identity configured");
-    jwk = await resolver.resolve(kid);
-  } catch {
-    return reject("governance_key_unknown", "Governance signing key could not be resolved");
+    buildGovernanceCommitment(options.actualCommitment.amount, options.actualCommitment.currency);
+  } catch (error) {
+    return reject("governance_token_invalid", error.message);
   }
-  if (!jwk || jwk.adcp_use !== "governance-signing" || jwk.use !== "sig" || !jwk.key_ops?.includes("verify") || jwk.alg !== void 0 && jwk.alg !== alg) {
-    return reject("governance_key_unknown", "Governance signing key is unknown or not authorized");
+  const parsed = parseGovernanceJws(options.token, options.expectedIssuer);
+  if (!parsed.ok) return parsed;
+  const { protectedHeader, decodedClaims, canonicalIssuer, alg } = parsed;
+  const kid = typeof protectedHeader.kid === "string" ? protectedHeader.kid : "";
+  if (!kid) return reject("governance_key_unknown", "Governance signing kid is missing");
+  let profile;
+  if (options.webBotAuth) {
+    try {
+      profile = await (0, import_jws_artifacts.selectJwsArtifactProfile)(options.expectedIssuer, options.webBotAuth.trust);
+    } catch {
+      return { ...reject("governance_key_unknown", "Governance issuer trust record is unavailable"), retryable: true };
+    }
   }
-  try {
-    const key = await (0, import_jose.importJWK)(jwk, alg);
-    await (0, import_jose.compactVerify)(options.token, key, {
-      algorithms: [alg],
-      crit: {
-        authorized_commitment: true,
-        authorized_task: true,
-        authorized_payload_hash: true
+  if (profile?.profile === "web-bot-auth") {
+    if (options.buyerIdentity) {
+      try {
+        const record = (0, import_select_agent.relyingPartyAgentRecord)(options.buyerIdentity.brandJson, options.buyerIdentity.brandDomain);
+        (0, import_select_agent.selectAgentByUrl)(record, canonicalIssuer, { agentType: "governance" });
+      } catch {
+        return reject("governance_key_unknown", "Governance issuer is not the buyer's governance agent");
       }
-    });
-  } catch {
-    return reject("governance_token_invalid", "Governance token signature verification failed");
+    }
+    const failure = await verifyGovernanceJwsOnWebBotAuth(options.token, profile.origin, options.webBotAuth);
+    if (failure) return failure;
+  } else {
+    let jwk;
+    try {
+      const resolver = options.buyerIdentity ? createGovernanceAgentJwksResolver(canonicalIssuer, options.buyerIdentity) : options.jwks;
+      if (!resolver) return reject("governance_key_unknown", "No governance key resolver or buyer identity configured");
+      jwk = await resolver.resolve(kid);
+    } catch {
+      return reject("governance_key_unknown", "Governance signing key could not be resolved");
+    }
+    if (!jwk || jwk.adcp_use !== "governance-signing" || jwk.use !== "sig" || !jwk.key_ops?.includes("verify") || jwk.alg !== void 0 && jwk.alg !== alg) {
+      return reject("governance_key_unknown", "Governance signing key is unknown or not authorized");
+    }
+    try {
+      const key = await (0, import_jose.importJWK)(jwk, alg);
+      await (0, import_jose.compactVerify)(options.token, key, {
+        algorithms: [alg],
+        crit: GOVERNANCE_CRIT
+      });
+    } catch {
+      return reject("governance_token_invalid", "Governance token signature verification failed");
+    }
   }
   try {
     if (options.revocationStore && await options.revocationStore.isRevoked(kid)) {
@@ -529,6 +565,113 @@ async function verifyGovernanceAuthorization(options) {
     payloadHash
   };
 }
+function governanceFailureFromJwsArtifact(error) {
+  if (!(error instanceof import_jws_artifacts.JwsArtifactError))
+    return {
+      ok: false,
+      error: "governance_key_unknown",
+      message: "Governance signing key could not be resolved",
+      retryable: true
+    };
+  switch (error.code) {
+    case "jws_key_revoked":
+      return { ok: false, error: "governance_token_revoked", message: "Governance signing key is revoked" };
+    case "jws_revocation_unavailable":
+      return {
+        ok: false,
+        error: "governance_token_revoked",
+        message: "Governance revocation status could not be established",
+        retryable: true
+      };
+    case "jws_invalid":
+      return {
+        ok: false,
+        error: "governance_token_invalid",
+        message: `Governance token verification failed: ${error.message}`
+      };
+    case "jws_key_unavailable":
+      return {
+        ok: false,
+        error: "governance_key_unknown",
+        message: "Governance signing key could not be resolved",
+        retryable: true
+      };
+    default:
+      return { ok: false, error: "governance_key_unknown", message: "Governance signing key could not be resolved" };
+  }
+}
+const NO_ORIGIN_REVOCATION = Object.freeze({
+  ok: false,
+  error: "governance_token_revoked",
+  message: "No origin revocation source is configured for the Web Bot Auth path"
+});
+async function verifyGovernanceJwsOnWebBotAuth(token, origin, webBotAuth) {
+  if (!webBotAuth.revocation) return { ...NO_ORIGIN_REVOCATION };
+  try {
+    await (0, import_jws_artifacts.verifyWebBotAuthJwsArtifact)(token, origin, {
+      typ: GOVERNANCE_JWS_TYP,
+      directory: webBotAuth.directory,
+      revocation: webBotAuth.revocation,
+      // A governance context authorizes spend: an origin that serves no list fails closed.
+      revocationAbsent: "reject",
+      crit: GOVERNANCE_CRIT
+    });
+    return void 0;
+  } catch (error) {
+    return governanceFailureFromJwsArtifact(error);
+  }
+}
+async function verifyHistoricalGovernanceContext(options) {
+  const parsed = parseGovernanceJws(options.token, options.expectedIssuer);
+  if (!parsed.ok) return parsed;
+  if (parsed.alg !== "EdDSA")
+    return {
+      ok: false,
+      error: "governance_token_invalid",
+      message: "A Web Bot Auth governance context uses alg EdDSA"
+    };
+  if (!options.webBotAuth.revocation) return { ...NO_ORIGIN_REVOCATION };
+  let profile;
+  try {
+    profile = await (0, import_jws_artifacts.selectJwsArtifactProfile)(options.expectedIssuer, options.webBotAuth.trust);
+  } catch {
+    return {
+      ok: false,
+      error: "governance_key_unknown",
+      message: "Governance issuer trust record is unavailable",
+      retryable: true
+    };
+  }
+  if (profile.profile !== "web-bot-auth")
+    return {
+      ok: false,
+      error: "governance_key_unknown",
+      message: "Governance issuer is on the 3.2 profile; its trust record does not list its origin",
+      profile: "3.2"
+    };
+  try {
+    const verified = await (0, import_jws_artifacts.verifyWebBotAuthJwsArtifact)(parsed.token, profile.origin, {
+      typ: GOVERNANCE_JWS_TYP,
+      directory: options.webBotAuth.directory,
+      archive: options.webBotAuth.archive,
+      revocation: options.webBotAuth.revocation,
+      // No spend rides on an audit: an origin that serves no list has revoked nothing.
+      revocationAbsent: "accept",
+      revokedKey: "report",
+      crit: GOVERNANCE_CRIT
+    });
+    return {
+      ok: true,
+      claims: parsed.decodedClaims,
+      protectedHeader: parsed.protectedHeader,
+      keySource: verified.keySource,
+      revocation: verified.revocation,
+      ...verified.revocationDetail ? { revocationDetail: verified.revocationDetail } : {}
+    };
+  } catch (error) {
+    return governanceFailureFromJwsArtifact(error);
+  }
+}
 class GovernanceAuthorizationError extends Error {
   code;
   constructor(result) {
@@ -585,5 +728,6 @@ function decodeJsonObject(segment) {
   governanceTaskRequiresProposedCommitment,
   targetDeclaresGovernanceEnforcement,
   targetDeclaresLegacyGovernanceAwareness,
-  verifyGovernanceAuthorization
+  verifyGovernanceAuthorization,
+  verifyHistoricalGovernanceContext
 });