@recursiv/sdk 0.7.121 → 0.7.122

package/dist/sealed-frame/protocol.js

@@ -0,0 +1,276 @@
+/**
+ * The Sealed frame's protocol, version 1: the messages between a host page (minds.com/ai, build.minds.com) and the
+ * Sealed frame it embeds (https://sealed.minds.com), and between a host and the frame's sign-out page (/wipe.html).
+ * Both sides use these types, builders and validators, so there is one definition of what may cross.
+ *
+ * How the two talk (the Sealed frame design of 2026-10-13, section 5):
+ * 1. On every load event of the frame's iframe, the host posts `sealed/hello` with a transferred MessagePort to the
+ *    frame origin only (`targetOrigin`). The frame must add its window message listener as soon as its module runs, and
+ *    accepts the first hello whose `event.origin` is one of its compiled hosts and whose `event.source` is
+ *    `window.parent`. After that both sides use the port only.
+ * 2. The frame answers `ready` on the port, naming the protocol it speaks; a host that speaks another shows "Reload
+ *    the page". Nothing else counts before `ready`.
+ * 3. Host to frame, on the port: `token`, `theme`, `layout`, `account`, `signed-out`, `new-chat`.
+ *    Frame to host, on the port: `need-token`, `state`, `navigate`, `wiped`.
+ *
+ * Every field is an enum, a boolean, an id, a time or the opaque token. Never sent, either way: typed words, answers,
+ * chat ids, titles or counts, failure details, or when sends happen. There are no size messages: the host sizes the
+ * frame with CSS, since a height would say how long the transcript is.
+ *
+ * Every message is checked before it is read. A validator returns a fresh copy holding only the message's own fields,
+ * or null for anything else: a type it does not know, a missing, extra or wrongly typed field, a string outside its
+ * enum or pattern, a getter or symbol key, or a message over 4 KB of JSON. The receiver ignores null. Builders check
+ * their own output the same way and throw a TypeError rather than send a message the other side would drop.
+ */
+/** The protocol this SDK speaks, which `ready` names. */
+export const SEALED_FRAME_PROTOCOL = 1;
+/** Every message's format version (`v`). */
+export const SEALED_FRAME_MESSAGE_VERSION = 1;
+/** The most a message may be, as UTF-8 JSON. Anything larger is dropped unread. */
+export const SEALED_FRAME_MESSAGE_MAX_BYTES = 4096;
+/**
+ * The frame's iframe sandbox. It protects the host, not the frame: the frame's protection is the same-origin policy and
+ * its own CSP. `allow-same-origin` keeps the frame's own storage; popups let crisis and help links open in a new tab.
+ * There is no `allow-forms`, in line with the frame CSP's `form-action 'none'`: embedded, the browser stops a form
+ * submission before its `submit` event fires, so the frame must not use `<form>` submission (handle Enter and the send
+ * button with key and click handlers). Standalone at its own origin a form would work, which is why tests miss it.
+ */
+export const SEALED_FRAME_SANDBOX = 'allow-scripts allow-same-origin allow-popups allow-popups-to-escape-sandbox';
+/** The sign-out page's sandbox: it runs a script against the frame origin's storage and opens nothing. */
+export const SEALED_WIPE_SANDBOX = 'allow-scripts allow-same-origin';
+/** The frame's permissions policy: only writing to the clipboard (copy an answer). */
+export const SEALED_FRAME_ALLOW = 'clipboard-write';
+/** No referrer leaves the host for the frame. */
+export const SEALED_FRAME_REFERRER_POLICY = 'no-referrer';
+/** The frame's sign-out page, on the frame origin. */
+export const SEALED_WIPE_PATH = '/wipe.html';
+/** Which host embeds the frame. */
+export const SEALED_FRAME_HOST_KINDS = ['minds', 'build'];
+export const SEALED_FRAME_SCHEMES = ['light', 'dark'];
+/** `column`: a phone-width column. `workspace`: the desktop thread area, where the frame lists its own Sealed chats. */
+export const SEALED_FRAME_LAYOUTS = ['column', 'workspace'];
+/** Why the frame cannot run Sealed now (`state`, `unavailable`). */
+export const SEALED_FRAME_UNAVAILABLE_REASONS = [
+    'unsupported',
+    'tab_busy',
+    'off',
+    'words',
+    'signed_out',
+    'update',
+    'no_account',
+];
+/** Where the frame asks the host to take the member (`navigate`). */
+export const SEALED_FRAME_NAVIGATE_TARGETS = ['plans', 'settings_ai', 'sign_in', 'get_app'];
+/** A member's user id (a UUID today): letters, digits, `-` and `_`, 1 to 64 of them. */
+const ACCOUNT = /^[A-Za-z0-9_-]{1,64}$/;
+/** A frame token: `sft_` + base64url payload + `.` + base64url MAC, the API's format. */
+const FRAME_TOKEN = /^sft_[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+const FRAME_TOKEN_MAX_LENGTH = 2048;
+/** A frame release id: the release's name or source commit. */
+const RELEASE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+function oneOf(values) {
+    return (value) => typeof value === 'string' && values.includes(value);
+}
+const isVersion = (value) => value === SEALED_FRAME_MESSAGE_VERSION;
+const isBoolean = (value) => typeof value === 'boolean';
+const isAccount = (value) => typeof value === 'string' && ACCOUNT.test(value);
+const isAccountOrNull = (value) => value === null || isAccount(value);
+const isRelease = (value) => typeof value === 'string' && RELEASE.test(value);
+const isProtocol = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value >= 1 && value <= 65535;
+const isTime = (value) => typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
+/** Whether a value is a frame token in the API's format. */
+export function isSealedFrameToken(value) {
+    return typeof value === 'string' && value.length <= FRAME_TOKEN_MAX_LENGTH && FRAME_TOKEN.test(value);
+}
+const field = (rule) => ({ rule });
+const optional = (rule) => ({ rule, optional: true });
+const HELLO_SHAPES = {
+    'sealed/hello': {
+        v: field(isVersion),
+        host: field(oneOf(SEALED_FRAME_HOST_KINDS)),
+        scheme: field(oneOf(SEALED_FRAME_SCHEMES)),
+        layout: field(oneOf(SEALED_FRAME_LAYOUTS)),
+        signedIn: field(isBoolean),
+        account: field(isAccountOrNull),
+    },
+};
+const HOST_SHAPES = {
+    token: { v: field(isVersion), token: field(isSealedFrameToken), expiresAt: field(isTime), account: field(isAccount) },
+    theme: { v: field(isVersion), scheme: field(oneOf(SEALED_FRAME_SCHEMES)) },
+    layout: { v: field(isVersion), layout: field(oneOf(SEALED_FRAME_LAYOUTS)) },
+    account: { v: field(isVersion), account: field(isAccount) },
+    'signed-out': { v: field(isVersion) },
+    'new-chat': { v: field(isVersion) },
+};
+const FRAME_SHAPES = {
+    ready: { v: field(isVersion), protocol: field(isProtocol), release: field(isRelease) },
+    'need-token': { v: field(isVersion) },
+    state: {
+        v: field(isVersion),
+        state: field(oneOf(['ready', 'unavailable'])),
+        reason: optional(oneOf(SEALED_FRAME_UNAVAILABLE_REASONS)),
+    },
+    navigate: { v: field(isVersion), to: field(oneOf(SEALED_FRAME_NAVIGATE_TARGETS)) },
+    wiped: { v: field(isVersion) },
+};
+const WIPE_SHAPES = {
+    'sealed/wipe': { v: field(isVersion), account: field(isAccountOrNull) },
+};
+/** More keys than any message has. */
+const MAX_KEYS = 8;
+const hasOwn = (object, key) => Object.hasOwn(object, key);
+function utf8Length(text) {
+    return new TextEncoder().encode(text).length;
+}
+/**
+ * The message `data` is, checked against `shapes`, as a fresh object with only its own fields; null for anything else.
+ * Never throws.
+ */
+function readShape(data, shapes) {
+    try {
+        // A plain object (from any realm: structured clone makes one in the receiver's), not an array or a class instance.
+        if (typeof data !== 'object' || data === null || Array.isArray(data))
+            return null;
+        if (Object.prototype.toString.call(data) !== '[object Object]')
+            return null;
+        const proto = Object.getPrototypeOf(data);
+        if (proto !== null && Object.getPrototypeOf(proto) !== null)
+            return null;
+        const keys = Reflect.ownKeys(data);
+        if (keys.length > MAX_KEYS)
+            return null;
+        // No prototype: an own `__proto__` key (JSON.parse and structured clone keep one) is then copied as a plain key and
+        // refused below as an extra field, instead of reaching Object.prototype's `__proto__` setter and vanishing.
+        const values = Object.create(null);
+        for (const key of keys) {
+            if (typeof key !== 'string')
+                return null;
+            const descriptor = Object.getOwnPropertyDescriptor(data, key);
+            // Data properties only: a getter could answer differently on each read.
+            if (!descriptor || !('value' in descriptor) || !descriptor.enumerable)
+                return null;
+            const value = descriptor.value;
+            if (value !== null && typeof value !== 'string' && typeof value !== 'number' && typeof value !== 'boolean')
+                return null;
+            if (typeof value === 'string' && value.length > SEALED_FRAME_MESSAGE_MAX_BYTES)
+                return null;
+            values[key] = value;
+        }
+        if (utf8Length(JSON.stringify(values)) > SEALED_FRAME_MESSAGE_MAX_BYTES)
+            return null;
+        const type = values.t;
+        if (typeof type !== 'string' || !hasOwn(shapes, type))
+            return null;
+        const shape = shapes[type];
+        for (const key of Object.keys(values)) {
+            if (key !== 't' && !hasOwn(shape, key))
+                return null;
+        }
+        const message = { t: type };
+        for (const [key, { rule, optional: isOptional }] of Object.entries(shape)) {
+            if (!hasOwn(values, key)) {
+                if (isOptional)
+                    continue;
+                return null;
+            }
+            if (!rule(values[key]))
+                return null;
+            message[key] = values[key];
+        }
+        return message;
+    }
+    catch {
+        return null;
+    }
+}
+/** A `sealed/hello`, as the frame reads it; null for anything else. */
+export function parseSealedFrameHello(data) {
+    const message = readShape(data, HELLO_SHAPES);
+    if (!message)
+        return null;
+    // Signed in exactly when an account is named.
+    if ((message.signedIn === true) !== (message.account !== null))
+        return null;
+    return message;
+}
+/** A host-to-frame port message, as the frame reads it; null for anything else. */
+export function parseSealedHostMessage(data) {
+    return readShape(data, HOST_SHAPES);
+}
+/** A frame-to-host port message, as the host reads it; null for anything else. */
+export function parseSealedFrameMessage(data) {
+    const message = readShape(data, FRAME_SHAPES);
+    if (!message)
+        return null;
+    // A reason exactly when unavailable.
+    if (message.t === 'state' && (message.state === 'unavailable') !== hasOwn(message, 'reason'))
+        return null;
+    return message;
+}
+/** A `sealed/wipe`, as the sign-out page reads it; null for anything else. */
+export function parseSealedWipeRequest(data) {
+    return readShape(data, WIPE_SHAPES);
+}
+// --- builders ------------------------------------------------------------------------------------------------------
+function checked(message, what) {
+    if (message === null)
+        throw new TypeError(`Not a valid Sealed frame ${what} message. Nothing was sent.`);
+    return message;
+}
+/** The host's `sealed/hello`. `account` is the signed-in member's user id, or null when no one is signed in. */
+export function sealedFrameHello(input) {
+    const hello = {
+        t: 'sealed/hello',
+        v: 1,
+        host: input.host,
+        scheme: input.scheme,
+        layout: input.layout,
+        signedIn: input.account !== null,
+        account: input.account,
+    };
+    return checked(parseSealedFrameHello(hello), 'hello');
+}
+/** The host's port messages. */
+export const sealedHostMessage = {
+    token: (token, expiresAt, account) => checked(parseSealedHostMessage({ t: 'token', v: 1, token, expiresAt, account }), 'token'),
+    theme: (scheme) => checked(parseSealedHostMessage({ t: 'theme', v: 1, scheme }), 'theme'),
+    layout: (layout) => checked(parseSealedHostMessage({ t: 'layout', v: 1, layout }), 'layout'),
+    account: (account) => checked(parseSealedHostMessage({ t: 'account', v: 1, account }), 'account'),
+    signedOut: () => checked(parseSealedHostMessage({ t: 'signed-out', v: 1 }), 'signed-out'),
+    newChat: () => checked(parseSealedHostMessage({ t: 'new-chat', v: 1 }), 'new-chat'),
+};
+/**
+ * The frame's port messages. Each takes only enums, numbers and the frame's compiled release id, so nothing the member
+ * typed or read can be put in one.
+ */
+export const sealedFrameMessage = {
+    ready: (release) => checked(parseSealedFrameMessage({ t: 'ready', v: 1, protocol: SEALED_FRAME_PROTOCOL, release }), 'ready'),
+    needToken: () => checked(parseSealedFrameMessage({ t: 'need-token', v: 1 }), 'need-token'),
+    stateReady: () => checked(parseSealedFrameMessage({ t: 'state', v: 1, state: 'ready' }), 'state'),
+    unavailable: (reason) => checked(parseSealedFrameMessage({ t: 'state', v: 1, state: 'unavailable', reason }), 'state'),
+    navigate: (to) => checked(parseSealedFrameMessage({ t: 'navigate', v: 1, to }), 'navigate'),
+    wiped: () => checked(parseSealedFrameMessage({ t: 'wiped', v: 1 }), 'wiped'),
+};
+/** The host's `sealed/wipe` for the sign-out page. `account` null wipes every account's Sealed data in the browser. */
+export function sealedWipeRequest(account) {
+    return checked(parseSealedWipeRequest({ t: 'sealed/wipe', v: 1, account }), 'wipe');
+}
+/**
+ * The frame origin as an exact origin (`https://sealed.minds.com`), or a TypeError. Only https, or http on localhost
+ * for development; no path, query, fragment or credentials.
+ */
+export function sealedFrameOrigin(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError('frameOrigin must be an origin such as https://sealed.minds.com');
+    }
+    const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '[::1]';
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/'
+        || !(url.protocol === 'https:' || (url.protocol === 'http:' && local))) {
+        throw new TypeError('frameOrigin must be an https origin with no path, such as https://sealed.minds.com');
+    }
+    return url.origin;
+}

