@seams/wallet-server 0.5.0

package/cloudflare-router-ab/migrations/deriver-b/0007_tenant_root_restore_refresh_attempts.sql

@@ -0,0 +1,103 @@
+CREATE TABLE tenant_root_restore_refresh_attempts (
+    tenant_identity_digest_hex TEXT NOT NULL CHECK (
+        length(tenant_identity_digest_hex) = 64
+        AND tenant_identity_digest_hex NOT GLOB '*[^0-9a-f]*'
+    ),
+    custody_lineage_b64u TEXT NOT NULL CHECK (length(custody_lineage_b64u) = 22),
+    restore_session_id_hex TEXT NOT NULL CHECK (
+        length(restore_session_id_hex) = 32
+        AND restore_session_id_hex NOT GLOB '*[^0-9a-f]*'
+    ),
+    role TEXT NOT NULL CHECK (role = 'deriver_b'),
+    generation INTEGER NOT NULL CHECK (generation > 0),
+    import_key_id TEXT NOT NULL CHECK (length(import_key_id) BETWEEN 1 AND 128),
+    import_replay_key_digest_hex TEXT NOT NULL CHECK (
+        length(import_replay_key_digest_hex) = 64
+        AND import_replay_key_digest_hex NOT GLOB '*[^0-9a-f]*'
+    ),
+    import_command_digest_hex TEXT NOT NULL CHECK (
+        length(import_command_digest_hex) = 64
+        AND import_command_digest_hex NOT GLOB '*[^0-9a-f]*'
+    ),
+    import_operation_digest_hex TEXT NOT NULL CHECK (
+        length(import_operation_digest_hex) = 64
+        AND import_operation_digest_hex NOT GLOB '*[^0-9a-f]*'
+    ),
+    recovery_set_id_b64u TEXT NOT NULL CHECK (length(recovery_set_id_b64u) = 22),
+    manifest_digest_hex TEXT NOT NULL CHECK (
+        length(manifest_digest_hex) = 64
+        AND manifest_digest_hex NOT GLOB '*[^0-9a-f]*'
+    ),
+    stable_root_commitment_b64u TEXT NOT NULL CHECK (length(stable_root_commitment_b64u) = 43),
+    share_commitment_b64u TEXT NOT NULL CHECK (length(share_commitment_b64u) = 46),
+    destination_fingerprint_hex TEXT NOT NULL CHECK (
+        length(destination_fingerprint_hex) = 64
+        AND destination_fingerprint_hex NOT GLOB '*[^0-9a-f]*'
+    ),
+    import_public_key_b64u TEXT NOT NULL CHECK (length(import_public_key_b64u) = 43),
+    import_issued_at_ms INTEGER NOT NULL CHECK (import_issued_at_ms > 0),
+    import_expires_at_ms INTEGER NOT NULL CHECK (import_expires_at_ms > import_issued_at_ms),
+    refresh_command_digest_hex TEXT NOT NULL CHECK (
+        length(refresh_command_digest_hex) = 64
+        AND refresh_command_digest_hex NOT GLOB '*[^0-9a-f]*'
+    ),
+    refresh_issued_at_ms INTEGER NOT NULL CHECK (refresh_issued_at_ms > 0),
+    refresh_expires_at_ms INTEGER NOT NULL CHECK (refresh_expires_at_ms > refresh_issued_at_ms),
+    admitted_at_ms INTEGER NOT NULL CHECK (admitted_at_ms > 0),
+    encrypted_seed_json TEXT CHECK (
+        encrypted_seed_json IS NULL OR json_valid(encrypted_seed_json)
+    ),
+    encrypted_refreshed_share_json TEXT CHECK (
+        encrypted_refreshed_share_json IS NULL OR json_valid(encrypted_refreshed_share_json)
+    ),
+    installation_evidence_b64u TEXT CHECK (
+        installation_evidence_b64u IS NULL OR length(installation_evidence_b64u) BETWEEN 1 AND 8192
+    ),
+    installation_evidence_digest_hex TEXT CHECK (
+        installation_evidence_digest_hex IS NULL OR (
+            length(installation_evidence_digest_hex) = 64
+            AND installation_evidence_digest_hex NOT GLOB '*[^0-9a-f]*'
+        )
+    ),
+    lifecycle TEXT NOT NULL CHECK (lifecycle IN ('pending', 'refreshed', 'closed')),
+    refreshed_at_ms INTEGER CHECK (refreshed_at_ms IS NULL OR refreshed_at_ms >= admitted_at_ms),
+    created_at_ms INTEGER NOT NULL CHECK (created_at_ms > 0),
+    updated_at_ms INTEGER NOT NULL CHECK (updated_at_ms >= created_at_ms),
+    PRIMARY KEY (import_replay_key_digest_hex),
+    UNIQUE (
+        tenant_identity_digest_hex,
+        custody_lineage_b64u,
+        restore_session_id_hex,
+        role,
+        generation
+    ),
+    CHECK (
+        (lifecycle = 'pending'
+            AND encrypted_seed_json IS NOT NULL
+            AND encrypted_refreshed_share_json IS NULL
+            AND installation_evidence_b64u IS NULL
+            AND installation_evidence_digest_hex IS NULL
+            AND refreshed_at_ms IS NULL)
+        OR (lifecycle = 'refreshed'
+            AND encrypted_seed_json IS NOT NULL
+            AND encrypted_refreshed_share_json IS NOT NULL
+            AND installation_evidence_b64u IS NOT NULL
+            AND installation_evidence_digest_hex IS NOT NULL
+            AND refreshed_at_ms IS NOT NULL)
+        OR (lifecycle = 'closed'
+            AND encrypted_seed_json IS NULL
+            AND encrypted_refreshed_share_json IS NULL
+            AND installation_evidence_b64u IS NULL
+            AND installation_evidence_digest_hex IS NULL
+            AND refreshed_at_ms IS NULL)
+    )
+);
+
+CREATE INDEX tenant_root_restore_refresh_attempts_session
+    ON tenant_root_restore_refresh_attempts (
+        tenant_identity_digest_hex,
+        custody_lineage_b64u,
+        restore_session_id_hex,
+        role,
+        lifecycle
+    );

