@opendatalabs/vana-sdk 4.3.2 → 4.4.0-connect-sheet.0-pr.218.7f5d342

package/README.md

@@ -261,6 +261,49 @@ accepts write entries in `scopes`, but its scope part must be a concrete
 scope: this flow reads approved scopes back one at a time, so wildcards are
 rejected there for read and write alike.
 
+### PDPP grants
+
+Ask for PDPP data as **grants**: a registry `source_id` and the streams you
+want from it. The controller turns each stream into one scope key,
+`pdpp.<source>.<stream>`, and that key is what the request, the signed grant
+and your reads carry.
+
+```typescript
+export const vana = createDirectDataController({
+  // ...
+  source: "chatgpt",
+  grants: [
+    {
+      source_id: "https://registry.pdpp.dev/sources/chatgpt",
+      streams: ["conversations", "messages"],
+    },
+  ],
+});
+// Requests ["pdpp.chatgpt.conversations", "pdpp.chatgpt.messages"].
+
+await vana.readApprovedData({ requestId, scope: "pdpp.chatgpt.messages" });
+```
+
+- `grants` and `scopes` can be combined. The request is the union: your
+  `scopes` verbatim, then the derived keys that are not already in it.
+  Existing apps that pass only `scopes` are unchanged.
+- The `pdpp.` namespace is separate from legacy scopes. PDPP's ChatGPT
+  `conversations` stream is `pdpp.chatgpt.conversations`, not the legacy
+  `chatgpt.conversations`, and `pdpp.chatgpt.*` covers only PDPP streams.
+  A legacy `scopes` entry under `pdpp.` that is not a valid key is rejected.
+- The mapping is strict and never slugifies. `source_id` must be
+  `https://registry.pdpp.dev/sources/<source>`, and `<source>` and each stream
+  must be lowercase letters, digits and underscores, not starting with an
+  underscore. Anything else throws `InvalidPdppGrantError` when the controller
+  is created.
+- `pdppScopeKey(source_id, stream)`, `parsePdppScopeKey(key)` (`{ source_id,
+stream }` or `null`), `isPdppScopeKey(key)`, `pdppGrantsToScopes(grants)`
+  and `grantRequestScopes({ grants, scopes })` are exported from `/server`,
+  the root entry points and `@opendatalabs/vana-sdk/protocol/scopes`. Use them
+  rather than building keys by hand. Other implementations can check
+  themselves against the vectors in
+  [`src/protocol/fixtures/pdpp-scope-keys.json`](src/protocol/fixtures/pdpp-scope-keys.json).
+
 ### Backend controller
 
 ```typescript
@@ -457,10 +500,143 @@ 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. The controller decides
+what is requested (its `grants` and `scopes`, see [PDPP grants](#pdpp-grants));
+the browser never chooses.
+
+```ts
+// app/api/vana/[action]/route.ts
+import { createVanaConnectHandler } from "@opendatalabs/vana-sdk/server";
+import { vana } from "@/lib/vana"; // your createDirectDataController({ grants, ... })
+
+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
-[`vana-com/data-connectors`](https://github.com/vana-com/data-connectors). Keep
+[`PDP-Connect/data-connectors`](https://github.com/PDP-Connect/data-connectors). Keep
 the payload in a file or raw URL and point your app or agent at that location.
 Do not paste large JSON into the terminal.
 
@@ -471,7 +647,7 @@ still calls `readApprovedData`.
 
 See [`examples/vana-app`](../../examples/vana-app) for a runnable Next.js Vana
 app. It includes the route handlers, return page, and React connect button from
-this flow, defaults to sample-data mode using `vana-com/data-connectors`, and
+this flow, defaults to sample-data mode using `PDP-Connect/data-connectors`, and
 can be switched to live protocol mode with environment variables.
 
 ## Write into a Personal Server

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;

package/dist/connect/account-origin.js

@@ -0,0 +1,47 @@
+import { VANA_ACCOUNT_ORIGINS } from "./protocol.js";
+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 = 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;
+}
+export {
+  parseOriginAllowlist,
+  resolveVanaAccountOrigin
+};
+//# sourceMappingURL=account-origin.js.map

package/dist/connect/account-origin.js.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":"AAiBA,SAAS,4BAAiD;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,qBAAqB,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.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/connect/chrome.cjs

@@ -0,0 +1,221 @@
+"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 chrome_exports = {};
+__export(chrome_exports, {
+  DRAG_CLOSE_PX: () => DRAG_CLOSE_PX,
+  MAX_SHEET_RATIO: () => MAX_SHEET_RATIO,
+  RETURN_TAP_GUARD_MS: () => RETURN_TAP_GUARD_MS,
+  createSheetChrome: () => createSheetChrome,
+  sheetTopPx: () => sheetTopPx
+});
+module.exports = __toCommonJS(chrome_exports);
+const SHEET_RADIUS_PX = 28;
+const SHEET_MAX_WIDTH_PX = 480;
+const HANDLE_STRIP_PX = 20;
+const INITIAL_CONTENT_PX = 320;
+const TRANSITION_MS = 280;
+const SHEET_BACKGROUND = "#f4f4f4";
+const DRAG_CLOSE_PX = 120;
+const MAX_SHEET_RATIO = 0.92;
+const STYLES = `
+:host { all: initial; }
+.scrim {
+  position: fixed; inset: 0; z-index: 2147483646;
+  background: rgb(0 0 0 / 0.4);
+  opacity: 0; transition: opacity ${TRANSITION_MS}ms ease;
+}
+.sheet {
+  position: fixed; left: 0; right: 0; z-index: 2147483647;
+  margin: 0 auto; max-width: ${SHEET_MAX_WIDTH_PX}px;
+  top: 100vh;
+  transition: top ${TRANSITION_MS}ms cubic-bezier(0.32, 0.72, 0, 1);
+}
+.sheet.dragging { transition: none; }
+.handle {
+  height: ${HANDLE_STRIP_PX}px;
+  display: flex; justify-content: center; align-items: center;
+  background: ${SHEET_BACKGROUND};
+  border-radius: ${SHEET_RADIUS_PX}px ${SHEET_RADIUS_PX}px 0 0;
+  touch-action: none; cursor: grab;
+}
+.handle::before {
+  content: ""; width: 36px; height: 5px; border-radius: 3px;
+  background: rgb(0 0 0 / 0.18);
+}
+iframe {
+  display: block; width: 100%; border: 0;
+  background: ${SHEET_BACKGROUND};
+}
+.open .scrim { opacity: 1; }
+@media (prefers-reduced-motion: reduce) {
+  .scrim, .sheet { transition: none; }
+}
+`;
+function viewportPx() {
+  return window.visualViewport?.height ?? window.innerHeight;
+}
+function capPx() {
+  return Math.round(viewportPx() * MAX_SHEET_RATIO);
+}
+function placeSheet(sheet, content) {
+  sheet.style.top = `${sheetTopPx(viewportPx(), content)}px`;
+}
+function sheetTopPx(viewport, content) {
+  const cap = Math.round(viewport * MAX_SHEET_RATIO);
+  const visible = Math.min(content, cap - HANDLE_STRIP_PX);
+  return Math.round(viewport - HANDLE_STRIP_PX - visible);
+}
+const RETURN_TAP_GUARD_MS = 500;
+function installReturnGuard(sheet, iframe, state) {
+  const fitIframe = () => {
+    iframe.style.height = `${capPx() - HANDLE_STRIP_PX}px`;
+    if (state.shown) {
+      placeSheet(sheet, state.lastHeight ?? INITIAL_CONTENT_PX);
+    }
+  };
+  const onReturn = () => {
+    if (document.visibilityState !== "visible") {
+      return;
+    }
+    state.returnedAt = performance.now();
+    fitIframe();
+  };
+  fitIframe();
+  window.addEventListener("resize", fitIframe);
+  window.visualViewport?.addEventListener("resize", fitIframe);
+  document.addEventListener("visibilitychange", onReturn);
+  window.addEventListener("focus", onReturn);
+  return () => {
+    window.removeEventListener("resize", fitIframe);
+    window.visualViewport?.removeEventListener("resize", fitIframe);
+    document.removeEventListener("visibilitychange", onReturn);
+    window.removeEventListener("focus", onReturn);
+    sheet.style.transform = "";
+  };
+}
+function installDragToClose(sheet, handle, onClose) {
+  let startY = null;
+  handle.addEventListener("pointerdown", (event) => {
+    startY = event.clientY;
+    handle.setPointerCapture?.(event.pointerId);
+    sheet.classList.add("dragging");
+  });
+  handle.addEventListener("pointermove", (event) => {
+    if (startY === null) {
+      return;
+    }
+    const dy = Math.max(0, event.clientY - startY);
+    sheet.style.transform = `translateY(${dy}px)`;
+  });
+  const end = (event) => {
+    if (startY === null) {
+      return;
+    }
+    const dy = event.clientY - startY;
+    startY = null;
+    sheet.classList.remove("dragging");
+    sheet.style.transform = "";
+    if (dy > DRAG_CLOSE_PX) {
+      onClose("drag");
+    }
+  };
+  handle.addEventListener("pointerup", end);
+  handle.addEventListener("pointercancel", end);
+}
+function createSheetChrome(input) {
+  const returnState = {
+    lastHeight: null,
+    returnedAt: 0,
+    shown: false
+  };
+  const host = document.createElement("div");
+  host.setAttribute("data-vana-connect", "");
+  const root = host.attachShadow({ mode: "open" });
+  const style = document.createElement("style");
+  style.textContent = STYLES;
+  const frame = document.createElement("div");
+  const scrim = document.createElement("div");
+  scrim.className = "scrim";
+  scrim.setAttribute("data-slot", "scrim");
+  scrim.addEventListener("click", () => {
+    if (performance.now() - returnState.returnedAt < RETURN_TAP_GUARD_MS) {
+      return;
+    }
+    input.onClose("scrim");
+  });
+  const sheet = document.createElement("div");
+  sheet.className = "sheet";
+  sheet.setAttribute("role", "dialog");
+  sheet.setAttribute("aria-modal", "true");
+  sheet.setAttribute("aria-label", input.ariaLabel);
+  const iframe = document.createElement("iframe");
+  iframe.setAttribute(
+    "sandbox",
+    "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
+  );
+  iframe.setAttribute(
+    "allow",
+    "otp-credentials; publickey-credentials-get; clipboard-write"
+  );
+  iframe.setAttribute("title", "Vana");
+  iframe.referrerPolicy = "strict-origin-when-cross-origin";
+  iframe.src = input.src;
+  const handle = document.createElement("div");
+  handle.className = "handle";
+  handle.setAttribute("aria-hidden", "true");
+  sheet.append(handle, iframe);
+  frame.append(scrim, sheet);
+  root.append(style, frame);
+  input.container.append(host);
+  const removeReturnGuard = installReturnGuard(sheet, iframe, returnState);
+  installDragToClose(sheet, handle, input.onClose);
+  return {
+    host,
+    iframe,
+    remove() {
+      removeReturnGuard();
+      host.remove();
+    },
+    setContentHeight(px) {
+      if (document.visibilityState !== "visible") {
+        return;
+      }
+      returnState.lastHeight = px;
+      if (returnState.shown) {
+        placeSheet(sheet, px);
+      }
+    },
+    show() {
+      requestAnimationFrame(() => {
+        returnState.shown = true;
+        frame.classList.add("open");
+        placeSheet(sheet, returnState.lastHeight ?? INITIAL_CONTENT_PX);
+      });
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DRAG_CLOSE_PX,
+  MAX_SHEET_RATIO,
+  RETURN_TAP_GUARD_MS,
+  createSheetChrome,
+  sheetTopPx
+});
+//# sourceMappingURL=chrome.cjs.map