naro-js 0.7.1 → 0.8.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.
@@ -325,6 +327,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
@@ -856,7 +962,7 @@ await naro.removeChannel(room);
 - Unlike supabase-js: broadcast and presence listeners match one event name
   exactly, case included — `{ event: "*" }` hears nothing; `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'`.

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

@@ -308,6 +308,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);
@@ -1254,6 +1263,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. */

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naro-js",
-  "version": "0.7.1",
+  "version": "0.8.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": {
@@ -35,10 +42,10 @@
     "typescript": "7.0.2",
     "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/config": "0.1.0"
   },
   "scripts": {
     "build": "tsup && pnpm build:types",