naro-js 0.7.1 → 0.9.0

package/README.md

@@ -10,7 +10,7 @@ npm install naro-js
 ```
 
 The backend is off until you turn it on, one project at a time: Turn on in
-the Backend card of the project's Database page, or `naro backend enable`.
+the Backend section of the project's Settings page, or `naro backend enable`.
 `naro backend status` prints the `url` and the anon key this client takes.
 `naro backend disable` turns it off again: in up to about 90 seconds every call
 answers `404 NOT_FOUND` ("There is no Naro backend at this host."). The data,
@@ -52,11 +52,11 @@ await naro.from("posts").delete().eq("id", 10);
   `NARO_ANON_KEY`), saved for all environments with `naro env add` and in
   `.env.local` for local development. Production and preview use the values
   you saved. Server code reads `NARO_URL` and `NARO_ANON_KEY`, so save those
-  two for production and preview as well. The service key, which naro never
+  two for production and preview as well. The service key, which Naro never
   sets, goes in `NARO_SERVICE_KEY`: save one for each environment, because a
   production service key saved for all environments is refused (401) by an
   environment's backend. A named environment of a project with a backend has a backend of
-  its own, and naro sets those names to its address and anon key, so the same
+  its own, and Naro sets those names to its address and anon key, so the same
   code calls the right backend everywhere — an address written into the code
   calls production's from every environment. On a custom domain, save
   `NEXT_PUBLIC_NARO_URL=https://<your domain>` for production.
@@ -83,6 +83,8 @@ await naro.from("posts").delete().eq("id", 10);
 - The session token lives in `localStorage` in a browser and in memory
   elsewhere. On a server, create one client per request, or pass
   `auth: { storage }` with your own `getItem` / `setItem` / `removeItem`.
