@did-btcr2/cli 0.12.18 → 0.14.0

package/src/commands/update.ts

@@ -1,3 +1,4 @@
+import type { PublishToCasMode } from '@did-btcr2/api';
 import { KeyManagerSigner } from '@did-btcr2/key-manager';
 import type { Command } from 'commander';
 import { deriveNetwork, type ApiFactory } from '../config.js';
@@ -37,12 +38,20 @@ export function registerUpdateCommand(
       'Beacon ID as a JSON string',
       parseJsonArg('--beacon-id'),
     )
+    .option(
+      '--publish-to-cas <mode>',
+      'Publish update artifacts to a writable CAS before broadcast: auto|always|never. '
+        + 'CAS publication is optional; the default distributes the returned artifacts via sidecar.',
+      parsePublishToCasMode,
+      'never',
+    )
     .action(async (options: {
       sourceDocument       : unknown;
       sourceVersionId      : string;
       patches              : unknown;
       verificationMethodId : string;
       beaconId             : unknown;
+      publishToCas         : PublishToCasMode;
     }) => {
       if (!/^\d+$/.test(options.sourceVersionId)) {
         throw new CLIError(
@@ -70,6 +79,12 @@ export function registerUpdateCommand(
       const api = factory(network, globals());
       const keyId = resolveKeyRef(api.kms.kms, globals().signingKey);
       const signer = new KeyManagerSigner(api.kms.kms, keyId);
+      // CAS publication is optional and never required: every beacon update can
+      // be completed and shared via sidecar alone. It is opt-in and defaults to
+      // 'never'; pass --publish-to-cas auto|always to publish the signed update
+      // (and, for CAS beacons, the announcement) to a writable CAS configured
+      // via --cas-rpc-url. The returned artifacts (txid, announcement, proof)
+      // are always printed for sidecar distribution regardless.
       const data = await api.btcr2.update({
         sourceDocument       : parsed.sourceDocument,
         patches              : parsed.patches,
@@ -77,11 +92,27 @@ export function registerUpdateCommand(
         verificationMethodId : parsed.verificationMethodId,
         beaconId             : parsed.beaconId,
         signer,
+        publishToCas         : options.publishToCas,
       });
       console.log(formatResult({ action: 'update', data }, globals()));
     });
 }
 
+/**
+ * Commander argParser for `--publish-to-cas`. Validates the value is one of the
+ * three {@link PublishToCasMode} policies, erroring at parse time otherwise.
+ */
+function parsePublishToCasMode(value: string): PublishToCasMode {
+  if (value !== 'auto' && value !== 'always' && value !== 'never') {
+    throw new CLIError(
+      '--publish-to-cas must be one of "auto", "always", or "never".',
+      'INVALID_ARGUMENT_ERROR',
+      { value },
+    );
+  }
+  return value;
+}
+
 /**
  * Returns a commander argParser that validates JSON.
  * Errors at parse time with a clear flag reference.

package/src/config.ts

@@ -1,4 +1,4 @@
-import { createApi, Identifier, type BitcoinApiConfig, type DidBtcr2Api } from '@did-btcr2/api';
+import { createApi, Identifier, type BitcoinApiConfig, type CasConfig, type DidBtcr2Api } from '@did-btcr2/api';
 import type { KeyManager } from '@did-btcr2/key-manager';
 import { readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
@@ -23,7 +23,10 @@ export type ConnectionOverrides = {
   btcRpcUrl?      : string;
   btcRpcUser?     : string;
   btcRpcPass?     : string;
+  /** IPFS HTTP gateway for CAS reads (read-only). */
   casGateway?     : string;
+  /** IPFS HTTP RPC endpoint for a writable CAS (reads + writes). */
+  casRpcUrl?      : string;
   config?         : string;
   profile?        : string;
   /** Keystore file path. Overrides the default `$XDG_DATA_HOME/btcr2/keystore.json`. */
@@ -49,7 +52,7 @@ export type ConnectionOverrides = {
  *     },
  *     "bitcoin": {
  *       "btc": { "rest": "https://my-mempool/api" },
- *       "cas": { "gateway": "https://ipfs.io" }
+ *       "cas": { "gateway": "https://ipfs.io", "rpcUrl": "http://127.0.0.1:5001" }
  *     }
  *   }
  * }
@@ -72,7 +75,10 @@ export type ConfigFile = {
       rpcPass? : string;
     };
     cas?: {
+      /** IPFS HTTP gateway for CAS reads (read-only). */
       gateway?: string;
+      /** IPFS HTTP RPC endpoint for a writable CAS (reads + writes). */
+      rpcUrl?: string;
     };
     /** Signing identity references. Never embeds key material; the secret lives in the keystore. */
     identity?: {
@@ -153,6 +159,7 @@ export type ApiFactory = (network?: NetworkOption, overrides?: ConnectionOverrid
  * | `BTCR2_BTC_RPC_USER`  | `--btc-rpc-user`   |
  * | `BTCR2_BTC_RPC_PASS`  | `--btc-rpc-pass`   |
  * | `BTCR2_CAS_GATEWAY`   | `--cas-gateway`    |
+ * | `BTCR2_CAS_RPC_URL`   | `--cas-rpc-url`    |
  */
 export const ENV_VARS = {
   BTC_REST     : 'BTCR2_BTC_REST',
@@ -160,6 +167,7 @@ export const ENV_VARS = {
   BTC_RPC_USER : 'BTCR2_BTC_RPC_USER',
   BTC_RPC_PASS : 'BTCR2_BTC_RPC_PASS',
   CAS_GATEWAY  : 'BTCR2_CAS_GATEWAY',
+  CAS_RPC_URL  : 'BTCR2_CAS_RPC_URL',
 } as const;
 
 /**
@@ -174,6 +182,7 @@ export function readEnvOverrides(): ConnectionOverrides {
     btcRpcUser : env(ENV_VARS.BTC_RPC_USER),
     btcRpcPass : env(ENV_VARS.BTC_RPC_PASS),
     casGateway : env(ENV_VARS.CAS_GATEWAY),
+    casRpcUrl  : env(ENV_VARS.CAS_RPC_URL),
   };
 }
 
@@ -221,6 +230,7 @@ export function profileToOverrides(
     btcRpcUser : profile.btc?.rpcUser,
     btcRpcPass : profile.btc?.rpcPass,
     casGateway : profile.cas?.gateway,
+    casRpcUrl  : profile.cas?.rpcUrl,
   };
 }
 
@@ -261,7 +271,7 @@ export function resolveDefaultNetwork(overrides?: ConnectionOverrides): NetworkO
 function resolveConnectionConfig(
   network?  : NetworkOption,
   overrides?: ConnectionOverrides,
-): { btc?: BitcoinApiConfig; cas?: { gateway: string } } {
+): { btc?: BitcoinApiConfig; cas?: CasConfig } {
   if (!network) return {};
 
   // Layer 1: Config file profile (lowest precedence of the three override layers)
@@ -280,6 +290,7 @@ function resolveConnectionConfig(
     btcRpcUser : overrides?.btcRpcUser ?? env.btcRpcUser ?? fileOverrides.btcRpcUser,
     btcRpcPass : overrides?.btcRpcPass ?? env.btcRpcPass ?? fileOverrides.btcRpcPass,
     casGateway : overrides?.casGateway ?? env.casGateway ?? fileOverrides.casGateway,
+    casRpcUrl  : overrides?.casRpcUrl  ?? env.casRpcUrl  ?? fileOverrides.casRpcUrl,
   };
 
   const btc: BitcoinApiConfig = { network };
@@ -296,9 +307,15 @@ function resolveConnectionConfig(
     };
   }
 
-  const cas = merged.casGateway ? { gateway: merged.casGateway } : undefined;
+  // A configured RPC endpoint is writable and takes precedence over the
+  // read-only gateway (matching the api's CasConfig priority: rpcUrl > gateway).
+  // Both may be set; the api selects one executor from them.
+  const cas: CasConfig = {};
+  if (merged.casGateway) cas.gateway = merged.casGateway;
+  if (merged.casRpcUrl) cas.rpcUrl = merged.casRpcUrl;
+  const hasCas = merged.casGateway || merged.casRpcUrl;
 
-  return { btc, ...(cas && { cas }) };
+  return { btc, ...(hasCas && { cas }) };
 }
 
 /**

package/src/types.ts

@@ -1,5 +1,6 @@
+import type { DidUpdateResult } from '@did-btcr2/api';
 import type { PatchOperation } from '@did-btcr2/common';
-import type { Btcr2DidDocument, ResolutionOptions, SignedBTCR2Update } from '@did-btcr2/method';
+import type { Btcr2DidDocument, ResolutionOptions } from '@did-btcr2/method';
 import type { DidResolutionResult } from '@web5/dids';
 
 export type NetworkOption = 'bitcoin' | 'testnet3' | 'testnet4' | 'signet' | 'mutinynet' | 'regtest';
@@ -25,8 +26,8 @@ export interface UpdateCommandOptions {
 export type CommandResult =
   | { action: 'create'; data: string; keyId?: string; publicKey?: string }
   | { action: 'resolve'; data: DidResolutionResult }
-  | { action: 'update'; data: SignedBTCR2Update }
-  | { action: 'deactivate'; data: SignedBTCR2Update }
+  | { action: 'update'; data: DidUpdateResult }
+  | { action: 'deactivate'; data: DidUpdateResult }
   | { action: 'key-generate'; data: { keyId: string; publicKey: string; active: boolean } }
   | { action: 'key-list'; data: Array<{ keyId: string; fingerprint: string; name?: string; active: boolean }> }
   | { action: 'key-show'; data: { keyId: string; publicKey: string; tags?: Record<string, string> } }
@@ -55,6 +56,7 @@ export interface GlobalOptions {
   btcRpcUser?    : string;
   btcRpcPass?    : string;
   casGateway?    : string;
+  casRpcUrl?     : string;
   keystore?      : string;
   passphraseFile?: string;
   signingKey?    : string;