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

package/src/ledger/write.ts

@@ -0,0 +1,381 @@
+import { ethers, FetchRequest } from "ethers";
+
+import type { CliConfig } from "../config/config.ts";
+import type { WalletDetails } from "../crypto/wallet.ts";
+import type { RegistryEntry } from "./registries.ts";
+
+import { printWarning } from "../output/format.ts";
+
+/**
+ * Manual gas overrides for `ledger write` / `ledger write-batch` (`--gas-limit`
+ * / `--gas-price`). When omitted, both are derived from the node:
+ * `gasLimit` via `eth_estimateGas`, fees via `eth_getFeeData` (EIP-1559 when
+ * the node supports it, legacy `gasPrice` otherwise). Setting `gasPrice`
+ * explicitly forces a legacy (type 0) transaction.
+ */
+export interface GasOverrides {
+  gasLimit?: bigint;
+  gasPrice?: bigint;
+}
+
+/**
+ * Gas limit used by `signWriteBatch` only, when an entry's `eth_estimateGas`
+ * fails and no `--gas-limit` override was given for the batch — e.g. an
+ * entry that only becomes valid once a prior entry in the same batch has
+ * been mined, so estimating it against current (pre-submission) chain state
+ * legitimately reverts. `writeToRegistry` (a single write, with no such
+ * batch-ordering ambiguity) surfaces an estimation failure as a real error
+ * instead of silently substituting this and submitting a transaction that
+ * may be doomed to revert on-chain.
+ */
+const FALLBACK_GAS_LIMIT = 0x1_00_00_00n;
+
+/**
+ * Percentage headroom added on top of a node-estimated (not overridden) gas
+ * limit. `eth_estimateGas` reflects chain state at call time; by the time
+ * the signed transaction actually lands, state may have shifted enough to
+ * need more gas than that moment-in-time estimate — e.g. `write-batch`
+ * submitting several writes together where an earlier entry changes storage
+ * a later entry also touches, or simply other transactions landing first.
+ * A call that would genuinely revert is still a real error either way; this
+ * buffer only protects an estimate that succeeds but comes in slightly low.
+ */
+const GAS_LIMIT_BUFFER_PERCENT = 120n;
+
+export interface SignWriteBatchOptions {
+  /**
+   * Resolved CLI configuration (used for baseUrl)
+   */
+  config: CliConfig;
+  /**
+   * The writes to sign, in submission order
+   */
+  entries: BatchWriteEntry[];
+  /**
+   * Manual gas overrides shared by every entry in the batch. By default gas
+   * is estimated dynamically (see `GasOverrides`).
+   */
+  gas?: GasOverrides;
+  /**
+   * Access token (Bearer) shared by every write in the batch
+   */
+  token: string;
+  /**
+   * Resolved wallet — `wallet.wallet` (the ethers Wallet, always the
+   * secp256k1 key) signs the transaction
+   */
+  wallet: WalletDetails;
+}
+
+export interface WriteOptions {
+  /**
+   * 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 function name (e.g. "insertDidDocument")
+   */
+  functionName: string;
+  /**
+   * Manual gas overrides. By default gas is estimated dynamically (see
+   * `GasOverrides`).
+   */
+  gas?: GasOverrides;
+  /**
+   * Registry entry providing the ABI interface
+   */
+  registry: RegistryEntry;
+  /**
+   * Access token (Bearer) to attach to /ledger requests
+   */
+  token: string;
+  /**
+   * Resolved wallet — `wallet.wallet` (the ethers Wallet, always the
+   * secp256k1 key) signs the transaction
+   */
+  wallet: WalletDetails;
+}
+
+export interface WriteReceipt {
+  blockHash: string | undefined;
+  blockNumber: number | undefined;
+  contractAddress: string;
+  from: string;
+  hash: string;
+  status: number | undefined;
+  to: string;
+}
+
+interface BatchWriteEntry {
+  /**
+   * Parsed function arguments (from the JSON array in the batch file)
+   */
+  functionArgs: unknown[];
+  /**
+   * Smart contract function name (e.g. "insertDidDocument")
+   */
+  functionName: string;
+  /**
+   * Registry entry providing the ABI interface
+   */
+  registry: RegistryEntry;
+  /**
+   * Contract address (0x-prefixed)
+   */
+  to: string;
+}
+
+/**
+ * Encodes and signs a batch of registry write transactions from the same
+ * wallet, assigning each one a sequential nonce (starting from the wallet's
+ * current pending nonce) so they can be submitted together as a single
+ * JSON-RPC batch request without nonce collisions.
+ *
+ * Returns the raw signed transactions in the same order as `entries`, ready
+ * to be wrapped in `eth_sendRawTransaction` JSON-RPC requests. Does not
+ * submit anything — the caller is responsible for building and sending the
+ * batch (see `ledger write-batch`).
+ */
+export async function signWriteBatch(
+  opts: SignWriteBatchOptions,
+): Promise<string[]> {
+  const { config, entries, gas, token, wallet: walletDetails } = opts;
+
+  const provider = makeLedgerProvider(config, token);
+  const connectedWallet = walletDetails.wallet.connect(provider);
+
+  // The base nonce and the fee fields are shared by every entry in the
+  // batch, so resolve each with a single RPC round-trip up front (rather
+  // than once per entry) and fan out from there.
+  const [baseNonce, feeFields] = await Promise.all([
+    connectedWallet.getNonce("pending"),
+    resolveFeeFields(provider, gas),
+  ]);
+
+  // Each entry gets a precomputed, distinct nonce (baseNonce + index), so
+  // encoding + estimating + populating + signing has no cross-entry
+  // dependency and can run concurrently — only the final array order (==
+  // submission order) matters, which Promise.all preserves regardless of
+  // completion timing.
+  return Promise.all(
+    entries.map(async ({ functionArgs, functionName, registry, to }, index) => {
+      const position = `Entry #${(index + 1).toString()}`;
+      let data: string;
+      try {
+        data = registry
+          .getInterface()
+          .encodeFunctionData(functionName, functionArgs);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(
+          `${position}: failed to encode function data for "${functionName}": ${message}. ` +
+            "Check the function name and argument types.",
+          { cause: error },
+        );
+      }
+
+      let gasLimit: bigint;
+      try {
+        gasLimit = await resolveGasLimit(
+          provider,
+          { data, from: walletDetails.address, to },
+          gas,
+          position,
+        );
+      } catch (error) {
+        // Unlike `writeToRegistry`, a batch entry can legitimately fail
+        // estimation against pre-submission chain state — e.g. it only
+        // becomes valid once an earlier entry in this same batch has been
+        // mined — so fall back to a generous default instead of failing the
+        // whole batch over it.
+        const message = error instanceof Error ? error.message : String(error);
+        printWarning(
+          `${message}; falling back to the default gas limit ${FALLBACK_GAS_LIMIT.toString()}.`,
+        );
+        gasLimit = FALLBACK_GAS_LIMIT;
+      }
+
+      const populated = await connectedWallet.populateTransaction({
+        ...feeFields,
+        data,
+        gasLimit,
+        nonce: baseNonce + index,
+        to,
+      });
+      return connectedWallet.signTransaction(populated);
+    }),
+  );
+}
+
+/**
+ * Encodes a contract function call, signs it with the wallet, and submits it
+ * through the Ledger service (`POST /ledger`) using Pattern A (see
+ * `makeLedgerProvider`).
+ *
+ * ethers automatically fills nonce and chainId. Gas is resolved dynamically
+ * against the node (fees via `getFeeData`, limit via `estimateGas`) unless
+ * overridden — see `GasOverrides`.
+ */
+export async function writeToRegistry(
+  opts: WriteOptions,
+): Promise<WriteReceipt> {
+  const {
+    config,
+    contractAddress,
+    functionArgs,
+    functionName,
+    gas,
+    registry,
+    token,
+    wallet: walletDetails,
+  } = opts;
+
+  // Encode calldata
+  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 = makeLedgerProvider(config, token);
+
+  const [feeFields, gasLimit] = await Promise.all([
+    resolveFeeFields(provider, gas),
+    resolveGasLimit(
+      provider,
+      { data, from: walletDetails.address, to: contractAddress },
+      gas,
+      "ledger write",
+    ),
+  ]);
+
+  // Connect wallet to the provider and send the transaction
+  const connectedWallet = walletDetails.wallet.connect(provider);
+  const tx = await connectedWallet.sendTransaction({
+    ...feeFields,
+    data,
+    gasLimit,
+    to: contractAddress,
+  });
+
+  const receipt = await tx.wait();
+
+  // receipt?.status is typed `number | null` in ethers; coerce null to undefined
+  // so the WriteReceipt interface stays null-free (unicorn/no-null)
+  const status = receipt?.status;
+  return {
+    blockHash: receipt?.blockHash,
+    blockNumber: receipt?.blockNumber,
+    contractAddress,
+    from: walletDetails.address,
+    hash: tx.hash,
+    status: status === null ? undefined : status,
+    to: contractAddress,
+  };
+}
+
+/**
+ * Builds a JSON-RPC provider pointed at the Ledger service (`POST /ledger`)
+ * using Pattern A:
+ *
+ *   FetchRequest → preflightFunc injects Bearer token → JsonRpcProvider
+ *
+ * Shared by `writeToRegistry` (single write) and `signWriteBatch` (several
+ * writes signed against one nonce sequence and submitted as a single
+ * JSON-RPC batch).
+ */
+function makeLedgerProvider(
+  config: CliConfig,
+  token: string,
+): ethers.JsonRpcProvider {
+  const ledgerUrl = `${config.baseUrl}/ledger`;
+  const fetchReq = new FetchRequest(ledgerUrl);
+  // @ts-expect-error preflightFunc expects Promise<FetchRequest> in ethers types but sync return is accepted at runtime
+  fetchReq.preflightFunc = (req: FetchRequest) => {
+    req.setHeader("Authorization", `Bearer ${token}`);
+    return req;
+  };
+  return new ethers.JsonRpcProvider(fetchReq);
+}
+
+/**
+ * Resolves the fee fields for a transaction: an explicit `gas.gasPrice`
+ * override always wins, and stamps `type: 0` alongside it — otherwise, on a
+ * network that also supports EIP-1559 (like this one), ethers silently
+ * reinterprets a bare `gasPrice` as identical `maxFeePerGas`/
+ * `maxPriorityFeePerGas` values and signs a type-2 transaction instead (see
+ * `ethers`' `Signer.populateTransaction`), defeating the override. Without an
+ * override, this asks the node for its current fee data and forwards
+ * EIP-1559 fields (`maxFeePerGas`/`maxPriorityFeePerGas`) when the node
+ * supports them, falling back to a legacy `gasPrice` otherwise. Never
+ * returns both shapes — `ethers.Transaction` rejects a mix of the two.
+ */
+async function resolveFeeFields(
+  provider: ethers.JsonRpcProvider,
+  overrides: GasOverrides | undefined,
+): Promise<Record<string, bigint | number>> {
+  if (overrides?.gasPrice !== undefined) {
+    return { gasPrice: overrides.gasPrice, type: 0 };
+  }
+
+  const feeData = await provider.getFeeData();
+  if (feeData.maxFeePerGas !== null && feeData.maxPriorityFeePerGas !== null) {
+    return {
+      maxFeePerGas: feeData.maxFeePerGas,
+      maxPriorityFeePerGas: feeData.maxPriorityFeePerGas,
+    };
+  }
+  if (feeData.gasPrice !== null) {
+    return { gasPrice: feeData.gasPrice };
+  }
+  /* v8 ignore next -- defensive: every network ethers supports returns at
+     least one of the two fee shapes from getFeeData() */
+  return {};
+}
+
+/**
+ * Resolves the gas limit for a transaction: an explicit `gas.gasLimit`
+ * override always wins and is used exactly as given (no buffer). Otherwise
+ * asks the node to estimate it via `eth_estimateGas` and adds
+ * `GAS_LIMIT_BUFFER_PERCENT` headroom. A genuine estimation failure (e.g. a
+ * call that would revert) propagates as a descriptive error — this function
+ * never silently substitutes a fallback limit; `signWriteBatch`, which has a
+ * legitimate reason an entry's estimation can fail transiently, decides for
+ * itself whether to fall back (see `FALLBACK_GAS_LIMIT`).
+ */
+async function resolveGasLimit(
+  provider: ethers.JsonRpcProvider,
+  tx: { data: string; from: string; to: string },
+  overrides: GasOverrides | undefined,
+  label: string,
+): Promise<bigint> {
+  if (overrides?.gasLimit !== undefined) {
+    return overrides.gasLimit;
+  }
+
+  try {
+    const estimated = await provider.estimateGas(tx);
+    return (estimated * GAS_LIMIT_BUFFER_PERCENT) / 100n;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `${label}: gas estimation failed (${message}). Provide --gas-limit to override.`,
+      { cause: error },
+    );
+  }
+}