package/cloudflare-router-ab/migrations/deriver-b/0008_tenant_root_restore_promotion.sql

@@ -0,0 +1,40 @@
+ALTER TABLE tenant_root_restore_refresh_attempts ADD COLUMN promotion_lifecycle TEXT NOT NULL DEFAULT 'unstarted' CHECK (
+    promotion_lifecycle IN ('unstarted', 'reserved', 'completed')
+);
+ALTER TABLE tenant_root_restore_refresh_attempts ADD COLUMN promotion_reserved_at_ms INTEGER CHECK (
+    promotion_reserved_at_ms IS NULL OR promotion_reserved_at_ms > 0
+);
+ALTER TABLE tenant_root_restore_refresh_attempts ADD COLUMN encrypted_online_role_share_json TEXT CHECK (
+    encrypted_online_role_share_json IS NULL OR json_valid(encrypted_online_role_share_json)
+);
+ALTER TABLE tenant_root_restore_refresh_attempts ADD COLUMN provider_canary_receipt_b64u TEXT CHECK (
+    provider_canary_receipt_b64u IS NULL OR length(provider_canary_receipt_b64u) BETWEEN 1 AND 32768
+);
+ALTER TABLE tenant_root_restore_refresh_attempts ADD COLUMN promotion_completed_at_ms INTEGER CHECK (
+    promotion_completed_at_ms IS NULL OR promotion_completed_at_ms > 0
+);
+
+ALTER TABLE tenant_root_restore_import_sessions ADD COLUMN role TEXT NOT NULL DEFAULT 'deriver_b' CHECK (
+    role = 'deriver_b'
+);
+ALTER TABLE tenant_root_restore_import_sessions ADD COLUMN activation_operation TEXT CHECK (
+    activation_operation IS NULL OR activation_operation = 'initial_creation'
+);
+ALTER TABLE tenant_root_restore_import_sessions ADD COLUMN activation_receipt_b64u TEXT CHECK (
+    activation_receipt_b64u IS NULL OR length(activation_receipt_b64u) BETWEEN 1 AND 32768
+);
+ALTER TABLE tenant_root_restore_import_sessions ADD COLUMN activation_receipt_digest_hex TEXT CHECK (
+    activation_receipt_digest_hex IS NULL OR (
+        length(activation_receipt_digest_hex) = 64
+        AND activation_receipt_digest_hex NOT GLOB '*[^0-9a-f]*'
+    )
+);
+ALTER TABLE tenant_root_restore_import_sessions ADD COLUMN cleanup_receipt_b64u TEXT CHECK (
+    cleanup_receipt_b64u IS NULL OR length(cleanup_receipt_b64u) BETWEEN 1 AND 32768
+);
+ALTER TABLE tenant_root_restore_import_sessions ADD COLUMN cleanup_receipt_digest_hex TEXT CHECK (
+    cleanup_receipt_digest_hex IS NULL OR (
+        length(cleanup_receipt_digest_hex) = 64
+        AND cleanup_receipt_digest_hex NOT GLOB '*[^0-9a-f]*'
+    )
+);

