@europeum-ebsi/cli 0.0.0 → 1.0.0-rc.0

package/src/config/config.ts

@@ -0,0 +1,275 @@
+import envPaths from "env-paths";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+import type { KeyAlgorithm } from "../crypto/wallet.ts";
+
+/**
+ * Supported EBSI environments
+ */
+export type EbsiEnv = "local" | "pilot" | "preprod" | "prod" | "test";
+
+/**
+ * All known EBSI environment names
+ */
+export const EBSI_ENVS: EbsiEnv[] = [
+  "local",
+  "test",
+  "pilot",
+  "preprod",
+  "prod",
+];
+
+/**
+ * Default base URLs (including /v1) for the environments that have a single
+ * well-known API host.
+ *
+ * `preprod` and `prod` are deliberately absent: every node operator serves the
+ * API under a domain of their own choosing (`api-preprod.ebsi.<domain>` /
+ * `api.ebsi.<domain>`), so those environments must always be paired with an
+ * explicit `--base-url` / `EBSI_API_BASE_URL`.
+ */
+export const ENV_BASE_URLS: Partial<Record<EbsiEnv, string>> = {
+  local: "http://localhost:3000/v1",
+  pilot: "https://api-pilot.ebsi.eu/v1",
+  test: "https://api-test.testnode02.ebsi.eu/v1",
+};
+
+export interface CliConfig {
+  baseUrl: string;
+  /**
+   * EBSI DID (did:ebsi:...) associated with the private key(s).
+   */
+  did?: string;
+  /**
+   * EBSI environment the CLI targets. Always one of `EBSI_ENVS`, even when the
+   * base URL is overridden: it names the EBSI network credentials and URIs
+   * are minted for.
+   */
+  env: EbsiEnv;
+  /**
+   * Secp256k1 private key hex (0x-prefixed). Mandatory for anything that
+   * signs: always signs Ethereum transactions, and signs VCs/VPs unless
+   * `signAlg` is "ES256".
+   */
+  es256kPrivateKey?: string;
+  /**
+   * P-256 private key hex, for signing VCs/VPs. Optional — used instead of
+   * the mandatory secp256k1 key only when `signAlg` (or an explicit choice)
+   * picks ES256.
+   */
+  es256PrivateKey?: string;
+  output: OutputFormat;
+  /**
+   * Which key signs VCs/VPs when both `es256kPrivateKey` and
+   * `es256PrivateKey` are configured. Required in that case — see
+   * `WalletDetails.signingKey()` in `crypto/wallet.ts`.
+   */
+  signAlg?: KeyAlgorithm;
+  /**
+   * Bearer access token attached to every request as `Authorization: Bearer <token>`.
+   */
+  token?: string;
+}
+
+export type OutputFormat = "json" | "pretty" | "table";
+export const OUTPUT_FORMATS: OutputFormat[] = ["pretty", "json", "table"];
+
+export const SIGN_ALGS: KeyAlgorithm[] = ["ES256", "ES256K"];
+
+/**
+ * Persisted config file shape
+ */
+interface PersistedConfig {
+  baseUrl?: string;
+  did?: string;
+  env?: EbsiEnv;
+  es256kPrivateKey?: string;
+  es256PrivateKey?: string;
+  output?: OutputFormat;
+  signAlg?: KeyAlgorithm;
+  token?: string;
+}
+
+const APP_NAME = "ebsi-cli";
+const paths = envPaths(APP_NAME, { suffix: "" });
+const CONFIG_FILE = path.join(paths.config, "config.json");
+
+export function getConfigFilePath(): string {
+  return CONFIG_FILE;
+}
+
+export function getPersistedConfigValue(
+  key: keyof PersistedConfig,
+): string | undefined {
+  const persisted = readPersistedConfig();
+  const value = persisted[key];
+  return value ?? undefined;
+}
+
+/**
+ * Resolves the active CLI config.
+ *
+ * The environment and the base URL are resolved separately: `env` always
+ * names the EBSI network (used for credentials and `ebsi:` URIs), while
+ * `baseUrl` only says which API host to call. Overriding one never affects
+ * the other.
+ *
+ * Resolution order (highest wins):
+ *   env:     --env flag > EBSI_ENV > persisted config > "test"
+ *   baseUrl: --base-url flag > EBSI_API_BASE_URL > ENV_BASE_URLS[env]
+ *
+ * Throws when the resolved env has no default URL (`preprod`, `prod`) and
+ * none was supplied.
+ */
+export function resolveConfig(
+  overrides: {
+    baseUrl?: string;
+    did?: string;
+    env?: string;
+    es256Key?: string;
+    es256kKey?: string;
+    output?: string;
+    signAlg?: string;
+    token?: string;
+  },
+  opts: { allowLegacyPrivateKey?: boolean } = {},
+): CliConfig {
+  const persisted = readPersistedConfig();
+
+  if (!opts.allowLegacyPrivateKey) {
+    assertNotLegacyPrivateKey(persisted);
+  }
+
+  // Output format
+  const output = (overrides.output ??
+    process.env["EBSI_OUTPUT"] ??
+    persisted.output ??
+    "pretty") as OutputFormat;
+
+  // Bearer token: flag → env var → persisted
+  const token =
+    overrides.token ?? process.env["EBSI_ACCESS_TOKEN"] ?? persisted.token;
+
+  // Secp256k1 key: flag → env var → persisted
+  const es256kPrivateKey =
+    overrides.es256kKey ??
+    process.env["EBSI_ES256K_PRIVATE_KEY"] ??
+    persisted.es256kPrivateKey;
+
+  // P-256 key (optional): flag → env var → persisted
+  const es256PrivateKey =
+    overrides.es256Key ??
+    process.env["EBSI_ES256_PRIVATE_KEY"] ??
+    persisted.es256PrivateKey;
+
+  // Which key signs VCs/VPs when both are configured: flag → env var → persisted
+  const signAlg = validateSignAlg(
+    overrides.signAlg ?? process.env["EBSI_SIGN_ALG"] ?? persisted.signAlg,
+  );
+
+  // DID: flag → env var → persisted
+  const did = overrides.did ?? process.env["EBSI_DID"] ?? persisted.did;
+
+  // Env selection (flag > env var > persisted > default)
+  const envName = overrides.env ?? process.env["EBSI_ENV"] ?? persisted.env;
+  const env = isEbsiEnv(envName) ? envName : "test";
+
+  // Base URL: flag > env var > env default
+  const baseUrl =
+    overrides.baseUrl ?? process.env["EBSI_API_BASE_URL"] ?? ENV_BASE_URLS[env];
+  if (baseUrl === undefined) {
+    throw new Error(
+      `The "${env}" environment has no default API base URL: ` +
+        "pass --base-url <url> or set EBSI_API_BASE_URL.",
+    );
+  }
+
+  return {
+    baseUrl,
+    env,
+    output,
+    ...(token !== undefined && { token }),
+    ...(es256kPrivateKey !== undefined && { es256kPrivateKey }),
+    ...(es256PrivateKey !== undefined && { es256PrivateKey }),
+    ...(signAlg !== undefined && { signAlg }),
+    ...(did !== undefined && { did }),
+  };
+}
+
+export function setPersistedConfigValue(
+  key: keyof PersistedConfig,
+  value: string,
+): void {
+  const persisted: PersistedConfig & { privateKey?: string } =
+    readPersistedConfig();
+  // Validated by callers
+  (persisted as Record<string, string>)[key] = value;
+  // Drop the pre-rename `privateKey` field on any write, so a single
+  // `ebsi config set <key> <value>` call (now reachable even with a legacy
+  // key present — see `allowLegacyPrivateKey`) permanently clears the
+  // condition `assertNotLegacyPrivateKey` checks for, instead of the user
+  // being stuck re-triggering it on every subsequent command.
+  delete persisted.privateKey;
+  writePersistedConfig(persisted);
+}
+
+export function writePersistedConfig(config: PersistedConfig): void {
+  mkdirSync(paths.config, { recursive: true });
+  writeFileSync(
+    CONFIG_FILE,
+    JSON.stringify(config, undefined, 2) + "\n",
+    "utf8",
+  );
+}
+
+/**
+ * `EBSI_PRIVATE_KEY` / the persisted `privateKey` entry were renamed to
+ * `EBSI_ES256K_PRIVATE_KEY` / `es256kPrivateKey`. Rather than silently
+ * ignoring a key the user still has configured under the old name, fail
+ * loudly so a stale env var or config file doesn't look like "no key found".
+ */
+function assertNotLegacyPrivateKey(
+  persisted: PersistedConfig & { privateKey?: string },
+): void {
+  if (
+    process.env["EBSI_PRIVATE_KEY"] === undefined &&
+    persisted.privateKey === undefined
+  ) {
+    return;
+  }
+  throw new Error(
+    "EBSI_PRIVATE_KEY has been renamed to EBSI_ES256K_PRIVATE_KEY. " +
+      "The CLI now takes a mandatory secp256k1 key (EBSI_ES256K_PRIVATE_KEY, " +
+      "signs Ethereum transactions) and an optional P-256 key " +
+      "(EBSI_ES256_PRIVATE_KEY, signs VCs/VPs). " +
+      "If a persisted config file still has a `privateKey` entry, run " +
+      "`ebsi config set es256kPrivateKey <hex>` to migrate it (allowed even " +
+      "while this error is otherwise showing) — it also clears the old entry. " +
+      "Otherwise, unset the EBSI_PRIVATE_KEY environment variable.",
+  );
+}
+
+function isEbsiEnv(value: string | undefined): value is EbsiEnv {
+  return EBSI_ENVS.includes(value as EbsiEnv);
+}
+
+function readPersistedConfig(): PersistedConfig {
+  if (!existsSync(CONFIG_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(CONFIG_FILE, "utf8")) as PersistedConfig;
+  } catch {
+    return {};
+  }
+}
+
+function validateSignAlg(value: string | undefined): KeyAlgorithm | undefined {
+  if (value === undefined) return undefined;
+  const normalized = value.toUpperCase();
+  if (!SIGN_ALGS.includes(normalized as KeyAlgorithm)) {
+    throw new Error(
+      `Invalid sign algorithm "${value}". Valid values: ${SIGN_ALGS.join(", ")}`,
+    );
+  }
+  return normalized as KeyAlgorithm;
+}

