@registrystack/client 0.26.1 → 0.28.0

package/README.md

@@ -15,6 +15,28 @@ const registry = new breg.BaseRegistryClient({
 });
 ```
 
+A TypeScript consumer also needs the Node type definitions, and must name
+them. The published declarations use `Buffer`, a Node.js global, and
+TypeScript 6 does not load installed `@types` packages on its own, so a
+project compiling against the declarations reports `TS2591` on every use of
+`Buffer` until it has both installed the package and listed it in
+`compilerOptions.types`:
+
+```sh
+npm install --save-dev "@types/node"
+```
+
+```json
+{
+  "compilerOptions": {
+    "types": ["node"]
+  }
+}
+```
+
+The package does not declare that dependency itself, because a JavaScript
+consumer does not need it.
+
 Each product remains in its own namespace because its routing,
 authentication, errors, and verification rules are different. The package
 uses one platform-specific native dependency containing all four bindings.
@@ -25,3 +47,19 @@ The unified package is published beginning with Registry Stack v0.26.1.
 Existing standalone client packages remain available for earlier versions,
 but the release process does not publish new standalone versions once this
 package is active.
+
+For server-side BReg applications, `breg.BaseRegistryClient.registryContract()`
+returns caller-filtered `operations` with typed field, request, and list-query
+descriptors. Descriptions do not grant authority: select opaque create, patch,
+and lifecycle authorities from that same contract before executing mutations.
+
+Use BReg methods ending in `Json` when values must cross Node without numeric
+coercion. They accept domain JSON text and return `valueJson` plus the usual
+trace, ETag, location, and opaque continuation. `lifecycleActionsJson` accepts a
+record envelope; opaque actions expose `bodyJson` and `reviewJson`. Decode these
+strings with a lossless JSON library when displaying wide numbers. Decimal
+fields remain fixed-scale strings, and null remains distinct from absence.
+Duplicate members and silently rounded literals are refused. Existing BReg
+integer restrictions still apply: `9007199254740992` is a supported write,
+whereas `9007199254740993` is refused before I/O. Do not round refused values.
+The client never retries a mutation automatically.

package/breg/client.d.ts

@@ -151,6 +151,79 @@ export interface LifecycleReceipt extends JsonObject {
   request: JsonObject
 }
 
+/** Exact validated JSON text, serialized before conversion to JavaScript numbers.
+ * Decode with a lossless JSON library if inspecting values outside the safe integer range.
+ * Decimal fields remain fixed-scale JSON strings. */
+export interface JsonOutcome {
+  kind: 'complete'
+  valueJson: string
+  continuation?: ListContinuation
+  traceId: string
+  etag?: string
+  location?: string
+}
+
+export interface BRegFieldDescriptor {
+  readonly id: string
+  readonly apiName: string
+  readonly label: string
+  readonly schemaJson: string
+  readonly required: boolean
+  readonly nullable: boolean
+  readonly readOnly: boolean
+  readonly removable: boolean
+  readonly referenceTargetEntity: string | null
+}
+export interface BRegQueryField {
+  readonly id: string
+  readonly apiName: string
+  readonly operators?: ReadonlyArray<string>
+  readonly directions?: ReadonlyArray<string>
+}
+export interface BRegQueryDescriptor {
+  readonly kind: string
+  readonly selectableFields: ReadonlyArray<BRegQueryField>
+  readonly filterableFields: ReadonlyArray<BRegQueryField>
+  readonly sortableFields: ReadonlyArray<BRegQueryField>
+  readonly allowCount: boolean
+  readonly defaultPageSize: number
+  readonly maxPageSize: number
+  readonly maxFilterClauses: number
+  readonly maxInValues: number
+  readonly pagination: { readonly parameter: string; readonly responsePath: string; readonly exclusive: boolean }
+  readonly temporal: JsonObject | null
+}
+export interface BRegOperationDescriptor {
+  readonly id: string
+  readonly method: string
+  readonly path: string
+  readonly kind: string
+  readonly sourceEntity: string
+  readonly responseEntity: string
+  readonly accessProfile: string
+  readonly entityLabel: string
+  readonly titleFields: ReadonlyArray<string>
+  readonly requiredCapabilities: ReadonlyArray<string>
+  readonly fields: ReadonlyArray<BRegFieldDescriptor>
+  readonly readableFields: ReadonlyArray<string>
+  readonly createWritableFields: ReadonlyArray<string>
+  readonly patchWritableFields: ReadonlyArray<string>
+  readonly query: BRegQueryDescriptor | null
+  readonly request: {
+    readonly fieldNames: string | null
+    readonly queryParameters: ReadonlyArray<string>
+    readonly body: string | null
+    readonly contentType: string | null
+    readonly schemaJson: string | null
+    readonly idempotencyKeyRequired: boolean | null
+    readonly ifMatchRequired: boolean | null
+    readonly mutationSemantics: string | null
+    readonly patchPathPrefix: string | null
+    readonly patchOperations: ReadonlyArray<string>
+    readonly removeSemantics: string | null
+  }
+}
+
 /** Opaque write authority selected from metadata fetched by this client source. */
 export declare class BRegCreateBinding {
   private constructor()
@@ -174,6 +247,8 @@ export declare class BRegLifecycleAction {
   readonly operation: string
   readonly stage: string | null
   readonly href: string
+  readonly bodyJson: string
+  readonly reviewJson: string | null
   readonly body: JsonObject
   readonly review: LifecycleReview | null
 }
@@ -182,6 +257,7 @@ export declare class BRegLifecycleAction {
 export declare class BRegMetadata {
   private constructor()
   private readonly __opaque: void
+  readonly operations: ReadonlyArray<BRegOperationDescriptor>
   readonly registryIdentifier: string
   readonly registryVersion: string
   readonly registryRevision: string
@@ -227,5 +303,13 @@ export declare class BaseRegistryClient {
   createRecord(binding: BRegCreateBinding, data: JsonObject, idempotencyKey: string, format?: RecordFormat | null): Promise<CompleteOutcome<RecordEnvelope>>
   patchRecord(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operations: ReadonlyArray<PatchOperation | RemovePatchOperation>, idempotencyKey: string, format?: RecordFormat | null): Promise<CompleteOutcome<RecordEnvelope>>
   lifecycleActions(authority: BRegLifecycleAuthority, record: RecordEnvelope, format?: RecordFormat | null): ReadonlyArray<BRegLifecycleAction>
+  getRecordJson(entityRoute: string, recordIdentifier: string, options?: RecordOptions | null): Promise<JsonOutcome>
+  listRecordsJson(entityRoute: string, options?: ListOptions | null): Promise<JsonOutcome>
+  continueListJson(continuation: ListContinuation): Promise<JsonOutcome>
+  lookupRecordJson(entityRoute: string, selector: string, valuesJson?: string | null, options?: RecordOptions | null): Promise<JsonOutcome>
+  createRecordJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, format?: RecordFormat | null): Promise<JsonOutcome>
+  patchRecordJson(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operationsJson: string, idempotencyKey: string, format?: RecordFormat | null): Promise<JsonOutcome>
+  lifecycleActionsJson(authority: BRegLifecycleAuthority, recordJson: string, format?: RecordFormat | null): ReadonlyArray<BRegLifecycleAction>
+  executeLifecycleActionJson(action: BRegLifecycleAction, idempotencyKey: string): Promise<JsonOutcome>
   executeLifecycleAction(action: BRegLifecycleAction, idempotencyKey: string): Promise<CompleteOutcome<LifecycleReceipt>>
 }

package/breg/client.js

@@ -141,8 +141,16 @@ for (const [method, jsonIndexes, requiredIndexes] of [
   ['getRecord', [2]], ['listRecords', [1]], ['continueList', [0], [0]],
   ['lookupRecord', [2, 3]], ['createRecord', [1], [1]],
   ['patchRecord', [3], [3]], ['executeLifecycleAction'],
+  ['getRecordJson', [2]], ['listRecordsJson', [1]], ['continueListJson', [0], [0]],
+  ['lookupRecordJson', [3]], ['createRecordJson'], ['patchRecordJson'], ['executeLifecycleActionJson'],
 ]) wrapAsync(method, jsonIndexes, requiredIndexes);
 
+const lifecycleActionsJson = native.BaseRegistryClient.prototype.lifecycleActionsJson;
+native.BaseRegistryClient.prototype.lifecycleActionsJson = function (...args) {
+  try { return lifecycleActionsJson.apply(this, args); }
+  catch (error) { throw normalize(error, 'invalid_request'); }
+};
+
 const lifecycleActions = native.BaseRegistryClient.prototype.lifecycleActions;
 native.BaseRegistryClient.prototype.lifecycleActions = function (...args) {
   try {

package/breg/index.d.ts

@@ -16,6 +16,14 @@ export declare class BaseRegistryClient {
   patchRecord(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operations: any, idempotencyKey: string, formatValue?: string | undefined | null): Promise<CompleteOutcome>
   lifecycleActions(authority: BRegLifecycleAuthority, record: any, formatValue?: string | undefined | null): Array<BRegLifecycleAction>
   executeLifecycleAction(action: BRegLifecycleAction, idempotencyKey: string): Promise<CompleteOutcome>
+  getRecordJson(entityRoute: string, recordIdentifier: string, options?: any | undefined | null): Promise<JsonOutcome>
+  listRecordsJson(entityRoute: string, options?: any | undefined | null): Promise<JsonOutcome>
+  continueListJson(value: any): Promise<JsonOutcome>
+  lookupRecordJson(entityRoute: string, selector: string, valuesJson?: string | undefined | null, options?: any | undefined | null): Promise<JsonOutcome>
+  createRecordJson(binding: BRegCreateBinding, dataJson: string, idempotencyKey: string, formatValue?: string | undefined | null): Promise<JsonOutcome>
+  patchRecordJson(binding: BRegPatchBinding, recordIdentifier: string, etag: string, operationsJson: string, idempotencyKey: string, formatValue?: string | undefined | null): Promise<JsonOutcome>
+  lifecycleActionsJson(authority: BRegLifecycleAuthority, recordJson: string, formatValue?: string | undefined | null): Array<BRegLifecycleAction>
+  executeLifecycleActionJson(action: BRegLifecycleAction, idempotencyKey: string): Promise<JsonOutcome>
 }
 
 export declare class BRegCreateBinding {
@@ -24,6 +32,8 @@ export declare class BRegCreateBinding {
 export type CreateBinding = BRegCreateBinding
 
 export declare class BRegLifecycleAction {
+  get bodyJson(): string
+  get reviewJson(): string | null
   get operation(): string
   get stage(): string | null
   get href(): string
@@ -38,6 +48,8 @@ export declare class BRegLifecycleAuthority {
 export type LifecycleAuthority = BRegLifecycleAuthority
 
 export declare class BRegMetadata {
+  /** Caller-filtered inert descriptors. Selectors below remain the only authority constructors. */
+  get operations(): any
   get registryIdentifier(): string
   get registryVersion(): string
   get registryRevision(): string
@@ -62,6 +74,16 @@ export interface CompleteOutcome {
   location?: string
 }
 
+/** Validated product result serialized before the JavaScript number boundary. */
+export interface JsonOutcome {
+  kind: string
+  valueJson: string
+  continuation?: any
+  traceId: string
+  etag?: string
+  location?: string
+}
+
 export interface PageOutcome {
   kind: string
   value: any

package/evidence/client.d.ts

@@ -4,6 +4,12 @@
 // `__test__/drift.test.js`, against the real module.
 export * from './index'
 
+import {
+  EvidenceClient as NativeEvidenceClient,
+  PreparedEvidenceRequest,
+  PreparedEvidenceRequestBatch,
+} from './index'
+
 /** The signed response encoding closed before one request is sent. */
 export type EvidenceResponseFormat = 'signed-jws' | 'sd-jwt-vc'
 
@@ -24,17 +30,22 @@ export type ProgressiveSubjectContinuity =
 
 export interface ProgressiveVerifiedResult {
   readonly evidence: unknown
-  readonly traceId?: string
+  /** The exchange's trace identifier, `null` when the response carried none. */
+  readonly traceId: string | null
   readonly values: Readonly<Record<string, unknown>>
   readonly value: unknown
   readonly subjectContinuity: ProgressiveSubjectContinuity
 }
 
+/** A signed-JWS result. The credential member of the native result is `null`. */
 export interface ProgressiveVerifiedAssertion extends ProgressiveVerifiedResult {
   readonly assertion: Buffer
+  readonly credential: null
 }
 
+/** An SD-JWT VC result. The assertion member of the native result is `null`. */
 export interface ProgressiveVerifiedAudienceScopedCredential extends ProgressiveVerifiedResult {
+  readonly assertion: null
   readonly credential: string
 }
 
@@ -53,20 +64,78 @@ export type AudienceScopedRequest = {
   bindingReceipt?: SubjectBindingReceipt
 }
 
-/** Progressive methods merged into the native `EvidenceClient` declaration. */
-export interface EvidenceClient {
-  refreshMetadata(): Promise<void>
-  request(request: AudienceScopedRequest): Promise<ProgressiveResult>
+/**
+ * The pinned verification key set, as a JWKS document. It is a trust input:
+ * the client never fetches one to verify a response it already holds.
+ */
+export interface TrustedJwks {
+  keys: ReadonlyArray<Readonly<Record<string, unknown>>>
+  readonly [field: string]: unknown
+}
+
+/**
+ * A private-key-JWT client-credentials exchange the client performs for
+ * itself. `clientKey` holds the private half; it stays in this process and
+ * reaches nothing but the token endpoint.
+ */
+export interface PrivateKeyJwtConfig {
+  tokenEndpoint: string
+  clientId: string
+  clientKey: Readonly<Record<string, unknown>>
+  audience?: string
+  assertionLifetimeSeconds?: number
+  refreshMarginSeconds?: number
+  requestTimeoutMs?: number
+  connectTimeoutMs?: number
+  userAgent?: string
+  /** Additional trust roots for the token endpoint, as a PEM bundle. */
+  trustedRootCertificates?: string
 }
 
-/** Progressive factories merged into the native `EvidenceClient` value. */
-export namespace EvidenceClient {
+/**
+ * Exactly one credential source. A configuration naming both is refused, so a
+ * merge of two authentication settings cannot silently pick one.
+ */
+export type EvidenceTokenConfig =
+  | { static: string }
+  | { privateKeyJwt: PrivateKeyJwtConfig }
+
+/** The configuration `new EvidenceClient(...)` reads. */
+export interface EvidenceClientConfig {
+  baseUrl: string
+  trustedJwks: TrustedJwks
+  revokedKeyIds: ReadonlyArray<string>
+  token: EvidenceTokenConfig
+  requestTimeoutMs?: number
+  connectTimeoutMs?: number
+  userAgent?: string
+  /** Additional trust roots for the deployment, as a PEM bundle. */
+  trustedRootCertificates?: string
+  maxResponseBytes?: number
+  maxMetadataBytes?: number
+}
+
+/**
+ * The client `client.js` exports, which subclasses the generated one so every
+ * mapped failure normalizes to an `EvidenceClientError`. Declaring it as a
+ * subclass, rather than as an interface of the same name, is what keeps the
+ * generated construct signature reachable: a same-named interface would
+ * shadow the re-exported class and leave `new EvidenceClient(...)` untyped.
+ *
+ * The members below only narrow generated declarations that cross as
+ * JSON-shaped `any`; every other member is inherited unchanged.
+ */
+export declare class EvidenceClient extends NativeEvidenceClient {
+  constructor(config: EvidenceClientConfig)
+  prepare(spec: EvidenceRequestSpec): PreparedEvidenceRequest
+  prepareBatch(spec: EvidenceRequestBatchSpec): PreparedEvidenceRequestBatch
+  request(request: AudienceScopedRequest): Promise<ProgressiveResult>
   /**
    * Read an application-owned profile. `privateKeyJwk` is optional and is
    * intended for an in-memory secret-manager result; it is never retained by
    * the JavaScript wrapper.
    */
-  function fromProfile(path: string, privateKeyJwk?: Readonly<Record<string, unknown>>): EvidenceClient
+  static fromProfile(path: string, privateKeyJwk?: Readonly<Record<string, unknown>>): EvidenceClient
 }
 
 /**

package/index.js

@@ -1,8 +1,9 @@
 'use strict';
 
-module.exports = {
-  discovery: require('./discovery/client'),
-  evidence: require('./evidence/client'),
-  relay: require('./relay/client'),
-  breg: require('./breg/client'),
-};
+// One assignment per namespace, never a `module.exports` object literal: Node
+// scans this file for these statements to synthesise the named exports an ESM
+// consumer imports, and `require()` sees the same four properties either way.
+exports.discovery = require('./discovery/client');
+exports.evidence = require('./evidence/client');
+exports.relay = require('./relay/client');
+exports.breg = require('./breg/client');

package/native.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@registrystack/client",
-  "version": "0.26.1",
+  "version": "0.28.0",
   "description": "Unified Node.js client for Registry Stack products.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -42,8 +42,8 @@
     "typescript": "6.0.3"
   },
   "optionalDependencies": {
-    "@registrystack/client-darwin-arm64": "0.26.1",
-    "@registrystack/client-linux-arm64-gnu": "0.26.1",
-    "@registrystack/client-linux-x64-gnu": "0.26.1"
+    "@registrystack/client-darwin-arm64": "0.28.0",
+    "@registrystack/client-linux-arm64-gnu": "0.28.0",
+    "@registrystack/client-linux-x64-gnu": "0.28.0"
   }
 }