naro-js 0.1.0

package/README.md

@@ -0,0 +1,334 @@
+# naro-js
+
+Auth and data for your [Naro](https://naro.sh) project, from the browser or
+the server. A project's backend brings its own database; this client signs
+users in and reads and writes it through the project's policies. No SQL, no
+database credentials, no dependencies.
+
+```sh
+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`.
+`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,
+the users and the keys are kept, and turning it back on brings them back
+with the same keys — nothing to change in your app.
+
+```ts
+import { createClient } from "naro-js";
+
+const naro = createClient({
+  url: "https://my-app.naro.sh",
+  anonKey: "naro_pk_…",
+});
+
+await naro.auth.signIn({ email, password });
+const {
+  data: { user },
+} = await naro.auth.getUser();
+
+const { data, error } = await naro
+  .from("posts")
+  .select("*")
+  .eq("user_id", user.id)
+  .order("created_at", { ascending: false })
+  .limit(20);
+
+await naro.from("posts").insert({ title: "Hello", content: "World" });
+await naro.from("posts").update({ title: "Updated" }).eq("id", 10);
+await naro.from("posts").delete().eq("id", 10);
+```
+
+- Every call resolves to `{ data, error }` and never throws. `createClient`
+  throws only for a configuration mistake.
+- `url` is the project's origin alone (`https://my-app.naro.sh`): no path,
+  no `?` or `#`.
+- Queries: `.select("id, title")`, `.eq` `.neq` `.gt` `.gte` `.lt` `.lte`
+  `.in` `.is` `.like` `.ilike`, `.or` `.and` `.not` `.filter` `.match`
+  `.contains` `.containedBy` `.overlaps` (see [Filters](#filters)),
+  `.order()`, `.limit()`, `.offset()`,
+  `.range(from, to)`, `.single()`, `.maybeSingle()`. One select reads at
+  most 1,000 rows, by `.limit()` or `.range()`. Add `.select()` to an
+  insert, update or delete to get the rows back.
+- The anon key is safe in a browser; what it may do is decided by the
+  project's policies. The service key (`naro_sk_…`, as `serviceKey`) skips
+  them — use it on a server only. `createClient` accepts it only in Node,
+  Deno, Bun, Cloudflare Workers or an edge runtime, and refuses it in a
+  browser, a web worker or a React Native app.
+- A `RATE_LIMITED` error carries `details.retryAfter`, in seconds, when the
+  backend says how long to wait. So does `WRITE_QUOTA_EXCEEDED`: the project
+  wrote more database rows today (UTC) than its daily limit, so inserts,
+  updates, deletes and sign-ups are refused until 00:00 UTC. Reads and
+  sign-in still work.
+- `DATABASE_FULL` (507) means the project's database reached D1's 10 GB
+  limit, which cannot be raised: writes fail until rows are deleted. Reads
+  still work, and no retry helps.
+- 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`.
+- Types: `createClient<Database>()` with the `Database` that
+  `naro gen types` writes — see [Types](#types).
+- Email and social sign-in — see [Sign-in flows](#sign-in-flows).
+
+## Sign-in flows
+
+Google and GitHub sign-in, email confirmation and password reset, once the
+project has set them up (`naro backend auth`). The names follow supabase-js.
+
+```ts
+// Sends the browser to the project's /_naro/v1/auth/authorize/github, then
+// to GitHub; it comes back to redirectTo.
+await naro.auth.signInWithOAuth({
+  provider: "github", // or "google"
+  redirectTo: "https://app.example.com/auth/done", // default: this page
+});
+
+// On the page it comes back to, createClient finishes the sign-in itself
+// (auth: { detectSessionInUrl: false } to do it yourself). getSession and
+// every naro.from() query wait for it, so none goes out as anon first — for
+// at most 15 seconds: then naro.auth.ready() resolves { error: TIMEOUT } and
+// they go out as anon. A client built twice on the page (React StrictMode)
+// waits on the same exchange.
+const {
+  data: { user },
+} = await naro.auth.getUser();
+
+// What came back: data.type is "oauth", "email_verification", "recovery"
+// or null, and a failure is the error (OAUTH_ACCESS_DENIED, TOKEN_EXPIRED…).
+const { data, error } = await naro.auth.getSessionFromUrl();
+
+// The confirmation link only confirms the address. After you confirm, sign in.
+await naro.auth.signUp({
+  email,
+  password,
+  redirectTo: APP + "/auth/confirmed",
+});
+await naro.auth.resendVerification(email, {
+  redirectTo: APP + "/auth/confirmed",
+});
+
+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:
+await naro.auth.updateUser({ password: newPassword });
+```
+
+- `redirectTo` must be on one of the project's production hosts — its
+  `https://<project>.naro.sh` address and its custom domains — or an entry
+  it allowed with `naro backend auth redirects add` — an origin, or an
+  origin and a path (`https://app.example.com/auth/`: only the pages under
+  it). Otherwise the worker answers `403 INVALID_REDIRECT_URL`
+  (`INVALID_CALLBACK_URL` from `signUp` and `resendVerification`). The
+  preview host (`<project>-preview.naro.sh`) runs any pushed branch against
+  the same accounts: it is allowed only once added, and emailed links always
+  point at a production host. Email flows without `redirectTo` come back to
+  that host's root.
+- Pass `createClient` the origin your app signs in on: the provider sends
+  the browser back to that host's `/_naro/v1/auth/callback/<provider>`, so
+  that is the redirect URI to register with the provider
+  (`naro backend auth` prints one per production host).
+- `signInWithOAuth` makes no request: it navigates. The worker's
+  `/authorize` sets a ten-minute `__Host-` cookie for that one sign-in on the
+  host it runs on — no other naro.sh app can set or overwrite it, and two
+  tabs keep their own — and only the browser that holds it can finish
+  (`OAUTH_BROWSER_MISMATCH` elsewhere);
+  anything that goes wrong — `PROVIDER_NOT_CONFIGURED`, `RATE_LIMITED`… —
+  comes back in the page's URL, as `getSessionFromUrl()`'s error.
+  `skipBrowserRedirect: true` answers the URL without going there.
+- The answer comes back in the URL fragment as a one-time code: it lives
+  60 seconds, works once, and only with the PKCE verifier this browser kept
+  for that sign-in (one per sign-in, for ten minutes, in the same storage as
+  the session token). Without it: `CODE_VERIFIER_MISSING` — sign in again.
+- The fragment can be read by any script on the page it lands on, and an
+  open redirect (`/logout?next=…`) passes it on. Keep sign-in on pages of
+  its own, allow only their path, and keep third-party scripts and open
+  redirects off them. `getSessionFromUrl()` never shows text from the URL:
+  its errors carry the SDK's own messages.
+- A provider email the provider has not verified is refused
+  (`OAUTH_PROVIDER_EMAIL_NOT_VERIFIED`): verify it with the provider first.
+  An account with the same email is linked only when both sides have it
+  confirmed (`OAUTH_ACCOUNT_NOT_LINKED` otherwise).
+- A confirmation link opens no session. If someone else signed up with the
+  address before its owner confirmed it — or the owner's Google or GitHub
+  sign-in was refused for that unconfirmed account
+  (`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.
+- `resetPasswordForEmail` and `resendVerification` answer the same whether or
+  not the address has an account.
+- With email verification required, `signUp` answers the user without a
+  session, and `signIn` before confirming answers `403 EMAIL_NOT_VERIFIED`.
+- Signing in with a provider needs `crypto.subtle` (https, or localhost);
+  without it `CRYPTO_UNAVAILABLE`.
+- The code exchange a page runs on load gives up after 15 seconds: the
+  request is called off, `getSessionFromUrl()` and `auth.ready()` answer
+  `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.
+
+## Types
+
+Generate the types from the project's schema, and hand them to
+`createClient`:
+
+```bash
+naro gen types --output src/database.types.ts
+```
+
+```ts
+import { createClient } from "naro-js";
+import type { Database, Tables } from "./database.types";
+
+const naro = createClient<Database>({
+  url: "https://my-app.naro.sh",
+  anonKey: "naro_pk_…",
+});
+
+// { id: number; title: string }[] | null
+const { data } = await naro.from("posts").select("id, title");
+
+await naro.from("posts").insert({ title: "Hello", user_id: user.id });
+const post: Tables<"posts"> | null = (
+  await naro.from("posts").select().eq("id", 1).maybeSingle()
+).data;
+```
+
+- `from()` takes the tables of `Database`. `select("id, title")` returns
+  those columns, `select()` or `select("*")` the whole row, and `.single()`
+  / `.maybeSingle()` follow. A column the table lacks is a type error where
+  you write it: `Argument of type '"id, nope"' is not assignable to
+parameter of type '"Unknown column 'nope'"'`. A list the types cannot read
+  — a quoted name, or a `string` variable — returns the whole row.
+- `insert()` takes the table's `Insert`: a column is optional when it has a
+  default, allows NULL, is the `INTEGER PRIMARY KEY`, or is the owner column
+  of a table whose insert rule is `owner` — the backend fills it, and
+  `naro gen types` reads the policies to know (run it again after
+  `naro policy set`). Generated columns are left out. `update()` takes
+  `Update`, every column optional.
+- **Arrays and objects go straight into a TEXT column.**
+  `insert({ tags: ["a", "b"] })` stores their JSON text — exactly what
+  `JSON.stringify` gives — which is what `.contains()` reads. It comes back
+  as that string: `JSON.parse(row.tags)`. A value typed with an `interface`
+  has no index signature and does not fit `Json`; spread it
+  (`{ ...value }`) or declare it with `type`.
+- Filters, `order()` and `.match()` take the table's column names; their
+  values stay loose (a column with a type converts `"10"` to 10, as SQLite
+  does). Filter strings like `or("status.eq.draft")` are not checked.
+- What a column holds, from its declared type: INTEGER, REAL → `number`;
+  TEXT → `string` (and writes take `Json` too, above); BOOLEAN → `number`
+  (0 or 1; insert `true` or `false`); NUMERIC, DATE, DATETIME →
+  `number | string` (`CURRENT_TIMESTAMP` is text); BLOB → `number[]`, and
+  never writable through the Data API; no type, or a STRICT table's `ANY` →
+  `number | string | number[]`. NULL allowed → `| null`.
+- Views are in `Database["views"]` for `Tables<"view">`, but `from()` does
+  not take them: the Data API reads no view (`404 TABLE_NOT_FOUND`).
+- Without a type argument everything stays untyped: any table, any column,
+  rows of `Record<string, unknown>`.
+
+## Filters
+
+Chained filters are ANDed. For anything else, group them:
+
+```ts
+// or / and / not, with a callback…
+await naro
+  .from("posts")
+  .select()
+  .or((q) => q.eq("status", "draft").lt("price", 10))
+  .not("deleted_at", "is", null);
+
+// …or with Supabase's filter string, pasted as it is.
+await naro
+  .from("posts")
+  .select()
+  .or("status.eq.draft,and(price.lt.10,tags.cs.{sale})");
+
+// A TEXT column holding a JSON array, like `["a","b"]`.
+await naro.from("posts").select().contains("tags", ["a", "b"]);
+```
+
+- `.or()` and `.and()` take a callback or a string; `.not()` takes a
+  callback (its conditions ANDed) or `column, operator, value`.
+  `.filter(column, operator, value)` takes any operator by name
+  (`"not.gte"` too), and `.match({ a: 1, b: "x" })` is an `.eq()` per key.
+- `.contains(column, values)`: the array has every value.
+  `.containedBy(column, values)`: every element is one of the values (`[]`
+  is). `.overlaps(column, values)`: at least one in common. Values are
+  strings and numbers, 1 to 100 of them, and one request holds at most 4 of
+  these three conditions. A row that is not a JSON array — other text, a
+  JSON object, a number — is no match, never an error. A value longer than
+  65,536 characters is not looked into: like NULL, it matches neither the
+  condition nor its `not`. The column must hold JSON text; a JSONB value is
+  no match. JSON `true` and `false` inside an array compare as 1 and 0, and
+  an element that is itself an array or object compares as its JSON text.
+- **NULL is neither.** A condition on a NULL column is unknown, and so is its
+  `not`: `.not("status", "eq", "draft")` does not return rows whose status
+  is NULL — as in SQL and in Supabase. Add
+  `.or("status.neq.draft,status.is.null")` to include them.
+- **String values are text.** In a filter string, and in a string value of
+  `.filter()` / `.not()`, `id.eq.10` sends `"10"`. A column declared with a
+  type (INTEGER, REAL…) converts it back to a number when comparing. A column
+  without a type does not: there `"10"` never equals `10`, and because
+  SQLite orders every number before any text, `.or("n.lt.10")` matches every
+  number in `n` — 5, 50 and 500 alike — and `.or("n.gt.100")` matches none.
+  Declare the column's type, or use the callback form or `.lt("n", 10)`,
+  whose values keep their type. The exceptions, for unquoted values only:
+  - `is.null`, `is.true` and `is.false` are those values.
+  - `true` and `false` after `eq` or `neq`, and in an `in.(…)` list, are
+    booleans — `done.eq.true` and `.filter("done", "eq", "true")` send
+    `true`, which the backend compares as 1, so it matches a BOOLEAN or
+    INTEGER column holding 1, and `archived.neq.true` matches only the 0
+    rows. Quoted, `done.eq."true"` compares with the text `true`. Other
+    items of an `in.(1,2)` list stay text.
+  - In a `cs` / `cd` / `ov` list, a plain decimal that goes out exactly as
+    written is a number: `tags.cs.{1,2.5}` sends `[1, 2.5]`. Integers must
+    be within ±9,007,199,254,740,991, and there is no exponent or `+` —
+    `{12345678901234567890}` and `{1e5}` stay text, as does `{"1"}`. Store
+    ids larger than that as strings in the array.
+- In a filter string, quote a value that holds `,` `.` `(` `)`, or leading
+  or trailing spaces: `title.eq."a, b"`, with `\` before a `"` or `\` inside.
+  `quoteFilterValue(text)` does exactly this. A string the SDK cannot read —
+  an unknown operator, unbalanced parentheses, an empty item — is answered
+  with `INVALID_QUERY` without being sent.
+- **`*` is `%` in every `like` and `ilike`** — `.ilike("name", "*kim*")`,
+  `name.ilike.*kim*` and `.filter("name", "ilike", "*kim*")` alike — as in
+  PostgREST, so code ported from supabase-js keeps matching. The price, the
+  same as in PostgREST: a literal `*` cannot be matched.
+- **Filtering on user input?** Prefer the methods that take a value —
+  `.eq()`, `.ilike()`, the callback form — or `.filter()`, whose value
+  cannot add a condition. If you must build a filter string, pass every
+  value through `quoteFilterValue()`:
+
+  ```ts
+  import { quoteFilterValue } from "naro-js";
+
+  await naro
+    .from("posts")
+    .select()
+    .or(`title.eq.${quoteFilterValue(q)},body.eq.${quoteFilterValue(q)}`);
+  ```
+
+  Pasted in unquoted (or quoted by escaping only `"`), input like
+  `x\",id.gte.0,title.eq.\"y` adds its own conditions. Filters only narrow
+  within what the project's policies allow — but inside that boundary an
+  injected condition can widen a query all the way to it: a `.delete().or(…)`
+  built that way can delete every row the caller is allowed to delete.
+
+- Limits: groups nest 4 deep (`not` counts); one request holds at most 100
+  conditions, 4 of them `contains` / `containedBy` / `overlaps`; one
+  statement binds at most 100 values (a select's limit and offset are two of
+  them) and compiles to at most 100,000 bytes of SQL.

package/dist/auth/client.d.ts

@@ -0,0 +1,122 @@
+import { type NaroError } from "../errors.js";
+import { type HttpConfig } from "../http.js";
+import type { AuthActionResponse, EmailRedirectOptions, OAuthResponse, SessionResponse, SignInCredentials, SignInWithOAuthOptions, SignOutResponse, SignUpCredentials, UrlSessionResponse, UserAttributes, UserResponse } from "../types.js";
+import type { FlowVerifiers } from "./flows.js";
+import type { RecoveryToken } from "./recovery.js";
+/** Better Auth requires `name` on sign-up; the email's local part stands in. */
+export declare function defaultName(email: string): string;
+export type AuthFlowStores = {
+    /** The PKCE verifiers of the provider sign-ins this browser began. */
+    verifiers: FlowVerifiers;
+    /** The password reset token a recovery link brought (15 minutes). */
+    recovery: RecoveryToken;
+    /**
+     * Read a sign-in's answer from the page URL when the client is created
+     * (`getSessionFromUrl`). Default true in a browser.
+     */
+    detectSessionInUrl: boolean;
+    /**
+     * Where the session is kept: the storage and its key. Clients on one page
+     * that keep it in the same place share the URL sign-in one of them began
+     * (`inFlight`).
+     */
+    shared: {
+        storage: object;
+        key: string;
+    };
+};
+/** How long the code exchange a sign-in redirect starts may take. */
+export declare const EXCHANGE_TIMEOUT_MS = 15000;
+/**
+ * `naro.auth` — email and password, email confirmation, password reset and
+ * provider sign-in through the worker's Better Auth routes
+ * (`/_naro/v1/auth/*`, spec §8.1, §13; P2-6 §13.3). Every method resolves;
+ * none throws.
+ */
+export declare class AuthClient {
+    #private;
+    constructor(http: HttpConfig, flow: AuthFlowStores);
+    /**
+     * Creates the account and signs in; the token is stored for later calls.
+     * When the project requires a confirmed email there is no session yet —
+     * `user` comes back, and after the confirmation link the user signs in.
+     */
+    signUp(credentials: SignUpCredentials): Promise<UserResponse>;
+    signIn(credentials: SignInCredentials): Promise<UserResponse>;
+    /**
+     * Starts a Google or GitHub sign-in: sends the browser, with a top-level
+     * navigation, to the worker's `GET /_naro/v1/auth/authorize/<provider>`,
+     * which checks `redirectTo`, binds the flow to this browser with a cookie
+     * and goes on to the provider (adversarial review I1). The provider sends
+     * the browser back to `redirectTo`, where `getSessionFromUrl()` (run by
+     * `createClient` on its own) finishes the sign-in. No request is made
+     * here: anything that goes wrong comes back in that page's URL.
+     */
+    signInWithOAuth(options: SignInWithOAuthOptions): Promise<OAuthResponse>;
+    /**
+     * Trades the one-time code a sign-in redirect brought for the session,
+     * with the verifier this browser kept when it began that flow — `flow` is
+     * the redirect's `naro_flow`; without it, the newest flow's. Most apps
+     * never call it: `getSessionFromUrl()` does.
+     */
+    exchangeCodeForSession(code: string, flow?: string): Promise<SessionResponse>;
+    /**
+     * Reads what a sign-in redirect left in this page's URL fragment, then
+     * clears it: a provider sign-in or a confirmation link hands over a
+     * session (traded here), a reset link a recovery token (kept for
+     * `updateUser`), and a failure its `code` and `message`. With nothing of
+     * Naro's in the URL, `type` is null — or, after `createClient` already
+     * read it, the answer it got.
+     */
+    getSessionFromUrl(): Promise<UrlSessionResponse>;
+    /**
+     * 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.
+     */
+    resetPasswordForEmail(email: string, options?: EmailRedirectOptions): Promise<AuthActionResponse>;
+    /**
+     * Sets a new password in the recovery flow: on the page the reset link
+     * opened, after `getSessionFromUrl()` read its token. Signing in with the
+     * new password comes after — a reset ends every session of the account.
+     * (Changing the password of a signed-in user is not offered: spec §14
+     * "(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.
+     */
+    updateUser(attributes: UserAttributes): Promise<AuthActionResponse>;
+    /**
+     * Emails the confirmation link again, when the address has an account that
+     * is not confirmed yet. The answer does not say which.
+     */
+    resendVerification(email: string, options?: EmailRedirectOptions): Promise<AuthActionResponse>;
+    /**
+     * Ends the session on the worker and forgets the token. The token is
+     * forgotten even when the worker cannot be reached — the error still comes
+     * back, since the session then lives on until it expires.
+     */
+    signOut(): Promise<SignOutResponse>;
+    /**
+     * The signed-in session and user. Signed out: both null, no request. A
+     * stored token the worker no longer accepts is forgotten and reported as
+     * INVALID_SESSION once (spec §11.1: a session never quietly turns anon).
+     * Waits for a sign-in the page URL carried, if `createClient` found one.
+     */
+    getSession(): Promise<SessionResponse>;
+    /** `{ data: { user } }`; `user` is null when signed out. */
+    getUser(): Promise<UserResponse>;
+    /**
+     * Resolves once a sign-in the page URL carried has been traded for its
+     * session (or failed), with its error. Queries wait for it, so the first
+     * one after a provider's redirect goes out signed in rather than as anon.
+     * The exchange gives up after 15 seconds (TIMEOUT, PR #68 review 10):
+     * then the queries go out as anon rather than wait forever.
+     */
+    ready(): Promise<{
+        error: NaroError | null;
+    }>;
+}

package/dist/auth/flow-errors.d.ts

@@ -0,0 +1,4 @@
+import type { NaroError } from "../errors.js";
+import type { AuthFlowType } from "../types.js";
+/** The error a sign-in redirect's `naro_error` stands for. */
+export declare function flowError(type: AuthFlowType | null, raw: string): NaroError;

package/dist/auth/flows.d.ts

@@ -0,0 +1,17 @@
+import type { TokenStore } from "./storage.js";
+/** A flow's life: the worker's flow row and Better Auth's state. */
+export declare const FLOW_TTL_MS: number;
+/** More in flight than anyone clicks; the oldest go first. */
+export declare const MAX_FLOWS = 10;
+export declare class FlowVerifiers {
+    #private;
+    constructor(store: TokenStore, now?: () => number);
+    /** Keeps `verifier` for the flow `flow`, for ten minutes. */
+    add(flow: string, verifier: string): Promise<void>;
+    /**
+     * The verifier of `flow`, taken — one flow, one use. Without a flow id
+     * (a code traded by hand), the newest one. Null when there is none, or it
+     * expired.
+     */
+    take(flow: string | undefined): Promise<string | null>;
+}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,10 @@
+export type PkcePair = {
+    verifier: string;
+    challenge: string;
+};
+/**
+ * A fresh verifier (32 random bytes, 43 base64url characters, RFC 7636 §4.1)
+ * and its S256 challenge; null where the runtime has no `crypto.subtle` — an
+ * http page that is not localhost, for one.
+ */
+export declare function createPkcePair(): Promise<PkcePair | null>;

package/dist/auth/recovery.d.ts

@@ -0,0 +1,15 @@
+import type { TokenStore } from "./storage.js";
+/** How long the token is kept after the link was opened. */
+export declare const RECOVERY_TTL_MS: number;
+export declare class RecoveryToken {
+    #private;
+    constructor(store: TokenStore, now?: () => number);
+    /** Keeps the token a recovery link brought, for 15 minutes. */
+    keep(token: string): Promise<void>;
+    /** The token, while it lasts; an expired or unreadable one is cleared. */
+    current(): Promise<string | null>;
+    /** Forgets it: a sign-in, a sign-up, a sign-out. */
+    forget(): Promise<void>;
+    /** Forgets it if it is still `token` — used, or refused as used. */
+    forgetIf(token: string): Promise<void>;
+}

package/dist/auth/storage.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Where the session token lives (spec §13). `localStorage` fits as it is; so
+ * does any async store (a cookie jar on the server, React Native's
+ * AsyncStorage) — `createClient({ auth: { storage } })`.
+ */
+export type AuthStorage = {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+};
+export declare function memoryStorage(): AuthStorage;
+/**
+ * The browser's `localStorage` when it works, memory otherwise. Merely
+ * reading `localStorage` throws in a sandboxed iframe or with storage
+ * blocked, and Safari's private mode used to throw on the first write, so
+ * the probe writes too.
+ */
+export declare function defaultStorage(): AuthStorage;
+/** One token per project URL, so two clients on one page do not collide. */
+export declare function storageKey(baseUrl: string): string;
+/**
+ * The PKCE verifiers of the provider sign-ins this browser began, one per
+ * flow (P2-6 §6, `flows.ts`), kept where the token is.
+ */
+export declare function verifierKey(baseUrl: string): string;
+/** The password reset token a recovery link brought, until it is used. */
+export declare function recoveryKey(baseUrl: string): string;
+/**
+ * The client's view of its token. Nothing here throws: the storage is the
+ * app's code, and a query must still answer `{ data, error }` when it fails.
+ * The first time the storage throws or rejects, the store stops using it and
+ * keeps the token in memory for the rest of the client's life — a store that
+ * failed once would otherwise hand back tokens it no longer has.
+ *
+ * Operations run one at a time, in call order, so a compare-and-clear cannot
+ * interleave with a sign-in on an async storage (see `#serial`). That holds
+ * per client; two clients on one storage key, or two tabs, can still race.
+ */
+export declare class TokenStore {
+    #private;
+    constructor(storage: AuthStorage, key: string);
+    get(): Promise<string | null>;
+    set(token: string): Promise<void>;
+    clear(): Promise<void>;
+    /**
+     * Clears only if the stored token is still the one that was rejected. A
+     * request that left with an old token can come back after the user signed
+     * in again; its INVALID_SESSION must not sign the new session out. The
+     * read and the removal are one operation: with an async storage, a sign-in
+     * that lands between them would otherwise be the token removed.
+     */
+    clearIf(token: string): Promise<void>;
+    /**
+     * Reads the value, hands it to `transform` and stores what that returns
+     * (null clears it), as one operation — the per-flow verifiers
+     * (`flows.ts`) change one entry of a JSON object this way.
+     */
+    update(transform: (current: string | null) => string | null): Promise<void>;
+    /** Stores `next` only if `expected` is still stored, as one operation. */
+    replaceIf(expected: string, next: string): Promise<void>;
+}

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+import { AuthClient } from "./auth/client.js";
+import { type AuthStorage } from "./auth/storage.js";
+import { type FetchLike } from "./http.js";
+import { TableBuilder } from "./query/builder.js";
+import type { DatabaseShape, InsertOf, RowOf, TableName, TablesOf, UntypedDatabase, UpdateOf } from "./types.js";
+type CommonOptions = {
+    /**
+     * The project's Naro URL, e.g. `https://my-app.naro.sh`: an origin only,
+     * since the worker serves `/_naro/v1/…` at the root of its host.
+     */
+    url: string;
+    auth?: {
+        /** Where the session token is kept. Default: localStorage in a browser, memory elsewhere. */
+        storage?: AuthStorage;
+        /**
+         * Finish a sign-in the page URL carries back — a provider's callback, a
+         * confirmation or reset link (P2-6) — when the client is created, and
+         * clear it from the address bar. Default true; off, call
+         * `naro.auth.getSessionFromUrl()` yourself.
+         */
+        detectSessionInUrl?: boolean;
+    };
+    /** Replaces the global fetch (tests, custom runtimes). */
+    fetch?: FetchLike;
+};
+export type ClientOptions = CommonOptions & ({
+    anonKey: string;
+    serviceKey?: undefined;
+}
+/**
+ * Server only: skips every policy (spec §7). Refused unless the runtime
+ * is one the SDK knows as a server (Node, Deno, Bun, Workers, edge).
+ */
+ | {
+    serviceKey: string;
+    anonKey?: undefined;
+});
+/** User-facing; quoted in spec §15's "(P1-4 구현 결정)". */
+export declare const CONFIG_MESSAGES: {
+    readonly url: "createClient needs the project url, like https://my-app.naro.sh.";
+    readonly urlNotOrigin: "createClient needs the project url alone, like https://my-app.naro.sh: no path, no ? or #, no user:password@. Naro serves its API at /_naro/v1 on that origin.";
+    readonly key: "createClient needs an anonKey (or, on a server, a serviceKey).";
+    readonly bothKeys: "Pass createClient an anonKey or a serviceKey, not both.";
+    readonly serviceKeyOffServer: "A Naro service key (naro_sk_…) 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_…) here and keep the service key on your server.";
+    readonly fetch: "This runtime has no fetch. Pass one to createClient({ fetch }).";
+};
+export declare class NaroClient<Database extends DatabaseShape<Database>> {
+    #private;
+    /** Sign-up, sign-in, sign-out and the current user (spec §13). */
+    readonly auth: AuthClient;
+    constructor(options: ClientOptions);
+    /** Start a query on `table`: `.select()`, `.insert()`, `.update()` or `.delete()`. */
+    from<Table extends TableName<Database>>(table: Table): TableBuilder<RowOf<TablesOf<Database>[Table]>, InsertOf<TablesOf<Database>[Table]>, UpdateOf<TablesOf<Database>[Table]>>;
+}
+/**
+ * The one entry point (spec §15). Throws only for a configuration mistake —
+ * no url or not an origin, no key, or a service key off a server; every call
+ * on the client resolves to `{ data, error }` instead.
+ */
+export declare function createClient<Database extends DatabaseShape<Database> = UntypedDatabase>(options: ClientOptions): NaroClient<Database>;
+export {};