@mysten-incubation/devstack 0.0.1 → 0.1.0

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

@@ -1 +1 @@
-{"version":3,"file":"server.mjs","names":[],"sources":["../../../src/plugins/wallet/server.ts"],"sourcesContent":["// Wallet plugin — in-process HTTP server.\n//\n// Responsibilities:\n//\n//   1. Bind a `node:http` server on a substrate-allocated port (the\n//      port broker hands the port in; we don't pick it here).\n//   2. Dispatch by `(METHOD, path)` to the four handlers below\n//      (health, accounts, sign-transaction, sign-personal-message,\n//      execute).\n//   3. Enforce the auth gate: mandatory Origin in policy.allowed +\n//      constant-time bearer compare.\n//   4. Body-cap enforcement: 64 KiB before buffering — protects the\n//      supervisor from OOM via streaming payloads.\n//   5. Per-request span + log annotation under the captured\n//      supervisor context — so handler errors hit the TUI logger\n//      sink instead of bare stderr.\n//   6. Scope-finalizer teardown: `closeAllConnections()` →\n//      `close()` awaited → port release (the substrate's scope\n//      finalizer chain handles release; we just close).\n//\n// Wiring status (15-wallet.md alignment): both the per-route handler\n// bodies (auth + decode + dispatch to `AccountValue` sign closures)\n// AND the in-process `node:http.Server` listen loop are real. The\n// listener buffers each request body up to `MAX_BODY_BYTES`, forks the\n// dispatcher Effect under the captured supervisor context (so handler\n// logs flow to the TUI logger sink), while the substrate scoped HTTP\n// listener owns bind/close lifecycle.\n\nimport { Context, Effect, Schema } from 'effect';\nimport type { Scope } from 'effect';\nimport { randomUUID } from 'node:crypto';\nimport type { IncomingMessage, ServerResponse } from 'node:http';\n\nimport { listenScopedHttpServer } from '../../substrate/runtime/scoped-http-server.ts';\nimport { SpanAttr } from '../../substrate/runtime/observability/spans.ts';\nimport { decodeJsonText } from '../../substrate/runtime/runtime-decode.ts';\nimport type { AccountValue } from '../account/service.ts';\nimport {\n\twalletBootError,\n\twalletRequestError,\n\ttype WalletBootError,\n\ttype WalletRequestError,\n} from './errors.ts';\nimport { checkOrigin, corsHeadersFor, type OriginPolicy } from './origin-policy.ts';\nimport { parseBearerHeader, safeBearerEquals, type PairingToken } from './pairing.ts';\nimport {\n\tAccountsResponseSchema,\n\tExecuteRequestSchema,\n\tHealthResponseSchema,\n\tSignRequestSchema,\n\tSignResponseSchema,\n\tWALLET_AUTH_HEADER,\n\tWALLET_PROTOCOL_PREFIX,\n\tWalletHttpPath,\n\ttype AccountSummary,\n} from './protocol.ts';\n\n// ----------------------------------------------------------------------\n// Server config + handle\n// ----------------------------------------------------------------------\n\n/** Inputs the substrate hands to `startHttpServer`. The plugin's\n *  acquire body builds this from its resolved inputs (port broker,\n *  origin policy, accounts map, token). */\nexport interface WalletServerConfig {\n\treadonly bindAddress: string;\n\treadonly port: number;\n\treadonly token: PairingToken;\n\treadonly policy: OriginPolicy;\n\treadonly accountsByAddress: ReadonlyMap<string, AccountValue>;\n\t/** Captured supervisor context — handler errors log under this so\n\t *  the TUI logger sink receives them. Stub: the substrate primitive\n\t *  will hand this in; today the field is opaque. */\n\treadonly supervisorCtx: unknown;\n}\n\n/** Opaque server handle. The substrate's scope finalizer chain\n *  invokes `.close()`; callers don't dispatch into it directly. */\nexport interface WalletServerHandle {\n\treadonly url: string; // direct loopback URL — `http://<bindAddress>:<port>`\n\treadonly close: () => Effect.Effect<void>;\n}\n\n/** Body cap — 64 KiB. Above the largest reasonable sign-tx payload,\n *  well below any OOM threshold. */\nexport const MAX_BODY_BYTES = 64 * 1024;\n\n// ----------------------------------------------------------------------\n// Top-level boot\n// ----------------------------------------------------------------------\n\n/** Per-request socket-level timeout, milliseconds. Caps the time a\n *  malicious / hung peer can hold an idle connection. */\nconst REQUEST_SOCKET_TIMEOUT_MS = 30_000;\n\n/**\n * Boot the wallet HTTP server.\n *\n * Wires `node:http.createServer` against the dispatcher. Listens on\n * `bindAddress:port` (the substrate's port broker chose `port` upstream\n * of this call). The scope finalizer awaits graceful close on teardown\n * — `closeAllConnections()` followed by `close()` with await.\n *\n *  Request flow (per connection):\n *\n *    1. `request` listener fires with `IncomingMessage`+`ServerResponse`.\n *    2. We buffer the request body up to `MAX_BODY_BYTES`. If the\n *       inbound payload exceeds the cap, the socket is destroyed and\n *       a 413 returned without ever invoking the dispatcher (closes the\n *       supervisor-OOM path).\n *    3. Construct a `WalletRequest` from the buffered body + headers.\n *    4. `Effect.runForkWith(supervisorContext)(dispatch(config, req))`\n *       — captured at acquire time so handler logs/spans flow to the\n *       TUI logger sink.\n *    5. On fiber completion, write status + headers + body to `res`.\n *    6. On uncaught exception in the listener path: 500 with an opaque\n *       message (no token leak, no internal-state leak).\n *\n *  Scope finalizer:\n *\n *    Calls `server.closeAllConnections()` (kills idle keepalive\n *    sockets) then awaits `server.close()` (drains in-flight). The\n *    finalizer is uninterruptible so a Ctrl-C double-tap doesn't\n *    leave the socket dangling.\n */\nexport const startHttpServer = (\n\tconfig: WalletServerConfig,\n): Effect.Effect<WalletServerHandle, WalletBootError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\t// Capture the supervisor context so handler fibers run with the\n\t\t// same Logger / span sinks as the rest of the stack. The\n\t\t// dispatcher's R-channel is `never`, but capturing the context\n\t\t// keeps fiber-refs (logger, spans) flowing.\n\t\tconst supervisorContext = yield* Effect.context<never>();\n\t\tconst runDispatch = Effect.runForkWith(supervisorContext as Context.Context<never>);\n\n\t\tconst handle = yield* listenScopedHttpServer({\n\t\t\tbindAddress: config.bindAddress,\n\t\t\tport: config.port,\n\t\t\tlistener: makeRequestListener(config, runDispatch),\n\t\t\tonListenError: (cause): WalletBootError =>\n\t\t\t\twalletBootError({\n\t\t\t\t\tphase: 'listen',\n\t\t\t\t\tmessage:\n\t\t\t\t\t\t`wallet HTTP server listen failed on ${config.bindAddress}:${config.port} — ` +\n\t\t\t\t\t\t(cause instanceof Error ? cause.message : String(cause)),\n\t\t\t\t\thint:\n\t\t\t\t\t\t'check that the port broker did not hand out a busy port; ' +\n\t\t\t\t\t\t'a sibling devstack on the same address would also explain this.',\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t});\n\n\t\tyield* Effect.logInfo('wallet HTTP server listening').pipe(\n\t\t\tEffect.annotateLogs({\n\t\t\t\t[SpanAttr.host]: config.bindAddress,\n\t\t\t\t[SpanAttr.port]: config.port,\n\t\t\t}),\n\t\t);\n\n\t\treturn {\n\t\t\turl: handle.url,\n\t\t\tclose: handle.close,\n\t\t} satisfies WalletServerHandle;\n\t});\n\n// ----------------------------------------------------------------------\n// Node request listener — bridges `node:http` → dispatcher Effect\n// ----------------------------------------------------------------------\n\n/**\n * Build the `(req, res)` listener Node hands to `http.createServer`.\n *\n * The listener:\n *\n *   - Buffers the request body up to `MAX_BODY_BYTES`. Over-cap →\n *     413 + socket destroyed (the dispatcher's body-cap check is the\n *     second line of defense; this one is the first).\n *   - Drops invalid socket-level errors silently (defensive: the\n *     wallet is loopback-only, but a malformed HTTP/1.1 line shouldn't\n *     crash the supervisor).\n *   - Forks the dispatcher Effect via the captured supervisor runtime.\n *   - Writes the resolved `WalletResponse` back to `res`.\n *\n * Returns void (Node listener signature) — all error reporting flows\n * through the dispatcher (request errors) or `Effect.logError` (boot/\n * listener path errors).\n */\nconst makeRequestListener =\n\t(\n\t\tconfig: WalletServerConfig,\n\t\trunDispatch: <A, E>(effect: Effect.Effect<A, E, never>) => unknown,\n\t): ((req: IncomingMessage, res: ServerResponse) => void) =>\n\t(req, res) => {\n\t\t// Socket-level timeout — protects against hung peers parking\n\t\t// requests on the supervisor's loopback.\n\t\treq.socket.setTimeout(REQUEST_SOCKET_TIMEOUT_MS);\n\n\t\tconst chunks: Buffer[] = [];\n\t\tlet totalBytes = 0;\n\t\tlet overflowed = false;\n\n\t\treq.on('data', (chunk: Buffer) => {\n\t\t\tif (overflowed) return;\n\t\t\ttotalBytes += chunk.length;\n\t\t\tif (totalBytes > MAX_BODY_BYTES) {\n\t\t\t\toverflowed = true;\n\t\t\t\twriteOverflow(res);\n\t\t\t\ttry {\n\t\t\t\t\treq.destroy();\n\t\t\t\t} catch {\n\t\t\t\t\t/* defensive */\n\t\t\t\t}\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tchunks.push(chunk);\n\t\t});\n\n\t\treq.on('error', () => {\n\t\t\t// Socket-level error — drop. Per-request errors are handled\n\t\t\t// inside the dispatcher.\n\t\t});\n\n\t\treq.on('end', () => {\n\t\t\tif (overflowed) return;\n\t\t\tconst body = Buffer.concat(chunks).toString('utf8');\n\t\t\tconst walletReq: WalletRequest = {\n\t\t\t\tmethod: req.method ?? 'GET',\n\t\t\t\turl: req.url ?? '/',\n\t\t\t\theaders: normalizeHeaders(req.headers),\n\t\t\t\tbody,\n\t\t\t};\n\t\t\tconst program = dispatch(config, walletReq).pipe(\n\t\t\t\tEffect.matchEffect({\n\t\t\t\t\tonFailure: (cause) =>\n\t\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\t\t// `dispatch` is typed `Effect<WalletResponse>` (no\n\t\t\t\t\t\t\t// failure channel); a thrown defect lands here as a\n\t\t\t\t\t\t\t// `Cause`. Log + write a 500.\n\t\t\t\t\t\t\twriteServerError(res, cause);\n\t\t\t\t\t\t}),\n\t\t\t\t\tonSuccess: (resp) => Effect.sync(() => writeResponse(res, resp)),\n\t\t\t\t}),\n\t\t\t);\n\t\t\trunDispatch(program);\n\t\t});\n\t};\n\nconst writeResponse = (res: ServerResponse, resp: WalletResponse): void => {\n\tif (res.writableEnded) return;\n\tres.statusCode = resp.status;\n\tfor (const [k, v] of Object.entries(resp.headers)) {\n\t\tres.setHeader(k, v);\n\t}\n\tres.end(resp.body);\n};\n\nconst writeOverflow = (res: ServerResponse): void => {\n\tif (res.writableEnded) return;\n\tres.statusCode = 413;\n\tres.setHeader('content-type', 'text/plain; charset=utf-8');\n\tres.end('payload too large');\n};\n\nconst writeServerError = (res: ServerResponse, cause: unknown): void => {\n\tif (res.writableEnded) return;\n\tres.statusCode = 500;\n\tres.setHeader('content-type', 'application/json; charset=utf-8');\n\t// Opaque error body — no token, no internal state leak.\n\tres.end(\n\t\tJSON.stringify({\n\t\t\terror: 'internal error',\n\t\t\tcode: 'internal-error',\n\t\t}),\n\t);\n\tvoid cause; // surfaces via Effect.logError on the dispatcher path\n};\n\n/** Normalize Node's `IncomingHttpHeaders` (string | string[] | undefined)\n *  to the `WalletRequest.headers` shape (string | undefined). Picks the\n *  first value for repeated headers — matches browser send semantics\n *  for the headers we care about (Origin, Authorization, Content-Type). */\nconst normalizeHeaders = (\n\theaders: IncomingMessage['headers'],\n): Readonly<Record<string, string | undefined>> => {\n\tconst out: Record<string, string | undefined> = {};\n\tfor (const [k, v] of Object.entries(headers)) {\n\t\tif (v === undefined) {\n\t\t\tout[k] = undefined;\n\t\t} else if (Array.isArray(v)) {\n\t\t\tout[k] = v[0];\n\t\t} else {\n\t\t\tout[k] = v;\n\t\t}\n\t}\n\treturn out;\n};\n\n// ----------------------------------------------------------------------\n// Dispatcher — pure(ish) function from request → effect\n// ----------------------------------------------------------------------\n\n/** Inbound request shape — substrate-runtime-agnostic. The substrate's\n *  http-server primitive converts a `node:http` IncomingMessage into\n *  this; tests can construct it directly. */\nexport interface WalletRequest {\n\treadonly method: string;\n\treadonly url: string; // path + query, no host\n\treadonly headers: Readonly<Record<string, string | undefined>>;\n\treadonly body: string; // already-buffered (capped at MAX_BODY_BYTES)\n}\n\n/** Outbound response. */\nexport interface WalletResponse {\n\treadonly status: number;\n\treadonly headers: Readonly<Record<string, string>>;\n\treadonly body: string;\n}\n\nconst json = (\n\tstatus: number,\n\tbody: unknown,\n\textraHeaders: Readonly<Record<string, string>> = {},\n): WalletResponse => ({\n\tstatus,\n\theaders: { 'content-type': 'application/json; charset=utf-8', ...extraHeaders },\n\tbody: JSON.stringify(body),\n});\n\nconst text = (\n\tstatus: number,\n\tbody: string,\n\textraHeaders: Readonly<Record<string, string>> = {},\n): WalletResponse => ({\n\tstatus,\n\theaders: { 'content-type': 'text/plain; charset=utf-8', ...extraHeaders },\n\tbody,\n});\n\n/**\n * Dispatch a single request to its handler. Returns an Effect that\n * always succeeds (the response is built); request-level failures\n * are projected to JSON envelopes via `errorEnvelope` below.\n *\n * The dispatch order matters:\n *   1. OPTIONS preflight (returns 204 + CORS) — no auth required.\n *   2. Path-prefix gate — anything not under `/api/v1/devstack/` is\n *      a flat 404 (text/plain). PROTECTS the auth gate from being\n *      visible on arbitrary URLs.\n *   3. Origin check (must be in policy.allowed; missing → 403).\n *   4. Bearer check (must constant-time-equal `config.token`).\n *   5. Method+path route to handler.\n */\nexport const dispatch = (\n\tconfig: WalletServerConfig,\n\treq: WalletRequest,\n): Effect.Effect<WalletResponse> =>\n\tEffect.gen(function* () {\n\t\tconst requestId = randomUUID();\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'wallet.request.id': requestId,\n\t\t\t'wallet.request.method': req.method,\n\t\t\t'wallet.request.url': req.url,\n\t\t});\n\n\t\t// 1. OPTIONS preflight — no auth check, but the origin still has\n\t\t//    to be in the allowlist so we don't leak CORS headers to\n\t\t//    arbitrary callers.\n\t\tif (req.method === 'OPTIONS') {\n\t\t\tconst origin = req.headers['origin'];\n\t\t\tif (origin !== undefined && config.policy.allowed.has(origin)) {\n\t\t\t\treturn { status: 204, headers: corsHeadersFor(origin), body: '' };\n\t\t\t}\n\t\t\treturn text(403, 'forbidden origin');\n\t\t}\n\n\t\t// 2. Path-prefix gate.\n\t\tconst path = req.url.split('?')[0] ?? '';\n\t\tif (!path.startsWith(WALLET_PROTOCOL_PREFIX)) {\n\t\t\treturn text(404, 'not found');\n\t\t}\n\n\t\t// 3. Origin check.\n\t\tconst originResult = checkOrigin(config.policy, req.headers['origin']);\n\t\tif (originResult === 'missing') {\n\t\t\t// Log the BEARER-VALIDITY only, never the token itself.\n\t\t\tyield* Effect.logWarning('wallet origin missing').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.requestId]: requestId,\n\t\t\t\t\t[SpanAttr.httpMethod]: req.method,\n\t\t\t\t\t[SpanAttr.httpPath]: path,\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn text(403, 'Origin header required');\n\t\t}\n\t\tif (originResult === 'forbidden') {\n\t\t\tyield* Effect.logWarning('wallet origin forbidden').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.requestId]: requestId,\n\t\t\t\t\t[SpanAttr.walletOrigin]: req.headers.origin ?? '(missing)',\n\t\t\t\t\t[SpanAttr.httpMethod]: req.method,\n\t\t\t\t\t[SpanAttr.httpPath]: path,\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn text(403, 'forbidden origin');\n\t\t}\n\t\tconst origin = req.headers['origin']!;\n\n\t\t// 4. Bearer check. Token never appears in log lines — only the\n\t\t//    boolean validity.\n\t\tconst bearer = parseBearerHeader(req.headers[WALLET_AUTH_HEADER]);\n\t\tconst bearerValid = bearer !== null && safeBearerEquals(bearer, config.token);\n\t\tyield* Effect.annotateCurrentSpan({ [SpanAttr.walletBearerValid]: bearerValid });\n\t\tif (!bearerValid) {\n\t\t\tyield* Effect.logWarning('wallet bearer check failed').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.requestId]: requestId,\n\t\t\t\t\t[SpanAttr.walletBearerValid]: bearerValid,\n\t\t\t\t\t[SpanAttr.httpMethod]: req.method,\n\t\t\t\t\t[SpanAttr.httpPath]: path,\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn errorEnvelope(\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'unauthorized',\n\t\t\t\t\thttpStatus: 401,\n\t\t\t\t\tmessage: 'unauthorized',\n\t\t\t\t}),\n\t\t\t\tcorsHeadersFor(origin),\n\t\t\t);\n\t\t}\n\n\t\t// 5. Route.\n\t\tconst corsHdr = corsHeadersFor(origin);\n\t\treturn yield* routeRequest(config, req, path, corsHdr).pipe(\n\t\t\tEffect.catchTag('WalletRequestError', (err) => Effect.succeed(errorEnvelope(err, corsHdr))),\n\t\t);\n\t});\n\n// ----------------------------------------------------------------------\n// Routing\n// ----------------------------------------------------------------------\n\nconst routeRequest = (\n\tconfig: WalletServerConfig,\n\treq: WalletRequest,\n\tpath: string,\n\tcorsHdr: Readonly<Record<string, string>>,\n): Effect.Effect<WalletResponse, WalletRequestError> => {\n\tif (req.method === 'GET' && path === WalletHttpPath.HEALTH) {\n\t\treturn Effect.succeed(\n\t\t\tjson(200, { ok: true } satisfies Schema.Schema.Type<typeof HealthResponseSchema>, corsHdr),\n\t\t);\n\t}\n\tif (req.method === 'GET' && path === WalletHttpPath.ACCOUNTS) {\n\t\treturn handleAccounts(config, corsHdr);\n\t}\n\tif (req.method === 'POST' && path === WalletHttpPath.SIGN_TRANSACTION) {\n\t\treturn handleSign(config, req, 'transaction', corsHdr);\n\t}\n\tif (req.method === 'POST' && path === WalletHttpPath.SIGN_PERSONAL_MESSAGE) {\n\t\treturn handleSign(config, req, 'personal-message', corsHdr);\n\t}\n\tif (req.method === 'POST' && path === WalletHttpPath.EXECUTE) {\n\t\treturn handleExecute(config, req, corsHdr);\n\t}\n\treturn Effect.fail(\n\t\twalletRequestError({\n\t\t\tphase: 'route-not-found',\n\t\t\thttpStatus: 404,\n\t\t\tmessage: `no route for ${req.method} ${path}`,\n\t\t}),\n\t);\n};\n\n// ----------------------------------------------------------------------\n// Handlers\n// ----------------------------------------------------------------------\n\nconst handleAccounts = (\n\tconfig: WalletServerConfig,\n\tcorsHdr: Readonly<Record<string, string>>,\n): Effect.Effect<WalletResponse, WalletRequestError> =>\n\tEffect.sync(() => {\n\t\tconst accounts: ReadonlyArray<AccountSummary> = Array.from(\n\t\t\tconfig.accountsByAddress.values(),\n\t\t).map((acct) => ({\n\t\t\tname: acct.name,\n\t\t\taddress: acct.address,\n\t\t\tscheme: acct.scheme,\n\t\t\tpublicKey: Buffer.from(acct.publicKey).toString('base64'),\n\t\t\tsource: acct.source,\n\t\t}));\n\t\t// Schema-validate the response so a drift between AccountValue\n\t\t// and the wire envelope blows up at the boundary rather than at\n\t\t// the browser-side decode.\n\t\tconst validated: Schema.Schema.Type<typeof AccountsResponseSchema> = { accounts };\n\t\treturn json(200, validated, corsHdr);\n\t});\n\nconst decodeJsonBody = <A>(\n\tschema: Schema.Schema<A>,\n\tbody: string,\n): Effect.Effect<A, WalletRequestError> =>\n\tEffect.gen(function* () {\n\t\tif (body.length > MAX_BODY_BYTES) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'body-invalid',\n\t\t\t\t\thttpStatus: 400,\n\t\t\t\t\tmessage: `body exceeds ${MAX_BODY_BYTES}-byte cap`,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\treturn yield* decodeJsonText(schema as Schema.Decoder<unknown>, body, {\n\t\t\tsource: 'wallet request body',\n\t\t\tmkError: (issue) =>\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'body-invalid',\n\t\t\t\t\thttpStatus: 400,\n\t\t\t\t\tmessage:\n\t\t\t\t\t\tissue.message === 'failed to parse JSON'\n\t\t\t\t\t\t\t? 'invalid JSON body'\n\t\t\t\t\t\t\t: 'request body did not match schema',\n\t\t\t\t\tcause: issue.cause,\n\t\t\t\t}),\n\t\t}) as Effect.Effect<A, WalletRequestError>;\n\t});\n\nconst handleSign = (\n\tconfig: WalletServerConfig,\n\treq: WalletRequest,\n\tkind: 'transaction' | 'personal-message',\n\tcorsHdr: Readonly<Record<string, string>>,\n): Effect.Effect<WalletResponse, WalletRequestError> =>\n\tEffect.gen(function* () {\n\t\tconst body = yield* decodeJsonBody(SignRequestSchema, req.body);\n\t\tconst account = config.accountsByAddress.get(body.address);\n\t\tif (account === undefined) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'address-not-found',\n\t\t\t\t\thttpStatus: 404,\n\t\t\t\t\tmessage: `no account for address '${body.address}'`,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst bytes = Buffer.from(body.bytes, 'base64');\n\t\tconst signed = yield* (\n\t\t\tkind === 'transaction' ? account.signTransaction(bytes) : account.signPersonalMessage(bytes)\n\t\t).pipe(\n\t\t\tEffect.mapError((cause) =>\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'sign-route-failed',\n\t\t\t\t\thttpStatus: 500,\n\t\t\t\t\tmessage: `${kind === 'transaction' ? 'signTransaction' : 'signPersonalMessage'} failed`,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t\tconst resp: Schema.Schema.Type<typeof SignResponseSchema> = signed;\n\t\treturn json(200, resp, corsHdr);\n\t});\n\nconst handleExecute = (\n\tconfig: WalletServerConfig,\n\treq: WalletRequest,\n\tcorsHdr: Readonly<Record<string, string>>,\n): Effect.Effect<WalletResponse, WalletRequestError> =>\n\tEffect.gen(function* () {\n\t\tconst body = yield* decodeJsonBody(ExecuteRequestSchema, req.body);\n\t\tconst account = config.accountsByAddress.get(body.address);\n\t\tif (account === undefined) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'address-not-found',\n\t\t\t\t\thttpStatus: 404,\n\t\t\t\t\tmessage: `no account for address '${body.address}'`,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst bytes = Buffer.from(body.bytes, 'base64');\n\t\tconst result = yield* account.signAndExecute(bytes).pipe(\n\t\t\tEffect.mapError((cause) =>\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'sign-route-failed',\n\t\t\t\t\thttpStatus: 500,\n\t\t\t\t\tmessage: 'signAndExecute failed',\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t\treturn json(200, result, corsHdr);\n\t});\n\n// ----------------------------------------------------------------------\n// Error envelope\n// ----------------------------------------------------------------------\n\nconst errorEnvelope = (\n\terr: WalletRequestError,\n\tcorsHdr: Readonly<Record<string, string>>,\n): WalletResponse => json(err.httpStatus, { error: err.message, code: err.phase }, corsHdr);\n"],"mappings":";;;;;;;;;;;;AAqFA,MAAa,iBAAiB,KAAK;;;AAQnC,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgClC,MAAa,mBACZ,WAEA,OAAO,IAAI,aAAa;CAKvB,MAAM,oBAAoB,OAAO,OAAO,SAAgB;CACxD,MAAM,cAAc,OAAO,YAAY,kBAA4C;CAEnF,MAAM,SAAS,OAAO,uBAAuB;EAC5C,aAAa,OAAO;EACpB,MAAM,OAAO;EACb,UAAU,oBAAoB,QAAQ,YAAY;EAClD,gBAAgB,UACf,gBAAgB;GACf,OAAO;GACP,SACC,uCAAuC,OAAO,YAAY,GAAG,OAAO,KAAK,QACxE,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;GACxD,MACC;GAED;GACA,CAAC;EACH,CAAC;AAEF,QAAO,OAAO,QAAQ,+BAA+B,CAAC,KACrD,OAAO,aAAa;GAClB,SAAS,OAAO,OAAO;GACvB,SAAS,OAAO,OAAO;EACxB,CAAC,CACF;AAED,QAAO;EACN,KAAK,OAAO;EACZ,OAAO,OAAO;EACd;EACA;;;;;;;;;;;;;;;;;;;AAwBH,MAAM,uBAEJ,QACA,iBAEA,KAAK,QAAQ;AAGb,KAAI,OAAO,WAAW,0BAA0B;CAEhD,MAAM,SAAmB,EAAE;CAC3B,IAAI,aAAa;CACjB,IAAI,aAAa;AAEjB,KAAI,GAAG,SAAS,UAAkB;AACjC,MAAI,WAAY;AAChB,gBAAc,MAAM;AACpB,MAAI,aAAA,OAA6B;AAChC,gBAAa;AACb,iBAAc,IAAI;AAClB,OAAI;AACH,QAAI,SAAS;WACN;AAGR;;AAED,SAAO,KAAK,MAAM;GACjB;AAEF,KAAI,GAAG,eAAe,GAGpB;AAEF,KAAI,GAAG,aAAa;AACnB,MAAI,WAAY;EAChB,MAAM,OAAO,OAAO,OAAO,OAAO,CAAC,SAAS,OAAO;AAmBnD,cAZgB,SAAS,QAAQ;GALhC,QAAQ,IAAI,UAAU;GACtB,KAAK,IAAI,OAAO;GAChB,SAAS,iBAAiB,IAAI,QAAQ;GACtC;GAEyC,CAAC,CAAC,KAC3C,OAAO,YAAY;GAClB,YAAY,UACX,OAAO,WAAW;AAIjB,qBAAiB,KAAK,MAAM;KAC3B;GACH,YAAY,SAAS,OAAO,WAAW,cAAc,KAAK,KAAK,CAAC;GAChE,CAAC,CAEgB,CAAC;GACnB;;AAGJ,MAAM,iBAAiB,KAAqB,SAA+B;AAC1E,KAAI,IAAI,cAAe;AACvB,KAAI,aAAa,KAAK;AACtB,MAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,KAAK,QAAQ,CAChD,KAAI,UAAU,GAAG,EAAE;AAEpB,KAAI,IAAI,KAAK,KAAK;;AAGnB,MAAM,iBAAiB,QAA8B;AACpD,KAAI,IAAI,cAAe;AACvB,KAAI,aAAa;AACjB,KAAI,UAAU,gBAAgB,4BAA4B;AAC1D,KAAI,IAAI,oBAAoB;;AAG7B,MAAM,oBAAoB,KAAqB,UAAyB;AACvE,KAAI,IAAI,cAAe;AACvB,KAAI,aAAa;AACjB,KAAI,UAAU,gBAAgB,kCAAkC;AAEhE,KAAI,IACH,KAAK,UAAU;EACd,OAAO;EACP,MAAM;EACN,CAAC,CACF;;;;;;AAQF,MAAM,oBACL,YACkD;CAClD,MAAM,MAA0C,EAAE;AAClD,MAAK,MAAM,CAAC,GAAG,MAAM,OAAO,QAAQ,QAAQ,CAC3C,KAAI,MAAM,KAAA,EACT,KAAI,KAAK,KAAA;UACC,MAAM,QAAQ,EAAE,CAC1B,KAAI,KAAK,EAAE;KAEX,KAAI,KAAK;AAGX,QAAO;;AAwBR,MAAM,QACL,QACA,MACA,eAAiD,EAAE,MAC9B;CACrB;CACA,SAAS;EAAE,gBAAgB;EAAmC,GAAG;EAAc;CAC/E,MAAM,KAAK,UAAU,KAAK;CAC1B;AAED,MAAM,QACL,QACA,MACA,eAAiD,EAAE,MAC9B;CACrB;CACA,SAAS;EAAE,gBAAgB;EAA6B,GAAG;EAAc;CACzE;CACA;;;;;;;;;;;;;;;AAgBD,MAAa,YACZ,QACA,QAEA,OAAO,IAAI,aAAa;CACvB,MAAM,YAAY,YAAY;AAC9B,QAAO,OAAO,oBAAoB;EACjC,qBAAqB;EACrB,yBAAyB,IAAI;EAC7B,sBAAsB,IAAI;EAC1B,CAAC;AAKF,KAAI,IAAI,WAAW,WAAW;EAC7B,MAAM,SAAS,IAAI,QAAQ;AAC3B,MAAI,WAAW,KAAA,KAAa,OAAO,OAAO,QAAQ,IAAI,OAAO,CAC5D,QAAO;GAAE,QAAQ;GAAK,SAAS,eAAe,OAAO;GAAE,MAAM;GAAI;AAElE,SAAO,KAAK,KAAK,mBAAmB;;CAIrC,MAAM,OAAO,IAAI,IAAI,MAAM,IAAI,CAAC,MAAM;AACtC,KAAI,CAAC,KAAK,WAAA,oBAAkC,CAC3C,QAAO,KAAK,KAAK,YAAY;CAI9B,MAAM,eAAe,YAAY,OAAO,QAAQ,IAAI,QAAQ,UAAU;AACtE,KAAI,iBAAiB,WAAW;AAE/B,SAAO,OAAO,WAAW,wBAAwB,CAAC,KACjD,OAAO,aAAa;IAClB,SAAS,YAAY;IACrB,SAAS,aAAa,IAAI;IAC1B,SAAS,WAAW;GACrB,CAAC,CACF;AACD,SAAO,KAAK,KAAK,yBAAyB;;AAE3C,KAAI,iBAAiB,aAAa;AACjC,SAAO,OAAO,WAAW,0BAA0B,CAAC,KACnD,OAAO,aAAa;IAClB,SAAS,YAAY;IACrB,SAAS,eAAe,IAAI,QAAQ,UAAU;IAC9C,SAAS,aAAa,IAAI;IAC1B,SAAS,WAAW;GACrB,CAAC,CACF;AACD,SAAO,KAAK,KAAK,mBAAmB;;CAErC,MAAM,SAAS,IAAI,QAAQ;CAI3B,MAAM,SAAS,kBAAkB,IAAI,QAAQ,oBAAoB;CACjE,MAAM,cAAc,WAAW,QAAQ,iBAAiB,QAAQ,OAAO,MAAM;AAC7E,QAAO,OAAO,oBAAoB,GAAG,SAAS,oBAAoB,aAAa,CAAC;AAChF,KAAI,CAAC,aAAa;AACjB,SAAO,OAAO,WAAW,6BAA6B,CAAC,KACtD,OAAO,aAAa;IAClB,SAAS,YAAY;IACrB,SAAS,oBAAoB;IAC7B,SAAS,aAAa,IAAI;IAC1B,SAAS,WAAW;GACrB,CAAC,CACF;AACD,SAAO,cACN,mBAAmB;GAClB,OAAO;GACP,YAAY;GACZ,SAAS;GACT,CAAC,EACF,eAAe,OAAO,CACtB;;CAIF,MAAM,UAAU,eAAe,OAAO;AACtC,QAAO,OAAO,aAAa,QAAQ,KAAK,MAAM,QAAQ,CAAC,KACtD,OAAO,SAAS,uBAAuB,QAAQ,OAAO,QAAQ,cAAc,KAAK,QAAQ,CAAC,CAAC,CAC3F;EACA;AAMH,MAAM,gBACL,QACA,KACA,MACA,YACuD;AACvD,KAAI,IAAI,WAAW,SAAS,SAAS,eAAe,OACnD,QAAO,OAAO,QACb,KAAK,KAAK,EAAE,IAAI,MAAM,EAA4D,QAAQ,CAC1F;AAEF,KAAI,IAAI,WAAW,SAAS,SAAS,eAAe,SACnD,QAAO,eAAe,QAAQ,QAAQ;AAEvC,KAAI,IAAI,WAAW,UAAU,SAAS,eAAe,iBACpD,QAAO,WAAW,QAAQ,KAAK,eAAe,QAAQ;AAEvD,KAAI,IAAI,WAAW,UAAU,SAAS,eAAe,sBACpD,QAAO,WAAW,QAAQ,KAAK,oBAAoB,QAAQ;AAE5D,KAAI,IAAI,WAAW,UAAU,SAAS,eAAe,QACpD,QAAO,cAAc,QAAQ,KAAK,QAAQ;AAE3C,QAAO,OAAO,KACb,mBAAmB;EAClB,OAAO;EACP,YAAY;EACZ,SAAS,gBAAgB,IAAI,OAAO,GAAG;EACvC,CAAC,CACF;;AAOF,MAAM,kBACL,QACA,YAEA,OAAO,WAAW;AAcjB,QAAO,KAAK,KAAK,EADsD,UAZvB,MAAM,KACrD,OAAO,kBAAkB,QAAQ,CACjC,CAAC,KAAK,UAAU;EAChB,MAAM,KAAK;EACX,SAAS,KAAK;EACd,QAAQ,KAAK;EACb,WAAW,OAAO,KAAK,KAAK,UAAU,CAAC,SAAS,SAAS;EACzD,QAAQ,KAAK;EACb,EAI8E,EACrD,EAAE,QAAQ;EACnC;AAEH,MAAM,kBACL,QACA,SAEA,OAAO,IAAI,aAAa;AACvB,KAAI,KAAK,SAAA,MACR,QAAO,OAAO,OAAO,KACpB,mBAAmB;EAClB,OAAO;EACP,YAAY;EACZ,SAAS,gBAAgB,eAAe;EACxC,CAAC,CACF;AAEF,QAAO,OAAO,eAAe,QAAmC,MAAM;EACrE,QAAQ;EACR,UAAU,UACT,mBAAmB;GAClB,OAAO;GACP,YAAY;GACZ,SACC,MAAM,YAAY,yBACf,sBACA;GACJ,OAAO,MAAM;GACb,CAAC;EACH,CAAC;EACD;AAEH,MAAM,cACL,QACA,KACA,MACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO,eAAe,mBAAmB,IAAI,KAAK;CAC/D,MAAM,UAAU,OAAO,kBAAkB,IAAI,KAAK,QAAQ;AAC1D,KAAI,YAAY,KAAA,EACf,QAAO,OAAO,OAAO,KACpB,mBAAmB;EAClB,OAAO;EACP,YAAY;EACZ,SAAS,2BAA2B,KAAK,QAAQ;EACjD,CAAC,CACF;CAEF,MAAM,QAAQ,OAAO,KAAK,KAAK,OAAO,SAAS;AAc/C,QAAO,KAAK,KAAK,QAZhB,SAAS,gBAAgB,QAAQ,gBAAgB,MAAM,GAAG,QAAQ,oBAAoB,MAAM,EAC3F,KACD,OAAO,UAAU,UAChB,mBAAmB;EAClB,OAAO;EACP,YAAY;EACZ,SAAS,GAAG,SAAS,gBAAgB,oBAAoB,sBAAsB;EAC/E;EACA,CAAC,CACF,CACD,EAEsB,QAAQ;EAC9B;AAEH,MAAM,iBACL,QACA,KACA,YAEA,OAAO,IAAI,aAAa;CACvB,MAAM,OAAO,OAAO,eAAe,sBAAsB,IAAI,KAAK;CAClE,MAAM,UAAU,OAAO,kBAAkB,IAAI,KAAK,QAAQ;AAC1D,KAAI,YAAY,KAAA,EACf,QAAO,OAAO,OAAO,KACpB,mBAAmB;EAClB,OAAO;EACP,YAAY;EACZ,SAAS,2BAA2B,KAAK,QAAQ;EACjD,CAAC,CACF;CAEF,MAAM,QAAQ,OAAO,KAAK,KAAK,OAAO,SAAS;AAW/C,QAAO,KAAK,KAAK,OAVK,QAAQ,eAAe,MAAM,CAAC,KACnD,OAAO,UAAU,UAChB,mBAAmB;EAClB,OAAO;EACP,YAAY;EACZ,SAAS;EACT;EACA,CAAC,CACF,CACD,EACwB,QAAQ;EAChC;AAMH,MAAM,iBACL,KACA,YACoB,KAAK,IAAI,YAAY;CAAE,OAAO,IAAI;CAAS,MAAM,IAAI;CAAO,EAAE,QAAQ"}
+{"version":3,"file":"server.mjs","names":[],"sources":["../../../src/plugins/wallet/server.ts"],"sourcesContent":["// Wallet plugin — in-process HTTP server.\n//\n// Responsibilities:\n//\n//   1. Bind a `node:http` server on a substrate-allocated port (the\n//      port broker hands the port in; we don't pick it here).\n//   2. Dispatch by `(METHOD, path)` to the four handlers below\n//      (health, accounts, sign-transaction, sign-personal-message).\n//   3. Enforce the auth gate: mandatory Origin in policy.allowed +\n//      constant-time bearer compare.\n//   4. Body-cap enforcement: 64 KiB before buffering — protects the\n//      supervisor from OOM via streaming payloads.\n//   5. Per-request span + log annotation under the captured\n//      supervisor context — so handler errors hit the TUI logger\n//      sink instead of bare stderr.\n//   6. Scope-finalizer teardown: `closeAllConnections()` →\n//      `close()` awaited → port release (the substrate's scope\n//      finalizer chain handles release; we just close).\n//\n// Wiring status (15-wallet.md alignment): both the per-route handler\n// bodies (auth + decode + dispatch to `AccountValue` sign closures)\n// AND the in-process `node:http.Server` listen loop are real. The\n// listener buffers each request body up to `MAX_BODY_BYTES`, forks the\n// dispatcher Effect under the captured supervisor context (so handler\n// logs flow to the TUI logger sink), while the substrate scoped HTTP\n// listener owns bind/close lifecycle.\n\nimport { Cause, Context, Effect, Schema } from 'effect';\nimport type { Scope } from 'effect';\nimport { randomUUID } from 'node:crypto';\nimport type { IncomingMessage, ServerResponse } from 'node:http';\n\nimport { listenScopedHttpServer } from '../../substrate/runtime/scoped-http-server.ts';\nimport { SpanAttr } from '../../substrate/runtime/observability/spans.ts';\nimport { decodeJsonText } from '../../substrate/runtime/runtime-decode.ts';\nimport { formatUnknownError } from '../../substrate/runtime/format-unknown-error.ts';\nimport { WalletSpans } from './spans.ts';\nimport type { AccountValue } from '../account/index.ts';\nimport {\n\twalletBootError,\n\twalletRequestError,\n\ttype WalletBootError,\n\ttype WalletRequestError,\n} from './errors.ts';\nimport { checkOrigin, corsHeadersFor, type OriginPolicy } from './origin-policy.ts';\nimport { parseBearerHeader, safeBearerEquals, type PairingToken } from './pairing.ts';\nimport {\n\tAccountsResponseSchema,\n\tHealthResponseSchema,\n\tSignRequestSchema,\n\tSignResponseSchema,\n\tWALLET_AUTH_HEADER,\n\tWALLET_PROTOCOL_PREFIX,\n\tWalletHttpPath,\n\ttype AccountSummary,\n} from './protocol.ts';\n\n// ----------------------------------------------------------------------\n// Server config + handle\n// ----------------------------------------------------------------------\n\n/** Inputs the substrate hands to `startHttpServer`. The plugin's\n *  acquire body builds this from its resolved inputs (port broker,\n *  origin policy, accounts map, token). */\nexport interface WalletServerConfig {\n\treadonly bindAddress: string;\n\treadonly port: number;\n\treadonly token: PairingToken;\n\treadonly policy: OriginPolicy;\n\treadonly accountsByAddress: ReadonlyMap<string, AccountValue>;\n}\n\n/** Opaque server handle. The substrate's scope finalizer chain\n *  invokes `.close()`; callers don't dispatch into it directly. */\nexport interface WalletServerHandle {\n\treadonly url: string; // direct loopback URL — `http://<bindAddress>:<port>`\n\treadonly close: () => Effect.Effect<void>;\n}\n\n/** Body cap — 64 KiB. Above the largest reasonable sign-tx payload,\n *  well below any OOM threshold. */\nexport const MAX_BODY_BYTES = 64 * 1024;\n\n// ----------------------------------------------------------------------\n// Top-level boot\n// ----------------------------------------------------------------------\n\n/** Per-request socket-level timeout, milliseconds. Caps the time a\n *  malicious / hung peer can hold an idle connection. */\nconst REQUEST_SOCKET_TIMEOUT_MS = 30_000;\n\n/**\n * Boot the wallet HTTP server.\n *\n * Wires `node:http.createServer` against the dispatcher. Listens on\n * `bindAddress:port` (the substrate's port broker chose `port` upstream\n * of this call). The scope finalizer awaits graceful close on teardown\n * — `closeAllConnections()` followed by `close()` with await.\n *\n *  Request flow (per connection):\n *\n *    1. `request` listener fires with `IncomingMessage`+`ServerResponse`.\n *    2. We buffer the request body up to `MAX_BODY_BYTES`. If the\n *       inbound payload exceeds the cap, the socket is destroyed and\n *       a 413 returned without ever invoking the dispatcher (closes the\n *       supervisor-OOM path).\n *    3. Construct a `WalletRequest` from the buffered body + headers.\n *    4. `Effect.runForkWith(supervisorContext)(dispatch(config, req))`\n *       — captured at acquire time so handler logs/spans flow to the\n *       TUI logger sink.\n *    5. On fiber completion, write status + headers + body to `res`.\n *    6. On uncaught exception in the listener path: 500 with an opaque\n *       message (no token leak, no internal-state leak).\n *\n *  Scope finalizer:\n *\n *    Calls `server.closeAllConnections()` (kills idle keepalive\n *    sockets) then awaits `server.close()` (drains in-flight). The\n *    finalizer is uninterruptible so a Ctrl-C double-tap doesn't\n *    leave the socket dangling.\n */\nexport const startHttpServer = (\n\tconfig: WalletServerConfig,\n): Effect.Effect<WalletServerHandle, WalletBootError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\t// Capture the supervisor context so handler fibers run with the\n\t\t// same Logger / span sinks as the rest of the stack. The\n\t\t// dispatcher's R-channel is `never`, but capturing the context\n\t\t// keeps fiber-refs (logger, spans) flowing.\n\t\tconst supervisorContext = yield* Effect.context<never>();\n\t\tconst runDispatch = Effect.runForkWith(supervisorContext as Context.Context<never>);\n\n\t\tconst handle = yield* listenScopedHttpServer({\n\t\t\tbindAddress: config.bindAddress,\n\t\t\tport: config.port,\n\t\t\tlistener: makeRequestListener(config, runDispatch),\n\t\t\tonListenError: (cause): WalletBootError =>\n\t\t\t\twalletBootError({\n\t\t\t\t\tphase: 'listen',\n\t\t\t\t\tmessage:\n\t\t\t\t\t\t`wallet HTTP server listen failed on ${config.bindAddress}:${config.port} — ` +\n\t\t\t\t\t\t(formatUnknownError(cause)),\n\t\t\t\t\thint:\n\t\t\t\t\t\t'check that the port broker did not hand out a busy port; ' +\n\t\t\t\t\t\t'a sibling devstack on the same address would also explain this.',\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t});\n\n\t\tyield* Effect.logInfo('wallet HTTP server listening').pipe(\n\t\t\tEffect.annotateLogs({\n\t\t\t\t[SpanAttr.host]: config.bindAddress,\n\t\t\t\t[SpanAttr.port]: config.port,\n\t\t\t}),\n\t\t);\n\n\t\treturn {\n\t\t\turl: handle.url,\n\t\t\tclose: handle.close,\n\t\t} satisfies WalletServerHandle;\n\t});\n\n// ----------------------------------------------------------------------\n// Node request listener — bridges `node:http` → dispatcher Effect\n// ----------------------------------------------------------------------\n\n/**\n * Build the `(req, res)` listener Node hands to `http.createServer`.\n *\n * The listener:\n *\n *   - Buffers the request body up to `MAX_BODY_BYTES`. Over-cap →\n *     413 + socket destroyed (the dispatcher's body-cap check is the\n *     second line of defense; this one is the first).\n *   - Drops invalid socket-level errors silently (defensive: the\n *     wallet is loopback-only, but a malformed HTTP/1.1 line shouldn't\n *     crash the supervisor).\n *   - Forks the dispatcher Effect via the captured supervisor runtime.\n *   - Writes the resolved `WalletResponse` back to `res`.\n *\n * Returns void (Node listener signature) — all error reporting flows\n * through the dispatcher (request errors) or `Effect.logError` (boot/\n * listener path errors).\n */\nconst makeRequestListener =\n\t(\n\t\tconfig: WalletServerConfig,\n\t\trunDispatch: <A, E>(effect: Effect.Effect<A, E, never>) => unknown,\n\t): ((req: IncomingMessage, res: ServerResponse) => void) =>\n\t(req, res) => {\n\t\t// Socket-level timeout — protects against hung peers parking\n\t\t// requests on the supervisor's loopback.\n\t\treq.socket.setTimeout(REQUEST_SOCKET_TIMEOUT_MS);\n\n\t\tconst chunks: Buffer[] = [];\n\t\tlet totalBytes = 0;\n\t\tlet overflowed = false;\n\n\t\treq.on('data', (chunk: Buffer) => {\n\t\t\tif (overflowed) return;\n\t\t\ttotalBytes += chunk.length;\n\t\t\tif (totalBytes > MAX_BODY_BYTES) {\n\t\t\t\toverflowed = true;\n\t\t\t\twriteOverflow(res);\n\t\t\t\ttry {\n\t\t\t\t\treq.destroy();\n\t\t\t\t} catch {\n\t\t\t\t\t/* defensive */\n\t\t\t\t}\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tchunks.push(chunk);\n\t\t});\n\n\t\treq.on('error', () => {\n\t\t\t// Socket-level error — drop. Per-request errors are handled\n\t\t\t// inside the dispatcher.\n\t\t});\n\n\t\treq.on('end', () => {\n\t\t\tif (overflowed) return;\n\t\t\tconst body = Buffer.concat(chunks).toString('utf8');\n\t\t\tconst walletReq: WalletRequest = {\n\t\t\t\tmethod: req.method ?? 'GET',\n\t\t\t\turl: req.url ?? '/',\n\t\t\t\theaders: normalizeHeaders(req.headers),\n\t\t\t\tbody,\n\t\t\t};\n\t\t\tconst program = dispatch(config, walletReq).pipe(\n\t\t\t\t// `dispatch` is typed `Effect<WalletResponse>` (no failure\n\t\t\t\t// channel) — its handlers map every expected failure into a\n\t\t\t\t// WalletResponse with the right HTTP status. Anything that\n\t\t\t\t// lands here is therefore a *defect* (thrown sync exception,\n\t\t\t\t// runtime invariant violation). We project the full Cause via\n\t\t\t\t// `matchCauseEffect` so we have something to log; `matchEffect`\n\t\t\t\t// would type the failure as `never` and the defect would\n\t\t\t\t// bypass it.\n\t\t\t\tEffect.matchCauseEffect({\n\t\t\t\t\tonFailure: (cause) =>\n\t\t\t\t\t\tEffect.logError('wallet dispatcher defect').pipe(\n\t\t\t\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t\t\t\t[WalletSpans.requestMethod]: walletReq.method,\n\t\t\t\t\t\t\t\t[WalletSpans.requestUrl]: walletReq.url,\n\t\t\t\t\t\t\t\tcause: Cause.pretty(cause),\n\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\tEffect.flatMap(() =>\n\t\t\t\t\t\t\t\tEffect.sync(() => {\n\t\t\t\t\t\t\t\t\twriteServerError(res);\n\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t),\n\t\t\t\t\t\t),\n\t\t\t\t\tonSuccess: (resp) => Effect.sync(() => writeResponse(res, resp)),\n\t\t\t\t}),\n\t\t\t);\n\t\t\trunDispatch(program);\n\t\t});\n\t};\n\nconst writeResponse = (res: ServerResponse, resp: WalletResponse): void => {\n\tif (res.writableEnded) return;\n\tres.statusCode = resp.status;\n\tfor (const [k, v] of Object.entries(resp.headers)) {\n\t\tres.setHeader(k, v);\n\t}\n\tres.end(resp.body);\n};\n\nconst writeOverflow = (res: ServerResponse): void => {\n\tif (res.writableEnded) return;\n\tres.statusCode = 413;\n\tres.setHeader('content-type', 'text/plain; charset=utf-8');\n\tres.end('payload too large');\n};\n\n/** Write an opaque 500 — no token, no internal state leak. The\n *  caller is responsible for logging the underlying cause (see the\n *  `Effect.logError('wallet dispatcher defect')` in `dispatch`'s\n *  `matchCauseEffect` onFailure branch). */\nconst writeServerError = (res: ServerResponse): void => {\n\tif (res.writableEnded) return;\n\tres.statusCode = 500;\n\tres.setHeader('content-type', 'application/json; charset=utf-8');\n\tres.end(\n\t\tJSON.stringify({\n\t\t\terror: 'internal error',\n\t\t\tcode: 'internal-error',\n\t\t}),\n\t);\n};\n\n/** Normalize Node's `IncomingHttpHeaders` (string | string[] | undefined)\n *  to the `WalletRequest.headers` shape (string | undefined). Picks the\n *  first value for repeated headers — matches browser send semantics\n *  for the headers we care about (Origin, Authorization, Content-Type). */\nconst normalizeHeaders = (\n\theaders: IncomingMessage['headers'],\n): Readonly<Record<string, string | undefined>> => {\n\tconst out: Record<string, string | undefined> = {};\n\tfor (const [k, v] of Object.entries(headers)) {\n\t\tif (v === undefined) {\n\t\t\tout[k] = undefined;\n\t\t} else if (Array.isArray(v)) {\n\t\t\tout[k] = v[0];\n\t\t} else {\n\t\t\tout[k] = v;\n\t\t}\n\t}\n\treturn out;\n};\n\n// ----------------------------------------------------------------------\n// Dispatcher — pure(ish) function from request → effect\n// ----------------------------------------------------------------------\n\n/** Inbound request shape — substrate-runtime-agnostic. The substrate's\n *  http-server primitive converts a `node:http` IncomingMessage into\n *  this; tests can construct it directly. */\nexport interface WalletRequest {\n\treadonly method: string;\n\treadonly url: string; // path + query, no host\n\treadonly headers: Readonly<Record<string, string | undefined>>;\n\treadonly body: string; // already-buffered (capped at MAX_BODY_BYTES)\n}\n\n/** Outbound response. */\nexport interface WalletResponse {\n\treadonly status: number;\n\treadonly headers: Readonly<Record<string, string>>;\n\treadonly body: string;\n}\n\nconst json = (\n\tstatus: number,\n\tbody: unknown,\n\textraHeaders: Readonly<Record<string, string>> = {},\n): WalletResponse => ({\n\tstatus,\n\theaders: { 'content-type': 'application/json; charset=utf-8', ...extraHeaders },\n\tbody: JSON.stringify(body),\n});\n\nconst text = (\n\tstatus: number,\n\tbody: string,\n\textraHeaders: Readonly<Record<string, string>> = {},\n): WalletResponse => ({\n\tstatus,\n\theaders: { 'content-type': 'text/plain; charset=utf-8', ...extraHeaders },\n\tbody,\n});\n\n/**\n * Dispatch a single request to its handler. Returns an Effect that\n * always succeeds (the response is built); request-level failures\n * are projected to JSON envelopes via `errorEnvelope` below.\n *\n * The dispatch order matters:\n *   1. Path-prefix gate — anything not under `/api/v1/devstack/` is\n *      a flat 404 (text/plain). PROTECTS the auth gate (and the CORS\n *      preflight) from being visible on arbitrary URLs.\n *   2. OPTIONS preflight (returns 204 + CORS) — no auth required, but\n *      scoped to the protocol prefix by step 1 so an allowed origin\n *      cannot extract CORS headers for unrelated paths.\n *   3. Origin check (must be in policy.allowed; missing → 403).\n *   4. Bearer check (must constant-time-equal `config.token`).\n *   5. Method+path route to handler.\n */\nexport const dispatch = (\n\tconfig: WalletServerConfig,\n\treq: WalletRequest,\n): Effect.Effect<WalletResponse> =>\n\tEffect.gen(function* () {\n\t\tconst requestId = randomUUID();\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t[WalletSpans.requestId]: requestId,\n\t\t\t[WalletSpans.requestMethod]: req.method,\n\t\t\t[WalletSpans.requestUrl]: req.url,\n\t\t});\n\n\t\t// 1. Path-prefix gate. Runs BEFORE the OPTIONS preflight so an\n\t\t//    allowed origin cannot pull a `204 + CORS` response for an\n\t\t//    arbitrary path — preflight success is scoped to the protocol\n\t\t//    prefix, not the whole host.\n\t\tconst path = req.url.split('?')[0] ?? '';\n\t\tif (!path.startsWith(WALLET_PROTOCOL_PREFIX)) {\n\t\t\treturn text(404, 'not found');\n\t\t}\n\n\t\t// 2. OPTIONS preflight — no auth check, but the origin still has\n\t\t//    to be in the allowlist so we don't leak CORS headers to\n\t\t//    arbitrary callers.\n\t\tif (req.method === 'OPTIONS') {\n\t\t\tconst origin = req.headers['origin'];\n\t\t\tif (origin !== undefined && config.policy.allowed.has(origin)) {\n\t\t\t\treturn { status: 204, headers: corsHeadersFor(origin), body: '' };\n\t\t\t}\n\t\t\treturn text(403, 'forbidden origin');\n\t\t}\n\n\t\t// 3. Origin check.\n\t\tconst originResult = checkOrigin(config.policy, req.headers['origin']);\n\t\tif (originResult === 'missing') {\n\t\t\t// Log the BEARER-VALIDITY only, never the token itself.\n\t\t\tyield* Effect.logWarning('wallet origin missing').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.requestId]: requestId,\n\t\t\t\t\t[SpanAttr.httpMethod]: req.method,\n\t\t\t\t\t[SpanAttr.httpPath]: path,\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn text(403, 'Origin header required');\n\t\t}\n\t\tif (originResult === 'forbidden') {\n\t\t\tyield* Effect.logWarning('wallet origin forbidden').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.requestId]: requestId,\n\t\t\t\t\t[WalletSpans.origin]: req.headers.origin ?? '(missing)',\n\t\t\t\t\t[SpanAttr.httpMethod]: req.method,\n\t\t\t\t\t[SpanAttr.httpPath]: path,\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn text(403, 'forbidden origin');\n\t\t}\n\t\tconst origin = req.headers['origin']!;\n\n\t\t// 4. Bearer check. Token never appears in log lines — only the\n\t\t//    boolean validity.\n\t\tconst bearer = parseBearerHeader(req.headers[WALLET_AUTH_HEADER]);\n\t\tconst bearerValid = bearer !== null && safeBearerEquals(bearer, config.token);\n\t\tyield* Effect.annotateCurrentSpan({ [WalletSpans.bearerValid]: bearerValid });\n\t\tif (!bearerValid) {\n\t\t\tyield* Effect.logWarning('wallet bearer check failed').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.requestId]: requestId,\n\t\t\t\t\t[WalletSpans.bearerValid]: bearerValid,\n\t\t\t\t\t[SpanAttr.httpMethod]: req.method,\n\t\t\t\t\t[SpanAttr.httpPath]: path,\n\t\t\t\t}),\n\t\t\t);\n\t\t\treturn errorEnvelope(\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'unauthorized',\n\t\t\t\t\thttpStatus: 401,\n\t\t\t\t\tmessage: 'unauthorized',\n\t\t\t\t}),\n\t\t\t\tcorsHeadersFor(origin),\n\t\t\t);\n\t\t}\n\n\t\t// 5. Route.\n\t\tconst corsHdr = corsHeadersFor(origin);\n\t\treturn yield* routeRequest(config, req, path, corsHdr).pipe(\n\t\t\tEffect.catchTag('WalletRequestError', (err) => Effect.succeed(errorEnvelope(err, corsHdr))),\n\t\t);\n\t});\n\n// ----------------------------------------------------------------------\n// Routing\n// ----------------------------------------------------------------------\n\nconst routeRequest = (\n\tconfig: WalletServerConfig,\n\treq: WalletRequest,\n\tpath: string,\n\tcorsHdr: Readonly<Record<string, string>>,\n): Effect.Effect<WalletResponse, WalletRequestError> => {\n\tif (req.method === 'GET' && path === WalletHttpPath.HEALTH) {\n\t\treturn Effect.succeed(\n\t\t\tjson(200, { ok: true } satisfies Schema.Schema.Type<typeof HealthResponseSchema>, corsHdr),\n\t\t);\n\t}\n\tif (req.method === 'GET' && path === WalletHttpPath.ACCOUNTS) {\n\t\treturn handleAccounts(config, corsHdr);\n\t}\n\tif (req.method === 'POST' && path === WalletHttpPath.SIGN_TRANSACTION) {\n\t\treturn handleSign(config, req, 'transaction', corsHdr);\n\t}\n\tif (req.method === 'POST' && path === WalletHttpPath.SIGN_PERSONAL_MESSAGE) {\n\t\treturn handleSign(config, req, 'personal-message', corsHdr);\n\t}\n\treturn Effect.fail(\n\t\twalletRequestError({\n\t\t\tphase: 'route-not-found',\n\t\t\thttpStatus: 404,\n\t\t\tmessage: `no route for ${req.method} ${path}`,\n\t\t}),\n\t);\n};\n\n// ----------------------------------------------------------------------\n// Handlers\n// ----------------------------------------------------------------------\n\nconst handleAccounts = (\n\tconfig: WalletServerConfig,\n\tcorsHdr: Readonly<Record<string, string>>,\n): Effect.Effect<WalletResponse, WalletRequestError> =>\n\tEffect.sync(() => {\n\t\tconst accounts: ReadonlyArray<AccountSummary> = Array.from(\n\t\t\tconfig.accountsByAddress.values(),\n\t\t).map((acct) => ({\n\t\t\tname: acct.name,\n\t\t\taddress: acct.address,\n\t\t\tscheme: acct.scheme,\n\t\t\tpublicKey: Buffer.from(acct.publicKey).toString('base64'),\n\t\t\tsource: acct.source,\n\t\t}));\n\t\t// Schema-validate the response so a drift between AccountValue\n\t\t// and the wire envelope blows up at the boundary rather than at\n\t\t// the browser-side decode.\n\t\tconst validated: Schema.Schema.Type<typeof AccountsResponseSchema> = { accounts };\n\t\treturn json(200, validated, corsHdr);\n\t});\n\nconst decodeJsonBody = <A>(\n\tschema: Schema.Schema<A>,\n\tbody: string,\n): Effect.Effect<A, WalletRequestError> =>\n\tEffect.gen(function* () {\n\t\t// Body-byte cap is enforced solely at the request listener (line\n\t\t// ~200): we accumulate `chunk.length` byte counts and write a 413\n\t\t// + destroy the socket the moment we cross `MAX_BODY_BYTES`. A\n\t\t// secondary in-dispatcher check on `body.length` would be wrong\n\t\t// anyway — `String.length` counts UTF-16 code units, not bytes,\n\t\t// so a 64 KiB body of multi-byte runes could slip past it. The\n\t\t// listener already gated correctly, so there's no second check\n\t\t// here.\n\t\t// Sanctioned cast: `decodeJsonText`'s `S extends Schema.Decoder<unknown>`\n\t\t// constraint is wider than `Schema.Schema<A>` (DecodingServices /\n\t\t// RequiresServices variance — Effect v4's `Decoder<unknown>` pins\n\t\t// these to `unknown` while `Schema.Schema<A>` pins them to `never`).\n\t\t// The runtime helper happily consumes either; only the TS variance\n\t\t// disagrees. Phase 19A attempted to widen the constraint to\n\t\t// `Schema.Top` but `decodeUnknownSync` requires `Decoder<unknown,\n\t\t// never>`, which a `Top` constraint can't satisfy without a\n\t\t// downstream cast that ends up uglier than this one.\n\t\treturn (yield* decodeJsonText(schema as Schema.Decoder<unknown>, body, {\n\t\t\tsource: 'wallet request body',\n\t\t\tmkError: (issue) =>\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'body-invalid',\n\t\t\t\t\thttpStatus: 400,\n\t\t\t\t\tmessage:\n\t\t\t\t\t\tissue.message === 'failed to parse JSON'\n\t\t\t\t\t\t\t? 'invalid JSON body'\n\t\t\t\t\t\t\t: 'request body did not match schema',\n\t\t\t\t\tcause: issue.cause,\n\t\t\t\t}),\n\t\t})) as A;\n\t});\n\nconst handleSign = (\n\tconfig: WalletServerConfig,\n\treq: WalletRequest,\n\tkind: 'transaction' | 'personal-message',\n\tcorsHdr: Readonly<Record<string, string>>,\n): Effect.Effect<WalletResponse, WalletRequestError> =>\n\tEffect.gen(function* () {\n\t\tconst body = yield* decodeJsonBody(SignRequestSchema, req.body);\n\t\tconst account = config.accountsByAddress.get(body.address);\n\t\tif (account === undefined) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'address-not-found',\n\t\t\t\t\thttpStatus: 404,\n\t\t\t\t\tmessage: `no account for address '${body.address}'`,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst bytes = Buffer.from(body.bytes, 'base64');\n\t\tconst signed = yield* (\n\t\t\tkind === 'transaction' ? account.signTransaction(bytes) : account.signPersonalMessage(bytes)\n\t\t).pipe(\n\t\t\tEffect.mapError((cause) =>\n\t\t\t\twalletRequestError({\n\t\t\t\t\tphase: 'sign-route-failed',\n\t\t\t\t\thttpStatus: 500,\n\t\t\t\t\tmessage: `${kind === 'transaction' ? 'signTransaction' : 'signPersonalMessage'} failed`,\n\t\t\t\t\tcause,\n\t\t\t\t}),\n\t\t\t),\n\t\t);\n\t\tconst resp: Schema.Schema.Type<typeof SignResponseSchema> = signed;\n\t\treturn json(200, resp, corsHdr);\n\t});\n\n// ----------------------------------------------------------------------\n// Error envelope\n// ----------------------------------------------------------------------\n\nconst errorEnvelope = (\n\terr: WalletRequestError,\n\tcorsHdr: Readonly<Record<string, string>>,\n): WalletResponse => json(err.httpStatus, { error: err.message, code: err.phase }, corsHdr);\n"],"mappings":"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"}

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

