@registrystack/client 0.26.1 → 0.27.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.

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.27.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.27.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.27.0",
+    "@registrystack/client-linux-arm64-gnu": "0.27.0",
+    "@registrystack/client-linux-x64-gnu": "0.27.0"
   }
 }