@opendatalabs/vana-sdk 4.3.1 → 4.4.0-connect-sheet.0-pr.218.295a8da

package/README.md

@@ -457,6 +457,137 @@ pass the same explicit `idempotencyKey` on the retry to avoid a duplicate DCR.
 `react` is an optional peer dependency. The underlying
 `createDirectConnectFlow` store is also exported for non-React frontends.
 
+### Connect in Vana's in-page sheet
+
+Instead of a Vana tab, the person can approve in a sheet Vana draws over your
+page (it signs them in, shows the request, and finishes inside the sheet). The
+sheet is `presentation: "sheet"` of the same flow: the request, the status poll
+and the read are unchanged. The integration is two files.
+
+Backend: one catch-all route serves `config`, `request`, `status` and `data`,
+binding each request to the browser that created it.
+
+```ts
+// app/api/vana/[action]/route.ts
+import { createVanaConnectHandler } from "@opendatalabs/vana-sdk/server";
+import { vana } from "@/lib/vana"; // your createDirectDataController(...)
+
+const handler = createVanaConnectHandler({
+  controller: vana,
+  returnUrl: `${process.env.APP_URL}/connect/return`,
+  clientId: "my-app", // the embed client id Vana Account registered for your origin
+  // Recommended in production: only your signed-in users create requests.
+  session: async (request) => (await getSession(request))?.userId ?? null,
+});
+export { handler as GET, handler as POST };
+```
+
+The handler reports the Vana Account origin from the controller's `env`
+(`account.vana.org` for `production`, `account-dev.vana.org` for `dev`), so a
+dev app never frames production.
+
+Frontend:
+
+```tsx
+"use client";
+import { useVanaConnect } from "@opendatalabs/vana-sdk/react";
+
+export function ConnectButton() {
+  const { state, start } = useVanaConnect<MyData>({ endpoint: "/api/vana" });
+  if (state.type === "done") return <Result data={state.result.data} />;
+  return (
+    <>
+      <button
+        disabled={
+          state.type === "creating" || state.type === "awaiting_approval"
+        }
+        onClick={start}
+      >
+        Connect with Vana
+      </button>
+      {state.type === "awaiting_approval" && state.popupBlocked && (
+        // The sheet could not run here (state.sheetUnavailable says why).
+        <a href={state.request.approvalUrl} target="_blank" rel="noreferrer">
+          Open Vana
+        </a>
+      )}
+    </>
+  );
+}
+```
+
+- While the sheet is up, `state.sheet` reports `completion` (`in_browser` or
+  `remote_collect`) once the person approves, coarse `progress`
+  (`collecting`, `writing`), and any `error` it is showing.
+- **Approval is not delivery.** The sheet's `connected` event (and
+  `state.sheet.completion`) means the person approved; the data may still be
+  collecting. The flow reaches `done` only when your backend's status poll
+  says the request is readable and the read succeeds, and `error` when the
+  poll reports `denied`, `expired` or `completed` or the read fails. The sheet
+  sends no terminal event of its own; its events only make the flow poll
+  sooner.
+- Closing the sheet before approving returns to `idle`. Closing it after
+  approving keeps polling, since the data may still be readable.
+- If the frame cannot run (`frame_blocked`, `origin_not_registered`,
+  `incompatible_version`), the flow falls back to the tab presentation with
+  `popupBlocked: true`, so the "Open approval" link above still finishes it.
+  `origin_not_registered` arrives at once: the launcher asks Vana
+  (`GET <account>/api/embed/connect/client`, no credentials) alongside
+  framing. `vana_unavailable` means Vana's own side is down or misconfigured;
+  the sheet stays open and says so.
+- The partner reads; it cannot write through the sheet. Pass
+  `sheet: { closeAfterDoneMs: null }` to leave the sheet open after the read.
+- If your page sets a CSP, allow the frame and the client check:
+  `vanaConnectCsp(env)` from `/server` (or `/connect/protocol`) returns
+  `{ "frame-src": [accountOrigin], "connect-src": [accountOrigin] }`. It has
+  no default environment.
+- `createVanaConnectHandler` takes `session` to bind requests to your own
+  signed-in user (recommended: without it anyone who loads your page can
+  create requests as your app), `createOptions` for per-request create input
+  (questions, owner), and `read` to replace the default `readApprovedData`.
+  Use `toNodeHandler(handler)` for Express or plain `http`.
+- Creating a request is rate limited. The default, `createMemoryRateLimit()`,
+  allows 10 creates a minute per client IP and per session, in memory. It is
+  not production-grade (each instance counts alone, and the IP comes from
+  proxy headers): pass `rateLimit` backed by a shared store, or `false` when
+  a limiter already sits in front of the route. A refusal is
+  `429 rate_limited` with `Retry-After`.
+
+Choosing the Vana Account origin yourself (a custom flow, or preview deploys
+of Vana Account) goes through `resolveVanaAccountOrigin`; never match origins
+with your own pattern. It returns the environment's origin unless overrides
+are switched on for this build and the override is exactly an `https` origin
+on your allowlist:
+
+```ts
+import {
+  parseOriginAllowlist,
+  resolveVanaAccountOrigin,
+} from "@opendatalabs/vana-sdk/connect";
+
+const accountOrigin = resolveVanaAccountOrigin({
+  env: "dev",
+  override: new URLSearchParams(location.search).get("vana_account"),
+  previewOrigins: parseOriginAllowlist(
+    process.env.NEXT_PUBLIC_VANA_ACCOUNT_PREVIEW_ORIGINS,
+  ),
+  // From build-time config, never the request. Off in production.
+  allowOverride: process.env.NEXT_PUBLIC_DEPLOY_ENV === "preview",
+});
+```
+
+`createDirectConnectFlow` and the launcher take that origin (or an `env`)
+explicitly; neither falls back to production.
+
+Lower-level pieces: `createDirectConnectFlow(transports, { presentation:
+"sheet", sheet: { clientId, appName, accountOrigin } })` with an
+`authorizeRequest` transport backed by
+`controller.authorizeRequestRead(requestId)`; the launcher itself
+(`@opendatalabs/vana-sdk/connect`); and the zero-dependency message protocol
+(`@opendatalabs/vana-sdk/connect/protocol`). A backend in another language
+implements the [connect wire contract](./src/connect/WIRE_CONTRACT.md), which has test
+vectors.
+
 ### Test with large sample data
 
 When testing with realistic exports, use the public fixture catalog in

