@registrystack/client 0.30.0 → 0.32.0

package/README.md

@@ -79,6 +79,14 @@ mutation automatically. See
 [Exact JSON in Node](https://docs.registrystack.org/reference/client-api/#exact-json-in-node)
 for the full rules.
 
+`breg.verifyWebhookDelivery({ method, path, headers, body, key })` authenticates
+the exact bytes of one Version 1 webhook delivery. The result returns
+`deliveryTime` and `idempotencyKey`; the receiver must bound clock skew and
+deduplicate once-only effects on authenticated `source` plus `id`, or on an
+application business key. See
+[Verify a webhook delivery](https://docs.registrystack.org/reference/client-api/#verify-a-webhook-delivery)
+for a receiver example.
+
 ## Versioning
 
 Install the exact client version that matches the deployment. The unified

package/breg/client.d.ts

@@ -7,6 +7,41 @@ export type JsonObject = { readonly [key: string]: JsonValue }
 /** An integer that satisfies `Number.isSafeInteger` and the option's documented bounds. */
 export type SafeInteger = number
 
+export type WebhookVerificationRefusalCode =
+  | 'missing_header'
+  | 'malformed_signature'
+  | 'signature_mismatch'
+  | 'unsupported_version'
+
+export interface WebhookDeliveryInput {
+  method: string
+  path: string
+  headers: Readonly<Record<string, string>>
+  /** Exact bytes in a non-shared backing store. */
+  body: Buffer
+  /** Secret bytes in a non-shared backing store. */
+  key: Buffer
+}
+
+export interface VerifiedWebhookDelivery {
+  readonly id: string
+  readonly source: string
+  readonly type: string
+  readonly time: string
+  readonly dataschema: string
+  readonly generation: string
+  readonly attempt: string
+  readonly deliveryTime: string
+  readonly idempotencyKey: string
+  readonly body: Buffer
+}
+
+/**
+ * Authenticate one exact Base Registry Engine Version 1 webhook delivery.
+ * Apply delivery-time skew and idempotency policy before acting on the body.
+ */
+export declare function verifyWebhookDelivery(input: WebhookDeliveryInput): VerifiedWebhookDelivery
+
 export interface PrivateJwk {
   readonly kty: string
   readonly kid: string
@@ -18,7 +53,23 @@ export interface PrivateKeyJwtConfig {
   tokenEndpoint: string
   clientId: string
   clientKey: PrivateJwk
+  /**
+   * The audience of the client assertion (who checks the client's
+   * authentication). Defaults to the token endpoint URL. This is not the
+   * `resource` of the token request.
+   */
   audience?: string | null
+  /**
+   * The RFC 8707 resource indicator the token is requested for: the resource
+   * server's registered identifier, not a URL to fetch.
+   */
+  resource?: string | null
+  /**
+   * The scopes requested for the token, sent as one space-delimited `scope`
+   * parameter. A requested scope may narrow the client's registered
+   * permission set; it can never widen it.
+   */
+  scopes?: ReadonlyArray<string> | null
   assertionLifetimeSeconds?: SafeInteger | null
   refreshMarginSeconds?: SafeInteger | null
   requestTimeoutMilliseconds?: SafeInteger | null
@@ -27,9 +78,56 @@ export interface PrivateKeyJwtConfig {
   trustedRootCertificates?: string | null
 }
 
+/** OAuth credentials are returned to the caller. Keep them out of logs and persistence. */
+export class PrivateKeyJwt {
+  constructor(config: PrivateKeyJwtConfig)
+  /** Fresh RFC 8693 exchange. Requires resource and scopes; never shares the service cache. */
+  exchange(subjectToken: string): Promise<string>
+  /** Client credentials with the shared provider's bounded service-token cache. */
+  bearerToken(): Promise<string>
+}
+
+/** One immutable verified person or grant context. Reconstruct after host source facts change. */
+export interface ExchangeContext {
+  issuer: string
+  subject: string
+  audience: string
+  generation: string
+  deadlineSeconds: SafeInteger
+  grantId?: string | null
+}
+
+export type ExchangePrivateKeyJwtConfig = PrivateKeyJwtConfig & {
+  resource: string
+  scopes: ReadonlyArray<string>
+}
+
+export interface FirstPartyExchangeSource {
+  key: PrivateJwk
+  /** Reviewed host attributes; registry_actor_kind must be human and grant claims are refused. */
+  attributes: Readonly<Record<string, JsonValue>>
+}
+
+export interface RemoteExchangeSource {
+  /** Exact assertion URL supplied by the authority client, such as Casework.taskAssertionEndpoint. */
+  endpoint: string
+  bootstrap: ExchangePrivateKeyJwtConfig
+  bootstrapResource: string
+  bootstrapScope: string
+  requestTimeoutMilliseconds?: SafeInteger | null
+  connectTimeoutMilliseconds?: SafeInteger | null
+  userAgent?: string | null
+  trustedRootCertificates?: string | null
+}
+
+export type ExchangeAuthorizationConfig =
+  | { client: ExchangePrivateKeyJwtConfig; context: ExchangeContext; firstParty: FirstPartyExchangeSource }
+  | { client: ExchangePrivateKeyJwtConfig; context: ExchangeContext; remote: RemoteExchangeSource }
+
 export type BaseRegistryAuthorization =
   | { static: string }
   | { privateKeyJwt: PrivateKeyJwtConfig }
+  | { exchange: ExchangeAuthorizationConfig }
 
 export interface BaseRegistryClientConfig {
   baseUrl: string

package/breg/client.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { types: { isProxy } } = require('node:util');
+const { types: { isProxy, isSharedArrayBuffer } } = require('node:util');
 const native = require('./index');
 
 const MAX_JSON_DEPTH = 128;
@@ -50,6 +50,64 @@ function inputError(kind) {
   });
 }
 
+function plainDataObject(value, expectedFields) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value) || isProxy(value)) {
+    throw inputError('invalid_request');
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) throw inputError('invalid_request');
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== 'string')
+    || keys.length !== expectedFields.length
+    || keys.some((key) => !expectedFields.includes(key))) throw inputError('invalid_request');
+  const result = Object.create(null);
+  for (const field of expectedFields) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, field);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')) {
+      throw inputError('invalid_request');
+    }
+    result[field] = descriptor.value;
+  }
+  return result;
+}
+
+function webhookHeaders(value) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value) || isProxy(value)) {
+    throw inputError('invalid_request');
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) throw inputError('invalid_request');
+  const keys = Reflect.ownKeys(value);
+  if (keys.some((key) => typeof key !== 'string')) {
+    throw inputError('invalid_request');
+  }
+  const result = Object.create(null);
+  for (const name of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, name);
+    if (!descriptor || !descriptor.enumerable || !Object.hasOwn(descriptor, 'value')
+      || typeof descriptor.value !== 'string') throw inputError('invalid_request');
+    result[name] = descriptor.value;
+  }
+  return result;
+}
+
+function verifyWebhookDelivery(value) {
+  try {
+    const input = plainDataObject(value, ['method', 'path', 'headers', 'body', 'key']);
+    if (typeof input.method !== 'string' || typeof input.path !== 'string'
+      || !Buffer.isBuffer(input.body) || !Buffer.isBuffer(input.key)
+      || isSharedArrayBuffer(input.body.buffer) || isSharedArrayBuffer(input.key.buffer)) {
+      throw inputError('invalid_request');
+    }
+    input.headers = webhookHeaders(input.headers);
+    input.body = Buffer.from(input.body);
+    input.key = Buffer.from(input.key);
+    return native.verifyWebhookDelivery(input);
+  } catch (error) {
+    throw normalize(error, 'invalid_request');
+  }
+}
+
 function chargeString(value, budget, kind) {
   budget.stringBytes += Buffer.byteLength(value, 'utf8');
   if (budget.stringBytes > MAX_JSON_STRING_BYTES) throw inputError(kind);
@@ -288,7 +346,25 @@ class BaseRegistryClient extends native.BaseRegistryClient {
   }
 }
 
