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

package/src/commands/onboarding.ts

@@ -0,0 +1,411 @@
+import { readFileSync, writeFileSync } from "node:fs";
+
+import type { CliConfig } from "../config/config.ts";
+import type { WalletDetails } from "../crypto/wallet.ts";
+import type { WriteReceipt } from "../ledger/write.ts";
+import type { CommandDescriptor } from "./registry.ts";
+
+import { getAccessToken } from "../auth/token.ts";
+import { REGISTRIES } from "../ledger/registries.ts";
+import { writeToRegistry } from "../ledger/write.ts";
+import { buildOnboardingVc } from "../onboarding/vc.ts";
+import { printWarning } from "../output/format.ts";
+import { resolveWallet, WALLET_KEY_OPTIONS } from "./shared/wallet-opts.ts";
+
+const DID_REGISTRY = REGISTRIES["did-registry"];
+/* v8 ignore next 3 -- REGISTRIES["did-registry"] is always defined; defensive per its Record<string, RegistryEntry | undefined> typing */
+if (!DID_REGISTRY) {
+  throw new Error('Unknown registry "did-registry"');
+}
+
+const RTAO_OPTIONS = [
+  {
+    description:
+      "The RTAO's DID (must already be registered as RootTAO in the Issuers Registry, " +
+      "e.g. via `hardhat bootstrap` or `setup-rtao.ts`). Also read from EBSI_RTAO_DID.",
+    flags: "--rtao-did <did>",
+  },
+  {
+    description:
+      "The RTAO's secp256k1 private key (0x-prefixed hex), used to sign the VC ES256K. " +
+      "Optional when --rtao-es256-key is given. Also read from EBSI_RTAO_ES256K_PRIVATE_KEY.",
+    flags: "--rtao-es256k-key <hex>",
+  },
+  {
+    description:
+      "The RTAO's P-256 private key (hex), used to sign the VC ES256 instead of ES256K. " +
+      "Required against deployments that restrict the did-registry:invite credential format to " +
+      "ES256. Also read from EBSI_RTAO_ES256_PRIVATE_KEY.",
+    flags: "--rtao-es256-key <hex>",
+  },
+  {
+    description:
+      "The RTAO's Issuers Registry attribute id carrying its RootTAO self-attestation " +
+      "(0x-prefixed hex, from `ebsi issuers-registry issuers attributes list <rtaoDid>`). " +
+      "Also read from EBSI_RTAO_ATTRIBUTE_ID.",
+    flags: "--rtao-attribute-id <hex>",
+  },
+];
+
+const MISSING_RTAO_MESSAGE =
+  "Missing RTAO credentials. Provide --rtao-did, --rtao-attribute-id, and " +
+  "one of --rtao-es256-key (ES256) or --rtao-es256k-key (ES256K), or set " +
+  "EBSI_RTAO_DID/EBSI_RTAO_ATTRIBUTE_ID plus " +
+  "EBSI_RTAO_ES256_PRIVATE_KEY/EBSI_RTAO_ES256K_PRIVATE_KEY.";
+
+interface RtaoCredentials {
+  rtaoAttributeId: string;
+  rtaoDid: string;
+  rtaoEs256kPrivateKey?: string;
+  rtaoEs256PrivateKey?: string;
+}
+
+/**
+ * The JSON-serialised-JWK public key encoding the DID Registry contract
+ * expects for a non-secp256k1 verification method (e.g. P-256) — see
+ * `generateDidParams.ts`'s `publicKeyHex` for ES256 in
+ * `contracts/deploy-toolkit`, which this must match exactly or the DID
+ * document's verification method won't resolve.
+ */
+function jwkToContractPublicKeyHex(jwk: unknown): string {
+  return `0x${Buffer.from(JSON.stringify(jwk)).toString("hex")}`;
+}
+
+/**
+ * Resolves RTAO credentials from flags or their EBSI_RTAO_* env var
+ * fallbacks. Returns `undefined` (rather than throwing) when the DID, the
+ * attribute id, or both signing keys are missing, so callers that also accept
+ * a pre-obtained `--vc <file>` can fall through.
+ */
+function resolveRtaoCredentials(
+  opts: Record<string, string>,
+): RtaoCredentials | undefined {
+  const rtaoDid = opts["rtaoDid"] ?? process.env["EBSI_RTAO_DID"];
+  const rtaoEs256kPrivateKey =
+    opts["rtaoEs256kKey"] ?? process.env["EBSI_RTAO_ES256K_PRIVATE_KEY"];
+  const rtaoEs256PrivateKey =
+    opts["rtaoEs256Key"] ?? process.env["EBSI_RTAO_ES256_PRIVATE_KEY"];
+  const rtaoAttributeId =
+    opts["rtaoAttributeId"] ?? process.env["EBSI_RTAO_ATTRIBUTE_ID"];
+  // Either key can sign the VC, so only their absence together is fatal.
+  if (
+    !rtaoDid ||
+    !rtaoAttributeId ||
+    (!rtaoEs256kPrivateKey && !rtaoEs256PrivateKey)
+  ) {
+    return undefined;
+  }
+  return {
+    rtaoAttributeId,
+    rtaoDid,
+    ...(rtaoEs256PrivateKey !== undefined && { rtaoEs256PrivateKey }),
+    ...(rtaoEs256kPrivateKey !== undefined && { rtaoEs256kPrivateKey }),
+  };
+}
+
+/**
+ * Registers `wallet.es256`'s public key as an additional verification method
+ * on `did`'s DID document — an `authentication` and `assertionMethod`
+ * relationship, both usable for VC/VP signing (`onboarding onboard
+ * --register-es256-key`).
+ *
+ * Mints its own `did-registry:write` access token signed with the ES256K key
+ * specifically — regardless of `--sign-alg` — since the P-256 verification
+ * method doesn't exist in the DID document yet, so an ES256-signed VP
+ * wouldn't resolve against it.
+ */
+const registerEs256VerificationMethod = async (
+  config: CliConfig,
+  wallet: WalletDetails,
+  contractAddress: string,
+): Promise<{
+  addVerificationMethod: WriteReceipt;
+  addVerificationRelationship: WriteReceipt[];
+}> => {
+  const { es256, es256k } = wallet;
+  /* v8 ignore next 3 -- callers only invoke this once `es256` is confirmed present */
+  if (!es256) {
+    throw new Error("No P-256 key configured. Pass --es256-key <hex>.");
+  }
+
+  // Forces ES256K regardless of --sign-alg -- see doc comment above.
+  const es256kOnlyWallet: WalletDetails = {
+    ...wallet,
+    signingKey: () => es256k,
+  };
+  const token = await getAccessToken({
+    config,
+    scope: `did-registry:write:${contractAddress}`,
+    wallet: es256kOnlyWallet,
+  });
+
+  const publicKeyHex = jwkToContractPublicKeyHex(es256.publicKeyJwk);
+  const notBefore = 0;
+  const notAfter = 9_999_999_999;
+
+  const addVerificationMethod = await writeToRegistry({
+    config,
+    contractAddress,
+    functionArgs: [wallet.did, es256.thumbprint, publicKeyHex, false],
+    functionName: "addVerificationMethod",
+    registry: DID_REGISTRY,
+    token,
+    wallet,
+  });
+
+  const addVerificationRelationship: WriteReceipt[] = await Array.fromAsync(
+    ["authentication", "assertionMethod"],
+    (relationship) =>
+      writeToRegistry({
+        config,
+        contractAddress,
+        functionArgs: [
+          wallet.did,
+          relationship,
+          es256.thumbprint,
+          notBefore,
+          notAfter,
+        ],
+        functionName: "addVerificationRelationship",
+        registry: DID_REGISTRY,
+        token,
+        wallet,
+      }),
+  );
+
+  return { addVerificationMethod, addVerificationRelationship };
+};
+
+export const onboardingCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "Onboarding",
+    async handler(_args, opts, config) {
+      let holderDid = opts["holderDid"];
+      let holderThumbprint = opts["holderThumbprint"];
+      if (holderDid === undefined || holderThumbprint === undefined) {
+        const wallet = await resolveWallet(opts, config);
+        holderDid ??= wallet.did;
+        holderThumbprint ??= wallet.signingKey().thumbprint;
+      }
+
+      const rtao = resolveRtaoCredentials(opts);
+      if (!rtao) {
+        throw new Error(MISSING_RTAO_MESSAGE);
+      }
+
+      const { alg, rtaoKid, vcJwt } = await buildOnboardingVc({
+        config,
+        holderDid,
+        holderThumbprint,
+        ...rtao,
+      });
+
+      const outFile = opts["out"];
+      if (outFile) {
+        writeFileSync(outFile, vcJwt + "\n", "utf8");
+      }
+
+      return {
+        alg,
+        holderDid,
+        holderThumbprint,
+        ...(outFile !== undefined && { outFile }),
+        rtaoDid: rtao.rtaoDid,
+        rtaoKid,
+        vcJwt,
+      };
+    },
+    id: "onboarding.issue-vc",
+    options: [
+      {
+        description:
+          "DID to embed as credentialSubject.id. Defaults to the DID derived from " +
+          "the configured wallet (--es256k-key/--did, EBSI_ES256K_PRIVATE_KEY, or persisted config).",
+        flags: "--holder-did <did>",
+      },
+      {
+        description:
+          "JWK thumbprint to embed as credentialSubject.jwkThumbprint (binds the VC " +
+          "to a specific key). Defaults to the configured wallet's signing key thumbprint " +
+          "(see --sign-alg).",
+        flags: "--holder-thumbprint <thumbprint>",
+      },
+      ...RTAO_OPTIONS,
+      ...WALLET_KEY_OPTIONS,
+      {
+        description: "Also write the signed VC JWT to this file.",
+        flags: "--out <file>",
+      },
+    ],
+    segments: ["onboarding", "issue-vc"],
+    summary:
+      "Mint a VerifiableAuthorisationToOnboard VC for a holder DID/key, signed by an " +
+      "RTAO already registered as RootTAO on chain. Signs ES256 when --rtao-es256-key " +
+      "is given, otherwise ES256K. There is no CLI/API endpoint for this otherwise — " +
+      "it's a local signing operation, not a network call.",
+  },
+
+  {
+    args: [],
+    group: "Onboarding",
+    async handler(_args, opts, config) {
+      const wallet = await resolveWallet(opts, config);
+
+      const registerEs256Key = Boolean(opts["registerEs256Key"]);
+      if (registerEs256Key && !wallet.es256) {
+        throw new Error(
+          "--register-es256-key requires a P-256 key. Provide --es256-key <hex>, set " +
+            "EBSI_ES256_PRIVATE_KEY, or run `ebsi config set es256PrivateKey <hex>`.",
+        );
+      }
+
+      // The onboarding VC authorises whichever key insertDidDocument is about
+      // to register — always the ES256K key (see doc comment on --sign-alg
+      // below). A VC signed ES256 here would authorise a key that never gets
+      // registered by this command.
+      if (wallet.es256 && config.signAlg === "ES256") {
+        printWarning(
+          "--sign-alg ES256 is set, but `onboarding onboard` always registers " +
+            "the ES256K key via insertDidDocument. Signing the onboarding VP with " +
+            "the ES256 key here would authorise a different key than the one " +
+            "being registered. Proceeding with the ES256K key for this VC/VP.",
+        );
+      }
+      const es256kOnlyWallet: WalletDetails = {
+        ...wallet,
+        signingKey: () => wallet.es256k,
+      };
+
+      const vcFile = opts["vc"];
+      let vcJwt: string;
+      if (vcFile) {
+        vcJwt = readFileSync(vcFile, "utf8").trim();
+      } else {
+        const rtao = resolveRtaoCredentials(opts);
+        if (!rtao) {
+          throw new Error(
+            "Provide --vc <file> with a pre-obtained onboarding VC, or the " +
+              "RTAO credentials to mint one inline. " +
+              MISSING_RTAO_MESSAGE,
+          );
+        }
+        ({ vcJwt } = await buildOnboardingVc({
+          config,
+          holderDid: wallet.did,
+          holderThumbprint: wallet.es256k.thumbprint,
+          ...rtao,
+        }));
+      }
+
+      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 token = await getAccessToken({
+        config,
+        scope: "did-registry:invite",
+        vcJwt,
+        wallet: es256kOnlyWallet,
+        ...(specOpt !== undefined && { spec: specOpt }),
+      });
+
+      const contractAddress =
+        opts["to"] ?? process.env[DID_REGISTRY.addressEnvKey];
+      if (!contractAddress) {
+        throw new Error(
+          `No contract address for "did-registry". Provide --to <address> or ` +
+            `set ${DID_REGISTRY.addressEnvKey}.`,
+        );
+      }
+
+      const baseDocument = JSON.stringify({
+        "@context": [
+          "https://www.w3.org/ns/did/v1",
+          "https://w3id.org/security/suites/jws-2020/v1",
+        ],
+      });
+      const notBefore = Number(opts["notBefore"] ?? "0");
+      const notAfter = Number(opts["notAfter"] ?? "9999999999");
+      const publicKey = wallet.wallet.signingKey.publicKey;
+
+      const receipt = await writeToRegistry({
+        config,
+        contractAddress,
+        functionArgs: [
+          wallet.did,
+          baseDocument,
+          wallet.es256k.thumbprint,
+          publicKey,
+          true,
+          notBefore,
+          notAfter,
+        ],
+        functionName: "insertDidDocument",
+        registry: DID_REGISTRY,
+        token,
+        wallet,
+      });
+
+      const es256Registration = registerEs256Key
+        ? await registerEs256VerificationMethod(config, wallet, contractAddress)
+        : undefined;
+
+      return {
+        did: wallet.did,
+        ...receipt,
+        ...(es256Registration !== undefined && { es256Registration }),
+      };
+    },
+    id: "onboarding.onboard",
+    options: [
+      {
+        description:
+          "Path to a pre-obtained onboarding VC JWT file. If omitted, one is minted " +
+          "inline from the --rtao-* flags.",
+        flags: "--vc <file>",
+      },
+      ...RTAO_OPTIONS,
+      ...WALLET_KEY_OPTIONS,
+      {
+        description:
+          "Contract address (0x-prefixed). If omitted, read from DID_REGISTRY_CONTRACT_ADDRESS.",
+        flags: "--to <address>",
+      },
+      {
+        description:
+          'Which OpenID4VP grant to speak: "draft14" (default) or "1.0" (DCQL).',
+        flags: "--spec <draft14|1.0>",
+      },
+      {
+        defaultValue: "0",
+        description: "Unix timestamp the DID document becomes valid from.",
+        flags: "--not-before <epoch>",
+      },
+      {
+        defaultValue: "9999999999",
+        description: "Unix timestamp the DID document expires at.",
+        flags: "--not-after <epoch>",
+      },
+      {
+        description:
+          "After registering the DID document, also register the configured P-256 key " +
+          "(--es256-key) as an additional verification method (authentication + " +
+          "assertionMethod), so it can be used to sign VCs/VPs afterwards. Requires a " +
+          "P-256 key to be configured. Mints a separate did-registry:write token, " +
+          "always signed with the ES256K key.",
+        flags: "--register-es256-key",
+      },
+    ],
+    segments: ["onboarding", "onboard"],
+    summary:
+      "One-shot: mint (or load) a VerifiableAuthorisationToOnboard VC, exchange it for " +
+      "a did-registry:invite access token, and insert the DID document for the configured " +
+      "wallet — auto-deriving the base document, verification method id, and raw " +
+      "public key, so you don't have to build insertDidDocument's args by hand. Always " +
+      "signs with the ES256K key, regardless of --sign-alg — the P-256 key isn't " +
+      "registered in the DID document yet at this point. Pass --register-es256-key to " +
+      "also register a configured P-256 key right after.",
+  },
+];

