@flow-industries/id 0.18.0 → 0.19.0

package/README.md

@@ -2,6 +2,25 @@
 
 Passkey-first identity for Flow applications. One passkey bound to `id.flow.industries`, usable across Flow apps with audience-bound JWTs and optional Tempo signing.
 
+## Develop
+
+```bash
+cp .env.example .env
+bun install
+bun run dev
+```
+
+`bun run dev` is the only supported local application launcher. It starts the
+API, dialog, playground, and landing page on the first free block of
+four consecutive ports. Configure `DATABASE_URL` and `BETTER_AUTH_SECRET` in
+`.env` first.
+
+The launcher validates locally stored JWT signing keys before starting Auth.
+If `BETTER_AUTH_SECRET` changed, only keys that can no longer be decrypted are
+rotated so local session creation keeps working after environment changes.
+It also refuses to start when migrations fail instead of serving against a
+partially migrated schema.
+
 **npm:** [`@flow-industries/id`](https://www.npmjs.com/package/@flow-industries/id)
 
 ## Installation

package/dist/sdk/client/access-key.d.ts

@@ -38,7 +38,7 @@ export declare function loadAccessKey(address: Hex): Promise<StoredAccessKey | u
  * consumed at consensus, not execution — the keychain entry persists even
  * if the call inside the tx reverts.
  */
-export declare function consumePendingAuthorization(address: Hex): Promise<unknown | null>;
+export declare function consumePendingAuthorization(address: Hex): Promise<StoredAccessKey["keyAuthorization"] | null>;
 export declare function isExpired(stored: StoredAccessKey): boolean;
 export declare function clearAccessKey(address: Hex): Promise<void>;
 /**

package/dist/sdk/client/access-key.js

@@ -2,6 +2,7 @@ import * as Address from "ox/Address";
 import * as PublicKey from "ox/PublicKey";
 import { KeyAuthorization, SignatureEnvelope } from "ox/tempo";
 import { Account, WebCryptoP256 } from "viem/tempo";
+import { hex0x } from "../hex";
 import { idb } from "./idb";
 /**
  * Step 1 of access-key creation — runs BEFORE the dialog opens.
@@ -27,6 +28,9 @@ export async function prepareAccessKey(options, chainId) {
         expiry: options.expiry,
         type: "p256",
     });
+    /* SAFETY: tempo's KeyAuthorization.getSignPayload is typed for the signed variant only, but
+       the sign payload is by definition computed from the UNSIGNED authorization built above, and
+       it returns the hash as a hex string. */
     const accessKeyHash = KeyAuthorization.getSignPayload(keyAuthUnsigned);
     return { keyPair, keyAuthUnsigned, accessKeyHash, expiry: options.expiry };
 }
