@recursiv/sdk 0.7.121 → 0.7.122

package/dist/sealed-frame/host.js

@@ -0,0 +1,379 @@
+import { isSealedFrameToken, parseSealedFrameMessage, SEALED_FRAME_ALLOW, SEALED_FRAME_HOST_KINDS, SEALED_FRAME_LAYOUTS, SEALED_FRAME_PROTOCOL, SEALED_FRAME_REFERRER_POLICY, SEALED_FRAME_SANDBOX, SEALED_FRAME_SCHEMES, sealedFrameHello, sealedFrameOrigin, sealedHostMessage, } from './protocol.js';
+import { SEALED_WIPE_TIMEOUT_MS, wipeSealedFrame } from './wipe.js';
+/**
+ * A cached token is handed out until this long before it expires (later only to a frame load that does not hold it,
+ * while the next mint is held back); the frame asks again then.
+ */
+export const SEALED_FRAME_TOKEN_REFRESH_MS = 60_000;
+/**
+ * The least time between two mints that worked, for one account: whatever the browser's clock says (a fast clock makes
+ * every token look near its expiry) and however often the frame asks, the host mints at most twice a minute.
+ */
+const MIN_MINT_GAP_MS = 30_000;
+/** The longest a token may say it lives (`expiresIn`): a day, far above anything the API grants. */
+const MAX_LIFE_SECONDS = 86_400;
+const FIRST_BACKOFF_MS = 2_000;
+const MAX_BACKOFF_MS = 60_000;
+const READY_TIMEOUT_MS = 15_000;
+function expiryMs(value) {
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string')
+        return Date.parse(value);
+    return Number.NaN;
+}
+/**
+ * When a minted token expires, in this browser's clock: `startedAt` (when the host asked for it) plus `expiresIn` when
+ * the API said how long it lives, else `expiresAt` as given. NaN when neither is usable.
+ */
+function localExpiryMs(minted, startedAt) {
+    if (minted?.expiresIn !== undefined) {
+        const life = minted.expiresIn;
+        if (typeof life !== 'number' || !Number.isFinite(life) || life <= 0 || life > MAX_LIFE_SECONDS)
+            return Number.NaN;
+        return startedAt + life * 1000;
+    }
+    return expiryMs(minted?.expiresAt);
+}
+/**
+ * The host's frame tokens: one cached token, handed out until 60 s before it expires; one shared mint in flight; at
+ * least 30 s between two mints that worked; and after a failed mint, nothing new for 2 s doubling to 60 s.
+ */
+class FrameTokens {
+    mint;
+    frameOrigin;
+    onError;
+    cached = null;
+    inflight = null;
+    generation = 0;
+    failures = 0;
+    notBefore = 0;
+    /** When the last mint that worked was asked for, in this generation. */
+    lastMinted = Number.NEGATIVE_INFINITY;
+    constructor(mint, frameOrigin, onError) {
+        this.mint = mint;
+        this.frameOrigin = frameOrigin;
+        this.onError = onError;
+    }
+    /** Whether `token` is the cached token for `account`. */
+    holds(account, token) {
+        return this.cached?.account === account && this.cached.token === token;
+    }
+    /**
+     * A token for `account`. `refused`: the frame already holds the cached one and asks again (the API refused it, or it
+     * is near its expiry). Null when a mint failed.
+     */
+    async get(account, refused) {
+        const now = Date.now();
+        const cached = this.cached !== null && this.cached.account === account ? this.cached : null;
+        const usable = cached !== null && cached.expiresAtMs - SEALED_FRAME_TOKEN_REFRESH_MS > now;
+        if (cached && usable && !refused)
+            return { token: cached };
+        if (this.inflight && this.inflight.account === account) {
+            const token = await this.inflight.promise;
+            return token ? { token } : null;
+        }
+        const waitMs = Math.max(this.notBefore - now, this.lastMinted + MIN_MINT_GAP_MS - now);
+        if (waitMs > 0) {
+            // While the next mint is held back, a frame load that does not hold the cached token yet gets it if it is alive.
+            if (cached && !refused && cached.expiresAtMs > now)
+                return { token: cached };
+            return { waitMs };
+        }
+        const token = await this.start(account);
+        return token ? { token } : null;
+    }
+    /** Drops the cached token and any mint in flight (an account switch or sign-out): neither is handed out again. */
+    forget() {
+        this.generation += 1;
+        this.cached = null;
+        this.inflight = null;
+        this.lastMinted = Number.NEGATIVE_INFINITY;
+    }
+    start(account) {
+        const generation = this.generation;
+        const startedAt = Date.now();
+        const promise = Promise.resolve()
+            .then(() => this.mint())
+            .then((minted) => {
+            const expiresAtMs = localExpiryMs(minted, startedAt);
+            if (!isSealedFrameToken(minted?.token))
+                throw new TypeError('mintToken did not give a Sealed frame token');
+            if (!Number.isFinite(expiresAtMs) || expiresAtMs <= Date.now()) {
+                throw new TypeError('mintToken gave a frame token with no expiry, or one already expired');
+            }
+            if (minted.origin !== undefined && minted.origin !== this.frameOrigin) {
+                throw new TypeError(`mintToken gave a frame token for ${String(minted.origin)}, not ${this.frameOrigin}`);
+            }
+            const token = { account, token: minted.token, expiresAtMs: Math.floor(expiresAtMs) };
+            if (generation !== this.generation)
+                return null;
+            this.failures = 0;
+            this.notBefore = 0;
+            this.lastMinted = startedAt;
+            this.cached = token;
+            return token;
+        })
+            .catch((error) => {
+            if (generation === this.generation) {
+                this.failures += 1;
+                this.notBefore = Date.now() + Math.min(MAX_BACKOFF_MS, FIRST_BACKOFF_MS * 2 ** (this.failures - 1));
+            }
+            this.onError?.(error);
+            return null;
+        });
+        const entry = { account, promise };
+        this.inflight = entry;
+        void promise.then(() => {
+            if (this.inflight === entry)
+                this.inflight = null;
+        });
+        return promise;
+    }
+}
+function checkEnum(values, value, name) {
+    if (typeof value !== 'string' || !values.includes(value)) {
+        throw new TypeError(`${name} must be one of ${values.join(', ')}`);
+    }
+    return value;
+}
+function checkAccount(value, allowNull) {
+    if (value === null && allowNull)
+        return null;
+    // The hello builder holds the full rule; this gives a clearer error first.
+    if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,64}$/.test(value)) {
+        throw new TypeError(`account must be the member's user id${allowNull ? ', or null' : ''}`);
+    }
+    return value;
+}
+/**
+ * Embeds the Sealed frame in `container` and runs the host's side of protocol v1 (protocol.ts). The iframe is
+ * sandboxed (SEALED_FRAME_SANDBOX), may only write to the clipboard, sends no referrer, and is never `credentialless`
+ * (that would give the frame a throwaway storage partition and lose the member's Sealed chats).
+ *
+ * On every load of the iframe the host posts `sealed/hello` to the frame origin only, with a new MessagePort, and from
+ * then on reads that port only: a window message is never read, whatever its origin or source, and a port from an
+ * earlier load is closed. Nothing counts until the frame answers `ready`.
+ *
+ * `need-token` is answered through `mintToken`, minting at most once per token life and never twice in 30 s (see
+ * MountSealedFrameOptions), so reloading the frame, a frame that asks too often or a wrong browser clock never storms
+ * the API. The token cache belongs to one mount: keep one mount for as long as the page shows Sealed, since each new
+ * mount mints afresh on its frame's first ask.
+ *
+ * Browser only: call it in an effect, and `destroy()` on unmount.
+ */
+export function mountSealedFrame(options) {
+    const frameOrigin = sealedFrameOrigin(options.frameOrigin);
+    const hostKind = checkEnum(SEALED_FRAME_HOST_KINDS, options.hostKind, 'hostKind');
+    let scheme = checkEnum(SEALED_FRAME_SCHEMES, options.scheme, 'scheme');
+    let layout = checkEnum(SEALED_FRAME_LAYOUTS, options.layout, 'layout');
+    let account = checkAccount(options.account, true);
+    if (typeof options.mintToken !== 'function')
+        throw new TypeError('mintToken must be a function');
+    const readyTimeoutMs = options.readyTimeoutMs ?? READY_TIMEOUT_MS;
+    const doc = options.container.ownerDocument;
+    const tokens = new FrameTokens(options.mintToken, frameOrigin, options.onTokenError);
+    const waiters = new Set();
+    let session = null;
+    let destroyed = false;
+    let readyTimer;
+    const iframe = doc.createElement('iframe');
+    /** From the mount and from each load: a frame that has not said `ready` in time is reported as `no_answer`. */
+    function armReadyTimer() {
+        clearTimeout(readyTimer);
+        readyTimer = setTimeout(() => {
+            if (!destroyed && !session?.ready)
+                options.onState?.({ state: 'unavailable', reason: 'no_answer' });
+        }, readyTimeoutMs);
+    }
+    function endSession() {
+        if (!session)
+            return;
+        clearTimeout(session.tokenTimer);
+        session.port.onmessage = null;
+        session.port.close();
+        session = null;
+    }
+    function settleWaiters(result) {
+        const pending = [...waiters];
+        waiters.clear();
+        for (const settle of pending)
+            settle(result);
+    }
+    function post(message) {
+        session?.port.postMessage(message);
+    }
+    async function answerNeedToken(current) {
+        const forAccount = account;
+        if (forAccount === null || current.tokenTimer !== undefined)
+            return;
+        const refused = current.delivered !== null && tokens.holds(forAccount, current.delivered);
+        const answer = await tokens.get(forAccount, refused);
+        if (destroyed || session !== current || account !== forAccount || !answer)
+            return;
+        if ('waitMs' in answer) {
+            if (current.tokenTimer === undefined) {
+                current.tokenTimer = setTimeout(() => {
+                    current.tokenTimer = undefined;
+                    void answerNeedToken(current);
+                }, answer.waitMs);
+            }
+            return;
+        }
+        current.port.postMessage(sealedHostMessage.token(answer.token.token, answer.token.expiresAtMs, forAccount));
+        current.delivered = answer.token.token;
+    }
+    function onFrameMessage(current, data) {
+        if (destroyed || session !== current)
+            return;
+        const message = parseSealedFrameMessage(data);
+        if (!message)
+            return;
+        if (!current.ready) {
+            if (message.t !== 'ready')
+                return;
+            clearTimeout(readyTimer);
+            if (message.protocol !== SEALED_FRAME_PROTOCOL) {
+                endSession();
+                options.onState?.({ state: 'unavailable', reason: 'update' });
+                return;
+            }
+            current.ready = true;
+            return;
+        }
+        switch (message.t) {
+            case 'need-token':
+                void answerNeedToken(current);
+                return;
+            case 'state':
+                options.onState?.(message.state === 'ready' ? { state: 'ready' } : { state: 'unavailable', reason: message.reason });
+                return;
+            case 'navigate':
+                options.onNavigate?.(message.to);
+                return;
+            case 'wiped':
+                settleWaiters('wiped');
+                return;
+            default:
+                // A second `ready`: ignored.
+                return;
+        }
+    }
+    function onLoad() {
+        if (destroyed)
+            return;
+        endSession();
+        const target = iframe.contentWindow;
+        if (!target)
+            return;
+        const channel = new MessageChannel();
+        const current = { port: channel.port1, ready: false, delivered: null, tokenTimer: undefined };
+        session = current;
+        channel.port1.onmessage = (event) => onFrameMessage(current, event.data);
+        armReadyTimer();
+        target.postMessage(sealedFrameHello({ host: hostKind, scheme, layout, account }), frameOrigin, [channel.port2]);
+    }
+    // Every attribute before the src: the sandbox applies from the first navigation.
+    iframe.setAttribute('sandbox', SEALED_FRAME_SANDBOX);
+    iframe.setAttribute('allow', SEALED_FRAME_ALLOW);
+    iframe.setAttribute('referrerpolicy', SEALED_FRAME_REFERRER_POLICY);
+    iframe.title = options.title ?? 'Sealed chat';
+    iframe.style.border = '0';
+    iframe.style.display = 'block';
+    iframe.style.width = '100%';
+    iframe.style.height = '100%';
+    iframe.addEventListener('load', onLoad);
+    iframe.src = `${frameOrigin}/`;
+    options.container.appendChild(iframe);
+    armReadyTimer();
+    return {
+        iframe,
+        setTheme(next) {
+            if (destroyed)
+                return;
+            scheme = checkEnum(SEALED_FRAME_SCHEMES, next, 'scheme');
+            post(sealedHostMessage.theme(scheme));
+        },
+        setLayout(next) {
+            if (destroyed)
+                return;
+            layout = checkEnum(SEALED_FRAME_LAYOUTS, next, 'layout');
+            post(sealedHostMessage.layout(layout));
+        },
+        setAccount(next) {
+            if (destroyed)
+                return;
+            const checked = checkAccount(next, false);
+            if (checked === account)
+                return;
+            account = checked;
+            tokens.forget();
+            if (session) {
+                session.delivered = null;
+                clearTimeout(session.tokenTimer);
+                session.tokenTimer = undefined;
+            }
+            post(sealedHostMessage.account(checked));
+        },
+        signedOut(signOutOptions) {
+            if (destroyed)
+                return Promise.resolve('timeout');
+            const timeoutMs = signOutOptions?.timeoutMs ?? SEALED_WIPE_TIMEOUT_MS;
+            const previous = account;
+            account = null;
+            tokens.forget();
+            const current = session;
+            // Always, beside the frame's own wipe: the page records the wipe before doing it, so a frame whose port is dead
+            // (mid-reload) or a page that reloads now still loses the account's data on the frame's next load.
+            const viaPage = wipeSealedFrame({ frameOrigin, account: previous, timeoutMs, document: doc });
+            if (!current?.ready) {
+                // A frame that has had its hello but not said ready accepted the account it named. Reload it: its next hello
+                // is signed out, and the reload closes any of the account's storage it holds open (which would block the wipe).
+                if (current) {
+                    endSession();
+                    iframe.src = `${frameOrigin}/`;
+                }
+                return viaPage;
+            }
+            current.delivered = null;
+            clearTimeout(current.tokenTimer);
+            current.tokenTimer = undefined;
+            return new Promise((resolve) => {
+                let done = false;
+                const settle = (result) => {
+                    if (done)
+                        return;
+                    done = true;
+                    clearTimeout(timer);
+                    waiters.delete(settle);
+                    resolve(result);
+                };
+                const timer = setTimeout(() => settle('timeout'), timeoutMs);
+                waiters.add(settle);
+                post(sealedHostMessage.signedOut());
+                void viaPage.then((result) => {
+                    if (result === 'wiped')
+                        settle('wiped');
+                });
+            });
+        },
+        newChat() {
+            if (destroyed)
+                return;
+            post(sealedHostMessage.newChat());
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            clearTimeout(readyTimer);
+            endSession();
+            tokens.forget();
+            settleWaiters('timeout');
+            iframe.removeEventListener('load', onLoad);
+            iframe.remove();
+        },
+    };
+}

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

