@registrystack/client 0.0.0 → 0.27.0

package/evidence/client.d.ts

@@ -0,0 +1,250 @@
+// The package's actual entry point. `index.d.ts` is auto-generated by
+// `napi build --platform` on every build and is what `check:types` diffs
+// byte-for-byte; the hand-written surface below is checked separately, by
+// `__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'
+
+/** An opaque, versioned subject-continuity receipt owned by the application. */
+export interface SubjectBindingReceipt {
+  readonly schema: 'registry.evidence-subject-binding-receipt/v1'
+  readonly [field: string]: unknown
+}
+
+/**
+ * The hand-written progressive result view refines napi-rs's JSON-shaped
+ * generated declarations without pretending it can infer a domain-specific
+ * output type. Its discriminants mirror the native result exactly.
+ */
+export type ProgressiveSubjectContinuity =
+  | { readonly status: 'firstUse'; readonly receipt: SubjectBindingReceipt }
+  | { readonly status: 'matched'; readonly receipt: SubjectBindingReceipt }
+
+export interface ProgressiveVerifiedResult {
+  readonly evidence: unknown
+  /** 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
+}
+
+export type ProgressiveResult =
+  | ({ readonly responseFormat: 'signed-jws' } & ProgressiveVerifiedAssertion)
+  | ({ readonly responseFormat: 'sd-jwt-vc' } & ProgressiveVerifiedAudienceScopedCredential)
+
+export type AudienceScopedRequest = {
+  requirement: string
+  responseFormat?: EvidenceResponseFormat
+  /** One request-origin subject. Node keeps the selector map explicit. */
+  selectors?: Readonly<Record<string, string | number | boolean>>
+  /** Multiple roles, or a request whose selector field needs a reserved name. */
+  subjects?: Readonly<Record<string, Readonly<Record<string, string | number | boolean>>>>
+  /** A prior receipt the application chose to retain. Nothing is persisted by this package. */
+  bindingReceipt?: SubjectBindingReceipt
+}
+
+/**
+ * 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
+}
+
+/**
+ * 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.
+   */
+  static fromProfile(path: string, privateKeyJwk?: Readonly<Record<string, unknown>>): EvidenceClient
+}
+
+/**
+ * A holder public key a request may present, as a public JWK.
+ *
+ * Public material only. There is no member here for a private key half, and
+ * a key carrying one (`d`, or any other private JWK member) is refused with
+ * that stated as the reason: the private half stays with whoever holds it,
+ * and this package never asks for it, holds it, or sends it.
+ */
+export interface HolderPublicKey {
+  kty: 'EC'
+  crv: 'P-256'
+  /** The x coordinate, unpadded base64url. */
+  x: string
+  /** The y coordinate, unpadded base64url. */
+  y: string
+  alg?: 'ES256' | null
+  kid?: string | null
+}
+
+/** The request-spec input accepted by `EvidenceClient.prepare`. */
+export interface EvidenceRequestSpec {
+  responseFormat: EvidenceResponseFormat
+  requirement: string
+  purpose: string
+  audience: string
+  evidenceType: string
+  issuedBy: string
+  providedBy: string
+  configurationRevision: string
+  expectedAssuranceProfile: unknown
+  subjects: ReadonlyArray<{
+    role: string
+    selectorProfile: string
+    selectorValues?: Readonly<Record<string, string | number | boolean>> | null
+  }>
+  /**
+   * Holder public keys this request presents, in the order the caller wants
+   * them answered. Omit it (or pass an empty array) to present none, which is
+   * the request this package has always sent.
+   *
+   * A request presenting several keys can be answered with one credential per
+   * key, in that same order; see `SdJwtVcBatchResponse`.
+   */
+  holderKeys?: ReadonlyArray<HolderPublicKey>
+  expectedOutputs: ReadonlyArray<Readonly<Record<string, unknown>>>
+  maximumAssertionLifetimeSeconds: number
+  clockSkewSeconds: number
+  subjectExpectations:
+    | 'acceptFirstUse'
+    | { pinned: ReadonlyArray<{ role: string; binding: string }> }
+}
+
+/** One positional item in a multi-subject Evidence request batch. */
+export interface EvidenceRequestBatchItemSpec {
+  subjects: ReadonlyArray<{
+    role: string
+    selectorProfile: string
+    selectorValues?: Readonly<Record<string, string | number | boolean>> | null
+  }>
+  subjectExpectations:
+    | 'acceptFirstUse'
+    | { pinned: ReadonlyArray<{ role: string; binding: string }> }
+}
+
+/**
+ * The common request inputs and ordered item inputs accepted by
+ * `EvidenceClient.prepareBatch`.
+ */
+export interface EvidenceRequestBatchSpec {
+  requirement: string
+  purpose: string
+  audience: string
+  evidenceType: string
+  issuedBy: string
+  providedBy: string
+  configurationRevision: string
+  expectedAssuranceProfile: unknown
+  expectedOutputs: ReadonlyArray<Readonly<Record<string, unknown>>>
+  maximumAssertionLifetimeSeconds: number
+  clockSkewSeconds: number
+  items: ReadonlyArray<EvidenceRequestBatchItemSpec>
+}
+
+/**
+ * The stable eight-kind error envelope every mapped Evidence Node failure
+ * carries, as properties on a thrown `Error` (see `src/lib.rs`'s
+ * `to_napi_error` and `src/convert.rs`'s `map_client_error` for the Rust side
+ * of this contract).
+ *
+ * `kind` is always present. The rest are present only when the underlying
+ * failure carries them:
+ * - `status`: `denied`, `protocol`, and any `token` failure whose `tokenKind`
+ *   is `protocol`
+ * - `code`: `denied`, `protocol` (optional), `verification`, and any `token`
+ *   failure whose `tokenKind` is `refused`
+ * - `traceId`: `denied`, `not_available`, `protocol` (all optional)
+ * - `retryAfterSeconds`: `denied`, `protocol` (both optional)
+ * - `transportKind`: `transport`, and any `token` failure whose `tokenKind`
+ *   is `transport`
+ * - `tokenKind`: every `token` failure
+ */
+export declare class EvidenceClientError extends Error {
+  readonly kind: string
+  readonly status?: number
+  readonly code?: string
+  readonly traceId?: string
+  readonly retryAfterSeconds?: number
+  readonly transportKind?: string
+  readonly tokenKind?: string
+}