package/src/commands/openapi.ts

@@ -0,0 +1,42 @@
+import type { CommandDescriptor } from "./registry.ts";
+
+export const openapiCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "OpenAPI",
+    async handler(_args, _opts, config) {
+      const response = await fetch(`${config.baseUrl}/openapi.json`, {
+        headers: { Accept: "application/openapi+json" },
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch OpenAPI JSON: HTTP ${String(response.status)}`,
+        );
+      }
+      return response.json();
+    },
+    id: "openapi.json",
+    options: [],
+    segments: ["openapi", "json"],
+    summary: "Fetch the OpenAPI 3.1 spec in JSON format",
+  },
+  {
+    args: [],
+    group: "OpenAPI",
+    async handler(_args, _opts, config) {
+      const response = await fetch(`${config.baseUrl}/openapi.yaml`, {
+        headers: { Accept: "application/openapi+yaml" },
+      });
+      if (!response.ok) {
+        throw new Error(
+          `Failed to fetch OpenAPI YAML: HTTP ${String(response.status)}`,
+        );
+      }
+      return response.text();
+    },
+    id: "openapi.yaml",
+    options: [],
+    segments: ["openapi", "yaml"],
+    summary: "Fetch the OpenAPI 3.1 spec in YAML format",
+  },
+];

package/src/commands/policies-registry.ts

@@ -0,0 +1,218 @@
+import type { CommandDescriptor } from "./registry.ts";
+
+import { getClient, unwrap } from "../api/fetch.ts";
+import { q } from "../api/params.ts";
+import { contractAddressOptionFor } from "../ledger/registries.ts";
+import { requiredArg } from "./shared/args.ts";
+
+const PAGINATION_OPTIONS = [
+  {
+    description: "Cursor for pagination (page[after])",
+    flags: "--page-after <cursor>",
+  },
+  {
+    description: "Maximum number of items per page (page[size])",
+    flags: "--page-size <n>",
+  },
+];
+
+const { option: CONTRACT_ADDRESS_OPTION, resolve: contractAddress } =
+  contractAddressOptionFor("policies-registry");
+
+export const policiesRegistryCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "Policies Registry",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/policies-registry/policies", {
+        params: {
+          query: q({
+            contractAddress: contractAddress(opts),
+            "page[after]": opts["pageAfter"]
+              ? Number(opts["pageAfter"])
+              : undefined,
+            "page[size]": opts["pageSize"]
+              ? Number(opts["pageSize"])
+              : undefined,
+          }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "policies-registry.policies.list",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["policies-registry", "policies", "list"],
+    summary: "List all policies registered on the EBSI ledger",
+  },
+
+  {
+    args: [
+      {
+        description: "Policy name",
+        example: "VerifiableAuthorisationForTrustChain",
+        name: "policyName",
+        required: true,
+      },
+    ],
+    group: "Policies Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/policies-registry/policies/{policyName}",
+        {
+          params: {
+            path: { policyName: requiredArg(args, "policyName") },
+            query: q({ contractAddress: contractAddress(opts) }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "policies-registry.policies.get",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["policies-registry", "policies", "get"],
+    summary: "Get a policy by name",
+  },
+
+  {
+    args: [],
+    group: "Policies Registry",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/policies-registry/subjects", {
+        params: {
+          query: q({
+            contractAddress: contractAddress(opts),
+            "page[after]": opts["pageAfter"]
+              ? Number(opts["pageAfter"])
+              : undefined,
+            "page[size]": opts["pageSize"]
+              ? Number(opts["pageSize"])
+              : undefined,
+          }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "policies-registry.subjects.list",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["policies-registry", "subjects", "list"],
+    summary: "List all subjects with assigned policies",
+  },
+
+  {
+    args: [
+      {
+        description: "Subject DID",
+        example: "did:ebsi:ziDnioxYYLW1a3FDD",
+        name: "subject",
+        required: true,
+      },
+    ],
+    group: "Policies Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/policies-registry/subjects/{subject}", {
+        params: {
+          path: { subject: requiredArg(args, "subject") },
+          query: q({ contractAddress: contractAddress(opts) }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "policies-registry.subjects.get",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["policies-registry", "subjects", "get"],
+    summary: "Get a subject by DID",
+  },
+
+  {
+    args: [
+      {
+        description: "Subject DID",
+        example: "did:ebsi:ziDnioxYYLW1a3FDD",
+        name: "subject",
+        required: true,
+      },
+    ],
+    group: "Policies Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/policies-registry/subjects/{subject}/policies",
+        {
+          params: {
+            path: { subject: requiredArg(args, "subject") },
+            query: q({
+              contractAddress: contractAddress(opts),
+              "page[after]": opts["pageAfter"]
+                ? Number(opts["pageAfter"])
+                : undefined,
+              "page[size]": opts["pageSize"]
+                ? Number(opts["pageSize"])
+                : undefined,
+            }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "policies-registry.subjects.policies",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["policies-registry", "subjects", "policies"],
+    summary: "List all policies assigned to a subject",
+  },
+
+  {
+    args: [
+      {
+        description: "Subject DID",
+        example: "did:ebsi:ziDnioxYYLW1a3FDD",
+        name: "subject",
+        required: true,
+      },
+      {
+        description: "Policy name",
+        example: "VerifiableAuthorisationForTrustChain",
+        name: "policyName",
+        required: true,
+      },
+    ],
+    group: "Policies Registry",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/policies-registry/subjects/{subject}/policies/{policyName}",
+        {
+          params: {
+            path: {
+              policyName: requiredArg(args, "policyName"),
+              subject: requiredArg(args, "subject"),
+            },
+            query: q({ contractAddress: contractAddress(opts) }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "policies-registry.subjects.policy",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["policies-registry", "subjects", "policy"],
+    summary: "Get a specific policy assigned to a subject",
+  },
+
+  {
+    args: [],
+    group: "Policies Registry",
+    async handler(_args, _opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/policies-registry/abi");
+      return unwrap(result);
+    },
+    id: "policies-registry.abi",
+    options: [],
+    segments: ["policies-registry", "abi"],
+    summary: "Get the ABI of the Policies Registry smart contract",
+  },
+];