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

package/src/auth/token.ts

@@ -0,0 +1,244 @@
+import { createVerifiablePresentationJwt } from "@europeum-ebsi/verifiable-presentation/vcdm11.js";
+import { decodeJwt } from "jose";
+import { randomUUID } from "node:crypto";
+
+import type { CliConfig } from "../config/config.ts";
+import type { WalletDetails } from "../crypto/wallet.ts";
+
+import { buildEbsiEnvConfig } from "../config/ebsi-env.ts";
+import {
+  buildDcqlVpToken,
+  createSelfAttestationVcJwt,
+  dcqlCredentialQueryId,
+} from "./dcql.ts";
+import {
+  buildPresentationSubmission,
+  requiresVc,
+  scopeFamilies,
+} from "./presentation.ts";
+
+const DID_REGISTRY_INVITE_FAMILY = "did-registry:invite";
+
+export interface GetAccessTokenOptions {
+  config: CliConfig;
+  scope: string;
+  /**
+   * Which OpenID4VP grant to speak: `"draft14"` (default), the legacy
+   * Presentation Exchange grant, or `"1.0"`, the final DCQL grant. Both are
+   * accepted side by side by the Authorisation service; this only picks
+   * which one the CLI itself sends.
+   */
+  spec?: "1.0" | "draft14";
+  vcJwt?: string;
+  wallet: WalletDetails;
+}
+
+/**
+ * Obtains an EBSI access token via the OIDC4VP `vp_token` grant flow.
+ *
+ * Mirrors the behaviour of `getAccessToken.ts` from the API test helpers.
+ *
+ * @param opts.scope  - The EBSI scope string, e.g. "did-registry:write" or "issuers-registry:invite"
+ * @param opts.spec   - Which grant to speak: "draft14" (default, legacy PEX) or "1.0" (DCQL)
+ * @param opts.vcJwt  - A VC JWT to include in the VP (required for VC-required scopes)
+ * @param opts.wallet - Resolved wallet details; `wallet.signingKey()` picks the
+ * key that signs the VP (throws if both an ES256K and an ES256 key are
+ * configured with no --sign-alg to choose between them)
+ */
+export async function getAccessToken(
+  opts: GetAccessTokenOptions,
+): Promise<string> {
+  const { config, scope, spec = "draft14", vcJwt, wallet } = opts;
+
+  if (!vcJwt && requiresVc(scope)) {
+    throw new Error(
+      `Scope "${scope}" requires a Verifiable Credential. ` +
+        "Pass --vc <file> with a path to a VC JWT file.",
+    );
+  }
+
+  // Resolved once: throws when both keys are configured and no --sign-alg
+  // (or EBSI_SIGN_ALG / `ebsi config set signAlg`) chose one.
+  const signingKey = wallet.signingKey();
+
+  // `did-registry:invite`: the presented VerifiableAuthorisationToOnboard VC must
+  // authorise the signing key -- via `credentialSubject.jwkThumbprint` --
+  // or the Authorisation service will reject the request. Catch a mismatch
+  // here instead of round-tripping to the server, since it usually means
+  // either the wrong VC or the wrong key was passed.
+  if (vcJwt && scopeFamilies(scope).includes(DID_REGISTRY_INVITE_FAMILY)) {
+    const { vc } = decodeJwt(vcJwt) as {
+      vc?: { credentialSubject?: { jwkThumbprint?: unknown } };
+    };
+    const jwkThumbprint = vc?.credentialSubject?.jwkThumbprint;
+
+    if (!jwkThumbprint) {
+      throw new Error(
+        "The Verifiable Credential passed via --vc is missing " +
+          "credentialSubject.jwkThumbprint, which the Authorisation service " +
+          `requires for the "did-registry:invite" scope. Ask the issuer for a VC that ` +
+          `authorises this key (thumbprint: ${signingKey.thumbprint}).`,
+      );
+    }
+
+    if (typeof jwkThumbprint !== "string") {
+      throw new TypeError(
+        "The Verifiable Credential passed via --vc has an invalid " +
+          "credentialSubject.jwkThumbprint property (not a string).",
+      );
+    }
+
+    if (jwkThumbprint !== signingKey.thumbprint) {
+      throw new Error(
+        "The Verifiable Credential passed via --vc authorises a different " +
+          `key (thumbprint: ${jwkThumbprint}) than the signing key ` +
+          `(thumbprint: ${signingKey.thumbprint}). Use the key the VC was ` +
+          "issued for, request a new VC for this key, or pass --sign-alg to " +
+          "select the intended key.",
+      );
+    }
+  }
+
+  const { issuer, tokenEndpoint } = await discoverAuthEndpoints(config.baseUrl);
+  const ebsiEnvConfig = buildEbsiEnvConfig(config);
+  const nonce = randomUUID();
+  const now = Math.floor(Date.now() / 1000);
+
+  // On the OpenID4VP 1.0 (final)/DCQL grant, a combinable scope with no VC of
+  // its own (did-registry:write, issuers-registry:write, etc.) presents a self-issued placeholder
+  // credential instead of an empty VP -- DCQL requires `credentials` to be
+  // non-empty, unlike the legacy grant's `input_descriptors: []` (see
+  // `createSelfAttestationVcJwt`).
+  const dcqlSelfAttestationVc =
+    spec === "1.0" && !vcJwt
+      ? createSelfAttestationVcJwt(signingKey)
+      : undefined;
+
+  // Mutually exclusive by construction: `dcqlSelfAttestationVc` is only ever
+  // built when `!vcJwt` (see above).
+  const credential = vcJwt ?? dcqlSelfAttestationVc;
+
+  const vpPayload = {
+    "@context": ["https://www.w3.org/2018/credentials/v1"],
+    holder: signingKey.issuer.did,
+    type: ["VerifiablePresentation"],
+    verifiableCredential: credential ? [credential] : [],
+  };
+
+  const vpJwt = await createVerifiablePresentationJwt(
+    vpPayload,
+    signingKey.issuer,
+    issuer,
+    ebsiEnvConfig,
+    {
+      exp: now + 100,
+      // Needed only for "did-registry:invite": the holder DID isn't registered yet,
+      // so the server verifies the VP signature against this self-asserted
+      // header jwk instead of a DID Document. Every other scope's holder is
+      // already resolvable, so this would be superfluous there.
+      ...(scopeFamilies(scope).includes(DID_REGISTRY_INVITE_FAMILY) && {
+        header: { jwk: signingKey.publicKeyJwk },
+      }),
+      nbf: now - 100,
+      nonce,
+      skipValidation: true,
+    },
+  );
+
+  if (spec === "1.0") {
+    // Every combinable family shares the same DCQL credential-query id
+    // (self_attestation_credential), so it doesn't matter which of a
+    // combined request's families is used to look it up.
+    const credentialQueryId = dcqlCredentialQueryId(scopeFamilies(scope)[0]!);
+
+    const body = new URLSearchParams({
+      grant_type: "vp_token",
+      scope: `openid ${scope}`,
+      vp_token: buildDcqlVpToken(credentialQueryId, vpJwt),
+    });
+
+    return submitTokenRequest(tokenEndpoint, body);
+  }
+
+  const submissionId = randomUUID();
+  const presentationSubmission = buildPresentationSubmission(
+    scope,
+    submissionId,
+  );
+
+  const body = new URLSearchParams({
+    grant_type: "vp_token",
+    presentation_submission: JSON.stringify(presentationSubmission),
+    scope: `openid ${scope}`,
+    vp_token: vpJwt,
+  });
+
+  return submitTokenRequest(tokenEndpoint, body);
+}
+
+/**
+ * Discovers the auth token endpoint from the authorisation service's
+ * OpenID Connect discovery document.
+ *
+ * Returns `{ issuer, tokenEndpoint }` where `issuer` is used as the VP audience.
+ */
+async function discoverAuthEndpoints(
+  baseUrl: string,
+): Promise<{ issuer: string; tokenEndpoint: string }> {
+  const discoveryUrl = `${baseUrl}/auth/.well-known/openid-configuration`;
+  const resp = await fetch(discoveryUrl, {
+    headers: { Accept: "application/json" },
+  });
+  if (!resp.ok) {
+    throw new Error(
+      `Failed to fetch OpenID config from ${discoveryUrl}: HTTP ${resp.status.toString()}`,
+    );
+  }
+  const body = (await resp.json()) as {
+    issuer?: string;
+    token_endpoint?: string;
+  };
+  const { issuer, token_endpoint: tokenEndpoint } = body;
+  if (!issuer || !tokenEndpoint) {
+    throw new Error(
+      `OpenID config at ${discoveryUrl} is missing 'issuer' or 'token_endpoint'`,
+    );
+  }
+  return { issuer, tokenEndpoint };
+}
+
+/**
+ * POSTs a `vp_token` grant's form body to the token endpoint and extracts
+ * `access_token` from the response. Shared by both the legacy (draft 14) and
+ * 1.0 (final) OpenID4VP grants -- once the (differently-shaped) request body
+ * is built, submitting it and handling the response is identical either way.
+ */
+async function submitTokenRequest(
+  tokenEndpoint: string,
+  body: URLSearchParams,
+): Promise<string> {
+  const resp = await fetch(tokenEndpoint, {
+    body: body.toString(),
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    method: "POST",
+  });
+
+  if (!resp.ok) {
+    let detail: string;
+    try {
+      const errBody = await resp.text();
+      detail = errBody;
+    } catch {
+      detail = `HTTP ${resp.status.toString()}`;
+    }
+    throw new Error(
+      `Token request failed (HTTP ${resp.status.toString()}): ${detail}`,
+    );
+  }
+
+  const data = (await resp.json()) as { access_token?: string };
+  if (!data.access_token) {
+    throw new Error("Token response did not contain 'access_token'");
+  }
+  return data.access_token;
+}

