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

package/src/commands/timestamp.ts

@@ -0,0 +1,272 @@
+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("timestamp");
+
+export const timestampCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "Timestamp",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/timestamp/timestamps", {
+        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: "timestamp.timestamps.list",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["timestamp", "timestamps", "list"],
+    summary: "List timestamps on the EBSI ledger",
+  },
+
+  {
+    args: [
+      {
+        description: "Timestamp ID",
+        example: "0x1234...",
+        name: "timestampId",
+        required: true,
+      },
+    ],
+    group: "Timestamp",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/timestamp/timestamps/{timestampId}", {
+        params: {
+          path: { timestampId: requiredArg(args, "timestampId") },
+          query: q({ contractAddress: contractAddress(opts) }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "timestamp.timestamps.get",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["timestamp", "timestamps", "get"],
+    summary: "Get a timestamp by its ID",
+  },
+
+  {
+    args: [],
+    group: "Timestamp",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/timestamp/records", {
+        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: "timestamp.records.list",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["timestamp", "records", "list"],
+    summary: "List timestamp records",
+  },
+
+  {
+    args: [
+      {
+        description: "Record ID",
+        example: "0x1234...",
+        name: "recordId",
+        required: true,
+      },
+    ],
+    group: "Timestamp",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/timestamp/records/{recordId}", {
+        params: {
+          path: { recordId: requiredArg(args, "recordId") },
+          query: q({ contractAddress: contractAddress(opts) }),
+        },
+      });
+      return unwrap(result);
+    },
+    id: "timestamp.records.get",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["timestamp", "records", "get"],
+    summary: "Get a timestamp record by ID",
+  },
+
+  {
+    args: [
+      {
+        description: "Record ID",
+        example: "0x1234...",
+        name: "recordId",
+        required: true,
+      },
+    ],
+    group: "Timestamp",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/timestamp/records/{recordId}/versions",
+        {
+          params: {
+            path: { recordId: requiredArg(args, "recordId") },
+            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: "timestamp.records.versions",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["timestamp", "records", "versions"],
+    summary: "List all versions of a timestamp record",
+  },
+
+  {
+    args: [
+      {
+        description: "Record ID",
+        example: "0x1234...",
+        name: "recordId",
+        required: true,
+      },
+      {
+        description: "Version ID",
+        example: "0",
+        name: "versionId",
+        required: true,
+      },
+    ],
+    group: "Timestamp",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/timestamp/records/{recordId}/versions/{versionId}",
+        {
+          params: {
+            path: {
+              recordId: requiredArg(args, "recordId"),
+              versionId: Number(requiredArg(args, "versionId")),
+            },
+            query: q({ contractAddress: contractAddress(opts) }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "timestamp.records.version",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["timestamp", "records", "version"],
+    summary: "Get a specific version of a timestamp record",
+  },
+
+  {
+    args: [],
+    group: "Timestamp",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/timestamp/hash-algorithms", {
+        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: "timestamp.hash-algorithms.list",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["timestamp", "hash-algorithms", "list"],
+    summary: "List supported hash algorithms for timestamping",
+  },
+
+  {
+    args: [
+      {
+        description: "Hash algorithm ID",
+        example: "0",
+        name: "hashAlgorithmId",
+        required: true,
+      },
+    ],
+    group: "Timestamp",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/timestamp/hash-algorithms/{hashAlgorithmId}",
+        {
+          params: {
+            path: {
+              hashAlgorithmId: Number(requiredArg(args, "hashAlgorithmId")),
+            },
+            query: q({ contractAddress: contractAddress(opts) }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "timestamp.hash-algorithms.get",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["timestamp", "hash-algorithms", "get"],
+    summary: "Get a hash algorithm by its ID",
+  },
+
+  {
+    args: [],
+    group: "Timestamp",
+    async handler(_args, _opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/timestamp/abi");
+      return unwrap(result);
+    },
+    id: "timestamp.abi",
+    options: [],
+    segments: ["timestamp", "abi"],
+    summary: "Get the ABI of the Timestamp smart contract",
+  },
+];

package/src/commands/track-and-trace.ts

@@ -0,0 +1,263 @@
+import type { CommandDescriptor } from "./registry.ts";
+
+import { ApiError, 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("track-and-trace");
+
+export const trackAndTraceCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "Track & Trace",
+    async handler(_args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/track-and-trace/documents", {
+        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: "track-and-trace.documents.list",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["track-and-trace", "documents", "list"],
+    summary: "List all Track and Trace documents",
+  },
+
+  {
+    args: [
+      {
+        description: "Document ID",
+        example: "0x1234...",
+        name: "documentId",
+        required: true,
+      },
+    ],
+    group: "Track & Trace",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/track-and-trace/documents/{documentId}",
+        {
+          params: {
+            path: { documentId: requiredArg(args, "documentId") },
+            query: q({ contractAddress: contractAddress(opts) }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "track-and-trace.documents.get",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["track-and-trace", "documents", "get"],
+    summary: "Get a Track and Trace document by ID",
+  },
+
+  {
+    args: [
+      {
+        description: "Document ID",
+        example: "0x1234...",
+        name: "documentId",
+        required: true,
+      },
+    ],
+    group: "Track & Trace",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/track-and-trace/documents/{documentId}/events",
+        {
+          params: {
+            path: { documentId: requiredArg(args, "documentId") },
+            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: "track-and-trace.documents.events",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["track-and-trace", "documents", "events"],
+    summary: "List events for a Track and Trace document",
+  },
+
+  {
+    args: [
+      {
+        description: "Document ID",
+        example: "0x1234...",
+        name: "documentId",
+        required: true,
+      },
+      {
+        description: "Event ID",
+        example:
+          "0x4791c04d2e4838042c67f3e739ab8639b6bd0f6896ec7e32e99c640d43b530c7",
+        name: "eventId",
+        required: true,
+      },
+    ],
+    group: "Track & Trace",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/track-and-trace/documents/{documentId}/events/{eventId}",
+        {
+          params: {
+            path: {
+              documentId: requiredArg(args, "documentId"),
+              eventId: requiredArg(args, "eventId"),
+            },
+            query: q({ contractAddress: contractAddress(opts) }),
+          },
+        },
+      );
+      return unwrap(result);
+    },
+    id: "track-and-trace.documents.event",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["track-and-trace", "documents", "event"],
+    summary: "Get an event for a Track and Trace document",
+  },
+
+  {
+    args: [
+      {
+        description: "Document ID",
+        example: "0x1234...",
+        name: "documentId",
+        required: true,
+      },
+    ],
+    group: "Track & Trace",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const result = await client.GET(
+        "/track-and-trace/documents/{documentId}/accesses",
+        {
+          params: {
+            path: { documentId: requiredArg(args, "documentId") },
+            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: "track-and-trace.documents.accesses",
+    options: [...PAGINATION_OPTIONS, CONTRACT_ADDRESS_OPTION],
+    segments: ["track-and-trace", "documents", "accesses"],
+    summary: "List accesses for a Track and Trace document",
+  },
+
+  {
+    args: [
+      {
+        description: "Subject DID to filter accesses by",
+        example: "did:ebsi:ztqWJAmfyuUEf9Jvh97p167",
+        name: "subject",
+        required: true,
+      },
+    ],
+    group: "Track & Trace",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const subject = requiredArg(args, "subject");
+      const result = await client.GET("/track-and-trace/accesses", {
+        params: {
+          query: { ...q({ contractAddress: contractAddress(opts) }), subject },
+        },
+      });
+      return unwrap(result);
+    },
+    id: "track-and-trace.accesses.get",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["track-and-trace", "accesses", "get"],
+    summary: "Get access control entries for a subject DID",
+  },
+
+  {
+    args: [
+      {
+        description: "Creator DID to check",
+        example: "did:ebsi:zxaYaUtb8pvoAtYNWbKcveg",
+        name: "creator",
+        required: true,
+      },
+    ],
+    group: "Track & Trace",
+    async handler(args, opts, config) {
+      const client = getClient(config);
+      const creator = requiredArg(args, "creator");
+      // HEAD responses never carry a body: openapi-fetch always returns
+      // `data: undefined` for them (see its source), so the shared `unwrap()`
+      // (which throws whenever `data` is `undefined`) can't be used here --
+      // check `response.status` directly instead.
+      const { response } = await client.HEAD("/track-and-trace/accesses", {
+        params: {
+          query: { ...q({ contractAddress: contractAddress(opts) }), creator },
+        },
+      });
+      if (response.status === 204) return { allowed: true, creator };
+      if (response.status === 404) return { allowed: false, creator };
+      throw new ApiError(response.status, undefined);
+    },
+    id: "track-and-trace.accesses.check",
+    options: [CONTRACT_ADDRESS_OPTION],
+    segments: ["track-and-trace", "accesses", "check"],
+    summary:
+      "Check whether a DID is allowlisted as a Track and Trace document creator",
+  },
+
+  {
+    args: [],
+    group: "Track & Trace",
+    async handler(_args, _opts, config) {
+      const client = getClient(config);
+      const result = await client.GET("/track-and-trace/abi");
+      return unwrap(result);
+    },
+    id: "track-and-trace.abi",
+    options: [],
+    segments: ["track-and-trace", "abi"],
+    summary: "Get the ABI of the Track and Trace smart contract",
+  },
+];

package/src/commands/wallet.ts

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+
+import type { KeyMaterial } from "../crypto/wallet.ts";
+import type { CommandDescriptor } from "./registry.ts";
+
+import { getConfigFilePath } from "../config/config.ts";
+import { deriveWallet, generatePrivateKey } from "../crypto/wallet.ts";
+import { resolveSignAlg, resolveWallet } from "./shared/wallet-opts.ts";
+
+/**
+ * Persist { es256kPrivateKey, es256PrivateKey?, did } to the config file and
+ * emit a plaintext warning.
+ */
+function persistKeyToDisk(
+  es256kPrivateKey: string,
+  es256PrivateKey: string | undefined,
+  did: string,
+): void {
+  const configFilePath = getConfigFilePath();
+  let persisted: Record<string, string> = {};
+  if (existsSync(configFilePath)) {
+    try {
+      persisted = JSON.parse(readFileSync(configFilePath, "utf8")) as Record<
+        string,
+        string
+      >;
+    } catch /* v8 ignore next */ {
+      // ignore parse errors, start fresh
+    }
+  }
+  persisted["es256kPrivateKey"] = es256kPrivateKey;
+  if (es256PrivateKey !== undefined) {
+    persisted["es256PrivateKey"] = es256PrivateKey;
+  }
+  persisted["did"] = did;
+  writeFileSync(
+    configFilePath,
+    JSON.stringify(persisted, undefined, 2) + "\n",
+    "utf8",
+  );
+  process.stderr.write(
+    "\n⚠️  WARNING: Private key(s) stored in plaintext at " +
+      configFilePath +
+      "\n   Keep this file secret and restrict its permissions.\n\n",
+  );
+}
+
+/**
+ * Summarises one curve's `KeyMaterial` for command output.
+ */
+function summariseKey(key: KeyMaterial): {
+  alg: string;
+  kid: string;
+  thumbprint: string;
+} {
+  return { alg: key.alg, kid: key.kid, thumbprint: key.thumbprint };
+}
+
+const SIGN_ALG_OPTION = {
+  description:
+    'Which key signs VCs/VPs when both are configured: "ES256" or "ES256K". ' +
+    "Also read from EBSI_SIGN_ALG or `ebsi config set signAlg <alg>`.",
+  flags: "--sign-alg <alg>",
+};
+
+const ES256_KEY_OPTION = {
+  description:
+    "P-256 private key (hex), optional. Also read from EBSI_ES256_PRIVATE_KEY " +
+    "or `ebsi config set es256PrivateKey <hex>`.",
+  flags: "--es256-key <hex>",
+};
+
+export const walletCommands: CommandDescriptor[] = [
+  {
+    args: [],
+    group: "Wallet",
+    async handler(_args, opts, config) {
+      // Resolve keys: flag → env/persisted config → generate new (ES256K only)
+      const es256kPrivateKey =
+        opts["es256kKey"] ?? config.es256kPrivateKey ?? generatePrivateKey();
+      const es256PrivateKey = opts["es256Key"] ?? config.es256PrivateKey;
+      const signAlg = resolveSignAlg(opts, config);
+      const overrideDid = opts["did"] ?? config.did;
+
+      const details = await deriveWallet(
+        {
+          es256kPrivateKey,
+          ...(es256PrivateKey !== undefined && { es256PrivateKey }),
+          ...(signAlg !== undefined && { signAlg }),
+        },
+        overrideDid,
+      );
+
+      // Boolean commander flag arrives as true (or undefined); opts is cast to string record
+      // so we check truthiness
+      const save = Boolean(opts["save"]);
+      if (save) {
+        persistKeyToDisk(es256kPrivateKey, es256PrivateKey, details.did);
+      }
+
+      return {
+        address: details.address,
+        did: details.did,
+        es256: details.es256 ? summariseKey(details.es256) : undefined,
+        es256k: summariseKey(details.es256k),
+        privateKeys: save
+          ? "(saved to config)"
+          : "(not persisted — use --save to persist)",
+      };
+    },
+    id: "wallet.create",
+    options: [
+      {
+        description:
+          "Use this secp256k1 private key instead of generating a new one " +
+          "(0x-prefixed hex). Also read from EBSI_ES256K_PRIVATE_KEY or " +
+          "`ebsi config set es256kPrivateKey <hex>`.",
+        flags: "--es256k-key <hex>",
+      },
+      ES256_KEY_OPTION,
+      SIGN_ALG_OPTION,
+      {
+        description:
+          "Assign this EBSI DID (did:ebsi:...) instead of generating a new one. " +
+          "Also read from EBSI_DID or `ebsi config set did <did>`.",
+        flags: "--did <did>",
+      },
+      {
+        description:
+          "Persist the private key(s) and DID to the config file. " +
+          "⚠ WARNING: stored as plaintext.",
+        flags: "--save",
+      },
+    ],
+    segments: ["wallet", "create"],
+    summary:
+      "Generate (or import) a secp256k1 key pair and derive the associated EBSI DID, " +
+      "Ethereum address, and JWK thumbprint. Pass --es256-key to also register a P-256 " +
+      "key for signing VCs/VPs. " +
+      "Use --save to persist the key(s) to the config file (stored as plaintext — handle with care).",
+  },
+
+  {
+    args: [],
+    group: "Wallet",
+    async handler(_args, opts, config) {
+      const details = await resolveWallet(opts, config);
+
+      return {
+        address: details.address,
+        did: details.did,
+        es256: details.es256 ? summariseKey(details.es256) : undefined,
+        es256k: summariseKey(details.es256k),
+      };
+    },
+    id: "wallet.info",
+    options: [
+      {
+        description:
+          "secp256k1 private key (0x-prefixed hex) to derive info from.",
+        flags: "--es256k-key <hex>",
+      },
+      ES256_KEY_OPTION,
+      SIGN_ALG_OPTION,
+      {
+        description: "Override DID (did:ebsi:...)",
+        flags: "--did <did>",
+      },
+    ],
+    segments: ["wallet", "info"],
+    summary:
+      "Show the address, DID, kid, and JWK thumbprint derived from the configured key(s) " +
+      "(does not generate or persist anything).",
+  },
+];