package/dist/auth/web3-signed-builder.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/auth/web3-signed-builder.ts"],"sourcesContent":["/**\n * Builder for Web3Signed Authorization headers.\n *\n * @remarks\n * Ported from `personal-server-ts`\n * (`packages/core/src/signing/request-signer.ts`). The original was wired\n * to a Node-only `ServerAccount` and `node:crypto`. This isomorphic version\n * accepts any `signMessage` callback (viem accounts, wallet clients, etc.)\n * and uses `@noble/hashes` for SHA-256 so it runs in browsers and Workers.\n *\n * Wire format is identical to PS — payload is JSON with sorted keys,\n * base64url-encoded, signed via EIP-191.\n *\n * @category Auth\n */\n\nimport { sha256 } from \"@noble/hashes/sha2\";\nimport { bytesToHex } from \"viem\";\nimport { toBase64 } from \"../utils/encoding\";\n\n/**\n * Sign-message callback compatible with viem `LocalAccount`/`WalletClient`-style\n * signers. Must produce an EIP-191 (`personal_sign`) signature.\n */\nexport type Web3SignedSignFn = (message: string) => Promise<`0x${string}`>;\n\n/** SHA-256 of the empty string — bodyHash for empty bodies. */\nconst EMPTY_BODY_HASH =\n  \"sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\";\n\n/** Default token lifetime (seconds). */\nconst DEFAULT_TTL_SECONDS = 300;\n\n/** Base64url encode bytes (no padding). */\nfunction base64urlEncode(input: Uint8Array): string {\n  return toBase64(input)\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/, \"\");\n}\n\n/** Compute the `sha256:<hex>` bodyHash claim for a request body. */\nexport function computeBodyHash(body: Uint8Array | undefined): string {\n  if (!body || body.length === 0) {\n    return EMPTY_BODY_HASH;\n  }\n  const digest = sha256(body);\n  return `sha256:${bytesToHex(digest).slice(2)}`;\n}\n\n/**\n * Build a Web3Signed Authorization header value.\n *\n * @returns The full header value (`\"Web3Signed <base64url>.<sig>\"`).\n */\nexport async function buildWeb3SignedHeader(params: {\n  /** EIP-191 signer (e.g. viem `account.signMessage`). */\n  signMessage: Web3SignedSignFn;\n  /** Expected origin (e.g. `\"https://ps.example.com\"`). */\n  aud: string;\n  /** HTTP method (e.g. `\"GET\"`). */\n  method: string;\n  /** Request URI/path (e.g. `\"/v1/data/instagram.profile\"`). */\n  uri: string;\n  /** Optional request body — when present, used to compute `bodyHash`. */\n  body?: Uint8Array;\n  /** Issued-at (unix seconds). Defaults to now. */\n  iat?: number;\n  /** Expiry (unix seconds). Defaults to `iat + 300`. */\n  exp?: number;\n  /** Optional grant id, attached as the `grantId` claim. */\n  grantId?: string;\n  /**\n   * Optional uniqueness claim, attached as the `nonce` claim (a uuid is the\n   * intended shape; the Personal Server bounds it at 128 characters).\n   *\n   * @remarks\n   * A payload is otherwise fully determined by\n   * `{ aud, bodyHash, exp, grantId, iat, method, uri }`, so two identical\n   * requests signed inside the same second produce the same bytes and the\n   * Personal Server refuses the second as a replay. With a nonce the replay\n   * key becomes `(signer, nonce)` instead, which is what lets a poll loop\n   * send the same request twice. The nonce is then single use itself:\n   * re-using one is a replay even when the rest of the payload changed.\n   */\n  nonce?: string;\n  /** Pre-computed `bodyHash` claim — overrides `body`. */\n  bodyHash?: string;\n}): Promise<string> {\n  const now = Math.floor(Date.now() / 1000);\n  const iat = params.iat ?? now;\n  const exp = params.exp ?? iat + DEFAULT_TTL_SECONDS;\n\n  const payload: Record<string, unknown> = {\n    aud: params.aud,\n    bodyHash: params.bodyHash ?? computeBodyHash(params.body),\n    exp,\n    iat,\n    method: params.method,\n    uri: params.uri,\n  };\n\n  if (params.grantId !== undefined) {\n    payload[\"grantId\"] = params.grantId;\n  }\n\n  // Merged before the sort, so the nonce sits in its alphabetical place like\n  // every other claim and the payload stays deterministic.\n  if (params.nonce !== undefined) {\n    payload[\"nonce\"] = params.nonce;\n  }\n\n  // Sort keys for deterministic serialization.\n  const sortedPayload = Object.keys(payload)\n    .sort()\n    .reduce<Record<string, unknown>>((acc, key) => {\n      acc[key] = payload[key];\n      return acc;\n    }, {});\n\n  const payloadJson = JSON.stringify(sortedPayload);\n  const payloadBytes = new TextEncoder().encode(payloadJson);\n  const payloadBase64 = base64urlEncode(payloadBytes);\n\n  const signature = await params.signMessage(payloadBase64);\n\n  return `Web3Signed ${payloadBase64}.${signature}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,kBAAuB;AACvB,kBAA2B;AAC3B,sBAAyB;AASzB,MAAM,kBACJ;AAGF,MAAM,sBAAsB;AAG5B,SAAS,gBAAgB,OAA2B;AAClD,aAAO,0BAAS,KAAK,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,EAAE;AACtB;AAGO,SAAS,gBAAgB,MAAsC;AACpE,MAAI,CAAC,QAAQ,KAAK,WAAW,GAAG;AAC9B,WAAO;AAAA,EACT;AACA,QAAM,aAAS,oBAAO,IAAI;AAC1B,SAAO,cAAU,wBAAW,MAAM,EAAE,MAAM,CAAC,CAAC;AAC9C;AAOA,eAAsB,sBAAsB,QAiCxB;AAClB,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,MAAM,OAAO,OAAO;AAC1B,QAAM,MAAM,OAAO,OAAO,MAAM;AAEhC,QAAM,UAAmC;AAAA,IACvC,KAAK,OAAO;AAAA,IACZ,UAAU,OAAO,YAAY,gBAAgB,OAAO,IAAI;AAAA,IACxD;AAAA,IACA;AAAA,IACA,QAAQ,OAAO;AAAA,IACf,KAAK,OAAO;AAAA,EACd;AAEA,MAAI,OAAO,YAAY,QAAW;AAChC,YAAQ,SAAS,IAAI,OAAO;AAAA,EAC9B;AAIA,MAAI,OAAO,UAAU,QAAW;AAC9B,YAAQ,OAAO,IAAI,OAAO;AAAA,EAC5B;AAGA,QAAM,gBAAgB,OAAO,KAAK,OAAO,EACtC,KAAK,EACL,OAAgC,CAAC,KAAK,QAAQ;AAC7C,QAAI,GAAG,IAAI,QAAQ,GAAG;AACtB,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AAEP,QAAM,cAAc,KAAK,UAAU,aAAa;AAChD,QAAM,eAAe,IAAI,YAAY,EAAE,OAAO,WAAW;AACzD,QAAM,gBAAgB,gBAAgB,YAAY;AAElD,QAAM,YAAY,MAAM,OAAO,YAAY,aAAa;AAExD,SAAO,cAAc,aAAa,IAAI,SAAS;AACjD;","names":[]}
+{"version":3,"sources":["../../src/auth/web3-signed-builder.ts"],"sourcesContent":["/**\n * Builder for Web3Signed Authorization headers.\n *\n * @remarks\n * Ported from `personal-server-ts`\n * (`packages/core/src/signing/request-signer.ts`). The original was wired\n * to a Node-only `ServerAccount` and `node:crypto`. This isomorphic version\n * accepts any `signMessage` callback (viem accounts, wallet clients, etc.)\n * and uses `@noble/hashes` for SHA-256 so it runs in browsers and Workers.\n *\n * Wire format is identical to PS — payload is JSON with sorted keys,\n * base64url-encoded, signed via EIP-191.\n *\n * @category Auth\n */\n\nimport { sha256 } from \"@noble/hashes/sha2\";\nimport { bytesToHex } from \"viem\";\nimport { toBase64 } from \"../utils/encoding\";\n\n/**\n * Sign-message callback compatible with viem `LocalAccount`/`WalletClient`-style\n * signers. Must produce an EIP-191 (`personal_sign`) signature.\n */\nexport type Web3SignedSignFn = (message: string) => Promise<`0x${string}`>;\n\n/** SHA-256 of the empty string — bodyHash for empty bodies. */\nconst EMPTY_BODY_HASH =\n  \"sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\";\n\n/** Default token lifetime (seconds). */\nconst DEFAULT_TTL_SECONDS = 300;\n\n/** Base64url encode bytes (no padding). */\nfunction base64urlEncode(input: Uint8Array): string {\n  return toBase64(input)\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/, \"\");\n}\n\n/** Compute the `sha256:<hex>` bodyHash claim for a request body. */\nexport function computeBodyHash(body: Uint8Array | undefined): string {\n  if (!body || body.length === 0) {\n    return EMPTY_BODY_HASH;\n  }\n  const digest = sha256(body);\n  return `sha256:${bytesToHex(digest).slice(2)}`;\n}\n\n/**\n * Build a Web3Signed Authorization header value.\n *\n * @returns The full header value (`\"Web3Signed <base64url>.<sig>\"`).\n */\nexport async function buildWeb3SignedHeader(params: {\n  /** EIP-191 signer (e.g. viem `account.signMessage`). */\n  signMessage: Web3SignedSignFn;\n  /** Expected origin (e.g. `\"https://ps.example.com\"`). */\n  aud: string;\n  /** HTTP method (e.g. `\"GET\"`). */\n  method: string;\n  /** Request URI/path (e.g. `\"/v1/data/instagram.profile\"`). */\n  uri: string;\n  /** Optional request body — when present, used to compute `bodyHash`. */\n  body?: Uint8Array;\n  /** Issued-at (unix seconds). Defaults to now. */\n  iat?: number;\n  /**\n   * Expiry (unix seconds). Defaults to `iat + 300`. Verifiers reject a window\n   * longer than 15 minutes after `iat` (see `verifyWeb3Signed`).\n   */\n  exp?: number;\n  /** Optional grant id, attached as the `grantId` claim. */\n  grantId?: string;\n  /**\n   * Optional uniqueness claim, attached as the `nonce` claim (a uuid is the\n   * intended shape; the Personal Server bounds it at 128 characters).\n   *\n   * @remarks\n   * A payload is otherwise fully determined by\n   * `{ aud, bodyHash, exp, grantId, iat, method, uri }`, so two identical\n   * requests signed inside the same second produce the same bytes. On the\n   * routes that keep a replay store (the MCP and write-session handshakes\n   * and delegated writes) the Personal Server refuses the second as a\n   * replay; with a nonce the replay key becomes `(signer, nonce)` instead,\n   * which is what lets a poll loop send the same request twice. The nonce\n   * is then single use itself: re-using one is a replay even when the rest\n   * of the payload changed. Plain data reads keep no replay store; their\n   * exposure is bounded by the lifetime cap.\n   */\n  nonce?: string;\n  /** Pre-computed `bodyHash` claim — overrides `body`. */\n  bodyHash?: string;\n}): Promise<string> {\n  const now = Math.floor(Date.now() / 1000);\n  const iat = params.iat ?? now;\n  const exp = params.exp ?? iat + DEFAULT_TTL_SECONDS;\n\n  const payload: Record<string, unknown> = {\n    aud: params.aud,\n    bodyHash: params.bodyHash ?? computeBodyHash(params.body),\n    exp,\n    iat,\n    method: params.method,\n    uri: params.uri,\n  };\n\n  if (params.grantId !== undefined) {\n    payload[\"grantId\"] = params.grantId;\n  }\n\n  // Merged before the sort, so the nonce sits in its alphabetical place like\n  // every other claim and the payload stays deterministic.\n  if (params.nonce !== undefined) {\n    payload[\"nonce\"] = params.nonce;\n  }\n\n  // Sort keys for deterministic serialization.\n  const sortedPayload = Object.keys(payload)\n    .sort()\n    .reduce<Record<string, unknown>>((acc, key) => {\n      acc[key] = payload[key];\n      return acc;\n    }, {});\n\n  const payloadJson = JSON.stringify(sortedPayload);\n  const payloadBytes = new TextEncoder().encode(payloadJson);\n  const payloadBase64 = base64urlEncode(payloadBytes);\n\n  const signature = await params.signMessage(payloadBase64);\n\n  return `Web3Signed ${payloadBase64}.${signature}`;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBA,kBAAuB;AACvB,kBAA2B;AAC3B,sBAAyB;AASzB,MAAM,kBACJ;AAGF,MAAM,sBAAsB;AAG5B,SAAS,gBAAgB,OAA2B;AAClD,aAAO,0BAAS,KAAK,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,EAAE;AACtB;AAGO,SAAS,gBAAgB,MAAsC;AACpE,MAAI,CAAC,QAAQ,KAAK,WAAW,GAAG;AAC9B,WAAO;AAAA,EACT;AACA,QAAM,aAAS,oBAAO,IAAI;AAC1B,SAAO,cAAU,wBAAW,MAAM,EAAE,MAAM,CAAC,CAAC;AAC9C;AAOA,eAAsB,sBAAsB,QAuCxB;AAClB,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,MAAM,OAAO,OAAO;AAC1B,QAAM,MAAM,OAAO,OAAO,MAAM;AAEhC,QAAM,UAAmC;AAAA,IACvC,KAAK,OAAO;AAAA,IACZ,UAAU,OAAO,YAAY,gBAAgB,OAAO,IAAI;AAAA,IACxD;AAAA,IACA;AAAA,IACA,QAAQ,OAAO;AAAA,IACf,KAAK,OAAO;AAAA,EACd;AAEA,MAAI,OAAO,YAAY,QAAW;AAChC,YAAQ,SAAS,IAAI,OAAO;AAAA,EAC9B;AAIA,MAAI,OAAO,UAAU,QAAW;AAC9B,YAAQ,OAAO,IAAI,OAAO;AAAA,EAC5B;AAGA,QAAM,gBAAgB,OAAO,KAAK,OAAO,EACtC,KAAK,EACL,OAAgC,CAAC,KAAK,QAAQ;AAC7C,QAAI,GAAG,IAAI,QAAQ,GAAG;AACtB,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AAEP,QAAM,cAAc,KAAK,UAAU,aAAa;AAChD,QAAM,eAAe,IAAI,YAAY,EAAE,OAAO,WAAW;AACzD,QAAM,gBAAgB,gBAAgB,YAAY;AAElD,QAAM,YAAY,MAAM,OAAO,YAAY,aAAa;AAExD,SAAO,cAAc,aAAa,IAAI,SAAS;AACjD;","names":[]}

package/dist/auth/web3-signed-builder.d.ts

@@ -38,7 +38,10 @@ export declare function buildWeb3SignedHeader(params: {
     body?: Uint8Array;
     /** Issued-at (unix seconds). Defaults to now. */
     iat?: number;
-    /** Expiry (unix seconds). Defaults to `iat + 300`. */
+    /**
+     * Expiry (unix seconds). Defaults to `iat + 300`. Verifiers reject a window
+     * longer than 15 minutes after `iat` (see `verifyWeb3Signed`).
+     */
     exp?: number;
     /** Optional grant id, attached as the `grantId` claim. */
     grantId?: string;
@@ -49,11 +52,14 @@ export declare function buildWeb3SignedHeader(params: {
      * @remarks
      * A payload is otherwise fully determined by
      * `{ aud, bodyHash, exp, grantId, iat, method, uri }`, so two identical
-     * requests signed inside the same second produce the same bytes and the
-     * Personal Server refuses the second as a replay. With a nonce the replay
-     * key becomes `(signer, nonce)` instead, which is what lets a poll loop
-     * send the same request twice. The nonce is then single use itself:
-     * re-using one is a replay even when the rest of the payload changed.
+     * requests signed inside the same second produce the same bytes. On the
+     * routes that keep a replay store (the MCP and write-session handshakes
+     * and delegated writes) the Personal Server refuses the second as a
+     * replay; with a nonce the replay key becomes `(signer, nonce)` instead,
+     * which is what lets a poll loop send the same request twice. The nonce
+     * is then single use itself: re-using one is a replay even when the rest
+     * of the payload changed. Plain data reads keep no replay store; their
+     * exposure is bounded by the lifetime cap.
      */
     nonce?: string;
     /** Pre-computed `bodyHash` claim — overrides `body`. */

package/dist/auth/web3-signed-builder.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/auth/web3-signed-builder.ts"],"sourcesContent":["/**\n * Builder for Web3Signed Authorization headers.\n *\n * @remarks\n * Ported from `personal-server-ts`\n * (`packages/core/src/signing/request-signer.ts`). The original was wired\n * to a Node-only `ServerAccount` and `node:crypto`. This isomorphic version\n * accepts any `signMessage` callback (viem accounts, wallet clients, etc.)\n * and uses `@noble/hashes` for SHA-256 so it runs in browsers and Workers.\n *\n * Wire format is identical to PS — payload is JSON with sorted keys,\n * base64url-encoded, signed via EIP-191.\n *\n * @category Auth\n */\n\nimport { sha256 } from \"@noble/hashes/sha2\";\nimport { bytesToHex } from \"viem\";\nimport { toBase64 } from \"../utils/encoding\";\n\n/**\n * Sign-message callback compatible with viem `LocalAccount`/`WalletClient`-style\n * signers. Must produce an EIP-191 (`personal_sign`) signature.\n */\nexport type Web3SignedSignFn = (message: string) => Promise<`0x${string}`>;\n\n/** SHA-256 of the empty string — bodyHash for empty bodies. */\nconst EMPTY_BODY_HASH =\n  \"sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\";\n\n/** Default token lifetime (seconds). */\nconst DEFAULT_TTL_SECONDS = 300;\n\n/** Base64url encode bytes (no padding). */\nfunction base64urlEncode(input: Uint8Array): string {\n  return toBase64(input)\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/, \"\");\n}\n\n/** Compute the `sha256:<hex>` bodyHash claim for a request body. */\nexport function computeBodyHash(body: Uint8Array | undefined): string {\n  if (!body || body.length === 0) {\n    return EMPTY_BODY_HASH;\n  }\n  const digest = sha256(body);\n  return `sha256:${bytesToHex(digest).slice(2)}`;\n}\n\n/**\n * Build a Web3Signed Authorization header value.\n *\n * @returns The full header value (`\"Web3Signed <base64url>.<sig>\"`).\n */\nexport async function buildWeb3SignedHeader(params: {\n  /** EIP-191 signer (e.g. viem `account.signMessage`). */\n  signMessage: Web3SignedSignFn;\n  /** Expected origin (e.g. `\"https://ps.example.com\"`). */\n  aud: string;\n  /** HTTP method (e.g. `\"GET\"`). */\n  method: string;\n  /** Request URI/path (e.g. `\"/v1/data/instagram.profile\"`). */\n  uri: string;\n  /** Optional request body — when present, used to compute `bodyHash`. */\n  body?: Uint8Array;\n  /** Issued-at (unix seconds). Defaults to now. */\n  iat?: number;\n  /** Expiry (unix seconds). Defaults to `iat + 300`. */\n  exp?: number;\n  /** Optional grant id, attached as the `grantId` claim. */\n  grantId?: string;\n  /**\n   * Optional uniqueness claim, attached as the `nonce` claim (a uuid is the\n   * intended shape; the Personal Server bounds it at 128 characters).\n   *\n   * @remarks\n   * A payload is otherwise fully determined by\n   * `{ aud, bodyHash, exp, grantId, iat, method, uri }`, so two identical\n   * requests signed inside the same second produce the same bytes and the\n   * Personal Server refuses the second as a replay. With a nonce the replay\n   * key becomes `(signer, nonce)` instead, which is what lets a poll loop\n   * send the same request twice. The nonce is then single use itself:\n   * re-using one is a replay even when the rest of the payload changed.\n   */\n  nonce?: string;\n  /** Pre-computed `bodyHash` claim — overrides `body`. */\n  bodyHash?: string;\n}): Promise<string> {\n  const now = Math.floor(Date.now() / 1000);\n  const iat = params.iat ?? now;\n  const exp = params.exp ?? iat + DEFAULT_TTL_SECONDS;\n\n  const payload: Record<string, unknown> = {\n    aud: params.aud,\n    bodyHash: params.bodyHash ?? computeBodyHash(params.body),\n    exp,\n    iat,\n    method: params.method,\n    uri: params.uri,\n  };\n\n  if (params.grantId !== undefined) {\n    payload[\"grantId\"] = params.grantId;\n  }\n\n  // Merged before the sort, so the nonce sits in its alphabetical place like\n  // every other claim and the payload stays deterministic.\n  if (params.nonce !== undefined) {\n    payload[\"nonce\"] = params.nonce;\n  }\n\n  // Sort keys for deterministic serialization.\n  const sortedPayload = Object.keys(payload)\n    .sort()\n    .reduce<Record<string, unknown>>((acc, key) => {\n      acc[key] = payload[key];\n      return acc;\n    }, {});\n\n  const payloadJson = JSON.stringify(sortedPayload);\n  const payloadBytes = new TextEncoder().encode(payloadJson);\n  const payloadBase64 = base64urlEncode(payloadBytes);\n\n  const signature = await params.signMessage(payloadBase64);\n\n  return `Web3Signed ${payloadBase64}.${signature}`;\n}\n"],"mappings":"AAgBA,SAAS,cAAc;AACvB,SAAS,kBAAkB;AAC3B,SAAS,gBAAgB;AASzB,MAAM,kBACJ;AAGF,MAAM,sBAAsB;AAG5B,SAAS,gBAAgB,OAA2B;AAClD,SAAO,SAAS,KAAK,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,EAAE;AACtB;AAGO,SAAS,gBAAgB,MAAsC;AACpE,MAAI,CAAC,QAAQ,KAAK,WAAW,GAAG;AAC9B,WAAO;AAAA,EACT;AACA,QAAM,SAAS,OAAO,IAAI;AAC1B,SAAO,UAAU,WAAW,MAAM,EAAE,MAAM,CAAC,CAAC;AAC9C;AAOA,eAAsB,sBAAsB,QAiCxB;AAClB,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,MAAM,OAAO,OAAO;AAC1B,QAAM,MAAM,OAAO,OAAO,MAAM;AAEhC,QAAM,UAAmC;AAAA,IACvC,KAAK,OAAO;AAAA,IACZ,UAAU,OAAO,YAAY,gBAAgB,OAAO,IAAI;AAAA,IACxD;AAAA,IACA;AAAA,IACA,QAAQ,OAAO;AAAA,IACf,KAAK,OAAO;AAAA,EACd;AAEA,MAAI,OAAO,YAAY,QAAW;AAChC,YAAQ,SAAS,IAAI,OAAO;AAAA,EAC9B;AAIA,MAAI,OAAO,UAAU,QAAW;AAC9B,YAAQ,OAAO,IAAI,OAAO;AAAA,EAC5B;AAGA,QAAM,gBAAgB,OAAO,KAAK,OAAO,EACtC,KAAK,EACL,OAAgC,CAAC,KAAK,QAAQ;AAC7C,QAAI,GAAG,IAAI,QAAQ,GAAG;AACtB,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AAEP,QAAM,cAAc,KAAK,UAAU,aAAa;AAChD,QAAM,eAAe,IAAI,YAAY,EAAE,OAAO,WAAW;AACzD,QAAM,gBAAgB,gBAAgB,YAAY;AAElD,QAAM,YAAY,MAAM,OAAO,YAAY,aAAa;AAExD,SAAO,cAAc,aAAa,IAAI,SAAS;AACjD;","names":[]}
+{"version":3,"sources":["../../src/auth/web3-signed-builder.ts"],"sourcesContent":["/**\n * Builder for Web3Signed Authorization headers.\n *\n * @remarks\n * Ported from `personal-server-ts`\n * (`packages/core/src/signing/request-signer.ts`). The original was wired\n * to a Node-only `ServerAccount` and `node:crypto`. This isomorphic version\n * accepts any `signMessage` callback (viem accounts, wallet clients, etc.)\n * and uses `@noble/hashes` for SHA-256 so it runs in browsers and Workers.\n *\n * Wire format is identical to PS — payload is JSON with sorted keys,\n * base64url-encoded, signed via EIP-191.\n *\n * @category Auth\n */\n\nimport { sha256 } from \"@noble/hashes/sha2\";\nimport { bytesToHex } from \"viem\";\nimport { toBase64 } from \"../utils/encoding\";\n\n/**\n * Sign-message callback compatible with viem `LocalAccount`/`WalletClient`-style\n * signers. Must produce an EIP-191 (`personal_sign`) signature.\n */\nexport type Web3SignedSignFn = (message: string) => Promise<`0x${string}`>;\n\n/** SHA-256 of the empty string — bodyHash for empty bodies. */\nconst EMPTY_BODY_HASH =\n  \"sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855\";\n\n/** Default token lifetime (seconds). */\nconst DEFAULT_TTL_SECONDS = 300;\n\n/** Base64url encode bytes (no padding). */\nfunction base64urlEncode(input: Uint8Array): string {\n  return toBase64(input)\n    .replace(/\\+/g, \"-\")\n    .replace(/\\//g, \"_\")\n    .replace(/=+$/, \"\");\n}\n\n/** Compute the `sha256:<hex>` bodyHash claim for a request body. */\nexport function computeBodyHash(body: Uint8Array | undefined): string {\n  if (!body || body.length === 0) {\n    return EMPTY_BODY_HASH;\n  }\n  const digest = sha256(body);\n  return `sha256:${bytesToHex(digest).slice(2)}`;\n}\n\n/**\n * Build a Web3Signed Authorization header value.\n *\n * @returns The full header value (`\"Web3Signed <base64url>.<sig>\"`).\n */\nexport async function buildWeb3SignedHeader(params: {\n  /** EIP-191 signer (e.g. viem `account.signMessage`). */\n  signMessage: Web3SignedSignFn;\n  /** Expected origin (e.g. `\"https://ps.example.com\"`). */\n  aud: string;\n  /** HTTP method (e.g. `\"GET\"`). */\n  method: string;\n  /** Request URI/path (e.g. `\"/v1/data/instagram.profile\"`). */\n  uri: string;\n  /** Optional request body — when present, used to compute `bodyHash`. */\n  body?: Uint8Array;\n  /** Issued-at (unix seconds). Defaults to now. */\n  iat?: number;\n  /**\n   * Expiry (unix seconds). Defaults to `iat + 300`. Verifiers reject a window\n   * longer than 15 minutes after `iat` (see `verifyWeb3Signed`).\n   */\n  exp?: number;\n  /** Optional grant id, attached as the `grantId` claim. */\n  grantId?: string;\n  /**\n   * Optional uniqueness claim, attached as the `nonce` claim (a uuid is the\n   * intended shape; the Personal Server bounds it at 128 characters).\n   *\n   * @remarks\n   * A payload is otherwise fully determined by\n   * `{ aud, bodyHash, exp, grantId, iat, method, uri }`, so two identical\n   * requests signed inside the same second produce the same bytes. On the\n   * routes that keep a replay store (the MCP and write-session handshakes\n   * and delegated writes) the Personal Server refuses the second as a\n   * replay; with a nonce the replay key becomes `(signer, nonce)` instead,\n   * which is what lets a poll loop send the same request twice. The nonce\n   * is then single use itself: re-using one is a replay even when the rest\n   * of the payload changed. Plain data reads keep no replay store; their\n   * exposure is bounded by the lifetime cap.\n   */\n  nonce?: string;\n  /** Pre-computed `bodyHash` claim — overrides `body`. */\n  bodyHash?: string;\n}): Promise<string> {\n  const now = Math.floor(Date.now() / 1000);\n  const iat = params.iat ?? now;\n  const exp = params.exp ?? iat + DEFAULT_TTL_SECONDS;\n\n  const payload: Record<string, unknown> = {\n    aud: params.aud,\n    bodyHash: params.bodyHash ?? computeBodyHash(params.body),\n    exp,\n    iat,\n    method: params.method,\n    uri: params.uri,\n  };\n\n  if (params.grantId !== undefined) {\n    payload[\"grantId\"] = params.grantId;\n  }\n\n  // Merged before the sort, so the nonce sits in its alphabetical place like\n  // every other claim and the payload stays deterministic.\n  if (params.nonce !== undefined) {\n    payload[\"nonce\"] = params.nonce;\n  }\n\n  // Sort keys for deterministic serialization.\n  const sortedPayload = Object.keys(payload)\n    .sort()\n    .reduce<Record<string, unknown>>((acc, key) => {\n      acc[key] = payload[key];\n      return acc;\n    }, {});\n\n  const payloadJson = JSON.stringify(sortedPayload);\n  const payloadBytes = new TextEncoder().encode(payloadJson);\n  const payloadBase64 = base64urlEncode(payloadBytes);\n\n  const signature = await params.signMessage(payloadBase64);\n\n  return `Web3Signed ${payloadBase64}.${signature}`;\n}\n"],"mappings":"AAgBA,SAAS,cAAc;AACvB,SAAS,kBAAkB;AAC3B,SAAS,gBAAgB;AASzB,MAAM,kBACJ;AAGF,MAAM,sBAAsB;AAG5B,SAAS,gBAAgB,OAA2B;AAClD,SAAO,SAAS,KAAK,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,GAAG,EAClB,QAAQ,OAAO,EAAE;AACtB;AAGO,SAAS,gBAAgB,MAAsC;AACpE,MAAI,CAAC,QAAQ,KAAK,WAAW,GAAG;AAC9B,WAAO;AAAA,EACT;AACA,QAAM,SAAS,OAAO,IAAI;AAC1B,SAAO,UAAU,WAAW,MAAM,EAAE,MAAM,CAAC,CAAC;AAC9C;AAOA,eAAsB,sBAAsB,QAuCxB;AAClB,QAAM,MAAM,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AACxC,QAAM,MAAM,OAAO,OAAO;AAC1B,QAAM,MAAM,OAAO,OAAO,MAAM;AAEhC,QAAM,UAAmC;AAAA,IACvC,KAAK,OAAO;AAAA,IACZ,UAAU,OAAO,YAAY,gBAAgB,OAAO,IAAI;AAAA,IACxD;AAAA,IACA;AAAA,IACA,QAAQ,OAAO;AAAA,IACf,KAAK,OAAO;AAAA,EACd;AAEA,MAAI,OAAO,YAAY,QAAW;AAChC,YAAQ,SAAS,IAAI,OAAO;AAAA,EAC9B;AAIA,MAAI,OAAO,UAAU,QAAW;AAC9B,YAAQ,OAAO,IAAI,OAAO;AAAA,EAC5B;AAGA,QAAM,gBAAgB,OAAO,KAAK,OAAO,EACtC,KAAK,EACL,OAAgC,CAAC,KAAK,QAAQ;AAC7C,QAAI,GAAG,IAAI,QAAQ,GAAG;AACtB,WAAO;AAAA,EACT,GAAG,CAAC,CAAC;AAEP,QAAM,cAAc,KAAK,UAAU,aAAa;AAChD,QAAM,eAAe,IAAI,YAAY,EAAE,OAAO,WAAW;AACzD,QAAM,gBAAgB,gBAAgB,YAAY;AAElD,QAAM,YAAY,MAAM,OAAO,YAAY,aAAa;AAExD,SAAO,cAAc,aAAa,IAAI,SAAS;AACjD;","names":[]}

package/dist/auth/web3-signed.cjs

@@ -18,6 +18,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var web3_signed_exports = {};
 __export(web3_signed_exports, {
+  MAX_WEB3SIGNED_LIFETIME_SECONDS: () => MAX_WEB3SIGNED_LIFETIME_SECONDS,
   parseWeb3SignedHeader: () => parseWeb3SignedHeader,
   verifyWeb3Signed: () => verifyWeb3Signed
 });
@@ -28,6 +29,7 @@ var import_errors = require("./errors.cjs");
 var import_web3_signed_builder = require("./web3-signed-builder");
 const WEB3_SIGNED_PREFIX = "Web3Signed ";
 const CLOCK_SKEW_SECONDS = 60;
+const MAX_WEB3SIGNED_LIFETIME_SECONDS = 15 * 60;
 function base64urlDecode(input) {
   let base64 = input.replace(/-/g, "+").replace(/_/g, "/");
   const padLength = (4 - base64.length % 4) % 4;
@@ -140,10 +142,19 @@ async function verifyWeb3Signed(params) {
   if (payload.iat > now + CLOCK_SKEW_SECONDS) {
     throw new import_errors.ExpiredTokenError({ reason: "Token issued in the future" });
   }
+  const lifetime = payload.exp - payload.iat;
+  if (lifetime <= 0 || lifetime > MAX_WEB3SIGNED_LIFETIME_SECONDS) {
+    throw new import_errors.ExpiredTokenError({
+      reason: "Token lifetime exceeds the maximum",
+      maxLifetimeSeconds: MAX_WEB3SIGNED_LIFETIME_SECONDS,
+      lifetimeSeconds: lifetime
+    });
+  }
   return { signer, payload };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  MAX_WEB3SIGNED_LIFETIME_SECONDS,
   parseWeb3SignedHeader,
   verifyWeb3Signed
 });

package/dist/auth/web3-signed.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/auth/web3-signed.ts"],"sourcesContent":["/**\n * Web3Signed Authorization header parsing and verification.\n *\n * @remarks\n * Header format: `\"Web3Signed {base64url(payload)}.{signature}\"`.\n * Payload is JSON with fields `aud`, `method`, `uri`, `bodyHash`, `iat`, `exp`,\n * and optional `grantId`. The signature is EIP-191 over the base64url-encoded\n * payload string.\n *\n * Ported from `personal-server-ts` (`packages/core/src/auth/web3-signed.ts`).\n * Adjusted to be isomorphic (no `Buffer`) and to use SDK-local error types.\n *\n * @category Auth\n */\n\nimport { recoverMessageAddress } from \"viem\";\nimport { fromBase64 } from \"../utils/encoding\";\nimport {\n  MissingAuthError,\n  InvalidSignatureError,\n  ExpiredTokenError,\n} from \"./errors\";\nimport { computeBodyHash } from \"./web3-signed-builder\";\n\nexport interface Web3SignedPayload {\n  aud: string;\n  method: string;\n  uri: string;\n  bodyHash: string;\n  iat: number;\n  exp: number;\n  grantId?: string;\n}\n\nexport interface VerifiedAuth {\n  signer: `0x${string}`;\n  payload: Web3SignedPayload;\n}\n\nconst WEB3_SIGNED_PREFIX = \"Web3Signed \";\nconst CLOCK_SKEW_SECONDS = 60;\n\n/** Decode a base64url string (no padding) to UTF-8. */\nfunction base64urlDecode(input: string): string {\n  let base64 = input.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const padLength = (4 - (base64.length % 4)) % 4;\n  base64 += \"=\".repeat(padLength);\n  return new TextDecoder().decode(fromBase64(base64));\n}\n\nfunction isFiniteNumber(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isFinite(value);\n}\n\nfunction parsePayload(value: unknown): Web3SignedPayload {\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n    throw new InvalidSignatureError({ reason: \"Invalid payload shape\" });\n  }\n\n  const payload = value as Record<string, unknown>;\n  if (\n    typeof payload[\"aud\"] !== \"string\" ||\n    typeof payload[\"method\"] !== \"string\" ||\n    typeof payload[\"uri\"] !== \"string\" ||\n    typeof payload[\"bodyHash\"] !== \"string\" ||\n    !isFiniteNumber(payload[\"iat\"]) ||\n    !isFiniteNumber(payload[\"exp\"])\n  ) {\n    throw new InvalidSignatureError({ reason: \"Invalid payload claims\" });\n  }\n\n  if (\n    payload[\"grantId\"] !== undefined &&\n    typeof payload[\"grantId\"] !== \"string\"\n  ) {\n    throw new InvalidSignatureError({ reason: \"Invalid grantId claim\" });\n  }\n\n  return {\n    aud: payload[\"aud\"],\n    method: payload[\"method\"],\n    uri: payload[\"uri\"],\n    bodyHash: payload[\"bodyHash\"],\n    iat: payload[\"iat\"],\n    exp: payload[\"exp\"],\n    grantId: payload[\"grantId\"],\n  };\n}\n\n/**\n * Parse a `\"Web3Signed <base64url>.<signature>\"` header value.\n *\n * @throws {MissingAuthError} If the header is missing or empty.\n * @throws {InvalidSignatureError} If the format is invalid.\n */\nexport function parseWeb3SignedHeader(headerValue: string | undefined): {\n  payloadBase64: string;\n  payload: Web3SignedPayload;\n  signature: `0x${string}`;\n} {\n  if (!headerValue) {\n    throw new MissingAuthError();\n  }\n\n  if (!headerValue.startsWith(WEB3_SIGNED_PREFIX)) {\n    throw new InvalidSignatureError({ reason: \"Missing Web3Signed prefix\" });\n  }\n\n  const value = headerValue.slice(WEB3_SIGNED_PREFIX.length);\n  const dotIndex = value.indexOf(\".\");\n  if (dotIndex === -1 || dotIndex === 0 || dotIndex === value.length - 1) {\n    throw new InvalidSignatureError({ reason: \"Invalid header format\" });\n  }\n\n  const payloadBase64 = value.slice(0, dotIndex);\n  const signatureStr = value.slice(dotIndex + 1);\n\n  if (!signatureStr.startsWith(\"0x\")) {\n    throw new InvalidSignatureError({ reason: \"Invalid signature format\" });\n  }\n\n  let payload: Web3SignedPayload;\n  try {\n    const decoded = base64urlDecode(payloadBase64);\n    payload = parsePayload(JSON.parse(decoded));\n  } catch (err) {\n    if (err instanceof InvalidSignatureError) throw err;\n    throw new InvalidSignatureError({ reason: \"Invalid payload encoding\" });\n  }\n\n  return {\n    payloadBase64,\n    payload,\n    signature: signatureStr as `0x${string}`,\n  };\n}\n\n/**\n * Full verification: parse header, recover signer via EIP-191, check claims.\n *\n * @remarks\n * Steps:\n * 1. Parse header to base64url + signature.\n * 2. Recover signer via {@link recoverMessageAddress} (EIP-191) over the base64url payload string.\n * 3. Check `aud === expectedOrigin`, `method === expectedMethod`, `uri === expectedPath`.\n * 4. Optionally check `bodyHash` against `bodyBytes`.\n * 5. Check `iat`/`exp` within a 60s clock skew.\n *\n * @returns The recovered signer address and parsed payload.\n */\nexport async function verifyWeb3Signed(params: {\n  headerValue: string | undefined;\n  expectedOrigin: string;\n  expectedMethod: string;\n  expectedPath: string;\n  bodyBytes?: Uint8Array;\n  now?: number;\n}): Promise<VerifiedAuth> {\n  const { payloadBase64, payload, signature } = parseWeb3SignedHeader(\n    params.headerValue,\n  );\n\n  let signer: `0x${string}`;\n  try {\n    signer = await recoverMessageAddress({\n      message: payloadBase64,\n      signature,\n    });\n  } catch {\n    throw new InvalidSignatureError({ reason: \"Signature recovery failed\" });\n  }\n\n  if (payload.aud !== params.expectedOrigin) {\n    throw new InvalidSignatureError({\n      reason: \"Audience mismatch\",\n      expected: params.expectedOrigin,\n      actual: payload.aud,\n    });\n  }\n\n  if (payload.method !== params.expectedMethod) {\n    throw new InvalidSignatureError({\n      reason: \"Method mismatch\",\n      expected: params.expectedMethod,\n      actual: payload.method,\n    });\n  }\n\n  if (payload.uri !== params.expectedPath) {\n    throw new InvalidSignatureError({\n      reason: \"URI mismatch\",\n      expected: params.expectedPath,\n      actual: payload.uri,\n    });\n  }\n\n  if (params.bodyBytes !== undefined) {\n    const expectedBodyHash = computeBodyHash(params.bodyBytes);\n    if (payload.bodyHash !== expectedBodyHash) {\n      throw new InvalidSignatureError({\n        reason: \"Body hash mismatch\",\n        expected: expectedBodyHash,\n        actual: payload.bodyHash,\n      });\n    }\n  }\n\n  const now = params.now ?? Math.floor(Date.now() / 1000);\n\n  if (payload.exp < now - CLOCK_SKEW_SECONDS) {\n    throw new ExpiredTokenError({ reason: \"Token expired\" });\n  }\n\n  if (payload.iat > now + CLOCK_SKEW_SECONDS) {\n    throw new ExpiredTokenError({ reason: \"Token issued in the future\" });\n  }\n\n  return { signer, payload };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/auth/web3-signed.ts"],"sourcesContent":["/**\n * Web3Signed Authorization header parsing and verification.\n *\n * @remarks\n * Header format: `\"Web3Signed {base64url(payload)}.{signature}\"`.\n * Payload is JSON with fields `aud`, `method`, `uri`, `bodyHash`, `iat`, `exp`,\n * and optional `grantId`. The signature is EIP-191 over the base64url-encoded\n * payload string.\n *\n * Ported from `personal-server-ts` (`packages/core/src/auth/web3-signed.ts`).\n * Adjusted to be isomorphic (no `Buffer`) and to use SDK-local error types.\n *\n * @category Auth\n */\n\nimport { recoverMessageAddress } from \"viem\";\nimport { fromBase64 } from \"../utils/encoding\";\nimport {\n  MissingAuthError,\n  InvalidSignatureError,\n  ExpiredTokenError,\n} from \"./errors\";\nimport { computeBodyHash } from \"./web3-signed-builder\";\n\nexport interface Web3SignedPayload {\n  aud: string;\n  method: string;\n  uri: string;\n  bodyHash: string;\n  iat: number;\n  exp: number;\n  grantId?: string;\n}\n\nexport interface VerifiedAuth {\n  signer: `0x${string}`;\n  payload: Web3SignedPayload;\n}\n\nconst WEB3_SIGNED_PREFIX = \"Web3Signed \";\nconst CLOCK_SKEW_SECONDS = 60;\n\n/**\n * Longest `exp - iat` window a Web3Signed header may carry (seconds). Without\n * this bound the signer chooses how long a captured request stays replayable.\n *\n * @category Auth\n */\nexport const MAX_WEB3SIGNED_LIFETIME_SECONDS = 15 * 60;\n\n/** Decode a base64url string (no padding) to UTF-8. */\nfunction base64urlDecode(input: string): string {\n  let base64 = input.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const padLength = (4 - (base64.length % 4)) % 4;\n  base64 += \"=\".repeat(padLength);\n  return new TextDecoder().decode(fromBase64(base64));\n}\n\nfunction isFiniteNumber(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isFinite(value);\n}\n\nfunction parsePayload(value: unknown): Web3SignedPayload {\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n    throw new InvalidSignatureError({ reason: \"Invalid payload shape\" });\n  }\n\n  const payload = value as Record<string, unknown>;\n  if (\n    typeof payload[\"aud\"] !== \"string\" ||\n    typeof payload[\"method\"] !== \"string\" ||\n    typeof payload[\"uri\"] !== \"string\" ||\n    typeof payload[\"bodyHash\"] !== \"string\" ||\n    !isFiniteNumber(payload[\"iat\"]) ||\n    !isFiniteNumber(payload[\"exp\"])\n  ) {\n    throw new InvalidSignatureError({ reason: \"Invalid payload claims\" });\n  }\n\n  if (\n    payload[\"grantId\"] !== undefined &&\n    typeof payload[\"grantId\"] !== \"string\"\n  ) {\n    throw new InvalidSignatureError({ reason: \"Invalid grantId claim\" });\n  }\n\n  return {\n    aud: payload[\"aud\"],\n    method: payload[\"method\"],\n    uri: payload[\"uri\"],\n    bodyHash: payload[\"bodyHash\"],\n    iat: payload[\"iat\"],\n    exp: payload[\"exp\"],\n    grantId: payload[\"grantId\"],\n  };\n}\n\n/**\n * Parse a `\"Web3Signed <base64url>.<signature>\"` header value.\n *\n * @throws {MissingAuthError} If the header is missing or empty.\n * @throws {InvalidSignatureError} If the format is invalid.\n */\nexport function parseWeb3SignedHeader(headerValue: string | undefined): {\n  payloadBase64: string;\n  payload: Web3SignedPayload;\n  signature: `0x${string}`;\n} {\n  if (!headerValue) {\n    throw new MissingAuthError();\n  }\n\n  if (!headerValue.startsWith(WEB3_SIGNED_PREFIX)) {\n    throw new InvalidSignatureError({ reason: \"Missing Web3Signed prefix\" });\n  }\n\n  const value = headerValue.slice(WEB3_SIGNED_PREFIX.length);\n  const dotIndex = value.indexOf(\".\");\n  if (dotIndex === -1 || dotIndex === 0 || dotIndex === value.length - 1) {\n    throw new InvalidSignatureError({ reason: \"Invalid header format\" });\n  }\n\n  const payloadBase64 = value.slice(0, dotIndex);\n  const signatureStr = value.slice(dotIndex + 1);\n\n  if (!signatureStr.startsWith(\"0x\")) {\n    throw new InvalidSignatureError({ reason: \"Invalid signature format\" });\n  }\n\n  let payload: Web3SignedPayload;\n  try {\n    const decoded = base64urlDecode(payloadBase64);\n    payload = parsePayload(JSON.parse(decoded));\n  } catch (err) {\n    if (err instanceof InvalidSignatureError) throw err;\n    throw new InvalidSignatureError({ reason: \"Invalid payload encoding\" });\n  }\n\n  return {\n    payloadBase64,\n    payload,\n    signature: signatureStr as `0x${string}`,\n  };\n}\n\n/**\n * Full verification: parse header, recover signer via EIP-191, check claims.\n *\n * @remarks\n * Steps:\n * 1. Parse header to base64url + signature.\n * 2. Recover signer via {@link recoverMessageAddress} (EIP-191) over the base64url payload string.\n * 3. Check `aud === expectedOrigin`, `method === expectedMethod`, `uri === expectedPath`.\n * 4. Optionally check `bodyHash` against `bodyBytes`.\n * 5. Check `iat`/`exp` within a 60s clock skew.\n *\n * @returns The recovered signer address and parsed payload.\n */\nexport async function verifyWeb3Signed(params: {\n  headerValue: string | undefined;\n  expectedOrigin: string;\n  expectedMethod: string;\n  expectedPath: string;\n  bodyBytes?: Uint8Array;\n  now?: number;\n}): Promise<VerifiedAuth> {\n  const { payloadBase64, payload, signature } = parseWeb3SignedHeader(\n    params.headerValue,\n  );\n\n  let signer: `0x${string}`;\n  try {\n    signer = await recoverMessageAddress({\n      message: payloadBase64,\n      signature,\n    });\n  } catch {\n    throw new InvalidSignatureError({ reason: \"Signature recovery failed\" });\n  }\n\n  if (payload.aud !== params.expectedOrigin) {\n    throw new InvalidSignatureError({\n      reason: \"Audience mismatch\",\n      expected: params.expectedOrigin,\n      actual: payload.aud,\n    });\n  }\n\n  if (payload.method !== params.expectedMethod) {\n    throw new InvalidSignatureError({\n      reason: \"Method mismatch\",\n      expected: params.expectedMethod,\n      actual: payload.method,\n    });\n  }\n\n  if (payload.uri !== params.expectedPath) {\n    throw new InvalidSignatureError({\n      reason: \"URI mismatch\",\n      expected: params.expectedPath,\n      actual: payload.uri,\n    });\n  }\n\n  if (params.bodyBytes !== undefined) {\n    const expectedBodyHash = computeBodyHash(params.bodyBytes);\n    if (payload.bodyHash !== expectedBodyHash) {\n      throw new InvalidSignatureError({\n        reason: \"Body hash mismatch\",\n        expected: expectedBodyHash,\n        actual: payload.bodyHash,\n      });\n    }\n  }\n\n  const now = params.now ?? Math.floor(Date.now() / 1000);\n\n  if (payload.exp < now - CLOCK_SKEW_SECONDS) {\n    throw new ExpiredTokenError({ reason: \"Token expired\" });\n  }\n\n  if (payload.iat > now + CLOCK_SKEW_SECONDS) {\n    throw new ExpiredTokenError({ reason: \"Token issued in the future\" });\n  }\n\n  // Bound the window the signer chose, not just where `now` falls in it:\n  // otherwise a captured request stays replayable for as long as the signer\n  // liked.\n  const lifetime = payload.exp - payload.iat;\n  if (lifetime <= 0 || lifetime > MAX_WEB3SIGNED_LIFETIME_SECONDS) {\n    throw new ExpiredTokenError({\n      reason: \"Token lifetime exceeds the maximum\",\n      maxLifetimeSeconds: MAX_WEB3SIGNED_LIFETIME_SECONDS,\n      lifetimeSeconds: lifetime,\n    });\n  }\n\n  return { signer, payload };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAeA,kBAAsC;AACtC,sBAA2B;AAC3B,oBAIO;AACP,iCAAgC;AAiBhC,MAAM,qBAAqB;AAC3B,MAAM,qBAAqB;AAQpB,MAAM,kCAAkC,KAAK;AAGpD,SAAS,gBAAgB,OAAuB;AAC9C,MAAI,SAAS,MAAM,QAAQ,MAAM,GAAG,EAAE,QAAQ,MAAM,GAAG;AACvD,QAAM,aAAa,IAAK,OAAO,SAAS,KAAM;AAC9C,YAAU,IAAI,OAAO,SAAS;AAC9B,SAAO,IAAI,YAAY,EAAE,WAAO,4BAAW,MAAM,CAAC;AACpD;AAEA,SAAS,eAAe,OAAiC;AACvD,SAAO,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK;AAC3D;AAEA,SAAS,aAAa,OAAmC;AACvD,MAAI,UAAU,QAAQ,OAAO,UAAU,YAAY,MAAM,QAAQ,KAAK,GAAG;AACvE,UAAM,IAAI,oCAAsB,EAAE,QAAQ,wBAAwB,CAAC;AAAA,EACrE;AAEA,QAAM,UAAU;AAChB,MACE,OAAO,QAAQ,KAAK,MAAM,YAC1B,OAAO,QAAQ,QAAQ,MAAM,YAC7B,OAAO,QAAQ,KAAK,MAAM,YAC1B,OAAO,QAAQ,UAAU,MAAM,YAC/B,CAAC,eAAe,QAAQ,KAAK,CAAC,KAC9B,CAAC,eAAe,QAAQ,KAAK,CAAC,GAC9B;AACA,UAAM,IAAI,oCAAsB,EAAE,QAAQ,yBAAyB,CAAC;AAAA,EACtE;AAEA,MACE,QAAQ,SAAS,MAAM,UACvB,OAAO,QAAQ,SAAS,MAAM,UAC9B;AACA,UAAM,IAAI,oCAAsB,EAAE,QAAQ,wBAAwB,CAAC;AAAA,EACrE;AAEA,SAAO;AAAA,IACL,KAAK,QAAQ,KAAK;AAAA,IAClB,QAAQ,QAAQ,QAAQ;AAAA,IACxB,KAAK,QAAQ,KAAK;AAAA,IAClB,UAAU,QAAQ,UAAU;AAAA,IAC5B,KAAK,QAAQ,KAAK;AAAA,IAClB,KAAK,QAAQ,KAAK;AAAA,IAClB,SAAS,QAAQ,SAAS;AAAA,EAC5B;AACF;AAQO,SAAS,sBAAsB,aAIpC;AACA,MAAI,CAAC,aAAa;AAChB,UAAM,IAAI,+BAAiB;AAAA,EAC7B;AAEA,MAAI,CAAC,YAAY,WAAW,kBAAkB,GAAG;AAC/C,UAAM,IAAI,oCAAsB,EAAE,QAAQ,4BAA4B,CAAC;AAAA,EACzE;AAEA,QAAM,QAAQ,YAAY,MAAM,mBAAmB,MAAM;AACzD,QAAM,WAAW,MAAM,QAAQ,GAAG;AAClC,MAAI,aAAa,MAAM,aAAa,KAAK,aAAa,MAAM,SAAS,GAAG;AACtE,UAAM,IAAI,oCAAsB,EAAE,QAAQ,wBAAwB,CAAC;AAAA,EACrE;AAEA,QAAM,gBAAgB,MAAM,MAAM,GAAG,QAAQ;AAC7C,QAAM,eAAe,MAAM,MAAM,WAAW,CAAC;AAE7C,MAAI,CAAC,aAAa,WAAW,IAAI,GAAG;AAClC,UAAM,IAAI,oCAAsB,EAAE,QAAQ,2BAA2B,CAAC;AAAA,EACxE;AAEA,MAAI;AACJ,MAAI;AACF,UAAM,UAAU,gBAAgB,aAAa;AAC7C,cAAU,aAAa,KAAK,MAAM,OAAO,CAAC;AAAA,EAC5C,SAAS,KAAK;AACZ,QAAI,eAAe,oCAAuB,OAAM;AAChD,UAAM,IAAI,oCAAsB,EAAE,QAAQ,2BAA2B,CAAC;AAAA,EACxE;AAEA,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,WAAW;AAAA,EACb;AACF;AAeA,eAAsB,iBAAiB,QAOb;AACxB,QAAM,EAAE,eAAe,SAAS,UAAU,IAAI;AAAA,IAC5C,OAAO;AAAA,EACT;AAEA,MAAI;AACJ,MAAI;AACF,aAAS,UAAM,mCAAsB;AAAA,MACnC,SAAS;AAAA,MACT;AAAA,IACF,CAAC;AAAA,EACH,QAAQ;AACN,UAAM,IAAI,oCAAsB,EAAE,QAAQ,4BAA4B,CAAC;AAAA,EACzE;AAEA,MAAI,QAAQ,QAAQ,OAAO,gBAAgB;AACzC,UAAM,IAAI,oCAAsB;AAAA,MAC9B,QAAQ;AAAA,MACR,UAAU,OAAO;AAAA,MACjB,QAAQ,QAAQ;AAAA,IAClB,CAAC;AAAA,EACH;AAEA,MAAI,QAAQ,WAAW,OAAO,gBAAgB;AAC5C,UAAM,IAAI,oCAAsB;AAAA,MAC9B,QAAQ;AAAA,MACR,UAAU,OAAO;AAAA,MACjB,QAAQ,QAAQ;AAAA,IAClB,CAAC;AAAA,EACH;AAEA,MAAI,QAAQ,QAAQ,OAAO,cAAc;AACvC,UAAM,IAAI,oCAAsB;AAAA,MAC9B,QAAQ;AAAA,MACR,UAAU,OAAO;AAAA,MACjB,QAAQ,QAAQ;AAAA,IAClB,CAAC;AAAA,EACH;AAEA,MAAI,OAAO,cAAc,QAAW;AAClC,UAAM,uBAAmB,4CAAgB,OAAO,SAAS;AACzD,QAAI,QAAQ,aAAa,kBAAkB;AACzC,YAAM,IAAI,oCAAsB;AAAA,QAC9B,QAAQ;AAAA,QACR,UAAU;AAAA,QACV,QAAQ,QAAQ;AAAA,MAClB,CAAC;AAAA,IACH;AAAA,EACF;AAEA,QAAM,MAAM,OAAO,OAAO,KAAK,MAAM,KAAK,IAAI,IAAI,GAAI;AAEtD,MAAI,QAAQ,MAAM,MAAM,oBAAoB;AAC1C,UAAM,IAAI,gCAAkB,EAAE,QAAQ,gBAAgB,CAAC;AAAA,EACzD;AAEA,MAAI,QAAQ,MAAM,MAAM,oBAAoB;AAC1C,UAAM,IAAI,gCAAkB,EAAE,QAAQ,6BAA6B,CAAC;AAAA,EACtE;AAKA,QAAM,WAAW,QAAQ,MAAM,QAAQ;AACvC,MAAI,YAAY,KAAK,WAAW,iCAAiC;AAC/D,UAAM,IAAI,gCAAkB;AAAA,MAC1B,QAAQ;AAAA,MACR,oBAAoB;AAAA,MACpB,iBAAiB;AAAA,IACnB,CAAC;AAAA,EACH;AAEA,SAAO,EAAE,QAAQ,QAAQ;AAC3B;","names":[]}

package/dist/auth/web3-signed.d.ts

@@ -25,6 +25,13 @@ export interface VerifiedAuth {
     signer: `0x${string}`;
     payload: Web3SignedPayload;
 }
+/**
+ * Longest `exp - iat` window a Web3Signed header may carry (seconds). Without
+ * this bound the signer chooses how long a captured request stays replayable.
+ *
+ * @category Auth
+ */
+export declare const MAX_WEB3SIGNED_LIFETIME_SECONDS: number;
 /**
  * Parse a `"Web3Signed <base64url>.<signature>"` header value.
  *

package/dist/auth/web3-signed.js

@@ -8,6 +8,7 @@ import {
 import { computeBodyHash } from "./web3-signed-builder.js";
 const WEB3_SIGNED_PREFIX = "Web3Signed ";
 const CLOCK_SKEW_SECONDS = 60;
+const MAX_WEB3SIGNED_LIFETIME_SECONDS = 15 * 60;
 function base64urlDecode(input) {
   let base64 = input.replace(/-/g, "+").replace(/_/g, "/");
   const padLength = (4 - base64.length % 4) % 4;
@@ -120,9 +121,18 @@ async function verifyWeb3Signed(params) {
   if (payload.iat > now + CLOCK_SKEW_SECONDS) {
     throw new ExpiredTokenError({ reason: "Token issued in the future" });
   }
+  const lifetime = payload.exp - payload.iat;
+  if (lifetime <= 0 || lifetime > MAX_WEB3SIGNED_LIFETIME_SECONDS) {
+    throw new ExpiredTokenError({
+      reason: "Token lifetime exceeds the maximum",
+      maxLifetimeSeconds: MAX_WEB3SIGNED_LIFETIME_SECONDS,
+      lifetimeSeconds: lifetime
+    });
+  }
   return { signer, payload };
 }
 export {
+  MAX_WEB3SIGNED_LIFETIME_SECONDS,
   parseWeb3SignedHeader,
   verifyWeb3Signed
 };

package/dist/auth/web3-signed.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/auth/web3-signed.ts"],"sourcesContent":["/**\n * Web3Signed Authorization header parsing and verification.\n *\n * @remarks\n * Header format: `\"Web3Signed {base64url(payload)}.{signature}\"`.\n * Payload is JSON with fields `aud`, `method`, `uri`, `bodyHash`, `iat`, `exp`,\n * and optional `grantId`. The signature is EIP-191 over the base64url-encoded\n * payload string.\n *\n * Ported from `personal-server-ts` (`packages/core/src/auth/web3-signed.ts`).\n * Adjusted to be isomorphic (no `Buffer`) and to use SDK-local error types.\n *\n * @category Auth\n */\n\nimport { recoverMessageAddress } from \"viem\";\nimport { fromBase64 } from \"../utils/encoding\";\nimport {\n  MissingAuthError,\n  InvalidSignatureError,\n  ExpiredTokenError,\n} from \"./errors\";\nimport { computeBodyHash } from \"./web3-signed-builder\";\n\nexport interface Web3SignedPayload {\n  aud: string;\n  method: string;\n  uri: string;\n  bodyHash: string;\n  iat: number;\n  exp: number;\n  grantId?: string;\n}\n\nexport interface VerifiedAuth {\n  signer: `0x${string}`;\n  payload: Web3SignedPayload;\n}\n\nconst WEB3_SIGNED_PREFIX = \"Web3Signed \";\nconst CLOCK_SKEW_SECONDS = 60;\n\n/** Decode a base64url string (no padding) to UTF-8. */\nfunction base64urlDecode(input: string): string {\n  let base64 = input.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const padLength = (4 - (base64.length % 4)) % 4;\n  base64 += \"=\".repeat(padLength);\n  return new TextDecoder().decode(fromBase64(base64));\n}\n\nfunction isFiniteNumber(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isFinite(value);\n}\n\nfunction parsePayload(value: unknown): Web3SignedPayload {\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n    throw new InvalidSignatureError({ reason: \"Invalid payload shape\" });\n  }\n\n  const payload = value as Record<string, unknown>;\n  if (\n    typeof payload[\"aud\"] !== \"string\" ||\n    typeof payload[\"method\"] !== \"string\" ||\n    typeof payload[\"uri\"] !== \"string\" ||\n    typeof payload[\"bodyHash\"] !== \"string\" ||\n    !isFiniteNumber(payload[\"iat\"]) ||\n    !isFiniteNumber(payload[\"exp\"])\n  ) {\n    throw new InvalidSignatureError({ reason: \"Invalid payload claims\" });\n  }\n\n  if (\n    payload[\"grantId\"] !== undefined &&\n    typeof payload[\"grantId\"] !== \"string\"\n  ) {\n    throw new InvalidSignatureError({ reason: \"Invalid grantId claim\" });\n  }\n\n  return {\n    aud: payload[\"aud\"],\n    method: payload[\"method\"],\n    uri: payload[\"uri\"],\n    bodyHash: payload[\"bodyHash\"],\n    iat: payload[\"iat\"],\n    exp: payload[\"exp\"],\n    grantId: payload[\"grantId\"],\n  };\n}\n\n/**\n * Parse a `\"Web3Signed <base64url>.<signature>\"` header value.\n *\n * @throws {MissingAuthError} If the header is missing or empty.\n * @throws {InvalidSignatureError} If the format is invalid.\n */\nexport function parseWeb3SignedHeader(headerValue: string | undefined): {\n  payloadBase64: string;\n  payload: Web3SignedPayload;\n  signature: `0x${string}`;\n} {\n  if (!headerValue) {\n    throw new MissingAuthError();\n  }\n\n  if (!headerValue.startsWith(WEB3_SIGNED_PREFIX)) {\n    throw new InvalidSignatureError({ reason: \"Missing Web3Signed prefix\" });\n  }\n\n  const value = headerValue.slice(WEB3_SIGNED_PREFIX.length);\n  const dotIndex = value.indexOf(\".\");\n  if (dotIndex === -1 || dotIndex === 0 || dotIndex === value.length - 1) {\n    throw new InvalidSignatureError({ reason: \"Invalid header format\" });\n  }\n\n  const payloadBase64 = value.slice(0, dotIndex);\n  const signatureStr = value.slice(dotIndex + 1);\n\n  if (!signatureStr.startsWith(\"0x\")) {\n    throw new InvalidSignatureError({ reason: \"Invalid signature format\" });\n  }\n\n  let payload: Web3SignedPayload;\n  try {\n    const decoded = base64urlDecode(payloadBase64);\n    payload = parsePayload(JSON.parse(decoded));\n  } catch (err) {\n    if (err instanceof InvalidSignatureError) throw err;\n    throw new InvalidSignatureError({ reason: \"Invalid payload encoding\" });\n  }\n\n  return {\n    payloadBase64,\n    payload,\n    signature: signatureStr as `0x${string}`,\n  };\n}\n\n/**\n * Full verification: parse header, recover signer via EIP-191, check claims.\n *\n * @remarks\n * Steps:\n * 1. Parse header to base64url + signature.\n * 2. Recover signer via {@link recoverMessageAddress} (EIP-191) over the base64url payload string.\n * 3. Check `aud === expectedOrigin`, `method === expectedMethod`, `uri === expectedPath`.\n * 4. Optionally check `bodyHash` against `bodyBytes`.\n * 5. Check `iat`/`exp` within a 60s clock skew.\n *\n * @returns The recovered signer address and parsed payload.\n */\nexport async function verifyWeb3Signed(params: {\n  headerValue: string | undefined;\n  expectedOrigin: string;\n  expectedMethod: string;\n  expectedPath: string;\n  bodyBytes?: Uint8Array;\n  now?: number;\n}): Promise<VerifiedAuth> {\n  const { payloadBase64, payload, signature } = parseWeb3SignedHeader(\n    params.headerValue,\n  );\n\n  let signer: `0x${string}`;\n  try {\n    signer = await recoverMessageAddress({\n      message: payloadBase64,\n      signature,\n    });\n  } catch {\n    throw new InvalidSignatureError({ reason: \"Signature recovery failed\" });\n  }\n\n  if (payload.aud !== params.expectedOrigin) {\n    throw new InvalidSignatureError({\n      reason: \"Audience mismatch\",\n      expected: params.expectedOrigin,\n      actual: payload.aud,\n    });\n  }\n\n  if (payload.method !== params.expectedMethod) {\n    throw new InvalidSignatureError({\n      reason: \"Method mismatch\",\n      expected: params.expectedMethod,\n      actual: payload.method,\n    });\n  }\n\n  if (payload.uri !== params.expectedPath) {\n    throw new InvalidSignatureError({\n      reason: \"URI mismatch\",\n      expected: params.expectedPath,\n      actual: payload.uri,\n    });\n  }\n\n  if (params.bodyBytes !== undefined) {\n    const expectedBodyHash = computeBodyHash(params.bodyBytes);\n    if (payload.bodyHash !== expectedBodyHash) {\n      throw new InvalidSignatureError({\n        reason: \"Body hash mismatch\",\n        expected: expectedBodyHash,\n        actual: payload.bodyHash,\n      });\n    }\n  }\n\n  const now = params.now ?? Math.floor(Date.now() / 1000);\n\n  if (payload.exp < now - CLOCK_SKEW_SECONDS) {\n    throw new ExpiredTokenError({ reason: \"Token expired\" });\n  }\n\n  if (payload.iat > now + CLOCK_SKEW_SECONDS) {\n    throw new ExpiredTokenError({ reason: \"Token issued in the future\" });\n  }\n\n  return { signer, payload };\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../../src/auth/web3-signed.ts"],"sourcesContent":["/**\n * Web3Signed Authorization header parsing and verification.\n *\n * @remarks\n * Header format: `\"Web3Signed {base64url(payload)}.{signature}\"`.\n * Payload is JSON with fields `aud`, `method`, `uri`, `bodyHash`, `iat`, `exp`,\n * and optional `grantId`. The signature is EIP-191 over the base64url-encoded\n * payload string.\n *\n * Ported from `personal-server-ts` (`packages/core/src/auth/web3-signed.ts`).\n * Adjusted to be isomorphic (no `Buffer`) and to use SDK-local error types.\n *\n * @category Auth\n */\n\nimport { recoverMessageAddress } from \"viem\";\nimport { fromBase64 } from \"../utils/encoding\";\nimport {\n  MissingAuthError,\n  InvalidSignatureError,\n  ExpiredTokenError,\n} from \"./errors\";\nimport { computeBodyHash } from \"./web3-signed-builder\";\n\nexport interface Web3SignedPayload {\n  aud: string;\n  method: string;\n  uri: string;\n  bodyHash: string;\n  iat: number;\n  exp: number;\n  grantId?: string;\n}\n\nexport interface VerifiedAuth {\n  signer: `0x${string}`;\n  payload: Web3SignedPayload;\n}\n\nconst WEB3_SIGNED_PREFIX = \"Web3Signed \";\nconst CLOCK_SKEW_SECONDS = 60;\n\n/**\n * Longest `exp - iat` window a Web3Signed header may carry (seconds). Without\n * this bound the signer chooses how long a captured request stays replayable.\n *\n * @category Auth\n */\nexport const MAX_WEB3SIGNED_LIFETIME_SECONDS = 15 * 60;\n\n/** Decode a base64url string (no padding) to UTF-8. */\nfunction base64urlDecode(input: string): string {\n  let base64 = input.replace(/-/g, \"+\").replace(/_/g, \"/\");\n  const padLength = (4 - (base64.length % 4)) % 4;\n  base64 += \"=\".repeat(padLength);\n  return new TextDecoder().decode(fromBase64(base64));\n}\n\nfunction isFiniteNumber(value: unknown): value is number {\n  return typeof value === \"number\" && Number.isFinite(value);\n}\n\nfunction parsePayload(value: unknown): Web3SignedPayload {\n  if (value === null || typeof value !== \"object\" || Array.isArray(value)) {\n    throw new InvalidSignatureError({ reason: \"Invalid payload shape\" });\n  }\n\n  const payload = value as Record<string, unknown>;\n  if (\n    typeof payload[\"aud\"] !== \"string\" ||\n    typeof payload[\"method\"] !== \"string\" ||\n    typeof payload[\"uri\"] !== \"string\" ||\n    typeof payload[\"bodyHash\"] !== \"string\" ||\n    !isFiniteNumber(payload[\"iat\"]) ||\n    !isFiniteNumber(payload[\"exp\"])\n  ) {\n    throw new InvalidSignatureError({ reason: \"Invalid payload claims\" });\n  }\n\n  if (\n    payload[\"grantId\"] !== undefined &&\n    typeof payload[\"grantId\"] !== \"string\"\n  ) {\n    throw new InvalidSignatureError({ reason: \"Invalid grantId claim\" });\n  }\n\n  return {\n    aud: payload[\"aud\"],\n    method: payload[\"method\"],\n    uri: payload[\"uri\"],\n    bodyHash: payload[\"bodyHash\"],\n    iat: payload[\"iat\"],\n    exp: payload[\"exp\"],\n    grantId: payload[\"grantId\"],\n  };\n}\n\n/**\n * Parse a `\"Web3Signed <base64url>.<signature>\"` header value.\n *\n * @throws {MissingAuthError} If the header is missing or empty.\n * @throws {InvalidSignatureError} If the format is invalid.\n */\nexport function parseWeb3SignedHeader(headerValue: string | undefined): {\n  payloadBase64: string;\n  payload: Web3SignedPayload;\n  signature: `0x${string}`;\n} {\n  if (!headerValue) {\n    throw new MissingAuthError();\n  }\n\n  if (!headerValue.startsWith(WEB3_SIGNED_PREFIX)) {\n    throw new InvalidSignatureError({ reason: \"Missing Web3Signed prefix\" });\n  }\n\n  const value = headerValue.slice(WEB3_SIGNED_PREFIX.length);\n  const dotIndex = value.indexOf(\".\");\n  if (dotIndex === -1 || dotIndex === 0 || dotIndex === value.length - 1) {\n    throw new InvalidSignatureError({ reason: \"Invalid header format\" });\n  }\n\n  const payloadBase64 = value.slice(0, dotIndex);\n  const signatureStr = value.slice(dotIndex + 1);\n\n  if (!signatureStr.startsWith(\"0x\")) {\n    throw new InvalidSignatureError({ reason: \"Invalid signature format\" });\n  }\n\n  let payload: Web3SignedPayload;\n  try {\n    const decoded = base64urlDecode(payloadBase64);\n    payload = parsePayload(JSON.parse(decoded));\n  } catch (err) {\n    if (err instanceof InvalidSignatureError) throw err;\n    throw new InvalidSignatureError({ reason: \"Invalid payload encoding\" });\n  }\n\n  return {\n    payloadBase64,\n    payload,\n    signature: signatureStr as `0x${string}`,\n  };\n}\n\n/**\n * Full verification: parse header, recover signer via EIP-191, check claims.\n *\n * @remarks\n * Steps:\n * 1. Parse header to base64url + signature.\n * 2. Recover signer via {@link recoverMessageAddress} (EIP-191) over the base64url payload string.\n * 3. Check `aud === expectedOrigin`, `method === expectedMethod`, `uri === expectedPath`.\n * 4. Optionally check `bodyHash` against `bodyBytes`.\n * 5. Check `iat`/`exp` within a 60s clock skew.\n *\n * @returns The recovered signer address and parsed payload.\n */\nexport async function verifyWeb3Signed(params: {\n  headerValue: string | undefined;\n  expectedOrigin: string;\n  expectedMethod: string;\n  expectedPath: string;\n  bodyBytes?: Uint8Array;\n  now?: number;\n}): Promise<VerifiedAuth> {\n  const { payloadBase64, payload, signature } = parseWeb3SignedHeader(\n    params.headerValue,\n  );\n\n  let signer: `0x${string}`;\n  try {\n    signer = await recoverMessageAddress({\n      message: payloadBase64,\n      signature,\n    });\n  } catch {\n    throw new InvalidSignatureError({ reason: \"Signature recovery failed\" });\n  }\n\n  if (payload.aud !== params.expectedOrigin) {\n    throw new InvalidSignatureError({\n      reason: \"Audience mismatch\",\n      expected: params.expectedOrigin,\n      actual: payload.aud,\n    });\n  }\n\n  if (payload.method !== params.expectedMethod) {\n    throw new InvalidSignatureError({\n      reason: \"Method mismatch\",\n      expected: params.expectedMethod,\n      actual: payload.method,\n    });\n  }\n\n  if (payload.uri !== params.expectedPath) {\n    throw new InvalidSignatureError({\n      reason: \"URI mismatch\",\n      expected: params.expectedPath,\n      actual: payload.uri,\n    });\n  }\n\n  if (params.bodyBytes !== undefined) {\n    const expectedBodyHash = computeBodyHash(params.bodyBytes);\n    if (payload.bodyHash !== expectedBodyHash) {\n      throw new InvalidSignatureError({\n        reason: \"Body hash mismatch\",\n        expected: expectedBodyHash,\n        actual: payload.bodyHash,\n      });\n    }\n  }\n\n  const now = params.now ?? Math.floor(Date.now() / 1000);\n\n  if (payload.exp < now - CLOCK_SKEW_SECONDS) {\n    throw new ExpiredTokenError({ reason: \"Token expired\" });\n  }\n\n  if (payload.iat > now + CLOCK_SKEW_SECONDS) {\n    throw new ExpiredTokenError({ reason: \"Token issued in the future\" });\n  }\n\n  // Bound the window the signer chose, not just where `now` falls in it:\n  // otherwise a captured request stays replayable for as long as the signer\n  // liked.\n  const lifetime = payload.exp - payload.iat;\n  if (lifetime <= 0 || lifetime > MAX_WEB3SIGNED_LIFETIME_SECONDS) {\n    throw new ExpiredTokenError({\n      reason: \"Token lifetime exceeds the maximum\",\n      maxLifetimeSeconds: MAX_WEB3SIGNED_LIFETIME_SECONDS,\n      lifetimeSeconds: lifetime,\n    });\n  }\n\n  return { signer, payload };\n}\n"],"mappings":"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","names":[]}