package/src/cli.ts

@@ -0,0 +1,164 @@
+import { Command } from "commander";
+
+import { COMMANDS } from "./commands/registry.ts";
+import { resolveConfig } from "./config/config.ts";
+import { printError, printResult } from "./output/format.ts";
+
+/**
+ * Builds and returns the Commander program.
+ *
+ * The command tree is assembled from the COMMANDS registry so that the same
+ * single source of truth drives both the non-interactive CLI and the TUI
+ * command palette.
+ */
+export function buildProgram(): Command {
+  const program = new Command();
+
+  program
+    .name("ebsi")
+    .description("EBSI Core CLI — interact with the EBSI Core API")
+    .version("1.0.0-rc.0")
+    // Global options inherited by all sub-commands
+    .option(
+      "--env <env>",
+      "EBSI environment (local, test, pilot, preprod, prod)",
+    )
+    .option("--base-url <url>", "Override the API base URL (incl. /v1 prefix)")
+    .option("--output <format>", "Output format: pretty (default), json, table")
+    .option(
+      "--token <jwt>",
+      "Bearer access token for authenticated requests (e.g. POST /ledger write methods). " +
+        "Also read from EBSI_ACCESS_TOKEN env var or `ebsi config set token <jwt>`.",
+    )
+    .option(
+      "--es256k-key <hex>",
+      "Secp256k1 private key (0x-prefixed hex). Mandatory for anything that signs: " +
+        "always signs Ethereum transactions, and signs VCs/VPs unless --sign-alg is ES256. " +
+        "Also read from EBSI_ES256K_PRIVATE_KEY env var or `ebsi config set es256kPrivateKey <hex>`. " +
+        "WARNING: passing keys on the command line may expose them in shell history.",
+    )
+    .option(
+      "--es256-key <hex>",
+      "P-256 private key (hex), optional — for signing VCs/VPs only (e.g. an `auth token` " +
+        "request). Also read from EBSI_ES256_PRIVATE_KEY env var or " +
+        "`ebsi config set es256PrivateKey <hex>`.",
+    )
+    .option(
+      "--sign-alg <alg>",
+      'Which key signs VCs/VPs: "ES256" or "ES256K". Required when both keys are ' +
+        "configured. Also read from EBSI_SIGN_ALG env var or `ebsi config set signAlg <alg>`.",
+    )
+    .option(
+      "--did <did>",
+      "EBSI DID (did:ebsi:...) to associate with the key(s). " +
+        "Also read from EBSI_DID env var or `ebsi config set did <did>`. " +
+        "If omitted when running `wallet create`, a new random DID is generated.",
+    );
+
+  // Build a sub-command tree from each descriptor's segment path, creating
+  // (or reusing) one Command node per segment so paths of any depth work —
+  // not just the "group", "group action", and "group sub action" shapes.
+  const nodes = new Map<string, Command>();
+  const configured = new Set<string>();
+
+  for (const descriptor of COMMANDS) {
+    let parent = program;
+    const path: string[] = [];
+
+    for (const [index, segment] of descriptor.segments.entries()) {
+      path.push(segment);
+      const key = path.join(".");
+      let node = nodes.get(key);
+      if (!node) {
+        node = new Command(segment).description(
+          index === 0
+            ? `Commands for the ${descriptor.group} API`
+            : `${descriptor.group} ${path.slice(1).join(" ")} commands`,
+        );
+        parent.addCommand(node);
+        nodes.set(key, node);
+      }
+      parent = node;
+    }
+
+    const leafKey = descriptor.segments.join(".");
+    /* v8 ignore next -- no two command descriptors share a full segment path */
+    if (configured.has(leafKey)) continue;
+    configured.add(leafKey);
+    configureLeaf(parent, descriptor);
+  }
+
+  return program;
+}
+
+/**
+ * Attaches positional args, options, help text, and action handler to a leaf
+ * Commander command from a CommandDescriptor.
+ */
+function configureLeaf(
+  cmd: Command,
+  descriptor: (typeof COMMANDS)[number],
+): void {
+  cmd.description(descriptor.summary);
+
+  for (const arg of descriptor.args) {
+    if (arg.required) {
+      cmd.argument(`<${arg.name}>`, arg.description);
+    } else {
+      cmd.argument(`[${arg.name}]`, arg.description);
+    }
+  }
+
+  for (const opt of descriptor.options) {
+    cmd.option(opt.flags, opt.description, opt.defaultValue);
+  }
+
+  cmd.action(async (...cmdArgs: unknown[]) => {
+    // Commander passes positional args first, then the Command instance
+    // (and any parent option values via parent chain)
+    const commandInstance = cmdArgs.at(-1) as Command;
+
+    // Collect positional arg values
+    const positional = cmdArgs.slice(0, descriptor.args.length) as string[];
+    const argMap: Record<string, string> = {};
+    for (const [i, arg] of descriptor.args.entries()) {
+      argMap[arg.name] = positional[i] ?? "";
+    }
+
+    // optsWithGlobals() merges options from the entire parent chain
+    const mergedOpts =
+      commandInstance.optsWithGlobals<Record<string, string>>();
+
+    try {
+      // resolveConfig can throw (e.g. the legacy EBSI_PRIVATE_KEY migration
+      // error, or an invalid --sign-alg) -- resolved inside this try so that,
+      // like every other command error, it goes through printError/exitCode
+      // instead of surfacing as an unhandled rejection. `config`/`config set`
+      // itself stays reachable even while that migration error would
+      // otherwise fire everywhere else, so the user has a way to fix it.
+      const config = resolveConfig(
+        Object.fromEntries(
+          Object.entries({
+            baseUrl: mergedOpts["baseUrl"],
+            did: mergedOpts["did"],
+            env: mergedOpts["env"],
+            es256Key: mergedOpts["es256Key"],
+            es256kKey: mergedOpts["es256kKey"],
+            output: mergedOpts["output"],
+            signAlg: mergedOpts["signAlg"],
+            token: mergedOpts["token"],
+          }).filter(([, v]) => v !== undefined),
+        ),
+        { allowLegacyPrivateKey: descriptor.segments[0] === "config" },
+      );
+
+      const data = await descriptor.handler(argMap, mergedOpts, config);
+      printResult(data, config.output);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
+      const detail = error instanceof Error ? error.cause : error;
+      printError(message, detail);
+      process.exitCode = 1;
+    }
+  });
+}