+  To render pages as the signed-in user, keep it in cookies with
+  `naro-js/ssr` — see [Server rendering](#server-rendering).
 - Queries and Storage calls carry a short-lived access token (15 minutes)
   next to the session, which lasts days. The client renews it on its own
   before it expires, and once more if the backend refuses it — nothing to
@@ -91,7 +93,7 @@ await naro.from("posts").delete().eq("id", 10);
   and the client forgets both tokens: sign in again.
 - Types: `createClient<Database>()` with the `Database` that
   `naro gen types` writes — see [Types](#types).
-- Sign-in is naro Auth, the project's own (like Supabase Auth). Email and
+- Sign-in is Naro Auth, the project's own (like Supabase Auth). Email and
   password sign-up and sign-in need no setup: they work as soon as the
   backend is on. Resend is needed only to send confirmation and password
   reset emails.
@@ -241,6 +243,8 @@ const {
 
 // What came back: data.type is "oauth", "email_verification", "recovery"
 // or null, and a failure is the error (OAUTH_ACCESS_DENIED, TOKEN_EXPIRED…).
+// A reset link also names whose password it resets, masked: data.email is
+// "a***@example.com" — show it on the page.
 const { data, error } = await naro.auth.getSessionFromUrl();
 
 // The confirmation link only confirms the address. After you confirm, sign in.
@@ -256,8 +260,9 @@ await naro.auth.resendVerification(email, {
 await naro.auth.resetPasswordForEmail(email, {
   redirectTo: APP + "/auth/reset",
 });
-// On /auth/reset, after getSessionFromUrl() gave type "recovery" — within
-// 15 minutes, while nobody is signed in on this browser:
+// On /auth/reset, after getSessionFromUrl() gave type "recovery" (and the
+// page showed data.email) — within 15 minutes, while nobody is signed in
+// on this browser:
 await naro.auth.updateUser({ password: newPassword });
 ```
 
@@ -304,16 +309,25 @@ await naro.auth.updateUser({ password: newPassword });
   (`OAUTH_ACCOUNT_NOT_LINKED`) — confirming clears that password
   (`PASSWORD_RESET_REQUIRED`): set one with `resetPasswordForEmail`.
 - `updateUser({ password })` sets a new password in the recovery flow only
-  (`PASSWORD_RECOVERY_REQUIRED` otherwise, with no request). Like
-  supabase-js's recovery session, reading a reset link signs out whoever
-  was signed in on that browser, and `updateUser` acts on the link's
-  account: it uses the token only while nobody is signed in, for 15 minutes
-  after the link was opened, and `signIn`, `signUp`, `signInWithOAuth` and
-  `signOut` forget it — a link left open on a shared computer is not the
-  next person's to use. A reset ends every session of
-  the account and unlinks the Google or GitHub sign-ins made before it
-  (sign in with the provider again to link it back); sign in with the new
-  password afterwards.
+  (`PASSWORD_RECOVERY_REQUIRED` otherwise, with no request). Reading a reset
+  link asks the backend whose token it is — the URL's own words cannot be
+  trusted, since anyone holding a reset link of their own can send its
+  landing URL to someone else — and answers the account's address masked
+  (`data.email`, `a***@example.com`): show it, so the person sees whose
+  password they are about to set. A link for another account than the one
+  signed in on this browser is not used: the session stays, and
+  `getSessionFromUrl()` answers `RECOVERY_FOR_ANOTHER_USER` (with the
+  link's account in `details.email`). Otherwise, like supabase-js's recovery
+  session, the link signs out whoever was signed in on that browser, and
+  `updateUser` acts on the link's account: it uses the token only while
+  nobody is signed in, for 15 minutes after the link was opened, and
+  `signIn`, `signUp`, `signInWithOAuth` and `signOut` forget it — a link
+  left open on a shared computer is not the next person's to use. A token
+  the backend does not know (expired, spent, forged) is `INVALID_TOKEN` as
+  the link is read, and nothing is kept. A reset ends every session of the
+  account and unlinks the Google or GitHub sign-ins made before it (sign in
+  with the provider again to link it back); sign in with the new password
+  afterwards.
 - `resetPasswordForEmail` and `resendVerification` answer the same whether or
   not the address has an account.
 - With email verification required, `signUp` answers the user without a
@@ -325,6 +339,110 @@ await naro.auth.updateUser({ password: newPassword });
   `TIMEOUT` ("The Naro backend did not answer within 15 seconds. Check the
   network and try again."), and queries go out as anon — sign in again.
 
+## Server rendering
+
+`naro-js/ssr` keeps the session in your app's own cookies instead of
+`localStorage`, so a Server Component, a route handler, a server action or
+`proxy.ts` knows who is signed in — the place `@supabase/ssr` has. The
+backend still gets the anon key and a bearer token, never a cookie.
+
+```ts
+// lib/naro/client.ts — Client Components
+import { createBrowserClient } from "naro-js/ssr";
+
+export const naro = createBrowserClient<Database>({
+  url: process.env.NEXT_PUBLIC_NARO_URL!,
+  anonKey: process.env.NEXT_PUBLIC_NARO_ANON_KEY!,
+});
+```
+
+```ts
+// lib/naro/server.ts — Server Components, route handlers, server actions
+import { cookies } from "next/headers";
+import { createServerClient } from "naro-js/ssr";
+
+export async function naroServer() {
+  const cookieStore = await cookies();
+  return createServerClient<Database>({
+    url: process.env.NEXT_PUBLIC_NARO_URL!,
+    anonKey: process.env.NEXT_PUBLIC_NARO_ANON_KEY!,
+    cookies: {
+      getAll: () => cookieStore.getAll(),
+      setAll(cookies) {
+        try {
+          for (const { name, value, options } of cookies)
+            cookieStore.set(name, value, options);
+        } catch {
+          // A Server Component cannot write cookies: proxy.ts does.
+        }
+      },
+    },
+  });
+}
+
+// app/todos/page.tsx
+const naro = await naroServer();
+const { data: todos } = await naro.from("todos").select("id, title");
+```
+
+```ts
+// src/proxy.ts — keeps the access token in the cookies fresh
+import { NextResponse, type NextRequest } from "next/server";
+import { createServerClient } from "naro-js/ssr";
+
+export async function proxy(request: NextRequest) {
+  let response = NextResponse.next({ request });
+  const naro = createServerClient({
+    url: process.env.NEXT_PUBLIC_NARO_URL!,
+    anonKey: process.env.NEXT_PUBLIC_NARO_ANON_KEY!,
+    cookies: {
+      getAll: () => request.cookies.getAll(),
+      setAll(cookies) {
+        for (const { name, value } of cookies) request.cookies.set(name, value);
+        response = NextResponse.next({ request });
+        for (const { name, value, options } of cookies)
+          response.cookies.set(name, value, options);
+      },
+    },
+  });
+  await naro.auth.getUser();
+  return response;
+}
+```
+
+- Sign in, sign up and sign out in the browser with `createBrowserClient`,
+  or in a server action with `naroServer()`: both write the cookies. The
+  next request renders as that user.
+- `createBrowserClient` is one client per url and anon key on a page.
+  Where there is no page (a Client Component's server render) it keeps the
+  session in memory.
+- `createServerClient` is one client per request. It never reads a sign-in
+  from the page URL, and takes the anon key only: a `serviceKey` throws
+  ("naro-js/ssr keeps a signed-in user's session in cookies, so it takes the
+  anon key only. …"). Without `cookies.getAll` it throws too.
+- The access token lasts 15 minutes. A Server Component that finds it about
+  to expire gets a new one for that request, but cannot write it back;
+  `getUser()` in `proxy.ts` writes it to the response, so the pages behind
+  it do not renew on every render. `getSession()` and `getUser()` renew it
+  within a minute of its expiry on every client.
+- Google and GitHub sign-in come back to the page with the code in the URL
+  fragment, which never reaches the server: the browser client trades it
+  and writes the cookies, so the page they come back to renders signed out
+  once. Send them back to a client page (`redirectTo`) and refresh from
+  there (`router.refresh()`).
+- One cookie per key, named for the backend's host:
+  `naro-auth-token.<host>` (the session), `naro-auth-jwt.<host>` (the access
+  token), and while a sign-in or reset link is under way
+  `naro-auth-code-verifiers.<host>` and `naro-auth-recovery.<host>`. They are
+  `Path=/`, `SameSite=Lax`, `Max-Age` 400 days (the session ends on the
+  backend, which then clears them), and `Secure` on https pages and from the
+  server. They are not `HttpOnly`: your page's JavaScript reads them, as it
+  reads `localStorage` — the same exposure to an injected script.
+- `cookieOptions: { domain, path, sameSite, secure, maxAge }` changes them,
+  on both clients — `domain: "example.com"` to share the session with
+  subdomains, `secure: false` for a browser that refuses `Secure` cookies
+  from `http://localhost`.
+
 ## Types
 
 Generate the types from the project's schema, and hand them to
@@ -748,6 +866,8 @@ await naro.removeChannel(room);
   policies, so that table needs one too, or every private join is refused.
   Declare a type (`TEXT`, `INTEGER`, `REAL`) on every column a select policy
   reads.
+- `.on("broadcast", { event: "*" }, …)` hears every broadcast event on the
+  channel (0.9.0 and later); a listener with a name hears that event only.
 - Nothing that changed while the connection was away comes again: read again
   when the channel says `SUBSCRIBED`. `BULK_CHANGE` (one request changed over
   1,000 rows or 8 MiB) and `EVENTS_DROPPED` reach `.on("system", {}, …)` with
@@ -853,18 +973,27 @@ await naro.removeChannel(room);
   (`This connection sent messages faster than a connection may.`) with
   `lost: true`: sent again, such a message may arrive twice. Keep such sends
   to 10 a second for all of a client's channels together.
-- Unlike supabase-js: broadcast and presence listeners match one event name
-  exactly, case included — `{ event: "*" }` hears nothing; `DELETE` events
+- Unlike supabase-js: a broadcast listener with a name and every presence
+  listener match that event name exactly, case included — presence has no
+  `*`, while broadcast's `{ event: "*" }` hears every event, as in
+  supabase-js (0.9.0 and later); `DELETE` events
   pass the select policies too; a subscription takes one filter (`eq`, `neq`,
-  `lt`, `lte`, `gt`, `gte`, `in`); settings naro does not take
+  `lt`, `lte`, `gt`, `gte`, `in`); settings Naro does not take
   (`broadcast.replay`) are refused with `INVALID_CHANNEL_CONFIG`; `send()` and
   the rest answer `{ data, error }` (`send()`, `track()` and `untrack()` with
   `lost` too), not `'ok' | 'timed out' | 'error'`.
 - The service key receives every change of a published table, whatever the
   policies say: keep it on your server (`createClient` refuses it in a
-  browser). A server that writes with `env.DB` broadcasts with
-  `POST /_naro/v1/realtime/broadcast` and the API key: up to 100 messages and
-  1 MiB, all sent or none (202).
+  browser). On a server it goes in the `apikey` header of the connection,
+  never in its URL, where edge and worker logs would keep it: Node 22 or
+  later, Bun and `ws` take `{ headers }` on the WebSocket constructor, and
+  on Cloudflare Workers the connection is opened with `fetch` and
+  `Upgrade: websocket`. Deno's own WebSocket cannot send headers: there the
+  connection is refused (`WEBSOCKET_HEADERS_UNAVAILABLE`) until you pass
+  `ws` (`npm:ws`) as `realtime.WebSocket`. The anon key stays in the URL,
+  which a browser's WebSocket needs. A server that writes with `env.DB`
+  broadcasts with `POST /_naro/v1/realtime/broadcast` and the API key: up to
+  100 messages and 1 MiB, all sent or none (202).
 - `createClient({ realtime: { WebSocket, heartbeatIntervalMs, timeoutMs } })`
   — a heartbeat every 25,000 ms and answers within 10,000 ms by default, each
   in whole milliseconds from 1 to 2,147,483,647 (the longest a timer waits).

package/dist/auth/client.d.ts

@@ -101,11 +101,12 @@ export declare class AuthClient {
      * "(P1-2 리뷰 반영)".)
      *
      * Like supabase-js, it acts on the recovery link's account, which took the
-     * place of any signed-in session when the link was read — so the token is
-     * used only while no session is signed in on this browser, for 15 minutes
-     * after the link was opened, and never after a sign-in, sign-up or
-     * sign-out forgot it (PR #68 review 6). Otherwise PASSWORD_RECOVERY_REQUIRED,
-     * with no request.
+     * place of any signed-in session when the link was read (a link for
+     * another account than the signed-in one is not read, `#recoveryAnswer`)
+     * — so the token is used only while no session is signed in on this
+     * browser, for 15 minutes after the link was opened, and never after a
+     * sign-in, sign-up or sign-out forgot it (PR #68 review 6). Otherwise
+     * PASSWORD_RECOVERY_REQUIRED, with no request.
      */
     updateUser(attributes: UserAttributes): Promise<AuthActionResponse>;
     /**

package/dist/errors.d.ts

@@ -44,6 +44,13 @@ export declare function invalidSession(): NaroError;
 export declare function codeVerifierMissing(): NaroError;
 /** `updateUser({ password })` with no reset link opened. */
 export declare function passwordRecoveryRequired(): NaroError;
+/**
+ * A reset link for one account read on a browser signed in as another
+ * (security audit 2026-11-14 F6): the link is not used and the session is
+ * kept, so a password typed here cannot land on an account the sender
+ * holds. `details.email` is the link's account, masked.
+ */
+export declare function recoveryForAnotherUser(email: string | null): NaroError;
 /** `signInWithOAuth` with a provider the worker does not know. */
 export declare function invalidProvider(): NaroError;
 /**
@@ -58,6 +65,13 @@ export declare function cryptoUnavailable(): NaroError;
 export declare const SERVICE_KEY_OFF_SERVER_MESSAGE = "A Naro service key (naro_sk_\u2026) skips every policy, so createClient accepts it only on a server (Node, Deno, Bun, Cloudflare Workers, an edge runtime), never in a browser, a web worker or a React Native app. Use the anon key (naro_pk_\u2026) here and keep the service key on your server.";
 /** No WebSocket in this runtime, and none passed to createClient. */
 export declare function websocketUnavailable(): NaroError;
+/**
+ * The service key goes in the `apikey` header of the Realtime connection
+ * (security audit 2026-11-14 F7), which the runtime's own WebSocket cannot
+ * send — Deno's — and no WebSocket that can was passed. The key is never
+ * put in the URL instead.
+ */
+export declare function websocketHeadersUnavailable(): NaroError;
 /**
  * The server did not answer a join, a request or the opening in `ms`. Whole
  * seconds, never fewer than one: a `timeoutMs` under 500 must not read

package/dist/http.d.ts

@@ -50,6 +50,15 @@ export declare const ACCESS_JWT_MARGIN_MS = 60000;
  * INVALID_SESSION, if it comes, renews it (`call`, `send`).
  */
 export declare function expiryOf(jwt: string): number | null;
+/**
+ * Renews the stored access JWT when it is within `ACCESS_JWT_MARGIN_MS` of
+ * its `exp` (naro-js/ssr design 2026-11-04 decision 11): `getSession` calls
+ * it, so a server's proxy.ts gets a fresh JWT into the response cookies with
+ * one `getUser()`. A missing or unreadable JWT is left for the next query to
+ * mint; the service key and a client on an `accessToken` renew nothing.
+ * Never fails: a renewal that does not work leaves things as they were.
+ */
+export declare function freshAccessJwt(config: HttpConfig): Promise<void>;
 export type CallOptions = {
     method: "GET" | "POST" | "PUT" | "DELETE";
     /** Below `/_naro/v1`, e.g. `/data/query`. */

package/dist/index.js

@@ -49,6 +49,13 @@ function passwordRecoveryRequired() {
     message: "updateUser({ password }) works in the password recovery flow: open the link resetPasswordForEmail sent, then call it on that page."
   };
 }
+function recoveryForAnotherUser(email) {
+  return {
+    code: "RECOVERY_FOR_ANOTHER_USER",
+    message: "This password reset link is for another account than the one signed in on this browser, so it was not used. To reset that account's password, sign out first. If you did not ask for it, ignore it.",
+    details: { email }
+  };
+}
 function invalidProvider() {
   return {
     code: "VALIDATION_ERROR",
@@ -74,6 +81,12 @@ function websocketUnavailable() {
     message: "This runtime has no WebSocket. Pass one to createClient({ realtime: { WebSocket } })."
   };
 }
+function websocketHeadersUnavailable() {
+  return {
+    code: "WEBSOCKET_HEADERS_UNAVAILABLE",
+    message: "The service key goes in the apikey header of the realtime connection, which this runtime's WebSocket cannot send. Pass one that takes { headers } \u2014 ws (npm:ws) \u2014 as createClient({ realtime: { WebSocket } })."
+  };
+}
 function realtimeTimedOut(ms) {
   const seconds = Math.max(1, Math.round(ms / 1e3));
   return {
@@ -308,6 +321,15 @@ async function accessJwtFor(config, jwtStore) {
   }
   return { error: invalidSession() };
 }
+async function freshAccessJwt(config) {
+  const jwtStore = config.accessJwt;
+  if (jwtStore === void 0 || config.service) return;
+  const jwt = await jwtStore.get();
+  if (jwt === null) return;
+  const expiry = localExpiry(config, jwt);
+  if (expiry === null || expiry - ACCESS_JWT_MARGIN_MS > Date.now()) return;
+  await accessJwtFor(config, jwtStore);
+}
 async function bearerFor(config, path, withToken) {
   if (!withToken) return { token: null, session: null };
   const store = storeFor(config, path);
@@ -742,8 +764,11 @@ function isBrowser(scope = globalThis) {
   const g = scope;
   return g.window !== void 0 && g.document !== void 0;
 }
-function isWorkerd(g) {
-  return g.navigator?.userAgent === "Cloudflare-Workers";
+function isWorkerd(scope = globalThis) {
+  return scope.navigator?.userAgent === "Cloudflare-Workers";
+}
+function isDeno(scope = globalThis) {
+  return typeof scope.Deno?.version?.deno === "string";
 }
 function hasServerSignal(g) {
   return isWorkerd(g) || // Vercel's edge runtime and Next.js's edge (middleware, edge routes).
@@ -1127,12 +1152,8 @@ var AuthClient = class {
         await this.#flow.verifiers.take(fragment.naro_flow);
       return { data: none, error: flowError(type, fragment.naro_error) };
     }
-    if (type === "recovery" && fragment.naro_token) {
-      await this.#http.tokens.clear();
-      await this.#http.accessJwt?.clear();
-      await this.#flow.recovery.keep(fragment.naro_token);
-      return { data: none, error: null };
-    }
+    if (type === "recovery" && fragment.naro_token)
+      return this.#recoveryAnswer(none, fragment.naro_token);
     if (fragment.naro_code) {
       const traded = await this.exchangeCodeForSession(
         fragment.naro_code,
@@ -1142,6 +1163,45 @@ var AuthClient = class {
     }
     return { data: none, error: null };
   }
+  /**
+   * A reset link's token, read on the page it opened (security audit
+   * 2026-11-14 F6). The fragment is whoever sent the link's to write — one
+   * who holds a reset token of their own account can send the landing URL
+   * itself — so the worker is asked whose token it is: the answer names the
+   * account (masked, `data.email`, for the page to show) and whether it is
+   * the one signed in here.
+   *
+   * Signed in as another account, the link is not used: the session stays,
+   * the token is not kept, and the answer is RECOVERY_FOR_ANOTHER_USER — a
+   * password typed here cannot land on the sender's account. Otherwise,
+   * like supabase-js's recovery session, the link takes the place of
+   * whoever was signed in on this browser (the reset ends every session of
+   * that account anyway, PR #68 review 6): `updateUser` then acts on the
+   * link's account alone. A token the worker does not know is INVALID_TOKEN
+   * here, and nothing is kept.
+   */
+  async #recoveryAnswer(none, token) {
+    const result = await call(this.#http, {
+      method: "POST",
+      path: "/auth/recovery-owner",
+      body: { token },
+      withToken: true,
+      // The page's queries wait on this; they must not wait forever.
+      timeoutMs: EXCHANGE_TIMEOUT_MS
+    });
+    if (result.error !== null) return { data: none, error: result.error };
+    const { body } = result.answer;
+    const owner = isRecord(body) && isRecord(body.data) ? body.data : null;
+    if (owner === null)
+      return { data: none, error: invalidResponse(result.answer.status) };
+    const email = typeof owner.email === "string" ? owner.email : null;
+    if (owner.self === false)
+      return { data: none, error: recoveryForAnotherUser(email) };
+    await this.#http.tokens.clear();
+    await this.#http.accessJwt?.clear();
+    await this.#flow.recovery.keep(token);
+    return { data: { ...none, email }, error: null };
+  }
   /**
    * Emails a password reset link, when the address has an account. The
    * answer is the same either way — it does not say whether it had one.
@@ -1165,11 +1225,12 @@ var AuthClient = class {
    * "(P1-2 리뷰 반영)".)
    *
    * Like supabase-js, it acts on the recovery link's account, which took the
-   * place of any signed-in session when the link was read — so the token is
-   * used only while no session is signed in on this browser, for 15 minutes
-   * after the link was opened, and never after a sign-in, sign-up or
-   * sign-out forgot it (PR #68 review 6). Otherwise PASSWORD_RECOVERY_REQUIRED,
-   * with no request.
+   * place of any signed-in session when the link was read (a link for
+   * another account than the signed-in one is not read, `#recoveryAnswer`)
+   * — so the token is used only while no session is signed in on this
+   * browser, for 15 minutes after the link was opened, and never after a
+   * sign-in, sign-up or sign-out forgot it (PR #68 review 6). Otherwise
+   * PASSWORD_RECOVERY_REQUIRED, with no request.
    */
   async updateUser(attributes) {
     await this.#pendingUrl();
@@ -1254,6 +1315,7 @@ var AuthClient = class {
     const renewed = tokenFrom(result.answer);
     if (renewed !== null && token !== null && renewed !== token)
       await tokens.replaceIf(token, renewed);
+    await freshAccessJwt(this.#http);
     return { data: { session: body.session, user }, error: null };
   }
   /** `{ data: { user } }`; `user` is null when signed out. */
@@ -2891,9 +2953,79 @@ function channelNameProblem(name) {
 function socketUrl(baseUrl, apiKey) {
   const url = new URL("/_naro/v1/realtime/websocket", baseUrl);
   url.protocol = url.protocol === "http:" ? "ws:" : "wss:";
-  return `${url.href}?apikey=${encodeURIComponent(apiKey)}&vsn=${REALTIME_PROTOCOL_VERSION}`;
+  const key = apiKey === null ? "" : `apikey=${encodeURIComponent(apiKey)}&`;
+  return `${url.href}?${key}vsn=${REALTIME_PROTOCOL_VERSION}`;
 }
 
+// src/realtime/upgrade-socket.ts
+var UpgradeSocket = class {
+  onopen = null;
+  onmessage = null;
+  onclose = null;
+  onerror = null;
+  #ws = null;
+  /** `close()` was called, or the open failed: no event goes out after. */
+  #closed = null;
+  constructor(fetchLike, url, headers) {
+    let pending;
+    try {
+      pending = fetchLike(url, {
+        headers: { Upgrade: "websocket", ...headers }
+      });
+    } catch {
+      pending = Promise.reject(new Error("fetch threw"));
+    }
+    pending.then(
+      (response) => this.#arrived(response),
+      () => this.#failed()
+    );
+  }
+  #arrived(response) {
+    const ws = response.webSocket ?? null;
+    if (ws === null) {
+      void response.body?.cancel?.().catch(() => void 0);
+      this.#failed();
+      return;
+    }
+    if (this.#closed !== null) {
+      try {
+        ws.accept();
+        ws.close(this.#closed.code, this.#closed.reason);
+      } catch {
+      }
+      return;
+    }
+    this.#ws = ws;
+    ws.addEventListener("message", (event) => {
+      this.onmessage?.({ data: event.data });
+    });
+    ws.addEventListener("close", (event) => {
+      this.onclose?.({ code: event.code, reason: event.reason ?? "" });
+    });
+    ws.addEventListener("error", () => {
+      this.onerror?.();
+    });
+    ws.accept();
+    this.onopen?.();
+  }
+  /** No connection came of it: a close before the open. */
+  #failed() {
+    if (this.#closed !== null) return;
+    this.#closed = { code: void 0, reason: void 0 };
+    this.onclose?.({ code: 1006, reason: "" });
+  }
+  send(data) {
+    if (this.#ws === null)
+      throw new Error("The realtime connection is not open.");
+    this.#ws.send(data);
+  }
+  close(code, reason) {
+    if (this.#closed !== null) return;
+    this.#closed = { code, reason };
+    this.#ws?.close(code, reason);
+  }
+};
+
 // src/realtime/socket.ts
 var HEARTBEAT_MS = 25e3;
 var TIMEOUT_MS = 1e4;
@@ -3308,19 +3440,19 @@ var RealtimeSocket = class {
     }, this.#timeoutMs);
   }
   #open() {
-    const Impl = this.#config.options.WebSocket ?? globalThis.WebSocket;
+    const passed = this.#config.options.WebSocket;
+    const runtimes = globalThis.WebSocket;
+    const Impl = passed ?? runtimes;
     if (typeof Impl !== "function")
       return this.#stop(websocketUnavailable(), true);
     if (this.#config.service && !isKnownServer())
       return this.#stop(serviceKeyOffServer(), true);
-    let ws;
-    try {
-      ws = new Impl(
-        socketUrl(this.#config.baseUrl, this.#config.apiKey)
-      );
-    } catch (error) {
-      return this.#stop(socketRefused(error), true);
-    }
+    const made = this.#config.service ? this.#serviceSocket(
+      Impl,
+      passed === void 0 || passed === runtimes
+    ) : this.#anonSocket(Impl);
+    if ("error" in made) return this.#stop(made.error, true);
+    const ws = made.ws;
     this.#generation += 1;
     this.#ws = ws;
     this.#state = "connecting";
@@ -3335,6 +3467,48 @@ var RealtimeSocket = class {
       this.#timeoutMs
     );
   }
+  /**
+   * The anon key's connection: the one place a key goes into a URL (design
+   * §10 "3-2d") — a browser's WebSocket has no headers to put it in.
+   */
+  #anonSocket(Impl) {
+    try {
+      return {
+        ws: new Impl(socketUrl(this.#config.baseUrl, this.#config.apiKey))
+      };
+    } catch (error) {
+      return { error: socketRefused(error) };
+    }
+  }
+  /**
+   * The service key's connection (security audit 2026-11-14 F7): the key in
+   * the `apikey` header and never in the URL, where edge and worker logs
+   * would keep it. Node 22+, Bun and `ws` take `{ headers }` on the
+   * constructor; workerd's constructor takes none, so there — unless the
+   * app passed a WebSocket of its own, other than the runtime's — the
+   * connection is a `fetch` upgrade (`UpgradeSocket`); Deno's takes none
+   * either, and has no upgrade fetch, so the service key is refused there
+   * until a WebSocket that takes headers (`ws`) is passed. `runtimes` says
+   * the class is the runtime's own.
+   */
+  #serviceSocket(Impl, runtimes) {
+    const headers = { apikey: this.#config.apiKey };
+    const url = socketUrl(this.#config.baseUrl, null);
+    if (runtimes && isWorkerd())
+      return {
+        ws: new UpgradeSocket(
+          this.#config.fetch ?? globalThis.fetch,
+          `http${url.slice(2)}`,
+          headers
+        )
+      };
+    if (runtimes && isDeno()) return { error: websocketHeadersUnavailable() };
+    try {
+      return { ws: new Impl(url, { headers }) };
+    } catch (error) {
+      return { error: socketRefused(error) };
+    }
+  }
   #opened(ws) {
     if (this.#ws !== ws || this.#state !== "connecting") return;
     clearTimeout(this.#openTimer);
@@ -4083,7 +4257,7 @@ var RealtimeChannel = class {
       payload: isRecord(payload.payload) ? payload.payload : {}
     };
     for (const binding of this.#bindings)
-      if (binding.type === "broadcast" && binding.event === event)
+      if (binding.type === "broadcast" && (binding.event === event || binding.event === "*"))
         safely(() => binding.callback(message));
   }
   #system(payload) {
@@ -4524,6 +4698,7 @@ var RealtimeClient = class {
       apiKey: http.apiKey,
       service,
       options,
+      fetch: http.fetch,
       events: {
         // Not awaited, and not live yet: onLive says when the hub took it.
         opened: () => {

package/dist/realtime/protocol.d.ts

@@ -72,7 +72,9 @@ export declare function clientFrame(topic: string, event: string, payload: Recor
 export declare function channelNameProblem(name: string): string | undefined;
 /**
  * The connection's URL (original spec §6.3): a browser's WebSocket cannot
- * send headers, so the key rides in the query, encoded. Nothing logs it;
- * an error never quotes it (socket.ts).
+ * send headers, so the anon key rides in the query, encoded. Nothing logs
+ * it; an error never quotes it (socket.ts). With `apiKey` null the URL
+ * carries no key: the service key goes in the `apikey` header instead
+ * (security audit 2026-11-14 F7), where edge and worker logs do not keep it.
  */
-export declare function socketUrl(baseUrl: string, apiKey: string): string;
+export declare function socketUrl(baseUrl: string, apiKey: string | null): string;

package/dist/realtime/socket.d.ts

@@ -1,4 +1,5 @@
 import { type NaroError } from "../errors.js";
+import type { FetchLike } from "../http.js";
 import { type ServerFrame } from "./protocol.js";
 import type { RealtimeOptions } from "./types.js";
 export type Reply = {
@@ -27,6 +28,11 @@ export type SocketConfig = {
     service: boolean;
     options: RealtimeOptions;
     events: SocketEvents;
+    /**
+     * The client's `fetch`, for the service key's connection on workerd
+     * (`UpgradeSocket`); the runtime's when none was passed to createClient.
+     */
+    fetch?: FetchLike | undefined;
 };
 /**
  * Whose frame a request is, which sets its turn (`request()`): the app's

package/dist/realtime/types.d.ts

@@ -80,7 +80,13 @@ export type RealtimePresenceLeavePayload = {
     /** What the key holds after this leave; [] when it was the last. */
     currentPresences: RealtimePresenceEntry[];
 };
-/** The global WebSocket, or `ws`'s: any class built from a URL. */
+/**
+ * The global WebSocket, or `ws`'s: any class built from a URL. On a server
+ * the service key's connection is built from the URL and a second argument,
+ * `{ headers }` (security audit 2026-11-14 F7), which Node's, Bun's and
+ * `ws`'s constructors take; the type names the first argument only, so a
+ * browser's `WebSocket` (typed with `protocols` second) still fits.
+ */
 export type WebSocketConstructor = new (url: string) => unknown;
 export type RealtimeOptions = {
     WebSocket?: WebSocketConstructor;

package/dist/realtime/upgrade-socket.d.ts

@@ -0,0 +1,19 @@
+import type { FetchLike } from "../http.js";
+type MessageEvent = {
+    data: unknown;
+};
+type CloseEvent = {
+    code: number;
+    reason?: string;
+};
+export declare class UpgradeSocket {
+    #private;
+    onopen: (() => void) | null;
+    onmessage: ((event: MessageEvent) => void) | null;
+    onclose: ((event: CloseEvent) => void) | null;
+    onerror: (() => void) | null;
+    constructor(fetchLike: FetchLike, url: string, headers: Record<string, string>);
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+}
+export {};

package/dist/runtime.d.ts

@@ -4,6 +4,20 @@
  * service key is allowed is `isKnownServer`'s question, which is stricter.
  */
 export declare function isBrowser(scope?: object): boolean;
+/**
+ * workerd sends this user agent whatever the compatibility date or flags
+ * (measured on workerd 1.20260815 at 2023-01-01 and 2026-08-19, with and
+ * without nodejs_compat). Its global scope is a ServiceWorkerGlobalScope, so
+ * the worker-scope signals below must not count against it.
+ */
+export declare function isWorkerd(scope?: object): boolean;
+/**
+ * Deno, whose own WebSocket takes no headers (the service key's `apikey`
+ * header on a Realtime connection, security audit 2026-11-14 F7): there the
+ * SDK asks for a WebSocket that does (`ws`) instead of putting the key in
+ * the URL.
+ */
+export declare function isDeno(scope?: object): boolean;
 /**
  * Whether a service key may be used here (spec §7): only where the runtime
  * says it is a server and nothing says it is a user's device. Anything else —

package/dist/ssr/cookies.d.ts

@@ -0,0 +1,54 @@
+/** What an app may change about the cookies. */
+export type CookieOptions = {
+    domain?: string;
+    path?: string;
+    sameSite?: "lax" | "strict" | "none";
+    secure?: boolean;
+    /** Seconds. */
+    maxAge?: number;
+};
+export type ResolvedCookieOptions = {
+    domain?: string;
+    path: string;
+    sameSite: "lax" | "strict" | "none";
+    secure: boolean;
+    maxAge: number;
+};
+/**
+ * 400 days, the most a browser keeps a cookie. Longer than the session's 7
+ * days on purpose (decision 6): the session slides while it is used but its
+ * token does not change, so the cookie is never written again — a 7-day
+ * cookie would outlive nothing. A session that ends is cleared by
+ * INVALID_SESSION instead.
+ */
+export declare const COOKIE_MAX_AGE = 34560000;
+/**
+ * `naro-auth-token:https://abc.naro.sh` → `naro-auth-token.abc.naro.sh`: a
+ * cookie name holds no `:` or `/`. What else the host has (a port's `:`)
+ * becomes `_`; a key without a `:` is made safe the same way.
+ */
+export declare function cookieName(key: string): string;
+/**
+ * `base64-` and the value's UTF-8 as base64url, as `@supabase/ssr` writes:
+ * a session token's signature has `+`, `/` and `=`, and a verifier list is
+ * JSON. Next's `cookies().set()` encodes a value into `Set-Cookie`, which the
+ * browser's `document.cookie` hands back as it is — so a value that any
+ * layer would encode again comes back changed. base64url is left alone by
+ * all of them.
+ */
+export declare function encodeValue(value: string): string;
+/**
+ * The value `encodeValue` wrote; one without the prefix as it is. Null for
+ * one that does not decode — it is read as no cookie.
+ */
+export declare function decodeValue(value: string): string | null;
+export declare function resolveCookieOptions(options: CookieOptions | undefined, secure: boolean): ResolvedCookieOptions;
+/** A `document.cookie` line; `value` is already encoded. */
+export declare function serializeCookie(name: string, value: string, options: ResolvedCookieOptions): string;
+/** `a=1; b=2` as pairs, in order; what is not a pair is skipped. */
+export declare function parseCookies(header: string): {
+    name: string;
+    value: string;
+}[];
+/** One warning per cookie name (decision 7): it is written all the same. */
+export declare function warnIfLarge(name: string, value: string): void;

package/dist/ssr/storage.d.ts

@@ -0,0 +1,37 @@
+import type { AuthStorage } from "../auth/storage.js";
+import { type ResolvedCookieOptions } from "./cookies.js";
+export type CookieToSet = {
+    name: string;
+    /** Encoded; "" when the cookie is removed. */
+    value: string;
+    /** `maxAge` 0 removes it. */
+    options: ResolvedCookieOptions;
+};
+export type CookieMethods = {
+    /** The request's cookies — `cookieStore.getAll()`, `request.cookies.getAll()`. */
+    getAll(): {
+        name: string;
+        value: string;
+    }[] | Promise<{
+        name: string;
+        value: string;
+    }[]>;
+    /**
+     * Writes them to the response. Left out, or throwing (a Server Component
+     * cannot write cookies), the client keeps them for this request only.
+     */
+    setAll?(cookies: CookieToSet[]): void | Promise<void>;
+};
+/** What of `document` the browser storage uses. */
+type CookieDocument = {
+    cookie: string;
+};
+/** `document.cookie`, read again on every get: another tab's sign-in shows. */
+export declare function browserCookieStorage(options: ResolvedCookieOptions, doc: CookieDocument): AuthStorage;
+/**
+ * The request's cookies, read once, under what this client wrote since
+ * (decision 10): a JWT renewed in a Server Component, whose `setAll`
+ * throws, is still the one the next query of the request sends.
+ */
+export declare function serverCookieStorage(methods: CookieMethods, options: ResolvedCookieOptions): AuthStorage;
+export {};

package/dist/ssr.d.ts

@@ -0,0 +1,39 @@
+import { type DatabaseShape, type FetchLike, type NaroClient, type RealtimeOptions, type UntypedDatabase } from "./index.js";
+import { type CookieOptions } from "./ssr/cookies.js";
+import { type CookieMethods } from "./ssr/storage.js";
+export type { CookieOptions } from "./ssr/cookies.js";
+export type { CookieMethods, CookieToSet } from "./ssr/storage.js";
+/** User-facing; the design's §4.1. */
+export declare const SSR_MESSAGES: {
+    readonly serviceKey: "naro-js/ssr keeps a signed-in user's session in cookies, so it takes the anon key only. Make the service key's client with naro-js's createClient({ url, serviceKey }), on your server.";
+    readonly getAll: "createServerClient needs cookies.getAll: a function that returns the request's cookies, e.g. () => cookieStore.getAll().";
+};
+type SsrKeys = {
+    url: string;
+    anonKey: string;
+    serviceKey?: undefined;
+};
+export type BrowserClientOptions = SsrKeys & {
+    cookieOptions?: CookieOptions;
+    fetch?: FetchLike;
+    realtime?: RealtimeOptions;
+};
+export type ServerClientOptions = SsrKeys & {
+    cookies: CookieMethods;
+    cookieOptions?: CookieOptions;
+    fetch?: FetchLike;
+};
+/**
+ * The client for the browser: `createClient` with its session in
+ * `document.cookie`. On a page, the same url and key give the same client.
+ * Where there is no page (a Client Component's server render) it keeps the
+ * session in memory and is new each time.
+ */
+export declare function createBrowserClient<Database extends DatabaseShape<Database> = UntypedDatabase>(options: BrowserClientOptions): NaroClient<Database>;
+/**
+ * The client for a request on the server — a Server Component, a route
+ * handler, a server action or proxy.ts: its session is the request's
+ * cookies, and what it writes goes to `cookies.setAll`. Make one per
+ * request. It never reads a session from a URL.
+ */
+export declare function createServerClient<Database extends DatabaseShape<Database> = UntypedDatabase>(options: ServerClientOptions): NaroClient<Database>;

package/dist/ssr.js

@@ -0,0 +1,205 @@
+// src/ssr.ts
+import {
+  createClient
+} from "./index.js";
+
+// src/runtime.ts
+function isBrowser(scope = globalThis) {
+  const g = scope;
+  return g.window !== void 0 && g.document !== void 0;
+}
+
+// src/ssr/cookies.ts
+var COOKIE_MAX_AGE = 3456e4;
+var LARGE_COOKIE_BYTES = 4e3;
+function cookieName(key) {
+  const colon = key.indexOf(":");
+  if (colon === -1) return safe(key);
+  const prefix = key.slice(0, colon);
+  const rest = key.slice(colon + 1);
+  let host = rest;
+  try {
+    host = new URL(rest).host;
+  } catch {
+  }
+  return `${safe(prefix)}.${safe(host)}`;
+}
+function safe(text) {
+  return text.replace(/[^A-Za-z0-9.-]/g, "_");
+}
+var BASE64_PREFIX = "base64-";
+function encodeValue(value) {
+  let binary = "";
+  for (const byte of new TextEncoder().encode(value))
+    binary += String.fromCharCode(byte);
+  return BASE64_PREFIX + btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function decodeValue(value) {
+  if (!value.startsWith(BASE64_PREFIX)) return value;
+  const base64 = value.slice(BASE64_PREFIX.length).replace(/-/g, "+").replace(/_/g, "/");
+  try {
+    const binary = atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, "="));
+    const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    return null;
+  }
+}
+function resolveCookieOptions(options, secure) {
+  return {
+    ...options?.domain !== void 0 ? { domain: options.domain } : {},
+    path: options?.path ?? "/",
+    sameSite: options?.sameSite ?? "lax",
+    secure: options?.secure ?? secure,
+    maxAge: options?.maxAge ?? COOKIE_MAX_AGE
+  };
+}
+var SAME_SITE = { lax: "Lax", strict: "Strict", none: "None" };
+function serializeCookie(name, value, options) {
+  const parts = [
+    `${name}=${value}`,
+    `Max-Age=${options.maxAge}`,
+    `Path=${options.path}`
+  ];
+  if (options.domain !== void 0) parts.push(`Domain=${options.domain}`);
+  parts.push(`SameSite=${SAME_SITE[options.sameSite]}`);
+  if (options.secure) parts.push("Secure");
+  return parts.join("; ");
+}
+function parseCookies(header) {
+  const pairs = [];
+  for (const part of header.split(";")) {
+    const at = part.indexOf("=");
+    if (at <= 0) continue;
+    const name = part.slice(0, at).trim();
+    if (name === "") continue;
+    pairs.push({ name, value: part.slice(at + 1).trim() });
+  }
+  return pairs;
+}
+var warned = /* @__PURE__ */ new Set();
+function warnIfLarge(name, value) {
+  const bytes = new TextEncoder().encode(`${name}=${value}`).length;
+  if (bytes <= LARGE_COOKIE_BYTES || warned.has(name)) return;
+  warned.add(name);
+  console.warn(
+    `naro-js/ssr: the cookie ${name} is ${bytes} bytes. Browsers drop a cookie past 4096 bytes, and the session then lives only until the page closes.`
+  );
+}
+
+// src/ssr/storage.ts
+function browserCookieStorage(options, doc) {
+  return {
+    getItem(key) {
+      const name = cookieName(key);
+      const found = parseCookies(doc.cookie).find((c) => c.name === name);
+      return found === void 0 ? null : decodeValue(found.value);
+    },
+    setItem(key, value) {
+      const name = cookieName(key);
+      const encoded = encodeValue(value);
+      warnIfLarge(name, encoded);
+      doc.cookie = serializeCookie(name, encoded, options);
+    },
+    removeItem(key) {
+      doc.cookie = serializeCookie(cookieName(key), "", {
+        ...options,
+        maxAge: 0
+      });
+    }
+  };
+}
+function serverCookieStorage(methods, options) {
+  let request;
+  const written = /* @__PURE__ */ new Map();
+  const read = () => {
+    request ??= (async () => {
+      const cookies = /* @__PURE__ */ new Map();
+      for (const { name, value } of await methods.getAll())
+        if (!cookies.has(name)) cookies.set(name, value);
+      return cookies;
+    })();
+    return request;
+  };
+  const send = async (cookie) => {
+    try {
+      await methods.setAll?.([cookie]);
+    } catch {
+    }
+  };
+  return {
+    async getItem(key) {
+      const name = cookieName(key);
+      if (written.has(name)) return written.get(name) ?? null;
+      const value = (await read()).get(name);
+      return value === void 0 ? null : decodeValue(value);
+    },
+    async setItem(key, value) {
+      const name = cookieName(key);
+      written.set(name, value);
+      const encoded = encodeValue(value);
+      warnIfLarge(name, encoded);
+      await send({ name, value: encoded, options });
+    },
+    async removeItem(key) {
+      const name = cookieName(key);
+      written.set(name, null);
+      await send({ name, value: "", options: { ...options, maxAge: 0 } });
+    }
+  };
+}
+
+// src/ssr.ts
+var SSR_MESSAGES = {
+  serviceKey: "naro-js/ssr keeps a signed-in user's session in cookies, so it takes the anon key only. Make the service key's client with naro-js's createClient({ url, serviceKey }), on your server.",
+  getAll: "createServerClient needs cookies.getAll: a function that returns the request's cookies, e.g. () => cookieStore.getAll()."
+};
+function refuseServiceKey(options) {
+  if (options.serviceKey !== void 0)
+    throw new Error(SSR_MESSAGES.serviceKey);
+}
+var pageClients = /* @__PURE__ */ new Map();
+function createBrowserClient(options) {
+  refuseServiceKey(options);
+  const { url, anonKey, cookieOptions, fetch, realtime } = options;
+  const common = {
+    url,
+    anonKey,
+    ...fetch !== void 0 ? { fetch } : {},
+    ...realtime !== void 0 ? { realtime } : {}
+  };
+  if (!isBrowser()) return createClient(common);
+  const id = `${url}
+${anonKey}`;
+  const kept = pageClients.get(id);
+  if (kept !== void 0) return kept;
+  const https = globalThis.location?.protocol === "https:";
+  const storage = browserCookieStorage(
+    resolveCookieOptions(cookieOptions, https),
+    globalThis.document
+  );
+  const client = createClient({ ...common, auth: { storage } });
+  pageClients.set(id, client);
+  return client;
+}
+function createServerClient(options) {
+  refuseServiceKey(options);
+  const { url, anonKey, cookies, cookieOptions, fetch } = options;
+  if (typeof cookies?.getAll !== "function")
+    throw new Error(SSR_MESSAGES.getAll);
+  const storage = serverCookieStorage(
+    cookies,
+    resolveCookieOptions(cookieOptions, true)
+  );
+  return createClient({
+    url,
+    anonKey,
+    ...fetch !== void 0 ? { fetch } : {},
+    auth: { storage, detectSessionInUrl: false }
+  });
+}
+export {
+  SSR_MESSAGES,
+  createBrowserClient,
+  createServerClient
+};

package/dist/types.d.ts

@@ -190,12 +190,19 @@ export type AuthFlowType = "oauth" | "email_verification" | "recovery";
 /**
  * `getSessionFromUrl()`: `type` null when the URL carried nothing of Naro's.
  * `recovery` holds no session — the page asks for a new password and calls
- * `updateUser({ password })`.
+ * `updateUser({ password })` — and names whose password that is.
  */
 export type UrlSessionResponse = AuthResponse<{
     session: Session | null;
     user: User | null;
     type: AuthFlowType | null;
+    /**
+     * Recovery only: the address of the account the reset link is for, as
+     * the worker knows it, masked to its first character (`a***@example.com`)
+     * — show it, so the person sees whose password they are about to set.
+     * Null for an account without an email.
+     */
+    email?: string | null;
 }>;
 export type EmailRedirectOptions = {
     /** A URL on an allowed origin of the project; omitted, its own origin. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naro-js",
-  "version": "0.7.1",
+  "version": "0.9.0",
   "description": "Auth, data and files for your Naro project, from the browser or the server.",
   "type": "module",
   "sideEffects": false,
@@ -12,6 +12,9 @@
     "*": {
       "functions": [
         "./dist/functions.d.ts"
+      ],
+      "ssr": [
+        "./dist/ssr.d.ts"
       ]
     }
   },
@@ -23,6 +26,10 @@
     "./functions": {
       "types": "./dist/functions.d.ts",
       "default": "./dist/functions.js"
+    },
+    "./ssr": {
+      "types": "./dist/ssr.d.ts",
+      "default": "./dist/ssr.js"
     }
   },
   "publishConfig": {
@@ -36,9 +43,9 @@
     "vitest": "3.2.7",
     "@next-deploy/backend-worker": "0.1.0",
     "@next-deploy/config": "0.1.0",
+    "@next-deploy/data-core": "0.1.0",
     "@next-deploy/functions-runtime": "0.1.0",
-    "@next-deploy/sdk": "0.1.0",
-    "@next-deploy/data-core": "0.1.0"
+    "@next-deploy/sdk": "0.1.0"
   },
   "scripts": {
     "build": "tsup && pnpm build:types",