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

package/src/ledger/read.ts

@@ -0,0 +1,70 @@
+import { ethers } from "ethers";
+
+import type { CliConfig } from "../config/config.ts";
+import type { RegistryEntry } from "./registries.ts";
+
+export interface ReadOptions {
+  /**
+   * Resolved CLI configuration (used for baseUrl)
+   */
+  config: CliConfig;
+  /**
+   * Contract address (0x-prefixed)
+   */
+  contractAddress: string;
+  /**
+   * Parsed function arguments (from the JSON array on the CLI)
+   */
+  functionArgs: unknown[];
+  /**
+   * Smart contract view/pure function name (e.g. "getTimestamp")
+   */
+  functionName: string;
+  /**
+   * Registry entry providing the ABI interface
+   */
+  registry: RegistryEntry;
+}
+
+/**
+ * Encodes a contract view/pure function call and resolves it via the Ledger
+ * service's `eth_call` (served anonymously — no Bearer token needed, unlike
+ * `writeToRegistry`), decoding the result with the same registry interface
+ * `writeToRegistry` uses to encode writes.
+ *
+ * Always returns the function's outputs as an array, in declaration order,
+ * regardless of how many there are — the same shape for every function,
+ * rather than guessing whether to unwrap a single return value.
+ */
+export async function readFromRegistry(opts: ReadOptions): Promise<unknown> {
+  const { config, contractAddress, functionArgs, functionName, registry } =
+    opts;
+
+  const iface = registry.getInterface();
+  let data: string;
+  try {
+    data = iface.encodeFunctionData(functionName, functionArgs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to encode function data for "${functionName}": ${message}. ` +
+        "Check the function name and argument types.",
+      { cause: error },
+    );
+  }
+
+  const provider = new ethers.JsonRpcProvider(`${config.baseUrl}/ledger`);
+  const result = await provider.call({ data, to: contractAddress });
+  const decoded = iface.decodeFunctionResult(functionName, result);
+
+  return toJsonSafe(decoded);
+}
+
+/**
+ * Recursively converts ethers decode output (BigInt values, nested Result
+ * arrays) into a shape `JSON.stringify` can handle without throwing.
+ */
+function toJsonSafe(value: unknown): unknown {
+  if (typeof value === "bigint") return value.toString();
+  return Array.isArray(value) ? value.map((item) => toJsonSafe(item)) : value;
+}

package/src/ledger/registries.ts

@@ -0,0 +1,285 @@
+import { ethers } from "ethers";
+import { createRequire } from "node:module";
+
+const req = createRequire(import.meta.url);
+
+export interface RegistryEntry {
+  /**
+   * Environment variable that holds the contract address.
+   * Mirrors the API's configuration env key (e.g. DID_REGISTRY_CONTRACT_ADDRESS).
+   *
+   * Dual-purpose: `ledger write` uses it (via `--to`) to pick a signing
+   * target, and read commands' `--contract-address` flag (via
+   * `resolveContractAddress`) uses the same variable as their default query
+   * target, so reads and writes stay consistent within one environment. If
+   * you only meant to set this for a one-off write, note that it will also
+   * silently redirect reads in the same shell/session unless you pass
+   * `--contract-address` explicitly on those calls.
+   */
+  addressEnvKey: string;
+  /**
+   * Default EBSI scope for `--auto-token` (e.g. "did-registry:write")
+   */
+  defaultScope: string;
+  /**
+   * Returns the ethers Interface for ABI encoding
+   */
+  getInterface(): ethers.Interface;
+}
+
+/**
+ * Loads a contract factory from a CJS package via `createRequire` and calls
+ * its static `createInterface()` method to get an `ethers.Interface`.
+ *
+ * The factory packages are CommonJS; `createRequire` is the idiomatic ESM way
+ * to consume CJS in a Node.js ESM module.
+ */
+function loadInterface(pkg: string, factoryName: string): ethers.Interface {
+  const mod = req(pkg) as Record<
+    string,
+    undefined | { createInterface(): ethers.Interface }
+  >;
+  const factory = mod[factoryName];
+  /* v8 ignore next 4 — factory names are hardcoded; unreachable in practice */
+  if (!factory) {
+    throw new Error(
+      `Factory class "${factoryName}" not found in package "${pkg}"`,
+    );
+  }
+  return factory.createInterface();
+}
+
+/**
+ * Registry table: CLI name → factory / scope / address info.
+ *
+ * Contract addresses are NOT served by the API; they must be supplied via
+ * `--to`, the matching env var, or (for convenience) the persisted config.
+ */
+export const REGISTRIES: Record<string, RegistryEntry | undefined> = {
+  "did-registry": {
+    addressEnvKey: "DID_REGISTRY_CONTRACT_ADDRESS",
+    defaultScope: "did-registry:write",
+    getInterface() {
+      return loadInterface(
+        "@europeum-ebsi/did-registry-contract",
+        "DidRegistry__factory",
+      );
+    },
+  },
+  "issuers-registry": {
+    addressEnvKey: "ISSUERS_REGISTRY_CONTRACT_ADDRESS",
+    defaultScope: "issuers-registry:write",
+    getInterface() {
+      return loadInterface(
+        "@europeum-ebsi/issuers-registry-contract",
+        "IssuersRegistry__factory",
+      );
+    },
+  },
+  "policies-registry": {
+    addressEnvKey: "POLICIES_REGISTRY_CONTRACT_ADDRESS",
+    defaultScope: "policies-registry:write",
+    getInterface() {
+      return loadInterface(
+        "@europeum-ebsi/policies-registry-contract",
+        "PoliciesRegistry__factory",
+      );
+    },
+  },
+  "schemas-registry": {
+    addressEnvKey: "SCHEMAS_REGISTRY_CONTRACT_ADDRESS",
+    defaultScope: "schemas-registry:write",
+    getInterface() {
+      return loadInterface(
+        "@europeum-ebsi/schemas-registry-contract",
+        "SchemasRegistry__factory",
+      );
+    },
+  },
+  timestamp: {
+    addressEnvKey: "TIMESTAMP_CONTRACT_ADDRESS",
+    defaultScope: "timestamp:write",
+    getInterface() {
+      return loadInterface(
+        "@europeum-ebsi/timestamp-contract",
+        "Timestamp__factory",
+      );
+    },
+  },
+  "track-and-trace": {
+    addressEnvKey: "TRACK_AND_TRACE_CONTRACT_ADDRESS",
+    defaultScope: "track-and-trace:write",
+    getInterface() {
+      return loadInterface(
+        "@europeum-ebsi/track-and-trace-contract",
+        "TrackAndTrace__factory",
+      );
+    },
+  },
+};
+
+/**
+ * Returns all known registry names (for help text / validation).
+ */
+export const REGISTRY_NAMES = Object.keys(REGISTRIES);
+
+/**
+ * A `--contract-address` CLI option, plus its resolver against `envKey`.
+ */
+export interface ContractAddressOption {
+  option: { description: string; flags: string };
+  resolve: (opts: Record<string, string>) => string | undefined;
+}
+
+/**
+ * One resolved write target in a batch: which registry, which function, and
+ * which contract instance. `functionName` is optional so callers that don't
+ * need the `insertDidDocument` special-case (see `defaultScopeFor`) can omit
+ * it.
+ */
+export interface RegistryTarget {
+  functionName?: string;
+  registryName: string;
+  to: string;
+}
+
+/**
+ * Builds a `--contract-address` option + resolver reading from `envKey`, with
+ * a given description. Used directly by `contracts-registry` commands, which
+ * (unlike every other registry) have no `ledger write` path and therefore no
+ * `REGISTRIES[...].addressEnvKey` to derive from — see
+ * `contractAddressOptionFor` for the common case.
+ */
+export function contractAddressOption(
+  envKey: string,
+  description: string,
+): ContractAddressOption {
+  return {
+    option: { description, flags: "--contract-address <address>" },
+    resolve: (opts) => resolveContractAddress(opts, envKey),
+  };
+}
+
+/**
+ * Builds a `--contract-address` option + resolver for `registryName`, using
+ * its `REGISTRIES[...].addressEnvKey` and the standard description noting
+ * that it defaults to the same address `ledger write` signs against.
+ */
+export function contractAddressOptionFor(
+  registryName: string,
+): ContractAddressOption {
+  const registry = REGISTRIES[registryName];
+  if (!registry) {
+    throw new Error(
+      `Unknown registry "${registryName}". Known registries: ${REGISTRY_NAMES.join(", ")}`,
+    );
+  }
+  return contractAddressOption(
+    registry.addressEnvKey,
+    `Contract address to query. Defaults to $${registry.addressEnvKey} if set (the same address "ledger write" signs against), otherwise the API's configured default.`,
+  );
+}
+
+/**
+ * Track and Trace's scope requirement per function — mirrors
+ * `TRACK_AND_TRACE_FUNCTION_SCOPE` in `api/src/modules/ledger/validators/track-and-trace.ts`
+ * (the API's authoritative, per-function scope gate for this registry).
+ * There's no shared package to import this from (it's private to the API's
+ * ledger validators), so keep this in sync by hand if that table changes.
+ *
+ * `registry.defaultScope` ("track-and-trace:write") only covers `grantAccess`,
+ * `removeDocument`, `revokeAccess`, and `writeEvent` — `authoriseDid` needs
+ * the VC-required `track-and-trace:authorise`, and `createDocument`/`commitCreateDocument`
+ * need `track-and-trace:create`.
+ */
+const TRACK_AND_TRACE_FUNCTION_SCOPE: Record<string, string> = {
+  authoriseDid: "track-and-trace:authorise",
+  commitCreateDocument: "track-and-trace:create",
+  createDocument: "track-and-trace:create",
+};
+
+/**
+ * The scope family a write to `registryName`/`functionName` needs, for
+ * deriving a default `--auto-token` scope.
+ *
+ * This is `registry.defaultScope` for every function except:
+ * - DID Registry's `insertDidDocument`, which (unlike every other DID
+ *   Registry write) onboards a *new* DID and so requires `did-registry:invite`, not
+ *   `did-registry:write` — see `api/src/modules/ledger/validators/did-registry.ts`.
+ * - Track and Trace's `authoriseDid`/`createDocument`/`commitCreateDocument`
+ *   — see `TRACK_AND_TRACE_FUNCTION_SCOPE`.
+ */
+export function defaultScopeFor(
+  registryName: string,
+  functionName: string | undefined,
+  registry: RegistryEntry,
+): string {
+  if (registryName === "did-registry" && functionName === "insertDidDocument") {
+    return "did-registry:invite";
+  }
+  if (registryName === "track-and-trace" && functionName !== undefined) {
+    const scope = TRACK_AND_TRACE_FUNCTION_SCOPE[functionName];
+    if (scope) {
+      return scope;
+    }
+  }
+  return registry.defaultScope;
+}
+
+/**
+ * Derives the minimal space-separated multi-scope string covering every
+ * resolved `(registryName, functionName, to)` target, using `defaultScopeFor`
+ * — instance-targeted at the resolved `to` address, since each write is
+ * authorised against the specific beacon-proxy instance it's sent to (see
+ * "Auto-target the write instance" in the instance-targeting design). Scopes
+ * are deduped and sorted so the result is independent of input order — used
+ * by `ledger write-batch --auto-token` to mint a single token that authorises
+ * every write in the batch.
+ *
+ * Throws if any registry name is unknown, or if the batch targets two
+ * different instances under the same scope family (a single access token can
+ * only target one instance per family — split the batch, or pass
+ * `--token`/`--scope` explicitly in that case).
+ */
+export function deriveScopeForRegistries(targets: RegistryTarget[]): string {
+  const addressByFamily = new Map<string, string>();
+  for (const { functionName, registryName, to } of targets) {
+    const registry = REGISTRIES[registryName];
+    if (!registry) {
+      throw new Error(
+        `Unknown registry "${registryName}". Known registries: ${REGISTRY_NAMES.join(", ")}`,
+      );
+    }
+
+    const family = defaultScopeFor(registryName, functionName, registry);
+    const existingAddress = addressByFamily.get(family);
+    if (existingAddress !== undefined && existingAddress !== to) {
+      throw new Error(
+        `Batch targets two different "${family}" contract instances (${existingAddress} and ${to}) ` +
+          "in a single --auto-token request. A single access token can only target one instance " +
+          "per scope family — split the batch, or provide --token/--scope explicitly.",
+      );
+    }
+    addressByFamily.set(family, to);
+  }
+
+  return [...addressByFamily]
+    .map(([family, address]) => `${family}:${address}`)
+    .toSorted((a, b) => a.localeCompare(b))
+    .join(" ");
+}
+
+/**
+ * Resolves the contract address for a read command: an explicit
+ * `--contract-address` flag value if given, otherwise the given environment
+ * variable (typically `RegistryEntry.addressEnvKey`, the same variable
+ * `ledger write` uses to pick a signing target — see that field's doc
+ * comment). Falls through to `undefined` (the API's own configured default)
+ * if neither is set.
+ */
+function resolveContractAddress(
+  opts: Record<string, string>,
+  envKey: string,
+): string | undefined {
+  return opts["contractAddress"] ?? process.env[envKey];
+}