@@ -36,7 +36,7 @@ interface WalletOptions<Accounts extends ReadonlyArray<WalletAccountMember> = Re
    *     composer invokes once the account-providing members are
    *     known. */
   readonly accounts: Accounts | typeof WALLET_ACCOUNTS_ALL;
-  /** Extra origins merged on top of the stack-scoped auto-derived
+  /** Extra origins merged on top of the router-fronted dev-server
    *  origin. Useful for headless test runners and custom dev hosts. */
   readonly allowedOrigins?: ReadonlyArray<string>;
   /** Preferred host port. Substrate's port broker forward-scans if
@@ -47,10 +47,6 @@ interface WalletOptions<Accounts extends ReadonlyArray<WalletAccountMember> = Re
    *  host-gateway address on native Linux. The public wallet URL remains
    *  router-fronted and stack-scoped. */
   readonly bindAddress?: string;
-  /** Opt-in: allowlist the bare `http://localhost:<vite-port>` form.
-   *  Off by default to close the cross-stack pairing risk (see
-   *  `origin-policy.ts` for the long-form rationale). */
-  readonly allowLocalhostVite?: boolean;
 }
 interface WalletValue {
   readonly url: string;

package/dist/plugins/wallet/service.mjs

@@ -1,6 +1,7 @@
-import { SpanAttr } from "../../substrate/runtime/observability/spans.mjs";
+import { WalletHttpPath } from "../../contracts/wallet-protocol.mjs";
 import { walletBootError } from "./errors.mjs";
-import { WalletHttpPath } from "./protocol.mjs";
+import { WalletSpans } from "./spans.mjs";
+import "./protocol.mjs";
 import { acquirePairingToken, composePairUrl, tokenPath } from "./pairing.mjs";
 import { resolveOriginPolicy } from "./origin-policy.mjs";
 import { startHttpServer } from "./server.mjs";
@@ -29,19 +30,26 @@ const directUrlHostForBindAddress = (bindAddress) => bindAddress === WALLET_DEFA
 */
 const acquireWallet = (opts, ctx) => Effect.gen(function* () {
 	yield* Effect.annotateCurrentSpan({
-		"wallet.app": ctx.app,
-		"wallet.stack": ctx.stack,
-		"wallet.chain": ctx.chain
+		[WalletSpans.app]: ctx.app,
+		[WalletSpans.stack]: ctx.stack,
+		[WalletSpans.chain]: ctx.chain
 	});
 	const accounts = yield* ctx.resolveAccounts();
-	yield* Effect.annotateCurrentSpan({ "wallet.accountCount": accounts.length });
+	yield* Effect.annotateCurrentSpan({ [WalletSpans.accountCount]: accounts.length });
 	if (accounts.length === 0) return yield* Effect.fail(walletBootError({
 		phase: "no-accounts",
 		message: "wallet resolved zero accounts; add account('name') to the stack or pass accounts explicitly.",
 		hint: "`wallet()` and `wallet({ accounts: 'all' })` require at least one account member in the final stack."
 	}));
 	const accountsByAddress = /* @__PURE__ */ new Map();
-	for (const acct of accounts) accountsByAddress.set(acct.address, acct);
+	for (const acct of accounts) {
+		if (accountsByAddress.has(acct.address)) return yield* Effect.fail(walletBootError({
+			phase: "bind-account",
+			message: `wallet resolved two accounts at the same address ${acct.address}; each account must own a distinct address.`,
+			hint: "Remove the duplicate account member, or give the colliding accounts distinct keypairs."
+		}));
+		accountsByAddress.set(acct.address, acct);
+	}
 	const bindAddress = opts.bindAddress ?? WALLET_DEFAULT_BIND_ADDRESS;
 	const port = yield* ctx.allocatePort(opts.port, portProbeHostForBindAddress(bindAddress));
 	const token = yield* acquirePairingToken(tokenPath(ctx.stateRoot));
@@ -52,13 +60,10 @@ const acquireWallet = (opts, ctx) => Effect.gen(function* () {
 		policy: yield* resolveOriginPolicy({
 			app: ctx.app,
 			stack: ctx.stack,
-			vitePortForThisStack: ctx.vitePortForThisStack,
 			routedAppOrigin: ctx.routedAppOrigin,
-			extraOrigins: opts.allowedOrigins ?? [],
-			allowLocalhostVite: opts.allowLocalhostVite ?? false
+			extraOrigins: opts.allowedOrigins ?? []
 		}),
-		accountsByAddress,
-		supervisorCtx: ctx.supervisorCtx
+		accountsByAddress
 	});
 	const walletUrl = ctx.routerFrontedUrl ?? `http://${directUrlHostForBindAddress(bindAddress)}:${port}`;
 	const pairUrl = composePairUrl(walletUrl, token);
@@ -70,17 +75,16 @@ const acquireWallet = (opts, ctx) => Effect.gen(function* () {
 			health: WalletHttpPath.HEALTH,
 			accounts: WalletHttpPath.ACCOUNTS,
 			signTransaction: WalletHttpPath.SIGN_TRANSACTION,
-			signPersonalMessage: WalletHttpPath.SIGN_PERSONAL_MESSAGE,
-			execute: WalletHttpPath.EXECUTE
+			signPersonalMessage: WalletHttpPath.SIGN_PERSONAL_MESSAGE
 		}
 	};
 	yield* Effect.annotateCurrentSpan({
-		"wallet.url": walletUrl,
-		"wallet.localPort": port
+		[WalletSpans.url]: walletUrl,
+		[WalletSpans.localPort]: port
 	});
 	yield* Effect.logInfo("wallet ready").pipe(Effect.annotateLogs({
-		[SpanAttr.walletUrl]: walletUrl,
-		[SpanAttr.walletToken]: "redacted-fragment"
+		[WalletSpans.url]: walletUrl,
+		[WalletSpans.token]: "redacted-fragment"
 	}));
 	return {
 		url: walletUrl,

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

@@ -1 +1 @@
-{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/plugins/wallet/service.ts"],"sourcesContent":["// Wallet plugin — main acquire Effect.\n//\n// What this file does (15-wallet.md §Lifecycle, Startup ordered):\n//\n//   1. Resolve each consumed account tag and key the AccountValues by\n//      address (load-bearing: sign endpoints look up by address).\n//   2. Allocate a port via the substrate's `PortBrokerService`.\n//   3. Mint or rehydrate the pairing token (read-existing-or-mint at\n//      `<stateRoot>/wallet/token`, mode 0o600) via the substrate's\n//      `atomicWriteFile`.\n//   4. Resolve the stack-scoped origin allowlist via\n//      `origin-policy.ts`.\n//   5. Start the in-process HTTP server.\n//   6. Compose the wallet URL + pair URL + return the resolved\n//      `WalletValue`.\n//\n// The substrate handles:\n//\n//   - Scope finalizers (port release, server close) — declared by the\n//     substrate primitives we call into.\n//   - Endpoint registry publication (we surface the URL/pairUrl via\n//     our resolved tag value; the substrate's endpoint-registry\n//     primitive consumes the `RoutableDecl` from `routable.ts`).\n//   - Manifest emit — the substrate projects from registry. We never\n//     write `.devstack/manifest.json` directly.\n\nimport { Effect } from 'effect';\nimport type { FileSystem, Scope } from 'effect';\n\nimport type { AccountValue } from '../account/service.ts';\nimport type { DappKitConfigBindings } from './codegen.ts';\nimport { walletBootError, type WalletBootError } from './errors.ts';\nimport { resolveOriginPolicy } from './origin-policy.ts';\nimport { acquirePairingToken, composePairUrl, tokenPath, type PairingToken } from './pairing.ts';\nimport { startHttpServer, type WalletServerConfig, type WalletServerHandle } from './server.ts';\nimport { WalletHttpPath } from './protocol.ts';\n\n// ----------------------------------------------------------------------\n// User-facing options\n// ----------------------------------------------------------------------\n\nimport type { ResourceRef } from '../../api/define-plugin.ts';\nimport { SpanAttr } from '../../substrate/runtime/observability/spans.ts';\nimport type { AccountResourceId } from '../account/index.ts';\n\n/** Literal sentinel for `WalletOptions.accounts: 'all'` — every account\n *  member in the stack. Expanded by the composer at `defineDevstack`\n *  call time (api-surface-design §4 D6). Kept as an exported constant\n *  so the wallet factory + composer share one source of truth. */\nexport const WALLET_ACCOUNTS_ALL = 'all' as const;\nexport type WalletAccountsAll = typeof WALLET_ACCOUNTS_ALL;\n\n/** A user-supplied account ref. The user passes the result of\n *  `account('alice')` — NOT a bare string. Generic over the literal\n *  account name so the wallet's dependency tuple preserves each\n *  per-account resource id (`account/alice`, `account/bob`, ...). */\nexport type WalletAccountMember<Name extends string = string> = ResourceRef<\n\tAccountResourceId<Name>,\n\tAccountValue\n>;\n\nexport interface WalletOptions<\n\tAccounts extends ReadonlyArray<WalletAccountMember> = ReadonlyArray<WalletAccountMember>,\n> {\n\t/** Accounts the wallet binds. Each is yielded for ordering AND its\n\t *  resolved value is keyed by address into the sign-handler map.\n\t *\n\t *  Two shapes:\n\t *\n\t *   - Explicit tuple — each entry is the plugin/resource ref returned\n\t *     by `account('name')`. Pins the bound set at the wallet's call\n\t *     site; preserves each literal `account/${Name}` so stack\n\t *     composition can validate and recursively expand the refs.\n\t *\n\t *   - The literal `'all'` — shorthand for \"every account member in\n\t *     the stack\". The composer expands this against the final\n\t *     member tuple at `defineDevstack(...)` time (api-surface-design\n\t *     §4 D6). The wallet member returned by the factory carries an\n\t *     expander hook keyed off `WALLET_ACCOUNTS_ALL` that the\n\t *     composer invokes once the account-providing members are\n\t *     known. */\n\treadonly accounts: Accounts | typeof WALLET_ACCOUNTS_ALL;\n\t/** Extra origins merged on top of the stack-scoped auto-derived\n\t *  origin. Useful for headless test runners and custom dev hosts. */\n\treadonly allowedOrigins?: ReadonlyArray<string>;\n\t/** Preferred host port. Substrate's port broker forward-scans if\n\t *  this is taken. Default: substrate-picked (no preference). */\n\treadonly port?: number;\n\t/** NIC the HTTP server binds. Defaults to `'0.0.0.0'` because the\n\t *  router runs in Docker and must reach the host process through the\n\t *  host-gateway address on native Linux. The public wallet URL remains\n\t *  router-fronted and stack-scoped. */\n\treadonly bindAddress?: string;\n\t/** Opt-in: allowlist the bare `http://localhost:<vite-port>` form.\n\t *  Off by default to close the cross-stack pairing risk (see\n\t *  `origin-policy.ts` for the long-form rationale). */\n\treadonly allowLocalhostVite?: boolean;\n}\n\n// ----------------------------------------------------------------------\n// Resolved value (what the wallet plugin publishes)\n// ----------------------------------------------------------------------\n\nexport interface WalletValue {\n\treadonly url: string; // router-fronted URL when available, loopback otherwise\n\treadonly pairUrl: string;\n\treadonly bindings: DappKitConfigBindings;\n\treadonly localPort: number;\n\treadonly token: PairingToken;\n\t/** Server handle — substrate's scope finalizer chain invokes\n\t *  `.close()`; callers don't reach in. Exposed here so tests can\n\t *  drive teardown explicitly. */\n\treadonly server: WalletServerHandle;\n}\n\nconst WALLET_DEFAULT_BIND_ADDRESS = '0.0.0.0' as const;\nconst WALLET_DIRECT_URL_HOST = '127.0.0.1' as const;\ntype WalletPortProbeHost = '127.0.0.1' | '0.0.0.0';\n\nconst portProbeHostForBindAddress = (bindAddress: string): WalletPortProbeHost =>\n\tbindAddress === WALLET_DEFAULT_BIND_ADDRESS ? '0.0.0.0' : '127.0.0.1';\n\nconst directUrlHostForBindAddress = (bindAddress: string): string =>\n\tbindAddress === WALLET_DEFAULT_BIND_ADDRESS ? WALLET_DIRECT_URL_HOST : bindAddress;\n\n// ----------------------------------------------------------------------\n// Per-acquire context — supplied by the barrel\n// ----------------------------------------------------------------------\n\n/** Inputs from the substrate. The barrel fills these from the\n *  BuildContext; tests can construct directly. */\nexport interface WalletAcquireContext {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly chain: string;\n\t/** State root where `wallet/token` lives. Convention:\n\t *  `<appDir>/.devstack/stacks/<stack>/runtime`. */\n\treadonly stateRoot: string;\n\t/** Vite port for THIS stack (per-stack scoping — see\n\t *  `origin-policy.ts`). `null` if no vite is mounted. */\n\treadonly vitePortForThisStack: number | null;\n\t/** Port broker seam — returns the allocated port + a scope-\n\t *  finalizer-installed release. The barrel adapts the substrate's\n\t *  `PortBrokerService.allocate` to this signature so tests can pin\n\t *  the port without yielding from a substrate Layer. */\n\treadonly allocatePort: (\n\t\tpreferred?: number,\n\t\tprobeHost?: WalletPortProbeHost,\n\t) => Effect.Effect<number, WalletBootError, Scope.Scope>;\n\t/** Account value resolver — the barrel hands this in keyed off the\n\t *  BuildContext so the service body stays substrate-agnostic. */\n\treadonly resolveAccounts: () => Effect.Effect<ReadonlyArray<AccountValue>, WalletBootError>;\n\t/** Stable router-fronted base URL for this wallet on the stack-scoped\n\t *  hostname (e.g. `http://wallet.<app>.localhost:<router-port>`). Null\n\t *  only in tests that bypass the router derivation. */\n\treadonly routerFrontedUrl: string | null;\n\t/** Stable router-fronted dev-server origin for this stack. Added to\n\t *  the wallet allowlist so app+wallet stacks work without repeating\n\t *  router origins in user configs. */\n\treadonly routedAppOrigin: string | null;\n\t/** Supervisor context captured for log/span propagation on handler\n\t *  fibers (the in-process HTTP server forks per-request from this). */\n\treadonly supervisorCtx: unknown;\n}\n\n// ----------------------------------------------------------------------\n// Acquire\n// ----------------------------------------------------------------------\n\n/**\n * Acquire the wallet service.\n *\n * Distilled-doc invariants honored:\n *\n *   - C12 (mandatory Origin + bearer): both gates are wired in\n *     `server.ts:dispatch`.\n *   - Token comparison constant-time: `pairing.ts:safeBearerEquals`.\n *   - Token file 0o600: `pairing.ts:acquirePairingToken`.\n *   - Token in URL fragment only: `pairing.ts:composePairUrl`.\n *   - Token NEVER in log lines: handlers log only `bearerValid:\n *     boolean`.\n *   - Default bindAddress `'0.0.0.0'`: required for the Docker router to\n *     reach host-loopback services on native Linux.\n *   - Stack-scoped origin allowlist (no cross-stack pairing risk):\n *     `origin-policy.ts:resolveOriginPolicy`.\n */\nexport const acquireWallet = (\n\topts: WalletOptions,\n\tctx: WalletAcquireContext,\n): Effect.Effect<WalletValue, WalletBootError, Scope.Scope | FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'wallet.app': ctx.app,\n\t\t\t'wallet.stack': ctx.stack,\n\t\t\t'wallet.chain': ctx.chain,\n\t\t});\n\n\t\t// 1. Resolve the dependency account values. The barrel sets up\n\t\t//    `resolveAccounts` to walk the BuildContext via resolved dependencies in\n\t\t//    `opts.accounts`; we just project to the address-keyed map.\n\t\t//    Count is annotated AFTER resolution — `opts.accounts` may\n\t\t//    be the `'all'` sentinel before composer expansion, so the\n\t\t//    resolved-array length is the load-bearing value.\n\t\tconst accounts = yield* ctx.resolveAccounts();\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'wallet.accountCount': accounts.length,\n\t\t});\n\t\tif (accounts.length === 0) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalletBootError({\n\t\t\t\t\tphase: 'no-accounts',\n\t\t\t\t\tmessage:\n\t\t\t\t\t\t\"wallet resolved zero accounts; add account('name') to the stack or pass accounts explicitly.\",\n\t\t\t\t\thint: \"`wallet()` and `wallet({ accounts: 'all' })` require at least one account member in the final stack.\",\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst accountsByAddress = new Map<string, AccountValue>();\n\t\tfor (const acct of accounts) {\n\t\t\taccountsByAddress.set(acct.address, acct);\n\t\t}\n\n\t\t// 2. Port allocation. Probe the same host family the real\n\t\t//    listener uses, otherwise a process bound on a non-loopback\n\t\t//    interface could race the wallet's all-interface listen.\n\t\tconst bindAddress = opts.bindAddress ?? WALLET_DEFAULT_BIND_ADDRESS;\n\t\tconst port = yield* ctx.allocatePort(opts.port, portProbeHostForBindAddress(bindAddress));\n\n\t\t// 3. Token mint or rehydrate. Lives at the stack-scoped state root\n\t\t//    so warm-start + snapshot-restore preserve the existing\n\t\t//    pairing.\n\t\tconst token = yield* acquirePairingToken(tokenPath(ctx.stateRoot));\n\n\t\t// 4. Origin policy. Stack-scoped — only allows THIS stack's vite\n\t\t//    port through.\n\t\tconst policy = yield* resolveOriginPolicy({\n\t\t\tapp: ctx.app,\n\t\t\tstack: ctx.stack,\n\t\t\tvitePortForThisStack: ctx.vitePortForThisStack,\n\t\t\troutedAppOrigin: ctx.routedAppOrigin,\n\t\t\textraOrigins: opts.allowedOrigins ?? [],\n\t\t\tallowLocalhostVite: opts.allowLocalhostVite ?? false,\n\t\t});\n\n\t\t// 5. Start the HTTP server. The dispatcher in `server.ts` owns\n\t\t//    route matching + the constant-time bearer compare + the\n\t\t//    JSON envelope contract.\n\t\tconst serverConfig: WalletServerConfig = {\n\t\t\tbindAddress,\n\t\t\tport,\n\t\t\ttoken,\n\t\t\tpolicy,\n\t\t\taccountsByAddress,\n\t\t\tsupervisorCtx: ctx.supervisorCtx,\n\t\t};\n\t\tconst server = yield* startHttpServer(serverConfig);\n\n\t\t// 6. Compose URLs. Router-fronted form when available, loopback\n\t\t//    fallback otherwise. The token rides ONLY the fragment — never\n\t\t//    a query param — per C13.\n\t\tconst walletUrl =\n\t\t\tctx.routerFrontedUrl ?? `http://${directUrlHostForBindAddress(bindAddress)}:${port}`;\n\t\tconst pairUrl = composePairUrl(walletUrl, token);\n\n\t\tconst bindings: DappKitConfigBindings = {\n\t\t\twalletUrl,\n\t\t\tpairUrl,\n\t\t\tchain: ctx.chain,\n\t\t\tprotocolPaths: {\n\t\t\t\thealth: WalletHttpPath.HEALTH,\n\t\t\t\taccounts: WalletHttpPath.ACCOUNTS,\n\t\t\t\tsignTransaction: WalletHttpPath.SIGN_TRANSACTION,\n\t\t\t\tsignPersonalMessage: WalletHttpPath.SIGN_PERSONAL_MESSAGE,\n\t\t\t\texecute: WalletHttpPath.EXECUTE,\n\t\t\t},\n\t\t};\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t'wallet.url': walletUrl,\n\t\t\t'wallet.localPort': port,\n\t\t});\n\n\t\t// Defensive: NEVER log `pairUrl` directly. It carries the token.\n\t\tyield* Effect.logInfo('wallet ready').pipe(\n\t\t\tEffect.annotateLogs({\n\t\t\t\t[SpanAttr.walletUrl]: walletUrl,\n\t\t\t\t[SpanAttr.walletToken]: 'redacted-fragment',\n\t\t\t}),\n\t\t);\n\n\t\treturn {\n\t\t\turl: walletUrl,\n\t\t\tpairUrl,\n\t\t\tbindings,\n\t\t\tlocalPort: port,\n\t\t\ttoken,\n\t\t\tserver,\n\t\t} satisfies WalletValue;\n\t});\n"],"mappings":";;;;;;;;AAmHA,MAAM,8BAA8B;AACpC,MAAM,yBAAyB;AAG/B,MAAM,+BAA+B,gBACpC,gBAAgB,8BAA8B,YAAY;AAE3D,MAAM,+BAA+B,gBACpC,gBAAgB,8BAA8B,yBAAyB;;;;;;;;;;;;;;;;;;AA+DxE,MAAa,iBACZ,MACA,QAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB;EACjC,cAAc,IAAI;EAClB,gBAAgB,IAAI;EACpB,gBAAgB,IAAI;EACpB,CAAC;CAQF,MAAM,WAAW,OAAO,IAAI,iBAAiB;AAC7C,QAAO,OAAO,oBAAoB,EACjC,uBAAuB,SAAS,QAChC,CAAC;AACF,KAAI,SAAS,WAAW,EACvB,QAAO,OAAO,OAAO,KACpB,gBAAgB;EACf,OAAO;EACP,SACC;EACD,MAAM;EACN,CAAC,CACF;CAEF,MAAM,oCAAoB,IAAI,KAA2B;AACzD,MAAK,MAAM,QAAQ,SAClB,mBAAkB,IAAI,KAAK,SAAS,KAAK;CAM1C,MAAM,cAAc,KAAK,eAAe;CACxC,MAAM,OAAO,OAAO,IAAI,aAAa,KAAK,MAAM,4BAA4B,YAAY,CAAC;CAKzF,MAAM,QAAQ,OAAO,oBAAoB,UAAU,IAAI,UAAU,CAAC;CAwBlE,MAAM,SAAS,OAAO,gBAAgB;EAPrC;EACA;EACA;EACA,QAAA,OAhBqB,oBAAoB;GACzC,KAAK,IAAI;GACT,OAAO,IAAI;GACX,sBAAsB,IAAI;GAC1B,iBAAiB,IAAI;GACrB,cAAc,KAAK,kBAAkB,EAAE;GACvC,oBAAoB,KAAK,sBAAsB;GAC/C,CAAC;EAUD;EACA,eAAe,IAAI;EAE8B,CAAC;CAKnD,MAAM,YACL,IAAI,oBAAoB,UAAU,4BAA4B,YAAY,CAAC,GAAG;CAC/E,MAAM,UAAU,eAAe,WAAW,MAAM;CAEhD,MAAM,WAAkC;EACvC;EACA;EACA,OAAO,IAAI;EACX,eAAe;GACd,QAAQ,eAAe;GACvB,UAAU,eAAe;GACzB,iBAAiB,eAAe;GAChC,qBAAqB,eAAe;GACpC,SAAS,eAAe;GACxB;EACD;AAED,QAAO,OAAO,oBAAoB;EACjC,cAAc;EACd,oBAAoB;EACpB,CAAC;AAGF,QAAO,OAAO,QAAQ,eAAe,CAAC,KACrC,OAAO,aAAa;GAClB,SAAS,YAAY;GACrB,SAAS,cAAc;EACxB,CAAC,CACF;AAED,QAAO;EACN,KAAK;EACL;EACA;EACA,WAAW;EACX;EACA;EACA;EACA"}
+{"version":3,"file":"service.mjs","names":[],"sources":["../../../src/plugins/wallet/service.ts"],"sourcesContent":["// Wallet plugin — main acquire Effect.\n//\n// What this file does (15-wallet.md §Lifecycle, Startup ordered):\n//\n//   1. Resolve each consumed account tag and key the AccountValues by\n//      address (load-bearing: sign endpoints look up by address).\n//   2. Allocate a port via the substrate's `PortBrokerService`.\n//   3. Mint or rehydrate the pairing token (read-existing-or-mint at\n//      `<stateRoot>/wallet/token`, mode 0o600) via the substrate's\n//      `atomicWriteFile`.\n//   4. Resolve the stack-scoped origin allowlist via\n//      `origin-policy.ts`.\n//   5. Start the in-process HTTP server.\n//   6. Compose the wallet URL + pair URL + return the resolved\n//      `WalletValue`.\n//\n// The substrate handles:\n//\n//   - Scope finalizers (port release, server close) — declared by the\n//     substrate primitives we call into.\n//   - Endpoint registry publication (we surface the URL/pairUrl via\n//     our resolved tag value; the substrate's endpoint-registry\n//     primitive consumes the `RoutableDecl` from `routable.ts`).\n//   - Manifest emit — the substrate projects from registry. We never\n//     write `.devstack/manifest.json` directly.\n\nimport { Effect } from 'effect';\nimport type { FileSystem, Scope } from 'effect';\n\nimport type { AccountResourceId, AccountValue } from '../account/index.ts';\nimport type { DappKitConfigBindings } from './codegen.ts';\nimport { walletBootError, type WalletBootError } from './errors.ts';\nimport { resolveOriginPolicy } from './origin-policy.ts';\nimport { acquirePairingToken, composePairUrl, tokenPath, type PairingToken } from './pairing.ts';\nimport { startHttpServer, type WalletServerConfig, type WalletServerHandle } from './server.ts';\nimport { WalletHttpPath } from './protocol.ts';\n\n// ----------------------------------------------------------------------\n// User-facing options\n// ----------------------------------------------------------------------\n\nimport type { ResourceRef } from '../../api/define-plugin.ts';\nimport { WalletSpans } from './spans.ts';\n\n/** Literal sentinel for `WalletOptions.accounts: 'all'` — every account\n *  member in the stack. Expanded by the composer at `defineDevstack`\n *  call time (api-surface-design §4 D6). Kept as an exported constant\n *  so the wallet factory + composer share one source of truth. */\nexport const WALLET_ACCOUNTS_ALL = 'all' as const;\nexport type WalletAccountsAll = typeof WALLET_ACCOUNTS_ALL;\n\n/** A user-supplied account ref. The user passes the result of\n *  `account('alice')` — NOT a bare string. Generic over the literal\n *  account name so the wallet's dependency tuple preserves each\n *  per-account resource id (`account/alice`, `account/bob`, ...). */\nexport type WalletAccountMember<Name extends string = string> = ResourceRef<\n\tAccountResourceId<Name>,\n\tAccountValue\n>;\n\nexport interface WalletOptions<\n\tAccounts extends ReadonlyArray<WalletAccountMember> = ReadonlyArray<WalletAccountMember>,\n> {\n\t/** Accounts the wallet binds. Each is yielded for ordering AND its\n\t *  resolved value is keyed by address into the sign-handler map.\n\t *\n\t *  Two shapes:\n\t *\n\t *   - Explicit tuple — each entry is the plugin/resource ref returned\n\t *     by `account('name')`. Pins the bound set at the wallet's call\n\t *     site; preserves each literal `account/${Name}` so stack\n\t *     composition can validate and recursively expand the refs.\n\t *\n\t *   - The literal `'all'` — shorthand for \"every account member in\n\t *     the stack\". The composer expands this against the final\n\t *     member tuple at `defineDevstack(...)` time (api-surface-design\n\t *     §4 D6). The wallet member returned by the factory carries an\n\t *     expander hook keyed off `WALLET_ACCOUNTS_ALL` that the\n\t *     composer invokes once the account-providing members are\n\t *     known. */\n\treadonly accounts: Accounts | typeof WALLET_ACCOUNTS_ALL;\n\t/** Extra origins merged on top of the router-fronted dev-server\n\t *  origin. Useful for headless test runners and custom dev hosts. */\n\treadonly allowedOrigins?: ReadonlyArray<string>;\n\t/** Preferred host port. Substrate's port broker forward-scans if\n\t *  this is taken. Default: substrate-picked (no preference). */\n\treadonly port?: number;\n\t/** NIC the HTTP server binds. Defaults to `'0.0.0.0'` because the\n\t *  router runs in Docker and must reach the host process through the\n\t *  host-gateway address on native Linux. The public wallet URL remains\n\t *  router-fronted and stack-scoped. */\n\treadonly bindAddress?: string;\n}\n\n// ----------------------------------------------------------------------\n// Resolved value (what the wallet plugin publishes)\n// ----------------------------------------------------------------------\n\nexport interface WalletValue {\n\treadonly url: string; // router-fronted URL when available, loopback otherwise\n\treadonly pairUrl: string;\n\treadonly bindings: DappKitConfigBindings;\n\treadonly localPort: number;\n\treadonly token: PairingToken;\n\t/** Server handle — substrate's scope finalizer chain invokes\n\t *  `.close()`; callers don't reach in. Exposed here so tests can\n\t *  drive teardown explicitly. */\n\treadonly server: WalletServerHandle;\n}\n\nconst WALLET_DEFAULT_BIND_ADDRESS = '0.0.0.0' as const;\nconst WALLET_DIRECT_URL_HOST = '127.0.0.1' as const;\ntype WalletPortProbeHost = '127.0.0.1' | '0.0.0.0';\n\nconst portProbeHostForBindAddress = (bindAddress: string): WalletPortProbeHost =>\n\tbindAddress === WALLET_DEFAULT_BIND_ADDRESS ? '0.0.0.0' : '127.0.0.1';\n\nconst directUrlHostForBindAddress = (bindAddress: string): string =>\n\tbindAddress === WALLET_DEFAULT_BIND_ADDRESS ? WALLET_DIRECT_URL_HOST : bindAddress;\n\n// ----------------------------------------------------------------------\n// Per-acquire context — supplied by the barrel\n// ----------------------------------------------------------------------\n\n/** Inputs from the substrate. The barrel fills these from the\n *  BuildContext; tests can construct directly. */\nexport interface WalletAcquireContext {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly chain: string;\n\t/** State root where `wallet/token` lives. Convention:\n\t *  `<appDir>/.devstack/stacks/<stack>/runtime`. */\n\treadonly stateRoot: string;\n\t/** Port broker seam — returns the allocated port + a scope-\n\t *  finalizer-installed release. The barrel adapts the substrate's\n\t *  `PortBrokerService.allocate` to this signature so tests can pin\n\t *  the port without yielding from a substrate Layer. */\n\treadonly allocatePort: (\n\t\tpreferred?: number,\n\t\tprobeHost?: WalletPortProbeHost,\n\t) => Effect.Effect<number, WalletBootError, Scope.Scope>;\n\t/** Account value resolver — the barrel hands this in keyed off the\n\t *  BuildContext so the service body stays substrate-agnostic. */\n\treadonly resolveAccounts: () => Effect.Effect<ReadonlyArray<AccountValue>, WalletBootError>;\n\t/** Stable router-fronted base URL for this wallet on the stack-scoped\n\t *  hostname (e.g. `http://wallet.<app>.localhost:<router-port>`). Null\n\t *  only in tests that bypass the router derivation. */\n\treadonly routerFrontedUrl: string | null;\n\t/** Stable router-fronted dev-server origin for this stack. Added to\n\t *  the wallet allowlist so app+wallet stacks work without repeating\n\t *  router origins in user configs. */\n\treadonly routedAppOrigin: string | null;\n}\n\n// ----------------------------------------------------------------------\n// Acquire\n// ----------------------------------------------------------------------\n\n/**\n * Acquire the wallet service.\n *\n * Distilled-doc invariants honored:\n *\n *   - C12 (mandatory Origin + bearer): both gates are wired in\n *     `server.ts:dispatch`.\n *   - Token comparison constant-time: `pairing.ts:safeBearerEquals`.\n *   - Token file 0o600: `pairing.ts:acquirePairingToken`.\n *   - Token in URL fragment only: `pairing.ts:composePairUrl`.\n *   - Token NEVER in log lines: handlers log only `bearerValid:\n *     boolean`.\n *   - Default bindAddress `'0.0.0.0'`: required for the Docker router to\n *     reach host-loopback services on native Linux.\n *   - Stack-scoped origin allowlist (no cross-stack pairing risk):\n *     `origin-policy.ts:resolveOriginPolicy`.\n */\nexport const acquireWallet = (\n\topts: WalletOptions,\n\tctx: WalletAcquireContext,\n): Effect.Effect<WalletValue, WalletBootError, Scope.Scope | FileSystem.FileSystem> =>\n\tEffect.gen(function* () {\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t[WalletSpans.app]: ctx.app,\n\t\t\t[WalletSpans.stack]: ctx.stack,\n\t\t\t[WalletSpans.chain]: ctx.chain,\n\t\t});\n\n\t\t// 1. Resolve the dependency account values. The barrel sets up\n\t\t//    `resolveAccounts` to walk the BuildContext via resolved dependencies in\n\t\t//    `opts.accounts`; we just project to the address-keyed map.\n\t\t//    Count is annotated AFTER resolution — `opts.accounts` may\n\t\t//    be the `'all'` sentinel before composer expansion, so the\n\t\t//    resolved-array length is the load-bearing value.\n\t\tconst accounts = yield* ctx.resolveAccounts();\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t[WalletSpans.accountCount]: accounts.length,\n\t\t});\n\t\tif (accounts.length === 0) {\n\t\t\treturn yield* Effect.fail(\n\t\t\t\twalletBootError({\n\t\t\t\t\tphase: 'no-accounts',\n\t\t\t\t\tmessage:\n\t\t\t\t\t\t\"wallet resolved zero accounts; add account('name') to the stack or pass accounts explicitly.\",\n\t\t\t\t\thint: \"`wallet()` and `wallet({ accounts: 'all' })` require at least one account member in the final stack.\",\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\t\tconst accountsByAddress = new Map<string, AccountValue>();\n\t\tfor (const acct of accounts) {\n\t\t\t// Two accounts resolving to the same address would silently\n\t\t\t// last-write-wins the sign-route map, so a sign request for\n\t\t\t// that address binds to a non-deterministic account. Fail at\n\t\t\t// boot with the colliding address named.\n\t\t\tif (accountsByAddress.has(acct.address)) {\n\t\t\t\treturn yield* Effect.fail(\n\t\t\t\t\twalletBootError({\n\t\t\t\t\t\tphase: 'bind-account',\n\t\t\t\t\t\tmessage: `wallet resolved two accounts at the same address ${acct.address}; each account must own a distinct address.`,\n\t\t\t\t\t\thint: 'Remove the duplicate account member, or give the colliding accounts distinct keypairs.',\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\t\t\taccountsByAddress.set(acct.address, acct);\n\t\t}\n\n\t\t// 2. Port allocation. Probe the same host family the real\n\t\t//    listener uses, otherwise a process bound on a non-loopback\n\t\t//    interface could race the wallet's all-interface listen.\n\t\tconst bindAddress = opts.bindAddress ?? WALLET_DEFAULT_BIND_ADDRESS;\n\t\tconst port = yield* ctx.allocatePort(opts.port, portProbeHostForBindAddress(bindAddress));\n\n\t\t// 3. Token mint or rehydrate. Lives at the stack-scoped state root\n\t\t//    so warm-start + snapshot-restore preserve the existing\n\t\t//    pairing.\n\t\tconst token = yield* acquirePairingToken(tokenPath(ctx.stateRoot));\n\n\t\t// 4. Origin policy. Allowlist is the router-fronted dev-server\n\t\t//    origin for this stack plus any explicit `allowedOrigins`.\n\t\tconst policy = yield* resolveOriginPolicy({\n\t\t\tapp: ctx.app,\n\t\t\tstack: ctx.stack,\n\t\t\troutedAppOrigin: ctx.routedAppOrigin,\n\t\t\textraOrigins: opts.allowedOrigins ?? [],\n\t\t});\n\n\t\t// 5. Start the HTTP server. The dispatcher in `server.ts` owns\n\t\t//    route matching + the constant-time bearer compare + the\n\t\t//    JSON envelope contract.\n\t\tconst serverConfig: WalletServerConfig = {\n\t\t\tbindAddress,\n\t\t\tport,\n\t\t\ttoken,\n\t\t\tpolicy,\n\t\t\taccountsByAddress,\n\t\t};\n\t\tconst server = yield* startHttpServer(serverConfig);\n\n\t\t// 6. Compose URLs. Router-fronted form when available, loopback\n\t\t//    fallback otherwise. The token rides ONLY the fragment — never\n\t\t//    a query param — per C13.\n\t\tconst walletUrl =\n\t\t\tctx.routerFrontedUrl ?? `http://${directUrlHostForBindAddress(bindAddress)}:${port}`;\n\t\tconst pairUrl = composePairUrl(walletUrl, token);\n\n\t\tconst bindings: DappKitConfigBindings = {\n\t\t\twalletUrl,\n\t\t\tpairUrl,\n\t\t\tchain: ctx.chain,\n\t\t\tprotocolPaths: {\n\t\t\t\thealth: WalletHttpPath.HEALTH,\n\t\t\t\taccounts: WalletHttpPath.ACCOUNTS,\n\t\t\t\tsignTransaction: WalletHttpPath.SIGN_TRANSACTION,\n\t\t\t\tsignPersonalMessage: WalletHttpPath.SIGN_PERSONAL_MESSAGE,\n\t\t\t},\n\t\t};\n\n\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t[WalletSpans.url]: walletUrl,\n\t\t\t[WalletSpans.localPort]: port,\n\t\t});\n\n\t\t// Defensive: NEVER log `pairUrl` directly. It carries the token.\n\t\tyield* Effect.logInfo('wallet ready').pipe(\n\t\t\tEffect.annotateLogs({\n\t\t\t\t[WalletSpans.url]: walletUrl,\n\t\t\t\t[WalletSpans.token]: 'redacted-fragment',\n\t\t\t}),\n\t\t);\n\n\t\treturn {\n\t\t\turl: walletUrl,\n\t\t\tpairUrl,\n\t\t\tbindings,\n\t\t\tlocalPort: port,\n\t\t\ttoken,\n\t\t\tserver,\n\t\t} satisfies WalletValue;\n\t});\n"],"mappings":";;;;;;;;;AA8GA,MAAM,8BAA8B;AACpC,MAAM,yBAAyB;AAG/B,MAAM,+BAA+B,gBACpC,gBAAgB,8BAA8B,YAAY;AAE3D,MAAM,+BAA+B,gBACpC,gBAAgB,8BAA8B,yBAAyB;;;;;;;;;;;;;;;;;;AAyDxE,MAAa,iBACZ,MACA,QAEA,OAAO,IAAI,aAAa;AACvB,QAAO,OAAO,oBAAoB;GAChC,YAAY,MAAM,IAAI;GACtB,YAAY,QAAQ,IAAI;GACxB,YAAY,QAAQ,IAAI;EACzB,CAAC;CAQF,MAAM,WAAW,OAAO,IAAI,iBAAiB;AAC7C,QAAO,OAAO,oBAAoB,GAChC,YAAY,eAAe,SAAS,QACrC,CAAC;AACF,KAAI,SAAS,WAAW,EACvB,QAAO,OAAO,OAAO,KACpB,gBAAgB;EACf,OAAO;EACP,SACC;EACD,MAAM;EACN,CAAC,CACF;CAEF,MAAM,oCAAoB,IAAI,KAA2B;AACzD,MAAK,MAAM,QAAQ,UAAU;AAK5B,MAAI,kBAAkB,IAAI,KAAK,QAAQ,CACtC,QAAO,OAAO,OAAO,KACpB,gBAAgB;GACf,OAAO;GACP,SAAS,oDAAoD,KAAK,QAAQ;GAC1E,MAAM;GACN,CAAC,CACF;AAEF,oBAAkB,IAAI,KAAK,SAAS,KAAK;;CAM1C,MAAM,cAAc,KAAK,eAAe;CACxC,MAAM,OAAO,OAAO,IAAI,aAAa,KAAK,MAAM,4BAA4B,YAAY,CAAC;CAKzF,MAAM,QAAQ,OAAO,oBAAoB,UAAU,IAAI,UAAU,CAAC;CAqBlE,MAAM,SAAS,OAAO,gBAAgB;EANrC;EACA;EACA;EACA,QAAA,OAdqB,oBAAoB;GACzC,KAAK,IAAI;GACT,OAAO,IAAI;GACX,iBAAiB,IAAI;GACrB,cAAc,KAAK,kBAAkB,EAAE;GACvC,CAAC;EAUD;EAEiD,CAAC;CAKnD,MAAM,YACL,IAAI,oBAAoB,UAAU,4BAA4B,YAAY,CAAC,GAAG;CAC/E,MAAM,UAAU,eAAe,WAAW,MAAM;CAEhD,MAAM,WAAkC;EACvC;EACA;EACA,OAAO,IAAI;EACX,eAAe;GACd,QAAQ,eAAe;GACvB,UAAU,eAAe;GACzB,iBAAiB,eAAe;GAChC,qBAAqB,eAAe;GACpC;EACD;AAED,QAAO,OAAO,oBAAoB;GAChC,YAAY,MAAM;GAClB,YAAY,YAAY;EACzB,CAAC;AAGF,QAAO,OAAO,QAAQ,eAAe,CAAC,KACrC,OAAO,aAAa;GAClB,YAAY,MAAM;GAClB,YAAY,QAAQ;EACrB,CAAC,CACF;AAED,QAAO;EACN,KAAK;EACL;EACA;EACA,WAAW;EACX;EACA;EACA;EACA"}

package/dist/plugins/wallet/spans.mjs

@@ -0,0 +1,22 @@
+//#region src/plugins/wallet/spans.ts
+const WalletSpans = {
+	accountCount: "wallet.accountCount",
+	app: "wallet.app",
+	bearerValid: "wallet.auth.bearerValid",
+	chain: "wallet.chain",
+	codegenPairUrl: "wallet.codegen.pairUrl",
+	codegenWalletUrl: "wallet.codegen.walletUrl",
+	localPort: "wallet.localPort",
+	origin: "wallet.origin",
+	requestId: "wallet.request.id",
+	requestMethod: "wallet.request.method",
+	requestUrl: "wallet.request.url",
+	stack: "wallet.stack",
+	token: "wallet.token",
+	tokenFile: "wallet.tokenFile",
+	url: "wallet.url"
+};
+//#endregion
+export { WalletSpans };
+
+//# sourceMappingURL=spans.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spans.mjs","names":[],"sources":["../../../src/plugins/wallet/spans.ts"],"sourcesContent":["// Wallet plugin span-attribute vocabulary. Plugin-local — substrate's\n// `SpanAttr` carries only engine-dimensional + http/process generic\n// keys; plugin-domain keys live next to the plugin that owns them.\n//\n// Callsite pattern: `Effect.annotateCurrentSpan({ [WalletSpans.token]:\n// value })`. Free-form string literals are a STYLE_GUIDE §16 violation.\n\nexport const WalletSpans = {\n\taccountCount: 'wallet.accountCount',\n\tapp: 'wallet.app',\n\tbearerValid: 'wallet.auth.bearerValid',\n\tchain: 'wallet.chain',\n\tcodegenPairUrl: 'wallet.codegen.pairUrl',\n\tcodegenWalletUrl: 'wallet.codegen.walletUrl',\n\tlocalPort: 'wallet.localPort',\n\torigin: 'wallet.origin',\n\trequestId: 'wallet.request.id',\n\trequestMethod: 'wallet.request.method',\n\trequestUrl: 'wallet.request.url',\n\tstack: 'wallet.stack',\n\ttoken: 'wallet.token',\n\ttokenFile: 'wallet.tokenFile',\n\turl: 'wallet.url',\n} as const;\n"],"mappings":";AAOA,MAAa,cAAc;CAC1B,cAAc;CACd,KAAK;CACL,aAAa;CACb,OAAO;CACP,gBAAgB;CAChB,kBAAkB;CAClB,WAAW;CACX,QAAQ;CACR,WAAW;CACX,eAAe;CACf,YAAY;CACZ,OAAO;CACP,OAAO;CACP,WAAW;CACX,KAAK;CACL"}

package/dist/plugins/walrus/bootstrap-assets/cargo-image.mjs

@@ -1,5 +1,8 @@
 import { walrusPluginError } from "../errors.mjs";
+import { WalrusSpans } from "../spans.mjs";
+import { readEnv } from "../../../substrate/runtime/typed-env.mjs";
 import { Effect } from "effect";
+import { fileURLToPath } from "node:url";
 //#region src/plugins/walrus/bootstrap-assets/cargo-image.ts
 const WALRUS_CARGO_IMAGE_OVERRIDE_ENV = "WALRUS_CARGO_IMAGE_OVERRIDE";
 /** Pinned Walrus release whose native binaries are packaged into the
@@ -9,12 +12,25 @@ const DEFAULT_WALRUS_REF = "testnet-v1.49.1";
 *  match the localnet image's sui release. Pinned here in lockstep
 *  with the walrus ref bump. */
 const DEFAULT_SUI_VERSION = "devnet-v1.71.0";
-/** Resolve to the on-disk path of the vendored Dockerfile context. */
-const vendoredDockerfileContext = () => new URL("../../../../images/walrus/", import.meta.url).pathname;
+/** Resolve to the on-disk path of the vendored Dockerfile context.
+*  `fileURLToPath` normalises the URL → host-path conversion across
+*  platforms (Windows `file:///C:/...` → `C:\...`; POSIX strips the
+*  scheme and percent-decodes). Reading `.pathname` directly would
+*  leave the leading `/` on Windows. */
+const vendoredDockerfileContext = () => fileURLToPath(new URL("../../../../images/walrus/", import.meta.url));
 /** Resolve the walrus image. Path (a) trusts an env-override tag; path
-*  (b) builds the vendored Dockerfile via `runtime.ensureImage`. */
-const resolveCargoImage = (runtime, inputs) => Effect.gen(function* () {
-	const override = globalThis.process?.env?.[WALRUS_CARGO_IMAGE_OVERRIDE_ENV];
+*  (b) builds the vendored Dockerfile via `runtime.ensureImage`.
+*
+*  `expectedTag`, when given, is the on-host tag the resolved image is
+*  published under (the build itself is content-cached, so multiple distinct
+*  tags of the SAME build are cheap re-tags). The storage-node committee uses
+*  this to give each node its OWN image tag — otherwise all N nodes share one
+*  tag and snapshot-restore's per-container image promote collapses N committed
+*  writable layers onto that single tag (last-write-wins), losing N-1 nodes'
+*  RocksDB. `ensureImage` reuses an existing tag without rebuilding, so a tag
+*  the restore already promoted to a committed layer is preserved on reboot. */
+const resolveCargoImage = (runtime, inputs, expectedTag) => Effect.gen(function* () {
+	const override = readEnv(WALRUS_CARGO_IMAGE_OVERRIDE_ENV);
 	if (override && override.length > 0) return {
 		digest: override,
 		tag: override
@@ -25,16 +41,25 @@ const resolveCargoImage = (runtime, inputs) => Effect.gen(function* () {
 		buildArgs: {
 			WALRUS_VERSION: inputs.walrusRef,
 			SUI_VERSION: inputs.suiVersion
+		},
+		owner: {
+			app: inputs.owner.app,
+			stack: inputs.owner.stack,
+			plugin: "walrus",
+			role: "cluster"
 		}
 	};
-	const built = yield* runtime.ensureImage(buildCtx).pipe(Effect.mapError((cause) => walrusPluginError("image-build", `walrus image build failed (walrusRef=${inputs.walrusRef}, suiVersion=${inputs.suiVersion}): ${cause.reason}: ${cause.detail}`, { cause })));
+	const built = yield* runtime.ensureImage(buildCtx, expectedTag !== void 0 ? {
+		digest: expectedTag,
+		tag: expectedTag
+	} : void 0).pipe(Effect.mapError((cause) => walrusPluginError("image-build", `walrus image build failed (walrusRef=${inputs.walrusRef}, suiVersion=${inputs.suiVersion}): ${cause.reason}: ${cause.detail}`, { cause })));
 	return {
 		digest: built.digest,
 		tag: built.tag ?? built.digest
 	};
 }).pipe(Effect.withSpan("devstack.plugin.walrus.cargoImage.resolve", { attributes: {
-	"walrus.ref": inputs.walrusRef,
-	"walrus.suiVersion": inputs.suiVersion
+	[WalrusSpans.ref]: inputs.walrusRef,
+	[WalrusSpans.suiVersion]: inputs.suiVersion
 } }));
 //#endregion
 export { DEFAULT_SUI_VERSION, DEFAULT_WALRUS_REF, resolveCargoImage };

package/dist/plugins/walrus/bootstrap-assets/cargo-image.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cargo-image.mjs","names":[],"sources":["../../../../src/plugins/walrus/bootstrap-assets/cargo-image.ts"],"sourcesContent":["// Walrus vendored Dockerfile-built image.\n//\n// CONTRACT:\n//\n// The vendored Dockerfile packages the upstream Walrus release tarball\n// selected by Docker's TARGETARCH. It never builds Walrus from source:\n// upstream release binaries are the contract, and the Dockerfile verifies\n// the selected asset before the image is accepted.\n//\n// Two staged paths:\n//\n//   (a) `WALRUS_CARGO_IMAGE_OVERRIDE` env var — points at a pre-baked\n//        registry tag (or a locally `docker build`-tagged image). Skips\n//        the runtime build entirely and returns a bare `ImageRef`. The\n//        e2e stub test uses this path (`walrus-test-stub:latest`).\n//\n//   (b) Vendored Dockerfile build via `runtime.ensureImage()`. The\n//        substrate's content-addressed build cache short-circuits when\n//        the (context + dockerfile + buildArgs) hash matches a prior result;\n//        cold-cache wall-time is the upstream release download.\n//\n// Distilled-doc invariants honored:\n//   - 24: `DEFAULT_SUI_VERSION` (the wrapper-baked sui binary) MUST\n//        align with the localnet image's sui release.\n//   - 25: ubuntu:24.04 base — handled in the Dockerfile.\n\nimport { Effect, type Scope } from 'effect';\n\nimport type { ContainerRuntime, ImageRef } from '../../../contracts/container-runtime.ts';\nimport { walrusPluginError, type WalrusPluginError } from '../errors.ts';\n\nconst WALRUS_CARGO_IMAGE_OVERRIDE_ENV = 'WALRUS_CARGO_IMAGE_OVERRIDE' as const;\n\n/** Pinned Walrus release whose native binaries are packaged into the\n *  local-cluster wrapper image. */\nexport const DEFAULT_WALRUS_REF = 'testnet-v1.49.1' as const;\n\n/** Distilled-doc invariant 24: the wrapper-baked sui binary must\n *  match the localnet image's sui release. Pinned here in lockstep\n *  with the walrus ref bump. */\nexport const DEFAULT_SUI_VERSION = 'devnet-v1.71.0' as const;\n\n/** Inputs to the walrus image resolver. */\nexport interface WalrusCargoImageInputs<Ref extends string = string, SuiV extends string = string> {\n\treadonly walrusRef: Ref;\n\treadonly suiVersion: SuiV;\n}\n\n/** Resolved value — the content-addressed image ref. */\nexport interface WalrusCargoImageResolved {\n\treadonly digest: string;\n\treadonly tag: string;\n}\n\n// ---------------------------------------------------------------------------\n// Runtime resolver\n// ---------------------------------------------------------------------------\n\n/** Resolve to the on-disk path of the vendored Dockerfile context. */\nconst vendoredDockerfileContext = (): string =>\n\tnew URL('../../../../images/walrus/', import.meta.url).pathname;\n\n/** Resolve the walrus image. Path (a) trusts an env-override tag; path\n *  (b) builds the vendored Dockerfile via `runtime.ensureImage`. */\nexport const resolveCargoImage = (\n\truntime: ContainerRuntime,\n\tinputs: WalrusCargoImageInputs,\n): Effect.Effect<WalrusCargoImageResolved, WalrusPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst override = (globalThis as { process?: { env?: Record<string, string | undefined> } })\n\t\t\t.process?.env?.[WALRUS_CARGO_IMAGE_OVERRIDE_ENV];\n\t\tif (override && override.length > 0) {\n\t\t\t// Trust-the-tag path. The digest is opaque (substrate's\n\t\t\t// content-addressed cache will re-resolve via `docker inspect`\n\t\t\t// when it materializes the image).\n\t\t\treturn { digest: override, tag: override };\n\t\t}\n\n\t\t// Real build via the vendored Dockerfile.\n\t\tconst buildCtx = {\n\t\t\tcontextPath: vendoredDockerfileContext(),\n\t\t\tdockerfile: 'Dockerfile',\n\t\t\tbuildArgs: {\n\t\t\t\tWALRUS_VERSION: inputs.walrusRef,\n\t\t\t\tSUI_VERSION: inputs.suiVersion,\n\t\t\t},\n\t\t};\n\n\t\tconst built = yield* runtime\n\t\t\t.ensureImage(buildCtx)\n\t\t\t.pipe(\n\t\t\t\tEffect.mapError((cause) =>\n\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t'image-build',\n\t\t\t\t\t\t`walrus image build failed (walrusRef=${inputs.walrusRef}, suiVersion=${inputs.suiVersion}): ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t{ cause },\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\treturn { digest: built.digest, tag: built.tag ?? built.digest };\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.walrus.cargoImage.resolve', {\n\t\t\tattributes: {\n\t\t\t\t'walrus.ref': inputs.walrusRef,\n\t\t\t\t'walrus.suiVersion': inputs.suiVersion,\n\t\t\t},\n\t\t}),\n\t);\n\n/** Convenience: resolve via the default inputs. */\nexport const resolveDefaultCargoImage = (\n\truntime: ContainerRuntime,\n): Effect.Effect<ImageRef, WalrusPluginError, Scope.Scope> =>\n\tresolveCargoImage(runtime, {\n\t\twalrusRef: DEFAULT_WALRUS_REF,\n\t\tsuiVersion: DEFAULT_SUI_VERSION,\n\t});\n"],"mappings":";;;AA+BA,MAAM,kCAAkC;;;AAIxC,MAAa,qBAAqB;;;;AAKlC,MAAa,sBAAsB;;AAmBnC,MAAM,kCACL,IAAI,IAAI,8BAA8B,OAAO,KAAK,IAAI,CAAC;;;AAIxD,MAAa,qBACZ,SACA,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAY,WAChB,SAAS,MAAM;AACjB,KAAI,YAAY,SAAS,SAAS,EAIjC,QAAO;EAAE,QAAQ;EAAU,KAAK;EAAU;CAI3C,MAAM,WAAW;EAChB,aAAa,2BAA2B;EACxC,YAAY;EACZ,WAAW;GACV,gBAAgB,OAAO;GACvB,aAAa,OAAO;GACpB;EACD;CAED,MAAM,QAAQ,OAAO,QACnB,YAAY,SAAS,CACrB,KACA,OAAO,UAAU,UAChB,kBACC,eACA,wCAAwC,OAAO,UAAU,eAAe,OAAO,WAAW,KAAK,MAAM,OAAO,IAAI,MAAM,UACtH,EAAE,OAAO,CACT,CACD,CACD;AACF,QAAO;EAAE,QAAQ,MAAM;EAAQ,KAAK,MAAM,OAAO,MAAM;EAAQ;EAC9D,CAAC,KACF,OAAO,SAAS,6CAA6C,EAC5D,YAAY;CACX,cAAc,OAAO;CACrB,qBAAqB,OAAO;CAC5B,EACD,CAAC,CACF"}
+{"version":3,"file":"cargo-image.mjs","names":[],"sources":["../../../../src/plugins/walrus/bootstrap-assets/cargo-image.ts"],"sourcesContent":["// Walrus vendored Dockerfile-built image.\n//\n// CONTRACT:\n//\n// The vendored Dockerfile packages the upstream Walrus release tarball\n// selected by Docker's TARGETARCH. It never builds Walrus from source:\n// upstream release binaries are the contract, and the Dockerfile verifies\n// the selected asset before the image is accepted.\n//\n// Two staged paths:\n//\n//   (a) `WALRUS_CARGO_IMAGE_OVERRIDE` env var — points at a pre-baked\n//        registry tag (or a locally `docker build`-tagged image). Skips\n//        the runtime build entirely and returns a bare `ImageRef`. The\n//        e2e stub test uses this path (`walrus-test-stub:latest`).\n//\n//   (b) Vendored Dockerfile build via `runtime.ensureImage()`. The\n//        substrate's content-addressed build cache short-circuits when\n//        the (context + dockerfile + buildArgs) hash matches a prior result;\n//        cold-cache wall-time is the upstream release download.\n//\n// Distilled-doc invariants honored:\n//   - 24: `DEFAULT_SUI_VERSION` (the wrapper-baked sui binary) MUST\n//        align with the localnet image's sui release.\n//   - 25: ubuntu:24.04 base — handled in the Dockerfile.\n\nimport { Effect, type Scope } from 'effect';\nimport { fileURLToPath } from 'node:url';\n\nimport type { ContainerRuntime } from '../../../contracts/container-runtime.ts';\nimport { readEnv } from '../../../substrate/runtime/typed-env.ts';\nimport { walrusPluginError, type WalrusPluginError } from '../errors.ts';\nimport { WalrusSpans } from '../spans.ts';\n\nconst WALRUS_CARGO_IMAGE_OVERRIDE_ENV = 'WALRUS_CARGO_IMAGE_OVERRIDE' as const;\n\n/** Pinned Walrus release whose native binaries are packaged into the\n *  local-cluster wrapper image. */\nexport const DEFAULT_WALRUS_REF = 'testnet-v1.49.1' as const;\n\n/** Distilled-doc invariant 24: the wrapper-baked sui binary must\n *  match the localnet image's sui release. Pinned here in lockstep\n *  with the walrus ref bump. */\nexport const DEFAULT_SUI_VERSION = 'devnet-v1.71.0' as const;\n\n/** Inputs to the walrus image resolver. */\nexport interface WalrusCargoImageInputs<Ref extends string = string, SuiV extends string = string> {\n\treadonly walrusRef: Ref;\n\treadonly suiVersion: SuiV;\n\t/** Owner identity stamped on the built image so label-driven prune\n\t *  finds it. */\n\treadonly owner: {\n\t\treadonly app: string;\n\t\treadonly stack: string;\n\t};\n}\n\n/** Resolved value — the content-addressed image ref. */\nexport interface WalrusCargoImageResolved {\n\treadonly digest: string;\n\treadonly tag: string;\n}\n\n// ---------------------------------------------------------------------------\n// Runtime resolver\n// ---------------------------------------------------------------------------\n\n/** Resolve to the on-disk path of the vendored Dockerfile context.\n *  `fileURLToPath` normalises the URL → host-path conversion across\n *  platforms (Windows `file:///C:/...` → `C:\\...`; POSIX strips the\n *  scheme and percent-decodes). Reading `.pathname` directly would\n *  leave the leading `/` on Windows. */\nconst vendoredDockerfileContext = (): string =>\n\tfileURLToPath(new URL('../../../../images/walrus/', import.meta.url));\n\n/** Resolve the walrus image. Path (a) trusts an env-override tag; path\n *  (b) builds the vendored Dockerfile via `runtime.ensureImage`.\n *\n *  `expectedTag`, when given, is the on-host tag the resolved image is\n *  published under (the build itself is content-cached, so multiple distinct\n *  tags of the SAME build are cheap re-tags). The storage-node committee uses\n *  this to give each node its OWN image tag — otherwise all N nodes share one\n *  tag and snapshot-restore's per-container image promote collapses N committed\n *  writable layers onto that single tag (last-write-wins), losing N-1 nodes'\n *  RocksDB. `ensureImage` reuses an existing tag without rebuilding, so a tag\n *  the restore already promoted to a committed layer is preserved on reboot. */\nexport const resolveCargoImage = (\n\truntime: ContainerRuntime,\n\tinputs: WalrusCargoImageInputs,\n\texpectedTag?: string,\n): Effect.Effect<WalrusCargoImageResolved, WalrusPluginError, Scope.Scope> =>\n\tEffect.gen(function* () {\n\t\tconst override = readEnv(WALRUS_CARGO_IMAGE_OVERRIDE_ENV);\n\t\tif (override && override.length > 0) {\n\t\t\t// Trust-the-tag path. The digest is opaque (substrate's\n\t\t\t// content-addressed cache will re-resolve via `docker inspect`\n\t\t\t// when it materializes the image). The per-node `expectedTag`\n\t\t\t// aliasing is build-path only (it relies on `ensureImage`'s\n\t\t\t// reuse-if-tag-exists to stay restore-safe across reboots);\n\t\t\t// override images keep the shared tag, so override + multi-node +\n\t\t\t// snapshot/restore is not committee-distinct (a documented niche —\n\t\t\t// the e2e matrix forces the build path).\n\t\t\treturn { digest: override, tag: override };\n\t\t}\n\n\t\t// Real build via the vendored Dockerfile.\n\t\tconst buildCtx = {\n\t\t\tcontextPath: vendoredDockerfileContext(),\n\t\t\tdockerfile: 'Dockerfile',\n\t\t\tbuildArgs: {\n\t\t\t\tWALRUS_VERSION: inputs.walrusRef,\n\t\t\t\tSUI_VERSION: inputs.suiVersion,\n\t\t\t},\n\t\t\towner: {\n\t\t\t\tapp: inputs.owner.app,\n\t\t\t\tstack: inputs.owner.stack,\n\t\t\t\tplugin: 'walrus',\n\t\t\t\trole: 'cluster',\n\t\t\t},\n\t\t};\n\n\t\t// `expected.tag`, when present, is the on-host tag ensureImage publishes\n\t\t// (and REUSES without rebuilding if it already exists — so a per-node tag\n\t\t// the restore promoted to a committed layer survives reboot). The build\n\t\t// itself is content-cached, so N per-node tags of one build are cheap.\n\t\tconst built = yield* runtime\n\t\t\t.ensureImage(\n\t\t\t\tbuildCtx,\n\t\t\t\texpectedTag !== undefined ? { digest: expectedTag, tag: expectedTag } : undefined,\n\t\t\t)\n\t\t\t.pipe(\n\t\t\t\tEffect.mapError((cause) =>\n\t\t\t\t\twalrusPluginError(\n\t\t\t\t\t\t'image-build',\n\t\t\t\t\t\t`walrus image build failed (walrusRef=${inputs.walrusRef}, suiVersion=${inputs.suiVersion}): ${cause.reason}: ${cause.detail}`,\n\t\t\t\t\t\t{ cause },\n\t\t\t\t\t),\n\t\t\t\t),\n\t\t\t);\n\t\treturn { digest: built.digest, tag: built.tag ?? built.digest };\n\t}).pipe(\n\t\tEffect.withSpan('devstack.plugin.walrus.cargoImage.resolve', {\n\t\t\tattributes: {\n\t\t\t\t[WalrusSpans.ref]: inputs.walrusRef,\n\t\t\t\t[WalrusSpans.suiVersion]: inputs.suiVersion,\n\t\t\t},\n\t\t}),\n\t);\n"],"mappings":";;;;;;AAkCA,MAAM,kCAAkC;;;AAIxC,MAAa,qBAAqB;;;;AAKlC,MAAa,sBAAsB;;;;;;AA6BnC,MAAM,kCACL,cAAc,IAAI,IAAI,8BAA8B,OAAO,KAAK,IAAI,CAAC;;;;;;;;;;;;AAatE,MAAa,qBACZ,SACA,QACA,gBAEA,OAAO,IAAI,aAAa;CACvB,MAAM,WAAW,QAAQ,gCAAgC;AACzD,KAAI,YAAY,SAAS,SAAS,EASjC,QAAO;EAAE,QAAQ;EAAU,KAAK;EAAU;CAI3C,MAAM,WAAW;EAChB,aAAa,2BAA2B;EACxC,YAAY;EACZ,WAAW;GACV,gBAAgB,OAAO;GACvB,aAAa,OAAO;GACpB;EACD,OAAO;GACN,KAAK,OAAO,MAAM;GAClB,OAAO,OAAO,MAAM;GACpB,QAAQ;GACR,MAAM;GACN;EACD;CAMD,MAAM,QAAQ,OAAO,QACnB,YACA,UACA,gBAAgB,KAAA,IAAY;EAAE,QAAQ;EAAa,KAAK;EAAa,GAAG,KAAA,EACxE,CACA,KACA,OAAO,UAAU,UAChB,kBACC,eACA,wCAAwC,OAAO,UAAU,eAAe,OAAO,WAAW,KAAK,MAAM,OAAO,IAAI,MAAM,UACtH,EAAE,OAAO,CACT,CACD,CACD;AACF,QAAO;EAAE,QAAQ,MAAM;EAAQ,KAAK,MAAM,OAAO,MAAM;EAAQ;EAC9D,CAAC,KACF,OAAO,SAAS,6CAA6C,EAC5D,YAAY;EACV,YAAY,MAAM,OAAO;EACzB,YAAY,aAAa,OAAO;CACjC,EACD,CAAC,CACF"}

package/dist/plugins/walrus/codegen.d.mts

@@ -21,9 +21,9 @@ interface WalrusBindings {
     readonly stakingPoolId: string;
     readonly exchangeIds?: ReadonlyArray<string>;
   };
-  /** HTTP URLs — present iff the publishing mode populated them
-   *  (local always; known only when all three are non-empty —
-   *  distilled-doc invariant 15). */
+  /** HTTP URLs — each is `null` only when that specific URL is
+   *  unresolved (local resolves all three; known surfaces each
+   *  independently — distilled-doc invariant 15). */
   readonly proxyUrl: string | null;
   readonly aggregatorUrl: string | null;
   readonly publisherUrl: string | null;

package/dist/plugins/walrus/codegen.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/walrus/codegen.ts"],"sourcesContent":["// Walrus plugin — Codegenable contribution.\n//\n// Architecture §6: plugins emit typed `CodegenableDecl`s; the codegen\n// orchestrator stages files into the user's source tree WITHOUT\n// naming the plugin. Walrus's contribution is the SDK-ready\n// `packageConfig` shape that the `@mysten/walrus` SDK consumes —\n// `{systemObjectId, stakingPoolId, exchangeIds}` — plus the proxy /\n// aggregator / publisher URLs for HTTP consumers.\n//\n// Distilled-doc opportunity #8: the v3 `localnetWalrusOptions` couples\n// to a free-form cast. We surface the bindings here as a typed\n// `WalrusBindings` shape so downstream code can `import { walrus }`\n// from the codegen-staged file and get a fully-typed handle.\n//\n// Mode-asymmetric emission:\n//   - Local: emits `{packageConfig, proxyUrl, aggregatorUrl,\n//     publisherUrl, nodes}` — full shape.\n//   - Known: emits `{packageConfig, proxyUrl?, aggregatorUrl?,\n//     publisherUrl?}` — the proxy URLs are optional because the\n//     contract only publishes them when ALL three are present\n//     (distilled-doc invariant 15).\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\n/** Per-node descriptor — matches the storage-nodes module's shape\n *  for the local-cluster path, and is empty (or whatever the user\n *  provides) for known. */\nexport interface WalrusNodeBinding {\n\treadonly nodeIndex: number;\n\treadonly publicHostname: string;\n\treadonly rpcUrl: string;\n}\n\n/** The typed shape the emitted file exports. */\nexport interface WalrusBindings {\n\treadonly mode: 'local' | 'known';\n\treadonly chain: string;\n\treadonly walrusPackageId: string | null;\n\treadonly walPackageId: string | null;\n\treadonly walCoinType: string | null;\n\t/** SDK-ready `packageConfig` — structurally compatible with\n\t *  `@mysten/walrus`'s `WalrusPackageConfig`. */\n\treadonly packageConfig: {\n\t\treadonly systemObjectId: string;\n\t\treadonly stakingPoolId: string;\n\t\treadonly exchangeIds?: ReadonlyArray<string>;\n\t};\n\t/** HTTP URLs — present iff the publishing mode populated them\n\t *  (local always; known only when all three are non-empty —\n\t *  distilled-doc invariant 15). */\n\treadonly proxyUrl: string | null;\n\treadonly aggregatorUrl: string | null;\n\treadonly publisherUrl: string | null;\n\t/** Storage-node committee — local publishes N descriptors; known\n\t *  publishes user-supplied nodes (testnet/mainnet's 100+ nodes\n\t *  are fetched dynamically by the SDK, not pinned here —\n\t *  distilled-doc invariant 16). */\n\treadonly nodes: ReadonlyArray<WalrusNodeBinding>;\n}\n\n/** Inputs to the codegen contribution — supplied at acquire-time.\n *  The codegen orchestrator's resolve-once memo picks up the real\n *  values via the dynamic capability factory (same shape used by\n *  Sui + Account: the factory stamps placeholders at compose-time\n *  and the post-acquire factory restamps with resolved fields). */\nexport interface MakeCodegenableInputs {\n\treadonly mode: 'local' | 'known';\n\treadonly chain: string;\n\treadonly walrusPackageId: string | null;\n\treadonly walPackageId: string | null;\n\treadonly walCoinType: string | null;\n\treadonly systemObjectId: string;\n\treadonly stakingPoolId: string;\n\treadonly exchangeIds: ReadonlyArray<string>;\n\treadonly proxyUrl: string | null;\n\treadonly aggregatorUrl: string | null;\n\treadonly publisherUrl: string | null;\n\treadonly nodes: ReadonlyArray<WalrusNodeBinding>;\n}\n\n/** Construct the Codegenable contribution. Emit is byte-deterministic\n *  on unchanged input (architecture: no mtime churn on no-op\n *  cycles). */\nexport const makeCodegenable = (\n\tinputs: MakeCodegenableInputs,\n): CodegenableDecl<'walrus-network'> => ({\n\tkind: 'codegenable',\n\temitterName: 'walrus-network',\n\toutputPath: 'walrus/network.ts',\n\temit: (ctx) =>\n\t\tEffect.sync(() => {\n\t\t\tconst bindings: WalrusBindings = {\n\t\t\t\tmode: inputs.mode,\n\t\t\t\tchain: inputs.chain,\n\t\t\t\twalrusPackageId: inputs.walrusPackageId,\n\t\t\t\twalPackageId: inputs.walPackageId,\n\t\t\t\twalCoinType: inputs.walCoinType,\n\t\t\t\tpackageConfig: {\n\t\t\t\t\tsystemObjectId: inputs.systemObjectId,\n\t\t\t\t\tstakingPoolId: inputs.stakingPoolId,\n\t\t\t\t\texchangeIds: inputs.exchangeIds.length > 0 ? inputs.exchangeIds : undefined,\n\t\t\t\t},\n\t\t\t\tproxyUrl: inputs.proxyUrl,\n\t\t\t\taggregatorUrl: inputs.aggregatorUrl,\n\t\t\t\tpublisherUrl: inputs.publisherUrl,\n\t\t\t\tnodes: inputs.nodes,\n\t\t\t};\n\t\t\tctx.exportConst('walrus', bindings);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n"],"mappings":";;;;;AAqFA,MAAa,mBACZ,YACwC;CACxC,MAAM;CACN,aAAa;CACb,YAAY;CACZ,OAAO,QACN,OAAO,WAAW;EACjB,MAAM,WAA2B;GAChC,MAAM,OAAO;GACb,OAAO,OAAO;GACd,iBAAiB,OAAO;GACxB,cAAc,OAAO;GACrB,aAAa,OAAO;GACpB,eAAe;IACd,gBAAgB,OAAO;IACvB,eAAe,OAAO;IACtB,aAAa,OAAO,YAAY,SAAS,IAAI,OAAO,cAAc,KAAA;IAClE;GACD,UAAU,OAAO;GACjB,eAAe,OAAO;GACtB,cAAc,OAAO;GACrB,OAAO,OAAO;GACd;AACD,MAAI,YAAY,UAAU,SAAS;AACnC,SAAO,IAAI,MAAM;GAChB;CACH"}
+{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/walrus/codegen.ts"],"sourcesContent":["// Walrus plugin — Codegenable contribution.\n//\n// Architecture §6: plugins emit typed `CodegenableDecl`s; the codegen\n// orchestrator stages files into the user's source tree WITHOUT\n// naming the plugin. Walrus's contribution is the SDK-ready\n// `packageConfig` shape that the `@mysten/walrus` SDK consumes —\n// `{systemObjectId, stakingPoolId, exchangeIds}` — plus the proxy /\n// aggregator / publisher URLs for HTTP consumers.\n//\n// Distilled-doc opportunity #8: the v3 `localnetWalrusOptions` couples\n// to a free-form cast. We surface the bindings here as a typed\n// `WalrusBindings` shape so downstream code can `import { walrus }`\n// from the codegen-staged file and get a fully-typed handle.\n//\n// Mode-asymmetric emission:\n//   - Local: emits `{packageConfig, proxyUrl, aggregatorUrl,\n//     publisherUrl, nodes}` — full shape (all three URLs resolved).\n//   - Known: emits the same shape; each of `proxyUrl /\n//     aggregatorUrl / publisherUrl` is `string | null` and surfaces\n//     INDEPENDENTLY — a field is null only when THAT specific URL is\n//     unresolved (distilled-doc invariant 15). A missing publisher\n//     URL no longer suppresses an available proxy/aggregator URL.\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\n/** Per-node descriptor — matches the storage-nodes module's shape\n *  for the local-cluster path, and is empty (or whatever the user\n *  provides) for known. */\nexport interface WalrusNodeBinding {\n\treadonly nodeIndex: number;\n\treadonly publicHostname: string;\n\treadonly rpcUrl: string;\n}\n\n/** The typed shape the emitted file exports. */\nexport interface WalrusBindings {\n\treadonly mode: 'local' | 'known';\n\treadonly chain: string;\n\treadonly walrusPackageId: string | null;\n\treadonly walPackageId: string | null;\n\treadonly walCoinType: string | null;\n\t/** SDK-ready `packageConfig` — structurally compatible with\n\t *  `@mysten/walrus`'s `WalrusPackageConfig`. */\n\treadonly packageConfig: {\n\t\treadonly systemObjectId: string;\n\t\treadonly stakingPoolId: string;\n\t\treadonly exchangeIds?: ReadonlyArray<string>;\n\t};\n\t/** HTTP URLs — each is `null` only when that specific URL is\n\t *  unresolved (local resolves all three; known surfaces each\n\t *  independently — distilled-doc invariant 15). */\n\treadonly proxyUrl: string | null;\n\treadonly aggregatorUrl: string | null;\n\treadonly publisherUrl: string | null;\n\t/** Storage-node committee — local publishes N descriptors; known\n\t *  publishes user-supplied nodes (testnet/mainnet's 100+ nodes\n\t *  are fetched dynamically by the SDK, not pinned here —\n\t *  distilled-doc invariant 16). */\n\treadonly nodes: ReadonlyArray<WalrusNodeBinding>;\n}\n\n/** Inputs to the codegen contribution — supplied at acquire-time.\n *  The codegen orchestrator's resolve-once memo picks up the real\n *  values via the dynamic capability factory (same shape used by\n *  Sui + Account: the factory stamps placeholders at compose-time\n *  and the post-acquire factory restamps with resolved fields). */\nexport interface MakeCodegenableInputs {\n\treadonly mode: 'local' | 'known';\n\treadonly chain: string;\n\treadonly walrusPackageId: string | null;\n\treadonly walPackageId: string | null;\n\treadonly walCoinType: string | null;\n\treadonly systemObjectId: string;\n\treadonly stakingPoolId: string;\n\treadonly exchangeIds: ReadonlyArray<string>;\n\treadonly proxyUrl: string | null;\n\treadonly aggregatorUrl: string | null;\n\treadonly publisherUrl: string | null;\n\treadonly nodes: ReadonlyArray<WalrusNodeBinding>;\n}\n\n/** Construct the Codegenable contribution. Emit is byte-deterministic\n *  on unchanged input (architecture: no mtime churn on no-op\n *  cycles). */\nexport const makeCodegenable = (\n\tinputs: MakeCodegenableInputs,\n): CodegenableDecl<'walrus-network'> => ({\n\tkind: 'codegenable',\n\temitterName: 'walrus-network',\n\toutputPath: 'walrus/network.ts',\n\temit: (ctx) =>\n\t\tEffect.sync(() => {\n\t\t\tconst bindings: WalrusBindings = {\n\t\t\t\tmode: inputs.mode,\n\t\t\t\tchain: inputs.chain,\n\t\t\t\twalrusPackageId: inputs.walrusPackageId,\n\t\t\t\twalPackageId: inputs.walPackageId,\n\t\t\t\twalCoinType: inputs.walCoinType,\n\t\t\t\tpackageConfig: {\n\t\t\t\t\tsystemObjectId: inputs.systemObjectId,\n\t\t\t\t\tstakingPoolId: inputs.stakingPoolId,\n\t\t\t\t\texchangeIds: inputs.exchangeIds.length > 0 ? inputs.exchangeIds : undefined,\n\t\t\t\t},\n\t\t\t\tproxyUrl: inputs.proxyUrl,\n\t\t\t\taggregatorUrl: inputs.aggregatorUrl,\n\t\t\t\tpublisherUrl: inputs.publisherUrl,\n\t\t\t\tnodes: inputs.nodes,\n\t\t\t};\n\t\t\tctx.exportConst('walrus', bindings);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n"],"mappings":";;;;;AAsFA,MAAa,mBACZ,YACwC;CACxC,MAAM;CACN,aAAa;CACb,YAAY;CACZ,OAAO,QACN,OAAO,WAAW;EACjB,MAAM,WAA2B;GAChC,MAAM,OAAO;GACb,OAAO,OAAO;GACd,iBAAiB,OAAO;GACxB,cAAc,OAAO;GACrB,aAAa,OAAO;GACpB,eAAe;IACd,gBAAgB,OAAO;IACvB,eAAe,OAAO;IACtB,aAAa,OAAO,YAAY,SAAS,IAAI,OAAO,cAAc,KAAA;IAClE;GACD,UAAU,OAAO;GACjB,eAAe,OAAO;GACtB,cAAc,OAAO;GACrB,OAAO,OAAO;GACd;AACD,MAAI,YAAY,UAAU,SAAS;AACnC,SAAO,IAAI,MAAM;GAChB;CACH"}

package/dist/plugins/walrus/deploy-paths.mjs

@@ -1,11 +1,27 @@
-import { dirname, join, relative } from "node:path";
+import { join, relative } from "node:path";
 //#region src/plugins/walrus/deploy-paths.ts
-const walrusDeployMountPaths = (deployOutputDirHostPath, mountTarget) => {
-	const sourceHostPath = dirname(dirname(dirname(deployOutputDirHostPath)));
+/** Compute the bind-mount triple shared by the walrus deploy
+*  one-shot + storage nodes.
+*
+*  Previous implementation walked up exactly three levels with
+*  `dirname(dirname(dirname(deployOutputDirHostPath)))`. A shorter
+*  input (e.g. a single-segment path under `/`) would silently
+*  return `/`, and the bind-mount would mount the host root into
+*  the container — a load-bearing footgun. We now require the
+*  caller to pass `stackRoot` explicitly (matching the existing
+*  `paths.stackRoot` injection pattern across the postgres / sui /
+*  seal / wallet plugins) and assert the deploy dir lives under it.
+*
+*  The mount source is `stackRoot`; the in-container path is
+*  re-derived through `relative(stackRoot, deployOutputDirHostPath)`. */
+const walrusDeployMountPaths = (input) => {
+	const { stackRoot, deployOutputDirHostPath, mountTarget } = input;
+	const rel = relative(stackRoot, deployOutputDirHostPath);
+	if (rel.length === 0 || rel.startsWith("..")) throw new Error(`walrusDeployMountPaths: deployOutputDirHostPath (${deployOutputDirHostPath}) must be a descendant of stackRoot (${stackRoot}). Cross-check the StackPathsService thread + the deploy directory layout.`);
 	return {
-		sourceHostPath,
+		sourceHostPath: stackRoot,
 		mountTarget,
-		outputDirInContainer: join(mountTarget, relative(sourceHostPath, deployOutputDirHostPath))
+		outputDirInContainer: join(mountTarget, rel)
 	};
 };
 //#endregion

package/dist/plugins/walrus/deploy-paths.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"deploy-paths.mjs","names":[],"sources":["../../../src/plugins/walrus/deploy-paths.ts"],"sourcesContent":["import { dirname, join, relative } from 'node:path';\n\nexport interface WalrusDeployMountPaths {\n\treadonly sourceHostPath: string;\n\treadonly mountTarget: string;\n\treadonly outputDirInContainer: string;\n}\n\nexport const walrusDeployMountPaths = (\n\tdeployOutputDirHostPath: string,\n\tmountTarget: string,\n): WalrusDeployMountPaths => {\n\tconst sourceHostPath = dirname(dirname(dirname(deployOutputDirHostPath)));\n\tconst outputDirInContainer = join(mountTarget, relative(sourceHostPath, deployOutputDirHostPath));\n\treturn { sourceHostPath, mountTarget, outputDirInContainer };\n};\n"],"mappings":";;AAQA,MAAa,0BACZ,yBACA,gBAC4B;CAC5B,MAAM,iBAAiB,QAAQ,QAAQ,QAAQ,wBAAwB,CAAC,CAAC;AAEzE,QAAO;EAAE;EAAgB;EAAa,sBADT,KAAK,aAAa,SAAS,gBAAgB,wBAAwB,CACtC;EAAE"}
+{"version":3,"file":"deploy-paths.mjs","names":[],"sources":["../../../src/plugins/walrus/deploy-paths.ts"],"sourcesContent":["import { join, relative } from 'node:path';\n\nexport interface WalrusDeployMountPaths {\n\treadonly sourceHostPath: string;\n\treadonly mountTarget: string;\n\treadonly outputDirInContainer: string;\n}\n\n/** Compute the bind-mount triple shared by the walrus deploy\n *  one-shot + storage nodes.\n *\n *  Previous implementation walked up exactly three levels with\n *  `dirname(dirname(dirname(deployOutputDirHostPath)))`. A shorter\n *  input (e.g. a single-segment path under `/`) would silently\n *  return `/`, and the bind-mount would mount the host root into\n *  the container — a load-bearing footgun. We now require the\n *  caller to pass `stackRoot` explicitly (matching the existing\n *  `paths.stackRoot` injection pattern across the postgres / sui /\n *  seal / wallet plugins) and assert the deploy dir lives under it.\n *\n *  The mount source is `stackRoot`; the in-container path is\n *  re-derived through `relative(stackRoot, deployOutputDirHostPath)`. */\nexport const walrusDeployMountPaths = (input: {\n\treadonly stackRoot: string;\n\treadonly deployOutputDirHostPath: string;\n\treadonly mountTarget: string;\n}): WalrusDeployMountPaths => {\n\tconst { stackRoot, deployOutputDirHostPath, mountTarget } = input;\n\tconst rel = relative(stackRoot, deployOutputDirHostPath);\n\tif (rel.length === 0 || rel.startsWith('..')) {\n\t\tthrow new Error(\n\t\t\t`walrusDeployMountPaths: deployOutputDirHostPath (${deployOutputDirHostPath}) ` +\n\t\t\t\t`must be a descendant of stackRoot (${stackRoot}). ` +\n\t\t\t\t`Cross-check the StackPathsService thread + the deploy directory layout.`,\n\t\t);\n\t}\n\tconst outputDirInContainer = join(mountTarget, rel);\n\treturn { sourceHostPath: stackRoot, mountTarget, outputDirInContainer };\n};\n"],"mappings":";;;;;;;;;;;;;;;;AAsBA,MAAa,0BAA0B,UAIT;CAC7B,MAAM,EAAE,WAAW,yBAAyB,gBAAgB;CAC5D,MAAM,MAAM,SAAS,WAAW,wBAAwB;AACxD,KAAI,IAAI,WAAW,KAAK,IAAI,WAAW,KAAK,CAC3C,OAAM,IAAI,MACT,oDAAoD,wBAAwB,uCACrC,UAAU,4EAEjD;AAGF,QAAO;EAAE,gBAAgB;EAAW;EAAa,sBADpB,KAAK,aAAa,IACsB;EAAE"}