naro-js 0.4.0 → 0.5.0

package/README.md

@@ -483,15 +483,49 @@ 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`.
+- `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
@@ -540,6 +574,38 @@ await naro.storage.from("videos").upload(`${user.id}/talk.mp4`, file, {
 });
 ```
 
+- `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
@@ -564,6 +630,5 @@ await naro.storage.from("videos").upload(`${user.id}/talk.mp4`, file, {
   downloads that way.
 - `OBJECT_RATE_LIMITED` and `STORAGE_OPS_QUOTA_EXCEEDED` carry
   `details.retryAfter`, in seconds.
-- Not yet: `move`, `copy`, `createSignedUrls`, `list`'s `search`, resuming
-  an upload in another session, 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/http.d.ts

@@ -13,6 +13,12 @@ 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" | "PUT" | "DELETE";
@@ -20,6 +26,11 @@ export type CallOptions = {
     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;
     /**

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { NaroError } from "./errors.js";
 export type { FetchLike } from "./http.js";
 export type { StorageClient, StorageFileApi } from "./storage/client.js";
 export { objectRoute, type Encoded as ObjectRouteResult, } from "./storage/path.js";
-export type { DownloadOption, FileObject, FolderEntry, ListOptions, UpdateOptions, UploadBody, UploadOptions, UploadResult, } from "./storage/types.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

@@ -91,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;
@@ -134,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,
@@ -165,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
@@ -226,7 +235,7 @@ async function send(config, options) {
   }
   const error = errorFromBody(status, body) ?? invalidResponse(status);
   return {
-    error: await settled(config, error, response.headers, token),
+    error: await settled(store, error, response.headers, token),
     status
   };
 }
@@ -421,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 = [
@@ -439,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;
 }
@@ -601,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 };
   }
@@ -637,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 };
     }
@@ -727,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 };
   }
   /**
@@ -748,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);
@@ -779,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, {
@@ -798,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 };
   }
 };
@@ -952,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}`;
 }
@@ -1854,6 +1884,7 @@ async function readJson(response, 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];
@@ -1884,6 +1915,8 @@ var sleepFor = (ms, signal) => new Promise((done) => {
 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,
@@ -1897,7 +1930,8 @@ async function uploadInParts(a) {
       // PUT always replaces: the worker refuses `upsert` on it.
       ...a.method === "POST" && a.upsert ? { upsert: true } : {}
     },
-    withToken: true
+    headers: signed,
+    withToken
   });
   if (started.error !== null) return fail(started.error);
   const plan = dataOf2(
@@ -1917,9 +1951,12 @@ async function uploadInParts(a) {
     }
   };
   const callOff = async () => {
-    await call(a.http, { method: "DELETE", path: base, withToken: true }).catch(
-      () => void 0
-    );
+    await call(a.http, {
+      method: "DELETE",
+      path: base,
+      headers: signed,
+      withToken
+    }).catch(() => void 0);
   };
   const etags = [];
   const failure = {
@@ -1934,9 +1971,9 @@ async function uploadInParts(a) {
     const sent = await send(a.http, {
       method: "PUT",
       path: `${base}/${String(n)}`,
-      headers: { "content-type": "application/octet-stream" },
+      headers: { "content-type": "application/octet-stream", ...signed },
       body: bytes,
-      withToken: true,
+      withToken,
       signal
     });
     if (sent.error !== null) return sent;
@@ -1986,7 +2023,8 @@ async function uploadInParts(a) {
     body: {
       parts: etags.map((etag, i) => ({ partNumber: i + 1, etag }))
     },
-    withToken: true
+    headers: signed,
+    withToken
   });
   if (completed.error !== null) {
     if (completed.answer !== null && completed.error.code !== "INVALID_RESPONSE")
@@ -2002,7 +2040,8 @@ var MAX_SINGLE_UPLOAD_BYTES = 52428800;
 var STORAGE_MESSAGES = {
   bucket: "The bucket name is not valid.",
   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",
@@ -2153,9 +2192,23 @@ function payloadOf(body, contentType) {
 
 // src/storage/client.ts
 var SIGNED_PREFIX = "/_naro/v1/storage/object/sign/";
+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 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);
 }
@@ -2203,8 +2256,7 @@ var StorageFileApi = class {
         method,
         bucket: this.#bucket,
         path,
-        // No copy: a Blob stays lazy, a Uint8Array is viewed, an ArrayBuffer wrapped.
-        body: isArrayBuffer(payload.body) ? new Uint8Array(payload.body) : payload.body,
+        body: partsBody(payload.body),
         size: payload.size,
         contentType: payload.type,
         cacheControl: cache,
@@ -2284,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/");
@@ -2332,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
@@ -2441,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(

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

@@ -14,6 +14,11 @@ export type PartsArgs = {
     /** 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;

package/dist/storage/path.d.ts

@@ -11,6 +11,7 @@ export declare const STORAGE_MESSAGES: {
     readonly bucket: "The bucket name is not valid.";
     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/`

package/dist/storage/types.d.ts

@@ -70,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.4.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"
   },