naro-js 0.3.0 → 0.5.0

package/README.md

@@ -483,20 +483,129 @@ await avatars.remove([`${user.id}/old.png`]);
 const { data: link } = await naro.storage
   .from("docs")
   .createSignedUrl("team-1/plan.pdf", 600);
+const { data: links } = await naro.storage
+  .from("docs")
+  .createSignedUrls(["team-1/a.pdf", "team-1/b.pdf"], 600);
+const { data: plans } = await naro.storage
+  .from("docs")
+  .list("team-1", { search: "plan" });
 ```
 
 - `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 }`.
+  `createSignedUrl`, `createSignedUrls` 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`.
+- `createSignedUrls(paths, expiresIn, { download })` signs 1 to 100 paths in
+  one request (naro-js 0.5.0) and answers one `{ path, signedUrl, error }`
+  per path, in the order given — a path given twice is answered twice. A
+  file that is not there, or that the caller cannot read, has
+  `signedUrl: null` and the `error`
+  `Object <path> was not found in bucket <bucket>.` — the same words for
+  both. `signedUrl` is absolute, as `createSignedUrl`'s. The paths go in the
+  body unchecked: a bad one fails the call with `INVALID_REQUEST`
+  (`details.path` `paths[<i>]`). Unlike supabase-js, `download` goes in the
+  request — the token covers it — so adding `&download` to a URL afterwards
+  answers `400 INVALID_SIGNATURE`.
+- `list(prefix, { search })` keeps the names directly below `prefix` that
+  start with `search`. As in Supabase, `%` and `_` are plain characters, not
+  wildcards. Unlike Supabase, only ASCII letters ignore case (Postgres folds
+  case by the database's locale) and `search` takes up to 256 characters. A
+  folder shows when a name under it starts with `search`.
+- A backend whose Storage was turned on before these two came answers
+  `createSignedUrls` with `404 NOT_FOUND` and a `search` with
+  `400 INVALID_REQUEST` (`details.path` `search`, `details.reason`
+  `search is not supported yet`): update it once with `naro backend enable`.
+- A public file is kept at Naro's edge for up to 5 minutes (or for its own
+  `cacheControl`, when that is shorter): after it is deleted, its bucket is
+  made private or it is replaced, `getPublicUrl`'s URL can still serve the
+  old bytes that long. Put a version in names that change
+  (`avatar-<time>.png`) or keep `cacheControl` short. Signed URLs are not
+  kept at the edge: replacing or deleting a file ends its signed links at
+  once.
+- An upload sends the file's own bytes, 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`.
+- One request carries 50 MiB. A larger body goes in parts by itself, up to
+  the plan's largest object: 16–64 MiB parts, four at a time, each tried
+  again up to three times after `NETWORK_ERROR`, a `5xx` or
+  `OBJECT_RATE_LIMITED` (waiting 1, 2, then 4 seconds, or the seconds the
+  429 says) — not after `507 STORAGE_QUOTA_EXCEEDED`, which lasts until
+  files are deleted. A part that still fails fails the upload with its
+  error, and the upload is called off. The last step is never tried again: if its
+  answer is lost (`NETWORK_ERROR`), ask `info(path)` whether the file is
+  there; if the backend refuses it, the upload is called off too and the
+  refusal is the answer. A part answered `UPLOAD_NOT_FOUND` belongs to an
+  upload that has ended — one left unsent for about an hour has. An upload in
+  parts must finish within 24 hours of its start (R2 ends unfinished
+  multipart uploads after a day). Replacing a file in parts (`update`, or
+  `upload` with `upsert` over a file that is there) needs room in the
+  project's capacity for the old file and the new one until it completes: if
+  the two together are over it, the upload answers
+  `507 STORAGE_QUOTA_EXCEEDED` before any part is sent.
+- `onProgress: (sentBytes, totalBytes) => void` is called after each part
+  of an upload over 50 MiB, the last time with both the same. An upload of
+  50 MiB or less is one request and does not call it. A `File` is sliced
+  into the parts, never read whole first. What the callback throws — or an
+  `async` one rejects with — does not stop the upload.
+
+- `signal: AbortSignal` stops an upload (`upload` and `update`): what has
+  not been answered yet is called off, and the upload answers `ABORTED`
+  ("The upload was stopped before it finished."). An upload in parts is
+  called off on the backend too — no part starts after the signal, and
+  `onProgress` is not called again — so its name and the space it reserved
+  are free at once, not after the hour its lock lasts. Its first step is
+  never cut short (a signal during it is acted on once it answers), and once
+  its last step is sent the signal stops nothing: that step's answer is the
+  upload's. A signal already aborted sends nothing. A page closed or a
+  network lost mid-upload sends no abort: the name waits for the lock.
+
+```ts
+const stop = new AbortController();
+cancelButton.onclick = () => stop.abort();
+await naro.storage.from("videos").upload(`${user.id}/talk.mp4`, file, {
+  onProgress: (sent, total) => setPercent(Math.round((sent / total) * 100)),
+  signal: stop.signal,
+});
+```
+
+- `createSignedUploadUrl(path, { upsert })` and
+  `uploadToSignedUrl(path, token, body, options)` are supabase-js's signed
+  upload (naro-js 0.5.0). A server with the service key — or anyone the
+  policies let upload there, anon or a signed-in user — makes a token for
+  one path; a page with only the anon key uploads by it. The token stands
+  in for the policies; the bucket's and the plan's limits and the
+  project's usage stops still apply. It works for 2 hours. Made with
+  `upsert: true` it may replace the file until then; without it a second
+  upload answers `409 OBJECT_EXISTS`.
+  `uploadToSignedUrl` sends no session, takes `contentType`,
+  `cacheControl`, `onProgress` and `signal` as `upload` does, and answers
+  `{ path, fullPath }`. Over 50 MiB it goes in parts with the token on
+  every step (the `x-naro-upload-token` header), and once started may
+  finish after the 2 hours. A token that is not the path's answers
+  `400 INVALID_SIGNATURE` (one no URL can carry is refused so before a
+  request), an expired one `400 SIGNED_URL_EXPIRED`. A token is neither
+  used up nor revocable: until its 2 hours end it can create its file again
+  after the file is deleted, and it keeps working if the user it was made
+  for is deleted or banned.
+
+```ts
+// On the server, with the service key:
+const { data, error } = await admin.storage
+  .from("avatars")
+  .createSignedUploadUrl(`${userId}/me.png`, { upsert: true });
+if (error) throw new Error(error.message);
+// In the browser, with the anon key:
+await naro.storage
+  .from("avatars")
+  .uploadToSignedUrl(data.path, data.token, file);
+```
+
 - 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
