@registrystack/client 0.0.0 → 0.27.0

package/evidence/index.d.ts

@@ -0,0 +1,302 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+/**
+ * One opaque, locally verified progressive result. Its getters keep the
+ * ambiguity check for `value` lazy and retain the exact artifact below the
+ * FFI boundary until the caller asks for it.
+ */
+export declare class AudienceScopedResult {
+  get responseFormat(): string
+  get evidence(): any
+  get traceId(): string | null
+  get assertion(): Buffer | null
+  get credential(): string | null
+  get values(): any
+  get value(): any
+  get subjectContinuity(): SubjectContinuity
+}
+
+/** A relying party's connection to one Evidence deployment. */
+export declare class EvidenceClient {
+  /**
+   * Build a client for one deployment. `trustedJwks` and `revokedKeyIds` are
+   * mandatory trust inputs. A key set or revoked-key list the verifier could
+   * never use is refused, exactly as the Rust configuration refuses it.
+   *
+   * `maxResponseBytes` bounds the signed response `send` reads.
+   * `maxMetadataBytes` bounds the documents `discover` and `fetchJwks` read,
+   * which are neither signed nor verified, and is a separate decision.
+   */
+  constructor(config: any)
+  /**
+   * Build the progressive client from an application-owned profile. An
+   * optional private JWK is an in-memory override for a secret-manager
+   * integration; it is parsed without ever rendering its contents in an
+   * error. Profile paths and file-backed secrets remain inside the core
+   * client and are likewise redacted there.
+   */
+  static fromProfile(path: string, privateKeyJwk?: 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:
+   * spend it with `send` or `requestAndVerify`.
+   */
+  prepare(spec: { responseFormat: 'signed-jws' | 'sd-jwt-vc'; [key: string]: any }): PreparedEvidenceRequest
+  /**
+   * Close one independently nonce-bound policy for each positional item in
+   * a multi-subject request batch. No I/O happens here, and the returned
+   * opaque batch is good for exactly one exchange.
+   */
+  prepareBatch(spec: { requirement: string; purpose: string; audience: string; evidenceType: string; issuedBy: string; providedBy: string; configurationRevision: string; expectedAssuranceProfile: any; expectedOutputs: ReadonlyArray<Readonly<Record<string, any>>>; maximumAssertionLifetimeSeconds: number; clockSkewSeconds: number; items: ReadonlyArray<{ subjects: ReadonlyArray<{ role: string; selectorProfile: string; selectorValues?: Readonly<Record<string, string | number | boolean>> | null }>; subjectExpectations: 'acceptFirstUse' | { pinned: ReadonlyArray<{ role: string; binding: string }> } }> }): PreparedEvidenceRequestBatch
+  /**
+   * Read the request shapes this requester is entitled to send. Discovery
+   * is authoring input, not a trust anchor: it never supplies verification
+   * expectations for a request already in flight.
+   */
+  discover(): Promise<any>
+  /**
+   * Read the deployment's published verification key set, for an
+   * out-of-band pinning workflow. Verification never calls this: a key set
+   * fetched from the same origin as the response it would verify
+   * establishes nothing.
+   */
+  fetchJwks(): Promise<any>
+  /**
+   * Refresh the profile's public metadata under the core client's bounded,
+   * single-flight cache policy. It never substitutes a response-time key
+   * refresh for the key snapshot closed before a request.
+   */
+  refreshMetadata(): Promise<void>
+  /**
+   * Discover, prepare, send exactly once, and verify one audience-scoped
+   * request. The request object intentionally accepts only explicit
+   * selectors or explicit role maps, and the Rust core owns all definition
+   * selection, metadata trust, receipt matching, and result construction.
+   */
+  request(request: any): Promise<AudienceScopedResult>
+  /**
+   * Send one prepared request and read the signed response.
+   *
+   * `prepared` allows exactly one send: a second call with the same object
+   * rejects with the configuration failure the Rust layer already
+   * produces, without reaching the deployment. Retrying means preparing
+   * again, for a fresh nonce.
+   */
+  send(prepared: PreparedEvidenceRequest): Promise<RawEvidenceResponse>
+  /**
+   * Send one prepared request batch and read its unverified envelope. The
+   * same opaque prepared object cannot be sent twice.
+   */
+  sendBatch(prepared: PreparedEvidenceRequestBatch): Promise<RawEvidenceRequestBatchResponse>
+  /**
+   * Verify a signed response against the policy its request closed, as of
+   * now. The trusted key set is the one pinned at construction, always.
+   *
+   * Unlike sending, verifying is unrestricted: it is offline and
+   * idempotent, so a retained response may be re-verified against a
+   * retained prepared request as often as needed, including after the
+   * single send has been spent.
+   */
+  verify(prepared: PreparedEvidenceRequest, response: RawEvidenceResponse): VerifiedEvidence
+  /**
+   * Atomically verify every available member against the policy at its own
+   * request position. No partial result is returned when one member fails.
+   */
+  verifyBatch(prepared: PreparedEvidenceRequestBatch, response: RawEvidenceRequestBatchResponse): VerifiedEvidenceRequestBatch
+  /**
+   * Request evidence and verify it in one step. This spends the single
+   * send `prepared` allows, exactly as `send` does, so calling it twice
+   * with one prepared request fails locally on the second call.
+   */
+  requestAndVerify(prepared: PreparedEvidenceRequest): Promise<VerifiedEvidence>
+  /** Send and atomically verify one prepared request batch in one step. */
+  requestAndVerifyBatch(prepared: PreparedEvidenceRequestBatch): Promise<VerifiedEvidenceRequestBatch>
+  /**
+   * Verify a retained response as of an explicit instant, given as
+   * milliseconds since the Unix epoch.
+   *
+   * `verify` judges a response against the current clock, which is right
+   * when the response has just arrived. This variant names the instant
+   * instead, for re-verifying a retained response or replaying a retained
+   * transaction record at the instant the original decision was made.
+   *
+   * A past instant is the direction that costs something: naming a stale
+   * instant accepts an assertion whose validity interval has since
+   * elapsed, because the question asked is whether it was acceptable then,
+   * and the answer stays yes forever. A live trust decision calls `verify`,
+   * not this.
+   */
+  verifyAsOf(prepared: PreparedEvidenceRequest, response: RawEvidenceResponse, asOfMillis: number): VerifiedEvidence
+  /**
+   * Atomically verify a retained request-batch envelope as of an explicit
+   * instant, in milliseconds since the Unix epoch.
+   */
+  verifyBatchAsOf(prepared: PreparedEvidenceRequestBatch, response: RawEvidenceRequestBatchResponse, asOfMillis: number): VerifiedEvidenceRequestBatch
+}
+
+/**
+ * One request, closed and nonce-bearing, before any byte has left the
+ * process.
+ *
+ * There is no constructor exposed to JS: the only way to obtain one is
+ * `EvidenceClient.prepare`, which mirrors the real type having no public
+ * constructor of its own either.
+ */
+export declare class PreparedEvidenceRequest {
+  /** The nonce this request carries. Retain it with the transaction record. */
+  get requestNonce(): string
+  /**
+   * The closed verification policy, with the subject set as `prepare` left
+   * it.
+   */
+  get policyDocument(): any
+  /**
+   * `"acceptFirstUse"` or `{ pinned: [{ role, binding }, ...] }`, exactly as
+   * this request was prepared.
+   */
+  get subjectExpectations(): any
+}
+
+/**
+ * One ordered request batch, with one nonce and closed policy per item,
+ * before any byte has left the process.
+ *
+ * There is no constructor exposed to JS. The only way to obtain this opaque
+ * class is `EvidenceClient.prepareBatch`, and every `Arc` clone shares the
+ * real batch's one-send flag rather than recreating it.
+ */
+export declare class PreparedEvidenceRequestBatch {
+  /** Independently generated item nonces in request order. */
+  get requestNonces(): Array<string>
+  /** Independently closed policy documents in request order. */
+  get policyDocuments(): Array<any>
+  /** Subject-verification stances in request order. */
+  get subjectExpectations(): Array<any>
+  /** Number of positional requests in this batch. */
+  get count(): number
+}
+
+/**
+ * Request-batch response bytes read but not yet judged.
+ *
+ * The class is opaque and has no JS constructor. It can only be returned by
+ * `EvidenceClient.sendBatch` and handed back to batch verification.
+ */
+export declare class RawEvidenceRequestBatchResponse {
+  /** Response envelope bytes exactly as received. */
+  get body(): Buffer
+  /** Deployment correlation identifier for the whole batch exchange. */
+  get traceId(): string | null
+}
+
+/**
+ * A signed response, read but not yet judged.
+ *
+ * There is no constructor exposed to JS: the real Rust type has no public
+ * constructor either, so the only way to obtain one is `EvidenceClient.send`.
+ */
+export declare class RawEvidenceResponse {
+  /**
+   * The signed response bytes, exactly as received. Nothing in them has
+   * been trusted yet; `verify` is what judges them.
+   */
+  get body(): Buffer
+  /**
+   * The validated W3C trace identifier for this exchange. It is support
+   * correlation only, not an Evidence audit operation identity.
+   */
+  get traceId(): string | null
+}
+
+/**
+ * The issuance envelope answering one request that presented several holder
+ * keys, read but not yet judged.
+ *
+ * The envelope's order is the request's own: `credentials[i]` answers the
+ * key the request sent as `holderKeys[i]`, one credential per key, and a
+ * caller that needs that correspondence spelled out can ask for it by index
+ * with `credentialForHolderKey`. There is no partial envelope: either every
+ * presented key was answered or reading the envelope failed.
+ *
+ * Reading it judges nothing. Each credential is verified individually,
+ * exactly as a single credential is, and parsing this envelope is not a step
+ * in that.
+ */
+export declare class SdJwtVcBatchResponse {
+  /**
+   * Read an envelope from the response bytes a batch exchange returned,
+   * such as `RawEvidenceResponse.body`.
+   *
+   * This is a constructor rather than a static factory because napi-rs
+   * defines a generated static as non-writable and non-configurable on the
+   * class object, which leaves `client.js` no way to patch its throw path
+   * the way it patches every other member here. A constructor it can
+   * subclass, exactly as it already does for `EvidenceClient`.
+   */
+  constructor(body: Buffer)
+  /**
+   * Every credential the envelope carries, in the order the request
+   * presented its holder keys.
+   */
+  get credentials(): Array<string>
+  /**
+   * How many credentials the envelope carries, which is how many holder
+   * keys the request presented.
+   */
+  get count(): number
+  /**
+   * The credential bound to the holder key the request sent at `index`, or
+   * `null` when the envelope carries no credential at that position.
+   */
+  credentialForHolderKey(index: number): string | null
+}
+
+/**
+ * An application-owned receipt emitted after a verified audience-scoped
+ * result. It is serializable but deliberately opaque to this binding: no
+ * selector or disclosed value is copied into it here.
+ */
+export type SubjectContinuity =
+  | { status: 'firstUse', receipt: any }
+  | { status: 'matched', receipt: any }
+
+/**
+ * A response that satisfied every expectation.
+ *
+ * Unlike the opaque classes above, this crosses as a plain object: it is a
+ * terminal result nothing hands back into a later call, so there is no
+ * single-send flag or unconstructible real type to protect by staying
+ * opaque.
+ */
+export interface VerifiedEvidence {
+  /** The verified payload, serialized field for field with no hand mapping. */
+  evidence: any
+  /**
+   * The validated W3C trace identifier for the exchange that produced this
+   * payload. It is support correlation only, not an Evidence audit operation
+   * identity.
+   */
+  traceId?: string
+  /**
+   * The role-bound subject bindings this payload carries. Persist these
+   * after a first-use acceptance and pass them back as `subjectExpectations:
+   * { pinned: [...] }` from then on.
+   */
+  pinnedSubjectExpectations: any
+}
+
+/** Every item of an atomically verified request-batch response. */
+export interface VerifiedEvidenceRequestBatch {
+  items: Array<VerifiedEvidenceRequestBatchItem>
+  traceId?: string
+}
+
+/**
+ * One ordered terminal request-batch result.
+ *
+ * The generated TypeScript declaration is a discriminated union:
+ * `{ status: "available", verified } | { status: "notAvailable" }`.
+ */
+export type VerifiedEvidenceRequestBatchItem =
+  | { status: 'available', verified: VerifiedEvidence }
+  | { status: 'notAvailable' }

package/evidence/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('../native').load('evidence');

package/index.d.ts

@@ -0,0 +1,6 @@
+import * as discovery from './discovery/client'
+import * as evidence from './evidence/client'
+import * as relay from './relay/client'
+import * as breg from './breg/client'
+
+export { discovery, evidence, relay, breg }

package/index.js

@@ -0,0 +1,9 @@
+'use strict';
+
+// 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

@@ -0,0 +1,34 @@
+'use strict';
+
+const PACKAGE_VERSION = '0.27.0';
+const PRODUCTS = new Set(['discovery', 'evidence', 'relay', 'breg']);
+
+function target() {
+  if (process.platform === 'darwin' && process.arch === 'arm64') return 'darwin-arm64';
+  if (process.platform === 'linux' && process.arch === 'arm64') return 'linux-arm64-gnu';
+  if (process.platform === 'linux' && process.arch === 'x64') return 'linux-x64-gnu';
+  throw new Error(`@registrystack/client does not support ${process.platform}-${process.arch}`);
+}
+
+function load(product) {
+  if (!PRODUCTS.has(product)) throw new Error(`unknown Registry Stack client product: ${product}`);
+  const suffix = target();
+  const packageName = `@registrystack/client-${suffix}`;
+  let bindings;
+  try {
+    bindings = require(packageName);
+  } catch (error) {
+    error.message = `Unable to load ${packageName}. Reinstall @registrystack/client for this platform. ${error.message}`;
+    throw error;
+  }
+  const installedVersion = require(`${packageName}/package.json`).version;
+  if (installedVersion !== PACKAGE_VERSION) {
+    throw new Error(`Native client package version mismatch: expected ${PACKAGE_VERSION}, got ${installedVersion}`);
+  }
+  if (!Object.hasOwn(bindings, product)) {
+    throw new Error(`${packageName} does not contain the ${product} binding`);
+  }
+  return bindings[product];
+}
+
+module.exports = { load };

package/package.json

@@ -1,21 +1,49 @@
 {
   "name": "@registrystack/client",
-  "version": "0.0.0",
-  "description": "Reserved package identity for the unified Registry Stack client.",
+  "version": "0.27.0",
+  "description": "Unified Node.js client for Registry Stack products.",
   "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/registrystack/registry-stack.git"
+    "url": "https://github.com/registrystack/registry-stack"
   },
-  "homepage": "https://github.com/registrystack/registry-stack",
-  "bugs": {
-    "url": "https://github.com/registrystack/registry-stack/issues"
-  },
-  "publishConfig": {
-    "access": "public"
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
   },
   "files": [
-    "README.md",
-    "LICENSE"
-  ]
+    "index.js",
+    "index.d.ts",
+    "native.js",
+    "discovery",
+    "evidence",
+    "relay",
+    "breg"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "scripts": {
+    "sync": "python3 ../../release/scripts/sync-registry-client-node.py",
+    "sync:check": "python3 ../../release/scripts/sync-registry-client-node.py --check",
+    "test": "npm run sync:check && node --test __test__/*.test.js",
+    "check:types": "tsc --noEmit --strict --skipLibCheck false --types node --moduleResolution node16 --module node16 --target es2022 index.d.ts __test__/facade.test-d.ts"
+  },
+  "devDependencies": {
+    "@types/node": "22.20.1",
+    "typescript": "6.0.3"
+  },
+  "optionalDependencies": {
+    "@registrystack/client-darwin-arm64": "0.27.0",
+    "@registrystack/client-linux-arm64-gnu": "0.27.0",
+    "@registrystack/client-linux-x64-gnu": "0.27.0"
+  }
 }