package/dist/connect/account-origin.cjs

@@ -0,0 +1,72 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var account_origin_exports = {};
+__export(account_origin_exports, {
+  parseOriginAllowlist: () => parseOriginAllowlist,
+  resolveVanaAccountOrigin: () => resolveVanaAccountOrigin
+});
+module.exports = __toCommonJS(account_origin_exports);
+var import_protocol = require("./protocol");
+const LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+const HOSTNAME = /^(?:\[[0-9a-f:.]+\]|[a-z0-9-]+(?:\.[a-z0-9-]+)*)$/;
+function exactOrigin(value, protocol) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  return url.protocol === protocol && url.origin === value && HOSTNAME.test(url.hostname) ? value : null;
+}
+function parseOriginAllowlist(csv) {
+  if (!csv) return [];
+  const origins = [];
+  for (const entry of csv.split(",")) {
+    const origin = exactOrigin(entry.trim(), "https:");
+    if (origin && !origins.includes(origin)) origins.push(origin);
+  }
+  return origins;
+}
+function resolveVanaAccountOrigin(input) {
+  if (input.env !== "production" && input.env !== "dev") {
+    throw new TypeError('env must be "production" or "dev"');
+  }
+  const fallback = import_protocol.VANA_ACCOUNT_ORIGINS[input.env];
+  const { override } = input;
+  if (input.allowOverride !== true || typeof override !== "string") {
+    return fallback;
+  }
+  const https = exactOrigin(override, "https:");
+  if (https && (input.previewOrigins ?? []).includes(https)) {
+    return https;
+  }
+  if (input.allowLocal === true) {
+    const local = exactOrigin(override, "http:");
+    if (local && LOOPBACK_HOSTS.has(new URL(local).hostname)) {
+      return local;
+    }
+  }
+  return fallback;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  parseOriginAllowlist,
+  resolveVanaAccountOrigin
+});
+//# sourceMappingURL=account-origin.cjs.map