+class PrivateKeyJwt {
+  #native;
+  constructor(config) {
+    try { this.#native = new native.PrivateKeyJwt(cloneJson(config, { nodes: 0, stringBytes: 0, active: new WeakSet() }, 0, 'configuration')); }
+    catch (error) { throw normalize(error, 'configuration'); }
+  }
+  async exchange(subjectToken) {
+    try { return await this.#native.exchange(subjectToken); }
+    catch (error) { throw normalize(error, 'token'); }
+  }
+  async bearerToken() {
+    try { return await this.#native.bearerToken(); }
+    catch (error) { throw normalize(error, 'token'); }
+  }
+}
+
 module.exports = {
+  verifyWebhookDelivery,
+  PrivateKeyJwt,
   BaseRegistryClient,
   BaseRegistryClientError,
   BRegMetadata: native.BRegMetadata,

package/breg/index.d.ts

@@ -244,6 +244,14 @@ export declare class BRegTombstoneBinding {
 }
 export type TombstoneBinding = BRegTombstoneBinding
 
+/** Shared OAuth client authentication and uncached task-token exchange. */
+export declare class PrivateKeyJwt {
+  constructor(config: any)
+  exchange(subjectToken: string): Promise<string>
+  bearerToken(): Promise<string>
+}
+export type PrivateKeyJwtBinding = PrivateKeyJwt
+
 export interface CompleteOutcome {
   kind: string
   value: any
@@ -281,3 +289,29 @@ export interface RawOutcome {
   traceId: string
   etag?: string
 }
+
+/** Authenticated BReg webhook metadata and exact body. */
+export interface VerifiedWebhookDelivery {
+  id: string
+  source: string
+  type: string
+  time: string
+  dataschema: string
+  generation: string
+  attempt: string
+  deliveryTime: string
+  idempotencyKey: string
+  body: Buffer
+}
+
+/** Verify a BReg Version 1 webhook signature without applying receiver policy. */
+export declare function verifyWebhookDelivery(input: WebhookDeliveryInput): VerifiedWebhookDelivery
+
+/** Exact BReg webhook request supplied by a receiver. */
+export interface WebhookDeliveryInput {
+  method: string
+  path: string
+  headers: Record<string, string>
+  body: Buffer
+  key: Buffer
+}

package/casework/client.d.ts

@@ -21,6 +21,30 @@ export type PageStatus = 'complete' | 'budget_exhausted' | 'source_unavailable'
 export type HistoryKind = 'observed' | 'opened' | 'claimed' | 'assigned' | 'delegated' | 'caseload_moved' | 'clock_reminder' | 'clock_step_applied' | 'clock_recomputed' | 'released' | 'draft_saved' | 'attempt_reserved' | 'attempt_uncertain' | 'action_completed' | 'attempt_settled' | 'superseded' | 'completed'
 
 export interface IssuerPrincipal { issuer: string; subject: string }
+export type TaskGrantBounds = { type: 'evidence'; requirement: string } | { type: 'breg'; permissions: ReadonlyArray<TaskPermission> }
+export interface TaskPermission { collection: string; operations: ReadonlyArray<string> }
+export interface EvidenceRequesterContext { requesterTags: ReadonlyArray<string>; audience: string }
+export interface TaskApprovalRequest { templateId: string; templateVersion: string }
+export interface TaskTemplatePreview {
+  id: string; version: string; label: string; agent: IssuerPrincipal; client: string; resource: string; scopes: ReadonlyArray<string>; purpose: string
+  evidenceContext?: EvidenceRequesterContext; bounds: TaskGrantBounds; subjects: { readonly [key: string]: Exclude<JsonScalar, null> }; lifetimeSeconds: SafeInteger
+}
+export interface TaskTemplatePreviews { itemRevision: SafeInteger; templates: ReadonlyArray<TaskTemplatePreview> }
+/** Grant metadata deliberately excludes stored subject values. */
+export interface TaskGrantView {
+  id: string; templateId: string; templateVersion: string; agent: IssuerPrincipal; client: string; resource: string; scopes: ReadonlyArray<string>; purpose: string
+  evidenceContext?: EvidenceRequesterContext; bounds: TaskGrantBounds; expiresAt: SafeInteger; invalidated: boolean
+}
+export interface TaskGrantList { grants: ReadonlyArray<TaskGrantView> }
+export interface TaskGrantRevocation { id: string; invalidated: boolean }
+/** A short-lived credential. Do not persist or log the assertion. */
+export interface TaskAssertionResponse { assertion: string; expiresAt: SafeInteger; grantExpiresAt: SafeInteger }
+export interface TaskGrantStatusDetails {
+  grantId: string; sourceIssuer: string; principal: string; client: string; resource: string; purpose: string
+  bounds: TaskGrantBounds; subjects: { readonly [key: string]: Exclude<JsonScalar, null> }; expiresAt: SafeInteger
+}
+export interface TaskGrantStatus { active: boolean; grant?: TaskGrantStatusDetails }
+
 export interface DirectoryMember { issuer: string; subject: string; displayName?: string | null }
 export interface SubjectRef { sourceId: string; kind: string; id: string }
 export interface SourceBinding {
@@ -326,12 +350,18 @@ export type KnownCaseworkProblemCode =
   | 'request.invalid'
   | 'request.method-not-allowed'
   | 'request.not-found'
+  | 'request.reason-unsupported'
+  | 'request.source-rejected'
   | 'request.unprocessable'
   | 'request.unsupported-media-type'
   | 'runtime.failure'
   | 'service.unavailable'
+  | 'source-profile.not-applicable'
+  | 'source-profile.required'
   | 'source.bad-gateway'
   | 'source.not-found'
+  | 'source.record-missing'
+  | 'source.reviewer-not-authorized'
   | 'source.signature-invalid'
   | 'work-item.already-claimed'
   | 'work-item.not-holder'
@@ -405,6 +435,14 @@ export class CaseworkClient {
   listWorkItems(token: string, profile: string, sourceProfile: string, query: ListWorkItemsQuery): Promise<CaseworkOutcome<WorkItemPage>>
   nextWorkItem(token: string, profile: string, sourceProfile: string, query?: NextWorkItemQuery | null): Promise<CaseworkOutcome<WorkItemPage>>
   getWorkItem(token: string, profile: string, sourceProfile: string, itemId: string): Promise<CaseworkOutcome<WorkItem>>
+  previewTaskTemplates(token: string, profile: string, sourceProfile: string, itemId: string): Promise<CaseworkOutcome<TaskTemplatePreviews>>
+  listTaskGrants(token: string, profile: string, sourceProfile: string, itemId: string): Promise<CaseworkOutcome<TaskGrantList>>
+  approveTaskGrant(token: string, profile: string, sourceProfile: string, itemId: string, expectedRevision: SafeInteger, idempotencyKey: string, approval: TaskApprovalRequest): Promise<CaseworkOutcome<TaskGrantView>>
+  revokeTaskGrant(token: string, profile: string, sourceProfile: string, itemId: string, grantId: string): Promise<CaseworkOutcome<TaskGrantRevocation>>
+  taskAssertion(token: string, grantId: string): Promise<CaseworkOutcome<TaskAssertionResponse>>
+  /** Exact empty-POST authority route for the shared remote exchange provider. */
+  taskAssertionEndpoint(grantId: string): string
+  taskGrantStatus(token: string, grantId: string): Promise<CaseworkOutcome<TaskGrantStatus>>
   claimWorkItem(token: string, profile: string, sourceProfile: string, action: CaseworkAction, idempotencyKey: string): Promise<CaseworkOutcome<MutationResponse>>
   releaseWorkItem(token: string, profile: string, sourceProfile: string, action: CaseworkAction, idempotencyKey: string): Promise<CaseworkOutcome<MutationResponse>>
   getDraft(token: string, profile: string, sourceProfile: string, itemId: string): Promise<CaseworkOutcome<DraftResponse>>

package/casework/client.js

@@ -92,6 +92,14 @@ class CaseworkClient {
       throw normalized(error, 'configuration');
     }
   }
+
+  taskAssertionEndpoint(grantId) {
+    try {
+      return this.native.taskAssertionEndpoint(grantId);
+    } catch (error) {
+      throw normalized(error, 'invalid_request');
+    }
+  }
 }
 
 for (const [method, jsonIndexes] of [
@@ -112,6 +120,12 @@ for (const [method, jsonIndexes] of [
   ['listWorkItems', [3]],
   ['nextWorkItem', [3]],
   ['getWorkItem', []],
+  ['previewTaskTemplates', []],
+  ['listTaskGrants', []],
+  ['approveTaskGrant', [6]],
+  ['revokeTaskGrant', []],
+  ['taskAssertion', []],
+  ['taskGrantStatus', []],
   ['claimWorkItem', [3]],
   ['releaseWorkItem', [3]],
   ['getDraft', []],

package/casework/index.d.ts

@@ -19,6 +19,13 @@ export declare class CaseworkClient {
   listWorkItems(token: string, profile: string, sourceProfile: string, query: any): Promise<CaseworkOutcome>
   nextWorkItem(token: string, profile: string, sourceProfile: string, query?: any | undefined | null): Promise<CaseworkOutcome>
   getWorkItem(token: string, profile: string, sourceProfile: string, itemId: string): Promise<CaseworkOutcome>
+  previewTaskTemplates(token: string, profile: string, sourceProfile: string, itemId: string): Promise<CaseworkOutcome>
+  listTaskGrants(token: string, profile: string, sourceProfile: string, itemId: string): Promise<CaseworkOutcome>
+  approveTaskGrant(token: string, profile: string, sourceProfile: string, itemId: string, expectedRevision: number, idempotencyKey: string, approval: any): Promise<CaseworkOutcome>
+  revokeTaskGrant(token: string, profile: string, sourceProfile: string, itemId: string, grantId: string): Promise<CaseworkOutcome>
+  taskAssertion(token: string, grantId: string): Promise<CaseworkOutcome>
+  taskAssertionEndpoint(grantId: string): string
+  taskGrantStatus(token: string, grantId: string): Promise<CaseworkOutcome>
   claimWorkItem(token: string, profile: string, sourceProfile: string, action: any, idempotencyKey: string): Promise<CaseworkOutcome>
   releaseWorkItem(token: string, profile: string, sourceProfile: string, action: any, idempotencyKey: string): Promise<CaseworkOutcome>
   getDraft(token: string, profile: string, sourceProfile: string, itemId: string): Promise<CaseworkOutcome>

package/evidence/client.d.ts

@@ -35,6 +35,8 @@ export interface ProgressiveVerifiedResult {
   readonly values: Readonly<Record<string, unknown>>
   readonly value: unknown
   readonly subjectContinuity: ProgressiveSubjectContinuity
+  /** Pre-response trust and policy snapshot. Retain with the exact artifact. */
+  readonly retainedVerification: Buffer
 }
 
 /** A signed-JWS result. The credential member of the native result is `null`. */
@@ -82,7 +84,23 @@ export interface PrivateKeyJwtConfig {
   tokenEndpoint: string
   clientId: string
   clientKey: Readonly<Record<string, unknown>>
+  /**
+   * The audience of the client assertion (who checks the client's
+   * authentication). Defaults to the token endpoint URL. This is not the
+   * `resource` of the token request.
+   */
   audience?: string
+  /**
+   * The RFC 8707 resource indicator the token is requested for: the resource
+   * server's registered identifier, not a URL to fetch.
+   */
+  resource?: string
+  /**
+   * The scopes requested for the token, sent as one space-delimited `scope`
+   * parameter. A requested scope may narrow the client's registered
+   * permission set; it can never widen it.
+   */
+  scopes?: ReadonlyArray<string>
   assertionLifetimeSeconds?: number
   refreshMarginSeconds?: number
   requestTimeoutMs?: number
@@ -100,12 +118,91 @@ export type EvidenceTokenConfig =
   | { static: string }
   | { privateKeyJwt: PrivateKeyJwtConfig }
 
+/** A verified actor/grant generation with a bounded authorization lifetime. */
+export interface EvidenceExchangeContext {
+  issuer: string
+  subject: string
+  audience: string
+  generation: string
+  deadlineSeconds: number
+  grantId?: string
+}
+
+/**
+ * The client half of an exchange authorization.
+ *
+ * This is not a `PrivateKeyJwtConfig`, even though the two describe the same
+ * kind of client: an exchange is pinned to one resource and scope set, so both
+ * are required here, and the object is read by the shared exchange
+ * configuration parser rather than by the binding's own reader, so its timeout
+ * members are the full-word ones that parser accepts. State at most one of
+ * `requestTimeoutMilliseconds` and `requestTimeoutSeconds`, and at most one of
+ * `connectTimeoutMilliseconds` and `connectTimeoutSeconds`; naming both of a
+ * pair is refused.
+ */
+export interface EvidenceExchangeClientConfig {
+  tokenEndpoint: string
+  clientId: string
+  /** The client's private key, as a JWK. */
+  clientKey: Readonly<Record<string, unknown>>
+  /**
+   * The audience of the client assertion, when the authorization server
+   * expects something other than its own token endpoint.
+   */
+  audience?: string
+  /**
+   * The RFC 8707 resource indicator the token is requested for: the resource
+   * server's registered identifier, not a URL to fetch.
+   */
+  resource: string
+  /**
+   * The scopes requested for the token, sent as one space-delimited `scope`
+   * parameter. A requested scope may narrow the client's registered
+   * permission set; it can never widen it.
+   */
+  scopes: ReadonlyArray<string>
+  assertionLifetimeSeconds?: number
+  refreshMarginSeconds?: number
+  requestTimeoutMilliseconds?: number
+  requestTimeoutSeconds?: number
+  connectTimeoutMilliseconds?: number
+  connectTimeoutSeconds?: number
+  userAgent?: string
+  /** Additional trust roots for the token endpoint, as a PEM bundle. */
+  trustedRootCertificates?: string
+}
+
+/** The owning authority a remote-sourced exchange obtains assertions from. */
+export interface EvidenceExchangeRemoteSourceConfig {
+  endpoint: string
+  bootstrap: EvidenceExchangeClientConfig
+  bootstrapResource: string
+  bootstrapScope: string
+  requestTimeoutMilliseconds?: number
+  requestTimeoutSeconds?: number
+  connectTimeoutMilliseconds?: number
+  connectTimeoutSeconds?: number
+  userAgent?: string
+  /** Additional trust roots for the authority, as a PEM bundle. */
+  trustedRootCertificates?: string
+}
+
+export type EvidenceExchangeAuthorizationConfig = {
+  client: EvidenceExchangeClientConfig
+  context: EvidenceExchangeContext
+} & (
+  | { firstParty: { key: Readonly<Record<string, unknown>>, attributes: Readonly<Record<string, unknown>> }, remote?: never }
+  | { firstParty?: never, remote: EvidenceExchangeRemoteSourceConfig }
+)
+
 /** The configuration `new EvidenceClient(...)` reads. */
 export interface EvidenceClientConfig {
   baseUrl: string
   trustedJwks: TrustedJwks
   revokedKeyIds: ReadonlyArray<string>
-  token: EvidenceTokenConfig
+  /** Configure exactly one of `token` or `authorization`. */
+  token?: EvidenceTokenConfig
+  authorization?: { exchange: EvidenceExchangeAuthorizationConfig }
   requestTimeoutMs?: number
   connectTimeoutMs?: number
   userAgent?: string
@@ -136,6 +233,10 @@ export declare class EvidenceClient extends NativeEvidenceClient {
    * the JavaScript wrapper.
    */
   static fromProfile(path: string, privateKeyJwk?: Readonly<Record<string, unknown>>): EvidenceClient
+  static fromProfileWithAuthorization(
+    path: string,
+    authorization: { exchange: EvidenceExchangeAuthorizationConfig },
+  ): EvidenceClient
 }
 
 /**

package/evidence/client.js

@@ -166,6 +166,7 @@ for (const name of [
   'values',
   'value',
   'subjectContinuity',
+  'retainedVerification',
 ]) {
   wrapGetter(native.AudienceScopedResult.prototype, name);
 }
@@ -215,6 +216,16 @@ class EvidenceClient extends native.EvidenceClient {
       throw normalize(error);
     }
   }
+
+  static fromProfileWithAuthorization(path, authorization) {
+    try {
+      const client = native.EvidenceClient.fromProfileWithAuthorization(path, authorization);
+      Object.setPrototypeOf(client, this.prototype);
+      return client;
+    } catch (error) {
+      throw normalize(error);
+    }
+  }
 }
 
 class SdJwtVcBatchResponse extends native.SdJwtVcBatchResponse {
@@ -236,4 +247,18 @@ module.exports = {
   RawEvidenceRequestBatchResponse: native.RawEvidenceRequestBatchResponse,
   AudienceScopedResult: native.AudienceScopedResult,
   SdJwtVcBatchResponse,
+  verifyRetained(context, response) {
+    try {
+      return native.verifyRetained(context, response);
+    } catch (error) {
+      throw normalize(error);
+    }
+  },
+  verifyRetainedAsOf(context, response, asOfMillis) {
+    try {
+      return native.verifyRetainedAsOf(context, response, asOfMillis);
+    } catch (error) {
+      throw normalize(error);
+    }
+  },
 };

package/evidence/index.d.ts

@@ -6,6 +6,8 @@
  * FFI boundary until the caller asks for it.
  */
 export declare class AudienceScopedResult {
+  /** Exact serialized pre-response trust snapshot for offline re-verification. */
+  get retainedVerification(): Buffer
   get responseFormat(): string
   get evidence(): any
   get traceId(): string | null
@@ -36,6 +38,12 @@ export declare class EvidenceClient {
    * client and are likewise redacted there.
    */
   static fromProfile(path: string, privateKeyJwk?: any): EvidenceClient
+  /**
+   * Build a profile-driven client with a context-bound staff exchange.
+   * The profile's discovered authority and pinned OAuth request parameters
+   * must match the immutable provider before the first token is acquired.
+   */
+  static fromProfileWithAuthorization(path: string, authorization: any): EvidenceClient
   /**
    * Close the expectations for one request and generate its nonce. No I/O
    * happens here. The returned request is good for exactly one exchange:
@@ -300,3 +308,15 @@ export interface VerifiedEvidenceRequestBatch {
 export type VerifiedEvidenceRequestBatchItem =
   | { status: 'available', verified: VerifiedEvidence }
   | { status: 'notAvailable' }
+
+/**
+ * Verify exact retained response bytes against a bounded pre-response trust
+ * snapshot without constructing a client or performing network I/O.
+ */
+export declare function verifyRetained(context: Buffer, response: Buffer): VerifiedEvidence
+
+/**
+ * Replay an earlier decision at its recorded instant. Current decisions use
+ * `verify_retained` so expired assertions cannot be accepted as current.
+ */
+export declare function verifyRetainedAsOf(context: Buffer, response: Buffer, asOfMillis: number): VerifiedEvidence

package/native.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const PACKAGE_VERSION = '0.30.0';
+const PACKAGE_VERSION = '0.32.0';
 const PRODUCTS = new Set(['discovery', 'evidence', 'relay', 'breg', 'casework']);
 
 function target() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@registrystack/client",
-  "version": "0.30.0",
+  "version": "0.32.0",
   "description": "Unified Node.js client for Registry Stack products.",
   "license": "Apache-2.0",
   "homepage": "https://docs.registrystack.org/reference/client-api/",
@@ -57,8 +57,8 @@
     "typescript": "6.0.3"
   },
   "optionalDependencies": {
-    "@registrystack/client-darwin-arm64": "0.30.0",
-    "@registrystack/client-linux-arm64-gnu": "0.30.0",
-    "@registrystack/client-linux-x64-gnu": "0.30.0"
+    "@registrystack/client-darwin-arm64": "0.32.0",
+    "@registrystack/client-linux-arm64-gnu": "0.32.0",
+    "@registrystack/client-linux-x64-gnu": "0.32.0"
   }
 }

package/relay/client.d.ts

@@ -14,7 +14,23 @@ export interface PrivateKeyJwtConfig {
   tokenEndpoint: string
   clientId: string
   clientKey: PrivateJwk
+  /**
+   * The audience of the client assertion (who checks the client's
+   * authentication). Defaults to the token endpoint URL. This is not the
+   * `resource` of the token request.
+   */
   audience?: string | null
+  /**
+   * The RFC 8707 resource indicator the token is requested for: the resource
+   * server's registered identifier, not a URL to fetch.
+   */
+  resource?: string | null
+  /**
+   * The scopes requested for the token, sent as one space-delimited `scope`
+   * parameter. A requested scope may narrow the client's registered
+   * permission set; it can never widen it.
+   */
+  scopes?: ReadonlyArray<string> | null
   assertionLifetimeSeconds?: SafeInteger | null
   refreshMarginSeconds?: SafeInteger | null
   requestTimeoutMilliseconds?: SafeInteger | null
@@ -23,9 +39,45 @@ export interface PrivateKeyJwtConfig {
   trustedRootCertificates?: string | null
 }
 
+/** One immutable verified person or grant context. Reconstruct after host source facts change. */
+export interface ExchangeContext {
+  issuer: string
+  subject: string
+  audience: string
+  generation: string
+  deadlineSeconds: SafeInteger
+  grantId?: string | null
+}
+
+export type ExchangePrivateKeyJwtConfig = PrivateKeyJwtConfig & {
+  resource: string
+  scopes: ReadonlyArray<string>
+}
+
+export interface FirstPartyExchangeSource {
+  key: PrivateJwk
+  attributes: Readonly<Record<string, JsonValue>>
+}
+
+export interface RemoteExchangeSource {
+  endpoint: string
+  bootstrap: ExchangePrivateKeyJwtConfig
+  bootstrapResource: string
+  bootstrapScope: string
+  requestTimeoutMilliseconds?: SafeInteger | null
+  connectTimeoutMilliseconds?: SafeInteger | null
+  userAgent?: string | null
+  trustedRootCertificates?: string | null
+}
+
+export type ExchangeAuthorizationConfig =
+  | { client: ExchangePrivateKeyJwtConfig; context: ExchangeContext; firstParty: FirstPartyExchangeSource }
+  | { client: ExchangePrivateKeyJwtConfig; context: ExchangeContext; remote: RemoteExchangeSource }
+
 export type RelayAuthorization =
   | { static: string }
   | { privateKeyJwt: PrivateKeyJwtConfig }
+  | { exchange: ExchangeAuthorizationConfig }
 
 export interface RelayClientConfig {
   baseUrl: string