naro-js 0.1.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # naro-js
 
-Auth and data for your [Naro](https://naro.sh) project, from the browser or
+Auth, data and files 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.
@@ -71,12 +71,133 @@ await naro.from("posts").delete().eq("id", 10);
   `auth: { storage }` with your own `getItem` / `setItem` / `removeItem`.
 - 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
+  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.
+- Admin accounts, closed sign-ups, sign-in by username and the password
+  length — see [Admin accounts and closed sign-ups](#admin-accounts-and-closed-sign-ups).
 - Email and social sign-in — see [Sign-in flows](#sign-in-flows).
+- Files — see [Storage](#storage).
+
+## Policies
+
+What a request may do is decided by the table's policies — Postgres's
+row-level security, as in Supabase. A table without a policy refuses every
+anon and signed-in request (only the service key gets through), so write a
+table's policies in the migration that creates it: `create policy` after the
+`create table`, in the same file. `naro db push` applies them with the table,
+all or nothing.
+
+```sql
+-- migrations/0002_todos.sql: each signed-in user reads and changes their own rows.
+create table todos (
+  id integer primary key,
+  user_id uuid not null,
+  title text not null
+);
+create policy "own rows" on todos for all to authenticated
+  using ((select auth.uid()) = user_id)
+  with check ((select auth.uid()) = user_id);
+
+-- migrations/0003_posts.sql: anyone reads, signed in or not.
+create table posts (id integer primary key, title text not null);
+create policy "read" on posts for select to anon, authenticated using (true);
+
+-- migrations/0004_reports.sql: an app only its admins sign in to. First run
+-- naro backend auth signups off and create the admin accounts: authenticated
+-- then means exactly those accounts.
+create table reports (id integer primary key, body text not null);
+create policy "admins" on reports for all to authenticated using (true) with check (true);
+```
+
+A request no policy lets through, and a written row that fails a check,
+answer `403 PERMISSION_DENIED`; rows a policy's `using` does not pass are left
+out without an error. The `naro-cli` README lists what a
+migration accepts and refuses (`DISABLE ROW LEVEL SECURITY`, `GRANT`,
+`REVOKE` and `ALTER POLICY` are refused), the warnings it answers with, and
+`naro policy set`, a shorthand for the common rules.
+
+## Admin accounts and closed sign-ups
+
+An app that only its admins sign in to: close sign-ups, then create the
+accounts yourself. With sign-ups closed, `authenticated` in a policy means
+exactly the users you created.
+
+```bash
+naro backend auth signups off
+echo "$ADMIN_PASSWORD" | naro backend users create --username admin --password-stdin
+```
+
+```ts
+// In the app: sign in by username, or by email.
+await naro.auth.signIn({ username: "admin", password });
+await naro.auth.signIn({ email, password });
+```
+
+The same from your own server, with supabase-js's `auth.admin` names:
+
+```ts
+// Server only: the service key skips every policy.
+const admin = createClient({
+  url: "https://my-app.naro.sh",
+  serviceKey: process.env.NARO_SERVICE_KEY,
+});
+
+const { data, error } = await admin.auth.admin.createUser({
+  username: "admin", // and/or email
+  password,
+  // emailConfirm: false — only with an email; users are confirmed otherwise
+});
+const {
+  data: { users, total },
+} = await admin.auth.admin.listUsers({ page: 1, perPage: 50 });
+await admin.auth.admin.deleteUser(data.user.id);
+```
+
+- `createUser` takes an email, a username or both. The user is confirmed
+  and signs in at once — while sign-ups are closed, and while sign-in waits
+  for a confirmed email — unless `emailConfirm: false` (which needs an
+  email). A user with only a username answers `email: null`, here, in
+  `signIn` and in `getUser()`, and signs in with its username. Answers
+  carry `id`, `email`, `username`, `emailVerified` and `createdAt`, never a
+  password.
+- `listUsers` is newest first, 50 a page unless `perPage` says (at most
+  1000), with the `total`. `deleteUser(id)` removes the user and its
+  sign-in methods and ends its sessions; an unknown id is
+  `404 USER_NOT_FOUND` ("No user has this id.").
+- `auth.admin` works only on a client made with `serviceKey`. On an anon
+  client each call answers `403 PERMISSION_DENIED` ("Only the service key
+  can manage users.") without a request.
+- A username is 3–30 letters, digits, `_` and `.`, and is matched in any
+  case (stored lowercased). `signUp({ email, password, username })` sets one
+  at sign-up.
+- Closed sign-ups: every `signUp` answers `403 SIGNUPS_DISABLED` ("Sign-ups
+  are closed for this project."), and so does a first Google or GitHub
+  sign-in, in `getSessionFromUrl()`. Users that exist keep signing in, with
+  a password or a provider. `naro backend auth signups on` opens them again.
+- While sign-ups are open, a sign-up with a username someone has answers
+  `409 USERNAME_TAKEN` ("That username is already taken.") — so anyone can
+  learn which usernames exist, as fast as sign-up's per-address rate limit
+  lets them. With sign-ups closed, every sign-up answers
+  `403 SIGNUPS_DISABLED` first. `createUser` answers `USERNAME_TAKEN` too,
+  and `422 USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL` for an email in use.
+- Passwords take at least 6 characters unless
+  `naro backend auth password --min-length <n>` (6–128) says more. A
+  shorter one, on sign-up, `createUser` or a reset, answers
+  `400 PASSWORD_TOO_SHORT` naming it: "Use at least 10 characters." Sign-in
+  never checks the length, so raising it locks nobody out.
+- Creating and deleting users are writes: past the project's daily write
+  limit they answer `429 WRITE_QUOTA_EXCEEDED`, like sign-up.
+- A backend turned on before these existed gets them with its next upload:
+  run `naro backend enable` once. Until then `auth.admin` and
+  `signIn({ username })` answer `404 NOT_FOUND`.
 
 ## 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.
+project has set them up (`naro backend auth`). Email and password sign-up
+and sign-in need none of it. The names follow supabase-js.
 
 ```ts
 // Sends the browser to the project's /_naro/v1/auth/authorize/github, then
@@ -331,4 +452,67 @@ await naro.from("posts").select().contains("tags", ["a", "b"]);
 - 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.
+  them) and compiles to at most 100,000 bytes of SQL. A `like` or `ilike`
+  pattern is at most 50 bytes of UTF-8, which is D1's limit; in `like`, a
+  literal `?` or `[` counts as 3. A longer one is `400 INVALID_QUERY` before
+  the database is asked.
+
+## Storage
+
+Files your users upload — avatars, attachments, documents — go in the
+project's Storage: Cloudflare R2 behind the same URL, under policies on
+`storage.objects` written as in Supabase. Turn it on with
+`naro storage enable` (the backend must be on), make buckets with
+`naro storage bucket create avatars --public`, and write the policies in a
+migration that `naro db push` applies:
+
+```sql
+create policy "avatars are readable" on storage.objects
+  for select to public using (bucket_id = 'avatars');
+create policy "upload into own folder" on storage.objects
+  for insert to authenticated
+  with check (bucket_id = 'avatars' and (storage.foldername(name))[1] = auth.uid()::text);
+```
+
+```ts
+const avatars = naro.storage.from("avatars");
+await avatars.upload(`${user.id}/me.png`, file, { upsert: true });
+const { data: image } = avatars.getPublicUrl(`${user.id}/me.png`); // no request
+const { data: files } = await avatars.list(user.id, { limit: 20 });
+await avatars.remove([`${user.id}/old.png`]);
+const { data: link } = await naro.storage
+  .from("docs")
+  .createSignedUrl("team-1/plan.pdf", 600);
+```
+
+- `upload`, `update`, `download`, `info`, `exists`, `list`, `remove`,
+  `createSignedUrl` and `getPublicUrl` take supabase-js's arguments and
+  answer its shapes (`FileObject` in snake_case), as `{ data, error }`.
+  One exception: supabase-js's `info` answers a camelCase object
+  (`bucketId`, `createdAt`, `size`, `contentType`, …); naro-js's `info`
+  answers the same snake_case `FileObject` as `list`, with the size and type
+  in `metadata.size` and `metadata.mimetype`.
+- An upload sends the file's own bytes, 50 MiB at most, typed as the file
+  is (`Blob.type`, or `application/octet-stream`; a string is
+  `text/plain;charset=utf-8`). The body is a `Blob`, `File`, `ArrayBuffer`,
+  typed array or string — not a stream or `FormData`, and not a buffer
+  transferred away (detached), which has no bytes left: `INVALID_BODY`.
+- A `contentType` or `cacheControl` no header can carry (a CR, LF or NUL
+  inside, or a character past U+00FF) is answered before a request, as the
+  backend answers one it cannot read: `INVALID_CONTENT_TYPE`, and
+  `INVALID_REQUEST` with `details.path` `cache-control`.
+- supabase-js's `upload(path, file)` sends `multipart/form-data`, which Naro
+  refuses with `400 INVALID_REQUEST`. Without naro-js, send the file's bytes
+  as the body of `POST /_naro/v1/storage/object/<bucket>/<path>`.
+- Refused before a request, with the backend's own words (`INVALID_PATH`):
+  an empty path, a `/` at either end, `//`, a `.` or `..` segment, a lone
+  surrogate (`is not valid UTF-8`: no URL can carry it), and a bucket named
+  `""`, `.`, `..`, with a lone surrogate or a word the storage routes use
+  (`The bucket name is not valid.`). Everything else is the backend's to
+  check.
+- `exists` answers `false` for `OBJECT_NOT_FOUND` and passes every other
+  error on. `getPublicUrl` makes no request and answers `{ data, error }`.
+- `OBJECT_RATE_LIMITED` and `STORAGE_OPS_QUOTA_EXCEEDED` carry
+  `details.retryAfter`, in seconds.
+- Not yet: `move`, `copy`, `createSignedUrls`, `list`'s `search`, files over
+  50 MiB, and bucket methods (buckets are made with `naro storage bucket`).

package/dist/auth/admin.d.ts

@@ -0,0 +1,23 @@
+import { type HttpConfig } from "../http.js";
+import type { AdminUserAttributes, AdminUserListResponse, AdminUserResponse, PageParams } from "../types.js";
+export declare class AuthAdminApi {
+    #private;
+    constructor(http: HttpConfig, serviceKey: boolean);
+    /**
+     * Creates a user with a password: an email, a username or both. It is
+     * made while sign-ups are closed too, and is confirmed unless
+     * `emailConfirm: false`. A username-only user answers `email: null` and
+     * signs in with `signIn({ username, password })`. Refusals come as the
+     * worker says them: USERNAME_TAKEN (409),
+     * USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL (422), PASSWORD_TOO_SHORT ("Use at
+     * least {n} characters."), VALIDATION_ERROR, WRITE_QUOTA_EXCEEDED (429).
+     */
+    createUser(attributes: AdminUserAttributes): Promise<AdminUserResponse>;
+    /** The project's users, newest first: page 1 and 50 a page unless given. */
+    listUsers(params?: PageParams): Promise<AdminUserListResponse>;
+    /**
+     * Deletes a user and its sign-in methods, and ends its sessions. Answers
+     * the user it was; USER_NOT_FOUND (404) for an id that is no user.
+     */
+    deleteUser(id: string): Promise<AdminUserResponse>;
+}

package/dist/auth/client.d.ts

@@ -1,9 +1,10 @@
 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 { AuthAdminApi } from "./admin.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. */
+/** Sign-up needs a `name`; 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. */
@@ -24,24 +25,42 @@ export type AuthFlowStores = {
         storage: object;
         key: string;
     };
+    /** Made with the service key: `admin` sends its requests. */
+    serviceKey: boolean;
 };
 /** 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.
+ * `naro.auth` — naro Auth, the project's own sign-in (like Supabase Auth):
+ * email or username and password, email confirmation, password reset and
+ * provider sign-in through the worker's `/_naro/v1/auth/*` routes (spec
+ * §8.1, §13; P2-6 §13.3; 2026-09-26 §2.3). Email and password work with no
+ * setup; email is needed only to send confirmation and reset links. Every
+ * method resolves; none throws.
  */
 export declare class AuthClient {
     #private;
+    /**
+     * The service key's user management — createUser, listUsers, deleteUser,
+     * as in supabase-js (spec 2026-09-26 §2.2). Only on a client made with
+     * `serviceKey`, on a server.
+     */
+    readonly admin: AuthAdminApi;
     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.
+     * While the project's sign-ups are closed every sign-up answers 403
+     * SIGNUPS_DISABLED; while they are open, a taken `username` answers 409
+     * USERNAME_TAKEN.
      */
     signUp(credentials: SignUpCredentials): Promise<UserResponse>;
+    /**
+     * Signs in with an email and password, or a username and password (spec
+     * 2026-09-26 §2.3); the token is stored for later calls. A wrong password
+     * answers 401 INVALID_EMAIL_OR_PASSWORD, or INVALID_USERNAME_OR_PASSWORD.
+     */
     signIn(credentials: SignInCredentials): Promise<UserResponse>;
     /**
      * Starts a Google or GitHub sign-in: sends the browser, with a top-level

package/dist/auth/flows.d.ts

@@ -1,5 +1,5 @@
 import type { TokenStore } from "./storage.js";
-/** A flow's life: the worker's flow row and Better Auth's state. */
+/** A flow's life: the worker's flow row and its sign-in state. */
 export declare const FLOW_TTL_MS: number;
 /** More in flight than anyone clicks; the oldest go first. */
 export declare const MAX_FLOWS = 10;

package/dist/client.d.ts

@@ -2,6 +2,7 @@ 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 { StorageClient } from "./storage/client.js";
 import type { DatabaseShape, InsertOf, RowOf, TableName, TablesOf, UntypedDatabase, UpdateOf } from "./types.js";
 type CommonOptions = {
     /**
@@ -46,8 +47,17 @@ export declare const CONFIG_MESSAGES: {
 };
 export declare class NaroClient<Database extends DatabaseShape<Database>> {
     #private;
-    /** Sign-up, sign-in, sign-out and the current user (spec §13). */
+    /**
+     * Sign-up, sign-in, sign-out and the current user (spec §13); with the
+     * service key, `auth.admin` manages users.
+     */
     readonly auth: AuthClient;
+    /**
+     * Files in the project's Naro Storage (first-release design 2026-10-06
+     * §8.1): `storage.from(bucket)` uploads, downloads, lists and removes
+     * them, as supabase-js does.
+     */
+    readonly storage: StorageClient;
     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]>>;

package/dist/errors.d.ts

@@ -1,12 +1,16 @@
+import type { AuthErrorCode } from "./types.js";
 /**
  * Every failure the SDK hands back (spec §15). The Naro worker's errors
  * (spec §14) arrive as they are; the SDK makes its own only for what never
  * got a readable answer from the worker, and for queries it can tell are
  * malformed before sending them. The messages are a contract — spec §15's
  * "(P1-4 구현 결정)" block quotes them.
+ *
+ * `code` can be any string. The sign-in and user codes an app branches on
+ * (`AuthErrorCode`) are spelled out, so an editor completes them.
  */
 export type NaroError = {
-    code: string;
+    code: AuthErrorCode | (string & {});
     message: string;
     details?: unknown;
 };
@@ -37,15 +41,21 @@ export declare function codeVerifierMissing(): NaroError;
 export declare function passwordRecoveryRequired(): NaroError;
 /** `signInWithOAuth` with a provider the worker does not know. */
 export declare function invalidProvider(): NaroError;
+/**
+ * `naro.auth.admin` on a client made with the anon key (spec 2026-09-26
+ * admin users §2.2): the worker's own refusal, word for word, without the
+ * request — the answer would be the same.
+ */
+export declare function serviceKeyRequired(): NaroError;
 /** No `crypto.subtle`: an http page that is not localhost. */
 export declare function cryptoUnavailable(): NaroError;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /**
  * The error a response carries, or null when it carries none. Every error
  * under `/_naro/v1` comes as `{ data: null, error: { code, message,
- * details? } }` — the worker wraps Better Auth's too (spec §14, P1-2 리뷰
- * 반영). Better Auth's success bodies are not wrapped, so a 2xx without an
- * `error` is not an error; a failing status without the envelope is not a
- * Naro answer at all (a proxy's HTML page, the app's own 404).
+ * details? } }` — the sign-in routes' too (spec §14, P1-2 리뷰 반영). Their
+ * success bodies are not wrapped, so a 2xx without an `error` is not an
+ * error; a failing status without the envelope is not a Naro answer at all
+ * (a proxy's HTML page, the app's own 404).
  */
 export declare function errorFromBody(status: number, body: unknown): NaroError | null;

package/dist/http.d.ts

@@ -15,7 +15,7 @@ export type HttpConfig = {
     tokens: TokenStore;
 };
 export type CallOptions = {
-    method: "GET" | "POST";
+    method: "GET" | "POST" | "DELETE";
     /** Below `/_naro/v1`, e.g. `/data/query`. */
     path: string;
     /** Sent as JSON. */
@@ -53,9 +53,32 @@ export type CallResult = {
  * §11.1), but only if it is still the token this request carried.
  */
 export declare function call(config: HttpConfig, options: CallOptions): Promise<CallResult>;
+export type SendOptions = {
+    method: "GET" | "POST" | "PUT";
+    /** Below `/_naro/v1`, e.g. `/storage/object/avatars/me.png`. */
+    path: string;
+    headers?: Record<string, string>;
+    body?: BodyInit;
+    withToken: boolean;
+};
+export type SendResult = {
+    error: NaroError;
+} | {
+    error: null;
+    response: Response;
+};
+/**
+ * A request whose body or answer is not JSON (Storage, first-release design
+ * 2026-10-06 §8.1): an upload's bytes go as they are, a download's come
+ * back unread. The same `apikey`, bearer token and no cookies as `call`;
+ * a failing answer is read the way `call` reads one — the worker's error
+ * envelope, or INVALID_RESPONSE — and every case resolves.
+ */
+export declare function send(config: HttpConfig, options: SendOptions): Promise<SendResult>;
 /**
- * The worker's two 429s. `RATE_LIMITED` is Better Auth's limiter;
- * `WRITE_QUOTA_EXCEEDED` (PR C) is the project over its daily database write
- * limit — Data API writes and sign-up wait for 00:00 UTC, reads still work.
+ * The worker's 429s that say how long to wait. `RATE_LIMITED` is the
+ * sign-in routes' per-address limiter; `WRITE_QUOTA_EXCEEDED` (PR C) is the
+ * project over its daily database write limit — Data API writes, sign-up
+ * and creating or deleting users wait for 00:00 UTC, reads still work.
  */
 export declare const RETRY_AFTER_CODES: ReadonlySet<string>;

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 export { createClient, NaroClient, type ClientOptions } from "./client.js";
+export type { AuthAdminApi } from "./auth/admin.js";
 export type { AuthClient } from "./auth/client.js";
 export type { AuthStorage } from "./auth/storage.js";
 export type { NaroError } from "./errors.js";
 export type { FetchLike } from "./http.js";
+export type { StorageClient, StorageFileApi } from "./storage/client.js";
+export type { DownloadOption, FileObject, FolderEntry, ListOptions, UpdateOptions, UploadBody, UploadOptions, UploadResult, } from "./storage/types.js";
 export type { ArrayValues, FilterGroup, FilterGroupCallback, InsertBuilder, MatchQuery, MutationBuilder, RawFilterValue, SelectBuilder, TableBuilder, } from "./query/builder.js";
 export { quoteFilterValue, type FilterOperatorName } from "./query/filters.js";
-export type { AuthActionResponse, AuthFlowType, AuthResponse, DatabaseShape, EmailRedirectOptions, OAuthProvider, OAuthResponse, SignInWithOAuthOptions, UrlSessionResponse, UserAttributes, GenericTable, GenericView, NaroResponse, OrderOptions, Session, SessionResponse, SignInCredentials, SignOutResponse, SignUpCredentials, UntypedDatabase, User, UserResponse, } from "./types.js";
+export type { AdminUser, AdminUserAttributes, AdminUserListResponse, AdminUserResponse, AuthActionResponse, AuthErrorCode, AuthFlowType, AuthResponse, DatabaseShape, EmailRedirectOptions, OAuthProvider, OAuthResponse, SignInWithOAuthOptions, UrlSessionResponse, UserAttributes, GenericTable, GenericView, NaroResponse, OrderOptions, PageParams, Session, SessionResponse, SignInCredentials, SignOutResponse, SignUpCredentials, UntypedDatabase, User, UserResponse, } from "./types.js";
 export type { Filter, FilterNode, FilterOperator, Order, Query, Row, Value, } from "./wire.js";