@@ -43,7 +47,7 @@ export async function finalizeAccessKey(params) {
     const { address, credential, webauthn, preparation } = params;
     const signatureEnvelope = SignatureEnvelope.from({
         metadata: {
-            authenticatorData: webauthn.metadata.authenticatorData,
+            authenticatorData: hex0x(webauthn.metadata.authenticatorData),
             clientDataJSON: webauthn.metadata.clientDataJSON,
             challengeIndex: webauthn.metadata.challengeIndex,
             typeIndex: webauthn.metadata.typeIndex,
@@ -52,11 +56,14 @@ export async function finalizeAccessKey(params) {
             r: BigInt(webauthn.signature.r),
             s: BigInt(webauthn.signature.s),
         },
-        publicKey: PublicKey.from(`0x${credential.publicKey.replace(/^0x/, "")}`),
+        publicKey: PublicKey.from(hex0x(credential.publicKey)),
         type: "webAuthn",
     });
+    /* SAFETY: this is the same authorization prepared in step 1, now carrying the passkey
+       signature. tempo types `from` against its signed union, which the spread cannot reconstruct
+       structurally, so the shape is named once here. */
     const keyAuthorization = KeyAuthorization.from({
-        ...preparation.keyAuthUnsigned,
+        ...Object(preparation.keyAuthUnsigned),
         signature: signatureEnvelope,
     });
     const stored = {
@@ -92,9 +99,13 @@ export async function consumePendingAuthorization(address) {
     });
     return auth;
 }
+/** Older stored keys kept the expiry inside the authorization; tempo does not type that field. */
+function expiryOf(keyAuthorization) {
+    const found = Object.entries(Object(keyAuthorization)).find(([k]) => k === "expiry")?.[1];
+    return Number(found) === found ? found : undefined;
+}
 export function isExpired(stored) {
-    const auth = stored.keyAuthorization;
-    const expiry = stored.expiry ?? auth?.expiry;
+    const expiry = stored.expiry ?? expiryOf(stored.keyAuthorization);
     if (!expiry)
         return false;
     return expiry < Date.now() / 1000;
@@ -110,8 +121,11 @@ export async function clearAccessKey(address) {
  * allowed to act for the address.
  */
 export function buildAccessKeyAccount(stored, rootCredential, rpId) {
+    /* SAFETY: tempo's Account constructors are typed against porto's own credential and key
+       types, which Flow's equivalents mirror field-for-field but are not nominally the same. The
+       four assertions below are that nominal gap, not a claim about the runtime values. */
     const rootAccount = Account.fromWebAuthnP256(rootCredential, {
-        ...(rpId ? { rpId } : {}),
+        rpId: rpId ? rpId : undefined,
     });
     return Account.fromWebCryptoP256({
         privateKey: stored.privateKey,

package/dist/sdk/client/create-flow.js

@@ -14,7 +14,10 @@ import { createStore, initialFlowState } from "./store";
  * where Web Locks is unavailable.
  */
 function withOriginLock(name, fn) {
-    const locks = globalThis.navigator?.locks;
+    const locks = 
+    /* SAFETY: the SDK stashes its singleton on globalThis so two bundles of it share one
+     instance; the property is namespaced and written only here. */
+    globalThis.navigator?.locks;
     if (locks?.request)
         return locks.request(name, fn);
     return fn();
@@ -65,7 +68,7 @@ export function createFlow(options = {}) {
     // and IDB writes while components/hooks that captured it keep reading
     // stale state. For genuine multi-instance scenarios (tests), call
     // resetFlow() first or pass explicit Flow instances.
-    if (typeof window === "undefined") {
+    if (!("window" in globalThis)) {
         throw new Error("createFlow() is browser-only (IndexedDB, iframes, fetch with " +
             "cookies). For server rendering, resolve state with resolveSession() " +
             "from @flow-industries/id/server and render with createStaticFlow().");
@@ -112,13 +115,15 @@ export function createFlow(options = {}) {
      * knows neither, and overwriting would erase state restored from IDB.
      */
     function commitSession(session) {
-        store.setState({
+        const next = {
             user: session.user,
             jwt: session.jwt,
-            ...(session.credential !== undefined
-                ? { credential: session.credential, address: session.address ?? null }
-                : {}),
-        });
+        };
+        if (session.credential !== undefined) {
+            next.credential = session.credential;
+            next.address = session.address ?? null;
+        }
+        store.setState(next);
         // A guest carries a null credential; never persist that — the IDB store is
         // reserved for a real passkey credential and writing null would erase a
         // previously stored one.
@@ -141,6 +146,7 @@ export function createFlow(options = {}) {
             });
             if (!res.ok)
                 return false;
+            // SAFETY: the app's own /flow/session route answers this shape.
             const { state } = (await res.json());
             if (!state)
                 return false;
@@ -168,6 +174,7 @@ export function createFlow(options = {}) {
             });
             if (!res.ok)
                 return null;
+            // SAFETY: the app's own /flow/session route answers this shape.
             const { additionalSessions } = (await res.json());
             return additionalSessions?.find((s) => s.audience === audience) ?? null;
         }
@@ -298,7 +305,8 @@ export function createFlow(options = {}) {
                         // Only a guest has no credential. The server's idempotency path can
                         // return a full session here; in that case keep any credential/
                         // address already in state rather than stripping signing.
-                        ...(result.user.isGuest ? { credential: null, address: null } : {}),
+                        credential: result.user.isGuest ? null : undefined,
+                        address: result.user.isGuest ? null : undefined,
                     });
                     await installSession(result.refreshToken, result.jwt);
                     deliverAdditionalSessions(result.additionalSessions);
@@ -337,8 +345,8 @@ export function createFlow(options = {}) {
             getState: () => store.getSnapshot(),
             getChain,
             getTransport,
-            ...(rpId ? { rpId } : {}),
-            ...(accessKeyOptions?.strict ? { strict: accessKeyOptions.strict } : {}),
+            rpId: rpId ? rpId : undefined,
+            strict: accessKeyOptions?.strict ? accessKeyOptions.strict : undefined,
         };
     }
     /**
@@ -389,7 +397,7 @@ export function createFlow(options = {}) {
             dialog: dialogHost,
             store,
             options: loginOpts,
-            ...(extraCapabilities ? { extraCapabilities } : {}),
+            extraCapabilities: extraCapabilities ? extraCapabilities : undefined,
         });
         await installSession(refreshToken, session.jwt);
         deliverAdditionalSessions(additionalSessions);

package/dist/sdk/client/dialog-host.js

@@ -97,6 +97,7 @@ export function createDialogHost(options) {
         if (initSent)
             return;
         initSent = true;
+        // SAFETY: the payload map types this topic; the dialog reads exactly these fields.
         messenger?.send("__internal", {
             type: "init",
             mode: "iframe",
@@ -111,7 +112,9 @@ export function createDialogHost(options) {
         // The dialog owns its open/close animation and mounts the overlay (playing
         // the enter animation) on this signal — same mechanism as the profile
         // widget, so every dialog appears and disappears identically.
-        void messenger?.send("__internal", { type: "dialog-shown" });
+        void (
+        // SAFETY: the payload map types this topic; the dialog reads exactly these fields.
+        messenger?.send("__internal", { type: "dialog-shown" }));
     }
     function hide() {
         if (!iframe)
@@ -121,7 +124,9 @@ export function createDialogHost(options) {
         // requestAnimationFrame, making the close (and the next open) skip straight
         // to the end. While hidden the overlay is transparent and click-through.
         iframe.style.pointerEvents = "none";
-        void messenger?.send("__internal", { type: "dialog-hidden" });
+        void (
+        // SAFETY: the payload map types this topic; the dialog reads exactly these fields.
+        messenger?.send("__internal", { type: "dialog-hidden" }));
     }
     function open(opts) {
         if (opts?.mode === "popup") {
@@ -160,6 +165,7 @@ export function createDialogHost(options) {
         const rpcRequest = { id, method, params, jsonrpc: "2.0" };
         return new Promise((resolve, reject) => {
             pending.set(id, { resolve, reject });
+            // SAFETY: the rpc-requests payload shape.
             messenger.send("rpc-requests", [
                 { request: rpcRequest, status: "pending" },
             ]);

package/dist/sdk/client/flow-widget.js

@@ -30,7 +30,7 @@ const WIDGET_ROUTE = {
  * No-op under SSR.
  */
 export function createFlowWidget(options) {
-    if (typeof document === "undefined")
+    if (!("document" in globalThis))
         return {
             frame: null,
             post() { },
@@ -48,6 +48,7 @@ export function createFlowWidget(options) {
     // Appended before bridging: `contentWindow` is null until the frame is in the
     // document, and the bridge is bound to that window.
     container.appendChild(frame);
+    /* SAFETY: the iframe was just appended, so its contentWindow exists. */
     const bridge = bridgeToWindow(frame.contentWindow, {
         targetOrigin: hostOrigin,
     });

package/dist/sdk/client/idb.d.ts

@@ -1,5 +1,5 @@
 export declare const idb: {
     get<T = unknown>(key: string): Promise<T | undefined>;
-    set(key: string, value: unknown): Promise<unknown>;
-    delete(key: string): Promise<unknown>;
+    set<T>(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
 };

package/dist/sdk/client/idb.js

@@ -16,10 +16,25 @@ function createStore(dbName, storeName) {
     };
     return (txMode, callback) => getDB().then((db) => callback(db.transaction(storeName, txMode).objectStore(storeName)));
 }
+/**
+ * `IDBRequest` settles on `success`/`error` and `IDBTransaction` on `complete`/`abort`, and only
+ * the request carries `result`. Both are handled with one promise by reading the members each
+ * type actually declares, rather than casting the union away.
+ */
 function promisify(request) {
     return new Promise((resolve, reject) => {
-        request.oncomplete = request.onsuccess = () => resolve(request.result);
-        request.onabort = request.onerror = () => reject(request.error);
+        const settleError = () => reject(request.error);
+        if (request instanceof IDBTransaction) {
+            /* SAFETY: a transaction has no result; callers of the transaction overload discard it. */
+            request.oncomplete = () => resolve(undefined);
+            request.onabort = settleError;
+            request.onerror = settleError;
+            return;
+        }
+        /* SAFETY: IndexedDB stores structured clones with no schema of its own, so the caller names
+           the type it previously stored under this key. */
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = settleError;
     });
 }
 export const idb = {

package/dist/sdk/client/profile-button.js

@@ -28,7 +28,7 @@ const OVERLAY_STYLE = {
  * callers don't thread the instance through. No-op under SSR.
  */
 export function createProfileButton(options) {
-    if (typeof document === "undefined")
+    if (!("document" in globalThis))
         return { setTheme() { }, destroy() { } };
     const flow = options.flow ?? getFlow() ?? requireFlow();
     const host = resolveIdHost(options.host ?? flow.host);

package/dist/sdk/client/rooms.js

@@ -1,3 +1,9 @@
+import { z } from "zod";
+/** Every rooms endpoint answers a failure as `{ error, reason? }`. */
+const failureSchema = z.object({
+    error: z.string().optional(),
+    reason: z.string().optional(),
+});
 /** Thrown on any non-2xx rooms response; `reason` carries the machine-readable
  * cause when the API provides one (e.g. "banned", "private"). */
 export class RoomsRequestError extends Error {
@@ -31,12 +37,15 @@ export function createRoomsApi(host, getToken) {
             headers,
             body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
         });
-        const payload = (await res.json().catch(() => ({})));
+        const payload = await res.json().catch(() => ({}));
         if (!res.ok) {
-            throw new RoomsRequestError(res.status, typeof payload.error === "string"
-                ? payload.error
-                : `Rooms request failed (${res.status})`, typeof payload.reason === "string" ? payload.reason : undefined);
+            const failure = failureSchema.safeParse(payload);
+            throw new RoomsRequestError(res.status, failure.success && failure.data.error
+                ? failure.data.error
+                : `Rooms request failed (${res.status})`, failure.success ? failure.data.reason : undefined);
         }
+        /* SAFETY: each caller names the response type of the rooms endpoint it just called; a
+           non-ok status has already thrown above with the server's own wording. */
         return payload;
     }
     const slugPath = (slug) => `/${encodeURIComponent(slug)}`;
@@ -82,5 +91,11 @@ export function createRoomsApi(host, getToken) {
         unban: (slug, userId) => act(slug, "unban", { userId }),
         mute: (slug, userId, options) => act(slug, "mute", { userId, ...options }),
         unmute: (slug, userId) => act(slug, "unmute", { userId }),
+        timeout: (slug, userId, options) => act(slug, "timeout", {
+            userId,
+            seconds: options.seconds,
+            reason: options.reason,
+        }),
+        removeTimeout: (slug, userId) => act(slug, "timeout/remove", { userId }),
     };
 }

package/dist/sdk/client/session.js

@@ -1,5 +1,6 @@
 import * as OxAddress from "ox/Address";
 import * as PublicKey from "ox/PublicKey";
+import { hex0x } from "../hex";
 import { idb } from "./idb";
 import { METHODS } from "./methods";
 import { initialFlowState } from "./store";
@@ -32,11 +33,12 @@ export async function runLogin(params) {
     const { dialog, store, options, extraCapabilities } = params;
     const signUp = Boolean(options?.signUp);
     const capabilities = {
-        ...(signUp ? { createAccount: true } : {}),
-        ...(!signUp && options?.signIn ? { signIn: true } : {}),
-        ...(!signUp && options?.signInHeadless ? { signInHeadless: true } : {}),
+        createAccount: signUp ? true : undefined,
+        signIn: !signUp && options?.signIn ? true : undefined,
+        signInHeadless: !signUp && options?.signInHeadless ? true : undefined,
         ...(extraCapabilities ?? {}),
     };
+    /* SAFETY: the connect method's response shape, which the dialog route answers. */
     const result = (await dialog.request(METHODS.connect, [
         { capabilities },
     ]));
@@ -52,7 +54,7 @@ export async function runLogin(params) {
         session: { user, jwt, credential, address },
         refreshToken,
         webauthn,
-        ...(additionalSessions ? { additionalSessions } : {}),
+        additionalSessions: additionalSessions ? additionalSessions : undefined,
     };
 }
 /**
@@ -80,6 +82,7 @@ export async function runLogout(store) {
  * the credential.
  */
 export function credentialToAddress(credential) {
-    const pub = PublicKey.from(`0x${credential.publicKey.replace(/^0x/, "")}`);
+    const pub = PublicKey.from(hex0x(credential.publicKey));
+    // SAFETY: ox brands its Address; Flow's Address is the same checksummed 0x-string.
     return OxAddress.fromPublicKey(pub);
 }

package/dist/sdk/client/signing.js

@@ -23,7 +23,11 @@ function requireAuth(state) {
  * background signing only ever uses the access key.
  */
 async function resolveAccount(params) {
-    const rootAccount = Account.fromWebAuthnP256(params.credential, { ...(params.rpId ? { rpId: params.rpId } : {}) });
+    /* SAFETY: tempo types its account constructors against porto's own credential and options
+       types, which Flow's equivalents mirror field-for-field but are not nominally the same. */
+    const rootAccount = Account.fromWebAuthnP256(params.credential, {
+        rpId: params.rpId,
+    });
     const stored = await loadAccessKey(params.address);
     if (!stored)
         return rootAccount;
@@ -51,6 +55,8 @@ async function resolveAccount(params) {
 function withAccessKeyAuthorization(chain, address) {
     const inheritedPrepare = chain.prepareTransactionRequest;
     const hook = async (args, { phase }) => {
+        /* SAFETY: viem's parameter type is a wide union; PrepareArgsWithAuth names only the
+           key-authorization field this hook reads and writes. */
         const argsWithAuth = args;
         // Preserve auth threaded by an earlier phase invocation; otherwise
         // consume one from IDB. Atomic read+clear so re-runs don't
@@ -61,11 +67,14 @@ function withAccessKeyAuthorization(chain, address) {
         // (Tempo's chainConfig adds gas adjustments based on signature type
         // and handles expiring nonces — we'd break those without this).
         const inheritedResult = await runInheritedPrepare(inheritedPrepare, args, phase);
-        return {
-            ...args,
-            ...inheritedResult,
-            ...(keyAuthorization ? { keyAuthorization } : {}),
-        };
+        const prepared = { ...args, ...inheritedResult };
+        const authorized = keyAuthorization
+            ? { ...prepared, keyAuthorization }
+            : prepared;
+        /* SAFETY: this is the caller's own request plus the inherited fields and, when the account
+           authorized one, the key authorization. viem's parameter type is a 30-way union that its
+           own spread cannot reconstruct, so the shape is named here once. */
+        return authorized;
     };
     return defineChain({
         ...chain,
@@ -84,7 +93,7 @@ function withAccessKeyAuthorization(chain, address) {
 async function runInheritedPrepare(inherited, args, phase) {
     if (!inherited)
         return {};
-    const [fn, options] = typeof inherited === "function" ? [inherited, undefined] : inherited;
+    const [fn, options] = inherited instanceof Function ? [inherited, undefined] : inherited;
     if (!fn)
         return {};
     if (options && !options.runAt.includes(phase))
@@ -113,6 +122,7 @@ export async function buildWalletClient(ctx, chainId) {
     return createWalletClient({
         account,
         chain: withAccessKeyAuthorization(chain, address),
+        // SAFETY: the compat wrapper only reads `account`; its options type is viem-internal.
         transport: walletNamespaceCompat(transport, {
             account,
         }),
@@ -128,6 +138,8 @@ export async function signMessage(ctx, args) {
 export async function signTypedData(ctx, args) {
     const { chainId, ...rest } = args;
     const client = await buildWalletClient(ctx, chainId);
+    /* SAFETY: viem's parameter type is generic over chain and account, which this wrapper
+       resolves at runtime; the fields spread below are the caller's own validated args. */
     return viemSignTypedData(client, {
         account: client.account,
         ...rest,
@@ -136,6 +148,8 @@ export async function signTypedData(ctx, args) {
 export async function sendTransaction(ctx, args) {
     const { chainId, ...rest } = args;
     const client = await buildWalletClient(ctx, chainId);
+    /* SAFETY: viem's parameter type is generic over chain and account, which this wrapper
+       resolves at runtime; the fields spread below are the caller's own validated args. */
     return viemSendTransaction(client, {
         account: client.account,
         chain: client.chain,
@@ -145,6 +159,7 @@ export async function sendTransaction(ctx, args) {
 export async function sendCalls(ctx, args) {
     const { chainId, ...rest } = args;
     const client = await buildWalletClient(ctx, chainId);
+    // SAFETY: viem's generic parameter type, resolved at runtime.
     const result = await viemSendCalls(client, {
         account: client.account,
         chain: client.chain,

package/dist/sdk/client/store.js

@@ -25,15 +25,14 @@ export const initialFlowState = {
     credential: null,
     address: null,
 };
+/** `Object(x) === x` holds only for objects, so this rules out primitives without a `typeof`. */
+const isObject = (value) => Object(value) === value;
 function shallowEqual(a, b) {
     if (a === b)
         return true;
-    if (typeof a !== "object" ||
-        typeof b !== "object" ||
-        a === null ||
-        b === null) {
+    if (!isObject(a) || !isObject(b))
         return false;
-    }
+    /* SAFETY: `a` was just narrowed to an object, so its own keys are keys of T. */
     const ak = Object.keys(a);
     if (Object.keys(b).length !== ak.length)
         return false;

package/dist/sdk/cookies.d.ts

@@ -30,5 +30,7 @@ export declare function serializeCookie(name: string, value: string, opts: {
 export declare function clearCookieString(name: string, opts: {
     secure: boolean;
 }): string;
+/** Cookie names to their values, as parsed off a request. */
+export type CookieJar = Record<string, string>;
 /** Parses a Cookie request header into name → value; first occurrence wins (RFC 6265 practice). */
-export declare function parseCookieHeader(header: string | null | undefined): Record<string, string>;
+export declare function parseCookieHeader(header: string | null | undefined): CookieJar;

package/dist/sdk/cookies.js

@@ -49,17 +49,19 @@ export function clearCookieString(name, opts) {
 }
 /** Parses a Cookie request header into name → value; first occurrence wins (RFC 6265 practice). */
 export function parseCookieHeader(header) {
-    const out = {};
     if (!header)
-        return out;
-    for (const part of header.split(";")) {
+        return {};
+    const seen = new Set();
+    const entries = header.split(";").flatMap((part) => {
         const eq = part.indexOf("=");
         if (eq === -1)
-            continue;
+            return [];
         const name = part.slice(0, eq).trim();
-        if (!name || name in out)
-            continue;
-        out[name] = part.slice(eq + 1).trim();
-    }
-    return out;
+        // First occurrence wins (RFC 6265 practice), so a repeat is dropped.
+        if (!name || seen.has(name))
+            return [];
+        seen.add(name);
+        return [[name, part.slice(eq + 1).trim()]];
+    });
+    return Object.fromEntries(entries);
 }

package/dist/sdk/dialog/remote/Messenger.d.ts

@@ -20,9 +20,4 @@ export declare function fromWindow(w: Window, options?: FromWindowOptions): Mess
  * dropped against an iframe that hasn't booted yet.
  */
 export declare function bridge(parameters: BridgeParameters): Bridge;
-/**
- * No-op bridge used in non-browser environments (SSR, tests, Node) where
- * `window` doesn't exist. All sends resolve to undefined and never deliver.
- * Lets the SDK be imported from anywhere without crashing on module load.
- */
 export declare function noop(): Bridge;

package/dist/sdk/dialog/remote/Messenger.js

@@ -6,22 +6,32 @@
  * object with a method on it would throw a DataCloneError at runtime.
  */
 function normalizeValue(value) {
-    if (Array.isArray(value))
+    /* The `as never`s below are all the same thing — this walks a value structurally and returns
+       a differently-shaped one (a stripped clone, or `undefined` for what cannot be cloned),
+       which a `<type> -> <type>` signature cannot express. */
+    if (Array.isArray(value)) {
+        // SAFETY: the walked copy replaces the array element-for-element.
         return value.map(normalizeValue);
-    if (typeof value === "function")
+    }
+    if (value instanceof Function) {
+        // SAFETY: a function cannot be structured-cloned, so it is dropped.
         return undefined;
-    if (typeof value !== "object" || value === null)
+    }
+    if (value === null || Object(value) !== value)
         return value;
     if (Object.getPrototypeOf(value) !== Object.prototype)
         try {
             return structuredClone(value);
         }
         catch {
+            // SAFETY: a value even structuredClone refuses is dropped.
             return undefined;
         }
     const normalized = {};
-    for (const [k, v] of Object.entries(value))
+    for (const [k, v] of Object.entries(Object(value))) {
+        // SAFETY: the walked value is a structured-clonable primitive or plain object.
         normalized[k] = normalizeValue(v);
+    }
     return normalized;
 }
 export function from(messenger) {
@@ -65,11 +75,15 @@ export function fromWindow(w, options = {}) {
         async send(topic, payload, target) {
             const id = crypto.randomUUID();
             w.postMessage(normalizeValue({ id, payload, topic }), target ?? targetOrigin ?? "*");
+            /* SAFETY: Bridge types `send`'s result from the topic's response map; the envelope this
+               transport resolves with is the request echo, which that map cannot name. */
             return { id, payload, topic };
         },
         async sendAsync(topic, payload, target) {
             const { id } = await this.send(topic, payload, target);
-            return new Promise((resolve) => this.on(topic, resolve, id));
+            return new Promise((resolve) => 
+            // SAFETY: `topic` is the same topic this method was called with.
+            this.on(topic, resolve, id));
         },
     });
 }
@@ -128,6 +142,10 @@ export function bridge(parameters) {
  * `window` doesn't exist. All sends resolve to undefined and never deliver.
  * Lets the SDK be imported from anywhere without crashing on module load.
  */
+/* Off-browser there is no peer to answer, so every send resolves to nothing while still
+   satisfying Bridge's per-topic response types. */
+// SAFETY: the no-op's contract — nothing is ever delivered or answered.
+const settle = () => Promise.resolve(undefined);
 export function noop() {
     return {
         destroy() { },
@@ -135,14 +153,8 @@ export function noop() {
             return () => { };
         },
         ready() { },
-        send() {
-            return Promise.resolve(undefined);
-        },
-        sendAsync() {
-            return Promise.resolve(undefined);
-        },
-        waitForReady() {
-            return Promise.resolve(undefined);
-        },
+        send: settle,
+        sendAsync: settle,
+        waitForReady: settle,
     };
 }

package/dist/sdk/driver-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Postgres driver errors are not typed by the driver, and the wrapper nests differently across
+ * postgres-js and PGlite. These read the fields we branch on without asserting a shape onto the
+ * error, and return "" / undefined when the field is absent.
+ */
+/** Reads a named string field off a driver error. */
+export declare function errField(cause: unknown, key: string): string;
+export declare function errCause(cause: unknown): object | undefined;

package/dist/sdk/driver-error.js

@@ -0,0 +1,17 @@
+/**
+ * Postgres driver errors are not typed by the driver, and the wrapper nests differently across
+ * postgres-js and PGlite. These read the fields we branch on without asserting a shape onto the
+ * error, and return "" / undefined when the field is absent.
+ */
+/** Reads a named string field off a driver error. */
+export function errField(cause, key) {
+    const value = Object.entries(Object(cause)).find(([k]) => k === key)?.[1];
+    return String(value) === value ? value : "";
+}
+/** The nested driver error, when the wrapper carries one. */
+/** `Object(x) === x` holds only for objects, so this tests without narrowing a representation. */
+const isObject = (cause) => Object(cause) === cause;
+export function errCause(cause) {
+    const value = Object.entries(Object(cause)).find(([k]) => k === "cause")?.[1];
+    return isObject(value) ? value : undefined;
+}