@mysten-incubation/devstack 0.0.0

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

@@ -0,0 +1 @@
+{"version":3,"file":"codegen.mjs","names":[],"sources":["../../../src/plugins/wallet/codegen.ts"],"sourcesContent":["// Wallet plugin — Codegenable contribution.\n//\n// Architecture (15-wallet.md §\"Capabilities PRODUCED\" + §\"Codegen\n// emits a `dapp-kit-config.ts`\"):\n//\n//   - The browser-side dev-wallet adapter is the cross-boundary\n//     consumer. It reads a typed `dapp-kit-config` value at startup,\n//     constructs a `DevstackSignerAdapter`, and registers it with\n//     `@mysten/dapp-kit`'s wallet-standard surface (in user-app\n//     bundle code — devstack itself NEVER imports dapp-kit).\n//\n//   - The emitted file lives at `dapp-kit/config.ts` under the staging\n//     dir. The generated module owns the exported config value's type.\n//\n// SENSITIVE FLAG (task requirement #5 — manifest-vs-token threat\n// surface):\n//\n//   - The emitted file carries the unredacted pair URL (incl. the\n//     `#token=<32-hex>` fragment) so the dev-wallet adapter can wire\n//     itself up without a side-channel read.\n//   - Therefore `sensitive: true`. The codegen orchestrator tightens\n//     the file mode to `0o600` on emit AND injects the file path into\n//     `.gitignore`.\n//\n// Distilled-doc tension absorbed (15-wallet.md \"Manifest carries\n// unredacted pair URL while token file is 0o600 — pick one\"):\n//\n//   We pick \"tighten the emit perms\". The token still lives in a\n//   `0o600` side-channel file (see `pairing.ts:tokenPath`), AND the\n//   codegen emit is also `0o600` via the sensitive flag. The legacy\n//   `.devstack/manifest.json` write that left the pair URL world-\n//   readable is GONE — the rewrite no longer emits an unredacted pair\n//   URL into the manifest. Only the codegen file carries it, and that\n//   file is tightened.\n//\n//   See the report's §\"Architecture-doc revisions\" for the\n//   architecture-doc note that needs to land alongside this.\n\nimport { Effect } from 'effect';\n\nimport type { CodegenableDecl } from '../../contracts/codegenable.ts';\n\nimport { redactToken } from './pairing.ts';\n\n// ----------------------------------------------------------------------\n// Emitted shape\n// ----------------------------------------------------------------------\n\n/** The typed shape `dapp-kit/config.ts` exports. Downstream consumers\n *  (the user-app's dapp-kit boot code) import and consume this.\n *\n *  Field shape mirrors what `DevstackSignerAdapter` needs:\n *\n *    - `walletUrl`     : the wallet HTTP server's URL (router-fronted\n *                        host form when available, direct-loopback\n *                        fallback otherwise).\n *    - `pairUrl`       : `walletUrl` + `/#token=<32-hex>` (single\n *                        source of truth for the token).\n *    - `protocolPaths` : path constants the adapter reads. Mirrored\n *                        here so the adapter doesn't depend on a\n *                        separate import.\n *    - `chain`         : Sui chain id the wallet's accounts are\n *                        scoped to. Surfaced so dapp-kit can pin its\n *                        active chain.\n */\nexport interface DappKitConfigBindings {\n\treadonly walletUrl: string;\n\treadonly pairUrl: string;\n\treadonly chain: string;\n\treadonly protocolPaths: {\n\t\treadonly health: string;\n\t\treadonly accounts: string;\n\t\treadonly signTransaction: string;\n\t\treadonly signPersonalMessage: string;\n\t\treadonly execute: string;\n\t};\n}\n\n// ----------------------------------------------------------------------\n// Decl construction\n// ----------------------------------------------------------------------\n\n/**\n * Construct the Codegenable contribution.\n *\n *  Emits `dapp-kit/config.ts` with `sensitive: true` → the orchestrator\n *  writes the file with `0o600` and gitignores it. The emitted shape\n *  carries the unredacted pair URL; the side-channel token file is\n *  also `0o600`.\n *\n *  The `resolved` arg is supplied AFTER acquire (the substrate's\n *  \"resolve-once\" memo). At factory time the barrel passes a\n *  placeholder so the type plumbing works; at codegen time the\n *  substrate re-evaluates with the resolved values.\n */\nexport const makeWalletCodegen = (\n\tresolved: DappKitConfigBindings,\n): CodegenableDecl<'dapp-kit-config'> => ({\n\tkind: 'codegenable',\n\temitterName: 'dapp-kit-config',\n\toutputPath: 'dapp-kit/config.ts',\n\t// SENSITIVE: drives 0o600 + .gitignore. The architecture has this\n\t// hook (`SnapshotableDecl` mirrors it for the snapshot subtree).\n\tsensitive: true,\n\temit: (ctx) =>\n\t\tEffect.gen(function* () {\n\t\t\t// Span annotation logs ONLY the redacted form — defense-in-\n\t\t\t// depth so any debug-mode span dump doesn't leak the token.\n\t\t\tyield* Effect.annotateCurrentSpan({\n\t\t\t\t'wallet.codegen.pairUrl': redactToken(resolved.pairUrl),\n\t\t\t\t'wallet.codegen.walletUrl': resolved.walletUrl,\n\t\t\t});\n\t\t\tctx.exportConst('dappKitConfig', resolved);\n\t\t\treturn ctx.done();\n\t\t}),\n});\n"],"mappings":";;;;;;;;;;;;;;;;AA+FA,MAAa,qBACZ,cACyC;CACzC,MAAM;CACN,aAAa;CACb,YAAY;CAGZ,WAAW;CACX,OAAO,QACN,OAAO,IAAI,aAAa;AAGvB,SAAO,OAAO,oBAAoB;GACjC,0BAA0B,YAAY,SAAS,QAAQ;GACvD,4BAA4B,SAAS;GACrC,CAAC;AACF,MAAI,YAAY,iBAAiB,SAAS;AAC1C,SAAO,IAAI,MAAM;GAChB;CACH"}

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

@@ -0,0 +1,66 @@
+//#region src/plugins/wallet/errors.d.ts
+/**
+ * Phases for `WalletBootError`. Closed sum — adding a phase means
+ * editing this list AND any cause-walker display tables.
+ *
+ *  - `listen`            : `http.Server.listen` rejected (typically
+ *                          EADDRINUSE after port-broker forward-scan, or
+ *                          EACCES on a privileged port).
+ *  - `allocate-port`     : the supervisor's port broker could not yield
+ *                          a free port near the preferred one.
+ *  - `read-token`        : the on-disk pairing-token file existed but
+ *                          could not be read (EACCES, EIO).
+ *  - `write-token`       : the freshly-minted token file could not be
+ *                          persisted (ENOSPC, EROFS).
+ *  - `bind-account`      : a consumed account tag failed to resolve at
+ *                          acquire time (re-thrown with a wallet phase).
+ *  - `route-url`         : failed to construct the router-fronted URL
+ *                          for the generated dapp-kit config.
+ *  - `no-accounts`       : account inference resolved to an empty set.
+ */
+type WalletBootPhase = 'listen' | 'allocate-port' | 'read-token' | 'write-token' | 'bind-account' | 'route-url' | 'no-accounts';
+/** Boot-time wallet error — raised by the plugin's acquire body. */
+interface WalletBootError {
+  readonly _tag: 'WalletBootError';
+  readonly phase: WalletBootPhase;
+  readonly message: string;
+  readonly hint?: string;
+  readonly cause?: unknown;
+}
+/**
+ * Phases for `WalletRequestError`. Each maps to an HTTP status the
+ * server emits (status code carried explicitly so renderers can keep
+ * the mapping in one place rather than re-deriving it).
+ *
+ *  - `origin-missing`        : 403 — no Origin header on a protected
+ *                              route (closes the curl/non-browser
+ *                              bypass; mandatory by C12).
+ *  - `origin-forbidden`      : 403 — Origin not in the stack-scoped
+ *                              allowlist.
+ *  - `unauthorized`          : 401 — bearer absent or did not survive
+ *                              constant-time compare.
+ *  - `route-not-found`       : 404 — `/api/v1/devstack/*` path with no
+ *                              handler wired.
+ *  - `address-not-found`     : 404 — sign request named an address the
+ *                              wallet did not bind.
+ *  - `body-invalid`          : 400 — JSON parse, missing required
+ *                              field, non-base64 bytes, body >64 KiB.
+ *  - `sign-route-failed`     : 500 — the routed `AccountValue` sign
+ *                              closure raised an `AccountSignError`.
+ */
+type WalletRequestPhase = 'origin-missing' | 'origin-forbidden' | 'unauthorized' | 'route-not-found' | 'address-not-found' | 'body-invalid' | 'sign-route-failed';
+/** Request-time wallet error — raised by the in-process HTTP handlers.
+ *  Carries the HTTP status the server will write and an optional inner
+ *  cause (e.g. an `AccountSignError` for `sign-route-failed`). */
+interface WalletRequestError {
+  readonly _tag: 'WalletRequestError';
+  readonly phase: WalletRequestPhase;
+  readonly httpStatus: number;
+  readonly message: string;
+  readonly cause?: unknown;
+}
+/** Union of every error a wallet caller may encounter. */
+type WalletError = WalletBootError | WalletRequestError;
+//#endregion
+export { WalletBootError, WalletBootPhase, WalletError, WalletRequestError, WalletRequestPhase };
+//# sourceMappingURL=errors.d.mts.map