package/cloudflare-router-ab/migrations/deriver-b/0009_tenant_root_restore_preactivation_cleanup.sql

@@ -0,0 +1,8 @@
+ALTER TABLE tenant_root_restore_import_sessions ADD COLUMN cleanup_grant_b64u TEXT CHECK (
+    cleanup_grant_b64u IS NULL OR (
+        length(cleanup_grant_b64u) BETWEEN 1 AND 32768
+        AND activation_operation IS NULL
+        AND activation_receipt_b64u IS NULL
+        AND activation_receipt_digest_hex IS NULL
+    )
+);

package/cloudflare-router-ab/migrations/deriver-b/0010_tenant_root_recovery_attempts.sql

@@ -0,0 +1,26 @@
+CREATE TABLE tenant_root_recovery_attempts (
+    recovery_set_id_b64u TEXT PRIMARY KEY CHECK (length(recovery_set_id_b64u) = 22),
+    tenant_identity_digest_hex TEXT NOT NULL CHECK (length(tenant_identity_digest_hex) = 64),
+    custody_lineage_b64u TEXT NOT NULL CHECK (length(custody_lineage_b64u) = 22),
+    role TEXT NOT NULL CHECK (role = 'deriver_b'),
+    command_b64u TEXT NOT NULL CHECK (length(command_b64u) BETWEEN 1 AND 21846),
+    admitted_at_ms INTEGER NOT NULL CHECK (admitted_at_ms > 0),
+    lifecycle TEXT NOT NULL CHECK (lifecycle IN ('provisioning', 'pending', 'packaged', 'destroying', 'destruction_scheduled', 'destroyed')),
+    encrypted_material_b64u TEXT,
+    encrypted_package_b64u TEXT,
+    package_digest_b64u TEXT,
+    destruction_receipt TEXT,
+    descriptor_b64u TEXT,
+    package_length INTEGER,
+    CHECK (
+        (lifecycle = 'packaged' AND descriptor_b64u IS NOT NULL AND length(descriptor_b64u) BETWEEN 1 AND 21846 AND package_length IS NOT NULL AND package_length BETWEEN 1 AND 16384)
+        OR (lifecycle <> 'packaged' AND descriptor_b64u IS NULL AND package_length IS NULL)
+    ),
+    CHECK (
+        (lifecycle IN ('provisioning', 'destroying') AND encrypted_material_b64u IS NULL AND encrypted_package_b64u IS NULL AND package_digest_b64u IS NULL AND destruction_receipt IS NULL)
+        OR (lifecycle = 'pending' AND encrypted_material_b64u IS NOT NULL AND encrypted_package_b64u IS NULL AND package_digest_b64u IS NULL AND destruction_receipt IS NULL)
+        OR (lifecycle = 'packaged' AND encrypted_material_b64u IS NULL AND encrypted_package_b64u IS NOT NULL AND package_digest_b64u IS NOT NULL AND length(package_digest_b64u) = 43 AND destruction_receipt IS NULL)
+        OR (lifecycle IN ('destruction_scheduled', 'destroyed') AND encrypted_material_b64u IS NULL AND encrypted_package_b64u IS NULL AND package_digest_b64u IS NULL AND destruction_receipt IS NOT NULL)
+    )
+);
+CREATE INDEX tenant_root_recovery_attempts_lineage ON tenant_root_recovery_attempts (tenant_identity_digest_hex, custody_lineage_b64u);

package/cloudflare-router-ab/migrations/deriver-b/0011_tenant_root_source_retirement.sql