package/src/commands/auth.ts

@@ -0,0 +1,119 @@
+import { readFileSync } from "node:fs";
+
+import type { CommandDescriptor } from "./registry.ts";
+
+import { KNOWN_SCOPES, validateScope } from "../auth/presentation.ts";
+import { getAccessToken } from "../auth/token.ts";
+import { setPersistedConfigValue } from "../config/config.ts";
+import { resolveWallet, WALLET_KEY_OPTIONS } from "./shared/wallet-opts.ts";
+
+export const authCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "Auth",
+    async handler(_args, opts, config) {
+      const scope = opts["scope"];
+      if (!scope) {
+        throw new Error(
+          "Missing --scope. Provide one of: " + KNOWN_SCOPES.join(", "),
+        );
+      }
+      // Throws a descriptive error for unknown scopes, duplicates, or an
+      // illegal combination (e.g. mixing an invite scope with a write scope).
+      validateScope(scope);
+
+      const wallet = await resolveWallet(opts, config);
+
+      // Load VC from file if provided
+      let vcJwt: string | undefined;
+      const vcFile = opts["vc"];
+      if (vcFile) {
+        try {
+          vcJwt = readFileSync(vcFile, "utf8").trim();
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : String(error);
+          throw new Error(`Failed to read VC file "${vcFile}": ${message}`, {
+            cause: error,
+          });
+        }
+      }
+
+      const specOpt = opts["spec"];
+      if (specOpt !== undefined && specOpt !== "draft14" && specOpt !== "1.0") {
+        throw new Error('Invalid --spec value. Must be "draft14" or "1.0".');
+      }
+
+      const accessToken = await getAccessToken({
+        config,
+        scope,
+        wallet,
+        ...(specOpt !== undefined && { spec: specOpt }),
+        ...(vcJwt !== undefined && { vcJwt }),
+      });
+
+      // Optionally persist the token
+      const save = Boolean(opts["save"]);
+      if (save) {
+        setPersistedConfigValue("token", accessToken);
+      }
+
+      return {
+        access_token: accessToken,
+        did: wallet.did,
+        saved: save,
+        scope,
+        signedWith: wallet.signingKey().alg,
+      };
+    },
+    id: "auth.token",
+    options: [
+      {
+        description:
+          "EBSI authorisation scope. Required. Either a single scope " +
+          '(e.g. "did-registry:write", "did-registry:invite"), or a space-separated combination of ' +
+          'write scopes for a multi-scope token (e.g. "did-registry:write issuers-registry:write"). ' +
+          "Only did-registry:write, issuers-registry:write, timestamp:write, track-and-trace:create, track-and-trace:write, policies-registry:write, " +
+          "and schemas-registry:write can be combined — invite/invoke scopes must be requested alone. " +
+          "Scopes that need a VC (did-registry:invite, ledger:invoke, issuers-registry:invite, track-and-trace:authorise) " +
+          "also require --vc and cannot be combined. Any scope may be suffixed with " +
+          '":<0x-address>" (e.g. "track-and-trace:write:0x61c36a8d610163660E21a8b7359e1Cac0C9133e1") ' +
+          "to target a specific deployed contract instance instead of the environment default.",
+        flags: "--scope <scope>",
+      },
+      {
+        description:
+          "Path to a VC JWT file. Required for invite/invoke scopes " +
+          "(did-registry:invite, ledger:invoke, issuers-registry:invite, track-and-trace:authorise).",
+        flags: "--vc <file>",
+      },
+      {
+        description:
+          "Persist the obtained access token to config (equivalent to `ebsi config set token <jwt>`).",
+        flags: "--save",
+      },
+      ...WALLET_KEY_OPTIONS,
+      {
+        description: "EBSI DID — overrides config/env.",
+        flags: "--did <did>",
+      },
+      {
+        description:
+          'Which OpenID4VP grant to speak: "draft14" (default, legacy Presentation ' +
+          'Exchange) or "1.0" (final, DCQL). Both are accepted by the Authorisation ' +
+          "service side by side.",
+        flags: "--spec <draft14|1.0>",
+      },
+    ],
+    segments: ["auth", "token"],
+    summary:
+      "Obtain an EBSI access token via the OIDC4VP `vp_token` grant flow. " +
+      "Requires a configured secp256k1 key (--es256k-key, EBSI_ES256K_PRIVATE_KEY, " +
+      "or `ebsi config set es256kPrivateKey`); when a P-256 key is also configured, " +
+      "--sign-alg picks which one signs the VP. " +
+      'Pass several space-separated write scopes (e.g. --scope "did-registry:write issuers-registry:write") ' +
+      "to mint a single multi-scope token. " +
+      "Use --vc <file> for scopes that require a Verifiable Credential. " +
+      "Use --save to persist the token for subsequent commands.",
+  },
+];