package/dist/plugins/wallet/errors.mjs

@@ -0,0 +1,16 @@
+//#region src/plugins/wallet/errors.ts
+const walletBootError = (parts) => ({
+	_tag: "WalletBootError",
+	...parts
+});
+const walletRequestError = (parts) => ({
+	_tag: "WalletRequestError",
+	...parts
+});
+/** Error tags this plugin contributes — surfaced to the cause walker
+*  via `PluginErrorContribution`. */
+const WALLET_ERROR_TAGS = ["WalletBootError", "WalletRequestError"];
+//#endregion
+export { WALLET_ERROR_TAGS, walletBootError, walletRequestError };
+
+//# sourceMappingURL=errors.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../src/plugins/wallet/errors.ts"],"sourcesContent":["// Wallet plugin — typed errors.\n//\n// Distilled-doc finding (15-wallet.md \"Failure modes\"): the wallet's\n// failure surface separates BOOT-time errors from REQUEST-time errors.\n// Boot errors surface as `WalletBootError` (port allocation, listen\n// failure, token-file write); request errors surface as\n// `WalletRequestError` (auth, origin, route, body parse, sign-route\n// failure). The two channels never mix — request errors flow back to\n// the HTTP client as JSON envelopes, boot errors flow up the supervisor\n// scope.\n//\n// Effect v4: plain interface + `_tag` literal discriminator (no\n// subclassing). Per-plugin tagged-error convention — the cause walker\n// dispatches on `_tag`.\n\n/**\n * Phases for `WalletBootError`. Closed sum — adding a phase means\n * editing this list AND any cause-walker display tables.\n *\n *  - `listen`            : `http.Server.listen` rejected (typically\n *                          EADDRINUSE after port-broker forward-scan, or\n *                          EACCES on a privileged port).\n *  - `allocate-port`     : the supervisor's port broker could not yield\n *                          a free port near the preferred one.\n *  - `read-token`        : the on-disk pairing-token file existed but\n *                          could not be read (EACCES, EIO).\n *  - `write-token`       : the freshly-minted token file could not be\n *                          persisted (ENOSPC, EROFS).\n *  - `bind-account`      : a consumed account tag failed to resolve at\n *                          acquire time (re-thrown with a wallet phase).\n *  - `route-url`         : failed to construct the router-fronted URL\n *                          for the generated dapp-kit config.\n *  - `no-accounts`       : account inference resolved to an empty set.\n */\nexport type WalletBootPhase =\n\t| 'listen'\n\t| 'allocate-port'\n\t| 'read-token'\n\t| 'write-token'\n\t| 'bind-account'\n\t| 'route-url'\n\t| 'no-accounts';\n\n/** Boot-time wallet error — raised by the plugin's acquire body. */\nexport interface WalletBootError {\n\treadonly _tag: 'WalletBootError';\n\treadonly phase: WalletBootPhase;\n\treadonly message: string;\n\treadonly hint?: string;\n\treadonly cause?: unknown;\n}\n\nexport const walletBootError = (parts: Omit<WalletBootError, '_tag'>): WalletBootError => ({\n\t_tag: 'WalletBootError',\n\t...parts,\n});\n\n/**\n * Phases for `WalletRequestError`. Each maps to an HTTP status the\n * server emits (status code carried explicitly so renderers can keep\n * the mapping in one place rather than re-deriving it).\n *\n *  - `origin-missing`        : 403 — no Origin header on a protected\n *                              route (closes the curl/non-browser\n *                              bypass; mandatory by C12).\n *  - `origin-forbidden`      : 403 — Origin not in the stack-scoped\n *                              allowlist.\n *  - `unauthorized`          : 401 — bearer absent or did not survive\n *                              constant-time compare.\n *  - `route-not-found`       : 404 — `/api/v1/devstack/*` path with no\n *                              handler wired.\n *  - `address-not-found`     : 404 — sign request named an address the\n *                              wallet did not bind.\n *  - `body-invalid`          : 400 — JSON parse, missing required\n *                              field, non-base64 bytes, body >64 KiB.\n *  - `sign-route-failed`     : 500 — the routed `AccountValue` sign\n *                              closure raised an `AccountSignError`.\n */\nexport type WalletRequestPhase =\n\t| 'origin-missing'\n\t| 'origin-forbidden'\n\t| 'unauthorized'\n\t| 'route-not-found'\n\t| 'address-not-found'\n\t| 'body-invalid'\n\t| 'sign-route-failed';\n\n/** Request-time wallet error — raised by the in-process HTTP handlers.\n *  Carries the HTTP status the server will write and an optional inner\n *  cause (e.g. an `AccountSignError` for `sign-route-failed`). */\nexport interface WalletRequestError {\n\treadonly _tag: 'WalletRequestError';\n\treadonly phase: WalletRequestPhase;\n\treadonly httpStatus: number;\n\treadonly message: string;\n\treadonly cause?: unknown;\n}\n\nexport const walletRequestError = (\n\tparts: Omit<WalletRequestError, '_tag'>,\n): WalletRequestError => ({ _tag: 'WalletRequestError', ...parts });\n\n/** Union of every error a wallet caller may encounter. */\nexport type WalletError = WalletBootError | WalletRequestError;\n\n/** Error tags this plugin contributes — surfaced to the cause walker\n *  via `PluginErrorContribution`. */\nexport const WALLET_ERROR_TAGS: ReadonlyArray<WalletError['_tag']> = [\n\t'WalletBootError',\n\t'WalletRequestError',\n] as const;\n"],"mappings":";AAoDA,MAAa,mBAAmB,WAA2D;CAC1F,MAAM;CACN,GAAG;CACH;AA2CD,MAAa,sBACZ,WACyB;CAAE,MAAM;CAAsB,GAAG;CAAO;;;AAOlE,MAAa,oBAAwD,CACpE,mBACA,qBACA"}

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