package/dist/connect/account-origin.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/connect/account-origin.ts"],"sourcesContent":["/**\n * Which Vana Account origin serves the connect sheet.\n *\n * @remarks\n * The sheet origin decides who the person signs in to and who receives the\n * partner's request capability, so it must never come from a pattern the\n * page URL can satisfy. {@link resolveVanaAccountOrigin} returns the\n * environment's Vana Account origin and accepts an override only when the\n * caller switched overrides on and the override is an exact origin from an\n * explicit allowlist. There is deliberately no pattern or wildcard option.\n *\n * Zero-dependency and browser-safe, like the protocol it builds on.\n *\n * @category Connect\n * @module connect/account-origin\n */\n\nimport { VANA_ACCOUNT_ORIGINS, type VanaConnectEnv } from \"./protocol\";\n\n/** Input for {@link resolveVanaAccountOrigin}. */\nexport interface ResolveVanaAccountOriginInput {\n  /** The deployment environment the app talks to. Required: there is no default. */\n  env: VanaConnectEnv;\n  /**\n   * A requested Account origin, typically read from a query parameter on a\n   * preview deploy. Untrusted. Ignored unless {@link allowOverride} is true.\n   */\n  override?: string | null;\n  /**\n   * Exact `https` origins (`https://host[:port]`, no path, no trailing slash)\n   * an override may name. Build it with {@link parseOriginAllowlist}. Entries\n   * that are not exact https origins never match.\n   */\n  previewOrigins?: readonly string[];\n  /**\n   * Whether this build honours an override at all. Decide it from build-time\n   * configuration (a non-production deploy), never from the request. Keep it\n   * `false` in production.\n   */\n  allowOverride: boolean;\n  /**\n   * Also accept an exact `http` loopback origin (`localhost`, `127.0.0.1`,\n   * `[::1]`, any port) without listing it, for a locally run Vana Account.\n   * Only applies when {@link allowOverride} is true. Defaults to `false`.\n   */\n  allowLocal?: boolean;\n}\n\nconst LOOPBACK_HOSTS = new Set([\"localhost\", \"127.0.0.1\", \"[::1]\"]);\n/** DNS labels (punycode included) or a bracketed IPv6 literal; no wildcards. */\nconst HOSTNAME = /^(?:\\[[0-9a-f:.]+\\]|[a-z0-9-]+(?:\\.[a-z0-9-]+)*)$/;\n\n/** `value` itself when it is a bare origin with `protocol`, else `null`. */\nfunction exactOrigin(\n  value: string,\n  protocol: \"https:\" | \"http:\",\n): string | null {\n  let url: URL;\n  try {\n    url = new URL(value);\n  } catch {\n    return null;\n  }\n  // `url.origin === value` rejects paths, queries, fragments, credentials,\n  // trailing slashes and any spelling the URL parser would rewrite.\n  return url.protocol === protocol &&\n    url.origin === value &&\n    HOSTNAME.test(url.hostname)\n    ? value\n    : null;\n}\n\n/**\n * Parse a comma-separated allowlist of exact `https` origins.\n *\n * @remarks\n * Whitespace around entries is trimmed. An entry that is not an exact\n * `https://host[:port]` origin (a path, a trailing slash, `http:`, a\n * wildcard such as `https://*.vercel.app`) is dropped, so a typo narrows\n * the list instead of widening it.\n *\n * @example\n * ```typescript\n * parseOriginAllowlist(process.env.VANA_ACCOUNT_PREVIEW_ORIGINS);\n * // [\"https://account-git-my-branch.vercel.app\"]\n * ```\n *\n * @param csv - The raw list, for example an environment variable.\n * @returns The exact https origins, deduplicated, in order.\n */\nexport function parseOriginAllowlist(csv: string | null | undefined): string[] {\n  if (!csv) return [];\n  const origins: string[] = [];\n  for (const entry of csv.split(\",\")) {\n    const origin = exactOrigin(entry.trim(), \"https:\");\n    if (origin && !origins.includes(origin)) origins.push(origin);\n  }\n  return origins;\n}\n\n/**\n * Resolve the Vana Account origin that serves the connect sheet.\n *\n * @remarks\n * Returns `VANA_ACCOUNT_ORIGINS[env]` unless `allowOverride` is true and\n * `override` is exactly one of `previewOrigins` (an `https` origin), or,\n * with `allowLocal`, exactly an `http` loopback origin. Anything else (a\n * path, a different scheme, a near-miss host, a lookalike) falls back to the\n * environment's origin. Matching is exact string equality: no patterns, no\n * suffixes, no normalization that could widen a match.\n *\n * @example\n * ```typescript\n * const accountOrigin = resolveVanaAccountOrigin({\n *   env: \"dev\",\n *   override: new URLSearchParams(location.search).get(\"vana_account\"),\n *   previewOrigins: parseOriginAllowlist(\n *     process.env.NEXT_PUBLIC_VANA_ACCOUNT_PREVIEW_ORIGINS,\n *   ),\n *   allowOverride: process.env.NEXT_PUBLIC_DEPLOY_ENV === \"preview\",\n * });\n * ```\n *\n * @param input - Environment, untrusted override, allowlist and switches.\n * @returns A bare Vana Account origin.\n * @throws TypeError when `env` is not `\"production\"` or `\"dev\"`.\n */\nexport function resolveVanaAccountOrigin(\n  input: ResolveVanaAccountOriginInput,\n): string {\n  if (input.env !== \"production\" && input.env !== \"dev\") {\n    throw new TypeError('env must be \"production\" or \"dev\"');\n  }\n  const fallback: string = VANA_ACCOUNT_ORIGINS[input.env];\n  const { override } = input;\n  if (input.allowOverride !== true || typeof override !== \"string\") {\n    return fallback;\n  }\n  const https = exactOrigin(override, \"https:\");\n  if (https && (input.previewOrigins ?? []).includes(https)) {\n    return https;\n  }\n  if (input.allowLocal === true) {\n    const local = exactOrigin(override, \"http:\");\n    if (local && LOOPBACK_HOSTS.has(new URL(local).hostname)) {\n      return local;\n    }\n  }\n  return fallback;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBA,sBAA0D;AA+B1D,MAAM,iBAAiB,oBAAI,IAAI,CAAC,aAAa,aAAa,OAAO,CAAC;AAElE,MAAM,WAAW;AAGjB,SAAS,YACP,OACA,UACe;AACf,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,IAAI,KAAK;AAAA,EACrB,QAAQ;AACN,WAAO;AAAA,EACT;AAGA,SAAO,IAAI,aAAa,YACtB,IAAI,WAAW,SACf,SAAS,KAAK,IAAI,QAAQ,IACxB,QACA;AACN;AAoBO,SAAS,qBAAqB,KAA0C;AAC7E,MAAI,CAAC,IAAK,QAAO,CAAC;AAClB,QAAM,UAAoB,CAAC;AAC3B,aAAW,SAAS,IAAI,MAAM,GAAG,GAAG;AAClC,UAAM,SAAS,YAAY,MAAM,KAAK,GAAG,QAAQ;AACjD,QAAI,UAAU,CAAC,QAAQ,SAAS,MAAM,EAAG,SAAQ,KAAK,MAAM;AAAA,EAC9D;AACA,SAAO;AACT;AA6BO,SAAS,yBACd,OACQ;AACR,MAAI,MAAM,QAAQ,gBAAgB,MAAM,QAAQ,OAAO;AACrD,UAAM,IAAI,UAAU,mCAAmC;AAAA,EACzD;AACA,QAAM,WAAmB,qCAAqB,MAAM,GAAG;AACvD,QAAM,EAAE,SAAS,IAAI;AACrB,MAAI,MAAM,kBAAkB,QAAQ,OAAO,aAAa,UAAU;AAChE,WAAO;AAAA,EACT;AACA,QAAM,QAAQ,YAAY,UAAU,QAAQ;AAC5C,MAAI,UAAU,MAAM,kBAAkB,CAAC,GAAG,SAAS,KAAK,GAAG;AACzD,WAAO;AAAA,EACT;AACA,MAAI,MAAM,eAAe,MAAM;AAC7B,UAAM,QAAQ,YAAY,UAAU,OAAO;AAC3C,QAAI,SAAS,eAAe,IAAI,IAAI,IAAI,KAAK,EAAE,QAAQ,GAAG;AACxD,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/connect/account-origin.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Which Vana Account origin serves the connect sheet.
+ *
+ * @remarks
+ * The sheet origin decides who the person signs in to and who receives the
+ * partner's request capability, so it must never come from a pattern the
+ * page URL can satisfy. {@link resolveVanaAccountOrigin} returns the
+ * environment's Vana Account origin and accepts an override only when the
+ * caller switched overrides on and the override is an exact origin from an
+ * explicit allowlist. There is deliberately no pattern or wildcard option.
+ *
+ * Zero-dependency and browser-safe, like the protocol it builds on.
+ *
+ * @category Connect
+ * @module connect/account-origin
+ */
+import { type VanaConnectEnv } from "./protocol.js";
+/** Input for {@link resolveVanaAccountOrigin}. */
+export interface ResolveVanaAccountOriginInput {
+    /** The deployment environment the app talks to. Required: there is no default. */
+    env: VanaConnectEnv;
+    /**
+     * A requested Account origin, typically read from a query parameter on a
+     * preview deploy. Untrusted. Ignored unless {@link allowOverride} is true.
+     */
+    override?: string | null;
+    /**
+     * Exact `https` origins (`https://host[:port]`, no path, no trailing slash)
+     * an override may name. Build it with {@link parseOriginAllowlist}. Entries
+     * that are not exact https origins never match.
+     */
+    previewOrigins?: readonly string[];
+    /**
+     * Whether this build honours an override at all. Decide it from build-time
+     * configuration (a non-production deploy), never from the request. Keep it
+     * `false` in production.
+     */
+    allowOverride: boolean;
+    /**
+     * Also accept an exact `http` loopback origin (`localhost`, `127.0.0.1`,
+     * `[::1]`, any port) without listing it, for a locally run Vana Account.
+     * Only applies when {@link allowOverride} is true. Defaults to `false`.
+     */
+    allowLocal?: boolean;
+}
+/**
+ * Parse a comma-separated allowlist of exact `https` origins.
+ *
+ * @remarks
+ * Whitespace around entries is trimmed. An entry that is not an exact
+ * `https://host[:port]` origin (a path, a trailing slash, `http:`, a
+ * wildcard such as `https://*.vercel.app`) is dropped, so a typo narrows
+ * the list instead of widening it.
+ *
+ * @example
+ * ```typescript
+ * parseOriginAllowlist(process.env.VANA_ACCOUNT_PREVIEW_ORIGINS);
+ * // ["https://account-git-my-branch.vercel.app"]
+ * ```
+ *
+ * @param csv - The raw list, for example an environment variable.
+ * @returns The exact https origins, deduplicated, in order.
+ */
+export declare function parseOriginAllowlist(csv: string | null | undefined): string[];
+/**
+ * Resolve the Vana Account origin that serves the connect sheet.
+ *
+ * @remarks
+ * Returns `VANA_ACCOUNT_ORIGINS[env]` unless `allowOverride` is true and
+ * `override` is exactly one of `previewOrigins` (an `https` origin), or,
+ * with `allowLocal`, exactly an `http` loopback origin. Anything else (a
+ * path, a different scheme, a near-miss host, a lookalike) falls back to the
+ * environment's origin. Matching is exact string equality: no patterns, no
+ * suffixes, no normalization that could widen a match.
+ *
+ * @example
+ * ```typescript
+ * const accountOrigin = resolveVanaAccountOrigin({
+ *   env: "dev",
+ *   override: new URLSearchParams(location.search).get("vana_account"),
+ *   previewOrigins: parseOriginAllowlist(
+ *     process.env.NEXT_PUBLIC_VANA_ACCOUNT_PREVIEW_ORIGINS,
+ *   ),
+ *   allowOverride: process.env.NEXT_PUBLIC_DEPLOY_ENV === "preview",
+ * });
+ * ```
+ *
+ * @param input - Environment, untrusted override, allowlist and switches.
+ * @returns A bare Vana Account origin.
+ * @throws TypeError when `env` is not `"production"` or `"dev"`.
+ */
+export declare function resolveVanaAccountOrigin(input: ResolveVanaAccountOriginInput): string;