@mysten-incubation/devstack 0.0.1 → 0.1.1

package/dist/plugins/wallet/origin-policy.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"origin-policy.mjs","names":[],"sources":["../../../src/plugins/wallet/origin-policy.ts"],"sourcesContent":["// Wallet plugin — CORS / origin allowlist policy.\n//\n// Distilled-doc problem (15-wallet.md \"Cross-stack pairing risk\"): the\n// legacy wallet auto-allowlisted `http://localhost:<vite-port>` per\n// stack. Two sibling stacks running vite on the same `localhost:5175`\n// (or `5176`, etc.) could pair with EITHER wallet — CORS lets the\n// request through, and the bearer token (once leaked once via any\n// channel) is enough to sign.\n//\n// Architecture decision (per task):\n//\n//   - Stack-scoped allowlist. The vite-port-derived origin is added to\n//     this stack's allowlist ONLY when the substrate's port broker\n//     records THIS stack as the owner of that vite port.\n//   - The stack-scoped host (e.g. `http://dev.<stack>.<app>.localhost:<port>`)\n//     is the canonical browser entry — always allowlisted.\n//   - The raw `http://localhost:<port>` form is OFF by default; opt-in\n//     via `WalletOptions.allowLocalhostVite: true` for callers who\n//     want the legacy behavior (e.g. headless test runners that pin\n//     `localhost`). Documented as a security tradeoff in the factory's\n//     JSDoc.\n//\n// Why \"origin + bearer together\" (task requirement #3): bearer alone\n// leaves a non-browser-tooling bypass — curl / fetch from a service\n// worker can forge `Authorization` from a leaked token. Browsers\n// always send `Origin`; non-browsers omit it. Demanding BOTH closes\n// the bypass.\n\nimport { Effect } from 'effect';\n\nimport { SpanAttr } from '../../substrate/runtime/observability/spans.ts';\nimport type { WalletBootError } from './errors.ts';\n\n// ----------------------------------------------------------------------\n// Policy shape\n// ----------------------------------------------------------------------\n\n/** Result of resolving the origin allowlist at boot. Captured into\n *  the HTTP handler closure so per-request checks are pure-string\n *  comparison. */\nexport interface OriginPolicy {\n\treadonly allowed: ReadonlySet<string>;\n\t/** True if the policy permitted the `http://localhost:<vite-port>`\n\t *  form. Carried for renderer / log hygiene — surfaces in the\n\t *  manifest as a flag so the TUI can warn. */\n\treadonly localhostViteEnabled: boolean;\n\t/** Bare host (e.g. `dev.<stack>.<app>.localhost`) the stack-scoped\n\t *  origin resolves under. Captured for log lines. */\n\treadonly stackScopedHost: string;\n}\n\n/** Per-stack inputs the policy resolver needs. Supplied by the\n *  substrate at acquire time (port broker + identity); this module\n *  doesn't reach into the broker itself. */\nexport interface OriginPolicyInputs {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly vitePortForThisStack: number | null;\n\treadonly routedAppOrigin: string | null;\n\treadonly extraOrigins: ReadonlyArray<string>;\n\treadonly allowLocalhostVite: boolean;\n}\n\n// ----------------------------------------------------------------------\n// Resolution\n// ----------------------------------------------------------------------\n\n/**\n * Resolve the per-stack origin allowlist.\n *\n *  - Always allowlisted: the stack-scoped router host\n *    `http://dev.<stack>.<app>.localhost:<vite-port>`, IF the broker recorded\n *    a vite port for this stack.\n *  - Conditionally allowlisted: the bare `http://localhost:<vite-port>`\n *    form. Off by default; on iff `allowLocalhostVite` is true.\n *  - Always allowlisted: any explicit caller-supplied origins from\n *    `extraOrigins`.\n *\n * Empty-allowlist policy (vite absent AND no `extraOrigins`): allowed.\n * The wallet boots normally; with an empty allowlist the per-request\n * gate refuses every request (every Origin lands in `forbidden`). This\n * is the correct behavior for a stack composed without any client UI\n * (e.g. node-only smoke / e2e configs) — the wallet's keypair + token\n * are still useful for the host process, but the HTTP surface is\n * effectively closed. A `Effect.logWarning` surfaces the configuration\n * for operator visibility.\n *\n * Returns `Effect<OriginPolicy, WalletBootError>` (the error channel\n * is preserved for future fail-fast modes the resolver may grow).\n */\nexport const resolveOriginPolicy = (\n\tinputs: OriginPolicyInputs,\n): Effect.Effect<OriginPolicy, WalletBootError> =>\n\tEffect.gen(function* () {\n\t\tconst allowed = new Set<string>();\n\t\tconst stackScopedHost =\n\t\t\tinputs.stack === 'main'\n\t\t\t\t? `dev.${inputs.app}.localhost`\n\t\t\t\t: `dev.${inputs.stack}.${inputs.app}.localhost`;\n\n\t\tif (inputs.vitePortForThisStack !== null) {\n\t\t\tallowed.add(`http://${stackScopedHost}:${inputs.vitePortForThisStack}`);\n\t\t\tif (inputs.allowLocalhostVite) {\n\t\t\t\tallowed.add(`http://localhost:${inputs.vitePortForThisStack}`);\n\t\t\t}\n\t\t}\n\n\t\tif (inputs.routedAppOrigin !== null) {\n\t\t\tallowed.add(inputs.routedAppOrigin);\n\t\t}\n\n\t\tfor (const o of inputs.extraOrigins) {\n\t\t\tallowed.add(o);\n\t\t}\n\n\t\tif (allowed.size === 0) {\n\t\t\tyield* Effect.logWarning('wallet origin allowlist is empty').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.app]: inputs.app,\n\t\t\t\t\t[SpanAttr.stack]: inputs.stack,\n\t\t\t\t\t[SpanAttr.walletLocalhostViteEnabled]: inputs.allowLocalhostVite,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\n\t\treturn {\n\t\t\tallowed,\n\t\t\tlocalhostViteEnabled: inputs.allowLocalhostVite,\n\t\t\tstackScopedHost,\n\t\t} satisfies OriginPolicy;\n\t});\n\n// ----------------------------------------------------------------------\n// Per-request check\n// ----------------------------------------------------------------------\n\n/** Per-request origin gate. Returns `'missing'` for absent Origin,\n *  `'forbidden'` for Origin not in the allowlist, `'ok'` for accepted.\n *\n *  Distilled-doc invariant (C12): missing Origin is its OWN refusal\n *  shape (closes the curl / non-browser bypass — bearer alone is not\n *  enough). */\nexport type OriginCheckResult = 'missing' | 'forbidden' | 'ok';\n\nexport const checkOrigin = (\n\tpolicy: OriginPolicy,\n\theaderValue: string | undefined,\n): OriginCheckResult => {\n\tif (headerValue === undefined || headerValue.length === 0) return 'missing';\n\treturn policy.allowed.has(headerValue) ? 'ok' : 'forbidden';\n};\n\n/** Compose CORS headers for a successful request. Single-allowed-origin\n *  echo (browsers don't honor wildcard with credentials, and we want\n *  to keep `Access-Control-Allow-Credentials` open for fetch with\n *  `credentials: 'include'` if a future codegen seam needs it). */\nexport const corsHeadersFor = (origin: string): Readonly<Record<string, string>> => ({\n\t'access-control-allow-origin': origin,\n\t'access-control-allow-methods': 'GET, POST, OPTIONS',\n\t'access-control-allow-headers': 'authorization, content-type',\n\t'access-control-allow-credentials': 'true',\n\tvary: 'origin',\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA0FA,MAAa,uBACZ,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,0BAAU,IAAI,KAAa;CACjC,MAAM,kBACL,OAAO,UAAU,SACd,OAAO,OAAO,IAAI,cAClB,OAAO,OAAO,MAAM,GAAG,OAAO,IAAI;AAEtC,KAAI,OAAO,yBAAyB,MAAM;AACzC,UAAQ,IAAI,UAAU,gBAAgB,GAAG,OAAO,uBAAuB;AACvE,MAAI,OAAO,mBACV,SAAQ,IAAI,oBAAoB,OAAO,uBAAuB;;AAIhE,KAAI,OAAO,oBAAoB,KAC9B,SAAQ,IAAI,OAAO,gBAAgB;AAGpC,MAAK,MAAM,KAAK,OAAO,aACtB,SAAQ,IAAI,EAAE;AAGf,KAAI,QAAQ,SAAS,EACpB,QAAO,OAAO,WAAW,mCAAmC,CAAC,KAC5D,OAAO,aAAa;GAClB,SAAS,MAAM,OAAO;GACtB,SAAS,QAAQ,OAAO;GACxB,SAAS,6BAA6B,OAAO;EAC9C,CAAC,CACF;AAGF,QAAO;EACN;EACA,sBAAsB,OAAO;EAC7B;EACA;EACA;AAcH,MAAa,eACZ,QACA,gBACuB;AACvB,KAAI,gBAAgB,KAAA,KAAa,YAAY,WAAW,EAAG,QAAO;AAClE,QAAO,OAAO,QAAQ,IAAI,YAAY,GAAG,OAAO;;;;;;AAOjD,MAAa,kBAAkB,YAAsD;CACpF,+BAA+B;CAC/B,gCAAgC;CAChC,gCAAgC;CAChC,oCAAoC;CACpC,MAAM;CACN"}
+{"version":3,"file":"origin-policy.mjs","names":[],"sources":["../../../src/plugins/wallet/origin-policy.ts"],"sourcesContent":["// Wallet plugin — CORS / origin allowlist policy.\n//\n// The allowlist is built from two real, substrate-wired sources: the\n// router-fronted dev-server origin for this stack (`routedAppOrigin`)\n// and any caller-supplied `extraOrigins`. Both are stack-scoped or\n// explicit, so neither opens the cross-stack pairing risk described in\n// 15-wallet.md.\n//\n// History (removed): an earlier design auto-allowlisted a vite-port-\n// derived origin (`http://dev.<stack>.<app>.localhost:<vite-port>`,\n// plus an opt-in `http://localhost:<vite-port>`). That branch was dead\n// AT THE TIME: there was no vite plugin and the port broker only\n// allocated ports for in-stack plugins with no reader/lookup API, so\n// `vitePortForThisStack` was always `null` at the only production call\n// site and the branch never fired. Per STYLE_GUIDE §5 (\"code either\n// works or doesn't exist\") the whole vite-origin path — and the\n// `allowLocalhostVite` opt-in it gated — was removed rather than left as\n// an unreachable allowlist seam.\n//\n// Note (no longer dead, but deliberately NOT re-added here): with the\n// `hostService(...)` plugin devstack now DOES own the dev server's bind\n// port (the broker allocates it; Vite binds it via `--port {port}`). So\n// the raw-loopback origin (`http://127.0.0.1:<port>` /\n// `http://localhost:<port>`) the dev sees in Vite's own console banner is\n// a real, knowable origin. The canonical fix lives on the host-service\n// side instead: it now publishes the ROUTED origin as its\n// `HostServiceValue.url`, so `devstack up` output (and any consumer\n// holding the resolved host-service value) point devs at the URL whose\n// Origin THIS allowlist already accepts (the routed `routedAppOrigin`).\n// Re-adding a raw-loopback branch\n// here is intentionally deferred — it would have to thread the\n// host-service's dynamic bind port into the wallet, which runs in the\n// OPPOSITE direction of the current dependency edge (host-service\n// `dependsOn` wallet), so the wallet has no view of that port at its own\n// boot. Devs who must load the raw Vite URL can pass it via\n// `allowedOrigins` (→ `extraOrigins`) until that plumbing is justified.\n//\n// Why \"origin + bearer together\": bearer alone leaves a non-browser-\n// tooling bypass — curl / fetch from a service worker can forge\n// `Authorization` from a leaked token. Browsers always send `Origin`;\n// non-browsers omit it. Demanding BOTH closes the bypass.\n\nimport { Effect } from 'effect';\n\nimport { SpanAttr } from '../../substrate/runtime/observability/spans.ts';\n\n// ----------------------------------------------------------------------\n// Policy shape\n// ----------------------------------------------------------------------\n\n/** Result of resolving the origin allowlist at boot. Captured into\n *  the HTTP handler closure so per-request checks are pure-string\n *  comparison. */\nexport interface OriginPolicy {\n\treadonly allowed: ReadonlySet<string>;\n}\n\n/** Per-stack inputs the policy resolver needs. Supplied by the\n *  substrate at acquire time (identity + routed-url derivation); this\n *  module doesn't reach into the broker itself. */\nexport interface OriginPolicyInputs {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly routedAppOrigin: string | null;\n\treadonly extraOrigins: ReadonlyArray<string>;\n}\n\n// ----------------------------------------------------------------------\n// Resolution\n// ----------------------------------------------------------------------\n\n/**\n * Resolve the per-stack origin allowlist.\n *\n *  - Always allowlisted: the router-fronted dev-server origin for this\n *    stack (`routedAppOrigin`), when the router derivation produced one.\n *  - Always allowlisted: any explicit caller-supplied origins from\n *    `extraOrigins`.\n *\n * Empty-allowlist policy (no `routedAppOrigin` AND no `extraOrigins`):\n * allowed. The wallet boots normally; with an empty allowlist the\n * per-request gate refuses every request (every Origin lands in\n * `forbidden`). This is the correct behavior for a stack composed\n * without any client UI (e.g. node-only smoke / e2e configs) — the\n * wallet's keypair + token are still useful for the host process, but\n * the HTTP surface is effectively closed. A `Effect.logWarning`\n * surfaces the configuration for operator visibility.\n */\nexport const resolveOriginPolicy = (inputs: OriginPolicyInputs): Effect.Effect<OriginPolicy> =>\n\tEffect.gen(function* () {\n\t\tconst allowed = new Set<string>();\n\n\t\tif (inputs.routedAppOrigin !== null) {\n\t\t\tallowed.add(inputs.routedAppOrigin);\n\t\t}\n\n\t\tfor (const o of inputs.extraOrigins) {\n\t\t\tallowed.add(o);\n\t\t}\n\n\t\tif (allowed.size === 0) {\n\t\t\tyield* Effect.logWarning('wallet origin allowlist is empty').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.app]: inputs.app,\n\t\t\t\t\t[SpanAttr.stack]: inputs.stack,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\n\t\treturn { allowed } satisfies OriginPolicy;\n\t});\n\n// ----------------------------------------------------------------------\n// Per-request check\n// ----------------------------------------------------------------------\n\n/** Per-request origin gate. Returns `'missing'` for absent Origin,\n *  `'forbidden'` for Origin not in the allowlist, `'ok'` for accepted.\n *\n *  Distilled-doc invariant (C12): missing Origin is its OWN refusal\n *  shape (closes the curl / non-browser bypass — bearer alone is not\n *  enough). */\nexport type OriginCheckResult = 'missing' | 'forbidden' | 'ok';\n\nexport const checkOrigin = (\n\tpolicy: OriginPolicy,\n\theaderValue: string | undefined,\n): OriginCheckResult => {\n\tif (headerValue === undefined || headerValue.length === 0) return 'missing';\n\treturn policy.allowed.has(headerValue) ? 'ok' : 'forbidden';\n};\n\n/** Compose CORS headers for a successful request. Single-allowed-origin\n *  echo (browsers don't honor wildcard with credentials, and we want\n *  to keep `Access-Control-Allow-Credentials` open for fetch with\n *  `credentials: 'include'` if a future codegen seam needs it). */\nexport const corsHeadersFor = (origin: string): Readonly<Record<string, string>> => ({\n\t'access-control-allow-origin': origin,\n\t'access-control-allow-methods': 'GET, POST, OPTIONS',\n\t'access-control-allow-headers': 'authorization, content-type',\n\t'access-control-allow-credentials': 'true',\n\tvary: 'origin',\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwFA,MAAa,uBAAuB,WACnC,OAAO,IAAI,aAAa;CACvB,MAAM,0BAAU,IAAI,KAAa;AAEjC,KAAI,OAAO,oBAAoB,KAC9B,SAAQ,IAAI,OAAO,gBAAgB;AAGpC,MAAK,MAAM,KAAK,OAAO,aACtB,SAAQ,IAAI,EAAE;AAGf,KAAI,QAAQ,SAAS,EACpB,QAAO,OAAO,WAAW,mCAAmC,CAAC,KAC5D,OAAO,aAAa;GAClB,SAAS,MAAM,OAAO;GACtB,SAAS,QAAQ,OAAO;EACzB,CAAC,CACF;AAGF,QAAO,EAAE,SAAS;EACjB;AAcH,MAAa,eACZ,QACA,gBACuB;AACvB,KAAI,gBAAgB,KAAA,KAAa,YAAY,WAAW,EAAG,QAAO;AAClE,QAAO,OAAO,QAAQ,IAAI,YAAY,GAAG,OAAO;;;;;;AAOjD,MAAa,kBAAkB,YAAsD;CACpF,+BAA+B;CAC/B,gCAAgC;CAChC,gCAAgC;CAChC,oCAAoC;CACpC,MAAM;CACN"}

package/dist/plugins/wallet/pairing.mjs

@@ -1,8 +1,10 @@
-import { atomicWriteFile } from "../../substrate/runtime/atomic-write.mjs";
-import { SpanAttr } from "../../substrate/runtime/observability/spans.mjs";
 import { redactText } from "../../substrate/runtime/observability/redaction.mjs";
+import { atomicWriteFile } from "../../substrate/runtime/atomic-write.mjs";
+import "../../substrate/runtime/observability/index.mjs";
+import { WALLET_BEARER_PREFIX, WALLET_TOKEN_FRAGMENT_KEY } from "../../contracts/wallet-protocol.mjs";
 import { walletBootError } from "./errors.mjs";
-import { WALLET_BEARER_PREFIX, WALLET_TOKEN_FRAGMENT_KEY } from "./protocol.mjs";
+import { WalletSpans } from "./spans.mjs";
+import "./protocol.mjs";
 import { Effect } from "effect";
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { join } from "node:path";
@@ -49,7 +51,7 @@ const acquirePairingToken = (path) => Effect.gen(function* () {
 	if (existing !== null) {
 		const trimmed = existing.trim();
 		if (TOKEN_RE.test(trimmed)) return asToken(trimmed);
-		yield* Effect.logWarning("wallet token file is malformed; re-minting").pipe(Effect.annotateLogs({ [SpanAttr.walletTokenFile]: path }));
+		yield* Effect.logWarning("wallet token file is malformed; re-minting").pipe(Effect.annotateLogs({ [WalletSpans.tokenFile]: path }));
 	}
 	const token = yield* mintToken();
 	yield* atomicWriteFile(path, new TextEncoder().encode(token), { mode: 384 }).pipe(Effect.mapError((cause) => walletBootError({

package/dist/plugins/wallet/pairing.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"pairing.mjs","names":["joinPath"],"sources":["../../../src/plugins/wallet/pairing.ts"],"sourcesContent":["// Wallet plugin — pairing-token discipline.\n//\n// What this module owns (15-wallet.md \"Token comparison MUST be\n// constant-time\", \"Token MUST live in URL fragment (not query)\",\n// \"Token MUST NOT appear in log lines\", \"Token file MUST be mode\n// 0o600\"):\n//\n//   1. Token generation: 16 random bytes → 32 hex chars.\n//   2. Token persistence: file at `<stateRoot>/wallet/token`, mode\n//      `0o600`, atomic write.\n//   3. Token rehydration: read-existing-or-mint so warm starts +\n//      snapshot restore preserve the dev-wallet pairing.\n//   4. URL-fragment ↔ Authorization-header bridge: helpers that\n//      compose the pair URL (token in fragment) and parse the\n//      bearer-prefixed header back to the raw token.\n//   5. Constant-time bearer compare: timing-safe equality so a\n//      remote attacker can't recover the token byte-by-byte via\n//      response-time measurement.\n//\n// What this module does NOT own:\n//\n//   - The HTTP server (see `server.ts`).\n//   - The CORS / Origin allowlist (see `origin-policy.ts`).\n//   - The codegen file (see `codegen.ts`).\n\nimport { Effect, FileSystem } from 'effect';\nimport { randomBytes, timingSafeEqual } from 'node:crypto';\nimport { readFile } from 'node:fs/promises';\nimport { join as joinPath } from 'node:path';\n\nimport { atomicWriteFile } from '../../substrate/runtime/atomic-write.ts';\nimport { redactText, type RedactionRule } from '../../substrate/runtime/observability/index.ts';\nimport { SpanAttr } from '../../substrate/runtime/observability/spans.ts';\nimport { walletBootError, type WalletBootError } from './errors.ts';\nimport {\n\tWALLET_BEARER_PREFIX,\n\tWALLET_TOKEN_FRAGMENT_KEY,\n\tWALLET_TOKEN_HEX_LENGTH,\n} from './protocol.ts';\n\n// ----------------------------------------------------------------------\n// Token shape\n// ----------------------------------------------------------------------\n\n/** A pairing token. Branded so it can't be confused with arbitrary\n *  strings at the type level — only this module mints them. */\nexport type PairingToken = string & { readonly __pairingToken: unique symbol };\n\n/** Token-charset regex: lowercase hex, exactly 32 chars. Reject any\n *  on-disk value that doesn't match (re-mint). */\nconst TOKEN_RE = /^[0-9a-f]{32}$/;\n\nconst asToken = (s: string): PairingToken => s as PairingToken;\n\n// ----------------------------------------------------------------------\n// Generation\n// ----------------------------------------------------------------------\n\n/** Mint a fresh token. 16 random bytes → 32 hex chars. */\nexport const mintToken = (): Effect.Effect<PairingToken> =>\n\tEffect.sync(() => asToken(randomBytes(16).toString('hex')));\n\n// ----------------------------------------------------------------------\n// Persistence\n// ----------------------------------------------------------------------\n\n/** Resolve the on-disk token path under a state root. The state root\n *  is supplied by the substrate's identity / state-store config; this\n *  helper centralises the layout convention.\n *\n *  Convention: `<stateRoot>/wallet/token` — one token per stack, lives\n *  alongside other per-stack runtime artifacts. */\nexport const tokenPath = (stateRoot: string): string => joinPath(stateRoot, 'wallet', 'token');\n\n/**\n * Read the on-disk token if it exists and is well-formed; otherwise\n * mint + persist a fresh one via the substrate's atomic-write primitive\n * (mkdir-parent → O_EXCL temp → write → fsync → rename, mode 0o600).\n * Warm starts and snapshot restores both land in the \"read existing\"\n * branch so a previously-paired dev-wallet keeps working without a\n * re-pair UX.\n */\nexport const acquirePairingToken = (\n\tpath: string,\n): Effect.Effect<PairingToken, WalletBootError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\t// Try to read an existing token.\n\t\tconst existing = yield* Effect.tryPromise({\n\t\t\ttry: async () => {\n\t\t\t\ttry {\n\t\t\t\t\treturn await readFile(path, 'utf8');\n\t\t\t\t} catch (err) {\n\t\t\t\t\tif ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return null;\n\t\t\t\t\tthrow err;\n\t\t\t\t}\n\t\t\t},\n\t\t\tcatch: (cause) =>\n\t\t\t\twalletBootError({\n\t\t\t\t\tphase: 'read-token',\n\t\t\t\t\tmessage: `read of wallet token file failed at ${path}`,\n\t\t\t\t\thint: 'check filesystem permissions / disk availability',\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t});\n\n\t\tif (existing !== null) {\n\t\t\tconst trimmed = existing.trim();\n\t\t\tif (TOKEN_RE.test(trimmed)) {\n\t\t\t\treturn asToken(trimmed);\n\t\t\t}\n\t\t\t// Malformed — fall through to mint + overwrite.\n\t\t\tyield* Effect.logWarning('wallet token file is malformed; re-minting').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.walletTokenFile]: path,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\n\t\t// Mint a new one + persist via substrate's atomic-write\n\t\t// (mode 0o600). The token survives partial-write failures: the\n\t\t// in-memory value is authoritative for the current cycle, and a\n\t\t// failed persist surfaces as `write-token` so callers can choose\n\t\t// to fail-fast or continue with a transient pairing.\n\t\tconst token = yield* mintToken();\n\t\tconst bytes = new TextEncoder().encode(token);\n\t\tyield* atomicWriteFile(path, bytes, { mode: 0o600 }).pipe(\n\t\t\tEffect.mapError((cause) =>\n\t\t\t\twalletBootError({\n\t\t\t\t\tphase: 'write-token',\n\t\t\t\t\tmessage: `failed to persist wallet token at ${path}`,\n\t\t\t\t\thint: 'ENOSPC / EROFS / EACCES — boot continues with in-memory token; new pairing required next cycle',\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\n\t\treturn token;\n\t});\n\n// ----------------------------------------------------------------------\n// Pair-URL composition (fragment-only)\n// ----------------------------------------------------------------------\n\n/**\n * Compose the pair URL the dev-wallet adapter reads.\n *\n * The token rides the URL FRAGMENT (`#token=...`), never a query\n * parameter. Fragments are not sent to servers, so the token can't\n * land in access logs / referrer headers / Sentry breadcrumbs.\n */\nexport const composePairUrl = (walletUrl: string, token: PairingToken): string =>\n\t`${walletUrl}/#${WALLET_TOKEN_FRAGMENT_KEY}=${token}`;\n\n/**\n * Inverse — parse the token out of a pair URL fragment. Used by tests +\n * by the dev-wallet adapter (mirrored there because of the workspace-\n * cycle constraint).\n */\nexport const parsePairUrl = (pairUrl: string): PairingToken | null => {\n\tconst hashIdx = pairUrl.indexOf('#');\n\tif (hashIdx < 0) return null;\n\tconst fragment = pairUrl.slice(hashIdx + 1);\n\tconst prefix = `${WALLET_TOKEN_FRAGMENT_KEY}=`;\n\tif (!fragment.startsWith(prefix)) return null;\n\tconst raw = fragment.slice(prefix.length);\n\treturn TOKEN_RE.test(raw) ? asToken(raw) : null;\n};\n\n// ----------------------------------------------------------------------\n// Authorization-header bridge\n// ----------------------------------------------------------------------\n\n/**\n * Parse a raw `Authorization` header value into the bearer token. The\n * dev-wallet adapter copies the token from `url.hash` into the\n * `Authorization: Bearer <token>` header on every request — this\n * helper is the symmetric inverse.\n *\n * Returns `null` on missing / malformed header so the caller can map\n * to the structured `unauthorized` request error.\n */\nexport const parseBearerHeader = (header: string | undefined): string | null => {\n\tif (header === undefined) return null;\n\tif (!header.startsWith(WALLET_BEARER_PREFIX)) return null;\n\tconst raw = header.slice(WALLET_BEARER_PREFIX.length);\n\t// Don't TOKEN_RE-test here — the constant-time compare against the\n\t// expected token covers shape mismatch (length-difference shortcut\n\t// is acceptable since token length is public knowledge).\n\treturn raw.length === WALLET_TOKEN_HEX_LENGTH ? raw : null;\n};\n\n// ----------------------------------------------------------------------\n// Constant-time compare\n// ----------------------------------------------------------------------\n\n/**\n * Constant-time bearer-token compare. The length-mismatch shortcut is\n * intentional — token length is public knowledge (always 32 hex\n * chars), so leaking \"wrong length\" is not a credential leak. The\n * shortcut also prevents `timingSafeEqual` from throwing on mismatched\n * buffer sizes.\n *\n * Invariant (15-wallet.md \"Token comparison MUST be constant-time\"):\n * NEVER `===` two tokens. `===` on strings short-circuits at the first\n * mismatching byte, leaking the prefix byte-by-byte via response-time\n * measurement to a remote attacker.\n */\nexport const safeBearerEquals = (a: string, b: PairingToken | string): boolean => {\n\tif (a.length !== b.length) return false;\n\t// Both strings are 32 hex chars, ASCII — a fixed-length byte compare\n\t// is sufficient. UTF-8 encoding via `Buffer.from(_, 'utf8')` is\n\t// constant-time for the ASCII subset (each char → 1 byte).\n\tconst ab = Buffer.from(a, 'utf8');\n\tconst bb = Buffer.from(b, 'utf8');\n\tif (ab.length !== bb.length) return false; // defensive\n\treturn timingSafeEqual(ab, bb);\n};\n\n// ----------------------------------------------------------------------\n// Logging hygiene\n// ----------------------------------------------------------------------\n\nconst TOKEN_REDACTION_RULE: RedactionRule = {\n\tkind: 'pattern',\n\tpattern: /([#?&]token=)[A-Za-z0-9]+/g,\n\treplacement: '$1<redacted>',\n};\n\n/**\n * Redact the token fragment from any URL-shaped string for logging /\n * TUI rendering. Defense-in-depth — the engine's log sink should never\n * see the unredacted pair URL anyway, but this exists for callers that\n * accidentally pass `pairUrl` straight into a log line.\n *\n * Distilled-doc opportunity (15-wallet.md): the legacy redactor only\n * covered `#token=`. This regex covers BOTH the fragment form and a\n * hypothetical query form so a future config change doesn't silently\n * leak.\n */\nexport const redactToken = (s: string): string => redactText(s, [TOKEN_REDACTION_RULE]);\n"],"mappings":";;;;;;;;;;;;AAkDA,MAAM,WAAW;AAEjB,MAAM,WAAW,MAA4B;;AAO7C,MAAa,kBACZ,OAAO,WAAW,QAAQ,YAAY,GAAG,CAAC,SAAS,MAAM,CAAC,CAAC;;;;;;;AAY5D,MAAa,aAAa,cAA8BA,KAAS,WAAW,UAAU,QAAQ;;;;;;;;;AAU9F,MAAa,uBACZ,SAEA,OAAO,IAAI,aAAa;CAEvB,MAAM,WAAW,OAAO,OAAO,WAAW;EACzC,KAAK,YAAY;AAChB,OAAI;AACH,WAAO,MAAM,SAAS,MAAM,OAAO;YAC3B,KAAK;AACb,QAAK,KAA+B,SAAS,SAAU,QAAO;AAC9D,UAAM;;;EAGR,QAAQ,UACP,gBAAgB;GACf,OAAO;GACP,SAAS,uCAAuC;GAChD,MAAM;GACN;GACA,CAAC;EACH,CAAC;AAEF,KAAI,aAAa,MAAM;EACtB,MAAM,UAAU,SAAS,MAAM;AAC/B,MAAI,SAAS,KAAK,QAAQ,CACzB,QAAO,QAAQ,QAAQ;AAGxB,SAAO,OAAO,WAAW,6CAA6C,CAAC,KACtE,OAAO,aAAa,GAClB,SAAS,kBAAkB,MAC5B,CAAC,CACF;;CAQF,MAAM,QAAQ,OAAO,WAAW;AAEhC,QAAO,gBAAgB,MADT,IAAI,aAAa,CAAC,OAAO,MACL,EAAE,EAAE,MAAM,KAAO,CAAC,CAAC,KACpD,OAAO,UAAU,UAChB,gBAAgB;EACf,OAAO;EACP,SAAS,qCAAqC;EAC9C,MAAM;EACN;EACA,CAAC,CACF,CACD;AAED,QAAO;EACN;;;;;;;;AAaH,MAAa,kBAAkB,WAAmB,UACjD,GAAG,UAAU,IAAI,0BAA0B,GAAG;;;;;;;;;;AA8B/C,MAAa,qBAAqB,WAA8C;AAC/E,KAAI,WAAW,KAAA,EAAW,QAAO;AACjC,KAAI,CAAC,OAAO,WAAA,UAAgC,CAAE,QAAO;CACrD,MAAM,MAAM,OAAO,MAAM,qBAAqB,OAAO;AAIrD,QAAO,IAAI,WAAA,KAAqC,MAAM;;;;;;;;;;;;;;AAmBvD,MAAa,oBAAoB,GAAW,MAAsC;AACjF,KAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;CAIlC,MAAM,KAAK,OAAO,KAAK,GAAG,OAAO;CACjC,MAAM,KAAK,OAAO,KAAK,GAAG,OAAO;AACjC,KAAI,GAAG,WAAW,GAAG,OAAQ,QAAO;AACpC,QAAO,gBAAgB,IAAI,GAAG;;AAO/B,MAAM,uBAAsC;CAC3C,MAAM;CACN,SAAS;CACT,aAAa;CACb;;;;;;;;;;;;AAaD,MAAa,eAAe,MAAsB,WAAW,GAAG,CAAC,qBAAqB,CAAC"}
+{"version":3,"file":"pairing.mjs","names":["joinPath"],"sources":["../../../src/plugins/wallet/pairing.ts"],"sourcesContent":["// Wallet plugin — pairing-token discipline.\n//\n// What this module owns (15-wallet.md \"Token comparison MUST be\n// constant-time\", \"Token MUST live in URL fragment (not query)\",\n// \"Token MUST NOT appear in log lines\", \"Token file MUST be mode\n// 0o600\"):\n//\n//   1. Token generation: 16 random bytes → 32 hex chars.\n//   2. Token persistence: file at `<stateRoot>/wallet/token`, mode\n//      `0o600`, atomic write.\n//   3. Token rehydration: read-existing-or-mint so warm starts +\n//      snapshot restore preserve the dev-wallet pairing.\n//   4. URL-fragment ↔ Authorization-header bridge: helpers that\n//      compose the pair URL (token in fragment) and parse the\n//      bearer-prefixed header back to the raw token.\n//   5. Constant-time bearer compare: timing-safe equality so a\n//      remote attacker can't recover the token byte-by-byte via\n//      response-time measurement.\n//\n// What this module does NOT own:\n//\n//   - The HTTP server (see `server.ts`).\n//   - The CORS / Origin allowlist (see `origin-policy.ts`).\n//   - The codegen file (see `codegen.ts`).\n\nimport { Effect, FileSystem } from 'effect';\nimport { randomBytes, timingSafeEqual } from 'node:crypto';\nimport { readFile } from 'node:fs/promises';\nimport { join as joinPath } from 'node:path';\n\nimport { atomicWriteFile } from '../../substrate/runtime/atomic-write.ts';\nimport { redactText, type RedactionRule } from '../../substrate/runtime/observability/index.ts';\nimport { walletBootError, type WalletBootError } from './errors.ts';\nimport { WalletSpans } from './spans.ts';\nimport {\n\tWALLET_BEARER_PREFIX,\n\tWALLET_TOKEN_FRAGMENT_KEY,\n\tWALLET_TOKEN_HEX_LENGTH,\n} from './protocol.ts';\n\n// ----------------------------------------------------------------------\n// Token shape\n// ----------------------------------------------------------------------\n\n/** A pairing token. Branded so it can't be confused with arbitrary\n *  strings at the type level — only this module mints them. */\nexport type PairingToken = string & { readonly __pairingToken: unique symbol };\n\n/** Token-charset regex: lowercase hex, exactly 32 chars. Reject any\n *  on-disk value that doesn't match (re-mint). */\nconst TOKEN_RE = /^[0-9a-f]{32}$/;\n\nconst asToken = (s: string): PairingToken => s as PairingToken;\n\n// ----------------------------------------------------------------------\n// Generation\n// ----------------------------------------------------------------------\n\n/** Mint a fresh token. 16 random bytes → 32 hex chars. */\nexport const mintToken = (): Effect.Effect<PairingToken> =>\n\tEffect.sync(() => asToken(randomBytes(16).toString('hex')));\n\n// ----------------------------------------------------------------------\n// Persistence\n// ----------------------------------------------------------------------\n\n/** Resolve the on-disk token path under a state root. The state root\n *  is supplied by the substrate's identity / state-store config; this\n *  helper centralises the layout convention.\n *\n *  Convention: `<stateRoot>/wallet/token` — one token per stack, lives\n *  alongside other per-stack runtime artifacts. */\nexport const tokenPath = (stateRoot: string): string => joinPath(stateRoot, 'wallet', 'token');\n\n/**\n * Read the on-disk token if it exists and is well-formed; otherwise\n * mint + persist a fresh one via the substrate's atomic-write primitive\n * (mkdir-parent → O_EXCL temp → write → fsync → rename, mode 0o600).\n * Warm starts and snapshot restores both land in the \"read existing\"\n * branch so a previously-paired dev-wallet keeps working without a\n * re-pair UX.\n */\nexport const acquirePairingToken = (\n\tpath: string,\n): Effect.Effect<PairingToken, WalletBootError, FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\t// Try to read an existing token.\n\t\tconst existing = yield* Effect.tryPromise({\n\t\t\ttry: async () => {\n\t\t\t\ttry {\n\t\t\t\t\treturn await readFile(path, 'utf8');\n\t\t\t\t} catch (err) {\n\t\t\t\t\tif ((err as NodeJS.ErrnoException)?.code === 'ENOENT') return null;\n\t\t\t\t\tthrow err;\n\t\t\t\t}\n\t\t\t},\n\t\t\tcatch: (cause) =>\n\t\t\t\twalletBootError({\n\t\t\t\t\tphase: 'read-token',\n\t\t\t\t\tmessage: `read of wallet token file failed at ${path}`,\n\t\t\t\t\thint: 'check filesystem permissions / disk availability',\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t});\n\n\t\tif (existing !== null) {\n\t\t\tconst trimmed = existing.trim();\n\t\t\tif (TOKEN_RE.test(trimmed)) {\n\t\t\t\treturn asToken(trimmed);\n\t\t\t}\n\t\t\t// Malformed — fall through to mint + overwrite.\n\t\t\tyield* Effect.logWarning('wallet token file is malformed; re-minting').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[WalletSpans.tokenFile]: path,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\n\t\t// Mint a new one + persist via substrate's atomic-write\n\t\t// (mode 0o600). The token survives partial-write failures: the\n\t\t// in-memory value is authoritative for the current cycle, and a\n\t\t// failed persist surfaces as `write-token` so callers can choose\n\t\t// to fail-fast or continue with a transient pairing.\n\t\tconst token = yield* mintToken();\n\t\tconst bytes = new TextEncoder().encode(token);\n\t\tyield* atomicWriteFile(path, bytes, { mode: 0o600 }).pipe(\n\t\t\tEffect.mapError((cause) =>\n\t\t\t\twalletBootError({\n\t\t\t\t\tphase: 'write-token',\n\t\t\t\t\tmessage: `failed to persist wallet token at ${path}`,\n\t\t\t\t\thint: 'ENOSPC / EROFS / EACCES — boot continues with in-memory token; new pairing required next cycle',\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\n\t\treturn token;\n\t});\n\n// ----------------------------------------------------------------------\n// Pair-URL composition (fragment-only)\n// ----------------------------------------------------------------------\n\n/**\n * Compose the pair URL the dev-wallet adapter reads.\n *\n * The token rides the URL FRAGMENT (`#token=...`), never a query\n * parameter. Fragments are not sent to servers, so the token can't\n * land in access logs / referrer headers / Sentry breadcrumbs.\n */\nexport const composePairUrl = (walletUrl: string, token: PairingToken): string =>\n\t`${walletUrl}/#${WALLET_TOKEN_FRAGMENT_KEY}=${token}`;\n\n/**\n * Inverse — parse the token out of a pair URL fragment. Used by tests +\n * by the dev-wallet adapter (mirrored there because of the workspace-\n * cycle constraint).\n */\nexport const parsePairUrl = (pairUrl: string): PairingToken | null => {\n\tconst hashIdx = pairUrl.indexOf('#');\n\tif (hashIdx < 0) return null;\n\tconst fragment = pairUrl.slice(hashIdx + 1);\n\tconst prefix = `${WALLET_TOKEN_FRAGMENT_KEY}=`;\n\tif (!fragment.startsWith(prefix)) return null;\n\tconst raw = fragment.slice(prefix.length);\n\treturn TOKEN_RE.test(raw) ? asToken(raw) : null;\n};\n\n// ----------------------------------------------------------------------\n// Authorization-header bridge\n// ----------------------------------------------------------------------\n\n/**\n * Parse a raw `Authorization` header value into the bearer token. The\n * dev-wallet adapter copies the token from `url.hash` into the\n * `Authorization: Bearer <token>` header on every request — this\n * helper is the symmetric inverse.\n *\n * Returns `null` on missing / malformed header so the caller can map\n * to the structured `unauthorized` request error.\n */\nexport const parseBearerHeader = (header: string | undefined): string | null => {\n\tif (header === undefined) return null;\n\tif (!header.startsWith(WALLET_BEARER_PREFIX)) return null;\n\tconst raw = header.slice(WALLET_BEARER_PREFIX.length);\n\t// Don't TOKEN_RE-test here — the constant-time compare against the\n\t// expected token covers shape mismatch (length-difference shortcut\n\t// is acceptable since token length is public knowledge).\n\treturn raw.length === WALLET_TOKEN_HEX_LENGTH ? raw : null;\n};\n\n// ----------------------------------------------------------------------\n// Constant-time compare\n// ----------------------------------------------------------------------\n\n/**\n * Constant-time bearer-token compare. The length-mismatch shortcut is\n * intentional — token length is public knowledge (always 32 hex\n * chars), so leaking \"wrong length\" is not a credential leak. The\n * shortcut also prevents `timingSafeEqual` from throwing on mismatched\n * buffer sizes.\n *\n * Invariant (15-wallet.md \"Token comparison MUST be constant-time\"):\n * NEVER `===` two tokens. `===` on strings short-circuits at the first\n * mismatching byte, leaking the prefix byte-by-byte via response-time\n * measurement to a remote attacker.\n */\nexport const safeBearerEquals = (a: string, b: PairingToken | string): boolean => {\n\tif (a.length !== b.length) return false;\n\t// `a` is attacker-controlled — a multi-byte UTF-8 codepoint in `a`\n\t// would inflate `ab.length` past `bb.length` even though\n\t// `a.length === b.length` passed (string length counts UTF-16 code\n\t// units, byte length counts UTF-8 bytes). The second length guard\n\t// stops `timingSafeEqual` from throwing in that case (its contract\n\t// requires equal-length buffers) and keeps the function total. For\n\t// the canonical case (`b` is a 32-hex `PairingToken`) the guard is\n\t// redundant; for the defensive case it prevents a malformed-input\n\t// throw from leaking up the dispatcher path.\n\tconst ab = Buffer.from(a, 'utf8');\n\tconst bb = Buffer.from(b, 'utf8');\n\tif (ab.length !== bb.length) return false;\n\treturn timingSafeEqual(ab, bb);\n};\n\n// ----------------------------------------------------------------------\n// Logging hygiene\n// ----------------------------------------------------------------------\n\nconst TOKEN_REDACTION_RULE: RedactionRule = {\n\tkind: 'pattern',\n\tpattern: /([#?&]token=)[A-Za-z0-9]+/g,\n\treplacement: '$1<redacted>',\n};\n\n/**\n * Redact the token fragment from any URL-shaped string for logging /\n * TUI rendering. Defense-in-depth — the engine's log sink should never\n * see the unredacted pair URL anyway, but this exists for callers that\n * accidentally pass `pairUrl` straight into a log line.\n *\n * Distilled-doc opportunity (15-wallet.md): the legacy redactor only\n * covered `#token=`. This regex covers BOTH the fragment form and a\n * hypothetical query form so a future config change doesn't silently\n * leak.\n */\nexport const redactToken = (s: string): string => redactText(s, [TOKEN_REDACTION_RULE]);\n"],"mappings":";;;;;;;;;;;;;;AAkDA,MAAM,WAAW;AAEjB,MAAM,WAAW,MAA4B;;AAO7C,MAAa,kBACZ,OAAO,WAAW,QAAQ,YAAY,GAAG,CAAC,SAAS,MAAM,CAAC,CAAC;;;;;;;AAY5D,MAAa,aAAa,cAA8BA,KAAS,WAAW,UAAU,QAAQ;;;;;;;;;AAU9F,MAAa,uBACZ,SAEA,OAAO,IAAI,aAAa;CAEvB,MAAM,WAAW,OAAO,OAAO,WAAW;EACzC,KAAK,YAAY;AAChB,OAAI;AACH,WAAO,MAAM,SAAS,MAAM,OAAO;YAC3B,KAAK;AACb,QAAK,KAA+B,SAAS,SAAU,QAAO;AAC9D,UAAM;;;EAGR,QAAQ,UACP,gBAAgB;GACf,OAAO;GACP,SAAS,uCAAuC;GAChD,MAAM;GACN;GACA,CAAC;EACH,CAAC;AAEF,KAAI,aAAa,MAAM;EACtB,MAAM,UAAU,SAAS,MAAM;AAC/B,MAAI,SAAS,KAAK,QAAQ,CACzB,QAAO,QAAQ,QAAQ;AAGxB,SAAO,OAAO,WAAW,6CAA6C,CAAC,KACtE,OAAO,aAAa,GAClB,YAAY,YAAY,MACzB,CAAC,CACF;;CAQF,MAAM,QAAQ,OAAO,WAAW;AAEhC,QAAO,gBAAgB,MADT,IAAI,aAAa,CAAC,OAAO,MACL,EAAE,EAAE,MAAM,KAAO,CAAC,CAAC,KACpD,OAAO,UAAU,UAChB,gBAAgB;EACf,OAAO;EACP,SAAS,qCAAqC;EAC9C,MAAM;EACN;EACA,CAAC,CACF,CACD;AAED,QAAO;EACN;;;;;;;;AAaH,MAAa,kBAAkB,WAAmB,UACjD,GAAG,UAAU,IAAI,0BAA0B,GAAG;;;;;;;;;;AA8B/C,MAAa,qBAAqB,WAA8C;AAC/E,KAAI,WAAW,KAAA,EAAW,QAAO;AACjC,KAAI,CAAC,OAAO,WAAA,UAAgC,CAAE,QAAO;CACrD,MAAM,MAAM,OAAO,MAAM,qBAAqB,OAAO;AAIrD,QAAO,IAAI,WAAA,KAAqC,MAAM;;;;;;;;;;;;;;AAmBvD,MAAa,oBAAoB,GAAW,MAAsC;AACjF,KAAI,EAAE,WAAW,EAAE,OAAQ,QAAO;CAUlC,MAAM,KAAK,OAAO,KAAK,GAAG,OAAO;CACjC,MAAM,KAAK,OAAO,KAAK,GAAG,OAAO;AACjC,KAAI,GAAG,WAAW,GAAG,OAAQ,QAAO;AACpC,QAAO,gBAAgB,IAAI,GAAG;;AAO/B,MAAM,uBAAsC;CAC3C,MAAM;CACN,SAAS;CACT,aAAa;CACb;;;;;;;;;;;;AAaD,MAAa,eAAe,MAAsB,WAAW,GAAG,CAAC,qBAAqB,CAAC"}

package/dist/plugins/wallet/protocol.d.mts

@@ -1 +1,2 @@
+import { WALLET_AUTH_HEADER, WALLET_BEARER_PREFIX, WALLET_PROTOCOL_PREFIX, WALLET_TOKEN_FRAGMENT_KEY, WALLET_TOKEN_HEX_LENGTH, WalletHttpPath, WalletHttpPathValue } from "../../contracts/wallet-protocol.mjs";
 import { Schema } from "effect";

package/dist/plugins/wallet/protocol.mjs

@@ -1,27 +1,7 @@
+import "../../contracts/wallet-protocol.mjs";
 import { Schema } from "effect";
 //#region src/plugins/wallet/protocol.ts
 /**
-* Canonical path constants under the `/api/v1/devstack/*` prefix.
-*
-* Distilled-doc note (15-wallet.md "Fork-control routes declared but
-* unimplemented"): the legacy server declared four `FORK_*` path
-* constants whose handlers never landed. Per "no compat for never-
-* cases", we drop them from the wire protocol entirely — when the
-* fork-control surface is wired, those routes will be added (and the
-* dev-wallet adapter shipped together). No half-done stubs.
-*/
-const WalletHttpPath = {
-	HEALTH: "/api/v1/devstack/health",
-	ACCOUNTS: "/api/v1/devstack/accounts",
-	SIGN_TRANSACTION: "/api/v1/devstack/sign-transaction",
-	SIGN_PERSONAL_MESSAGE: "/api/v1/devstack/sign-personal-message",
-	EXECUTE: "/api/v1/devstack/execute"
-};
-/** Prefix gate: ANY path under this prefix is treated as protocol traffic
-*  (and subject to mandatory Origin + bearer); anything else is a flat
-*  404. */
-const WALLET_PROTOCOL_PREFIX = "/api/v1/devstack/";
-/**
 * Sui address — `0x` + 64 hex chars. Schema-validated so a typo or
 * truncated address surfaces as a structured `body-invalid` request
 * error rather than a confusing `address-not-found` (no account bound
@@ -40,9 +20,9 @@ const SignatureSchemeSchema = Schema.Union([
 	Schema.Literal("secp256r1")
 ]);
 /** Account-source discriminator. `'impersonate'` accounts cannot
-*  satisfy `signTransaction` / `signPersonalMessage` — only
-*  `/execute` (which routes through the fork-admin surface) makes
-*  sense for them. */
+*  satisfy `signTransaction` / `signPersonalMessage` — fork-admin
+*  surfaces (not part of this protocol today) are the only sensible
+*  consumers. */
 const AccountSourceSchema = Schema.Union([Schema.Literal("real"), Schema.Literal("impersonate")]);
 Schema.Struct({ ok: Schema.Literal(true) });
 const AccountSummarySchema = Schema.Struct({
@@ -67,30 +47,11 @@ Schema.Struct({
 	bytes: Base64Schema,
 	signature: Schema.String
 });
-/** Execute request — `bytes` is the BCS-serialized transaction.
-*  Impersonation accounts route through fork-admin (no signature
-*  needed); real accounts route through `signAndExecute`. */
-const ExecuteRequestSchema = Schema.Struct({
-	address: SuiAddressSchema,
-	bytes: Base64Schema
-});
-Schema.Struct({
-	digest: Schema.String,
-	effects: Schema.Unknown,
-	objectChanges: Schema.Array(Schema.Unknown),
-	balanceChanges: Schema.Array(Schema.Unknown)
-});
 Schema.Struct({
 	error: Schema.String,
 	code: Schema.String
 });
-const WALLET_AUTH_HEADER = "authorization";
-const WALLET_BEARER_PREFIX = "Bearer ";
-/** URL-fragment key the pair-URL carries the token under
-*  (`<wallet-url>/#token=<32-hex>`). Fragments are not sent to the
-*  server, so the token never appears in access logs / referrers. */
-const WALLET_TOKEN_FRAGMENT_KEY = "token";
 //#endregion
-export { AccountSourceSchema, AccountSummarySchema, Base64Schema, ExecuteRequestSchema, SignRequestSchema, SignatureSchemeSchema, SuiAddressSchema, WALLET_AUTH_HEADER, WALLET_BEARER_PREFIX, WALLET_PROTOCOL_PREFIX, WALLET_TOKEN_FRAGMENT_KEY, WalletHttpPath };
+export { AccountSourceSchema, AccountSummarySchema, Base64Schema, SignRequestSchema, SignatureSchemeSchema, SuiAddressSchema };
 
 //# sourceMappingURL=protocol.mjs.map

package/dist/plugins/wallet/protocol.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.mjs","names":[],"sources":["../../../src/plugins/wallet/protocol.ts"],"sourcesContent":["// Wallet plugin — wire-level protocol.\n//\n// This file is the ONE cross-boundary contract between the devstack-\n// side HTTP server (this plugin) and the browser-side adapter (the\n// `dev-wallet` package). The browser-side adapter MUST be kept in\n// lock-step with these schemas; today that's enforced by a mirror in\n// `dev-wallet/src/adapters/devstack-paths.ts` + a byte-equality test.\n//\n// Distilled-doc opportunity (15-wallet.md \"Acyclic-edge duplication\"):\n// the duplication exists because devstack peer-deps on dev-wallet (for\n// codegen output) and a reverse edge would close a workspace cycle.\n// Per the task's architecture-revision flag: the long-term fix is to\n// hoist this file into a third tiny package (e.g.\n// `@mysten-incubation/devstack-wallet-protocol`) consumed by BOTH\n// sides. See `## Architecture-doc revisions` in the report.\n//\n// Canonical envelope choice (15-wallet.md \"Asymmetric sign-response\n// field names\" + \"Dual field-name acceptance\"):\n//\n//   - Sign endpoints accept `{ address, bytes }` (always `bytes`, never\n//     `txBytes` or `messageBytes`).\n//   - Sign endpoints respond `{ bytes, signature }` (always those two\n//     names; never `txBytes` / `suiSignature`).\n//\n// This mirrors `@mysten/sui`'s `Signer.signTransaction` /\n// `signPersonalMessage` return shape exactly, eliminating the asymmetry\n// the legacy server carried. Per the memory note \"no compat for\n// never-cases\" — devstack is unreleased, no migration burden.\n//\n// Effect v4 Schema is the validator. Each request/response is a\n// Schema.Struct; handlers `Schema.decodeUnknown(...)` the body and\n// `catchTag('ParseError', ...)` into a `body-invalid` request error.\n\nimport { Schema } from 'effect';\n\n// ----------------------------------------------------------------------\n// Path constants\n// ----------------------------------------------------------------------\n\n/**\n * Canonical path constants under the `/api/v1/devstack/*` prefix.\n *\n * Distilled-doc note (15-wallet.md \"Fork-control routes declared but\n * unimplemented\"): the legacy server declared four `FORK_*` path\n * constants whose handlers never landed. Per \"no compat for never-\n * cases\", we drop them from the wire protocol entirely — when the\n * fork-control surface is wired, those routes will be added (and the\n * dev-wallet adapter shipped together). No half-done stubs.\n */\nexport const WalletHttpPath = {\n\tHEALTH: '/api/v1/devstack/health',\n\tACCOUNTS: '/api/v1/devstack/accounts',\n\tSIGN_TRANSACTION: '/api/v1/devstack/sign-transaction',\n\tSIGN_PERSONAL_MESSAGE: '/api/v1/devstack/sign-personal-message',\n\tEXECUTE: '/api/v1/devstack/execute',\n} as const;\n\nexport type WalletHttpPathValue = (typeof WalletHttpPath)[keyof typeof WalletHttpPath];\n\n/** Prefix gate: ANY path under this prefix is treated as protocol traffic\n *  (and subject to mandatory Origin + bearer); anything else is a flat\n *  404. */\nexport const WALLET_PROTOCOL_PREFIX = '/api/v1/devstack/' as const;\n\n// ----------------------------------------------------------------------\n// Shared primitives\n// ----------------------------------------------------------------------\n\n/**\n * Sui address — `0x` + 64 hex chars. Schema-validated so a typo or\n * truncated address surfaces as a structured `body-invalid` request\n * error rather than a confusing `address-not-found` (no account bound\n * at the address would be the same shape if we didn't validate).\n */\nexport const SuiAddressSchema = Schema.String.check(Schema.isPattern(/^0x[0-9a-fA-F]{64}$/));\n\n/** Base64-encoded bytes — string-typed at the wire (we keep base64 over\n *  the cross-boundary; the server decodes with `Uint8Array.fromBase64`\n *  or equivalent before handing to the Account sign closures). */\nexport const Base64Schema = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9+/]*={0,2}$/));\n\n/** Signature scheme discriminator surfaced on `/accounts`. Mirrors the\n *  `AccountValue.scheme` shape from the account plugin. */\nexport const SignatureSchemeSchema = Schema.Union([\n\tSchema.Literal('ed25519'),\n\tSchema.Literal('secp256k1'),\n\tSchema.Literal('secp256r1'),\n]);\n\n/** Account-source discriminator. `'impersonate'` accounts cannot\n *  satisfy `signTransaction` / `signPersonalMessage` — only\n *  `/execute` (which routes through the fork-admin surface) makes\n *  sense for them. */\nexport const AccountSourceSchema = Schema.Union([\n\tSchema.Literal('real'),\n\tSchema.Literal('impersonate'),\n]);\n\n// ----------------------------------------------------------------------\n// Response envelopes (200)\n// ----------------------------------------------------------------------\n\nexport const HealthResponseSchema = Schema.Struct({\n\tok: Schema.Literal(true),\n});\nexport type HealthResponse = Schema.Schema.Type<typeof HealthResponseSchema>;\n\nexport const AccountSummarySchema = Schema.Struct({\n\tname: Schema.String,\n\taddress: SuiAddressSchema,\n\tscheme: SignatureSchemeSchema,\n\t/** Base64-encoded `publicKey`. Impersonation accounts publish a\n\t *  zero-length string here — consumers branch on `source`, not on\n\t *  publicKey emptiness. */\n\tpublicKey: Base64Schema,\n\tsource: AccountSourceSchema,\n});\nexport type AccountSummary = Schema.Schema.Type<typeof AccountSummarySchema>;\n\nexport const AccountsResponseSchema = Schema.Struct({\n\taccounts: Schema.Array(AccountSummarySchema),\n});\nexport type AccountsResponse = Schema.Schema.Type<typeof AccountsResponseSchema>;\n\n// ----------------------------------------------------------------------\n// Sign endpoints — request + response\n// ----------------------------------------------------------------------\n\n/** Canonical sign request — same shape for transaction and personal-\n *  message routes. `bytes` is the only payload key (no `txBytes`,\n *  `message`, or `messageBytes` aliases). */\nexport const SignRequestSchema = Schema.Struct({\n\taddress: SuiAddressSchema,\n\tbytes: Base64Schema,\n});\nexport type SignRequest = Schema.Schema.Type<typeof SignRequestSchema>;\n\n/** Canonical sign response — same shape for transaction and personal-\n *  message routes. Matches `@mysten/sui`'s `Signer` return shape\n *  byte-for-byte. */\nexport const SignResponseSchema = Schema.Struct({\n\tbytes: Base64Schema,\n\tsignature: Schema.String,\n});\nexport type SignResponse = Schema.Schema.Type<typeof SignResponseSchema>;\n\n// ----------------------------------------------------------------------\n// Execute endpoint — request + response\n// ----------------------------------------------------------------------\n\n/** Execute request — `bytes` is the BCS-serialized transaction.\n *  Impersonation accounts route through fork-admin (no signature\n *  needed); real accounts route through `signAndExecute`. */\nexport const ExecuteRequestSchema = Schema.Struct({\n\taddress: SuiAddressSchema,\n\tbytes: Base64Schema,\n});\nexport type ExecuteRequest = Schema.Schema.Type<typeof ExecuteRequestSchema>;\n\n/** Execute response — the narrow `TxResult` projection the account\n *  plugin already publishes. The `effects` / `objectChanges` /\n *  `balanceChanges` fields cross the wire as opaque JSON; downstream\n *  consumers do their own parsing. */\nexport const ExecuteResponseSchema = Schema.Struct({\n\tdigest: Schema.String,\n\teffects: Schema.Unknown,\n\tobjectChanges: Schema.Array(Schema.Unknown),\n\tbalanceChanges: Schema.Array(Schema.Unknown),\n});\nexport type ExecuteResponse = Schema.Schema.Type<typeof ExecuteResponseSchema>;\n\n// ----------------------------------------------------------------------\n// Error envelope\n// ----------------------------------------------------------------------\n\n/** Error response body. The HTTP status carries the broad classification\n *  (400/401/403/404/500); `code` carries the narrow phase so callers\n *  can branch programmatically. */\nexport const ErrorResponseSchema = Schema.Struct({\n\terror: Schema.String,\n\tcode: Schema.String,\n});\nexport type ErrorResponse = Schema.Schema.Type<typeof ErrorResponseSchema>;\n\n// ----------------------------------------------------------------------\n// Header constants (shared so the dev-wallet adapter doesn't open-code\n// the same strings).\n// ----------------------------------------------------------------------\n\nexport const WALLET_AUTH_HEADER = 'authorization' as const;\nexport const WALLET_BEARER_PREFIX = 'Bearer ' as const;\n\n/** URL-fragment key the pair-URL carries the token under\n *  (`<wallet-url>/#token=<32-hex>`). Fragments are not sent to the\n *  server, so the token never appears in access logs / referrers. */\nexport const WALLET_TOKEN_FRAGMENT_KEY = 'token' as const;\n\n/** Constant carried token byte length (16 random bytes → 32 hex chars).\n *  The on-disk token file is rejected + re-minted if it doesn't match. */\nexport const WALLET_TOKEN_HEX_LENGTH = 32 as const;\n"],"mappings":";;;;;;;;;;;;AAiDA,MAAa,iBAAiB;CAC7B,QAAQ;CACR,UAAU;CACV,kBAAkB;CAClB,uBAAuB;CACvB,SAAS;CACT;;;;AAOD,MAAa,yBAAyB;;;;;;;AAYtC,MAAa,mBAAmB,OAAO,OAAO,MAAM,OAAO,UAAU,sBAAsB,CAAC;;;;AAK5F,MAAa,eAAe,OAAO,OAAO,MAAM,OAAO,UAAU,yBAAyB,CAAC;;;AAI3F,MAAa,wBAAwB,OAAO,MAAM;CACjD,OAAO,QAAQ,UAAU;CACzB,OAAO,QAAQ,YAAY;CAC3B,OAAO,QAAQ,YAAY;CAC3B,CAAC;;;;;AAMF,MAAa,sBAAsB,OAAO,MAAM,CAC/C,OAAO,QAAQ,OAAO,EACtB,OAAO,QAAQ,cAAc,CAC7B,CAAC;AAMkC,OAAO,OAAO,EACjD,IAAI,OAAO,QAAQ,KAAK,EACxB,CAAC;AAGF,MAAa,uBAAuB,OAAO,OAAO;CACjD,MAAM,OAAO;CACb,SAAS;CACT,QAAQ;;;;CAIR,WAAW;CACX,QAAQ;CACR,CAAC;AAGoC,OAAO,OAAO,EACnD,UAAU,OAAO,MAAM,qBAAqB,EAC5C,CAAC;;;;AAUF,MAAa,oBAAoB,OAAO,OAAO;CAC9C,SAAS;CACT,OAAO;CACP,CAAC;AAMgC,OAAO,OAAO;CAC/C,OAAO;CACP,WAAW,OAAO;CAClB,CAAC;;;;AAUF,MAAa,uBAAuB,OAAO,OAAO;CACjD,SAAS;CACT,OAAO;CACP,CAAC;AAOmC,OAAO,OAAO;CAClD,QAAQ,OAAO;CACf,SAAS,OAAO;CAChB,eAAe,OAAO,MAAM,OAAO,QAAQ;CAC3C,gBAAgB,OAAO,MAAM,OAAO,QAAQ;CAC5C,CAAC;AAUiC,OAAO,OAAO;CAChD,OAAO,OAAO;CACd,MAAM,OAAO;CACb,CAAC;AAQF,MAAa,qBAAqB;AAClC,MAAa,uBAAuB;;;;AAKpC,MAAa,4BAA4B"}
+{"version":3,"file":"protocol.mjs","names":[],"sources":["../../../src/plugins/wallet/protocol.ts"],"sourcesContent":["// Wallet plugin — wire-level protocol.\n//\n// This file is the ONE cross-boundary contract between the devstack-\n// side HTTP server (this plugin) and the browser-side adapter (the\n// `dev-wallet` package). The browser-side adapter MUST be kept in\n// lock-step with these schemas; today that's enforced by a mirror in\n// `dev-wallet/src/adapters/devstack-paths.ts` + a byte-equality test.\n//\n// Distilled-doc opportunity (15-wallet.md \"Acyclic-edge duplication\"):\n// the duplication exists because devstack peer-deps on dev-wallet (for\n// codegen output) and a reverse edge would close a workspace cycle.\n// Per the task's architecture-revision flag: the long-term fix is to\n// hoist this file into a third tiny package (e.g.\n// `@mysten-incubation/devstack-wallet-protocol`) consumed by BOTH\n// sides. See `## Architecture-doc revisions` in the report.\n//\n// Canonical envelope choice (15-wallet.md \"Asymmetric sign-response\n// field names\" + \"Dual field-name acceptance\"):\n//\n//   - Sign endpoints accept `{ address, bytes }` (always `bytes`, never\n//     `txBytes` or `messageBytes`).\n//   - Sign endpoints respond `{ bytes, signature }` (always those two\n//     names; never `txBytes` / `suiSignature`).\n//\n// This mirrors `@mysten/sui`'s `Signer.signTransaction` /\n// `signPersonalMessage` return shape exactly, eliminating the asymmetry\n// the legacy server carried. Per the memory note \"no compat for\n// never-cases\" — devstack is unreleased, no migration burden.\n//\n// Effect v4 Schema is the validator. Each request/response is a\n// Schema.Struct; handlers `Schema.decodeUnknown(...)` the body and\n// `catchTag('ParseError', ...)` into a `body-invalid` request error.\n\nimport { Schema } from 'effect';\n\n// Pure wire constants live in the name-blind contract so L5 build\n// integrations can consume them without importing this L2 plugin\n// module; re-exported here so plugin-internal callers keep their\n// current import sites.\nexport {\n\tWalletHttpPath,\n\tWALLET_PROTOCOL_PREFIX,\n\tWALLET_AUTH_HEADER,\n\tWALLET_BEARER_PREFIX,\n\tWALLET_TOKEN_FRAGMENT_KEY,\n\tWALLET_TOKEN_HEX_LENGTH,\n\ttype WalletHttpPathValue,\n} from '../../contracts/wallet-protocol.ts';\n\n// ----------------------------------------------------------------------\n// Shared primitives\n// ----------------------------------------------------------------------\n\n/**\n * Sui address — `0x` + 64 hex chars. Schema-validated so a typo or\n * truncated address surfaces as a structured `body-invalid` request\n * error rather than a confusing `address-not-found` (no account bound\n * at the address would be the same shape if we didn't validate).\n */\nexport const SuiAddressSchema = Schema.String.check(Schema.isPattern(/^0x[0-9a-fA-F]{64}$/));\n\n/** Base64-encoded bytes — string-typed at the wire (we keep base64 over\n *  the cross-boundary; the server decodes with `Uint8Array.fromBase64`\n *  or equivalent before handing to the Account sign closures). */\nexport const Base64Schema = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9+/]*={0,2}$/));\n\n/** Signature scheme discriminator surfaced on `/accounts`. Mirrors the\n *  `AccountValue.scheme` shape from the account plugin. */\nexport const SignatureSchemeSchema = Schema.Union([\n\tSchema.Literal('ed25519'),\n\tSchema.Literal('secp256k1'),\n\tSchema.Literal('secp256r1'),\n]);\n\n/** Account-source discriminator. `'impersonate'` accounts cannot\n *  satisfy `signTransaction` / `signPersonalMessage` — fork-admin\n *  surfaces (not part of this protocol today) are the only sensible\n *  consumers. */\nexport const AccountSourceSchema = Schema.Union([\n\tSchema.Literal('real'),\n\tSchema.Literal('impersonate'),\n]);\n\n// ----------------------------------------------------------------------\n// Response envelopes (200)\n// ----------------------------------------------------------------------\n\nexport const HealthResponseSchema = Schema.Struct({\n\tok: Schema.Literal(true),\n});\nexport type HealthResponse = Schema.Schema.Type<typeof HealthResponseSchema>;\n\nexport const AccountSummarySchema = Schema.Struct({\n\tname: Schema.String,\n\taddress: SuiAddressSchema,\n\tscheme: SignatureSchemeSchema,\n\t/** Base64-encoded `publicKey`. Impersonation accounts publish a\n\t *  zero-length string here — consumers branch on `source`, not on\n\t *  publicKey emptiness. */\n\tpublicKey: Base64Schema,\n\tsource: AccountSourceSchema,\n});\nexport type AccountSummary = Schema.Schema.Type<typeof AccountSummarySchema>;\n\nexport const AccountsResponseSchema = Schema.Struct({\n\taccounts: Schema.Array(AccountSummarySchema),\n});\nexport type AccountsResponse = Schema.Schema.Type<typeof AccountsResponseSchema>;\n\n// ----------------------------------------------------------------------\n// Sign endpoints — request + response\n// ----------------------------------------------------------------------\n\n/** Canonical sign request — same shape for transaction and personal-\n *  message routes. `bytes` is the only payload key (no `txBytes`,\n *  `message`, or `messageBytes` aliases). */\nexport const SignRequestSchema = Schema.Struct({\n\taddress: SuiAddressSchema,\n\tbytes: Base64Schema,\n});\nexport type SignRequest = Schema.Schema.Type<typeof SignRequestSchema>;\n\n/** Canonical sign response — same shape for transaction and personal-\n *  message routes. Matches `@mysten/sui`'s `Signer` return shape\n *  byte-for-byte. */\nexport const SignResponseSchema = Schema.Struct({\n\tbytes: Base64Schema,\n\tsignature: Schema.String,\n});\nexport type SignResponse = Schema.Schema.Type<typeof SignResponseSchema>;\n\n// ----------------------------------------------------------------------\n// Error envelope\n// ----------------------------------------------------------------------\n\n/** Error response body. The HTTP status carries the broad classification\n *  (400/401/403/404/500); `code` carries the narrow phase so callers\n *  can branch programmatically. */\nexport const ErrorResponseSchema = Schema.Struct({\n\terror: Schema.String,\n\tcode: Schema.String,\n});\nexport type ErrorResponse = Schema.Schema.Type<typeof ErrorResponseSchema>;\n\n// Header / token constants are re-exported above from\n// `../../contracts/wallet-protocol.ts`.\n"],"mappings":";;;;;;;;;AA2DA,MAAa,mBAAmB,OAAO,OAAO,MAAM,OAAO,UAAU,sBAAsB,CAAC;;;;AAK5F,MAAa,eAAe,OAAO,OAAO,MAAM,OAAO,UAAU,yBAAyB,CAAC;;;AAI3F,MAAa,wBAAwB,OAAO,MAAM;CACjD,OAAO,QAAQ,UAAU;CACzB,OAAO,QAAQ,YAAY;CAC3B,OAAO,QAAQ,YAAY;CAC3B,CAAC;;;;;AAMF,MAAa,sBAAsB,OAAO,MAAM,CAC/C,OAAO,QAAQ,OAAO,EACtB,OAAO,QAAQ,cAAc,CAC7B,CAAC;AAMkC,OAAO,OAAO,EACjD,IAAI,OAAO,QAAQ,KAAK,EACxB,CAAC;AAGF,MAAa,uBAAuB,OAAO,OAAO;CACjD,MAAM,OAAO;CACb,SAAS;CACT,QAAQ;;;;CAIR,WAAW;CACX,QAAQ;CACR,CAAC;AAGoC,OAAO,OAAO,EACnD,UAAU,OAAO,MAAM,qBAAqB,EAC5C,CAAC;;;;AAUF,MAAa,oBAAoB,OAAO,OAAO;CAC9C,SAAS;CACT,OAAO;CACP,CAAC;AAMgC,OAAO,OAAO;CAC/C,OAAO;CACP,WAAW,OAAO;CAClB,CAAC;AAUiC,OAAO,OAAO;CAChD,OAAO,OAAO;CACd,MAAM,OAAO;CACb,CAAC"}

package/dist/plugins/wallet/routable.mjs

@@ -1,10 +1,4 @@
-//#region src/plugins/wallet/routable.ts
-/** Canonical endpoint name. The router orchestrator surfaces this in
-*  the manifest under `endpoints['wallet-app']`; downstream consumers
-*  (codegen, TUI, doctor) read it by this key.
-*
-*  Stable across rewrite + legacy so existing consumers don't break. */
-const WALLET_ENDPOINT_NAME = "wallet-app";
+import { WALLET_ENDPOINT_NAME } from "../../contracts/wallet-protocol.mjs";
 const WALLET_ENTRYPOINT_PORT = 6173;
 const WALLET_ENTRYPOINTS = [{
 	name: WALLET_ENDPOINT_NAME,
@@ -27,6 +21,6 @@ const makeWalletRoutable = (parts) => ({
 	wireProtocol: "http"
 });
 //#endregion
-export { WALLET_ENDPOINT_NAME, WALLET_ENTRYPOINTS, WALLET_ENTRYPOINT_PORT, makeWalletRoutable };
+export { WALLET_ENTRYPOINTS, WALLET_ENTRYPOINT_PORT, makeWalletRoutable };
 
 //# sourceMappingURL=routable.mjs.map

package/dist/plugins/wallet/routable.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"routable.mjs","names":[],"sources":["../../../src/plugins/wallet/routable.ts"],"sourcesContent":["// Wallet plugin — Routable contribution.\n//\n// The wallet's HTTP server is a HOST PROCESS (not a docker container)\n// listening on a loopback port the substrate's port broker hands us.\n// The router (Traefik) fronts the loopback port under a stack-scoped\n// hostname like `wallet.<app>.localhost:<router-port>`.\n//\n// This contribution is what tells the router about the upstream. The\n// router orchestrator reads the decl, mints the stack-scoped hostname,\n// and writes the file-provider YAML without ever naming the wallet\n// plugin.\n//\n// The wallet always emits this decl. The router is the standard app\n// and wallet entrypoint, while the loopback URL remains an internal\n// fallback for tests and direct host tooling.\n\nimport type { EntrypointDecl, RoutableDecl } from '../../contracts/routable.ts';\n\n// ----------------------------------------------------------------------\n// Endpoint name constant\n// ----------------------------------------------------------------------\n\n/** Canonical endpoint name. The router orchestrator surfaces this in\n *  the manifest under `endpoints['wallet-app']`; downstream consumers\n *  (codegen, TUI, doctor) read it by this key.\n *\n *  Stable across rewrite + legacy so existing consumers don't break. */\nexport const WALLET_ENDPOINT_NAME = 'wallet-app' as const;\nexport const WALLET_ROUTE_ROLE = 'api' as const;\nexport const WALLET_ENTRYPOINT_PORT = 6173;\n\nexport const WALLET_ENTRYPOINTS: ReadonlyArray<EntrypointDecl> = [\n\t{ name: WALLET_ENDPOINT_NAME, port: WALLET_ENTRYPOINT_PORT, protocol: 'http' },\n];\n\n// ----------------------------------------------------------------------\n// Decl\n// ----------------------------------------------------------------------\n\n/** Construct the Routable decl for the stack-scoped wallet endpoint. */\nexport const makeWalletRoutable = (parts: {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly port: number;\n}): RoutableDecl => ({\n\tkind: 'routable',\n\tendpointName: WALLET_ENDPOINT_NAME,\n\tdispatchId: {\n\t\t// Convention: `<plugin>.<app>.<stack>` keeps dispatch-file\n\t\t// listings readable; the router still hashes the full\n\t\t// `(app, stack, serviceKey, role)` tuple for uniqueness.\n\t\tserviceKey: `wallet.${parts.app}.${parts.stack}`,\n\t\trole: WALLET_ROUTE_ROLE,\n\t},\n\tupstream: { type: 'host-loopback', port: parts.port },\n\tcors: true,\n\twireProtocol: 'http',\n});\n"],"mappings":";;;;;;AA2BA,MAAa,uBAAuB;AAEpC,MAAa,yBAAyB;AAEtC,MAAa,qBAAoD,CAChE;CAAE,MAAM;CAAsB,MAAM;CAAwB,UAAU;CAAQ,CAC9E;;AAOD,MAAa,sBAAsB,WAId;CACpB,MAAM;CACN,cAAc;CACd,YAAY;EAIX,YAAY,UAAU,MAAM,IAAI,GAAG,MAAM;EACzC,MAAA;EACA;CACD,UAAU;EAAE,MAAM;EAAiB,MAAM,MAAM;EAAM;CACrD,MAAM;CACN,cAAc;CACd"}
+{"version":3,"file":"routable.mjs","names":[],"sources":["../../../src/plugins/wallet/routable.ts"],"sourcesContent":["// Wallet plugin — Routable contribution.\n//\n// The wallet's HTTP server is a HOST PROCESS (not a docker container)\n// listening on a loopback port the substrate's port broker hands us.\n// The router (Traefik) fronts the loopback port under a stack-scoped\n// hostname like `wallet.<app>.localhost:<router-port>`.\n//\n// This contribution is what tells the router about the upstream. The\n// router orchestrator reads the decl, mints the stack-scoped hostname,\n// and writes the file-provider YAML without ever naming the wallet\n// plugin.\n//\n// The wallet always emits this decl. The router is the standard app\n// and wallet entrypoint, while the loopback URL remains an internal\n// fallback for tests and direct host tooling.\n\nimport type { EntrypointDecl, RoutableDecl } from '../../contracts/routable.ts';\n\n// The routed-endpoint identity constants live in the name-blind\n// contract so L5 build integrations can consume them without importing\n// this L2 plugin module; re-exported here so plugin-internal callers\n// (and the conventional-routes alias table) keep one source of truth.\nexport {\n\tWALLET_ENDPOINT_NAME,\n\tWALLET_ENDPOINT_KEY,\n} from '../../contracts/wallet-protocol.ts';\n\nimport { WALLET_ENDPOINT_NAME } from '../../contracts/wallet-protocol.ts';\n\nexport const WALLET_ROUTE_ROLE = 'api' as const;\nexport const WALLET_ENTRYPOINT_PORT = 6173;\n\nexport const WALLET_ENTRYPOINTS: ReadonlyArray<EntrypointDecl> = [\n\t{ name: WALLET_ENDPOINT_NAME, port: WALLET_ENTRYPOINT_PORT, protocol: 'http' },\n];\n\n// ----------------------------------------------------------------------\n// Decl\n// ----------------------------------------------------------------------\n\n/** Construct the Routable decl for the stack-scoped wallet endpoint. */\nexport const makeWalletRoutable = (parts: {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly port: number;\n}): RoutableDecl => ({\n\tkind: 'routable',\n\tendpointName: WALLET_ENDPOINT_NAME,\n\tdispatchId: {\n\t\t// Convention: `<plugin>.<app>.<stack>` keeps dispatch-file\n\t\t// listings readable; the router still hashes the full\n\t\t// `(app, stack, serviceKey, role)` tuple for uniqueness.\n\t\tserviceKey: `wallet.${parts.app}.${parts.stack}`,\n\t\trole: WALLET_ROUTE_ROLE,\n\t},\n\tupstream: { type: 'host-loopback', port: parts.port },\n\tcors: true,\n\twireProtocol: 'http',\n});\n"],"mappings":";AA8BA,MAAa,yBAAyB;AAEtC,MAAa,qBAAoD,CAChE;CAAE,MAAM;CAAsB,MAAM;CAAwB,UAAU;CAAQ,CAC9E;;AAOD,MAAa,sBAAsB,WAId;CACpB,MAAM;CACN,cAAc;CACd,YAAY;EAIX,YAAY,UAAU,MAAM,IAAI,GAAG,MAAM;EACzC,MAAA;EACA;CACD,UAAU;EAAE,MAAM;EAAiB,MAAM,MAAM;EAAM;CACrD,MAAM;CACN,cAAc;CACd"}

package/dist/plugins/wallet/server.mjs

@@ -1,11 +1,14 @@
-import { decodeJsonText } from "../../substrate/runtime/runtime-decode.mjs";
 import { SpanAttr } from "../../substrate/runtime/observability/spans.mjs";
+import { decodeJsonText } from "../../substrate/runtime/runtime-decode.mjs";
+import { WALLET_AUTH_HEADER, WalletHttpPath } from "../../contracts/wallet-protocol.mjs";
+import { formatUnknownError } from "../../substrate/runtime/format-unknown-error.mjs";
 import { walletBootError, walletRequestError } from "./errors.mjs";
-import { ExecuteRequestSchema, SignRequestSchema, WALLET_AUTH_HEADER, WalletHttpPath } from "./protocol.mjs";
+import { WalletSpans } from "./spans.mjs";
+import { SignRequestSchema } from "./protocol.mjs";
 import { parseBearerHeader, safeBearerEquals } from "./pairing.mjs";
 import { checkOrigin, corsHeadersFor } from "./origin-policy.mjs";
 import { listenScopedHttpServer } from "../../substrate/runtime/scoped-http-server.mjs";
-import { Effect } from "effect";
+import { Cause, Effect } from "effect";
 import { randomUUID } from "node:crypto";
 //#region src/plugins/wallet/server.ts
 /** Body cap — 64 KiB. Above the largest reasonable sign-tx payload,
@@ -53,7 +56,7 @@ const startHttpServer = (config) => Effect.gen(function* () {
 		listener: makeRequestListener(config, runDispatch),
 		onListenError: (cause) => walletBootError({
 			phase: "listen",
-			message: `wallet HTTP server listen failed on ${config.bindAddress}:${config.port} — ` + (cause instanceof Error ? cause.message : String(cause)),
+			message: `wallet HTTP server listen failed on ${config.bindAddress}:${config.port} — ` + formatUnknownError(cause),
 			hint: "check that the port broker did not hand out a busy port; a sibling devstack on the same address would also explain this.",
 			cause
 		})
@@ -107,15 +110,20 @@ const makeRequestListener = (config, runDispatch) => (req, res) => {
 	req.on("end", () => {
 		if (overflowed) return;
 		const body = Buffer.concat(chunks).toString("utf8");
-		runDispatch(dispatch(config, {
+		const walletReq = {
 			method: req.method ?? "GET",
 			url: req.url ?? "/",
 			headers: normalizeHeaders(req.headers),
 			body
-		}).pipe(Effect.matchEffect({
-			onFailure: (cause) => Effect.sync(() => {
-				writeServerError(res, cause);
-			}),
+		};
+		runDispatch(dispatch(config, walletReq).pipe(Effect.matchCauseEffect({
+			onFailure: (cause) => Effect.logError("wallet dispatcher defect").pipe(Effect.annotateLogs({
+				[WalletSpans.requestMethod]: walletReq.method,
+				[WalletSpans.requestUrl]: walletReq.url,
+				cause: Cause.pretty(cause)
+			}), Effect.flatMap(() => Effect.sync(() => {
+				writeServerError(res);
+			}))),
 			onSuccess: (resp) => Effect.sync(() => writeResponse(res, resp))
 		})));
 	});
@@ -132,7 +140,11 @@ const writeOverflow = (res) => {
 	res.setHeader("content-type", "text/plain; charset=utf-8");
 	res.end("payload too large");
 };
-const writeServerError = (res, cause) => {
+/** Write an opaque 500 — no token, no internal state leak. The
+*  caller is responsible for logging the underlying cause (see the
+*  `Effect.logError('wallet dispatcher defect')` in `dispatch`'s
+*  `matchCauseEffect` onFailure branch). */
+const writeServerError = (res) => {
 	if (res.writableEnded) return;
 	res.statusCode = 500;
 	res.setHeader("content-type", "application/json; charset=utf-8");
@@ -174,10 +186,12 @@ const text = (status, body, extraHeaders = {}) => ({
 * are projected to JSON envelopes via `errorEnvelope` below.
 *
 * The dispatch order matters:
-*   1. OPTIONS preflight (returns 204 + CORS) — no auth required.
-*   2. Path-prefix gate — anything not under `/api/v1/devstack/` is
-*      a flat 404 (text/plain). PROTECTS the auth gate from being
-*      visible on arbitrary URLs.
+*   1. Path-prefix gate — anything not under `/api/v1/devstack/` is
+*      a flat 404 (text/plain). PROTECTS the auth gate (and the CORS
+*      preflight) from being visible on arbitrary URLs.
+*   2. OPTIONS preflight (returns 204 + CORS) — no auth required, but
+*      scoped to the protocol prefix by step 1 so an allowed origin
+*      cannot extract CORS headers for unrelated paths.
 *   3. Origin check (must be in policy.allowed; missing → 403).
 *   4. Bearer check (must constant-time-equal `config.token`).
 *   5. Method+path route to handler.
@@ -185,10 +199,12 @@ const text = (status, body, extraHeaders = {}) => ({
 const dispatch = (config, req) => Effect.gen(function* () {
 	const requestId = randomUUID();
 	yield* Effect.annotateCurrentSpan({
-		"wallet.request.id": requestId,
-		"wallet.request.method": req.method,
-		"wallet.request.url": req.url
+		[WalletSpans.requestId]: requestId,
+		[WalletSpans.requestMethod]: req.method,
+		[WalletSpans.requestUrl]: req.url
 	});
+	const path = req.url.split("?")[0] ?? "";
+	if (!path.startsWith("/api/v1/devstack/")) return text(404, "not found");
 	if (req.method === "OPTIONS") {
 		const origin = req.headers["origin"];
 		if (origin !== void 0 && config.policy.allowed.has(origin)) return {
@@ -198,8 +214,6 @@ const dispatch = (config, req) => Effect.gen(function* () {
 		};
 		return text(403, "forbidden origin");
 	}
-	const path = req.url.split("?")[0] ?? "";
-	if (!path.startsWith("/api/v1/devstack/")) return text(404, "not found");
 	const originResult = checkOrigin(config.policy, req.headers["origin"]);
 	if (originResult === "missing") {
 		yield* Effect.logWarning("wallet origin missing").pipe(Effect.annotateLogs({
@@ -212,7 +226,7 @@ const dispatch = (config, req) => Effect.gen(function* () {
 	if (originResult === "forbidden") {
 		yield* Effect.logWarning("wallet origin forbidden").pipe(Effect.annotateLogs({
 			[SpanAttr.requestId]: requestId,
-			[SpanAttr.walletOrigin]: req.headers.origin ?? "(missing)",
+			[WalletSpans.origin]: req.headers.origin ?? "(missing)",
 			[SpanAttr.httpMethod]: req.method,
 			[SpanAttr.httpPath]: path
 		}));
@@ -221,11 +235,11 @@ const dispatch = (config, req) => Effect.gen(function* () {
 	const origin = req.headers["origin"];
 	const bearer = parseBearerHeader(req.headers[WALLET_AUTH_HEADER]);
 	const bearerValid = bearer !== null && safeBearerEquals(bearer, config.token);
-	yield* Effect.annotateCurrentSpan({ [SpanAttr.walletBearerValid]: bearerValid });
+	yield* Effect.annotateCurrentSpan({ [WalletSpans.bearerValid]: bearerValid });
 	if (!bearerValid) {
 		yield* Effect.logWarning("wallet bearer check failed").pipe(Effect.annotateLogs({
 			[SpanAttr.requestId]: requestId,
-			[SpanAttr.walletBearerValid]: bearerValid,
+			[WalletSpans.bearerValid]: bearerValid,
 			[SpanAttr.httpMethod]: req.method,
 			[SpanAttr.httpPath]: path
 		}));
@@ -243,7 +257,6 @@ const routeRequest = (config, req, path, corsHdr) => {
 	if (req.method === "GET" && path === WalletHttpPath.ACCOUNTS) return handleAccounts(config, corsHdr);
 	if (req.method === "POST" && path === WalletHttpPath.SIGN_TRANSACTION) return handleSign(config, req, "transaction", corsHdr);
 	if (req.method === "POST" && path === WalletHttpPath.SIGN_PERSONAL_MESSAGE) return handleSign(config, req, "personal-message", corsHdr);
-	if (req.method === "POST" && path === WalletHttpPath.EXECUTE) return handleExecute(config, req, corsHdr);
 	return Effect.fail(walletRequestError({
 		phase: "route-not-found",
 		httpStatus: 404,
@@ -260,11 +273,6 @@ const handleAccounts = (config, corsHdr) => Effect.sync(() => {
 	})) }, corsHdr);
 });
 const decodeJsonBody = (schema, body) => Effect.gen(function* () {
-	if (body.length > 65536) return yield* Effect.fail(walletRequestError({
-		phase: "body-invalid",
-		httpStatus: 400,
-		message: `body exceeds ${MAX_BODY_BYTES}-byte cap`
-	}));
 	return yield* decodeJsonText(schema, body, {
 		source: "wallet request body",
 		mkError: (issue) => walletRequestError({
@@ -291,22 +299,6 @@ const handleSign = (config, req, kind, corsHdr) => Effect.gen(function* () {
 		cause
 	}))), corsHdr);
 });
-const handleExecute = (config, req, corsHdr) => Effect.gen(function* () {
-	const body = yield* decodeJsonBody(ExecuteRequestSchema, req.body);
-	const account = config.accountsByAddress.get(body.address);
-	if (account === void 0) return yield* Effect.fail(walletRequestError({
-		phase: "address-not-found",
-		httpStatus: 404,
-		message: `no account for address '${body.address}'`
-	}));
-	const bytes = Buffer.from(body.bytes, "base64");
-	return json(200, yield* account.signAndExecute(bytes).pipe(Effect.mapError((cause) => walletRequestError({
-		phase: "sign-route-failed",
-		httpStatus: 500,
-		message: "signAndExecute failed",
-		cause
-	}))), corsHdr);
-});
 const errorEnvelope = (err, corsHdr) => json(err.httpStatus, {
 	error: err.message,
 	code: err.phase