package/src/commands/config-cmd.ts

@@ -0,0 +1,122 @@
+import type { CommandDescriptor } from "./registry.ts";
+
+import {
+  EBSI_ENVS,
+  getConfigFilePath,
+  getPersistedConfigValue,
+  OUTPUT_FORMATS,
+  setPersistedConfigValue,
+  SIGN_ALGS,
+} from "../config/config.ts";
+import { requiredArg } from "./shared/args.ts";
+
+const SETTABLE_KEYS = [
+  "did",
+  "env",
+  "es256PrivateKey",
+  "es256kPrivateKey",
+  "output",
+  "signAlg",
+  "token",
+] as const;
+type SettableKey = (typeof SETTABLE_KEYS)[number];
+
+export const configCommands: CommandDescriptor[] = [
+  {
+    args: [
+      {
+        description: `Config key to read (${SETTABLE_KEYS.join(", ")})`,
+        example: "env",
+        name: "key",
+        required: true,
+      },
+    ],
+    group: "Config",
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async handler(args) {
+      const key = args["key"] as SettableKey;
+      if (!SETTABLE_KEYS.includes(key)) {
+        throw new Error(
+          `Unknown config key "${key}". Valid keys: ${SETTABLE_KEYS.join(", ")}`,
+        );
+      }
+      const value = getPersistedConfigValue(key);
+      return {
+        configFile: getConfigFilePath(),
+        key,
+        value: value ?? undefined,
+      };
+    },
+    id: "config.get",
+    options: [],
+    segments: ["config", "get"],
+    summary:
+      "Show the current persisted config value for a key " +
+      "(did, env, es256PrivateKey, es256kPrivateKey, output, signAlg, token)",
+  },
+  {
+    args: [
+      {
+        description: `Config key (${SETTABLE_KEYS.join(", ")})`,
+        example: "env",
+        name: "key",
+        required: true,
+      },
+      {
+        description: "Value to set",
+        example: "test",
+        name: "value",
+        required: true,
+      },
+    ],
+    group: "Config",
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async handler(args) {
+      const key = args["key"] as SettableKey;
+
+      if (!SETTABLE_KEYS.includes(key)) {
+        throw new Error(
+          `Unknown config key "${key}". Valid keys: ${SETTABLE_KEYS.join(", ")}`,
+        );
+      }
+
+      const value = requiredArg(args, "value");
+
+      // Validate values
+      if (
+        key === "env" &&
+        !EBSI_ENVS.includes(value as (typeof EBSI_ENVS)[number])
+      ) {
+        throw new Error(
+          `Invalid env "${value}". Valid values: ${EBSI_ENVS.join(", ")}`,
+        );
+      }
+      if (
+        key === "output" &&
+        !OUTPUT_FORMATS.includes(value as (typeof OUTPUT_FORMATS)[number])
+      ) {
+        throw new Error(
+          `Invalid output "${value}". Valid values: ${OUTPUT_FORMATS.join(", ")}`,
+        );
+      }
+      if (
+        key === "signAlg" &&
+        !SIGN_ALGS.includes(value.toUpperCase() as (typeof SIGN_ALGS)[number])
+      ) {
+        throw new Error(
+          `Invalid signAlg "${value}". Valid values: ${SIGN_ALGS.join(", ")}`,
+        );
+      }
+
+      setPersistedConfigValue(key, value);
+      return { configFile: getConfigFilePath(), key, value };
+    },
+    id: "config.set",
+    options: [],
+    segments: ["config", "set"],
+    summary:
+      "Persist a config value (key=did|env|es256PrivateKey|es256kPrivateKey|output|signAlg|token, " +
+      "value=...). WARNING: storing es256PrivateKey/es256kPrivateKey persists the key(s) as " +
+      "plaintext in the config file.",
+  },
+];