@@ -0,0 +1,15 @@
+/**
+ * `@recursiv/sdk/sealed-frame`: web Sealed's frame protocol (v1) for both sides, and the host's helpers. Browser only.
+ *
+ * - Host pages (minds.com/ai, build.minds.com): `mountSealedFrame()` embeds https://sealed.minds.com and runs the
+ *   handshake, the token answers and the sign-out; `wipeSealedFrame()` clears an account's Sealed chats at any sign-out.
+ * - The Sealed frame: the same message types, builders and validators (`parseSealedFrameHello`,
+ *   `parseSealedHostMessage`, `sealedFrameMessage`, ...), so both sides agree on what may cross.
+ *
+ * Importing it touches no DOM: everything runs when called.
+ */
+export * from './protocol.js';
+export { mountSealedFrame, SEALED_FRAME_TOKEN_REFRESH_MS } from './host.js';
+export type { MountSealedFrameOptions, SealedFrameHandle, SealedFrameHostState, SealedFrameMintedToken } from './host.js';
+export { SEALED_WIPE_TIMEOUT_MS, wipeSealedFrame } from './wipe.js';
+export type { WipeSealedFrameOptions } from './wipe.js';

package/dist/sealed-frame/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@recursiv/sdk/sealed-frame`: web Sealed's frame protocol (v1) for both sides, and the host's helpers. Browser only.
+ *
+ * - Host pages (minds.com/ai, build.minds.com): `mountSealedFrame()` embeds https://sealed.minds.com and runs the
+ *   handshake, the token answers and the sign-out; `wipeSealedFrame()` clears an account's Sealed chats at any sign-out.
+ * - The Sealed frame: the same message types, builders and validators (`parseSealedFrameHello`,
+ *   `parseSealedHostMessage`, `sealedFrameMessage`, ...), so both sides agree on what may cross.
+ *
+ * Importing it touches no DOM: everything runs when called.
+ */
+export * from './protocol.js';
+export { mountSealedFrame, SEALED_FRAME_TOKEN_REFRESH_MS } from './host.js';
+export { SEALED_WIPE_TIMEOUT_MS, wipeSealedFrame } from './wipe.js';