naro-js 0.1.0 → 0.3.0

package/dist/index.js

@@ -49,6 +49,12 @@ function invalidProvider() {
     message: "provider must be google or github."
   };
 }
+function serviceKeyRequired() {
+  return {
+    code: "PERMISSION_DENIED",
+    message: "Only the service key can manage users."
+  };
+}
 function cryptoUnavailable() {
   return {
     code: "CRYPTO_UNAVAILABLE",
@@ -128,9 +134,10 @@ async function call(config, options) {
   const init = {
     method: options.method,
     headers,
-    // Identity is the bearer token alone. Better Auth also sets a session
-    // cookie (spec §13); a request that carried it would let any site act
-    // as the user. Workers accept the field (measured on workerd 1.20260815).
+    // Identity is the bearer token alone. The sign-in routes also set a
+    // session cookie (spec §13); a request that carried it would let any site
+    // act as the user. Workers accept the field (measured on workerd
+    // 1.20260815).
     credentials: "omit"
   };
   if (payload !== void 0) {
@@ -151,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() ?? "";
@@ -196,6 +253,90 @@ function isKnownServer(scope = globalThis) {
   return hasServerSignal(g) && !hasDeviceSignal(g);
 }
 
+// src/auth/admin.ts
+var USERS_PATH = "/auth/admin/users";
+function dataOf(result) {
+  if (result.error !== null) return null;
+  const { body } = result.answer;
+  return isRecord(body) && isRecord(body.data) ? body.data : null;
+}
+function errorOf(result) {
+  if (result.error !== null) return result.error;
+  return invalidResponse(result.answer.status);
+}
+function userOf(value) {
+  return isRecord(value) && typeof value.id === "string" ? value : null;
+}
+var AuthAdminApi = class {
+  #http;
+  #serviceKey;
+  constructor(http, serviceKey) {
+    this.#http = http;
+    this.#serviceKey = serviceKey;
+  }
+  /**
+   * Creates a user with a password: an email, a username or both. It is
+   * made while sign-ups are closed too, and is confirmed unless
+   * `emailConfirm: false`. A username-only user answers `email: null` and
+   * signs in with `signIn({ username, password })`. Refusals come as the
+   * worker says them: USERNAME_TAKEN (409),
+   * USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL (422), PASSWORD_TOO_SHORT ("Use at
+   * least {n} characters."), VALIDATION_ERROR, WRITE_QUOTA_EXCEEDED (429).
+   */
+  async createUser(attributes) {
+    if (!this.#serviceKey)
+      return { data: { user: null }, error: serviceKeyRequired() };
+    const result = await call(this.#http, {
+      method: "POST",
+      path: USERS_PATH,
+      body: attributes,
+      withToken: false
+    });
+    const user = userOf(dataOf(result)?.user);
+    if (user === null) return { data: { user: null }, error: errorOf(result) };
+    return { data: { user }, error: null };
+  }
+  /** The project's users, newest first: page 1 and 50 a page unless given. */
+  async listUsers(params = {}) {
+    const none = { users: [], total: 0 };
+    if (!this.#serviceKey) return { data: none, error: serviceKeyRequired() };
+    const query = new URLSearchParams();
+    if (params.page !== void 0) query.set("page", String(params.page));
+    if (params.perPage !== void 0)
+      query.set("perPage", String(params.perPage));
+    const search = query.toString();
+    const result = await call(this.#http, {
+      method: "GET",
+      path: search === "" ? USERS_PATH : `${USERS_PATH}?${search}`,
+      withToken: false
+    });
+    const data = dataOf(result);
+    const users = Array.isArray(data?.users) ? data.users.map(userOf) : null;
+    if (!data || users === null || users.includes(null) || typeof data.total !== "number")
+      return { data: none, error: errorOf(result) };
+    return {
+      data: { users, total: data.total },
+      error: null
+    };
+  }
+  /**
+   * Deletes a user and its sign-in methods, and ends its sessions. Answers
+   * the user it was; USER_NOT_FOUND (404) for an id that is no user.
+   */
+  async deleteUser(id) {
+    if (!this.#serviceKey)
+      return { data: { user: null }, error: serviceKeyRequired() };
+    const result = await call(this.#http, {
+      method: "DELETE",
+      path: `${USERS_PATH}/${encodeURIComponent(String(id))}`,
+      withToken: false
+    });
+    const user = userOf(dataOf(result)?.user);
+    if (user === null) return { data: { user: null }, error: errorOf(result) };
+    return { data: { user }, error: null };
+  }
+};
+
 // src/auth/flow-errors.ts
 var CODE = /^[A-Z0-9_]{1,64}$/;
 var INVALID_CONFIRMATION = "The confirmation link is not valid. Ask for a new one.";
@@ -207,6 +348,9 @@ var MESSAGES = {
   OAUTH_ACCOUNT_NOT_LINKED: "An account with this email already exists and is not linked to this provider. Sign in the way you signed up.",
   PROVIDER_NOT_CONFIGURED: "Signing in with this provider is not set up for this project.",
   RATE_LIMITED: "Too many sign-in attempts. Wait a few seconds and try again.",
+  // A first Google or GitHub sign-in while the project's sign-ups are
+  // closed (spec 2026-09-26 §2.1): the worker's own words.
+  SIGNUPS_DISABLED: "Sign-ups are closed for this project.",
   INTERNAL_ERROR: "Something went wrong. Try again.",
   PASSWORD_RESET_REQUIRED: "Your email is confirmed. Someone else also signed up with it before it was confirmed, so its password was cleared: choose a new one with a password reset.",
   TOKEN_EXPIRED: "The confirmation link has expired. Ask for a new one.",
@@ -326,6 +470,12 @@ function share(shared, pending) {
   });
 }
 var AuthClient = class {
+  /**
+   * The service key's user management — createUser, listUsers, deleteUser,
+   * as in supabase-js (spec 2026-09-26 §2.2). Only on a client made with
+   * `serviceKey`, on a server.
+   */
+  admin;
   #http;
   #flow;
   /** The last `getSessionFromUrl()`, for callers after detection ran it. */
@@ -333,6 +483,7 @@ var AuthClient = class {
   constructor(http, flow) {
     this.#http = http;
     this.#flow = flow;
+    this.admin = new AuthAdminApi(http, flow.serviceKey);
     if (flow.detectSessionInUrl) {
       if (naroFragment() !== null) void this.getSessionFromUrl();
       else this.#fromUrl = sharedInFlight(flow.shared);
@@ -342,18 +493,37 @@ var AuthClient = class {
    * Creates the account and signs in; the token is stored for later calls.
    * When the project requires a confirmed email there is no session yet —
    * `user` comes back, and after the confirmation link the user signs in.
+   * While the project's sign-ups are closed every sign-up answers 403
+   * SIGNUPS_DISABLED; while they are open, a taken `username` answers 409
+   * USERNAME_TAKEN.
    */
   async signUp(credentials) {
-    const { email, password } = credentials;
-    const name = credentials.name ?? defaultName(email);
+    const { email, password, username } = credentials;
+    const name = credentials.name ?? username ?? defaultName(email);
     const body = { email, password, name };
+    if (username !== void 0) body.username = username;
     if (credentials.redirectTo !== void 0)
       body.callbackURL = credentials.redirectTo;
     return this.#signIn("/auth/sign-up/email", body, false);
   }
+  /**
+   * Signs in with an email and password, or a username and password (spec
+   * 2026-09-26 §2.3); the token is stored for later calls. A wrong password
+   * answers 401 INVALID_EMAIL_OR_PASSWORD, or INVALID_USERNAME_OR_PASSWORD.
+   */
   async signIn(credentials) {
-    const { email, password } = credentials;
-    return this.#signIn("/auth/sign-in/email", { email, password }, true);
+    const { password } = credentials;
+    if (credentials.username !== void 0)
+      return this.#signIn(
+        "/auth/sign-in/username",
+        { username: credentials.username, password },
+        true
+      );
+    return this.#signIn(
+      "/auth/sign-in/email",
+      { email: credentials.email, password },
+      true
+    );
   }
   /**
    * Starts a Google or GitHub sign-in: sends the browser, with a top-level
@@ -1636,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.",
@@ -1668,9 +2211,10 @@ function apiKeyOf(options) {
   if (hasAnon && hasService) throw new Error(CONFIG_MESSAGES.bothKeys);
   const key = hasService ? serviceKey : hasAnon ? anonKey : void 0;
   if (key === void 0) throw new Error(CONFIG_MESSAGES.key);
-  if ((hasService || key.startsWith(SERVICE_KEY_PREFIX)) && !isKnownServer())
+  const service = hasService || key.startsWith(SERVICE_KEY_PREFIX);
+  if (service && !isKnownServer())
     throw new Error(CONFIG_MESSAGES.serviceKeyOffServer);
-  return key;
+  return { key, service };
 }
 function queryRunner(http, auth) {
   return async (query) => {
@@ -1689,14 +2233,21 @@ function queryRunner(http, auth) {
   };
 }
 var NaroClient = class {
-  /** Sign-up, sign-in, sign-out and the current user (spec §13). */
+  /**
+   * Sign-up, sign-in, sign-out and the current user (spec §13); with the
+   * service key, `auth.admin` manages users.
+   */
   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 apiKey = apiKeyOf(options);
+    const { key: apiKey, service } = apiKeyOf(options);
     if (options.fetch === void 0 && typeof globalThis.fetch !== "function")
       throw new Error(CONFIG_MESSAGES.fetch);
     const storage = options.auth?.storage ?? defaultStorage();
@@ -1714,9 +2265,11 @@ var NaroClient = class {
         new TokenStore(storage, recoveryKey(baseUrl))
       ),
       detectSessionInUrl: options.auth?.detectSessionInUrl ?? true,
-      shared: { storage, key: storageKey(baseUrl) }
+      shared: { storage, key: storageKey(baseUrl) },
+      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) {