@registrystack/client 0.30.0 → 0.31.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,6 +78,15 @@ 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>
+}
+
 export type BaseRegistryAuthorization =
   | { static: string }
   | { privateKeyJwt: PrivateKeyJwtConfig }

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,12 @@ 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>>
+  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

@@ -112,6 +112,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,12 @@ 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>
+  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

@@ -82,7 +82,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

package/native.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const PACKAGE_VERSION = '0.30.0';
+const PACKAGE_VERSION = '0.31.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.31.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.31.0",
+    "@registrystack/client-linux-arm64-gnu": "0.31.0",
+    "@registrystack/client-linux-x64-gnu": "0.31.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