@@ -0,0 +1,63 @@
+import { CodegenableDecl } from "../../contracts/codegenable.mjs";
+import { RoutableDecl } from "../../contracts/routable.mjs";
+import { SnapshotableDecl } from "../../contracts/snapshotable.mjs";
+import { Plugin, ResourceRef } from "../../substrate/plugin.mjs";
+import { SeedObjectsAccumulator } from "../sui/seed-objects.mjs";
+import { SuiClient } from "../sui/mode/shared.mjs";
+import { SuiOptions } from "../sui/mode/spec.mjs";
+import { DappKitConfigBindings } from "./codegen.mjs";
+import { WalletBootError, WalletBootPhase, WalletError, WalletRequestError, WalletRequestPhase } from "./errors.mjs";
+import { PairingToken } from "./pairing.mjs";
+import { WalletServerHandle } from "./server.mjs";
+import { WALLET_ACCOUNTS_ALL, WalletAccountMember, WalletOptions, WalletValue } from "./service.mjs";
+//#region src/plugins/wallet/index.d.ts
+/**
+ * Construct the wallet plugin.
+ *
+ * Two parts of the wallet:
+ *
+ *   - HERE: HTTP server + token + pairing protocol + codegen.
+ *   - DEV-WALLET PACKAGE: `@mysten/dapp-kit`-shaped adapter the
+ *     user-app's frontend bundle imports.
+ *
+ *  Distilled-doc invariant (15-wallet.md "Always explicit"): the
+ *  composer NEVER auto-mounts the wallet. The user calls `wallet()`,
+ *  `wallet({ accounts: 'all' })`, or `wallet({ accounts: [alice, bob] })`
+ *  and passes the result to `defineDevstack(...)`.
+ *
+ *  ### Security defaults
+ *
+ *   - `bindAddress: '0.0.0.0'`. The router runs in Docker, so on
+ *     native Linux it reaches this host process through the Docker
+ *     host-gateway address instead of host loopback. The published
+ *     wallet URL remains stack-scoped through the router.
+ *
+ *   - `allowLocalhostVite: false`. The bare `http://localhost:<vite>`
+ *     form is OFF by default — opt-in for headless test runners /
+ *     custom dev hosts. Defaulting it on would let a sibling stack
+ *     running vite on the same port pair with this wallet (because
+ *     `localhost` is not stack-scoped). See `origin-policy.ts` for
+ *     the rationale.
+ *
+ *   - Pairing token in URL fragment only (`#token=<32-hex>`). Never
+ *     in query params (would land in access logs / referrers).
+ *
+ *   - Constant-time bearer compare on every request.
+ *
+ *   - Token file `0o600`. Codegen output (`dapp-kit/config.ts`)
+ *     `0o600` + gitignored via `sensitive: true`.
+ */
+declare function wallet<const Accounts extends ReadonlyArray<WalletAccountMember>>(opts: Omit<WalletOptions, 'accounts'> & {
+  readonly accounts: Accounts;
+}): ReturnType<typeof makeWalletMember<Accounts>>;
+declare function wallet(opts: Omit<WalletOptions, 'accounts'> & {
+  readonly accounts: typeof WALLET_ACCOUNTS_ALL;
+}): ReturnType<typeof makeWalletMember<readonly []>>;
+declare function wallet(): ReturnType<typeof makeWalletMember<readonly []>>;
+declare function makeWalletMember<Accounts extends ReadonlyArray<WalletAccountMember>>(opts: WalletOptions, accounts: Accounts): Plugin<"wallet", WalletValue, readonly [ResourceRef<"sui", SuiClient & {
+  readonly mode: SuiOptions["mode"];
+  readonly seedObjects: SeedObjectsAccumulator;
+}>, ...Accounts], readonly [SnapshotableDecl, CodegenableDecl<"dapp-kit-config">, RoutableDecl]>;
+//#endregion
+export { wallet };
+//# sourceMappingURL=index.d.mts.map

package/dist/plugins/wallet/index.mjs