package/src/config/ebsi-env.ts

@@ -0,0 +1,67 @@
+import type { EbsiEnvConfiguration } from "@europeum-ebsi/verifiable-credential";
+
+import type { CliConfig, EbsiEnv } from "./config.ts";
+
+const EBSI_SERVICES = [
+  "did-registry",
+  "track-and-trace",
+  "contracts-registry",
+  "issuers-registry",
+  "policies-registry",
+  "schemas-registry",
+] as const;
+
+/**
+ * Builds an `EbsiEnvConfiguration` from the CLI config.
+ *
+ * Shared by the VP signing path (`auth/token.ts`) and the onboarding VC
+ * builder (`onboarding/vc.ts`), so a credential and the presentation carrying
+ * it can never disagree about which EBSI network they belong to.
+ *
+ * When callers pass `skipValidation: true` the lib skips DID resolution, so
+ * the config only needs to be structurally valid.
+ */
+export function buildEbsiEnvConfig(config: CliConfig): EbsiEnvConfiguration {
+  const url = new URL(config.baseUrl);
+  // The CLI always uses /v1; cast to the ApiVersion literal type expected by EbsiEnvConfiguration
+  const version = (url.pathname.split("/").find(Boolean) ??
+    "v1") as `v${number}`;
+
+  return {
+    hosts: [url.hostname],
+    // Production URIs carry no network segment (mirrors the API's own
+    // `isOptional: NETWORK === "production"` in `api/src/config/configuration.ts`).
+    network: {
+      isOptional: config.env === "prod",
+      name: resolveNetworkName(config.env),
+    },
+    scheme: "ebsi",
+    services: [...EBSI_SERVICES],
+    version,
+  };
+}
+
+/**
+ * Maps the configured environment label onto the EBSI network name the API
+ * expects in `ebsi:` URIs. Most labels are used verbatim; the exceptions:
+ *
+ * - "prod" is the network the API calls "production" (`NETWORK=production`).
+ * - "local" is an API base URL, not an EBSI network: the local stack runs the
+ *   API with `NETWORK=test` (see `api/.env.default.local`), so every `ebsi:`
+ *   URI it accepts — and every one it mints — names "test". Emitting "local"
+ *   makes the API reject the CLI's own credentials with
+ *   "Invalid URI: network must be 'test'".
+ */
+function resolveNetworkName(env: EbsiEnv): string {
+  switch (env) {
+    case "local": {
+      return "test";
+    }
+    case "prod": {
+      return "production";
+    }
+    default: {
+      return env;
+    }
+  }
+}