package/evidence/client.js

@@ -0,0 +1,239 @@
+'use strict';
+
+// The package's actual entry point. `index.js`/`index.d.ts` are regenerated
+// by `napi build --platform` on every build (see `package.json`'s `build`
+// and `build:debug` scripts) and stay untouched here; this file sits on top
+// of them so a hand edit never gets silently overwritten by the next build.
+
+const native = require('./index');
+
+/**
+ * The stable eight-kind error envelope every mapped Evidence Node failure
+ * carries (see `crates/registry-evidence-client-node/src/convert.rs`'s
+ * `map_client_error`), as properties on a thrown `Error` rather than as JSON
+ * text a caller has to `JSON.parse` out of `.message`.
+ *
+ * `kind` is always present; `status`, `code`, `traceId`,
+ * `retryAfterSeconds`, `transportKind`, and `tokenKind` are present only when
+ * the underlying failure carries them.
+ */
+class EvidenceClientError extends Error {
+  constructor(envelope) {
+    super(envelope.message);
+    this.name = 'EvidenceClientError';
+    this.kind = envelope.kind;
+    for (const field of [
+      'status',
+      'code',
+      'traceId',
+      'retryAfterSeconds',
+      'transportKind',
+      'tokenKind',
+    ]) {
+      if (envelope[field] !== undefined) {
+        this[field] = envelope[field];
+      }
+    }
+  }
+}
+
+/**
+ * The native layer throws every mapped Evidence failure as an ordinary
+ * `Error` whose `message` is the JSON envelope described above
+ * (`src/lib.rs`'s `to_napi_error`). Every other native failure (a
+ * serialization defect, a caught panic, napi's own argument-type checking)
+ * throws a plain, non-JSON reason instead, and is left exactly as thrown:
+ * only a recognized envelope becomes an `EvidenceClientError`, so a caller
+ * cannot mistake "some other native failure" for one of the eight stable
+ * kinds.
+ */
+function normalize(error) {
+  if (!(error instanceof Error) || typeof error.message !== 'string') {
+    return error;
+  }
+  let envelope;
+  try {
+    envelope = JSON.parse(error.message);
+  } catch {
+    return error;
+  }
+  if (envelope === null || typeof envelope !== 'object' || typeof envelope.kind !== 'string') {
+    return error;
+  }
+  return new EvidenceClientError(envelope);
+}
+
+function wrapSync(prototype, name) {
+  const original = prototype[name];
+  prototype[name] = function (...args) {
+    try {
+      return original.apply(this, args);
+    } catch (error) {
+      throw normalize(error);
+    }
+  };
+}
+
+function wrapAsync(prototype, name) {
+  const original = prototype[name];
+  prototype[name] = function (...args) {
+    return original.apply(this, args).catch((error) => {
+      throw normalize(error);
+    });
+  };
+}
+
+// The public Node API exposes the opaque native result directly, with the
+// encoding tag next to its artifact, so the one-call tutorial can read
+// `result.value`. Its getters stay native: notably, only reading an ambiguous
+// `value` fails.
+function wrapProgressiveRequest(prototype) {
+  const original = prototype.request;
+  prototype.request = function (...args) {
+    try {
+      return original.apply(this, args).then(
+        (result) => result,
+        (error) => {
+          throw normalize(error);
+        },
+      );
+    } catch (error) {
+      throw normalize(error);
+    }
+  };
+}
+
+function wrapGetter(prototype, name) {
+  const descriptor = Object.getOwnPropertyDescriptor(prototype, name);
+  const originalGet = descriptor.get;
+  Object.defineProperty(prototype, name, {
+    ...descriptor,
+    get() {
+      try {
+        return originalGet.call(this);
+      } catch (error) {
+        throw normalize(error);
+      }
+    },
+  });
+}
+
+// Patch the native prototypes directly, in place, rather than wrapping
+// instances in a delegating object or a `Proxy`: only the throw/reject path
+// is touched here, so every argument and return value crossing these methods
+// keeps its exact native identity. This matters concretely for `send`'s
+// single-send guard: it depends on the `PreparedEvidenceRequest` object
+// handed back to a later `send`/`verify` call being the very same native
+// object `prepare` returned, not a copy or a wrapper around it (see
+// `__test__/happy-path.test.js`'s single-send-guard test, which asserts this
+// identity directly).
+wrapSync(native.EvidenceClient.prototype, 'prepare');
+wrapSync(native.EvidenceClient.prototype, 'prepareBatch');
+wrapAsync(native.EvidenceClient.prototype, 'discover');
+wrapAsync(native.EvidenceClient.prototype, 'fetchJwks');
+wrapAsync(native.EvidenceClient.prototype, 'send');
+wrapAsync(native.EvidenceClient.prototype, 'sendBatch');
+wrapSync(native.EvidenceClient.prototype, 'verify');
+wrapSync(native.EvidenceClient.prototype, 'verifyBatch');
+wrapAsync(native.EvidenceClient.prototype, 'requestAndVerify');
+wrapAsync(native.EvidenceClient.prototype, 'requestAndVerifyBatch');
+wrapProgressiveRequest(native.EvidenceClient.prototype);
+wrapAsync(native.EvidenceClient.prototype, 'refreshMetadata');
+wrapSync(native.EvidenceClient.prototype, 'verifyAsOf');
+wrapSync(native.EvidenceClient.prototype, 'verifyBatchAsOf');
+
+wrapGetter(native.PreparedEvidenceRequest.prototype, 'requestNonce');
+wrapGetter(native.PreparedEvidenceRequest.prototype, 'policyDocument');
+wrapGetter(native.PreparedEvidenceRequest.prototype, 'subjectExpectations');
+
+wrapGetter(native.PreparedEvidenceRequestBatch.prototype, 'requestNonces');
+wrapGetter(native.PreparedEvidenceRequestBatch.prototype, 'policyDocuments');
+wrapGetter(native.PreparedEvidenceRequestBatch.prototype, 'subjectExpectations');
+wrapGetter(native.PreparedEvidenceRequestBatch.prototype, 'count');
+
+wrapGetter(native.RawEvidenceResponse.prototype, 'body');
+wrapGetter(native.RawEvidenceResponse.prototype, 'traceId');
+
+wrapGetter(native.RawEvidenceRequestBatchResponse.prototype, 'body');
+wrapGetter(native.RawEvidenceRequestBatchResponse.prototype, 'traceId');
+
+for (const name of [
+  'responseFormat',
+  'evidence',
+  'traceId',
+  'assertion',
+  'credential',
+  'values',
+  'value',
+  'subjectContinuity',
+]) {
+  wrapGetter(native.AudienceScopedResult.prototype, name);
+}
+
+wrapSync(native.SdJwtVcBatchResponse.prototype, 'credentialForHolderKey');
+wrapGetter(native.SdJwtVcBatchResponse.prototype, 'credentials');
+wrapGetter(native.SdJwtVcBatchResponse.prototype, 'count');
+
+/**
+ * The two classes this module wraps rather than patches in place: a
+ * constructor's own throw happens before any instance exists, so there is no
+ * prototype method to patch ahead of time the way there is for every other
+ * method above.
+ *
+ * Subclassing is safe here in a way it would not be for
+ * `PreparedEvidenceRequest`: nothing hands an `EvidenceClient` or an
+ * `SdJwtVcBatchResponse` back into a later native call for an identity check
+ * to depend on, and every prototype member above is already patched on the
+ * native prototype, which these subclasses inherit unchanged, so
+ * `instanceof native.EvidenceClient` still holds for their instances.
+ */
+class EvidenceClient extends native.EvidenceClient {
+  constructor(config) {
+    try {
+      super(config);
+    } catch (error) {
+      throw normalize(error);
+    }
+  }
+
+  /**
+   * Construct the progressive client from an application-owned profile.
+   *
+   * The native implementation reads the profile, resolves any secret
+   * reference, discovers metadata, and owns every trust decision. Keeping
+   * that work below this wrapper is intentional: JavaScript never receives a
+   * key set or a subject-continuity store to accidentally retain.
+   */
+  static fromProfile(path, privateKeyJwk) {
+    try {
+      const client = privateKeyJwk === undefined
+        ? native.EvidenceClient.fromProfile(path)
+        : native.EvidenceClient.fromProfile(path, privateKeyJwk);
+      Object.setPrototypeOf(client, this.prototype);
+      return client;
+    } catch (error) {
+      throw normalize(error);
+    }
+  }
+}
+
+class SdJwtVcBatchResponse extends native.SdJwtVcBatchResponse {
+  constructor(body) {
+    try {
+      super(body);
+    } catch (error) {
+      throw normalize(error);
+    }
+  }
+}
+
+module.exports = {
+  EvidenceClient,
+  EvidenceClientError,
+  PreparedEvidenceRequest: native.PreparedEvidenceRequest,
+  PreparedEvidenceRequestBatch: native.PreparedEvidenceRequestBatch,
+  RawEvidenceResponse: native.RawEvidenceResponse,
+  RawEvidenceRequestBatchResponse: native.RawEvidenceRequestBatchResponse,
+  AudienceScopedResult: native.AudienceScopedResult,
+  SdJwtVcBatchResponse,
+};