@thirtified/eudi-dev 0.0.0-stage → 0.1.1

package/src/runner.ts

@@ -0,0 +1,310 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { EudiDevError, lastLine } from './errors.js';
+import { type FileInput, type Input, isPathInput, isUrlInput } from './input.js';
+
+export interface RunOptions {
+  /** Written to the process's stdin. Without it stdin is closed (/dev/null). */
+  stdin?: string | Uint8Array | undefined;
+  /** Kill the process after this many milliseconds. Default: the runner's timeout. */
+  timeoutMs?: number | undefined;
+  /** Aborts the process. */
+  signal?: AbortSignal | undefined;
+  /** Add `--json` and parse stdout as one JSON document. Default `true`. */
+  json?: boolean | undefined;
+}
+
+export interface RunResult<T = unknown> {
+  /** The parsed stdout document (`undefined` with `json: false` or empty stdout). */
+  document: T;
+  stdout: string;
+  /** Progress, hints and warnings. With `--json` nothing else goes to stdout. */
+  stderr: string;
+}
+
+export interface RunnerConfig {
+  bin: string;
+  /** Becomes EUDI_DEV_HOME. */
+  home: string;
+  /** Extra environment for every call. `undefined` removes a variable. */
+  env?: Record<string, string | undefined> | undefined;
+  /**
+   * Pass the caller's EUDI_DEV_* variables through to the binary. Default
+   * `false`: they are removed so that a developer's shell setup
+   * (EUDI_DEV_STORAGE, EUDI_DEV_SEED, ...) can't change test results.
+   */
+  inheritEudiEnv?: boolean | undefined;
+  timeoutMs?: number | undefined;
+  cwd?: string | undefined;
+  /** Upper bound for captured stdout plus stderr. Default 64 MiB. */
+  maxBufferBytes?: number | undefined;
+}
+
+const STRIPPED_LEGACY_VARS = ['OID4VC_DEV_HOME', 'EUDI_REMOTE_TIMEOUT'];
+
+/** Builds the environment for a child process. Exported for tests. */
+export function buildEnv(
+  config: Pick<RunnerConfig, 'home' | 'env' | 'inheritEudiEnv'>,
+  base: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (value === undefined) continue;
+    if (!config.inheritEudiEnv && (key.startsWith('EUDI_DEV_') || STRIPPED_LEGACY_VARS.includes(key))) continue;
+    env[key] = value;
+  }
+  env.EUDI_DEV_HOME = config.home;
+  env.NO_COLOR = '1';
+  for (const [key, value] of Object.entries(config.env ?? {})) {
+    if (value === undefined) delete env[key];
+    else env[key] = value;
+  }
+  return env;
+}
+
+/** Collects flags as `--name=value`, so a value starting with `-` is never read as a flag. */
+export class ArgList {
+  readonly args: string[];
+
+  constructor(...command: string[]) {
+    this.args = [...command];
+  }
+
+  /** `true` → `--name`, `false` → `--name=false`, `undefined` → nothing. */
+  bool(name: string, value: boolean | undefined): this {
+    if (value === true) this.args.push(`--${name}`);
+    else if (value === false) this.args.push(`--${name}=false`);
+    return this;
+  }
+
+  /** Only adds `--name` when `value` is true. For flags that default to false. */
+  on(name: string, value: boolean | undefined): this {
+    if (value) this.args.push(`--${name}`);
+    return this;
+  }
+
+  value(name: string, value: string | number | undefined | null): this {
+    if (value !== undefined && value !== null) this.args.push(`--${name}=${value}`);
+    return this;
+  }
+
+  /** A repeatable flag: one `--name=value` per entry. */
+  repeat(name: string, values: readonly (string | number)[] | undefined): this {
+    for (const v of values ?? []) this.args.push(`--${name}=${v}`);
+    return this;
+  }
+
+  /** A comma-separated single flag. */
+  csv(name: string, values: readonly string[] | undefined): this {
+    if (values && values.length > 0) this.args.push(`--${name}=${values.join(',')}`);
+    return this;
+  }
+
+  push(...args: string[]): this {
+    this.args.push(...args);
+    return this;
+  }
+}
+
+/** Temp files for one call. */
+export class Scratch {
+  private dir: string | undefined;
+  private n = 0;
+
+  /** Writes `content` to a private temp file and returns its path. */
+  async write(name: string, content: string | Uint8Array): Promise<string> {
+    this.dir ??= await mkdtemp(join(tmpdir(), 'eudi-dev-input-'));
+    const path = join(this.dir, `${++this.n}-${name}`);
+    await writeFile(path, content, { mode: 0o600 });
+    return path;
+  }
+
+  /**
+   * Turns a file-valued option into a flag value. Content is written to a temp
+   * file. `{ url }` is only allowed when `allowUrl` is set.
+   */
+  async file(input: FileInput, name: string, opts: { allowUrl?: boolean } = {}): Promise<string> {
+    if (isPathInput(input)) {
+      await assertFile(input.path);
+      return input.path;
+    }
+    if (isUrlInput(input)) {
+      if (!opts.allowUrl) throw new TypeError(`${name} does not accept a URL`);
+      assertHttpUrl(input.url);
+      return input.url;
+    }
+    return this.write(name, input);
+  }
+
+  async cleanup(): Promise<void> {
+    if (this.dir) await rm(this.dir, { recursive: true, force: true });
+    this.dir = undefined;
+  }
+}
+
+async function assertFile(path: string): Promise<void> {
+  let ok = false;
+  try {
+    ok = (await stat(path)).isFile();
+  } catch {
+    ok = false;
+  }
+  // eudi-dev treats a path that doesn't exist as raw input, which hides typos.
+  if (!ok) throw new TypeError(`${path} is not a file`);
+}
+
+function assertHttpUrl(url: string): void {
+  if (!/^https?:\/\//i.test(url)) throw new TypeError(`${url} is not an http(s) URL`);
+}
+
+/** Maps an {@link Input} to the positional argument and the stdin content. */
+export async function positionalInput(input: Input): Promise<{ arg: string; stdin?: string | Uint8Array }> {
+  if (isPathInput(input)) {
+    await assertFile(input.path);
+    return { arg: input.path };
+  }
+  if (isUrlInput(input)) {
+    assertHttpUrl(input.url);
+    return { arg: input.url };
+  }
+  if (typeof input !== 'string' && !(input instanceof Uint8Array)) {
+    throw new TypeError('input must be a string, bytes, { path } or { url }');
+  }
+  return { arg: '-', stdin: input };
+}
+
+/** Spawns the eudi-dev binary with an isolated environment. */
+export class Runner {
+  readonly bin: string;
+  readonly home: string;
+  private readonly config: RunnerConfig;
+
+  constructor(config: RunnerConfig) {
+    this.config = config;
+    this.bin = config.bin;
+    this.home = config.home;
+  }
+
+  /**
+   * Runs `eudi <args> --json --no-color` and parses stdout as exactly one
+   * JSON document. Rejects with {@link EudiDevError} on a non-zero exit, a
+   * timeout, or stdout that is not one JSON document.
+   */
+  async run<T = unknown>(args: readonly string[], opts: RunOptions = {}): Promise<RunResult<T>> {
+    const json = opts.json ?? true;
+    const fullArgs = json ? [...args, '--json', '--no-color'] : [...args, '--no-color'];
+    const { exitCode, signal, stdout, stderr, timedOut, spawnError } = await this.spawn(fullArgs, opts);
+
+    const base = { args: fullArgs, exitCode, signal, stdout, stderr };
+    if (spawnError) {
+      const message =
+        spawnError.name === 'AbortError' ? `eudi ${args[0] ?? ''} was aborted` : `Could not run ${this.bin}: ${spawnError.message}`;
+      throw new EudiDevError(message, { ...base, cause: spawnError });
+    }
+
+    let document: unknown;
+    let parseError: unknown;
+    if (json && stdout.trim() !== '') {
+      try {
+        document = JSON.parse(stdout);
+      } catch (err) {
+        parseError = err;
+      }
+    }
+
+    if (timedOut) {
+      throw new EudiDevError(`eudi ${args[0] ?? ''} timed out`, { ...base, document, timedOut: true });
+    }
+    if (exitCode !== 0) {
+      const reason = lastLine(stderr) || (signal ? `killed by ${signal}` : `exit code ${exitCode}`);
+      throw new EudiDevError(reason, { ...base, document });
+    }
+    if (parseError) {
+      throw new EudiDevError(`eudi ${args.join(' ')} printed stdout that is not one JSON document`, {
+        ...base,
+        cause: parseError,
+      });
+    }
+    return { document: document as T, stdout, stderr };
+  }
+
+  private spawn(
+    args: string[],
+    opts: RunOptions,
+  ): Promise<{
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    spawnError?: Error;
+  }> {
+    const maxBytes = this.config.maxBufferBytes ?? 64 * 1024 * 1024;
+    const timeoutMs = opts.timeoutMs ?? this.config.timeoutMs ?? 60_000;
+
+    return new Promise((resolve) => {
+      const child = spawn(this.bin, args, {
+        cwd: this.config.cwd,
+        env: buildEnv(this.config),
+        stdio: [opts.stdin !== undefined ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+        ...(opts.signal ? { signal: opts.signal } : {}),
+      });
+
+      const out: Buffer[] = [];
+      const err: Buffer[] = [];
+      let bytes = 0;
+      let timedOut = false;
+      let overflow = false;
+      let spawnError: Error | undefined;
+
+      const collect = (sink: Buffer[]) => (chunk: Buffer) => {
+        bytes += chunk.length;
+        if (bytes > maxBytes) {
+          if (!overflow) {
+            overflow = true;
+            child.kill('SIGKILL');
+          }
+          return;
+        }
+        sink.push(chunk);
+      };
+      child.stdout?.on('data', collect(out));
+      child.stderr?.on('data', collect(err));
+
+      const timer =
+        timeoutMs > 0
+          ? setTimeout(() => {
+              timedOut = true;
+              child.kill('SIGKILL');
+            }, timeoutMs)
+          : undefined;
+
+      child.on('error', (e) => {
+        spawnError = e;
+      });
+      child.on('close', (code, signal) => {
+        if (timer) clearTimeout(timer);
+        let stderr = Buffer.concat(err).toString('utf8');
+        if (overflow) stderr += `\n[eudi-dev] output exceeded ${maxBytes} bytes, process killed`;
+        const result = {
+          exitCode: code,
+          signal,
+          stdout: Buffer.concat(out).toString('utf8'),
+          stderr,
+          timedOut,
+        };
+        resolve(spawnError ? { ...result, spawnError } : result);
+      });
+
+      if (opts.stdin !== undefined && child.stdin) {
+        // The process may exit before it reads stdin (for example on a flag error).
+        child.stdin.on('error', () => {});
+        child.stdin.end(opts.stdin);
+      }
+    });
+  }
+}

package/src/types.ts

@@ -0,0 +1,396 @@
+/**
+ * Types for the `--json` documents of eudi-dev v3.
+ *
+ * Written by hand from the Go structs and JSON builders at v3.10.1
+ * (internal/output, internal/validate, internal/statuslist, internal/registrar,
+ * internal/trustedlists, internal/certinfo). Upstream has no OpenAPI or JSON
+ * schema for these documents. Within v3 fields are only added (ADR 0020), so
+ * every object type also accepts unknown keys.
+ */
+
+/** A JSON object whose shape this package does not pin down. */
+export type JsonObject = { [key: string]: unknown };
+
+/** Lets an object carry fields added by later v3 releases. */
+type Open = { [key: string]: unknown };
+
+/**
+ * Like `Partial<T>`, but also accepts an explicit `undefined` under
+ * `exactOptionalPropertyTypes`. Used for objects that callers pass in.
+ */
+export type Loose<T> = { [K in keyof T]?: T[K] | undefined };
+
+// ── Checks ────────────────────────────────────────────────────────────────
+
+export type CheckStatus = 'pass' | 'fail' | 'warning' | 'skipped';
+
+/** Check names, in the order `validate` runs them. */
+export type CheckName =
+  | 'type'
+  | 'expiry'
+  | 'integrity'
+  | 'trusted list'
+  | 'signature'
+  | 'trust'
+  | 'status'
+  | 'certificate revocation'
+  | 'status list signature'
+  | 'haip'
+  | (string & {});
+
+/** The trusted list service behind a passing trust or status list signature check. */
+export interface TrustAnchor extends Open {
+  entry?: string;
+  list_url: string;
+  service: string;
+}
+
+export interface Check extends Open {
+  name: CheckName;
+  status: CheckStatus;
+  detail: string;
+  /** The check was skipped because the validation ran offline. */
+  needsNetwork?: boolean;
+  anchor?: TrustAnchor;
+}
+
+// ── Certificates ──────────────────────────────────────────────────────────
+
+export interface CertificateExtension extends Open {
+  oid?: string;
+  name?: string;
+  critical?: boolean;
+  value?: unknown;
+}
+
+export interface CertificateInfo extends Open {
+  subject: string;
+  issuer: string;
+  serialNumber: string;
+  /** RFC 3339 time. */
+  notBefore: string;
+  /** RFC 3339 time. */
+  notAfter: string;
+  selfSigned: boolean;
+  ca: boolean;
+  maxPathLength?: number;
+  publicKey: string;
+  signatureAlgorithm: string;
+  keyUsage?: string[];
+  extendedKeyUsage?: string[];
+  subjectAltNames?: string[];
+  policies?: string[];
+  crlDistributionPoints?: string[];
+  ocspServers?: string[];
+  issuingCertificateURLs?: string[];
+  subjectKeyId?: string;
+  authorityKeyId?: string;
+  extensions: CertificateExtension[];
+  sha256Fingerprint: string;
+  pem: string;
+}
+
+// ── Decoded credentials ───────────────────────────────────────────────────
+
+export interface Disclosure extends Open {
+  name: string;
+  value: unknown;
+  salt: string;
+  digest: string;
+  isArrayEntry: boolean;
+  /** False for a disclosure whose digest the credential does not reference. */
+  referenced: boolean;
+}
+
+interface DecodedBase extends Open {
+  /** Parser warnings. */
+  warnings?: string[];
+  /** Spec deviations (for example RFC 9901 §7.1 rejection rules). */
+  deviations?: string[];
+  /** The x5c (JWT) or x5chain (mdoc) certificates, leaf first. */
+  certificates?: CertificateInfo[];
+}
+
+export interface DecodedSdJwt extends DecodedBase {
+  format: 'dc+sd-jwt';
+  header: JsonObject;
+  payload: JsonObject;
+  disclosures: Disclosure[];
+  /** The payload with every disclosure applied. */
+  resolvedClaims: JsonObject;
+  keyBindingJWT?: { header: JsonObject; payload: JsonObject };
+}
+
+export interface DecodedJwt extends DecodedBase {
+  format: 'jwt';
+  header: JsonObject;
+  payload: JsonObject;
+}
+
+export interface MdocValidityInfo extends Open {
+  signed?: string;
+  validFrom?: string;
+  validUntil?: string;
+}
+
+export interface DecodedMdoc extends DecodedBase {
+  format: 'mso_mdoc';
+  docType: string;
+  /** namespace → element identifier → value. */
+  claims: Record<string, Record<string, unknown>>;
+  isDeviceResponse?: boolean;
+  responseVersion?: string;
+  responseStatus?: number;
+  mso?: {
+    version: string;
+    digestAlgorithm: string;
+    docType: string;
+    validityInfo?: MdocValidityInfo;
+    status?: unknown;
+    /** namespace → digest id → base64url digest. */
+    valueDigests?: Record<string, Record<string, string>>;
+    deviceKeyInfo?: unknown;
+  } & Open;
+  deviceKey?: unknown;
+  issuerAuth?: unknown;
+}
+
+export interface DecodedCertificates extends Open {
+  format: 'x509';
+  certificates: CertificateInfo[];
+}
+
+export type DecodedCredential = DecodedSdJwt | DecodedJwt | DecodedMdoc | DecodedCertificates;
+
+/**
+ * `decode --json` of a credential or certificate. It runs the decoder's
+ * checks offline-capable, so the result carries `validation.checks`.
+ */
+export type DecodeCredentialResult = DecodedCredential & { validation: { checks: Check[] } };
+
+/**
+ * `decode --json` of an OpenID4VCI offer, an OpenID4VP request or a trusted
+ * list. Their documents are not typed by this package.
+ */
+export type DecodeOtherResult = JsonObject;
+
+export type DecodeResult = DecodeCredentialResult | DecodeOtherResult;
+
+// ── validate ──────────────────────────────────────────────────────────────
+
+export interface SignatureVerification extends Open {
+  signatureValid: boolean;
+  expired: boolean;
+  notYetValid: boolean;
+  algorithm?: string;
+  errors?: string[];
+  /** SD-JWT / JWT. */
+  keyId?: string;
+  issuer?: string;
+  expiresAt?: string;
+  issuedAt?: string;
+  notBefore?: string;
+  /** mdoc. */
+  docType?: string;
+  validFrom?: string;
+  validUntil?: string;
+  signed?: string;
+  warnings?: string[];
+}
+
+export interface StatusResult extends Open {
+  uri: string;
+  index: number;
+  status: number;
+  /** VALID, INVALID, SUSPENDED, an application specific value, or unknown. */
+  statusName: string;
+  isValid: boolean;
+  bitsPerEntry: number;
+  /** "jwt" or "cwt". */
+  format: string;
+  subject?: string;
+  signatureValid?: boolean;
+  trustAnchored: boolean;
+  warnings?: string[];
+  haipFindings?: string[];
+}
+
+export interface CatalogueTrust extends Open {
+  entry: string;
+  category: string;
+  anchored_by?: string;
+  findings?: string[];
+  warnings?: string[];
+}
+
+/** `validate --json`: the decoded credential plus the checks at top level. */
+export type ValidateReport = DecodedCredential & {
+  checks: Check[];
+  verification?: SignatureVerification;
+  status?: StatusResult;
+  trust?: CatalogueTrust;
+  /** Present with `--haip` (empty when there are no findings). */
+  haipFindings?: string[];
+};
+
+// ── dcql ──────────────────────────────────────────────────────────────────
+
+// Also an input (registrar add --dcql), so optional fields accept undefined.
+export interface DcqlClaimQuery extends Open {
+  id?: string | undefined;
+  path: (string | number | null)[];
+  values?: unknown[] | undefined;
+}
+
+export interface DcqlCredentialQuery extends Open {
+  id: string;
+  format: 'dc+sd-jwt' | 'jwt_vc_json' | 'mso_mdoc' | (string & {});
+  meta?: ({ vct_values?: string[] | undefined; doctype_value?: string | undefined } & Open) | undefined;
+  claims?: DcqlClaimQuery[] | undefined;
+  claim_sets?: string[][] | undefined;
+}
+
+export interface DcqlQuery extends Open {
+  credentials: DcqlCredentialQuery[];
+  credential_sets?: unknown[] | undefined;
+}
+
+// ── issue ─────────────────────────────────────────────────────────────────
+
+/** `issue <format> --json`. `id` is set only when the wallet stored the credential. */
+export interface IssueDocument extends Open {
+  credential: string;
+  id?: string;
+}
+
+// ── version ───────────────────────────────────────────────────────────────
+
+export interface VersionInfo extends Open {
+  name: string;
+  version: string;
+}
+
+// ── trust ─────────────────────────────────────────────────────────────────
+
+export interface TrustEntity extends Open {
+  id: string;
+  list: string;
+  name: string;
+  certificates: unknown[];
+}
+
+export interface TrustListLink extends Open {
+  url: string;
+  configured?: boolean;
+  via?: string;
+  error?: string;
+}
+
+/** `trust list --json`. */
+export interface TrustOverview extends Open {
+  entities: TrustEntity[];
+  entity_lists: string[];
+  lists: TrustListLink[];
+  lists_url: string;
+  relying_party_cas?: string[];
+  trusted_list_cas?: string[];
+  trust_lists: ({ id: string; default?: boolean; category?: string; path?: string } & Open)[];
+}
+
+/** A JWKS document as `trust ca-cert --jwks` prints it. */
+export interface Jwks extends Open {
+  keys: JsonObject[];
+}
+
+// ── registrar ─────────────────────────────────────────────────────────────
+
+export interface RegistrarIdentifier extends Open {
+  identifier: string;
+  type?: string;
+}
+
+export interface MultiLangString extends Open {
+  lang?: string;
+  content?: string;
+}
+
+export interface IntendedUse extends Open {
+  intendedUseIdentifier: string;
+  purpose: MultiLangString[];
+  privacyPolicy: unknown[];
+  createdAt: string;
+  credentials: unknown[];
+}
+
+export interface ProvidedAttestation extends Open {
+  format: string;
+  type: string;
+}
+
+export interface RelyingPartyService extends Open {
+  serviceTradeName: string;
+  serviceIdentifier?: string;
+  supportURI?: string;
+  srvDescription?: unknown;
+  entitlements: string[];
+  providesAttestations?: ProvidedAttestation[];
+  credentialIssuer?: string;
+  isIntermediary: boolean;
+  intendedUses?: IntendedUse[];
+}
+
+export interface RelyingParty extends Open {
+  identifier: RegistrarIdentifier[];
+  legalPerson: { legalName: string[] } & Open;
+  country: string;
+  tradeName?: string;
+  isPSB: boolean;
+  supervisoryAuthority: JsonObject;
+  registryURI: string;
+  services: RelyingPartyService[];
+}
+
+export interface RegistrationCertificateResult extends Open {
+  /** The bare registration certificate JWT (typ rc-wrp+jwt). */
+  registrationCertificate: string;
+  /** JSON array as a string, ready for a request's verifier_info parameter. */
+  verifierInfo?: string;
+  /** JSON array as a string, ready for the issuer metadata's issuer_info. */
+  issuerInfo?: string;
+}
+
+export interface AccessCertificateResult extends Open {
+  /** PEM leaf. */
+  certificate: string;
+  /** PEM leaf followed by the issuing CA. */
+  chain: string;
+  clientIds: string[];
+}
+
+export interface AccessCertificateRequest extends Open {
+  identifier?: string | undefined;
+  serviceIdentifier?: string | undefined;
+  csr: string;
+  dnsNames?: string[] | undefined;
+  validity?: string | undefined;
+}
+
+/** Input of `registrar enrol`, as for POST /api/registrar/enrolments. */
+export interface Enrolment extends Open {
+  relyingParty: Loose<RelyingParty> & Open;
+  access?: AccessCertificateRequest | undefined;
+  registration?: JsonObject | undefined;
+}
+
+export interface EnrolmentResult extends Open {
+  relyingParty: RelyingParty;
+  access?: AccessCertificateResult;
+  registration?: RegistrationCertificateResult;
+}
+
+/** `registrar verifiers add --to` / `registrar issuers add --to`. */
+export interface RegistrationExtensionResult extends Open {
+  relyingParty: RelyingParty;
+  intendedUse?: string;
+  registration: RegistrationCertificateResult | null;
+}