package/src/crypto/wallet.ts

@@ -0,0 +1,291 @@
+import type { EbsiIssuer } from "@europeum-ebsi/verifiable-credential";
+
+import {
+  bytesToBase64url,
+  ES256KSigner,
+  ES256Signer,
+  hexToBytes,
+} from "@europeum-ebsi/did-jwt";
+import { EbsiWallet } from "@europeum-ebsi/wallet";
+import { ethers } from "ethers";
+import { calculateJwkThumbprint } from "jose";
+
+export interface DeriveWalletKeys {
+  /**
+   * secp256k1 private key hex (0x-prefixed), mandatory.
+   */
+  es256kPrivateKey: string;
+  /**
+   * P-256 private key hex, optional. Enables `--sign-alg ES256`.
+   */
+  es256PrivateKey?: string;
+  /**
+   * Which curve signs VCs/VPs when both keys are given. See
+   * `WalletDetails.signingKey`.
+   */
+  signAlg?: KeyAlgorithm;
+}
+
+/**
+ * The two curves the CLI's wallet signs over: ES256K (secp256k1, the ledger
+ * key) and ES256 (P-256, VCs/VPs only). Not imported from
+ * `@europeum-ebsi/wallet` -- its `KeyAlgorithm` isn't re-exported through
+ * that package's public entry point.
+ */
+export type KeyAlgorithm = "ES256" | "ES256K";
+
+/**
+ * One curve's signing identity: everything needed to sign a JWT (VC or VP)
+ * as this key, plus the JWK thumbprint the DID document's verification
+ * method id is keyed by.
+ */
+export interface KeyMaterial {
+  alg: KeyAlgorithm;
+  issuer: EbsiIssuer;
+  /**
+   * DID key id: `${did}#${thumbprint}`
+   */
+  kid: string;
+  publicKeyJwk: JwkEcKey;
+  /**
+   * RFC 7638 JWK thumbprint (SHA-256 of canonical JWK, base64url). This is
+   * the verification method id the DID document registers for this key (see
+   * `generateDidParams`'s `vMethodId` in `contracts/deploy-toolkit`).
+   */
+  thumbprint: string;
+}
+
+export interface WalletDetails {
+  /**
+   * Ethereum address derived from the secp256k1 key (the on-chain controller
+   * address).
+   */
+  address: string;
+  /**
+   * EBSI DID (did:ebsi:...)
+   */
+  did: string;
+  /**
+   * The P-256 key material, when this wallet was also given one — for
+   * signing verifiable credentials/presentations alongside the secp256k1
+   * ledger key.
+   */
+  es256?: KeyMaterial;
+  /**
+   * The secp256k1 (ES256K) key material — the ledger key, required by every
+   * wallet.
+   */
+  es256k: KeyMaterial;
+  /**
+   * Picks the key that signs VCs/VPs:
+   * - `signAlg` names a curve → that curve's key (throws if it isn't configured)
+   * - no `signAlg`, no ES256 key → the ES256K key (today's behaviour)
+   * - no `signAlg`, both keys configured → throws — the caller must choose
+   *
+   * A method rather than a field so commands that never sign a VC/VP (`wallet
+   * info`, a plain `ledger read`, ...) keep working with both keys configured
+   * and no `--sign-alg`.
+   */
+  signingKey(): KeyMaterial;
+  /**
+   * ethers Wallet for Ethereum transaction signing — always the secp256k1
+   * key; a P-256 key cannot sign Ethereum transactions.
+   */
+  wallet: ethers.Wallet;
+}
+
+/**
+ * A JWK EC public key, as returned by `EbsiWallet.formatPublicKey(..., "jwk", ...)`.
+ * Declared locally for the same reason as `KeyAlgorithm` above -- only the
+ * fields this module actually uses.
+ */
+interface JwkEcKey {
+  crv: "P-256" | "secp256k1";
+  kty: "EC";
+  x: string;
+  y: string;
+}
+
+/**
+ * Derives a P-256 (ES256) `EbsiIssuer` for a DID that already exists.
+ *
+ * Kept as a thin wrapper around `deriveEs256KeyMaterial` for the RTAO issuing
+ * flow (`onboarding/vc.ts`), which signs as a *different* identity than the
+ * CLI's own wallet and has always taken its P-256 key separately (see
+ * `--rtao-es256-key`).
+ */
+export async function deriveEs256Issuer(
+  privateKeyHex: string,
+  did: string,
+): Promise<EbsiIssuer<"ES256">> {
+  const { issuer } = await deriveEs256KeyMaterial(privateKeyHex, did);
+  return issuer as EbsiIssuer<"ES256">;
+}
+
+/**
+ * Derives wallet details from a mandatory secp256k1 private key, and an
+ * optional P-256 private key alongside it.
+ *
+ * The secp256k1 key always serves dual purpose (mirrors API's `createUser()`
+ * pattern): an `ethers.Wallet` for on-chain transaction signing, and an
+ * ES256K JWT signer for VC/VP signing. The P-256 key, when given, is only
+ * ever a JWT signer.
+ *
+ * If `overrideDid` is not provided a fresh random EBSI DID is generated.
+ *
+ * @throws If either key is malformed (not 32 bytes of hex, or not a valid
+ * private key for its curve) — validated via `EbsiWallet`'s constructor.
+ */
+export async function deriveWallet(
+  keys: DeriveWalletKeys,
+  overrideDid?: string,
+): Promise<WalletDetails> {
+  const { es256kPrivateKey, es256PrivateKey, signAlg } = keys;
+
+  // Validates both keys (32 bytes of hex, valid scalar for their curve)
+  // before any derivation happens. EbsiWallet strips a leading "0x" itself.
+  new EbsiWallet({
+    ES256KPrivateKey: es256kPrivateKey,
+    ...(es256PrivateKey !== undefined && {
+      ES256PrivateKey: es256PrivateKey,
+    }),
+  });
+
+  const { publicKeyJwk, wallet } = deriveEs256kPublicMaterial(es256kPrivateKey);
+  const thumbprint = await calculateJwkThumbprint(publicKeyJwk);
+  const did = overrideDid ?? EbsiWallet.createDid();
+  const kid = `${did}#${thumbprint}`;
+  // hexToBytes handles "0x" prefix
+  const pkBytes = hexToBytes(wallet.privateKey);
+
+  const es256k: KeyMaterial = {
+    alg: "ES256K",
+    issuer: { alg: "ES256K", did, kid, signer: ES256KSigner(pkBytes) },
+    kid,
+    publicKeyJwk,
+    thumbprint,
+  };
+
+  const es256 =
+    es256PrivateKey === undefined
+      ? undefined
+      : await deriveEs256KeyMaterial(es256PrivateKey, did);
+
+  return {
+    address: wallet.address,
+    did,
+    ...(es256 !== undefined && { es256 }),
+    es256k,
+    signingKey: () => pickSigningKey(es256k, es256, signAlg),
+    wallet,
+  };
+}
+
+/**
+ * Generate a new random private key (0x-prefixed hex string).
+ * @param algorithm - Curve to generate on ("ES256K", secp256k1, default; or
+ * "ES256", P-256)
+ */
+export function generatePrivateKey(algorithm: KeyAlgorithm = "ES256K"): string {
+  if (algorithm === "ES256") {
+    const { privateKey } = EbsiWallet.generateKeyPair({ algorithm: "ES256" });
+    return addPrefix(privateKey);
+  }
+  return ethers.Wallet.createRandom().privateKey;
+}
+
+function addPrefix(hex: string): string {
+  return hex.startsWith("0x") ? hex : `0x${hex}`;
+}
+
+/**
+ * Derives a P-256 (ES256) `KeyMaterial` for a DID that already exists.
+ *
+ * Unlike the secp256k1 derivation this has no ledger counterpart -- a P-256
+ * key can't sign Ethereum transactions.
+ */
+async function deriveEs256KeyMaterial(
+  privateKeyHex: string,
+  did: string,
+): Promise<KeyMaterial> {
+  const publicKeyHex = EbsiWallet.getPublicKeyHex(privateKeyHex, "ES256");
+  const publicKeyJwk = EbsiWallet.formatPublicKey(publicKeyHex, "jwk", "ES256");
+  const thumbprint = await calculateJwkThumbprint(publicKeyJwk, "sha256");
+  const kid = `${did}#${thumbprint}`;
+
+  return {
+    alg: "ES256",
+    issuer: {
+      alg: "ES256",
+      did,
+      kid,
+      // hexToBytes handles "0x" prefix
+      signer: ES256Signer(hexToBytes(privateKeyHex)),
+    },
+    kid,
+    publicKeyJwk,
+    thumbprint,
+  };
+}
+
+/**
+ * Derives the secp256k1 public key JWK, plus the `ethers.Wallet` used for
+ * Ethereum transaction signing.
+ */
+function deriveEs256kPublicMaterial(privateKeyHex: string): {
+  publicKeyJwk: JwkEcKey;
+  wallet: ethers.Wallet;
+} {
+  const wallet = new ethers.Wallet(privateKeyHex);
+
+  // ethers returns "0x" + "04" (uncompressed prefix) + x(32 bytes=64 hex) + y(32 bytes=64 hex)
+  const uncompressed = ethers.SigningKey.computePublicKey(
+    wallet.signingKey.publicKey,
+    false,
+  );
+  const xHex = uncompressed.slice(4, 68);
+  const yHex = uncompressed.slice(68);
+
+  const publicKeyJwk: JwkEcKey = {
+    crv: "secp256k1",
+    kty: "EC",
+    x: bytesToBase64url(hexToBytes(xHex)),
+    y: bytesToBase64url(hexToBytes(yHex)),
+  };
+
+  return { publicKeyJwk, wallet };
+}
+
+/**
+ * Implements `WalletDetails.signingKey`'s selection rule — see its doc
+ * comment for the full contract.
+ */
+function pickSigningKey(
+  es256k: KeyMaterial,
+  es256: KeyMaterial | undefined,
+  signAlg: KeyAlgorithm | undefined,
+): KeyMaterial {
+  if (signAlg === "ES256") {
+    if (!es256) {
+      throw new Error(
+        "No P-256 key configured. Pass --es256-key <hex>, set " +
+          "EBSI_ES256_PRIVATE_KEY, or run `ebsi config set es256PrivateKey <hex>`.",
+      );
+    }
+    return es256;
+  }
+
+  if (signAlg === "ES256K") {
+    return es256k;
+  }
+
+  if (!es256) {
+    return es256k;
+  }
+
+  throw new Error(
+    "Two signing keys are configured (ES256K and ES256). Choose which one " +
+      "signs VCs/VPs with --sign-alg <ES256|ES256K>, EBSI_SIGN_ALG, or " +
+      "`ebsi config set signAlg <alg>`.",
+  );
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+/**
+ * EBSI CLI entry point.
+ *
+ * - With subcommand arguments: runs in non-interactive Commander mode.
+ * - Without arguments (or with `--interactive`): launches the Ink TUI.
+ */
+
+const args = process.argv.slice(2);
+const isInteractive = args.length === 0 || args[0] === "--interactive";
+
+if (isInteractive) {
+  // Launch Ink interactive TUI
+  const { render } = await import("ink");
+  // eslint-disable-next-line unicorn/no-await-expression-member
+  const React = (await import("react")).default;
+  const { App } = await import("./tui/App.tsx");
+  render(React.createElement(App, {}));
+} else {
+  // Non-interactive Commander mode
+  const { buildProgram } = await import("./cli.ts");
+  const program = buildProgram();
+  await program.parseAsync(process.argv);
+}