@registrystack/client 0.31.0 → 0.32.0

package/breg/client.d.ts

@@ -87,9 +87,47 @@ export class PrivateKeyJwt {
   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/casework/client.d.ts

@@ -440,6 +440,8 @@ export class CaseworkClient {
   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>>

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 [

package/casework/index.d.ts

@@ -24,6 +24,7 @@ export declare class CaseworkClient {
   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>

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`. */
@@ -116,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
@@ -152,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.31.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.31.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.31.0",
-    "@registrystack/client-linux-arm64-gnu": "0.31.0",
-    "@registrystack/client-linux-x64-gnu": "0.31.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

@@ -39,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