@@ -512,7 +621,14 @@ const { data: link } = await naro.storage
   check.
 - `exists` answers `false` for `OBJECT_NOT_FOUND` and passes every other
   error on. `getPublicUrl` makes no request and answers `{ data, error }`.
+- `objectRoute(bucket, path)` names an object the way the client does:
+  `{ ok: true, encoded }` with `<bucket>/<path>` as the object routes carry
+  it (each segment `encodeURIComponent`-ed), or `{ ok: false, error }` with
+  the client's own `INVALID_PATH` (type `ObjectRouteResult`). A tool that
+  streams an object itself builds `/_naro/v1/storage/object/<encoded>` from
+  it and gets the URL and the refusals the client would — `naro storage cp`
+  downloads that way.
 - `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`).
+- Not yet: `move`, `copy`, resuming an upload in another session, and bucket
+  methods (buckets are made with `naro storage bucket`).

package/dist/auth/storage.d.ts

@@ -18,6 +18,8 @@ export declare function memoryStorage(): AuthStorage;
 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 access JWT of the signed-in session, beside the session token. */
+export declare function accessJwtKey(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.

package/dist/errors.d.ts

@@ -25,6 +25,11 @@ export declare function networkError(cause: unknown): NaroError;
  * code exchange a page runs on load (PR #68 review 10). It is called off.
  */
 export declare function requestTimeout(ms: number): NaroError;
+/**
+ * An upload the caller's `signal` stopped (PR #111 review r1): what was not
+ * answered yet was called off. Never tried again.
+ */
+export declare function uploadAborted(): NaroError;
 /** An answer, but not one a Naro worker gives: HTML, empty, or the wrong shape. */
 export declare function invalidResponse(status: number): NaroError;
 /**

package/dist/http.d.ts

@@ -13,13 +13,24 @@ export type HttpConfig = {
     apiKey: string;
     fetch: FetchLike | undefined;
     tokens: TokenStore;
+    /**
+     * The short-lived access JWT the sign-in answers carry. Data and Storage
+     * requests send it; the auth routes keep the session token in `tokens`.
+     * Without it (not signed in) those requests go as anon.
+     */
+    accessJwt?: TokenStore;
 };
 export type CallOptions = {
-    method: "GET" | "POST" | "DELETE";
+    method: "GET" | "POST" | "PUT" | "DELETE";
     /** Below `/_naro/v1`, e.g. `/data/query`. */
     path: string;
     /** Sent as JSON. */
     body?: unknown;
+    /**
+     * Headers beside `apikey` and the JSON type — a signed upload's
+     * `x-naro-upload-token` (Storage 3-1e-2). `apikey` is always the client's.
+     */
+    headers?: Record<string, string>;
     /** Whether to send the stored session token. */
     withToken: boolean;
     /**
@@ -60,9 +71,21 @@ export type SendOptions = {
     headers?: Record<string, string>;
     body?: BodyInit;
     withToken: boolean;
+    /**
+     * An upload's `signal` (PR #111 review r1): it calls the request off until
+     * its answer comes — ABORTED, not NETWORK_ERROR — and never the reading
+     * of an answer that came, which may be a success.
+     */
+    signal?: AbortSignal | undefined;
 };
+/**
+ * A failure carries the answer's HTTP status, or null when nothing answered
+ * (NETWORK_ERROR): a multipart upload tries a part again on a 5xx, whatever
+ * the body said (Storage 3-1f, plan C7).
+ */
 export type SendResult = {
     error: NaroError;
+    status: number | null;
 } | {
     error: null;
     response: Response;

package/dist/index.d.ts

@@ -5,7 +5,8 @@ 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 { objectRoute, type Encoded as ObjectRouteResult, } from "./storage/path.js";
+export type { CreateSignedUploadUrlOptions, DownloadOption, FileObject, FolderEntry, ListOptions, SignedUploadResult, SignedUploadUrl, SignedUrlEntry, 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

@@ -14,6 +14,12 @@ function requestTimeout(ms) {
     message: `The Naro backend did not answer within ${String(Math.round(ms / 1e3))} seconds. Check the network and try again.`
   };
 }
+function uploadAborted() {
+  return {
+    code: "ABORTED",
+    message: "The upload was stopped before it finished."
+  };
+}
 function invalidResponse(status) {
   return {
     code: "INVALID_RESPONSE",
@@ -85,6 +91,10 @@ function errorFromBody(status, body) {
 }
 
 // src/http.ts
+var AUTH_PREFIX = "/auth/";
+function storeFor(config, path) {
+  return path.startsWith(AUTH_PREFIX) ? config.tokens : config.accessJwt ?? null;
+}
 async function receive(config, options, init) {
   const controller = options.timeoutMs !== void 0 && typeof AbortController === "function" ? new AbortController() : null;
   if (controller) init.signal = controller.signal;
@@ -128,8 +138,12 @@ async function call(config, options) {
       return { error: invalidQuery("", "is not JSON"), answer: null };
     }
   }
-  const token = options.withToken ? await config.tokens.get() : null;
-  const headers = { apikey: config.apiKey };
+  const store = storeFor(config, options.path);
+  const token = options.withToken && store ? await store.get() : null;
+  const headers = {
+    ...options.headers,
+    apikey: config.apiKey
+  };
   if (token !== null) headers.Authorization = `Bearer ${token}`;
   const init = {
     method: options.method,
@@ -159,17 +173,18 @@ async function call(config, options) {
   const error = errorFromBody(status, body);
   if (error === null) return { error: null, answer };
   return {
-    error: await settled(config, error, responseHeaders, token),
+    error: await settled(store, error, responseHeaders, token),
     answer
   };
 }
-async function settled(config, error, headers, token) {
-  if (error.code === "INVALID_SESSION" && token !== null)
-    await config.tokens.clearIf(token);
+async function settled(store, error, headers, token) {
+  if (error.code === "INVALID_SESSION" && token !== null && store)
+    await store.clearIf(token);
   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 store = storeFor(config, options.path);
+  const token = options.withToken && store ? await store.get() : null;
   const headers = {
     ...options.headers,
     apikey: config.apiKey
@@ -181,6 +196,12 @@ async function send(config, options) {
     credentials: "omit"
   };
   if (options.body !== void 0) init.body = options.body;
+  const { signal } = options;
+  if (signal?.aborted) return { error: uploadAborted(), status: null };
+  const controller = signal ? new AbortController() : null;
+  const stop = () => controller?.abort();
+  if (controller) init.signal = controller.signal;
+  signal?.addEventListener("abort", stop);
   let response;
   try {
     const fetchImpl = config.fetch ?? globalThis.fetch;
@@ -189,26 +210,34 @@ async function send(config, options) {
       init
     );
   } catch (error2) {
-    return { error: networkError(error2) };
+    return {
+      error: signal?.aborted ? uploadAborted() : networkError(error2),
+      status: null
+    };
+  } finally {
+    signal?.removeEventListener("abort", stop);
   }
-  if (response.status >= 200 && response.status < 300)
-    return { error: null, response };
+  const { status } = response;
+  if (status >= 200 && status < 300) return { error: null, response };
   let text;
   try {
     text = await response.text();
   } catch (error2) {
-    return { error: networkError(error2) };
+    return { error: networkError(error2), status: null };
   }
   let body;
   if (text.trim() !== "") {
     try {
       body = JSON.parse(text);
     } catch {
-      return { error: invalidResponse(response.status) };
+      return { error: invalidResponse(status), status };
     }
   }
-  const error = errorFromBody(response.status, body) ?? invalidResponse(response.status);
-  return { error: await settled(config, error, response.headers, token) };
+  const error = errorFromBody(status, body) ?? invalidResponse(status);
+  return {
+    error: await settled(store, error, response.headers, token),
+    status
+  };
 }
 var RETRY_AFTER_CODES = /* @__PURE__ */ new Set([
   "RATE_LIMITED",
@@ -401,6 +430,7 @@ async function createPkcePair() {
 
 // src/auth/client.ts
 var TOKEN_HEADER = "set-auth-token";
+var JWT_HEADER = "set-auth-jwt";
 var FRAGMENT_PREFIX = "naro_";
 var OAUTH_PROVIDERS = ["google", "github"];
 var FLOW_TYPES = [
@@ -419,6 +449,9 @@ function nonEmpty(value) {
 function tokenFrom(answer) {
   return nonEmpty(answer.headers.get(TOKEN_HEADER));
 }
+function jwtFrom(answer) {
+  return nonEmpty(answer.headers.get(JWT_HEADER));
+}
 function userFrom(body) {
   return isRecord(body) && isRecord(body.user) ? body.user : null;
 }
@@ -581,7 +614,7 @@ var AuthClient = class {
     const user = userFrom(body);
     if (token === null || user === null || !isRecord(body) || !isRecord(body.session))
       return { data: signedOut, error: invalidResponse(result.answer.status) };
-    await this.#http.tokens.set(token);
+    await this.#storeSession(token, jwtFrom(result.answer));
     await this.#flow.recovery.forget();
     return { data: { session: body.session, user }, error: null };
   }
@@ -617,6 +650,7 @@ var AuthClient = class {
     }
     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 };
     }
@@ -707,6 +741,7 @@ var AuthClient = class {
       withToken: true
     });
     await tokens.clearIf(result.answer?.token ?? token);
+    await this.#http.accessJwt?.clear();
     return { data: null, error: result.error };
   }
   /**
@@ -728,7 +763,10 @@ var AuthClient = class {
     if (result.error !== null) return { data: signedOut, error: result.error };
     const { body, token } = result.answer;
     if (body === null) {
-      if (token !== null) await tokens.clearIf(token);
+      if (token !== null) {
+        await tokens.clearIf(token);
+        await this.#http.accessJwt?.clear();
+      }
       return { data: signedOut, error: invalidSession() };
     }
     const user = userFrom(body);
@@ -759,6 +797,15 @@ var AuthClient = class {
   async #pendingUrl() {
     if (this.#fromUrl) await this.#fromUrl;
   }
+  /**
+   * Keeps a new session: its token, and the access JWT beside it. An answer
+   * without a JWT drops the old one — it belonged to the previous session.
+   */
+  async #storeSession(token, jwt) {
+    await this.#http.tokens.set(token);
+    if (jwt !== null) await this.#http.accessJwt?.set(jwt);
+    else await this.#http.accessJwt?.clear();
+  }
   async #signIn(path, body, needsToken) {
     await this.#flow.recovery.forget();
     const result = await call(this.#http, {
@@ -778,7 +825,7 @@ var AuthClient = class {
         data: { user: null },
         error: invalidResponse(result.answer.status)
       };
-    if (token !== null) await this.#http.tokens.set(token);
+    if (token !== null) await this.#storeSession(token, jwtFrom(result.answer));
     return { data: { user }, error: null };
   }
 };
@@ -932,6 +979,9 @@ function defaultStorage() {
 function storageKey(baseUrl) {
   return `naro-auth-token:${baseUrl}`;
 }
+function accessJwtKey(baseUrl) {
+  return `naro-auth-jwt:${baseUrl}`;
+}
 function verifierKey(baseUrl) {
   return `naro-auth-code-verifiers:${baseUrl}`;
 }
@@ -1806,13 +1856,192 @@ var TableBuilder = class {
   }
 };
 
+// src/storage/answer.ts
+function fail(error) {
+  return { data: null, error };
+}
+var isUploadResult = (value) => isRecord(value) && typeof value.id === "string" && typeof value.path === "string" && typeof value.fullPath === "string";
+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);
+}
+
+// src/storage/multipart.ts
+var ROUTE = "/storage/upload/multipart";
+var UPLOAD_TOKEN_HEADER = "x-naro-upload-token";
+var CONCURRENCY = 4;
+var ATTEMPTS = 4;
+var BACKOFF_MS = [1e3, 2e3, 4e3];
+var UPLOAD_ID = /^[\w-][\w.-]*$/;
+var positive = (value) => typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+var planFor = (size) => (value) => isRecord(value) && typeof value.uploadId === "string" && UPLOAD_ID.test(value.uploadId) && positive(value.partSize) && positive(value.partCount) && (value.partCount - 1) * value.partSize < size && value.partCount * value.partSize >= size;
+var partAnswer = (n) => (value) => isRecord(value) && value.partNumber === n && typeof value.etag === "string" && value.etag !== "";
+var retryable = (error, status) => error.code === "NETWORK_ERROR" || error.code === "OBJECT_RATE_LIMITED" || status !== null && status >= 500 && error.code !== "STORAGE_QUOTA_EXCEEDED";
+function waitAfter(error, attempt2) {
+  const after = isRecord(error.details) ? error.details.retryAfter : void 0;
+  if (typeof after === "number") return after * 1e3;
+  if (error.code === "OBJECT_RATE_LIMITED") return 1e3;
+  return BACKOFF_MS[attempt2 - 1] ?? 4e3;
+}
+var sleepFor = (ms, signal) => new Promise((done) => {
+  if (signal?.aborted) {
+    done();
+    return;
+  }
+  const end = () => {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", end);
+    done();
+  };
+  const timer = setTimeout(end, ms);
+  signal?.addEventListener("abort", end);
+});
+async function uploadInParts(a) {
+  const { signal } = a;
+  const sleep = a.sleep ?? sleepFor;
+  const signed = a.uploadToken === void 0 ? {} : { [UPLOAD_TOKEN_HEADER]: a.uploadToken };
+  const withToken = a.uploadToken === void 0;
+  if (signal?.aborted) return fail(uploadAborted());
+  const started = await call(a.http, {
+    method: a.method,
+    path: ROUTE,
+    body: {
+      bucket: a.bucket,
+      path: a.path,
+      size: a.size,
+      contentType: a.contentType,
+      cacheControl: a.cacheControl,
+      // PUT always replaces: the worker refuses `upsert` on it.
+      ...a.method === "POST" && a.upsert ? { upsert: true } : {}
+    },
+    headers: signed,
+    withToken
+  });
+  if (started.error !== null) return fail(started.error);
+  const plan = dataOf2(
+    started.answer.status,
+    started.answer.body,
+    planFor(a.size)
+  );
+  if (plan.error !== null) return fail(plan.error);
+  const { uploadId, partSize, partCount } = plan.data;
+  const base = `${ROUTE}/${uploadId}`;
+  const progress = (sentBytes2) => {
+    if (signal?.aborted) return;
+    try {
+      const result = a.onProgress?.(sentBytes2, a.size);
+      if (isThenable(result)) result.then(void 0, () => void 0);
+    } catch {
+    }
+  };
+  const callOff = async () => {
+    await call(a.http, {
+      method: "DELETE",
+      path: base,
+      headers: signed,
+      withToken
+    }).catch(() => void 0);
+  };
+  const etags = [];
+  const failure = {
+    error: signal?.aborted ? uploadAborted() : null
+  };
+  let next = 1;
+  let sentBytes = 0;
+  const onAbort = () => {
+    failure.error ??= uploadAborted();
+  };
+  const tryPart = async (n, bytes) => {
+    const sent = await send(a.http, {
+      method: "PUT",
+      path: `${base}/${String(n)}`,
+      headers: { "content-type": "application/octet-stream", ...signed },
+      body: bytes,
+      withToken,
+      signal
+    });
+    if (sent.error !== null) return sent;
+    const read = await readJson(sent.response, partAnswer(n));
+    if (read.error !== null)
+      return { error: read.error, status: sent.response.status };
+    return { etag: read.data.etag };
+  };
+  const sendPart = async (n) => {
+    const from = (n - 1) * partSize;
+    const to = Math.min(from + partSize, a.size);
+    const bytes = a.body instanceof Uint8Array ? a.body.subarray(from, to) : a.body.slice(from, to);
+    for (let attempt2 = 1; ; attempt2 += 1) {
+      const tried = await tryPart(n, bytes);
+      if ("etag" in tried) {
+        etags[n - 1] = tried.etag;
+        sentBytes += to - from;
+        progress(sentBytes);
+        return null;
+      }
+      if (attempt2 === ATTEMPTS || failure.error !== null || !retryable(tried.error, tried.status))
+        return tried.error;
+      await sleep(waitAfter(tried.error, attempt2), signal);
+      if (failure.error !== null) return tried.error;
+    }
+  };
+  const worker = async () => {
+    while (failure.error === null && next <= partCount) {
+      const n = next;
+      next += 1;
+      const error = await sendPart(n);
+      if (error !== null) failure.error ??= error;
+    }
+  };
+  signal?.addEventListener("abort", onAbort);
+  await Promise.all(
+    Array.from({ length: Math.min(CONCURRENCY, partCount) }, worker)
+  );
+  signal?.removeEventListener("abort", onAbort);
+  if (failure.error !== null) {
+    await callOff();
+    return fail(failure.error);
+  }
+  const completed = await call(a.http, {
+    method: "POST",
+    path: `${base}/complete`,
+    body: {
+      parts: etags.map((etag, i) => ({ partNumber: i + 1, etag }))
+    },
+    headers: signed,
+    withToken
+  });
+  if (completed.error !== null) {
+    if (completed.answer !== null && completed.error.code !== "INVALID_RESPONSE")
+      await callOff();
+    return fail(completed.error);
+  }
+  return dataOf2(completed.answer.status, completed.answer.body, isUploadResult);
+}
+var isThenable = (value) => typeof value === "object" && value !== null && typeof value.then === "function";
+
 // 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."
+  body: "upload takes a Blob, File, ArrayBuffer, typed array or string.",
+  signature: "The signed URL is not valid."
 };
 var RESERVED_BUCKETS = /* @__PURE__ */ new Set([
   "authenticated",
@@ -1835,9 +2064,6 @@ function invalidPath(reason) {
     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") };
@@ -1874,6 +2100,16 @@ function encodeBucket(bucket) {
     };
   return { ok: true, encoded: encodeURIComponent(bucket) };
 }
+function objectRoute(bucket, path) {
+  const encodedBucket = encodeBucket(bucket);
+  if (!encodedBucket.ok) return encodedBucket;
+  const encodedPath = encodePath(path);
+  if (!encodedPath.ok) return encodedPath;
+  return {
+    ok: true,
+    encoded: `${encodedBucket.encoded}/${encodedPath.encoded}`
+  };
+}
 var isArrayBuffer = (value) => Object.prototype.toString.call(value) === "[object ArrayBuffer]";
 function isDetached(buffer) {
   if (!isArrayBuffer(buffer)) return false;
@@ -1956,36 +2192,26 @@ function payloadOf(body, contentType) {
 
 // src/storage/client.ts
 var SIGNED_PREFIX = "/_naro/v1/storage/object/sign/";
-function fail(error) {
-  return { data: null, error };
+var SIGNED_UPLOAD_PREFIX = "/_naro/v1/storage/object/upload/sign/";
+var TOKEN_TEXT = /^[\x21-\x7e]+$/;
+var TOKEN_PARAMETER = /([?&]token=)[^&#\s"'<>]*/g;
+function withoutToken(error, token) {
+  const { details } = error;
+  if (!isRecord(details) || typeof details.cause !== "string") return error;
+  let cause = details.cause.replace(TOKEN_PARAMETER, "$1[redacted]");
+  for (const form of [encodeURIComponent(token), token])
+    cause = cause.replaceAll(form, "[redacted]");
+  return { ...error, details: { ...details, cause } };
 }
-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);
+var isSignedEntry = (value) => isRecord(value) && typeof value.path === "string" && (value.signedUrl === null || typeof value.signedUrl === "string" && value.signedUrl.startsWith(SIGNED_PREFIX)) && (value.error === null || typeof value.error === "string");
+var isSignedUpload = (value) => isRecord(value) && typeof value.signedUrl === "string" && value.signedUrl.startsWith(SIGNED_UPLOAD_PREFIX) && typeof value.token === "string" && value.token !== "" && typeof value.path === "string";
+var partsBody = (body) => isArrayBuffer(body) ? new Uint8Array(body) : body;
 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;
@@ -1997,14 +2223,9 @@ var StorageFileApi = class {
   }
   /** `/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}`
-    };
+    const target = objectRoute(this.#bucket, path);
+    if (!target.ok) return target;
+    return { ok: true, path: `/storage/object/${route}${target.encoded}` };
   }
   /** `/storage/object/<route><bucket>`, for the routes that take names in the body. */
   #bucketPath(route) {
@@ -2026,8 +2247,23 @@ var StorageFileApi = class {
     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());
+    const { signal } = options;
+    if (signal?.aborted) return fail(uploadAborted());
     await this.#auth.ready();
+    if (payload.size > MAX_SINGLE_UPLOAD_BYTES)
+      return uploadInParts({
+        http: this.#http,
+        method,
+        bucket: this.#bucket,
+        path,
+        body: partsBody(payload.body),
+        size: payload.size,
+        contentType: payload.type,
+        cacheControl: cache,
+        upsert,
+        ...options.onProgress ? { onProgress: options.onProgress } : {},
+        signal
+      });
     const headers = {
       "content-type": payload.type,
       "cache-control": cache
@@ -2038,7 +2274,9 @@ var StorageFileApi = class {
       path: target.path,
       headers,
       body: payload.body,
-      withToken: true
+      withToken: true,
+      // The fetch stops with the body: the worker undoes its claim at once.
+      signal
     });
     if (sent.error !== null) return fail(sent.error);
     return readJson(sent.response, isUploadResult);
@@ -2098,7 +2336,11 @@ var StorageFileApi = class {
   }
   /**
    * What is directly below `prefix` (the whole bucket by default): folders
-   * first, then files. The options go to the worker as they are given.
+   * first, then files. `search` keeps the names below the prefix that start
+   * with it, ASCII case ignored (Storage 3-1g); a backend whose Storage was
+   * turned on before it answers `INVALID_REQUEST` (`details.path`
+   * `search`) — update it with `naro backend enable`. The options go to the
+   * worker as they are given.
    */
   async list(prefix, options = {}) {
     const target = this.#bucketPath("list/");
@@ -2146,6 +2388,139 @@ var StorageFileApi = class {
       error: null
     };
   }
+  /**
+   * Links to several objects at once (Storage 3-1g): up to 100 paths, each
+   * for `expiresIn` seconds (1–604,800), with the same `download`. One entry
+   * per path, in the order given — a path given twice is answered twice.
+   * A path that is not there, or that the caller cannot read, has
+   * `signedUrl: null` and `error` "Object <path> was not found in bucket
+   * <bucket>." — the same words for both. The paths go in the body, so the
+   * backend checks them: a bad one fails the call with `INVALID_REQUEST`
+   * (`details.path` `paths[<i>]`). A backend whose Storage was turned on
+   * before this method came answers `NOT_FOUND`: update it with
+   * `naro backend enable`.
+   */
+  async createSignedUrls(paths, expiresIn, options = {}) {
+    const target = this.#bucketPath("sign/");
+    if (!target.ok) return fail(target.error);
+    const { download } = options ?? {};
+    const signed = await this.#json(
+      {
+        method: "POST",
+        path: target.path,
+        body: {
+          expiresIn,
+          paths,
+          ...download === void 0 || download === false ? {} : { download }
+        }
+      },
+      listOf(isSignedEntry)
+    );
+    if (signed.error !== null) return signed;
+    return {
+      data: signed.data.map((entry) => ({
+        path: entry.path,
+        signedUrl: entry.signedUrl === null ? null : `${this.#http.baseUrl}${entry.signedUrl}`,
+        error: entry.error
+      })),
+      error: null
+    };
+  }
+  /**
+   * A token that lets whoever holds it upload `path` for two hours (Storage
+   * 3-1e-2), as supabase-js's: made where the key is — a server with the
+   * service key for any path, anon or a signed-in user only where the
+   * policies let them upload. With `upsert: true` it may replace a file
+   * that is there.
+   * The token goes to `uploadToSignedUrl`; `signedUrl` is where a client
+   * without naro-js PUTs the bytes.
+   */
+  async createSignedUploadUrl(path, options = {}) {
+    const target = this.#objectPath("upload/sign/", path);
+    if (!target.ok) return fail(target.error);
+    const upsert = (options ?? {}).upsert === true;
+    const signed = await this.#json(
+      {
+        method: "POST",
+        path: target.path,
+        body: upsert ? { upsert: true } : {}
+      },
+      isSignedUpload
+    );
+    if (signed.error !== null) return signed;
+    return {
+      data: {
+        signedUrl: `${this.#http.baseUrl}${signed.data.signedUrl}`,
+        token: signed.data.token,
+        path: signed.data.path
+      },
+      error: null
+    };
+  }
+  /**
+   * Uploads `body` to `path` with a token from `createSignedUploadUrl`
+   * (Storage 3-1e-2). No session is sent, or needed: the token is the
+   * permission, so a page's anon-key client uploads where only a server
+   * could sign. It works until the token expires, two hours from when it
+   * was made; one made without `upsert` uploads one new file
+   * (`OBJECT_EXISTS` for a name that is there). A body over 50 MiB goes in
+   * parts with the token on every step, and once started may finish after
+   * the two hours. `contentType`, `cacheControl`, `onProgress` and `signal`
+   * are `upload`'s.
+   */
+  async uploadToSignedUrl(path, token, body, options = {}) {
+    const given = options ?? {};
+    const target = this.#objectPath("upload/sign/", path);
+    if (!target.ok) return fail(target.error);
+    if (typeof token !== "string" || !TOKEN_TEXT.test(token))
+      return fail({
+        code: "INVALID_SIGNATURE",
+        message: STORAGE_MESSAGES.signature
+      });
+    const payload = payloadOf(body, given.contentType);
+    if (!payload.ok) return fail(payload.error);
+    const cache = `max-age=${given.cacheControl ?? "3600"}`;
+    const unreadable = headerProblem(given.contentType, cache);
+    if (unreadable !== null) return fail(unreadable);
+    const { signal } = given;
+    if (signal?.aborted) return fail(uploadAborted());
+    const uploaded = payload.size > MAX_SINGLE_UPLOAD_BYTES ? await uploadInParts({
+      http: this.#http,
+      method: "POST",
+      bucket: this.#bucket,
+      path,
+      body: partsBody(payload.body),
+      size: payload.size,
+      contentType: payload.type,
+      cacheControl: cache,
+      upsert: false,
+      uploadToken: token,
+      ...given.onProgress ? { onProgress: given.onProgress } : {},
+      signal
+    }) : await this.#putSigned(target.path, token, payload, cache, signal);
+    if (uploaded.error !== null) return fail(uploaded.error);
+    return {
+      data: { path: uploaded.data.path, fullPath: uploaded.data.fullPath },
+      error: null
+    };
+  }
+  /**
+   * The one-request signed upload: the token in the query, no session — it
+   * is the permission. A failure's cause never carries the token.
+   */
+  async #putSigned(path, token, payload, cache, signal) {
+    const sent = await send(this.#http, {
+      method: "PUT",
+      path: `${path}?token=${encodeURIComponent(token)}`,
+      headers: { "content-type": payload.type, "cache-control": cache },
+      body: payload.body,
+      withToken: false,
+      signal
+    });
+    if (sent.error !== null) return fail(withoutToken(sent.error, token));
+    const read = await readJson(sent.response, isUploadResult);
+    return read.error === null ? read : fail(withoutToken(read.error, token));
+  }
   /**
    * 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
@@ -2255,7 +2630,8 @@ var NaroClient = class {
       baseUrl,
       apiKey,
       fetch: options.fetch,
-      tokens: new TokenStore(storage, storageKey(baseUrl))
+      tokens: new TokenStore(storage, storageKey(baseUrl)),
+      accessJwt: new TokenStore(storage, accessJwtKey(baseUrl))
     };
     this.auth = new AuthClient(http, {
       verifiers: new FlowVerifiers(
@@ -2282,5 +2658,6 @@ function createClient(options) {
 export {
   NaroClient,
   createClient,
+  objectRoute,
   quoteFilterValue
 };

package/dist/storage/answer.d.ts

@@ -0,0 +1,9 @@
+import { type NaroError } from "../errors.js";
+import type { NaroResponse } from "../types.js";
+import type { UploadResult } from "./types.js";
+export declare function fail<T>(error: NaroError): NaroResponse<T>;
+export declare const isUploadResult: (value: unknown) => value is UploadResult;
+/** `{ data }` of a worker's JSON answer that passes `guard`, else INVALID_RESPONSE. */
+export declare function dataOf<T>(status: number, body: unknown, guard: (value: unknown) => value is T): NaroResponse<T>;
+/** A 2xx answer `send` handed back unread, read as `dataOf` reads one. */
+export declare function readJson<T>(response: Response, guard: (value: unknown) => value is T): Promise<NaroResponse<T>>;

package/dist/storage/client.d.ts

@@ -1,7 +1,7 @@
 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";
+import type { CreateSignedUploadUrlOptions, DownloadOption, FileObject, FolderEntry, ListOptions, SignedUploadResult, SignedUploadUrl, SignedUrlEntry, UpdateOptions, UploadBody, UploadOptions, UploadResult } from "./types.js";
 /** One bucket's objects: supabase-js's StorageFileApi. */
 export declare class StorageFileApi {
     #private;
@@ -31,7 +31,11 @@ export declare class StorageFileApi {
     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.
+     * first, then files. `search` keeps the names below the prefix that start
+     * with it, ASCII case ignored (Storage 3-1g); a backend whose Storage was
+     * turned on before it answers `INVALID_REQUEST` (`details.path`
+     * `search`) — update it with `naro backend enable`. 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. */
@@ -43,6 +47,41 @@ export declare class StorageFileApi {
     createSignedUrl(path: string, expiresIn: number, options?: DownloadOption): Promise<NaroResponse<{
         signedUrl: string;
     }>>;
+    /**
+     * Links to several objects at once (Storage 3-1g): up to 100 paths, each
+     * for `expiresIn` seconds (1–604,800), with the same `download`. One entry
+     * per path, in the order given — a path given twice is answered twice.
+     * A path that is not there, or that the caller cannot read, has
+     * `signedUrl: null` and `error` "Object <path> was not found in bucket
+     * <bucket>." — the same words for both. The paths go in the body, so the
+     * backend checks them: a bad one fails the call with `INVALID_REQUEST`
+     * (`details.path` `paths[<i>]`). A backend whose Storage was turned on
+     * before this method came answers `NOT_FOUND`: update it with
+     * `naro backend enable`.
+     */
+    createSignedUrls(paths: string[], expiresIn: number, options?: DownloadOption): Promise<NaroResponse<SignedUrlEntry[]>>;
+    /**
+     * A token that lets whoever holds it upload `path` for two hours (Storage
+     * 3-1e-2), as supabase-js's: made where the key is — a server with the
+     * service key for any path, anon or a signed-in user only where the
+     * policies let them upload. With `upsert: true` it may replace a file
+     * that is there.
+     * The token goes to `uploadToSignedUrl`; `signedUrl` is where a client
+     * without naro-js PUTs the bytes.
+     */
+    createSignedUploadUrl(path: string, options?: CreateSignedUploadUrlOptions): Promise<NaroResponse<SignedUploadUrl>>;
+    /**
+     * Uploads `body` to `path` with a token from `createSignedUploadUrl`
+     * (Storage 3-1e-2). No session is sent, or needed: the token is the
+     * permission, so a page's anon-key client uploads where only a server
+     * could sign. It works until the token expires, two hours from when it
+     * was made; one made without `upsert` uploads one new file
+     * (`OBJECT_EXISTS` for a name that is there). A body over 50 MiB goes in
+     * parts with the token on every step, and once started may finish after
+     * the two hours. `contentType`, `cacheControl`, `onProgress` and `signal`
+     * are `upload`'s.
+     */
+    uploadToSignedUrl(path: string, token: string, body: UploadBody, options?: UpdateOptions): Promise<NaroResponse<SignedUploadResult>>;
     /**
      * 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

package/dist/storage/multipart.d.ts

@@ -0,0 +1,28 @@
+import { type HttpConfig } from "../http.js";
+import type { NaroResponse } from "../types.js";
+import type { UploadResult } from "./types.js";
+export type PartsArgs = {
+    http: HttpConfig;
+    /** POST for `upload` (a new name, or `upsert`), PUT for `update`. */
+    method: "POST" | "PUT";
+    bucket: string;
+    /** The object's name as given: the start carries it in JSON, not a URL. */
+    path: string;
+    body: Blob | Uint8Array<ArrayBuffer>;
+    size: number;
+    contentType: string;
+    /** As the upload's header says it: `max-age=<seconds>`. */
+    cacheControl: string;
+    upsert: boolean;
+    /**
+     * A signed upload's token (Storage 3-1e-2): every step carries it and
+     * none carries the session.
+     */
+    uploadToken?: string | undefined;
+    onProgress?: (sentBytes: number, totalBytes: number) => void;
+    /** The caller's: stops the upload until the complete is sent. */
+    signal?: AbortSignal | undefined;
+    /** How a retry waits — `ms`, or until the signal aborts; tests pass their own. */
+    sleep?: (ms: number, signal: AbortSignal | undefined) => Promise<void>;
+};
+export declare function uploadInParts(a: PartsArgs): Promise<NaroResponse<UploadResult>>;

package/dist/storage/path.d.ts

@@ -3,15 +3,15 @@ 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.
+ * read the answer: the SDK sends a larger body in parts (Storage 3-1f).
  */
 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.";
+    readonly signature: "The signed URL is not valid.";
 };
 /**
  * The words the worker's routes take as the first segment after `/object/`
@@ -29,7 +29,6 @@ export type Encoded = {
     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
@@ -53,6 +52,19 @@ export declare function downloadQuery(download: boolean | string | undefined): E
  * empty, `.`, `..`, a lone surrogate and the routes' own words.
  */
 export declare function encodeBucket(bucket: string): Encoded;
+/**
+ * `<bucket>/<path>` as the object routes carry it — the bucket by
+ * `encodeBucket`, the path by `encodePath` — or the INVALID_PATH either is
+ * refused with. Every object call builds its URL from it, and the package
+ * exports it for a tool that streams an object itself (naro-cli's
+ * download): it names the same URL, and is refused the same names.
+ */
+export declare function objectRoute(bucket: string, path: string): Encoded;
+/**
+ * `instanceof ArrayBuffer` is false for one made in another realm (an
+ * iframe, a vm context); the tag is the same in every realm.
+ */
+export declare const isArrayBuffer: (value: unknown) => value is ArrayBuffer;
 /** 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";
 /**

package/dist/storage/types.d.ts

@@ -34,6 +34,25 @@ export type UploadOptions = {
     cacheControl?: string;
     /** Replace an object of the same name. Default false. */
     upsert?: boolean;
+    /**
+     * Called each time a part of an upload over 50 MiB is sent: the bytes
+     * sent so far and the body's size, ending with both the same. An upload
+     * of 50 MiB or less is one request and never calls it. What it throws is
+     * ignored: the upload goes on.
+     */
+    onProgress?: (sentBytes: number, totalBytes: number) => void;
+    /**
+     * Stops the upload: what has not been answered yet is called off, and the
+     * upload answers `ABORTED` ("The upload was stopped before it finished.").
+     * One over 50 MiB is called off on the backend too, so its name and the
+     * space it reserved are free at once — not after the hour its lock lasts;
+     * no part starts and `onProgress` is not called after the signal. Its
+     * first and last steps are never cut short: a signal during the first is
+     * acted on once it answers, and once the last is sent the signal stops
+     * nothing and that step's answer is the upload's. A signal already aborted
+     * sends nothing.
+     */
+    signal?: AbortSignal;
 };
 export type UpdateOptions = Omit<UploadOptions, "upsert">;
 export type UploadResult = {
@@ -51,8 +70,48 @@ export type ListOptions = {
         column?: "name" | "created_at" | "updated_at";
         order?: "asc" | "desc";
     };
+    /**
+     * Names below the prefix that start with it, ASCII case ignored; % and _
+     * are plain characters. Up to 256 characters. A folder shows when a name
+     * under it starts with it. A backend whose Storage was turned on before
+     * search came answers INVALID_REQUEST (`details.path` "search"): update
+     * it with `naro backend enable`.
+     */
+    search?: string;
 };
 /** `true` downloads under the object's own name, a string under that name. */
 export type DownloadOption = {
     download?: boolean | string;
 };
+/** `createSignedUploadUrl`'s options (Storage 3-1e-2). */
+export type CreateSignedUploadUrlOptions = {
+    /** Let the token replace a file of the same name. Default false: a second upload is `OBJECT_EXISTS`. */
+    upsert?: boolean;
+};
+/**
+ * A signed upload's token (Storage 3-1e-2): `token` for `uploadToSignedUrl`,
+ * and `signedUrl` — on the project's URL — where a client without naro-js
+ * PUTs the file's bytes with no key. It works for two hours from when it
+ * was made.
+ */
+export type SignedUploadUrl = {
+    signedUrl: string;
+    token: string;
+    path: string;
+};
+/** What `uploadToSignedUrl` answers: supabase-js's shape. */
+export type SignedUploadResult = {
+    path: string;
+    fullPath: string;
+};
+/**
+ * One path's answer of `createSignedUrls` (Storage 3-1g): supabase-js's
+ * shape without its `signedURL` copy. `signedUrl` is null, and `error`
+ * says `Object <path> was not found in bucket <bucket>.`, for a file that
+ * is not there or that the caller cannot read — the same words for both.
+ */
+export type SignedUrlEntry = {
+    path: string;
+    signedUrl: string | null;
+    error: string | null;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naro-js",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Auth, data and files for your Naro project, from the browser or the server.",
   "type": "module",
   "sideEffects": false,
@@ -23,8 +23,8 @@
     "tsup": "8.5.0",
     "typescript": "7.0.2",
     "vitest": "3.2.7",
-    "@next-deploy/backend-worker": "0.1.0",
     "@next-deploy/config": "0.1.0",
+    "@next-deploy/backend-worker": "0.1.0",
     "@next-deploy/data-core": "0.1.0",
     "@next-deploy/sdk": "0.1.0"
   },