naro-js 0.2.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.
@@ -78,6 +78,45 @@ await naro.from("posts").delete().eq("id", 10);
 - 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
 
@@ -413,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/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 = {
     /**
@@ -51,6 +52,12 @@ export declare class NaroClient<Database extends DatabaseShape<Database>> {
      * 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/http.d.ts

@@ -53,10 +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 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.
+ * 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

@@ -4,6 +4,8 @@ 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 { 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";

package/dist/index.js

@@ -158,15 +158,65 @@ async function call(config, options) {
   const answer = { status, headers: responseHeaders, body, token };
   const error = errorFromBody(status, body);
   if (error === null) return { error: null, answer };
+  return {
+    error: await settled(config, error, responseHeaders, token),
+    answer
+  };
+}
+async function settled(config, error, headers, token) {
   if (error.code === "INVALID_SESSION" && token !== null)
     await config.tokens.clearIf(token);
-  if (RETRY_AFTER_CODES.has(error.code))
-    return { error: withRetryAfter(error, responseHeaders), answer };
-  return { error, answer };
+  return RETRY_AFTER_CODES.has(error.code) ? withRetryAfter(error, headers) : error;
+}
+async function send(config, options) {
+  const token = options.withToken ? await config.tokens.get() : null;
+  const headers = {
+    ...options.headers,
+    apikey: config.apiKey
+  };
+  if (token !== null) headers.Authorization = `Bearer ${token}`;
+  const init = {
+    method: options.method,
+    headers,
+    credentials: "omit"
+  };
+  if (options.body !== void 0) init.body = options.body;
+  let response;
+  try {
+    const fetchImpl = config.fetch ?? globalThis.fetch;
+    response = await fetchImpl(
+      `${config.baseUrl}/_naro/v1${options.path}`,
+      init
+    );
+  } catch (error2) {
+    return { error: networkError(error2) };
+  }
+  if (response.status >= 200 && response.status < 300)
+    return { error: null, response };
+  let text;
+  try {
+    text = await response.text();
+  } catch (error2) {
+    return { error: networkError(error2) };
+  }
+  let body;
+  if (text.trim() !== "") {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      return { error: invalidResponse(response.status) };
+    }
+  }
+  const error = errorFromBody(response.status, body) ?? invalidResponse(response.status);
+  return { error: await settled(config, error, response.headers, token) };
 }
 var RETRY_AFTER_CODES = /* @__PURE__ */ new Set([
   "RATE_LIMITED",
-  "WRITE_QUOTA_EXCEEDED"
+  "WRITE_QUOTA_EXCEEDED",
+  // Storage (original spec §13): one object written twice within a second
+  // (`x-retry-after: 1`), and the daily operation limit (3-1d).
+  "OBJECT_RATE_LIMITED",
+  "STORAGE_OPS_QUOTA_EXCEEDED"
 ]);
 function withRetryAfter(error, headers) {
   const header = headers.get("x-retry-after")?.trim() ?? "";
@@ -1756,6 +1806,379 @@ var TableBuilder = class {
   }
 };
 
+// src/storage/path.ts
+var MAX_SINGLE_UPLOAD_BYTES = 52428800;
+var STORAGE_MESSAGES = {
+  bucket: "The bucket name is not valid.",
+  tooLarge: "Uploads over 50 MiB are not supported yet.",
+  request: "The storage request is not valid.",
+  body: "upload takes a Blob, File, ArrayBuffer, typed array or string."
+};
+var RESERVED_BUCKETS = /* @__PURE__ */ new Set([
+  "authenticated",
+  "copy",
+  "info",
+  "list",
+  "move",
+  "public",
+  "render",
+  "sign",
+  "upload"
+]);
+var DOWNLOAD_NAME_REASON = "must be a file name of up to 255 bytes";
+var LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/;
+var OCTET_STREAM = "application/octet-stream";
+var UTF8_TEXT = "text/plain;charset=utf-8";
+function invalidPath(reason) {
+  return {
+    code: "INVALID_PATH",
+    message: `The object path is not valid: it ${reason}.`
+  };
+}
+function objectTooLarge() {
+  return { code: "OBJECT_TOO_LARGE", message: STORAGE_MESSAGES.tooLarge };
+}
+function encodePath(path) {
+  if (typeof path !== "string" || path === "")
+    return { ok: false, error: invalidPath("is empty") };
+  if (LONE_SURROGATE.test(path))
+    return { ok: false, error: invalidPath("is not valid UTF-8") };
+  if (path.startsWith("/") || path.endsWith("/"))
+    return { ok: false, error: invalidPath("starts or ends with /") };
+  if (path.includes("//"))
+    return { ok: false, error: invalidPath("has an empty segment (//)") };
+  const segments = path.split("/");
+  if (segments.some((segment) => segment === "." || segment === ".."))
+    return { ok: false, error: invalidPath("has a . or .. segment") };
+  return { ok: true, encoded: segments.map(encodeURIComponent).join("/") };
+}
+function downloadQuery(download) {
+  if (download === true) return { ok: true, encoded: "?download" };
+  if (typeof download !== "string") return { ok: true, encoded: "" };
+  if (LONE_SURROGATE.test(download))
+    return {
+      ok: false,
+      error: {
+        code: "INVALID_REQUEST",
+        message: STORAGE_MESSAGES.request,
+        details: { path: "download", reason: DOWNLOAD_NAME_REASON }
+      }
+    };
+  return { ok: true, encoded: `?download=${encodeURIComponent(download)}` };
+}
+function encodeBucket(bucket) {
+  if (typeof bucket !== "string" || bucket === "" || bucket === "." || bucket === ".." || LONE_SURROGATE.test(bucket) || RESERVED_BUCKETS.has(bucket))
+    return {
+      ok: false,
+      error: { code: "INVALID_PATH", message: STORAGE_MESSAGES.bucket }
+    };
+  return { ok: true, encoded: encodeURIComponent(bucket) };
+}
+var isArrayBuffer = (value) => Object.prototype.toString.call(value) === "[object ArrayBuffer]";
+function isDetached(buffer) {
+  if (!isArrayBuffer(buffer)) return false;
+  const flag = buffer.detached;
+  if (typeof flag === "boolean") return flag;
+  if (buffer.byteLength > 0) return false;
+  try {
+    buffer.slice(0);
+    return false;
+  } catch {
+    return true;
+  }
+}
+var CACHE_CONTROL_REASON = "must be max-age=<seconds> from 0 to 31536000";
+var MAX_TYPE_IN_MESSAGE = 256;
+function unsendable(value) {
+  return /[\0\r\n]|[^\0-\xff]/.test(
+    value.replace(/^[\t\n\r ]+|[\t\n\r ]+$/g, "")
+  );
+}
+function headerProblem(contentType, cacheControl) {
+  if (typeof contentType === "string" && unsendable(contentType)) {
+    let shown = contentType;
+    if (shown.length > MAX_TYPE_IN_MESSAGE) {
+      shown = shown.slice(0, MAX_TYPE_IN_MESSAGE);
+      if (/[\ud800-\udbff]$/.test(shown)) shown = shown.slice(0, -1);
+    }
+    return {
+      code: "INVALID_CONTENT_TYPE",
+      message: `Content-Type ${shown} is not a media type like image/png.`
+    };
+  }
+  if (unsendable(cacheControl))
+    return {
+      code: "INVALID_REQUEST",
+      message: STORAGE_MESSAGES.request,
+      details: { path: "cache-control", reason: CACHE_CONTROL_REASON }
+    };
+  return null;
+}
+function payloadOf(body, contentType) {
+  if (typeof body === "string") {
+    const bytes = new TextEncoder().encode(body);
+    return {
+      ok: true,
+      body: bytes,
+      size: bytes.byteLength,
+      type: contentType ?? UTF8_TEXT
+    };
+  }
+  if (typeof Blob === "function" && body instanceof Blob)
+    return {
+      ok: true,
+      body,
+      size: body.size,
+      type: contentType ?? (body.type === "" ? OCTET_STREAM : body.type)
+    };
+  if (isArrayBuffer(body) && !isDetached(body))
+    return {
+      ok: true,
+      body,
+      size: body.byteLength,
+      type: contentType ?? OCTET_STREAM
+    };
+  if (ArrayBuffer.isView(body) && !isDetached(body.buffer)) {
+    const { buffer, byteOffset, byteLength } = body;
+    const bytes = isArrayBuffer(buffer) ? new Uint8Array(buffer, byteOffset, byteLength) : Uint8Array.from(new Uint8Array(buffer, byteOffset, byteLength));
+    return {
+      ok: true,
+      body: bytes,
+      size: byteLength,
+      type: contentType ?? OCTET_STREAM
+    };
+  }
+  return {
+    ok: false,
+    error: { code: "INVALID_BODY", message: STORAGE_MESSAGES.body }
+  };
+}
+
+// src/storage/client.ts
+var SIGNED_PREFIX = "/_naro/v1/storage/object/sign/";
+function fail(error) {
+  return { data: null, error };
+}
+var isUploadResult = (value) => isRecord(value) && typeof value.id === "string" && typeof value.path === "string" && typeof value.fullPath === "string";
+var isFileObject = (value) => isRecord(value) && typeof value.id === "string" && typeof value.name === "string" && isRecord(value.metadata);
+var isEntry2 = (value) => isRecord(value) && typeof value.name === "string" && (value.id === null || isFileObject(value));
+var isSigned = (value) => isRecord(value) && typeof value.signedUrl === "string" && value.signedUrl.startsWith(SIGNED_PREFIX);
+function listOf(guard) {
+  return (value) => Array.isArray(value) && value.every(guard);
+}
+function dataOf2(status, body, guard) {
+  if (isRecord(body) && Object.hasOwn(body, "data") && guard(body.data))
+    return { data: body.data, error: null };
+  return fail(invalidResponse(status));
+}
+async function readJson(response, guard) {
+  let text;
+  try {
+    text = await response.text();
+  } catch (error) {
+    return fail(networkError(error));
+  }
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    return fail(invalidResponse(response.status));
+  }
+  return dataOf2(response.status, body, guard);
+}
+var StorageFileApi = class {
+  #http;
+  #auth;
+  #bucket;
+  constructor(http, auth, bucket) {
+    this.#http = http;
+    this.#auth = auth;
+    this.#bucket = bucket;
+  }
+  /** `/storage/object/<route><bucket>/<path>`, or the refusal no request needs. */
+  #objectPath(route, path) {
+    const bucket = encodeBucket(this.#bucket);
+    if (!bucket.ok) return bucket;
+    const name = encodePath(path);
+    if (!name.ok) return name;
+    return {
+      ok: true,
+      path: `/storage/object/${route}${bucket.encoded}/${name.encoded}`
+    };
+  }
+  /** `/storage/object/<route><bucket>`, for the routes that take names in the body. */
+  #bucketPath(route) {
+    const bucket = encodeBucket(this.#bucket);
+    if (!bucket.ok) return bucket;
+    return { ok: true, path: `/storage/object/${route}${bucket.encoded}` };
+  }
+  async #json(request, guard) {
+    await this.#auth.ready();
+    const result = await call(this.#http, { ...request, withToken: true });
+    if (result.error !== null) return fail(result.error);
+    return dataOf2(result.answer.status, result.answer.body, guard);
+  }
+  async #write(method, path, body, options, upsert) {
+    const target = this.#objectPath("", path);
+    if (!target.ok) return fail(target.error);
+    const payload = payloadOf(body, options.contentType);
+    if (!payload.ok) return fail(payload.error);
+    const cache = `max-age=${options.cacheControl ?? "3600"}`;
+    const unreadable = headerProblem(options.contentType, cache);
+    if (unreadable !== null) return fail(unreadable);
+    if (payload.size > MAX_SINGLE_UPLOAD_BYTES) return fail(objectTooLarge());
+    await this.#auth.ready();
+    const headers = {
+      "content-type": payload.type,
+      "cache-control": cache
+    };
+    if (upsert) headers["x-upsert"] = "true";
+    const sent = await send(this.#http, {
+      method,
+      path: target.path,
+      headers,
+      body: payload.body,
+      withToken: true
+    });
+    if (sent.error !== null) return fail(sent.error);
+    return readJson(sent.response, isUploadResult);
+  }
+  /**
+   * A new object; with `upsert: true`, one of the same name is replaced.
+   * `null` options, as a JS caller may pass, are no options.
+   */
+  upload(path, body, options = {}) {
+    const given = options ?? {};
+    return this.#write("POST", path, body, given, given.upsert === true);
+  }
+  /** Replaces an object that is there (`OBJECT_NOT_FOUND` otherwise). */
+  update(path, body, options = {}) {
+    return this.#write("PUT", path, body, options ?? {}, false);
+  }
+  /**
+   * The object's bytes, as a Blob of the type the worker serves it under:
+   * the stored type for the images, audio, video, PDF, plain text, CSV,
+   * JSON and SVG it serves as themselves, `application/octet-stream` for
+   * anything else (HTML, scripts, archives, unknown types — `info` and
+   * `list` hold the stored type).
+   */
+  async download(path) {
+    const target = this.#objectPath("", path);
+    if (!target.ok) return fail(target.error);
+    await this.#auth.ready();
+    const sent = await send(this.#http, {
+      method: "GET",
+      path: target.path,
+      withToken: true
+    });
+    if (sent.error !== null) return fail(sent.error);
+    try {
+      return { data: await sent.response.blob(), error: null };
+    } catch (error) {
+      return fail(networkError(error));
+    }
+  }
+  async info(path) {
+    const target = this.#objectPath("info/", path);
+    if (!target.ok) return fail(target.error);
+    return this.#json({ method: "GET", path: target.path }, isFileObject);
+  }
+  /**
+   * Whether the caller can see the object: `OBJECT_NOT_FOUND` is false,
+   * every other error comes back as it is (plan C1 — asked with `info`,
+   * not HEAD, whose answer has no body to tell a missing bucket from a
+   * missing object).
+   */
+  async exists(path) {
+    const found = await this.info(path);
+    if (found.error === null) return { data: true, error: null };
+    if (found.error.code === "OBJECT_NOT_FOUND")
+      return { data: false, error: null };
+    return fail(found.error);
+  }
+  /**
+   * What is directly below `prefix` (the whole bucket by default): folders
+   * first, then files. The options go to the worker as they are given.
+   */
+  async list(prefix, options = {}) {
+    const target = this.#bucketPath("list/");
+    if (!target.ok) return fail(target.error);
+    return this.#json(
+      {
+        method: "POST",
+        path: target.path,
+        body: { ...prefix === void 0 ? {} : { prefix }, ...options }
+      },
+      listOf(isEntry2)
+    );
+  }
+  /** Removes the objects named — 1 to 1,000 — and answers the ones it removed. */
+  async remove(paths) {
+    const target = this.#bucketPath("");
+    if (!target.ok) return fail(target.error);
+    return this.#json(
+      { method: "DELETE", path: target.path, body: { prefixes: paths } },
+      listOf(isFileObject)
+    );
+  }
+  /**
+   * A link to the object for `expiresIn` seconds (1–604,800). It stops
+   * working once the object is replaced or removed.
+   */
+  async createSignedUrl(path, expiresIn, options = {}) {
+    const target = this.#objectPath("sign/", path);
+    if (!target.ok) return fail(target.error);
+    const { download } = options ?? {};
+    const signed = await this.#json(
+      {
+        method: "POST",
+        path: target.path,
+        body: {
+          expiresIn,
+          ...download === void 0 || download === false ? {} : { download }
+        }
+      },
+      isSigned
+    );
+    if (signed.error !== null) return signed;
+    return {
+      data: { signedUrl: `${this.#http.baseUrl}${signed.data.signedUrl}` },
+      error: null
+    };
+  }
+  /**
+   * A public bucket's URL for the object. No request is made, so whether
+   * the bucket is public is not checked (as in supabase-js); a path no URL
+   * can carry is INVALID_PATH (plan C3), and a download name none can carry
+   * is the worker's INVALID_REQUEST for it.
+   */
+  getPublicUrl(path, options = {}) {
+    const target = this.#objectPath("public/", path);
+    if (!target.ok) return fail(target.error);
+    const { download } = options ?? {};
+    const query = downloadQuery(download);
+    if (!query.ok) return fail(query.error);
+    return {
+      data: {
+        publicUrl: `${this.#http.baseUrl}/_naro/v1${target.path}${query.encoded}`
+      },
+      error: null
+    };
+  }
+};
+var StorageClient = class {
+  #http;
+  #auth;
+  constructor(http, auth) {
+    this.#http = http;
+    this.#auth = auth;
+  }
+  /** The objects of one bucket. */
+  from(bucket) {
+    return new StorageFileApi(this.#http, this.#auth, bucket);
+  }
+};
+
 // src/client.ts
 var CONFIG_MESSAGES = {
   url: "createClient needs the project url, like https://my-app.naro.sh.",
@@ -1815,9 +2238,13 @@ var NaroClient = class {
    * service key, `auth.admin` manages users.
    */
   auth;
+  /**
+   * 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.
+   */
+  storage;
   #run;
-  // naro.storage — Phase 3 (spec §18): R2 storage lands here, beside `auth`
-  // and `from()`. Deliberately absent in Phase 1: not implemented, not typed.
   constructor(options) {
     const baseUrl = baseUrlOf(options.url);
     const { key: apiKey, service } = apiKeyOf(options);
@@ -1842,6 +2269,7 @@ var NaroClient = class {
       serviceKey: service
     });
     this.#run = queryRunner(http, this.auth);
+    this.storage = new StorageClient(http, this.auth);
   }
   /** Start a query on `table`: `.select()`, `.insert()`, `.update()` or `.delete()`. */
   from(table) {

package/dist/storage/client.d.ts

@@ -0,0 +1,65 @@
+import type { AuthClient } from "../auth/client.js";
+import { type HttpConfig } from "../http.js";
+import type { NaroResponse } from "../types.js";
+import type { DownloadOption, FileObject, FolderEntry, ListOptions, UpdateOptions, UploadBody, UploadOptions, UploadResult } from "./types.js";
+/** One bucket's objects: supabase-js's StorageFileApi. */
+export declare class StorageFileApi {
+    #private;
+    constructor(http: HttpConfig, auth: AuthClient, bucket: string);
+    /**
+     * A new object; with `upsert: true`, one of the same name is replaced.
+     * `null` options, as a JS caller may pass, are no options.
+     */
+    upload(path: string, body: UploadBody, options?: UploadOptions): Promise<NaroResponse<UploadResult>>;
+    /** Replaces an object that is there (`OBJECT_NOT_FOUND` otherwise). */
+    update(path: string, body: UploadBody, options?: UpdateOptions): Promise<NaroResponse<UploadResult>>;
+    /**
+     * The object's bytes, as a Blob of the type the worker serves it under:
+     * the stored type for the images, audio, video, PDF, plain text, CSV,
+     * JSON and SVG it serves as themselves, `application/octet-stream` for
+     * anything else (HTML, scripts, archives, unknown types — `info` and
+     * `list` hold the stored type).
+     */
+    download(path: string): Promise<NaroResponse<Blob>>;
+    info(path: string): Promise<NaroResponse<FileObject>>;
+    /**
+     * Whether the caller can see the object: `OBJECT_NOT_FOUND` is false,
+     * every other error comes back as it is (plan C1 — asked with `info`,
+     * not HEAD, whose answer has no body to tell a missing bucket from a
+     * missing object).
+     */
+    exists(path: string): Promise<NaroResponse<boolean>>;
+    /**
+     * What is directly below `prefix` (the whole bucket by default): folders
+     * first, then files. The options go to the worker as they are given.
+     */
+    list(prefix?: string, options?: ListOptions): Promise<NaroResponse<(FileObject | FolderEntry)[]>>;
+    /** Removes the objects named — 1 to 1,000 — and answers the ones it removed. */
+    remove(paths: string[]): Promise<NaroResponse<FileObject[]>>;
+    /**
+     * A link to the object for `expiresIn` seconds (1–604,800). It stops
+     * working once the object is replaced or removed.
+     */
+    createSignedUrl(path: string, expiresIn: number, options?: DownloadOption): Promise<NaroResponse<{
+        signedUrl: string;
+    }>>;
+    /**
+     * A public bucket's URL for the object. No request is made, so whether
+     * the bucket is public is not checked (as in supabase-js); a path no URL
+     * can carry is INVALID_PATH (plan C3), and a download name none can carry
+     * is the worker's INVALID_REQUEST for it.
+     */
+    getPublicUrl(path: string, options?: DownloadOption): NaroResponse<{
+        publicUrl: string;
+    }>;
+}
+/**
+ * `naro.storage`. Buckets are made with `naro storage bucket create` or the
+ * MCP server, never from a client (original spec §6).
+ */
+export declare class StorageClient {
+    #private;
+    constructor(http: HttpConfig, auth: AuthClient);
+    /** The objects of one bucket. */
+    from(bucket: string): StorageFileApi;
+}

package/dist/storage/path.d.ts

@@ -0,0 +1,76 @@
+import type { NaroError } from "../errors.js";
+/**
+ * The most one upload request carries (original spec §9.1): 50 MiB.
+ * data-core's MAX_SINGLE_UPLOAD_BYTES — storage/wire.test.ts holds them
+ * equal. Over it, the edge cuts the body off and the browser often cannot
+ * read the answer: the SDK refuses first.
+ */
+export declare const MAX_SINGLE_UPLOAD_BYTES = 52428800;
+/** The worker's words (data-core's catalog) for what the SDK refuses itself. */
+export declare const STORAGE_MESSAGES: {
+    readonly bucket: "The bucket name is not valid.";
+    readonly tooLarge: "Uploads over 50 MiB are not supported yet.";
+    readonly request: "The storage request is not valid.";
+    readonly body: "upload takes a Blob, File, ArrayBuffer, typed array or string.";
+};
+/**
+ * The words the worker's routes take as the first segment after `/object/`
+ * (data-core's STORAGE_RESERVED_WORDS): as a bucket, the URL would name
+ * another route. No bucket can have one of these names.
+ */
+export declare const RESERVED_BUCKETS: ReadonlySet<string>;
+/** Why the worker refuses a `download` name (serve.ts's DOWNLOAD_NAME_REASON). */
+export declare const DOWNLOAD_NAME_REASON = "must be a file name of up to 255 bytes";
+export type Encoded = {
+    ok: true;
+    encoded: string;
+} | {
+    ok: false;
+    error: NaroError;
+};
+export declare function invalidPath(reason: string): NaroError;
+export declare function objectTooLarge(): NaroError;
+/**
+ * An object path as a URL carries it, each segment encoded once and `/`
+ * kept as the separator — or the worker's INVALID_PATH for the paths no
+ * URL can carry as they are (original spec §13, plan C2): an empty name, a
+ * `/` at either end, `//`, a `.` or `..` segment (WHATWG URL parsing folds
+ * `..` and `%2E%2E` alike, so the worker would get another path), and a
+ * lone surrogate (`encodeURIComponent` throws on one). Every other rule is
+ * the worker's alone — one set of rules, in one place.
+ */
+export declare function encodePath(path: string): Encoded;
+/**
+ * `?download` for the object's own name, `?download=<name>` for another, or
+ * the worker's own INVALID_REQUEST for a name `encodeURIComponent` throws on
+ * (a lone surrogate: the sign route refuses the same name in its body). Every
+ * other rule on the name is the worker's alone.
+ */
+export declare function downloadQuery(download: boolean | string | undefined): Encoded;
+/**
+ * A bucket name as the URL's segment — encoded (a valid name is unchanged
+ * by it), or INVALID_PATH for the names that would not reach a bucket:
+ * empty, `.`, `..`, a lone surrogate and the routes' own words.
+ */
+export declare function encodeBucket(bucket: string): Encoded;
+/** Why the worker refuses a cache-control it cannot read (its upload.ts). */
+export declare const CACHE_CONTROL_REASON = "must be max-age=<seconds> from 0 to 31536000";
+/**
+ * The upload's `contentType` and `cacheControl` as headers, or the worker's
+ * answer for a value it cannot read when no header can carry it (PR #90
+ * review 1): INVALID_CONTENT_TYPE with data-core's words (the type cut at
+ * 256 UTF-16 units, as `storageName` cuts it), and INVALID_REQUEST
+ * `cache-control`. Every other value is the worker's to judge.
+ */
+export declare function headerProblem(contentType: string | undefined, cacheControl: string): NaroError | null;
+export type Payload = {
+    ok: true;
+    body: Blob | ArrayBuffer | Uint8Array<ArrayBuffer>;
+    size: number;
+    type: string;
+} | {
+    ok: false;
+    error: NaroError;
+};
+/** The upload's body, its bytes and its type — or INVALID_BODY. */
+export declare function payloadOf(body: unknown, contentType: string | undefined): Payload;

package/dist/storage/types.d.ts

@@ -0,0 +1,58 @@
+/** An object as the worker answers it. */
+export type FileObject = {
+    id: string;
+    /** The full path from `info` and `remove`; the name below the prefix in `list`. */
+    name: string;
+    bucket_id: string;
+    /** Who uploaded it; null for the anon or the service key. */
+    owner: string | null;
+    owner_id: string | null;
+    /** The bytes' etag. */
+    version: string;
+    created_at: string;
+    updated_at: string;
+    /** `eTag`, `size`, `mimetype`, `cacheControl`, `lastModified`, `contentLength`, `httpStatusCode`. */
+    metadata: Record<string, unknown>;
+};
+/** A folder in a listing: a name and nothing else. Folders come first. */
+export type FolderEntry = {
+    name: string;
+    id: null;
+    created_at: null;
+    updated_at: null;
+    metadata: null;
+};
+/**
+ * What an upload sends: bytes whose length `fetch` knows, so it sets
+ * `Content-Length`. A string goes as UTF-8. Not a stream, not `FormData`.
+ */
+export type UploadBody = Blob | ArrayBuffer | ArrayBufferView | string;
+export type UploadOptions = {
+    /** Default: the Blob's type, `text/plain;charset=utf-8` for a string, else `application/octet-stream`. */
+    contentType?: string;
+    /** Seconds a browser may keep it, as text. Default `"3600"`. */
+    cacheControl?: string;
+    /** Replace an object of the same name. Default false. */
+    upsert?: boolean;
+};
+export type UpdateOptions = Omit<UploadOptions, "upsert">;
+export type UploadResult = {
+    id: string;
+    path: string;
+    fullPath: string;
+};
+export type ListOptions = {
+    /** 1–1,000; 100 by default. */
+    limit?: number;
+    /** 0–100,000. */
+    offset?: number;
+    /** Folders come first whatever the sort. Default name ascending. */
+    sortBy?: {
+        column?: "name" | "created_at" | "updated_at";
+        order?: "asc" | "desc";
+    };
+};
+/** `true` downloads under the object's own name, a string under that name. */
+export type DownloadOption = {
+    download?: boolean | string;
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "naro-js",
-  "version": "0.2.0",
-  "description": "Auth and data for your Naro project, from the browser or the server.",
+  "version": "0.3.0",
+  "description": "Auth, data and files for your Naro project, from the browser or the server.",
   "type": "module",
   "sideEffects": false,
   "files": [