/** * @fileoverview Audience-binding verification primitives. * * ── PROOF BOX ────────────────────────────────────────────────────────────── * What a passing audience check PROVES: * The issuer named this relying party (by its `recipientId`) among the * intended recipients of the proof. A proof minted for recipient A is * rejected when checked against recipient B. * * What it does NOT prove: * - It does NOT prove the proof is otherwise valid. Audience is one facet; * the signature, freshness, scope, and revocation checks are separate and * must all pass independently. * - It does NOT prevent a NAMED recipient from misusing what it legitimately * received. Audience binding restricts WHO may present a proof, not what a * legitimate holder does with it afterward. * - It is NOT an assurance scalar. The status is a mechanical fact about * recipient-identifier membership, derived by the verifier from its own * policy, never read from the proof. * ─────────────────────────────────────────────────────────────────────────── * * The membership algorithm reuses the array-normalize + `includes` pattern * already established by jwtSvidToDidInput in src/adapters/oauth-rfc8693, and * the `expectedAudience`/`recipientId` naming so request-level and proof-level * audience reads consistently across the SDK. */ import type { AudienceBinding, AudienceCheckResult, AudiencePolicy } from './types.js'; /** * A proof object that may carry an additive `aud` binding. Both V2Delegation * and BilateralReceipt structurally satisfy this once their optional `aud` * slot is populated; this interface keeps the primitive decoupled from either * concrete proof type. */ export interface AudienceBearer { aud?: AudienceBinding; } /** * Normalize an audience value to a recipient-id array, mirroring the OAuth * adapter's `Array.isArray(claims.aud) ? claims.aud : [claims.aud]` shape. * Returns null when the binding is malformed (absent recipients, empty set, * or a non-string member). Callers treat null as `audience_malformed`. */ export declare function normalizeRecipients(aud: AudienceBinding | undefined): string[] | null; /** * Membership test: is `recipientId` among the proof's named recipients? Reuses * the same normalize-then-`includes` membership check as the OAuth adapter's * expectedAudience path. Returns false for a malformed or absent binding. */ export declare function matchAudience(aud: AudienceBinding | undefined, recipientId: string): boolean; /** * Evaluate the audience facet of a proof against a relying-party policy. * * Returns a four-valued result consistent with the Belnap ConstraintStatus * lattice. The mapping: * - bound + member → pass / audience_match * - bound + not a member → fail / audience_mismatch * - bound + malformed → fail / audience_malformed * - unbound + required → fail / audience_required_absent * - unbound + not required → not_applicable / audience_unbound * - no recipientId in policy → unknown / audience_unknown * * Fail-closed: any malformed binding is a failure, never a silent pass. */ export declare function checkAudience(proof: AudienceBearer, policy: AudiencePolicy): AudienceCheckResult; /** * Construct an audience binding for the given recipient(s). A convenience * builder so issuers attach a well-formed, versioned slot. Throws on an empty * recipient set so a meaningless binding is never minted. */ export declare function bindAudience(recipients: string | string[]): AudienceBinding; //# sourceMappingURL=verify.d.ts.map