@@ -0,0 +1,100 @@
+CREATE TABLE tenant_root_source_retirements (
+    tenant_identity_digest_hex TEXT NOT NULL CHECK (length(tenant_identity_digest_hex) = 64),
+    custody_lineage_b64u TEXT NOT NULL CHECK (length(custody_lineage_b64u) = 22),
+    role TEXT NOT NULL CHECK (role = 'deriver_b'),
+    active_receipt_digest_b64u TEXT NOT NULL CHECK (length(active_receipt_digest_b64u) = 43),
+    destination_receipt_digest_b64u TEXT NOT NULL CHECK (length(destination_receipt_digest_b64u) = 43),
+    retired_at_ms INTEGER NOT NULL CHECK (retired_at_ms > 0),
+    PRIMARY KEY (tenant_identity_digest_hex, custody_lineage_b64u)
+);
+
+CREATE TRIGGER tenant_root_role_shares_source_retired_insert
+BEFORE INSERT ON tenant_root_role_shares
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u)
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+
+CREATE TRIGGER tenant_root_role_shares_source_retired_update
+BEFORE UPDATE ON tenant_root_role_shares
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u)
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+
+CREATE TRIGGER tenant_root_command_replays_source_retired_insert
+BEFORE INSERT ON tenant_root_command_replays
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u)
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+
+CREATE TRIGGER tenant_root_command_replays_source_retired_update
+BEFORE UPDATE ON tenant_root_command_replays
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u)
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+
+CREATE TRIGGER tenant_root_restore_import_keys_source_retired_insert
+BEFORE INSERT ON tenant_root_restore_import_keys
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u)
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+
+CREATE TRIGGER tenant_root_restore_import_keys_source_retired_update
+BEFORE UPDATE ON tenant_root_restore_import_keys
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u)
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+
+CREATE TRIGGER tenant_root_restore_refresh_attempts_source_retired_insert
+BEFORE INSERT ON tenant_root_restore_refresh_attempts
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u)
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+
+CREATE TRIGGER tenant_root_restore_refresh_attempts_source_retired_update
+BEFORE UPDATE ON tenant_root_restore_refresh_attempts
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u)
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+
+CREATE TRIGGER tenant_root_recovery_attempts_source_retired_insert
+BEFORE INSERT ON tenant_root_recovery_attempts
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u) AND NEW.lifecycle IN ('provisioning','pending','packaged')
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+
+CREATE TRIGGER tenant_root_recovery_attempts_source_retired_update
+BEFORE UPDATE ON tenant_root_recovery_attempts
+WHEN EXISTS (SELECT 1 FROM tenant_root_source_retirements
+    WHERE tenant_identity_digest_hex = NEW.tenant_identity_digest_hex
+      AND custody_lineage_b64u = NEW.custody_lineage_b64u) AND NEW.lifecycle IN ('provisioning','pending','packaged')
+BEGIN
+    SELECT RAISE(ABORT, 'tenant root source lineage is retired');
+END;
+

package/cloudflare-router-ab/migrations/signing-worker/0001_private_storage.sql

@@ -0,0 +1,67 @@
+CREATE TABLE signing_worker_activations (
+    material_key TEXT PRIMARY KEY,
+    active_key TEXT NOT NULL UNIQUE,
+    record_json TEXT NOT NULL,
+    active_state_json TEXT NOT NULL,
+    created_at_ms INTEGER NOT NULL
+);
+
+CREATE TABLE signing_worker_activation_revocation_fences (
+    active_key TEXT PRIMARY KEY
+);
+
+CREATE TABLE signing_worker_round1 (
+    record_key TEXT PRIMARY KEY,
+    record_json TEXT NOT NULL,
+    expires_at_ms INTEGER NOT NULL
+);
+
+CREATE INDEX signing_worker_round1_expiry
+    ON signing_worker_round1 (expires_at_ms);
+
+CREATE TABLE signing_worker_ecdsa_pool (
+    record_key TEXT PRIMARY KEY,
+    record_json TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    cleanup_deadline_ms INTEGER
+);
+
+CREATE INDEX signing_worker_ecdsa_pool_expiry
+    ON signing_worker_ecdsa_pool (cleanup_deadline_ms);
+
+CREATE TABLE signing_worker_terminal_responses (
+    operation_key TEXT PRIMARY KEY,
+    request_digest_hex TEXT NOT NULL,
+    response_json TEXT NOT NULL,
+    committed_at_ms INTEGER NOT NULL
+);
+
+CREATE TABLE signing_worker_effect_claims (
+    operation_key TEXT PRIMARY KEY,
+    authorization_key TEXT NOT NULL UNIQUE,
+    request_digest_hex TEXT NOT NULL,
+    authorization_json TEXT NOT NULL,
+    claimed_at_ms INTEGER NOT NULL
+);
+
+CREATE TABLE signing_worker_secret_states (
+    purpose TEXT NOT NULL,
+    record_key TEXT NOT NULL,
+    ciphertext_json TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    updated_at_ms INTEGER NOT NULL,
+    PRIMARY KEY (purpose, record_key)
+);
+
+CREATE TABLE signing_worker_lane_material (
+    operation_key TEXT PRIMARY KEY,
+    activation_id TEXT NOT NULL UNIQUE,
+    wallet_key_id TEXT NOT NULL,
+    target_lane_id TEXT NOT NULL,
+    target_lane_share_epoch TEXT NOT NULL,
+    identity_digest_b64u TEXT NOT NULL,
+    record_json TEXT NOT NULL,
+    version INTEGER NOT NULL,
+    updated_at_ms INTEGER NOT NULL,
+    UNIQUE (wallet_key_id, target_lane_id, target_lane_share_epoch)
+);