package/dist/sealed-frame/wipe.d.ts

@@ -0,0 +1,25 @@
+export interface WipeSealedFrameOptions {
+    /** The frame origin, e.g. `https://sealed.minds.com`. */
+    frameOrigin: string;
+    /** The account signing out (its user id); null wipes every account's Sealed data in this browser. */
+    account: string | null;
+    /** How long to wait in all, page load included, before giving up. 1500 ms by default. */
+    timeoutMs?: number;
+    /** The document to load the page in; the global one by default. */
+    document?: Document;
+}
+/** How long a sign-out waits for the Sealed data to go before it carries on (the frame design, section 7). */
+export declare const SEALED_WIPE_TIMEOUT_MS = 1500;
+/**
+ * Clears an account's Sealed chats from this browser at sign-out, whether or not a Sealed frame is open: it loads the
+ * frame origin's sign-out page (/wipe.html) in a hidden iframe, posts `sealed/wipe` to that origin only with a
+ * transferred MessagePort, and waits for `wiped` on the port. Resolves `wiped`, or `timeout` once `timeoutMs` has passed
+ * in all (page load included) so sign-out never hangs on it. Either way the iframe is removed. Call it on every
+ * sign-out path before the page reloads.
+ *
+ * The page writes a pending-wipe record first, so a wipe cut short by the reload finishes on the frame's next load.
+ * Without a DOM (React Native, a server render) it resolves `timeout` at once and does nothing.
+ *
+ * Only the port carries the answer: a window message, from any origin or window, is never read.
+ */
+export declare function wipeSealedFrame(options: WipeSealedFrameOptions): Promise<'wiped' | 'timeout'>;

