@seams/wallet-server 0.5.0

package/scripts/d1-local-migrate-signer.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { cpSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const phase1BridgeMigrationName = '0028_r103f_phase1_additive_schema_bridge.sql';
+const workerdIncompatibleChecks = Object.freeze([
+  Object.freeze({
+    source:
+      "schema.sql NOT LIKE '%PRIMARY KEY (namespace, org_id, project_id, env_id, link_session_id)%'",
+    replacement:
+      "instr(upper(schema.sql), 'PRIMARY KEY (NAMESPACE, ORG_ID, PROJECT_ID, ENV_ID, LINK_SESSION_ID)') = 0",
+  }),
+  Object.freeze({
+    source: "schema.sql NOT LIKE '%UNIQUE (namespace, org_id, project_id, env_id, authority_id)%'",
+    replacement:
+      "instr(upper(schema.sql), 'UNIQUE (NAMESPACE, ORG_ID, PROJECT_ID, ENV_ID, AUTHORITY_ID)') = 0",
+  }),
+  Object.freeze({
+    source: "schema.sql NOT LIKE '%CHECK (created_at_ms >= 0)%'",
+    replacement: "instr(upper(schema.sql), 'CHECK (CREATED_AT_MS >= 0)') = 0",
+  }),
+]);
+
+export function buildWorkerdCompatiblePhase1Bridge(source) {
+  let result = source;
+  for (const check of workerdIncompatibleChecks) {
+    const first = result.indexOf(check.source);
+    if (first === -1 || result.indexOf(check.source, first + check.source.length) !== -1) {
+      throw new Error(`Expected exactly one local D1 schema guard: ${check.source}`);
+    }
+    result = result.replace(check.source, check.replacement);
+  }
+  return result;
+}
+
+export function resolveSignerMigrationsDirectory(configSource, configPath) {
+  const blocks = configSource.split(/(?=\[\[d1_databases\]\])/u);
+  let signerBlock;
+  for (const block of blocks) {
+    if (/database_name\s*=\s*"seams-signer"/u.test(block)) signerBlock = block;
+  }
+  if (!signerBlock) throw new Error('Local D1 config has no seams-signer database binding');
+
+  const match = signerBlock.match(/migrations_dir\s*=\s*"([^"]+)"/u);
+  if (!match) throw new Error('Local seams-signer binding has no migrations_dir');
+  return path.resolve(path.dirname(configPath), match[1]);
+}
+
+export function buildSignerCompatibilityConfig(configSource, migrationsDirectory) {
+  const blocks = configSource.split(/(?=\[\[d1_databases\]\])/u);
+  let replaced = false;
+  const result = [];
+  for (const block of blocks) {
+    if (!/database_name\s*=\s*"seams-signer"/u.test(block)) {
+      result.push(block);
+      continue;
+    }
+    if (replaced) throw new Error('Local D1 config has multiple seams-signer bindings');
+    replaced = true;
+    result.push(
+      block.replace(
+        /migrations_dir\s*=\s*"[^"]+"/u,
+        `migrations_dir = ${JSON.stringify(migrationsDirectory)}`,
+      ),
+    );
+  }
+  if (!replaced) throw new Error('Local D1 config has no seams-signer database binding');
+  return result.join('');
+}
+
+function runLocalSignerMigrations(args, env = process.env) {
+  const options = parseArguments(args);
+  const configPath = path.resolve(
+    options.config || env.SEAMS_D1_LOCAL_WRANGLER_CONFIG || 'wrangler.d1-local.toml',
+  );
+  const persistTo =
+    options.persistTo || env.SEAMS_D1_LOCAL_PERSIST_TO || '.wrangler/state/seams-d1';
+  const workingDirectory = path.dirname(configPath);
+  const configSource = readFileSync(configPath, 'utf8');
+  const sourceMigrationsDirectory = resolveSignerMigrationsDirectory(configSource, configPath);
+  const temporaryRoot = mkdtempSync(path.join(tmpdir(), 'seams-d1-local-migrations-'));
+  const compatibleMigrationsDirectory = path.join(temporaryRoot, 'd1-signer');
+  const compatibilityConfigPath = path.join(
+    path.dirname(configPath),
+    `.wrangler.d1-local.compat-${process.pid}.toml`,
+  );
+
+  try {
+    cpSync(sourceMigrationsDirectory, compatibleMigrationsDirectory, { recursive: true });
+    const bridgePath = path.join(compatibleMigrationsDirectory, phase1BridgeMigrationName);
+    writeFileSync(
+      bridgePath,
+      buildWorkerdCompatiblePhase1Bridge(readFileSync(bridgePath, 'utf8')),
+      'utf8',
+    );
+    writeFileSync(
+      compatibilityConfigPath,
+      buildSignerCompatibilityConfig(configSource, compatibleMigrationsDirectory),
+      { mode: 0o600 },
+    );
+
+    const result = spawnSync(
+      'wrangler',
+      [
+        'd1',
+        'migrations',
+        'apply',
+        'seams-signer',
+        '--local',
+        '--persist-to',
+        persistTo,
+        '--config',
+        compatibilityConfigPath,
+      ],
+      { cwd: workingDirectory, env, stdio: 'inherit' },
+    );
+    if (result.error) throw result.error;
+    if (result.status !== 0) process.exitCode = result.status ?? 1;
+  } finally {
+    rmSync(compatibilityConfigPath, { force: true });
+    rmSync(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+function parseArguments(args) {
+  const options = { config: '', persistTo: '' };
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    const value = args[index + 1];
+    if (argument === '--config' || argument === '--persist-to') {
+      if (!value || value.startsWith('--')) throw new Error(`${argument} requires a value`);
+      if (argument === '--config') options.config = value;
+      if (argument === '--persist-to') options.persistTo = value;
+      index += 1;
+      continue;
+    }
+    throw new Error(`Unknown argument: ${argument}`);
+  }
+  return options;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runLocalSignerMigrations(process.argv.slice(2));
+}

package/src/README.md

@@ -0,0 +1,75 @@
+# Server Package
+
+`AuthService` and the Router API implement wallet registration, built-in owner
+verification, opaque Wallet Sessions, signing admission, and recovery. Wallet
+application authentication is intentionally outside this package.
+
+## Authorization model
+
+- Passkey and Email OTP verifiers create a server-internal
+  `VerifiedOwnerProof`.
+- Registration and unlock may consume that proof to mint an opaque, D1-backed
+  Wallet Session token.
+- Signing routes resolve the token into trusted curve-specific admission,
+  consume server-authoritative budget, and never decode claims supplied by the
+  client.
+- Fresh step-up and export proofs authorize one exact operation without
+  renewing a reusable Wallet Session.
+- Linked-device signing keeps its separate JWT, local-presence, permission,
+  quota, and revocation boundary.
+- Console authentication uses its independent `console_session_v1` boundary in
+  the console server package.
+
+## Primary wallet routes
+
+- `POST /wallets/register/setup`
+- `POST /wallets/register/respond`
+- `POST /wallets/register/activate`
+- `POST /wallets/register/near-provisioning`
+- `POST /wallet/unlock/challenge`
+- `POST /wallet/unlock/verify`
+- `POST /wallet/session/exchange/issue`
+- `POST /wallet/session/exchange/redeem`
+- `POST /router-ab/ecdsa-derivation/sign/prepare`
+- `POST /router-ab/ed25519/sign/prepare`
+- `GET /healthz`
+- `GET /readyz`
+- `GET /.well-known/webauthn`
+
+The hosted-wallet exchange routes deliver one opaque Wallet Session token
+through a short-lived, origin-bound, single-use capability. They do not create
+an application session, and the outer application never receives the token.
+
+## PRF Session Seal Module
+
+`signingSessionSeal` is optional and preserves sealed signing refresh material.
+It does not authorize wallet ownership.
+
+```ts
+import { createRouterApiRouter } from '@seams/wallet-server/router/express';
+import { createSigningSessionSealOptions } from '@seams/wallet-server';
+
+const signingSessionSeal = createSigningSessionSealOptions({
+  rootSecretB64u: process.env.SIGNING_SESSION_SEAL_ROOT_SECRET_B64U!,
+  currentKeyVersion: 'signing-session-seal-production-r2',
+  acceptedWarmKeyVersions: ['signing-session-seal-production-r2'],
+});
+
+app.use('/', createRouterApiRouter(service, {
+  threshold,
+  signingSessionSeal,
+}));
+```
+
+Store the random 32-byte root secret in a secrets manager. Retain accepted old
+key versions only until their sealed records expire.
+
+## Required runtime configuration
+
+```bash
+RELAYER_ACCOUNT_ID=relayer.testnet
+RELAYER_PRIVATE_KEY=ed25519:...
+ROR_RP_ID=wallet.example.localhost
+NEAR_RPC_URL=https://rpc.testnet.near.org
+NETWORK_ID=testnet
+```

package/wrangler.local-hosted-wallet-gateway.toml

@@ -0,0 +1,37 @@
+name = "seams-wallet-local-gateway"
+main = "src/local-hosted-wallet-gateway-worker.ts"
+compatibility_date = "2026-04-17"
+compatibility_flags = ["nodejs_compat"]
+
+[triggers]
+crons = ["* * * * *"]
+
+[[d1_databases]]
+binding = "SIGNER_DB"
+database_name = "seams-wallet-signer-local"
+database_id = "00000000-0000-0000-0000-000000000201"
+preview_database_id = "00000000-0000-0000-0000-000000000202"
+migrations_dir = "migrations/d1-signer"
+
+[[services]]
+binding = "MPC_ROUTER"
+service = "router-ab-mpc-router"
+
+[[services]]
+binding = "SIGNING_WORKER"
+service = "router-ab-signing-worker"
+
+[vars]
+ROUTER_AB_PREWARM_ENABLED = "true"
+SEAMS_TENANT_STORAGE_NAMESPACE = "seams-local"
+RELAYER_ACCOUNT_ID = "w3a-relayer.testnet"
+RELAYER_PUBLIC_KEY = "ed25519:local-relay-public-key"
+NEAR_RPC_URL = "https://test.rpc.fastnear.com"
+ACCOUNT_INITIAL_BALANCE = "30000000000000000000000"
+ENABLE_IMPLICIT_NEAR_ACCOUNT_TEST_FUNDING = "true"
+SESSION_COOKIE_NAME = "seams-jwt"
+RELAY_SESSION_ISSUER = "seams-wallet-local"
+RELAY_SESSION_AUDIENCE = "seams-wallet-local"
+LINKED_DEVICE_WEBAUTHN_RP_ID = "localhost"
+EMAIL_OTP_DELIVERY_MODE = "dev_d1_outbox"
+EMAIL_OTP_DEV_OUTBOX_ENABLED = "true"