naro-js 0.8.0 → 0.9.0

package/README.md

@@ -243,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.
@@ -258,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 });
 ```
 
@@ -306,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
@@ -854,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
@@ -959,8 +973,10 @@ 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
   (`broadcast.replay`) are refused with `INVALID_CHANNEL_CONFIG`; `send()` and
@@ -968,9 +984,16 @@ await naro.removeChannel(room);
   `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/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 {
@@ -751,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).
@@ -1136,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,
@@ -1151,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.
@@ -1174,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();
@@ -2901,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;
@@ -3318,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";
@@ -3345,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);
@@ -4093,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) {
@@ -4534,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/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.8.0",
+  "version": "0.9.0",
   "description": "Auth, data and files for your Naro project, from the browser or the server.",
   "type": "module",
   "sideEffects": false,
@@ -42,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/config": "0.1.0"
+    "@next-deploy/sdk": "0.1.0"
   },
   "scripts": {
     "build": "tsup && pnpm build:types",