package/dist/sealed-frame/wipe.js

@@ -0,0 +1,67 @@
+import { parseSealedFrameMessage, SEALED_FRAME_REFERRER_POLICY, SEALED_WIPE_PATH, SEALED_WIPE_SANDBOX, sealedFrameOrigin, sealedWipeRequest, } from './protocol.js';
+/** How long a sign-out waits for the Sealed data to go before it carries on (the frame design, section 7). */
+export const SEALED_WIPE_TIMEOUT_MS = 1500;
+/**
+ * Clears an account's Sealed chats from this browser at sign-out, whether or not a Sealed frame is open: it loads the
+ * frame origin's sign-out page (/wipe.html) in a hidden iframe, posts `sealed/wipe` to that origin only with a
+ * transferred MessagePort, and waits for `wiped` on the port. Resolves `wiped`, or `timeout` once `timeoutMs` has passed
+ * in all (page load included) so sign-out never hangs on it. Either way the iframe is removed. Call it on every
+ * sign-out path before the page reloads.
+ *
+ * The page writes a pending-wipe record first, so a wipe cut short by the reload finishes on the frame's next load.
+ * Without a DOM (React Native, a server render) it resolves `timeout` at once and does nothing.
+ *
+ * Only the port carries the answer: a window message, from any origin or window, is never read.
+ */
+export function wipeSealedFrame(options) {
+    const frameOrigin = sealedFrameOrigin(options.frameOrigin);
+    const request = sealedWipeRequest(options.account);
+    const timeoutMs = options.timeoutMs ?? SEALED_WIPE_TIMEOUT_MS;
+    const doc = options.document ?? (typeof document === 'undefined' ? undefined : document);
+    if (!doc?.body || typeof MessageChannel === 'undefined')
+        return Promise.resolve('timeout');
+    return new Promise((resolve) => {
+        const iframe = doc.createElement('iframe');
+        let port = null;
+        let done = false;
+        const finish = (result) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            iframe.removeEventListener('load', onLoad);
+            if (port) {
+                port.onmessage = null;
+                port.close();
+            }
+            iframe.remove();
+            resolve(result);
+        };
+        const onLoad = () => {
+            const target = iframe.contentWindow;
+            if (done || !target)
+                return;
+            // A second load (the page reloaded itself) gets a fresh port; the old one is closed and never read again.
+            if (port) {
+                port.onmessage = null;
+                port.close();
+            }
+            const channel = new MessageChannel();
+            port = channel.port1;
+            channel.port1.onmessage = (event) => {
+                if (parseSealedFrameMessage(event.data)?.t === 'wiped')
+                    finish('wiped');
+            };
+            target.postMessage(request, frameOrigin, [channel.port2]);
+        };
+        const timer = setTimeout(() => finish('timeout'), timeoutMs);
+        iframe.setAttribute('sandbox', SEALED_WIPE_SANDBOX);
+        iframe.setAttribute('referrerpolicy', SEALED_FRAME_REFERRER_POLICY);
+        iframe.setAttribute('aria-hidden', 'true');
+        iframe.tabIndex = -1;
+        iframe.style.display = 'none';
+        iframe.addEventListener('load', onLoad);
+        iframe.src = `${frameOrigin}${SEALED_WIPE_PATH}`;
+        doc.body.appendChild(iframe);
+    });
+}