@@ -0,0 +1,126 @@
+import { definePlugin, resource } from "../../substrate/plugin.mjs";
+import { pluginErrorContributions } from "../../api/plugin-errors.mjs";
+import { IdentityContext, StackPathsService } from "../../substrate/runtime/paths.mjs";
+import { PortBrokerService } from "../../substrate/runtime/port-broker/service.mjs";
+import { renderUrl, routerHostname } from "../../orchestrators/router/hostname.mjs";
+import { suiResource } from "../sui/index.mjs";
+import { HOST_SERVICE_DEFAULT_ENTRYPOINT_PORT } from "../host-service/routable.mjs";
+import { WALLET_ERROR_TAGS, walletBootError } from "./errors.mjs";
+import "./protocol.mjs";
+import "./pairing.mjs";
+import { makeWalletCodegen } from "./codegen.mjs";
+import { WALLET_ENTRYPOINT_PORT, makeWalletRoutable } from "./routable.mjs";
+import { makeWalletSnapshotable } from "./snapshot.mjs";
+import "./origin-policy.mjs";
+import "./server.mjs";
+import { acquireWallet } from "./service.mjs";
+import { Effect } from "effect";
+//#region src/plugins/wallet/index.ts
+/** Composer-side expander hook for `wallet({ accounts: 'all' })`. The
+*  wallet factory cannot know the stack's account members at its own
+*  call site (members are introduced positionally to `defineDevstack`
+*  AFTER the wallet factory has returned). The composer detects this
+*  symbol on a member returned by the wallet factory, collects every
+*  account-providing member from the final stack, and invokes the
+*  hook to produce the real wallet member with a populated dependencies
+*  tuple — keeping the dep-graph edges accurate.
+*
+*  Symbol-keyed (not a named property) so it cannot collide with any
+*  user-facing member field. Globally registered via `Symbol.for(...)`
+*  so the composer can look it up without importing the wallet
+*  module's symbol-binding (this side-steps a TS2742 inferred-type
+*  portability error: a `unique symbol`-keyed property in the wallet
+*  member's return type would leak the symbol's compile-time identity
+*  into the user's `defineDevstack(...)` inferred Stack type, forcing
+*  every example's default export to carry an explicit annotation). */
+const WALLET_EXPAND_ACCOUNTS_ALL = Symbol.for("devstack.wallet.expand-accounts-all");
+/** The wallet plugin's resource identity. ONE per stack (15-wallet.md
+*  "singleton per stack"). The id is `'wallet'` (singular). */
+const walletResource = resource("wallet");
+const walletErrorContributions = pluginErrorContributions(WALLET_ERROR_TAGS);
+function wallet(opts) {
+	const resolvedOpts = opts ?? { accounts: "all" };
+	if (resolvedOpts.accounts === "all") {
+		const placeholder = makeWalletMember(resolvedOpts, []);
+		const expander = (accountMembers) => makeWalletMember({
+			...resolvedOpts,
+			accounts: accountMembers
+		}, accountMembers);
+		placeholder[WALLET_EXPAND_ACCOUNTS_ALL] = expander;
+		return placeholder;
+	}
+	return makeWalletMember(resolvedOpts, resolvedOpts.accounts);
+}
+function makeWalletMember(opts, accounts) {
+	const dependencies = [suiResource, ...accounts];
+	const resolvedOpts = {
+		...opts,
+		accounts
+	};
+	return definePlugin({
+		id: walletResource.id,
+		dependsOn: dependencies,
+		role: "service",
+		start: (deps) => Effect.gen(function* () {
+			const identity = yield* IdentityContext;
+			const paths = yield* StackPathsService;
+			const portBroker = yield* PortBrokerService;
+			const [, ...resolvedAccounts] = deps;
+			const routerFrontedUrl = yield* routerHostname(identity, "api").pipe(Effect.map((hostname) => renderUrl({
+				protocol: "http",
+				hostname,
+				port: WALLET_ENTRYPOINT_PORT
+			})), Effect.mapError((err) => walletBootError({
+				phase: "route-url",
+				message: `wallet router URL construction failed: ${err.detail}`,
+				cause: err
+			})));
+			const routedAppOrigin = yield* routerHostname(identity, "dev").pipe(Effect.map((hostname) => renderUrl({
+				protocol: "http",
+				hostname,
+				port: HOST_SERVICE_DEFAULT_ENTRYPOINT_PORT
+			})), Effect.mapError((err) => walletBootError({
+				phase: "route-url",
+				message: `wallet app-origin URL construction failed: ${err.detail}`,
+				cause: err
+			})));
+			return yield* acquireWallet(resolvedOpts, {
+				app: identity.app,
+				stack: identity.stack,
+				chain: identity.chain,
+				stateRoot: paths.stackRoot,
+				vitePortForThisStack: null,
+				allocatePort: (preferred, probeHost) => portBroker.allocate({
+					kind: "wallet",
+					preferredPort: preferred,
+					...probeHost === void 0 ? {} : { probeHost }
+				}).pipe(Effect.map((alloc) => alloc.port), Effect.mapError((err) => walletBootError({
+					phase: "allocate-port",
+					message: `port-broker allocate failed: ${err.detail}`,
+					hint: err.reason === "preferred-busy" ? "another plugin in this stack is using your preferred port; omit `port` to let the broker pick." : err.reason === "no-free-port" ? "the wallet kind-window is exhausted; check for stray devstack supervisors holding ports." : "bind-probe failed — likely a privileged port or jail restriction.",
+					cause: err
+				}))),
+				resolveAccounts: () => Effect.succeed(resolvedAccounts),
+				routerFrontedUrl,
+				routedAppOrigin,
+				supervisorCtx: void 0
+			});
+		}),
+		errorContributions: walletErrorContributions,
+		capabilities: ({ value: resolved, runtime: acquireCtx }) => {
+			return [
+				makeWalletSnapshotable(),
+				makeWalletCodegen(resolved.bindings),
+				makeWalletRoutable({
+					app: acquireCtx.identity.app,
+					stack: acquireCtx.identity.stack,
+					port: resolved.localPort
+				})
+			];
+		}
+	});
+}
+//#endregion
+export { WALLET_EXPAND_ACCOUNTS_ALL, wallet };
+
+//# sourceMappingURL=index.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../src/plugins/wallet/index.ts"],"sourcesContent":["// Wallet plugin — barrel + `wallet(opts?)` factory.\n//\n// Architecture (15-wallet.md):\n//\n//   The wallet bridges devstack (the supervisor host) and the\n//   browser-side dev-wallet adapter (in the separate `dev-wallet`\n//   package). Two parts:\n//\n//     1. The IN-PROCESS HTTP server. Owned here. Boot at acquire,\n//        serve `/api/v1/devstack/*` routes (health, accounts,\n//        sign-transaction, sign-personal-message, execute).\n//\n//     2. The BROWSER-SIDE ADAPTER. Owned by `dev-wallet`. Reads the\n//        codegen-emitted `dapp-kit/config.ts`, constructs a\n//        `DevstackSignerAdapter`, registers it with `@mysten/dapp-\n//        kit`'s wallet-standard surface.\n//\n//   The HTTP protocol is the ONE cross-boundary contract. THIS PACKAGE\n//   NEVER IMPORTS `@mysten/dapp-kit*` OR `@mysten/wallet-standard`.\n//\n// Capabilities emitted:\n//\n//   1. Snapshotable — pairing token under `wallet/token`.\n//   2. Codegenable — `dapp-kit-config` bindings (the dev-wallet\n//      adapter consumes this). Sensitive flag set — 0o600 + gitignore.\n//   3. Routable — wallet UI URL on the stack-scoped router.\n\nimport { Effect } from 'effect';\n\nimport { definePlugin, resource } from '../../api/define-plugin.ts';\nimport { pluginErrorContributions } from '../../api/plugin-errors.ts';\nimport { IdentityContext, StackPathsService } from '../../substrate/runtime/paths.ts';\nimport { PortBrokerService } from '../../substrate/runtime/port-broker/index.ts';\nimport { renderUrl, routerHostname } from '../../orchestrators/router/hostname.ts';\nimport { suiResource } from '../sui/index.ts';\nimport {\n\tHOST_SERVICE_DEFAULT_ENDPOINT_NAME,\n\tHOST_SERVICE_DEFAULT_ENTRYPOINT_PORT,\n} from '../host-service/routable.ts';\n\nimport { makeWalletCodegen } from './codegen.ts';\nimport { WALLET_ERROR_TAGS, walletBootError } from './errors.ts';\nimport { makeWalletRoutable, WALLET_ENTRYPOINT_PORT, WALLET_ROUTE_ROLE } from './routable.ts';\nimport { makeWalletSnapshotable } from './snapshot.ts';\nimport {\n\tacquireWallet,\n\tWALLET_ACCOUNTS_ALL,\n\ttype WalletAcquireContext,\n\ttype WalletAccountMember,\n\ttype WalletOptions,\n\ttype WalletValue,\n} from './service.ts';\nimport type { AnyPlugin } from '../../substrate/plugin.ts';\n\n/** Composer-side expander hook for `wallet({ accounts: 'all' })`. The\n *  wallet factory cannot know the stack's account members at its own\n *  call site (members are introduced positionally to `defineDevstack`\n *  AFTER the wallet factory has returned). The composer detects this\n *  symbol on a member returned by the wallet factory, collects every\n *  account-providing member from the final stack, and invokes the\n *  hook to produce the real wallet member with a populated dependencies\n *  tuple — keeping the dep-graph edges accurate.\n *\n *  Symbol-keyed (not a named property) so it cannot collide with any\n *  user-facing member field. Globally registered via `Symbol.for(...)`\n *  so the composer can look it up without importing the wallet\n *  module's symbol-binding (this side-steps a TS2742 inferred-type\n *  portability error: a `unique symbol`-keyed property in the wallet\n *  member's return type would leak the symbol's compile-time identity\n *  into the user's `defineDevstack(...)` inferred Stack type, forcing\n *  every example's default export to carry an explicit annotation). */\nexport const WALLET_EXPAND_ACCOUNTS_ALL: symbol = Symbol.for('devstack.wallet.expand-accounts-all');\n\n/** Runtime-only expander shape attached to the placeholder wallet\n *  member when the user passes `accounts: 'all'`. The composer reads\n *  `member[WALLET_EXPAND_ACCOUNTS_ALL](accountMembers)` to mint the\n *  resolved-tuple wallet member.\n *\n *  Kept as a value-level shape (not a type-level intersection on the\n *  factory's return signature) so the symbol-keyed property does NOT\n *  leak into the user's inferred Stack type (see TS2742 note above). */\nexport type WalletExpandAccountsAllExpander = (\n\taccountMembers: ReadonlyArray<WalletAccountMember>,\n) => AnyPlugin;\n\n// ----------------------------------------------------------------------\n// Resource identity\n// ----------------------------------------------------------------------\n\n/** The wallet plugin's resource identity. ONE per stack (15-wallet.md\n *  \"singleton per stack\"). The id is `'wallet'` (singular). */\nconst walletResource = resource<'wallet', WalletValue>('wallet');\nconst walletErrorContributions = pluginErrorContributions(WALLET_ERROR_TAGS);\n\n// ----------------------------------------------------------------------\n// User-facing factory\n// ----------------------------------------------------------------------\n\n/**\n * Construct the wallet plugin.\n *\n * Two parts of the wallet:\n *\n *   - HERE: HTTP server + token + pairing protocol + codegen.\n *   - DEV-WALLET PACKAGE: `@mysten/dapp-kit`-shaped adapter the\n *     user-app's frontend bundle imports.\n *\n *  Distilled-doc invariant (15-wallet.md \"Always explicit\"): the\n *  composer NEVER auto-mounts the wallet. The user calls `wallet()`,\n *  `wallet({ accounts: 'all' })`, or `wallet({ accounts: [alice, bob] })`\n *  and passes the result to `defineDevstack(...)`.\n *\n *  ### Security defaults\n *\n *   - `bindAddress: '0.0.0.0'`. The router runs in Docker, so on\n *     native Linux it reaches this host process through the Docker\n *     host-gateway address instead of host loopback. The published\n *     wallet URL remains stack-scoped through the router.\n *\n *   - `allowLocalhostVite: false`. The bare `http://localhost:<vite>`\n *     form is OFF by default — opt-in for headless test runners /\n *     custom dev hosts. Defaulting it on would let a sibling stack\n *     running vite on the same port pair with this wallet (because\n *     `localhost` is not stack-scoped). See `origin-policy.ts` for\n *     the rationale.\n *\n *   - Pairing token in URL fragment only (`#token=<32-hex>`). Never\n *     in query params (would land in access logs / referrers).\n *\n *   - Constant-time bearer compare on every request.\n *\n *   - Token file `0o600`. Codegen output (`dapp-kit/config.ts`)\n *     `0o600` + gitignored via `sensitive: true`.\n */\nexport function wallet<const Accounts extends ReadonlyArray<WalletAccountMember>>(\n\topts: Omit<WalletOptions, 'accounts'> & { readonly accounts: Accounts },\n): ReturnType<typeof makeWalletMember<Accounts>>;\nexport function wallet(\n\topts: Omit<WalletOptions, 'accounts'> & { readonly accounts: typeof WALLET_ACCOUNTS_ALL },\n): ReturnType<typeof makeWalletMember<readonly []>>;\nexport function wallet(): ReturnType<typeof makeWalletMember<readonly []>>;\nexport function wallet(opts?: WalletOptions): AnyPlugin {\n\tconst resolvedOpts: WalletOptions =\n\t\topts ?? ({ accounts: WALLET_ACCOUNTS_ALL } satisfies WalletOptions);\n\tif (resolvedOpts.accounts === WALLET_ACCOUNTS_ALL) {\n\t\t// Deferred placeholder. `dependsOn` carries only `[suiResource]` —\n\t\t// the composer rewrites the member once it knows which account\n\t\t// members are in the stack (api-surface-design §4 D6). Without\n\t\t// composer expansion, the wallet would race account funding;\n\t\t// WITH composer expansion, every per-account dependency edge is\n\t\t// in place by the time the dep-graph builds.\n\t\t//\n\t\t// Type-level: the placeholder's `dependsOn` is `[suiResource]`. A\n\t\t// wider `ReadonlyArray<account/${string}>` would widen the\n\t\t// stack-level `MissingProviders` check to the template literal\n\t\t// (which never reduces to any concrete `account/<name>`), so\n\t\t// the placeholder MUST stay narrow.\n\t\t//\n\t\t// Runtime: the symbol-keyed expander is attached as a value-\n\t\t// only property; the factory's declared return type\n\t\t// intentionally does NOT surface it (a `unique symbol`-keyed\n\t\t// member field would leak into the user's inferred Stack type\n\t\t// and trigger TS2742 \"type cannot be named without a reference\n\t\t// to ./node_modules/.../plugins/wallet\" at every example's\n\t\t// default export).\n\t\tconst placeholder = makeWalletMember(resolvedOpts, [] as const);\n\t\tconst expander: WalletExpandAccountsAllExpander = (accountMembers) =>\n\t\t\tmakeWalletMember({ ...resolvedOpts, accounts: accountMembers }, accountMembers);\n\t\t(placeholder as unknown as Record<symbol, unknown>)[WALLET_EXPAND_ACCOUNTS_ALL] = expander;\n\t\treturn placeholder;\n\t}\n\treturn makeWalletMember(resolvedOpts, resolvedOpts.accounts);\n}\n\nfunction makeWalletMember<Accounts extends ReadonlyArray<WalletAccountMember>>(\n\topts: WalletOptions,\n\taccounts: Accounts,\n) {\n\t// Dependencies MUST include every account ref (15-wallet.md\n\t// \"upstreamKeys MUST include suiResource.id + every account id\" — same\n\t// load-bearing invariant). The substrate's topological scheduler\n\t// uses `dependsOn` to drive build order; without including the\n\t// account refs here, the wallet would race account funding and the\n\t// first `signTransaction` would fail with `address-not-found`.\n\t//\n\tconst dependencies = [suiResource, ...accounts] as const;\n\n\t// The resolved-opts shape acquireWallet sees has accounts pinned to\n\t// the resolved tuple — `'all'` is purely a user-surface convenience\n\t// the composer never propagates to the supervisor.\n\tconst resolvedOpts: WalletOptions<Accounts> = { ...opts, accounts };\n\n\treturn definePlugin({\n\t\tid: walletResource.id,\n\t\tdependsOn: dependencies,\n\t\t// The HTTP server is a long-lived host process; per-request\n\t\t// handlers fork off the supervisor-context fiber but the server\n\t\t// itself lives for the stack's lifetime.\n\t\trole: 'service',\n\t\tstart: (deps) =>\n\t\t\tEffect.gen(function* () {\n\t\t\t\t// Pull identity, the stack-paths bundle, and the port-\n\t\t\t\t// broker from the supervisor-provided substrate context.\n\t\t\t\t// `StackPathsService.stackRoot` is the on-disk root for\n\t\t\t\t// per-stack runtime artifacts (incl. `wallet/token`); the\n\t\t\t\t// port broker is per-stack (Layer-driven, one instance per\n\t\t\t\t// stack scope); the wallet's scope hangs off the\n\t\t\t\t// supervisor's `acquireScope`, so any release finalizer\n\t\t\t\t// installed by these primitives unwinds with the rest of\n\t\t\t\t// the plugin's resources on cycle / teardown.\n\t\t\t\tconst identity = yield* IdentityContext;\n\t\t\t\tconst paths = yield* StackPathsService;\n\t\t\t\tconst portBroker = yield* PortBrokerService;\n\n\t\t\t\t// The first dependency is the hard Sui ordering edge; the\n\t\t\t\t// remaining values mirror the explicit account tuple.\n\t\t\t\tconst [, ...resolvedAccounts] = deps;\n\t\t\t\tconst routerFrontedUrl = yield* routerHostname(identity, WALLET_ROUTE_ROLE).pipe(\n\t\t\t\t\tEffect.map((hostname) =>\n\t\t\t\t\t\trenderUrl({\n\t\t\t\t\t\t\tprotocol: 'http',\n\t\t\t\t\t\t\thostname,\n\t\t\t\t\t\t\tport: WALLET_ENTRYPOINT_PORT,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t\tEffect.mapError((err) =>\n\t\t\t\t\t\twalletBootError({\n\t\t\t\t\t\t\tphase: 'route-url',\n\t\t\t\t\t\t\tmessage: `wallet router URL construction failed: ${err.detail}`,\n\t\t\t\t\t\t\tcause: err,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t);\n\t\t\t\tconst routedAppOrigin = yield* routerHostname(\n\t\t\t\t\tidentity,\n\t\t\t\t\tHOST_SERVICE_DEFAULT_ENDPOINT_NAME,\n\t\t\t\t).pipe(\n\t\t\t\t\tEffect.map((hostname) =>\n\t\t\t\t\t\trenderUrl({\n\t\t\t\t\t\t\tprotocol: 'http',\n\t\t\t\t\t\t\thostname,\n\t\t\t\t\t\t\tport: HOST_SERVICE_DEFAULT_ENTRYPOINT_PORT,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t\tEffect.mapError((err) =>\n\t\t\t\t\t\twalletBootError({\n\t\t\t\t\t\t\tphase: 'route-url',\n\t\t\t\t\t\t\tmessage: `wallet app-origin URL construction failed: ${err.detail}`,\n\t\t\t\t\t\t\tcause: err,\n\t\t\t\t\t\t}),\n\t\t\t\t\t),\n\t\t\t\t);\n\n\t\t\t\tconst acquireCtx: WalletAcquireContext = {\n\t\t\t\t\tapp: identity.app,\n\t\t\t\t\tstack: identity.stack,\n\t\t\t\t\tchain: identity.chain,\n\t\t\t\t\tstateRoot: paths.stackRoot,\n\t\t\t\t\tvitePortForThisStack: null,\n\t\t\t\t\tallocatePort: (preferred, probeHost) =>\n\t\t\t\t\t\tportBroker\n\t\t\t\t\t\t\t.allocate({\n\t\t\t\t\t\t\t\tkind: 'wallet',\n\t\t\t\t\t\t\t\tpreferredPort: preferred,\n\t\t\t\t\t\t\t\t...(probeHost === undefined ? {} : { probeHost }),\n\t\t\t\t\t\t\t})\n\t\t\t\t\t\t\t.pipe(\n\t\t\t\t\t\t\t\tEffect.map((alloc) => alloc.port),\n\t\t\t\t\t\t\t\tEffect.mapError((err) =>\n\t\t\t\t\t\t\t\t\twalletBootError({\n\t\t\t\t\t\t\t\t\t\tphase: 'allocate-port',\n\t\t\t\t\t\t\t\t\t\tmessage: `port-broker allocate failed: ${err.detail}`,\n\t\t\t\t\t\t\t\t\t\thint:\n\t\t\t\t\t\t\t\t\t\t\terr.reason === 'preferred-busy'\n\t\t\t\t\t\t\t\t\t\t\t\t? 'another plugin in this stack is using your preferred port; omit `port` to let the broker pick.'\n\t\t\t\t\t\t\t\t\t\t\t\t: err.reason === 'no-free-port'\n\t\t\t\t\t\t\t\t\t\t\t\t\t? 'the wallet kind-window is exhausted; check for stray devstack supervisors holding ports.'\n\t\t\t\t\t\t\t\t\t\t\t\t\t: 'bind-probe failed — likely a privileged port or jail restriction.',\n\t\t\t\t\t\t\t\t\t\tcause: err,\n\t\t\t\t\t\t\t\t\t}),\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t),\n\t\t\t\t\tresolveAccounts: () => Effect.succeed(resolvedAccounts),\n\t\t\t\t\trouterFrontedUrl,\n\t\t\t\t\troutedAppOrigin,\n\t\t\t\t\tsupervisorCtx: undefined,\n\t\t\t\t};\n\n\t\t\t\treturn yield* acquireWallet(resolvedOpts, acquireCtx);\n\t\t\t}),\n\t\terrorContributions: walletErrorContributions,\n\t\t// Dynamic capability factory — receives the resolved\n\t\t// `WalletValue` + acquire context. Stamps the real dapp-kit\n\t\t// bindings (walletUrl, pairUrl, chain id, paths) into the\n\t\t// codegen decl, and the real identity app/stack into the\n\t\t// routable decl.\n\t\tcapabilities: ({ value: resolved, runtime: acquireCtx }) => {\n\t\t\tconst snapshot = makeWalletSnapshotable();\n\t\t\tconst codegen = makeWalletCodegen(resolved.bindings);\n\t\t\tconst routable = makeWalletRoutable({\n\t\t\t\tapp: acquireCtx.identity.app,\n\t\t\t\tstack: acquireCtx.identity.stack,\n\t\t\t\tport: resolved.localPort,\n\t\t\t});\n\t\t\treturn [snapshot, codegen, routable] as const;\n\t\t},\n\t});\n}\n\n// ----------------------------------------------------------------------\n// Re-exports\n// ----------------------------------------------------------------------\n\nexport type {\n\tWalletOptions,\n\tWalletValue,\n\tWalletAccountMember,\n\tWalletAccountsAll,\n} from './service.ts';\nexport { WALLET_ACCOUNTS_ALL } from './service.ts';\nexport type { DappKitConfigBindings } from './codegen.ts';\nexport {\n\tWalletHttpPath,\n\tWALLET_PROTOCOL_PREFIX,\n\tWALLET_AUTH_HEADER,\n\tWALLET_BEARER_PREFIX,\n\tWALLET_TOKEN_FRAGMENT_KEY,\n\tWALLET_TOKEN_HEX_LENGTH,\n\tSignRequestSchema,\n\tSignResponseSchema,\n\tExecuteRequestSchema,\n\tExecuteResponseSchema,\n\tHealthResponseSchema,\n\tAccountsResponseSchema,\n\tAccountSummarySchema,\n\tErrorResponseSchema,\n\tSuiAddressSchema,\n\tBase64Schema,\n\tSignatureSchemeSchema,\n\tAccountSourceSchema,\n\ttype WalletHttpPathValue,\n\ttype SignRequest,\n\ttype SignResponse,\n\ttype ExecuteRequest,\n\ttype ExecuteResponse,\n\ttype HealthResponse,\n\ttype AccountsResponse,\n\ttype AccountSummary,\n\ttype ErrorResponse,\n} from './protocol.ts';\nexport type {\n\tWalletError,\n\tWalletBootError,\n\tWalletBootPhase,\n\tWalletRequestError,\n\tWalletRequestPhase,\n} from './errors.ts';\nexport { WALLET_ERROR_TAGS } from './errors.ts';\nexport type { OriginPolicy, OriginPolicyInputs, OriginCheckResult } from './origin-policy.ts';\nexport { resolveOriginPolicy, checkOrigin, corsHeadersFor } from './origin-policy.ts';\nexport type { PairingToken } from './pairing.ts';\nexport {\n\tmintToken,\n\tacquirePairingToken,\n\ttokenPath,\n\tcomposePairUrl,\n\tparsePairUrl,\n\tparseBearerHeader,\n\tsafeBearerEquals,\n\tredactToken,\n} from './pairing.ts';\nexport { WALLET_ENDPOINT_NAME, makeWalletRoutable } from './routable.ts';\nexport {\n\tdispatch,\n\tstartHttpServer,\n\tMAX_BODY_BYTES,\n\ttype WalletRequest,\n\ttype WalletResponse,\n\ttype WalletServerConfig,\n\ttype WalletServerHandle,\n} from './server.ts';\nexport { makeWalletCodegen } from './codegen.ts';\nexport { makeWalletSnapshotable } from './snapshot.ts';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,MAAa,6BAAqC,OAAO,IAAI,sCAAsC;;;AAoBnG,MAAM,iBAAiB,SAAgC,SAAS;AAChE,MAAM,2BAA2B,yBAAyB,kBAAkB;AAiD5E,SAAgB,OAAO,MAAiC;CACvD,MAAM,eACL,QAAS,EAAE,UAAA,OAA+B;AAC3C,KAAI,aAAa,aAAA,OAAkC;EAqBlD,MAAM,cAAc,iBAAiB,cAAc,EAAE,CAAU;EAC/D,MAAM,YAA6C,mBAClD,iBAAiB;GAAE,GAAG;GAAc,UAAU;GAAgB,EAAE,eAAe;AAC/E,cAAmD,8BAA8B;AAClF,SAAO;;AAER,QAAO,iBAAiB,cAAc,aAAa,SAAS;;AAG7D,SAAS,iBACR,MACA,UACC;CAQD,MAAM,eAAe,CAAC,aAAa,GAAG,SAAS;CAK/C,MAAM,eAAwC;EAAE,GAAG;EAAM;EAAU;AAEnE,QAAO,aAAa;EACnB,IAAI,eAAe;EACnB,WAAW;EAIX,MAAM;EACN,QAAQ,SACP,OAAO,IAAI,aAAa;GAUvB,MAAM,WAAW,OAAO;GACxB,MAAM,QAAQ,OAAO;GACrB,MAAM,aAAa,OAAO;GAI1B,MAAM,GAAG,GAAG,oBAAoB;GAChC,MAAM,mBAAmB,OAAO,eAAe,UAAA,MAA4B,CAAC,KAC3E,OAAO,KAAK,aACX,UAAU;IACT,UAAU;IACV;IACA,MAAM;IACN,CAAC,CACF,EACD,OAAO,UAAU,QAChB,gBAAgB;IACf,OAAO;IACP,SAAS,0CAA0C,IAAI;IACvD,OAAO;IACP,CAAC,CACF,CACD;GACD,MAAM,kBAAkB,OAAO,eAC9B,UAAA,MAEA,CAAC,KACD,OAAO,KAAK,aACX,UAAU;IACT,UAAU;IACV;IACA,MAAM;IACN,CAAC,CACF,EACD,OAAO,UAAU,QAChB,gBAAgB;IACf,OAAO;IACP,SAAS,8CAA8C,IAAI;IAC3D,OAAO;IACP,CAAC,CACF,CACD;AAqCD,UAAO,OAAO,cAAc,cAAc;IAlCzC,KAAK,SAAS;IACd,OAAO,SAAS;IAChB,OAAO,SAAS;IAChB,WAAW,MAAM;IACjB,sBAAsB;IACtB,eAAe,WAAW,cACzB,WACE,SAAS;KACT,MAAM;KACN,eAAe;KACf,GAAI,cAAc,KAAA,IAAY,EAAE,GAAG,EAAE,WAAW;KAChD,CAAC,CACD,KACA,OAAO,KAAK,UAAU,MAAM,KAAK,EACjC,OAAO,UAAU,QAChB,gBAAgB;KACf,OAAO;KACP,SAAS,gCAAgC,IAAI;KAC7C,MACC,IAAI,WAAW,mBACZ,mGACA,IAAI,WAAW,iBACd,6FACA;KACL,OAAO;KACP,CAAC,CACF,CACD;IACH,uBAAuB,OAAO,QAAQ,iBAAiB;IACvD;IACA;IACA,eAAe,KAAA;IAGoC,CAAC;IACpD;EACH,oBAAoB;EAMpB,eAAe,EAAE,OAAO,UAAU,SAAS,iBAAiB;AAQ3D,UAAO;IAPU,wBAOD;IANA,kBAAkB,SAAS,SAMlB;IALR,mBAAmB;KACnC,KAAK,WAAW,SAAS;KACzB,OAAO,WAAW,SAAS;KAC3B,MAAM,SAAS;KACf,CACkC;IAAC;;EAErC,CAAC"}