package/src/onboarding/vc.ts

@@ -0,0 +1,205 @@
+import type { EbsiIssuer } from "@europeum-ebsi/verifiable-credential";
+import type { Schemas } from "@europeum-ebsi/verifiable-credential/vcdm11.js";
+
+import { fromUrl } from "@europeum-ebsi/ebsi-uri";
+import { metadata as attestationSchema } from "@europeum-ebsi/vcdm1.1-attestation-schema";
+import { createVerifiableCredentialJwt } from "@europeum-ebsi/verifiable-credential/vcdm11.js";
+import { randomUUID } from "node:crypto";
+
+import type { CliConfig } from "../config/config.ts";
+
+import { buildEbsiEnvConfig } from "../config/ebsi-env.ts";
+import { deriveEs256Issuer, deriveWallet } from "../crypto/wallet.ts";
+
+/**
+ * The services whose resources this credential's ids can name. Narrower than
+ * `buildEbsiEnvConfig`'s list on purpose -- `credentialSchema.id` and
+ * `termsOfUse.id` only ever point at a schema or an issuer's accreditation.
+ */
+const EBSI_URI_SERVICES = [
+  "did-registry",
+  "issuers-registry",
+  "schemas-registry",
+];
+
+export interface BuildOnboardingVcOptions {
+  /**
+   * Resolved CLI config. Supplies the API base URL the VC's resource
+   * references are derived from (`credentialSchema`, `termsOfUse` -- already
+   * including the `/v1` prefix) and, via `buildEbsiEnvConfig`, the EBSI
+   * network they are named against. Neither reference keeps the host: both
+   * are rewritten to EBSI URIs by `toEbsiUri`.
+   */
+  config: CliConfig;
+  holderDid: string;
+  holderThumbprint: string;
+  /**
+   * The RTAO's Issuers Registry attribute id carrying its RootTAO
+   * self-attestation — see `ebsi issuers-registry issuers attributes list
+   * <rtaoDid>`. Accepted with or without a `0x`/`0h` prefix; the credential
+   * always names it in the registry's canonical unprefixed form.
+   */
+  rtaoAttributeId: string;
+  rtaoDid: string;
+  /**
+   * The RTAO's secp256k1 private key, used to sign the VC ES256K when no
+   * ES256 key is given.
+   */
+  rtaoEs256kPrivateKey?: string;
+  /**
+   * The RTAO's P-256 private key. When provided the VC is signed ES256 and
+   * `rtaoEs256kPrivateKey` is not used for signing at all. Required against a
+   * deployment whose Authorisation service restricts the `did-registry:invite`
+   * credential format to ES256 -- ES256K is accepted only where every scope
+   * shares `SUPPORTED_ALGS` (`["ES256", "ES256K"]`).
+   */
+  rtaoEs256PrivateKey?: string;
+}
+
+export interface BuildOnboardingVcResult {
+  // Algorithm the VC was signed with, so callers can report the key used.
+  alg: EbsiIssuer["alg"];
+  rtaoKid: string;
+  vcJwt: string;
+}
+
+/**
+ * Signs a "VerifiableAuthorisationToOnboard" VC for `holderDid`/`holderThumbprint`,
+ * issued by the given RTAO. Mirrors `buildVerifiableAuthorisationToOnboard` in
+ * `api/tests/utils/access-tokens.ts` (the only other place in the repo that
+ * builds this VC type), but as a reusable, non-test-only function.
+ *
+ * The RTAO must already be registered on chain as `RootTAO` (e.g. via
+ * `hardhat bootstrap` or `contracts/deploy-toolkit/scripts/tests/setup-rtao.ts`)
+ * for the resulting VC to pass the Authorisation service's trust-chain check.
+ *
+ * @throws If neither `rtaoEs256PrivateKey` nor `rtaoEs256kPrivateKey` is set.
+ */
+export async function buildOnboardingVc(
+  opts: BuildOnboardingVcOptions,
+): Promise<BuildOnboardingVcResult> {
+  const {
+    config,
+    holderDid,
+    holderThumbprint,
+    rtaoAttributeId,
+    rtaoDid,
+    rtaoEs256kPrivateKey,
+    rtaoEs256PrivateKey,
+  } = opts;
+  const issuer = await resolveIssuer(
+    rtaoDid,
+    rtaoEs256PrivateKey,
+    rtaoEs256kPrivateKey,
+  );
+
+  // `config.baseUrl` already carries the API version prefix (e.g.
+  // "https://api-pilot.ebsi.eu/v1"), so resource references are built from it
+  // directly rather than from the bare origin plus a hardcoded "/v1".
+  const apiBaseUrl = config.baseUrl.replace(/\/+$/, "");
+  const ebsiEnvConfig = buildEbsiEnvConfig(config);
+  const { name: network } = ebsiEnvConfig.network;
+
+  // The Issuers Registry returns attribute ids unprefixed, and that's their
+  // canonical form in a resource path, so strip any "0x"/"0h" the caller
+  // passed -- the URI must name the attribute identically however the id was
+  // supplied, or two credentials naming the same attribute won't compare equal.
+  const attributeId = rtaoAttributeId.replace(/^0[hx]/, "");
+
+  const issuanceDate = new Date(Date.now() - 5000);
+  const expirationDate = new Date(issuanceDate.getTime() + 2 * 60 * 60 * 1000);
+  const iso = (date: Date) => `${date.toISOString().slice(0, -5)}Z`;
+
+  const vcPayload: Schemas["Attestation"] = {
+    "@context": ["https://www.w3.org/2018/credentials/v1"],
+    credentialSchema: {
+      id: toEbsiUri(
+        `${apiBaseUrl}/schemas-registry/schemas/${attestationSchema.id.base16}`,
+        network,
+      ),
+      type: "FullJsonSchemaValidator2021",
+    },
+    credentialSubject: {
+      id: holderDid,
+      jwkThumbprint: holderThumbprint,
+      type: "same-device",
+    },
+    expirationDate: iso(expirationDate),
+    id: `urn:uuid:${randomUUID()}`,
+    issuanceDate: iso(issuanceDate),
+    issued: iso(issuanceDate),
+    issuer: rtaoDid,
+    termsOfUse: {
+      id: toEbsiUri(
+        `${apiBaseUrl}/issuers-registry/issuers/${rtaoDid}/attributes/${attributeId}`,
+        network,
+      ),
+      type: "IssuanceCertificate",
+    },
+    type: [
+      "VerifiableCredential",
+      "VerifiableAttestation",
+      "VerifiableAuthorisationToOnboard",
+    ],
+    validFrom: iso(issuanceDate),
+  };
+
+  const vcJwt = await createVerifiableCredentialJwt(
+    vcPayload,
+    issuer,
+    ebsiEnvConfig,
+    { skipValidation: true },
+  );
+
+  return { alg: issuer.alg, rtaoKid: issuer.kid, vcJwt };
+}
+
+/**
+ * Picks the signing identity: the RTAO's ES256 key when it has one, otherwise
+ * the ES256K ledger key `deriveWallet` doubles up as a JWT signer. Preferring
+ * ES256 is deliberate -- every deployment that accepts ES256K for this
+ * credential also accepts ES256, but not the reverse.
+ */
+async function resolveIssuer(
+  rtaoDid: string,
+  rtaoEs256PrivateKey: string | undefined,
+  rtaoES256kPrivateKey: string | undefined,
+): Promise<EbsiIssuer> {
+  if (rtaoEs256PrivateKey) {
+    return deriveEs256Issuer(rtaoEs256PrivateKey, rtaoDid);
+  }
+  if (!rtaoES256kPrivateKey) {
+    throw new Error(
+      "No RTAO signing key. Provide --rtao-es256-key <hex> (P-256, signs " +
+        "ES256) or --rtao-es256k-key <hex> (secp256k1, signs ES256K), or set " +
+        "EBSI_RTAO_ES256_PRIVATE_KEY / EBSI_RTAO_ES256K_PRIVATE_KEY.",
+    );
+  }
+  const wallet = await deriveWallet(
+    { es256kPrivateKey: rtaoES256kPrivateKey },
+    rtaoDid,
+  );
+  return wallet.es256k.issuer;
+}
+
+/**
+ * Turns a core-services URL into the EBSI URI it names
+ * (`ebsi:<network>:<service>:<resource>`), so ids embedded in a VC
+ * (`credentialSchema.id`, `termsOfUse.id`, ...) name a resource on the EBSI
+ * network rather than binding to whichever node happened to serve this
+ * command's requests -- a node that may later be dropped from the trust
+ * chain, invalidating every credential that pointed at it directly.
+ *
+ * `hosts` is taken from the URL itself rather than from `buildEbsiEnvConfig`:
+ * `parseUrl` matches `config.hosts` against the URL's `host`, which carries
+ * the port, while the shared env config holds the bare `hostname` -- so a
+ * local `localhost:3000` base URL would otherwise be rejected outright.
+ */
+function toEbsiUri(url: string, network: string): string {
+  return fromUrl(url, {
+    hosts: [new URL(url).host],
+    network: { name: network },
+    scheme: "ebsi",
+    services: EBSI_URI_SERVICES,
+  });
+}