naro-js 0.1.0 → 0.2.0

package/README.md

@@ -71,12 +71,94 @@ await naro.from("posts").delete().eq("id", 10);
   `auth: { storage }` with your own `getItem` / `setItem` / `removeItem`.
 - Types: `createClient<Database>()` with the `Database` that
   `naro gen types` writes — see [Types](#types).
+- Sign-in is naro Auth, the project's own (like Supabase Auth). Email and
+  password sign-up and sign-in need no setup: they work as soon as the
+  backend is on. Resend is needed only to send confirmation and password
+  reset emails.
+- Admin accounts, closed sign-ups, sign-in by username and the password
+  length — see [Admin accounts and closed sign-ups](#admin-accounts-and-closed-sign-ups).
 - Email and social sign-in — see [Sign-in flows](#sign-in-flows).
 
+## Admin accounts and closed sign-ups
+
+An app that only its admins sign in to: close sign-ups, then create the
+accounts yourself. With sign-ups closed, `authenticated` in a policy means
+exactly the users you created.
+
+```bash
+naro backend auth signups off
+echo "$ADMIN_PASSWORD" | naro backend users create --username admin --password-stdin
+```
+
+```ts
+// In the app: sign in by username, or by email.
+await naro.auth.signIn({ username: "admin", password });
+await naro.auth.signIn({ email, password });
+```
+
+The same from your own server, with supabase-js's `auth.admin` names:
+
+```ts
+// Server only: the service key skips every policy.
+const admin = createClient({
+  url: "https://my-app.naro.sh",
+  serviceKey: process.env.NARO_SERVICE_KEY,
+});
+
+const { data, error } = await admin.auth.admin.createUser({
+  username: "admin", // and/or email
+  password,
+  // emailConfirm: false — only with an email; users are confirmed otherwise
+});
+const {
+  data: { users, total },
+} = await admin.auth.admin.listUsers({ page: 1, perPage: 50 });
+await admin.auth.admin.deleteUser(data.user.id);
+```
+
+- `createUser` takes an email, a username or both. The user is confirmed
+  and signs in at once — while sign-ups are closed, and while sign-in waits
+  for a confirmed email — unless `emailConfirm: false` (which needs an
+  email). A user with only a username answers `email: null`, here, in
+  `signIn` and in `getUser()`, and signs in with its username. Answers
+  carry `id`, `email`, `username`, `emailVerified` and `createdAt`, never a
+  password.
+- `listUsers` is newest first, 50 a page unless `perPage` says (at most
+  1000), with the `total`. `deleteUser(id)` removes the user and its
+  sign-in methods and ends its sessions; an unknown id is
+  `404 USER_NOT_FOUND` ("No user has this id.").
+- `auth.admin` works only on a client made with `serviceKey`. On an anon
+  client each call answers `403 PERMISSION_DENIED` ("Only the service key
+  can manage users.") without a request.
+- A username is 3–30 letters, digits, `_` and `.`, and is matched in any
+  case (stored lowercased). `signUp({ email, password, username })` sets one
+  at sign-up.
+- Closed sign-ups: every `signUp` answers `403 SIGNUPS_DISABLED` ("Sign-ups
+  are closed for this project."), and so does a first Google or GitHub
+  sign-in, in `getSessionFromUrl()`. Users that exist keep signing in, with
+  a password or a provider. `naro backend auth signups on` opens them again.
+- While sign-ups are open, a sign-up with a username someone has answers
+  `409 USERNAME_TAKEN` ("That username is already taken.") — so anyone can
+  learn which usernames exist, as fast as sign-up's per-address rate limit
+  lets them. With sign-ups closed, every sign-up answers
+  `403 SIGNUPS_DISABLED` first. `createUser` answers `USERNAME_TAKEN` too,
+  and `422 USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL` for an email in use.
+- Passwords take at least 6 characters unless
+  `naro backend auth password --min-length <n>` (6–128) says more. A
+  shorter one, on sign-up, `createUser` or a reset, answers
+  `400 PASSWORD_TOO_SHORT` naming it: "Use at least 10 characters." Sign-in
+  never checks the length, so raising it locks nobody out.
+- Creating and deleting users are writes: past the project's daily write
+  limit they answer `429 WRITE_QUOTA_EXCEEDED`, like sign-up.
+- A backend turned on before these existed gets them with its next upload:
+  run `naro backend enable` once. Until then `auth.admin` and
+  `signIn({ username })` answer `404 NOT_FOUND`.
+
 ## Sign-in flows
 
 Google and GitHub sign-in, email confirmation and password reset, once the
-project has set them up (`naro backend auth`). The names follow supabase-js.
+project has set them up (`naro backend auth`). Email and password sign-up
+and sign-in need none of it. The names follow supabase-js.
 
 ```ts
 // Sends the browser to the project's /_naro/v1/auth/authorize/github, then

package/dist/auth/admin.d.ts

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

package/dist/auth/client.d.ts

@@ -1,9 +1,10 @@
 import { type NaroError } from "../errors.js";
 import { type HttpConfig } from "../http.js";
 import type { AuthActionResponse, EmailRedirectOptions, OAuthResponse, SessionResponse, SignInCredentials, SignInWithOAuthOptions, SignOutResponse, SignUpCredentials, UrlSessionResponse, UserAttributes, UserResponse } from "../types.js";
+import { AuthAdminApi } from "./admin.js";
 import type { FlowVerifiers } from "./flows.js";
 import type { RecoveryToken } from "./recovery.js";
-/** Better Auth requires `name` on sign-up; the email's local part stands in. */
+/** Sign-up needs a `name`; the email's local part stands in. */
 export declare function defaultName(email: string): string;
 export type AuthFlowStores = {
     /** The PKCE verifiers of the provider sign-ins this browser began. */
@@ -24,24 +25,42 @@ export type AuthFlowStores = {
         storage: object;
         key: string;
     };
+    /** Made with the service key: `admin` sends its requests. */
+    serviceKey: boolean;
 };
 /** How long the code exchange a sign-in redirect starts may take. */
 export declare const EXCHANGE_TIMEOUT_MS = 15000;
 /**
- * `naro.auth` — email and password, email confirmation, password reset and
- * provider sign-in through the worker's Better Auth routes
- * (`/_naro/v1/auth/*`, spec §8.1, §13; P2-6 §13.3). Every method resolves;
- * none throws.
+ * `naro.auth` — naro Auth, the project's own sign-in (like Supabase Auth):
+ * email or username and password, email confirmation, password reset and
+ * provider sign-in through the worker's `/_naro/v1/auth/*` routes (spec
+ * §8.1, §13; P2-6 §13.3; 2026-09-26 §2.3). Email and password work with no
+ * setup; email is needed only to send confirmation and reset links. Every
+ * method resolves; none throws.
  */
 export declare class AuthClient {
     #private;
+    /**
+     * The service key's user management — createUser, listUsers, deleteUser,
+     * as in supabase-js (spec 2026-09-26 §2.2). Only on a client made with
+     * `serviceKey`, on a server.
+     */
+    readonly admin: AuthAdminApi;
     constructor(http: HttpConfig, flow: AuthFlowStores);
     /**
      * Creates the account and signs in; the token is stored for later calls.
      * When the project requires a confirmed email there is no session yet —
      * `user` comes back, and after the confirmation link the user signs in.
+     * While the project's sign-ups are closed every sign-up answers 403
+     * SIGNUPS_DISABLED; while they are open, a taken `username` answers 409
+     * USERNAME_TAKEN.
      */
     signUp(credentials: SignUpCredentials): Promise<UserResponse>;
+    /**
+     * Signs in with an email and password, or a username and password (spec
+     * 2026-09-26 §2.3); the token is stored for later calls. A wrong password
+     * answers 401 INVALID_EMAIL_OR_PASSWORD, or INVALID_USERNAME_OR_PASSWORD.
+     */
     signIn(credentials: SignInCredentials): Promise<UserResponse>;
     /**
      * Starts a Google or GitHub sign-in: sends the browser, with a top-level

package/dist/auth/flows.d.ts

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

package/dist/client.d.ts

@@ -46,7 +46,10 @@ export declare const CONFIG_MESSAGES: {
 };
 export declare class NaroClient<Database extends DatabaseShape<Database>> {
     #private;
-    /** Sign-up, sign-in, sign-out and the current user (spec §13). */
+    /**
+     * Sign-up, sign-in, sign-out and the current user (spec §13); with the
+     * service key, `auth.admin` manages users.
+     */
     readonly auth: AuthClient;
     constructor(options: ClientOptions);
     /** Start a query on `table`: `.select()`, `.insert()`, `.update()` or `.delete()`. */

package/dist/errors.d.ts

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

package/dist/http.d.ts

@@ -15,7 +15,7 @@ export type HttpConfig = {
     tokens: TokenStore;
 };
 export type CallOptions = {
-    method: "GET" | "POST";
+    method: "GET" | "POST" | "DELETE";
     /** Below `/_naro/v1`, e.g. `/data/query`. */
     path: string;
     /** Sent as JSON. */
@@ -54,8 +54,9 @@ export type CallResult = {
  */
 export declare function call(config: HttpConfig, options: CallOptions): Promise<CallResult>;
 /**
- * The worker's two 429s. `RATE_LIMITED` is Better Auth's limiter;
- * `WRITE_QUOTA_EXCEEDED` (PR C) is the project over its daily database write
- * limit — Data API writes and sign-up wait for 00:00 UTC, reads still work.
+ * The worker's two 429s. `RATE_LIMITED` is the sign-in routes' per-address
+ * limiter; `WRITE_QUOTA_EXCEEDED` (PR C) is the project over its daily
+ * database write limit — Data API writes, sign-up and creating or deleting
+ * users wait for 00:00 UTC, reads still work.
  */
 export declare const RETRY_AFTER_CODES: ReadonlySet<string>;

package/dist/index.d.ts

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

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) {
@@ -196,6 +203,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 +298,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 +420,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 +433,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 +443,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
@@ -1668,9 +1788,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 +1810,17 @@ 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;
   #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,7 +1838,8 @@ 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);
   }

package/dist/types.d.ts

@@ -81,10 +81,19 @@ export type OrderOptions = {
     /** Where NULLs go. Omitted, SQLite's default: first ascending, last descending. */
     nullsFirst?: boolean;
 };
-/** Better Auth's user (spec §13), as JSON: dates are ISO strings. */
+/**
+ * The signed-in user, as naro Auth answers it (spec §13): dates are ISO
+ * strings. `email` is null for a user created with only a username
+ * (`auth.admin.createUser({ username, password })`).
+ */
 export type User = {
     id: string;
-    email: string;
+    email: string | null;
+    /**
+     * Lowercased; null for a user without one. Absent from a backend whose
+     * Naro worker predates usernames (`naro backend enable` updates it).
+     */
+    username?: string | null;
     name: string;
     emailVerified: boolean;
     image?: string | null;
@@ -92,7 +101,7 @@ export type User = {
     updatedAt: string;
     [field: string]: unknown;
 };
-/** Better Auth's session, as JSON. */
+/** The session, as naro Auth answers it. */
 export type Session = {
     id: string;
     userId: string;
@@ -124,7 +133,16 @@ export type SignOutResponse = {
 export type SignUpCredentials = {
     email: string;
     password: string;
-    /** Better Auth requires a name; omitted, the email's local part is sent. */
+    /**
+     * A name to sign in by as well as the email (spec 2026-09-26 §2.3): 3–30
+     * letters, digits, `_` and `.`, stored lowercased. One that is taken
+     * answers 409 USERNAME_TAKEN.
+     */
+    username?: string;
+    /**
+     * Every user has a display name; omitted, the username is sent, or else
+     * the email's local part.
+     */
     name?: string;
     /**
      * Where the confirmation link sends the browser back to, when the project
@@ -133,8 +151,17 @@ export type SignUpCredentials = {
      */
     redirectTo?: string;
 };
+/**
+ * An email and its password, or a username and its password (spec
+ * 2026-09-26 §2.3). A username is matched in any case.
+ */
 export type SignInCredentials = {
     email: string;
+    username?: undefined;
+    password: string;
+} | {
+    username: string;
+    email?: undefined;
     password: string;
 };
 export type OAuthProvider = "google" | "github";
@@ -183,4 +210,59 @@ export type AuthActionResponse = {
     data: null;
     error: NaroError | null;
 };
+/**
+ * A user as `naro.auth.admin` answers it — never a password or a hash.
+ * `email` is null for a user created with only a username.
+ */
+export type AdminUser = {
+    id: string;
+    email: string | null;
+    /** Lowercased; null for a user without one. */
+    username: string | null;
+    emailVerified: boolean;
+    /** ISO 8601. */
+    createdAt: string;
+};
+/**
+ * `auth.admin.createUser()`: an email, a username or both, and a password
+ * of at least the project's minimum length (6 unless
+ * `naro backend auth password --min-length` changed it). The user is
+ * confirmed — signs in at once, even where sign-in waits for a confirmed
+ * email — unless `emailConfirm: false`, which needs an email. (Supabase's
+ * `email_confirm` is false by default; here confirmed is the default.)
+ */
+export type AdminUserAttributes = {
+    email?: string;
+    username?: string;
+    password: string;
+    emailConfirm?: boolean;
+};
+/** `auth.admin.listUsers()`: page 1 and 50 a page unless given; at most 1000. */
+export type PageParams = {
+    page?: number;
+    perPage?: number;
+};
+export type AdminUserResponse = AuthResponse<{
+    user: AdminUser | null;
+}>;
+/** A page of users, newest first, and how many there are in all. */
+export type AdminUserListResponse = AuthResponse<{
+    users: AdminUser[];
+    total: number;
+}>;
+/**
+ * The codes sign-up, sign-in and `auth.admin` answer that an app branches
+ * on. `NaroError.code` can be any other string too.
+ */
+export type AuthErrorCode = 
+/** Sign-ups are closed: only `auth.admin.createUser` makes users. */
+"SIGNUPS_DISABLED"
+/** Sign-up or `createUser` with a username someone has, in any case. */
+ | "USERNAME_TAKEN" | "USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL"
+/** "Use at least {n} characters." — the project's minimum. */
+ | "PASSWORD_TOO_SHORT" | "PASSWORD_TOO_LONG" | "USERNAME_TOO_SHORT" | "USERNAME_TOO_LONG" | "INVALID_USERNAME" | "INVALID_EMAIL" | "INVALID_EMAIL_OR_PASSWORD" | "INVALID_USERNAME_OR_PASSWORD" | "EMAIL_NOT_VERIFIED" | "INVALID_SESSION"
+/** `auth.admin` without the service key. */
+ | "PERMISSION_DENIED"
+/** `auth.admin.deleteUser` with an id that is no user. */
+ | "USER_NOT_FOUND" | "RATE_LIMITED" | "WRITE_QUOTA_EXCEEDED";
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "naro-js",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Auth and data for your Naro project, from the browser or the server.",
   "type": "module",
   "sideEffects": false,
@@ -25,8 +25,8 @@
     "vitest": "3.2.7",
     "@next-deploy/backend-worker": "0.1.0",
     "@next-deploy/config": "0.1.0",
-    "@next-deploy/sdk": "0.1.0",
-    "@next-deploy/data-core": "0.1.0"
+    "@next-deploy/data-core": "0.1.0",
+    "@next-deploy/sdk": "0.1.0"
   },
   "scripts": {
     "build": "tsup && pnpm build:types",