package/dist/plugins/wallet/origin-policy.d.mts

@@ -0,0 +1 @@
+import { Effect } from "effect";

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

@@ -0,0 +1,65 @@
+import { SpanAttr } from "../../substrate/runtime/observability/spans.mjs";
+import { Effect } from "effect";
+//#region src/plugins/wallet/origin-policy.ts
+/**
+* Resolve the per-stack origin allowlist.
+*
+*  - Always allowlisted: the stack-scoped router host
+*    `http://dev.<stack>.<app>.localhost:<vite-port>`, IF the broker recorded
+*    a vite port for this stack.
+*  - Conditionally allowlisted: the bare `http://localhost:<vite-port>`
+*    form. Off by default; on iff `allowLocalhostVite` is true.
+*  - Always allowlisted: any explicit caller-supplied origins from
+*    `extraOrigins`.
+*
+* Empty-allowlist policy (vite absent AND no `extraOrigins`): allowed.
+* The wallet boots normally; with an empty allowlist the per-request
+* gate refuses every request (every Origin lands in `forbidden`). This
+* is the correct behavior for a stack composed without any client UI
+* (e.g. node-only smoke / e2e configs) — the wallet's keypair + token
+* are still useful for the host process, but the HTTP surface is
+* effectively closed. A `Effect.logWarning` surfaces the configuration
+* for operator visibility.
+*
+* Returns `Effect<OriginPolicy, WalletBootError>` (the error channel
+* is preserved for future fail-fast modes the resolver may grow).
+*/
+const resolveOriginPolicy = (inputs) => Effect.gen(function* () {
+	const allowed = /* @__PURE__ */ new Set();
+	const stackScopedHost = inputs.stack === "main" ? `dev.${inputs.app}.localhost` : `dev.${inputs.stack}.${inputs.app}.localhost`;
+	if (inputs.vitePortForThisStack !== null) {
+		allowed.add(`http://${stackScopedHost}:${inputs.vitePortForThisStack}`);
+		if (inputs.allowLocalhostVite) allowed.add(`http://localhost:${inputs.vitePortForThisStack}`);
+	}
+	if (inputs.routedAppOrigin !== null) allowed.add(inputs.routedAppOrigin);
+	for (const o of inputs.extraOrigins) allowed.add(o);
+	if (allowed.size === 0) yield* Effect.logWarning("wallet origin allowlist is empty").pipe(Effect.annotateLogs({
+		[SpanAttr.app]: inputs.app,
+		[SpanAttr.stack]: inputs.stack,
+		[SpanAttr.walletLocalhostViteEnabled]: inputs.allowLocalhostVite
+	}));
+	return {
+		allowed,
+		localhostViteEnabled: inputs.allowLocalhostVite,
+		stackScopedHost
+	};
+});
+const checkOrigin = (policy, headerValue) => {
+	if (headerValue === void 0 || headerValue.length === 0) return "missing";
+	return policy.allowed.has(headerValue) ? "ok" : "forbidden";
+};
+/** Compose CORS headers for a successful request. Single-allowed-origin
+*  echo (browsers don't honor wildcard with credentials, and we want
+*  to keep `Access-Control-Allow-Credentials` open for fetch with
+*  `credentials: 'include'` if a future codegen seam needs it). */
+const corsHeadersFor = (origin) => ({
+	"access-control-allow-origin": origin,
+	"access-control-allow-methods": "GET, POST, OPTIONS",
+	"access-control-allow-headers": "authorization, content-type",
+	"access-control-allow-credentials": "true",
+	vary: "origin"
+});
+//#endregion
+export { checkOrigin, corsHeadersFor, resolveOriginPolicy };
+
+//# sourceMappingURL=origin-policy.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"origin-policy.mjs","names":[],"sources":["../../../src/plugins/wallet/origin-policy.ts"],"sourcesContent":["// Wallet plugin — CORS / origin allowlist policy.\n//\n// Distilled-doc problem (15-wallet.md \"Cross-stack pairing risk\"): the\n// legacy wallet auto-allowlisted `http://localhost:<vite-port>` per\n// stack. Two sibling stacks running vite on the same `localhost:5175`\n// (or `5176`, etc.) could pair with EITHER wallet — CORS lets the\n// request through, and the bearer token (once leaked once via any\n// channel) is enough to sign.\n//\n// Architecture decision (per task):\n//\n//   - Stack-scoped allowlist. The vite-port-derived origin is added to\n//     this stack's allowlist ONLY when the substrate's port broker\n//     records THIS stack as the owner of that vite port.\n//   - The stack-scoped host (e.g. `http://dev.<stack>.<app>.localhost:<port>`)\n//     is the canonical browser entry — always allowlisted.\n//   - The raw `http://localhost:<port>` form is OFF by default; opt-in\n//     via `WalletOptions.allowLocalhostVite: true` for callers who\n//     want the legacy behavior (e.g. headless test runners that pin\n//     `localhost`). Documented as a security tradeoff in the factory's\n//     JSDoc.\n//\n// Why \"origin + bearer together\" (task requirement #3): bearer alone\n// leaves a non-browser-tooling bypass — curl / fetch from a service\n// worker can forge `Authorization` from a leaked token. Browsers\n// always send `Origin`; non-browsers omit it. Demanding BOTH closes\n// the bypass.\n\nimport { Effect } from 'effect';\n\nimport { SpanAttr } from '../../substrate/runtime/observability/spans.ts';\nimport type { WalletBootError } from './errors.ts';\n\n// ----------------------------------------------------------------------\n// Policy shape\n// ----------------------------------------------------------------------\n\n/** Result of resolving the origin allowlist at boot. Captured into\n *  the HTTP handler closure so per-request checks are pure-string\n *  comparison. */\nexport interface OriginPolicy {\n\treadonly allowed: ReadonlySet<string>;\n\t/** True if the policy permitted the `http://localhost:<vite-port>`\n\t *  form. Carried for renderer / log hygiene — surfaces in the\n\t *  manifest as a flag so the TUI can warn. */\n\treadonly localhostViteEnabled: boolean;\n\t/** Bare host (e.g. `dev.<stack>.<app>.localhost`) the stack-scoped\n\t *  origin resolves under. Captured for log lines. */\n\treadonly stackScopedHost: string;\n}\n\n/** Per-stack inputs the policy resolver needs. Supplied by the\n *  substrate at acquire time (port broker + identity); this module\n *  doesn't reach into the broker itself. */\nexport interface OriginPolicyInputs {\n\treadonly app: string;\n\treadonly stack: string;\n\treadonly vitePortForThisStack: number | null;\n\treadonly routedAppOrigin: string | null;\n\treadonly extraOrigins: ReadonlyArray<string>;\n\treadonly allowLocalhostVite: boolean;\n}\n\n// ----------------------------------------------------------------------\n// Resolution\n// ----------------------------------------------------------------------\n\n/**\n * Resolve the per-stack origin allowlist.\n *\n *  - Always allowlisted: the stack-scoped router host\n *    `http://dev.<stack>.<app>.localhost:<vite-port>`, IF the broker recorded\n *    a vite port for this stack.\n *  - Conditionally allowlisted: the bare `http://localhost:<vite-port>`\n *    form. Off by default; on iff `allowLocalhostVite` is true.\n *  - Always allowlisted: any explicit caller-supplied origins from\n *    `extraOrigins`.\n *\n * Empty-allowlist policy (vite absent AND no `extraOrigins`): allowed.\n * The wallet boots normally; with an empty allowlist the per-request\n * gate refuses every request (every Origin lands in `forbidden`). This\n * is the correct behavior for a stack composed without any client UI\n * (e.g. node-only smoke / e2e configs) — the wallet's keypair + token\n * are still useful for the host process, but the HTTP surface is\n * effectively closed. A `Effect.logWarning` surfaces the configuration\n * for operator visibility.\n *\n * Returns `Effect<OriginPolicy, WalletBootError>` (the error channel\n * is preserved for future fail-fast modes the resolver may grow).\n */\nexport const resolveOriginPolicy = (\n\tinputs: OriginPolicyInputs,\n): Effect.Effect<OriginPolicy, WalletBootError> =>\n\tEffect.gen(function* () {\n\t\tconst allowed = new Set<string>();\n\t\tconst stackScopedHost =\n\t\t\tinputs.stack === 'main'\n\t\t\t\t? `dev.${inputs.app}.localhost`\n\t\t\t\t: `dev.${inputs.stack}.${inputs.app}.localhost`;\n\n\t\tif (inputs.vitePortForThisStack !== null) {\n\t\t\tallowed.add(`http://${stackScopedHost}:${inputs.vitePortForThisStack}`);\n\t\t\tif (inputs.allowLocalhostVite) {\n\t\t\t\tallowed.add(`http://localhost:${inputs.vitePortForThisStack}`);\n\t\t\t}\n\t\t}\n\n\t\tif (inputs.routedAppOrigin !== null) {\n\t\t\tallowed.add(inputs.routedAppOrigin);\n\t\t}\n\n\t\tfor (const o of inputs.extraOrigins) {\n\t\t\tallowed.add(o);\n\t\t}\n\n\t\tif (allowed.size === 0) {\n\t\t\tyield* Effect.logWarning('wallet origin allowlist is empty').pipe(\n\t\t\t\tEffect.annotateLogs({\n\t\t\t\t\t[SpanAttr.app]: inputs.app,\n\t\t\t\t\t[SpanAttr.stack]: inputs.stack,\n\t\t\t\t\t[SpanAttr.walletLocalhostViteEnabled]: inputs.allowLocalhostVite,\n\t\t\t\t}),\n\t\t\t);\n\t\t}\n\n\t\treturn {\n\t\t\tallowed,\n\t\t\tlocalhostViteEnabled: inputs.allowLocalhostVite,\n\t\t\tstackScopedHost,\n\t\t} satisfies OriginPolicy;\n\t});\n\n// ----------------------------------------------------------------------\n// Per-request check\n// ----------------------------------------------------------------------\n\n/** Per-request origin gate. Returns `'missing'` for absent Origin,\n *  `'forbidden'` for Origin not in the allowlist, `'ok'` for accepted.\n *\n *  Distilled-doc invariant (C12): missing Origin is its OWN refusal\n *  shape (closes the curl / non-browser bypass — bearer alone is not\n *  enough). */\nexport type OriginCheckResult = 'missing' | 'forbidden' | 'ok';\n\nexport const checkOrigin = (\n\tpolicy: OriginPolicy,\n\theaderValue: string | undefined,\n): OriginCheckResult => {\n\tif (headerValue === undefined || headerValue.length === 0) return 'missing';\n\treturn policy.allowed.has(headerValue) ? 'ok' : 'forbidden';\n};\n\n/** Compose CORS headers for a successful request. Single-allowed-origin\n *  echo (browsers don't honor wildcard with credentials, and we want\n *  to keep `Access-Control-Allow-Credentials` open for fetch with\n *  `credentials: 'include'` if a future codegen seam needs it). */\nexport const corsHeadersFor = (origin: string): Readonly<Record<string, string>> => ({\n\t'access-control-allow-origin': origin,\n\t'access-control-allow-methods': 'GET, POST, OPTIONS',\n\t'access-control-allow-headers': 'authorization, content-type',\n\t'access-control-allow-credentials': 'true',\n\tvary: 'origin',\n});\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA0FA,MAAa,uBACZ,WAEA,OAAO,IAAI,aAAa;CACvB,MAAM,0BAAU,IAAI,KAAa;CACjC,MAAM,kBACL,OAAO,UAAU,SACd,OAAO,OAAO,IAAI,cAClB,OAAO,OAAO,MAAM,GAAG,OAAO,IAAI;AAEtC,KAAI,OAAO,yBAAyB,MAAM;AACzC,UAAQ,IAAI,UAAU,gBAAgB,GAAG,OAAO,uBAAuB;AACvE,MAAI,OAAO,mBACV,SAAQ,IAAI,oBAAoB,OAAO,uBAAuB;;AAIhE,KAAI,OAAO,oBAAoB,KAC9B,SAAQ,IAAI,OAAO,gBAAgB;AAGpC,MAAK,MAAM,KAAK,OAAO,aACtB,SAAQ,IAAI,EAAE;AAGf,KAAI,QAAQ,SAAS,EACpB,QAAO,OAAO,WAAW,mCAAmC,CAAC,KAC5D,OAAO,aAAa;GAClB,SAAS,MAAM,OAAO;GACtB,SAAS,QAAQ,OAAO;GACxB,SAAS,6BAA6B,OAAO;EAC9C,CAAC,CACF;AAGF,QAAO;EACN;EACA,sBAAsB,OAAO;EAC7B;EACA;EACA;AAcH,MAAa,eACZ,QACA,gBACuB;AACvB,KAAI,gBAAgB,KAAA,KAAa,YAAY,WAAW,EAAG,QAAO;AAClE,QAAO,OAAO,QAAQ,IAAI,YAAY,GAAG,OAAO;;;;;;AAOjD,MAAa,kBAAkB,YAAsD;CACpF,+BAA+B;CAC/B,gCAAgC;CAChC,gCAAgC;CAChC,oCAAoC;CACpC,MAAM;CACN"}

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