package/llm.md

@@ -856,6 +856,13 @@ const { data: capabilities } = await r.privacy.capabilities()
 const showNoPushLine = isFactLive('sealed.no_push', capabilities)
 const showCheckedLine = isFactLive('sealed.attest_before_send', capabilities, { deviceFacts: ['sealed.attest_before_send'] })
 ```
+- `r.sealed` web frame routes (unreleased; server switch `config().web`, SEALED_GATEWAY_WEB) — `frameToken()` → `{ token, expiresAt, expiresIn?, origin }` (`expiresIn` only once the gateway sends `expires_in`): a short-lived `sft_` credential for the Sealed frame, minted from the member's own app key (never an API key; accepted only from `origin`, only on the frame's routes, never to mint another). `me()` → `{ user_id, privacy, content, data }` (GET /sealed/me; `data` repeats the fields so a `settings.getPreferences()` reader takes it unchanged; through a frame token `content.sealed_adult` is always false). `report({ reason, details? })` → `{ id, existing, details_kept }` (filed on the member's own account; `details` at most 2000 characters). All three are sent once, never retried, and throw AuthorizationError `sealed_web_off` while web Sealed is off (`isSealedWebOff(error)`). `@recursiv/sdk/sealed` carries only `HttpClient`, `SealedResource` and the errors, for the frame's bundle. `@recursiv/sdk/sealed-frame` (browser only) is protocol v1 for both sides: the message types, builders and validators (`parseSealedFrameHello`, `parseSealedHostMessage`, `parseSealedFrameMessage`, `parseSealedWipeRequest`; null for anything unknown, mistyped, outside its enum or over 4 KB), `mountSealedFrame({ container, frameOrigin, hostKind, scheme, layout, account, mintToken, onState, onNavigate, onTokenError? })` → `{ iframe, setTheme, setLayout, setAccount, signedOut, newChat, destroy }` (sandboxed iframe, hello + MessagePort on every load, window messages never read, one shared mint cached until 60 s before expiry, at least 30 s between mints whatever the browser clock says; `signedOut()` also runs the sign-out page and reloads a frame that has not said ready), and `wipeSealedFrame({ frameOrigin, account, timeoutMs? })` → `'wiped' | 'timeout'` for every sign-out path.
+
+```typescript
+import { mountSealedFrame, wipeSealedFrame } from '@recursiv/sdk/sealed-frame'
+const frame = mountSealedFrame({ container, frameOrigin: 'https://sealed.minds.com', hostKind: 'minds', scheme: 'dark', layout: 'column', account: me.id, mintToken: () => r.sealed.frameToken(), onState: setSealedState, onNavigate: go })
+// sign-out: await frame.signedOut()  (no frame mounted: await wipeSealedFrame({ frameOrigin, account: me.id }))
+```
 - `r.billing` — Usage tracking, checkout sessions, portal sessions, metered billing
 - `r.appSubscriptions` — Project-scoped consumer plans: `checkout` (409 `subscription_exists` when the member already pays), `status`, `createPortalSession({ return_url, flow?: 'cancel' })` (`flow: 'cancel'` opens Stripe's cancel confirmation; 409 `no_subscription` when there is no plan to cancel), `previewTierChange({ tier })`, `changeTier({ tier, proration_date? })` (in-place, prorated, never a second subscription)
 - `r.boosts` — Promoted posts (micro-USD): `create`, `mine`, `balance`, `pause`, `resume`, `cancel`, `recordEvent`; buy credit with `topup({ amount_cents, return_url })` then `confirmTopup(sessionId)` (credits once); admin `listPendingReview`, `review`, `grant`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@recursiv/sdk",
-  "version": "0.7.121",
+  "version": "0.7.122",
   "description": "TypeScript SDK for the Recursiv API",
   "license": "FSL-1.1-ALv2",
   "type": "module",
@@ -32,6 +32,16 @@
       "types": "./dist/privacy/index.d.ts",
       "import": "./dist/privacy/index.js",
       "default": "./dist/privacy/index.js"
+    },
+    "./sealed": {
+      "types": "./dist/sealed/index.d.ts",
+      "import": "./dist/sealed/index.js",
+      "default": "./dist/sealed/index.js"
+    },
+    "./sealed-frame": {
+      "types": "./dist/sealed-frame/index.d.ts",
+      "import": "./dist/sealed-frame/index.js",
+      "default": "./dist/sealed-frame/index.js"
     }
   },
   "files": [