package/cloudflare-router-ab/migrations/signing-worker/0002_activation_revocation_fences.sql

@@ -0,0 +1,3 @@
+CREATE TABLE IF NOT EXISTS signing_worker_activation_revocation_fences (
+    active_key TEXT PRIMARY KEY
+);

package/cloudflare-router-ab/scripts/bootstrap-local-tenant-root.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+
+import {
+  buildTenantRootIdentityFromAuthenticatedDeploymentV1,
+  randomTenantRootCreationGrantBytesV1,
+  signTenantRootCreationGrantV1,
+} from '@seams/wallet-server/cloud-host';
+
+import { resolveLocalTenantRootKeyMaterial } from './prepare-local-runtime-config.mjs';
+
+const INTERNAL_SERVICE_AUTH_HEADER = 'x-router-ab-internal-service-auth';
+const TENANT_ROOT_CREATION_PATH = '/router-ab/internal/tenant-root/creation/v1/create';
+
+await main().catch(handleFatalError);
+
+async function main() {
+  const options = parseArguments(process.argv.slice(2));
+  const identityResult = buildTenantRootIdentityFromAuthenticatedDeploymentV1(options.identity);
+  if (!identityResult.ok) {
+    throw new Error('Local tenant-root bootstrap identity is invalid');
+  }
+  const localKeys = resolveLocalTenantRootKeyMaterial({
+    repoRoot: options.repoRoot,
+    localEnvRoot: options.localRoot,
+  });
+  const routerEnv = readEnvMap(path.join(options.localRoot, '.env.router-ab.router.local'));
+  const issuedAtMs = Math.max(1, Date.now() - 1);
+  const grant = await signTenantRootCreationGrantV1({
+    identity: identityResult.value,
+    custodyLineage: randomTenantRootCreationGrantBytesV1(16),
+    grantNonce: randomTenantRootCreationGrantBytesV1(32),
+    issuedAtMs,
+    expiresAtMs: issuedAtMs + 300_000,
+    grantKeyId: localKeys.grantAuthority.keyId,
+    signingSeedB64u: localKeys.grantAuthority.signingSeedB64u,
+  });
+  const response = await fetch(new URL(TENANT_ROOT_CREATION_PATH, options.routerUrl), {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      [INTERNAL_SERVICE_AUTH_HEADER]: requiredEnv(
+        routerEnv,
+        'ROUTER_AB_INTERNAL_SERVICE_AUTH_SECRET',
+      ),
+    },
+    body: JSON.stringify({ creation_grant_b64u: grant.grantB64u }),
+  });
+  const body = await response.text();
+  if (!response.ok) {
+    throw new Error(`Tenant-root bootstrap failed (HTTP ${response.status}): ${body}`);
+  }
+  const result = parseCreationResult(body);
+  process.stdout.write(
+    `${JSON.stringify({ kind: 'wallet_local_tenant_root_ready_v1', ...result })}\n`,
+  );
+}
+
+function parseArguments(args) {
+  const values = new Map();
+  for (let index = 0; index < args.length; index += 2) {
+    const name = args[index];
+    const value = args[index + 1];
+    if (!name?.startsWith('--') || !value) throw new Error(usage());
+    values.set(name, value);
+  }
+  const repoRoot = process.cwd();
+  return {
+    repoRoot,
+    localRoot: path.resolve(requiredOption(values, '--root')),
+    routerUrl: requiredUrl(values.get('--router-url') ?? 'http://127.0.0.1:4102'),
+    identity: {
+      orgId: requiredOption(values, '--org-id'),
+      projectId: requiredOption(values, '--project-id'),
+      envId: requiredOption(values, '--env-id'),
+      signingRootId: requiredOption(values, '--signing-root-id'),
+      signingRootVersion: requiredOption(values, '--signing-root-version'),
+    },
+  };
+}
+
+function usage() {
+  return [
+    'Usage: bootstrap-local-tenant-root.mjs',
+    '  --root <local-runtime-directory>',
+    '  --org-id <organization-id>',
+    '  --project-id <project-id>',
+    '  --env-id <environment-id>',
+    '  --signing-root-id <signing-root-id>',
+    '  --signing-root-version <version>',
+    '  [--router-url <mpc-router-url>]',
+  ].join(' ');
+}
+
+function requiredOption(values, name) {
+  const value = values.get(name);
+  if (!value) throw new Error(usage());
+  return value;
+}
+
+function requiredUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('router URL must use HTTP or HTTPS');
+  }
+  return url.href;
+}
+
+function readEnvMap(filePath) {
+  const values = new Map();
+  for (const rawLine of readFileSync(filePath, 'utf8').split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const separator = line.indexOf('=');
+    if (separator <= 0) continue;
+    values.set(line.slice(0, separator).trim(), unquote(line.slice(separator + 1).trim()));
+  }
+  return values;
+}
+
+function unquote(value) {
+  if (
+    value.length >= 2 &&
+    ((value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'")))
+  ) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+
+function requiredEnv(values, name) {
+  const value = values.get(name);
+  if (!value) throw new Error(`${name} is missing from the local Router environment`);
+  return value;
+}
+
+function parseCreationResult(source) {
+  let value;
+  try {
+    value = JSON.parse(source);
+  } catch {
+    throw new Error('Tenant-root bootstrap returned invalid JSON');
+  }
+  if (!isRecord(value) || !isRecord(value.status) || value.status.kind !== 'ready') {
+    throw new Error('Tenant-root bootstrap did not reach ready state');
+  }
+  return {
+    identityDigestB64u: requiredText(value.identity_digest_b64u, 'identity_digest_b64u'),
+    custodyLineageB64u: requiredText(value.custody_lineage_b64u, 'custody_lineage_b64u'),
+    revision: requiredPositiveInteger(value.revision, 'revision'),
+    rootCommitmentB64u: requiredText(
+      value.status.root_commitment_b64u,
+      'status.root_commitment_b64u',
+    ),
+    replayed: value.replayed === true,
+  };
+}
+
+function requiredText(value, label) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text) throw new Error(`${label} is required`);
+  return text;
+}
+
+function requiredPositiveInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return value;
+}
+
+function isRecord(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function handleFatalError(error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/cloudflare-router-ab/scripts/initialize-local-wallet.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { chmodSync, existsSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const binary = fileURLToPath(new URL(
+  '../build/local-tools/' + process.platform + '-' + process.arch + '/router_ab_local_init',
+  import.meta.url,
+));
+if (!existsSync(binary)) {
+  throw new Error('Wallet local initializer is unavailable for ' + process.platform + '-' + process.arch);
+}
+// Package managers can normalize executable bits on bundled native assets.
+if ((statSync(binary).mode & 0o111) === 0) chmodSync(binary, 0o755);
+const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
+if (result.error) throw result.error;
+process.exitCode = result.status ?? 1;

package/cloudflare-router-ab/scripts/local-key-material.mjs

@@ -0,0 +1,29 @@
+import { createPrivateKey, createPublicKey } from 'node:crypto';
+
+const ED25519_PKCS8_SEED_PREFIX = Buffer.from('302e020100300506032b657004220420', 'hex');
+
+export function localPeerSigningKeyBase64Url(value) {
+  return Buffer.from(localPeerSigningSeedHex(value), 'hex').toString('base64url');
+}
+
+export function localPeerVerifyingKeyHex(value) {
+  const seed = Buffer.from(localPeerSigningSeedHex(value), 'hex');
+  const privateKey = createPrivateKey({
+    key: Buffer.concat([ED25519_PKCS8_SEED_PREFIX, seed]),
+    format: 'der',
+    type: 'pkcs8',
+  });
+  const publicKey = createPublicKey(privateKey).export({ format: 'der', type: 'spki' });
+  return Buffer.from(publicKey).subarray(-32).toString('hex');
+}
+
+function localPeerSigningSeedHex(value) {
+  if (!/^[A-Za-z0-9_-]{43}$/.test(value)) {
+    throw new Error('Router A/B local peer signing key must be 32-byte base64url');
+  }
+  const seed = Buffer.from(value, 'base64url');
+  if (seed.length !== 32) {
+    throw new Error('Router A/B local peer signing key must decode to 32 bytes');
+  }
+  return seed.toString('hex');
+}