@@ -0,0 +1,11 @@
+import { Effect, FileSystem } from "effect";
+
+//#region src/plugins/wallet/pairing.d.ts
+/** A pairing token. Branded so it can't be confused with arbitrary
+ *  strings at the type level — only this module mints them. */
+type PairingToken = string & {
+  readonly __pairingToken: unique symbol;
+};
+//#endregion
+export { PairingToken };
+//# sourceMappingURL=pairing.d.mts.map

package/dist/plugins/wallet/pairing.mjs

@@ -0,0 +1,125 @@
+import { atomicWriteFile } from "../../substrate/runtime/atomic-write.mjs";
+import { SpanAttr } from "../../substrate/runtime/observability/spans.mjs";
+import { redactText } from "../../substrate/runtime/observability/redaction.mjs";
+import { walletBootError } from "./errors.mjs";
+import { WALLET_BEARER_PREFIX, WALLET_TOKEN_FRAGMENT_KEY } from "./protocol.mjs";
+import { Effect } from "effect";
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+//#region src/plugins/wallet/pairing.ts
+/** Token-charset regex: lowercase hex, exactly 32 chars. Reject any
+*  on-disk value that doesn't match (re-mint). */
+const TOKEN_RE = /^[0-9a-f]{32}$/;
+const asToken = (s) => s;
+/** Mint a fresh token. 16 random bytes → 32 hex chars. */
+const mintToken = () => Effect.sync(() => asToken(randomBytes(16).toString("hex")));
+/** Resolve the on-disk token path under a state root. The state root
+*  is supplied by the substrate's identity / state-store config; this
+*  helper centralises the layout convention.
+*
+*  Convention: `<stateRoot>/wallet/token` — one token per stack, lives
+*  alongside other per-stack runtime artifacts. */
+const tokenPath = (stateRoot) => join(stateRoot, "wallet", "token");
+/**
+* Read the on-disk token if it exists and is well-formed; otherwise
+* mint + persist a fresh one via the substrate's atomic-write primitive
+* (mkdir-parent → O_EXCL temp → write → fsync → rename, mode 0o600).
+* Warm starts and snapshot restores both land in the "read existing"
+* branch so a previously-paired dev-wallet keeps working without a
+* re-pair UX.
+*/
+const acquirePairingToken = (path) => Effect.gen(function* () {
+	const existing = yield* Effect.tryPromise({
+		try: async () => {
+			try {
+				return await readFile(path, "utf8");
+			} catch (err) {
+				if (err?.code === "ENOENT") return null;
+				throw err;
+			}
+		},
+		catch: (cause) => walletBootError({
+			phase: "read-token",
+			message: `read of wallet token file failed at ${path}`,
+			hint: "check filesystem permissions / disk availability",
+			cause
+		})
+	});
+	if (existing !== null) {
+		const trimmed = existing.trim();
+		if (TOKEN_RE.test(trimmed)) return asToken(trimmed);
+		yield* Effect.logWarning("wallet token file is malformed; re-minting").pipe(Effect.annotateLogs({ [SpanAttr.walletTokenFile]: path }));
+	}
+	const token = yield* mintToken();
+	yield* atomicWriteFile(path, new TextEncoder().encode(token), { mode: 384 }).pipe(Effect.mapError((cause) => walletBootError({
+		phase: "write-token",
+		message: `failed to persist wallet token at ${path}`,
+		hint: "ENOSPC / EROFS / EACCES — boot continues with in-memory token; new pairing required next cycle",
+		cause
+	})));
+	return token;
+});
+/**
+* Compose the pair URL the dev-wallet adapter reads.
+*
+* The token rides the URL FRAGMENT (`#token=...`), never a query
+* parameter. Fragments are not sent to servers, so the token can't
+* land in access logs / referrer headers / Sentry breadcrumbs.
+*/
+const composePairUrl = (walletUrl, token) => `${walletUrl}/#${WALLET_TOKEN_FRAGMENT_KEY}=${token}`;
+/**
+* Parse a raw `Authorization` header value into the bearer token. The
+* dev-wallet adapter copies the token from `url.hash` into the
+* `Authorization: Bearer <token>` header on every request — this
+* helper is the symmetric inverse.
+*
+* Returns `null` on missing / malformed header so the caller can map
+* to the structured `unauthorized` request error.
+*/
+const parseBearerHeader = (header) => {
+	if (header === void 0) return null;
+	if (!header.startsWith("Bearer ")) return null;
+	const raw = header.slice(WALLET_BEARER_PREFIX.length);
+	return raw.length === 32 ? raw : null;
+};
+/**
+* Constant-time bearer-token compare. The length-mismatch shortcut is
+* intentional — token length is public knowledge (always 32 hex
+* chars), so leaking "wrong length" is not a credential leak. The
+* shortcut also prevents `timingSafeEqual` from throwing on mismatched
+* buffer sizes.
+*
+* Invariant (15-wallet.md "Token comparison MUST be constant-time"):
+* NEVER `===` two tokens. `===` on strings short-circuits at the first
+* mismatching byte, leaking the prefix byte-by-byte via response-time
+* measurement to a remote attacker.
+*/
+const safeBearerEquals = (a, b) => {
+	if (a.length !== b.length) return false;
+	const ab = Buffer.from(a, "utf8");
+	const bb = Buffer.from(b, "utf8");
+	if (ab.length !== bb.length) return false;
+	return timingSafeEqual(ab, bb);
+};
+const TOKEN_REDACTION_RULE = {
+	kind: "pattern",
+	pattern: /([#?&]token=)[A-Za-z0-9]+/g,
+	replacement: "$1<redacted>"
+};
+/**
+* Redact the token fragment from any URL-shaped string for logging /
+* TUI rendering. Defense-in-depth — the engine's log sink should never
+* see the unredacted pair URL anyway, but this exists for callers that
+* accidentally pass `pairUrl` straight into a log line.
+*
+* Distilled-doc opportunity (15-wallet.md): the legacy redactor only
+* covered `#token=`. This regex covers BOTH the fragment form and a
+* hypothetical query form so a future config change doesn't silently
+* leak.
+*/
+const redactToken = (s) => redactText(s, [TOKEN_REDACTION_RULE]);
+//#endregion
+export { acquirePairingToken, composePairUrl, mintToken, parseBearerHeader, redactToken, safeBearerEquals, tokenPath };
+
+//# sourceMappingURL=pairing.mjs.map

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

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

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

@@ -0,0 +1 @@
+import { Schema } from "effect";