@pramen/auth 0.0.7 → 0.0.8

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { HandlerContext } from "@pramen/server";
+import type { HandlerContext, Policy } from "@pramen/server";
 export declare const authSchema: {
     auth_users: import("@pramen/server").EntityDef<{
         username: {
@@ -8,10 +8,22 @@ export declare const authSchema: {
         };
         passwordHash: {
             readonly type: "text";
+        } & {
+            readonly hidden: true;
         };
         roles: {
             readonly type: "json";
         };
+        email: {
+            readonly type: "text";
+        } & {
+            readonly unique: true;
+        };
+        active: {
+            readonly type: "boolean";
+        } & {
+            readonly default: true;
+        };
         createdAt: {
             readonly type: "integer";
         };
@@ -106,3 +118,67 @@ export declare function createMagicLinkAuth(opts: MagicLinkOptions): {
         };
     }>;
 };
+/** Admin + self-service handlers over `auth_users`. Spread into your handler map
+ * alongside `authHandlers`; gate them by spreading `authPolicies()` into your roles. */
+export declare const userHandlers: {
+    /** Admin: list users (ACL projects out passwordHash). A non-admin caller granted
+     * only the self policy sees just their own row; ungranted callers get a 403. */
+    listUsers: import("@pramen/server").Handler<{
+        limit?: number;
+        offset?: number;
+    }, (import("@pramen/server").InferRow<import("@pramen/server").EntityFields> & Partial<{
+        [x: string]: import("@pramen/server").InferRow<import("@pramen/server").EntityFields> | import("@pramen/server").InferRow<import("@pramen/server").EntityFields>[] | null;
+    }>)[]>;
+    /** Admin: replace a user's roles. The ACL admin update policy permits writing
+     * `roles`; a self-only caller can't (so this is admin-gated declaratively). */
+    setUserRoles: import("@pramen/server").Handler<{
+        username: string;
+        roles: string[];
+    }, Record<string, unknown>>;
+    /** Admin: activate / deactivate a user. Deactivating blocks future logins (and
+     * token refresh); existing tokens still expire naturally within the TTL. */
+    setUserActive: import("@pramen/server").Handler<{
+        username: string;
+        active: boolean;
+    }, Record<string, unknown>>;
+    /** Admin: permanently delete a user. ACL-gated by the admin delete policy; a caller
+     * cannot delete their own account. Deactivation (setUserActive) is usually preferable. */
+    deleteUser: import("@pramen/server").Handler<{
+        username: string;
+    }, {
+        ok: boolean;
+    }>;
+    /** Self-service: change the caller's contact email. The ACL self policy scopes the
+     * write to the caller's own row and permits only the `email` field. Email is unique,
+     * so a clash is reported as a clean 400 rather than surfacing the DB constraint as a 500. */
+    changeEmail: import("@pramen/server").Handler<{
+        email: string;
+    }, Record<string, unknown>>;
+    /** Self-service: change the caller's password. A credential op — it reads the
+     * caller's OWN hash (passwordHash is never ACL-readable) to verify the current
+     * password, then writes the new one. Self-scoped by the verified identity, so it
+     * never touches another row; passwordless (magic-link) users have no current
+     * password and are rejected. */
+    changePassword: import("@pramen/server").Handler<{
+        currentPassword: string;
+        newPassword: string;
+    }, {
+        ok: boolean;
+    }>;
+};
+/** ACL policy fragments that turn on `userHandlers`. Spread `admin` into your admin
+ * role and `self` into your authenticated-user role:
+ *
+ *   role("admin", [...authPolicies().admin, ...yourAdminPolicies])
+ *   role("user",  [...authPolicies().self,  ...yourUserPolicies])
+ *
+ * `admin` grants read (projected) + update of roles/email/active on every user.
+ * `self` grants each user read + email-update of ONLY their own row (matched on the
+ * `userId` identity claim). passwordHash is in no policy, so it is never exposed. */
+export declare function authPolicies(opts?: {
+    table?: string;
+    identityPath?: string;
+}): {
+    admin: Policy[];
+    self: Policy[];
+};

package/dist/index.js

@@ -15,13 +15,15 @@
 // Passwordless magic-link login is also available via createMagicLinkAuth (spread
 // magicLinkSchema too). It is transport-agnostic: you supply sendEmail; pramen owns
 // the token lifecycle. See createMagicLinkAuth below.
-import { Entity, mutation, query, BadRequest, Unauthorized } from "@pramen/server";
+import { Entity, mutation, query, defaultTo, unique, hidden, policy, allow, $identity, BadRequest, Unauthorized } from "@pramen/server";
 // --- schema fragment: spread into your defineSchema so the table is migrated ---
 export const authSchema = {
     auth_users: Entity((t) => ({
-        username: t.textId(),
-        passwordHash: t.text(),
+        username: t.textId(), // stable identity / PK (= the JWT `sub`); not the email
+        passwordHash: hidden(t.text()), // never readable via the ORM; empty for passwordless users
         roles: t.json(), // string[]
+        email: unique(t.text()), // mutable contact email (nullable, unique); the magic-link key
+        active: defaultTo(t.bool(), true), // deactivation flag — false blocks login (additive, backfills 1)
         createdAt: t.int(),
     })),
 };
@@ -86,6 +88,12 @@ function secretOf(ctx) {
 }
 const DEFAULT_ROLES = ["user"];
 const TOKEN_TTL_SECONDS = 3600;
+/** Session-token lifetime: AUTH_SESSION_TTL_SECONDS from the env (a deployment can
+ * shorten it to tighten the deactivation/role-change window), else 1h. */
+function sessionTtlOf(ctx) {
+    const v = Number(ctx.env.AUTH_SESSION_TTL_SECONDS);
+    return Number.isFinite(v) && v > 0 ? Math.trunc(v) : TOKEN_TTL_SECONDS;
+}
 function parseCreds(raw) {
     const o = (raw ?? {});
     if (typeof o.username !== "string" || o.username.length === 0)
@@ -103,17 +111,21 @@ export const authHandlers = {
             throw new BadRequest("username is taken");
         const roles = DEFAULT_ROLES;
         await ctx.db.exec("INSERT INTO auth_users (username, passwordHash, roles, createdAt) VALUES (?, ?, ?, ?)", input.username, await hashPassword(input.password), JSON.stringify(roles), Date.now());
-        const token = await signToken({ sub: input.username, roles }, secretOf(ctx), { ttlSeconds: TOKEN_TTL_SECONDS });
+        const token = await signToken({ sub: input.username, roles }, secretOf(ctx), { ttlSeconds: sessionTtlOf(ctx) });
         return { token, user: { username: input.username, roles } };
     }, { input: parseCreds }),
     login: mutation(async (ctx, input) => {
-        const rows = await ctx.db.exec("SELECT username, passwordHash, roles FROM auth_users WHERE username = ? LIMIT 1", input.username);
+        const rows = await ctx.db.exec("SELECT username, passwordHash, roles, active FROM auth_users WHERE username = ? LIMIT 1", input.username);
         const u = rows[0];
         if (!u || !(await verifyPassword(input.password, String(u.passwordHash)))) {
             throw new Unauthorized("invalid username or password");
         }
+        // Only after the password verifies (so this can't enumerate accounts): a
+        // deactivated user gets no new token. Existing tokens expire within the TTL.
+        if (!isActive(u.active))
+            throw new Unauthorized("account is deactivated");
         const roles = JSON.parse(String(u.roles));
-        const token = await signToken({ sub: String(u.username), roles }, secretOf(ctx), { ttlSeconds: TOKEN_TTL_SECONDS });
+        const token = await signToken({ sub: String(u.username), roles }, secretOf(ctx), { ttlSeconds: sessionTtlOf(ctx) });
         return { token, user: { username: String(u.username), roles } };
     }, { input: parseCreds }),
     me: query((ctx) => ctx.identity),
@@ -194,19 +206,164 @@ export function createMagicLinkAuth(opts) {
             // Single-use: consume before issuing the session.
             await ctx.db.exec("UPDATE auth_magic_links SET consumedAt = ? WHERE tokenHash = ?", Date.now(), tokenHash);
             const email = String(link.email);
-            const existing = await ctx.db.exec("SELECT roles FROM auth_users WHERE username = ? LIMIT 1", email);
+            // Match on the EMAIL column (not username), so a magic link for an address a
+            // password user later set via changeEmail logs into THAT account — username
+            // (the JWT sub) stays the user's stable identity. New users key username = email.
+            const existing = await ctx.db.exec("SELECT username, roles, active FROM auth_users WHERE email = ? LIMIT 1", email);
+            let username;
             let roles;
             if (existing.length > 0) {
+                if (!isActive(existing[0].active))
+                    throw new Unauthorized("account is deactivated");
+                username = String(existing[0].username);
                 roles = JSON.parse(String(existing[0].roles));
             }
             else {
+                username = email;
                 roles = defaultRoles;
                 await ctx.db.exec(
                 // Empty passwordHash can never verify → the user stays passwordless.
-                "INSERT INTO auth_users (username, passwordHash, roles, createdAt) VALUES (?, ?, ?, ?)", email, "", JSON.stringify(roles), Date.now());
+                "INSERT INTO auth_users (username, passwordHash, roles, email, createdAt) VALUES (?, ?, ?, ?, ?)", email, "", JSON.stringify(roles), email, Date.now());
             }
-            const token = await signToken({ sub: email, roles }, secretOf(ctx), { ttlSeconds: sessionTtl });
-            return { token, user: { username: email, roles } };
+            const token = await signToken({ sub: username, roles }, secretOf(ctx), { ttlSeconds: sessionTtl });
+            return { token, user: { username, roles } };
         }, { input: parseLinkToken }),
     };
 }
+// --- user management ---------------------------------------------------------
+//
+// Admin + self-service operations over `auth_users`, built the pramen way: ordinary
+// handlers over `ctx.db` whose authorization is the ACL, not imperative `if (admin)`
+// checks. They are inert until you grant access — spread `authPolicies()` into your
+// roles (admin manages everyone; the authenticated user manages only itself). Because
+// the admin read policy restricts `fields`, `passwordHash` is never projected back.
+//
+// Role/active changes are baked into the JWT at login, so setUserRoles / setUserActive
+// take effect on the user's NEXT login — not instantly. That lag is the cost of the
+// stateless, verify-only core (no session store, by design). Tune the revocation window
+// with the AUTH_SESSION_TTL_SECONDS env var (default 3600); for immediate revocation an
+// app can keep a per-user denylist in ctx.kv and check it in a route/middleware —
+// deliberately left to the app rather than building a session store into the core.
+/** SQLite has no bool: `active` is stored 0/1 (NULL on a pre-column row = active). */
+function isActive(v) {
+    return v == null || Number(v) !== 0;
+}
+function requireUserId(ctx) {
+    const id = ctx.identity?.userId;
+    if (typeof id !== "string" || id.length === 0)
+        throw new Unauthorized("authentication required");
+    return id;
+}
+const usersDb = (ctx) => ctx.db;
+/** Admin + self-service handlers over `auth_users`. Spread into your handler map
+ * alongside `authHandlers`; gate them by spreading `authPolicies()` into your roles. */
+export const userHandlers = {
+    /** Admin: list users (ACL projects out passwordHash). A non-admin caller granted
+     * only the self policy sees just their own row; ungranted callers get a 403. */
+    listUsers: query(async (ctx, input) => {
+        const limit = Math.min(Math.max(Math.trunc(Number(input?.limit ?? 50)) || 50, 1), 200);
+        const offset = Math.max(Math.trunc(Number(input?.offset ?? 0)) || 0, 0);
+        return ctx.db.find({ from: "auth_users", orderBy: { column: "createdAt", dir: "desc" }, limit, offset });
+    }),
+    /** Admin: replace a user's roles. The ACL admin update policy permits writing
+     * `roles`; a self-only caller can't (so this is admin-gated declaratively). */
+    setUserRoles: mutation(async (ctx, input) => {
+        if (typeof input?.username !== "string" || input.username.length === 0)
+            throw new BadRequest("username is required");
+        if (!Array.isArray(input.roles) || !input.roles.every((r) => typeof r === "string" && r.length > 0)) {
+            throw new BadRequest("roles must be a non-empty string[]");
+        }
+        const updated = await usersDb(ctx).update("auth_users", input.username, { roles: input.roles });
+        if (!updated)
+            throw new BadRequest("user not found"); // (or out of the caller's update scope)
+        return updated;
+    }),
+    /** Admin: activate / deactivate a user. Deactivating blocks future logins (and
+     * token refresh); existing tokens still expire naturally within the TTL. */
+    setUserActive: mutation(async (ctx, input) => {
+        if (typeof input?.username !== "string" || input.username.length === 0)
+            throw new BadRequest("username is required");
+        if (typeof input?.active !== "boolean")
+            throw new BadRequest("active must be a boolean");
+        if (input.active === false && input.username === ctx.identity?.userId) {
+            throw new BadRequest("cannot deactivate your own account");
+        }
+        const updated = await usersDb(ctx).update("auth_users", input.username, { active: input.active });
+        if (!updated)
+            throw new BadRequest("user not found");
+        return updated;
+    }),
+    /** Admin: permanently delete a user. ACL-gated by the admin delete policy; a caller
+     * cannot delete their own account. Deactivation (setUserActive) is usually preferable. */
+    deleteUser: mutation(async (ctx, input) => {
+        if (typeof input?.username !== "string" || input.username.length === 0)
+            throw new BadRequest("username is required");
+        if (input.username === ctx.identity?.userId)
+            throw new BadRequest("cannot delete your own account");
+        const deleted = await usersDb(ctx).delete("auth_users", input.username);
+        if (!deleted)
+            throw new BadRequest("user not found");
+        return { ok: true };
+    }),
+    /** Self-service: change the caller's contact email. The ACL self policy scopes the
+     * write to the caller's own row and permits only the `email` field. Email is unique,
+     * so a clash is reported as a clean 400 rather than surfacing the DB constraint as a 500. */
+    changeEmail: mutation(async (ctx, input) => {
+        const userId = requireUserId(ctx);
+        const { email } = parseEmail(input); // validates + normalizes; 400 on a bad address
+        const taken = await ctx.db.exec("SELECT 1 FROM auth_users WHERE email = ? AND username != ? LIMIT 1", email, userId);
+        if (taken.length > 0)
+            throw new BadRequest("email already in use");
+        const updated = await usersDb(ctx).update("auth_users", userId, { email });
+        if (!updated)
+            throw new Unauthorized("authentication required");
+        return updated;
+    }),
+    /** Self-service: change the caller's password. A credential op — it reads the
+     * caller's OWN hash (passwordHash is never ACL-readable) to verify the current
+     * password, then writes the new one. Self-scoped by the verified identity, so it
+     * never touches another row; passwordless (magic-link) users have no current
+     * password and are rejected. */
+    changePassword: mutation(async (ctx, input) => {
+        const userId = requireUserId(ctx);
+        const current = typeof input?.currentPassword === "string" ? input.currentPassword : "";
+        const next = typeof input?.newPassword === "string" ? input.newPassword : "";
+        if (next.length < 8)
+            throw new BadRequest("newPassword must be at least 8 characters");
+        const rows = await ctx.db.exec("SELECT passwordHash FROM auth_users WHERE username = ? LIMIT 1", userId);
+        const stored = rows[0] ? String(rows[0].passwordHash ?? "") : "";
+        if (stored === "" || !(await verifyPassword(current, stored))) {
+            throw new Unauthorized("current password is incorrect");
+        }
+        await ctx.db.exec("UPDATE auth_users SET passwordHash = ? WHERE username = ?", await hashPassword(next), userId);
+        return { ok: true };
+    }),
+};
+// Fields a self-service caller may see of their own row (never passwordHash/roles).
+const SELF_READ_FIELDS = ["username", "email", "active", "createdAt"];
+// Fields an admin may see of any user (never passwordHash).
+const ADMIN_READ_FIELDS = ["username", "roles", "email", "active", "createdAt"];
+/** ACL policy fragments that turn on `userHandlers`. Spread `admin` into your admin
+ * role and `self` into your authenticated-user role:
+ *
+ *   role("admin", [...authPolicies().admin, ...yourAdminPolicies])
+ *   role("user",  [...authPolicies().self,  ...yourUserPolicies])
+ *
+ * `admin` grants read (projected) + update of roles/email/active on every user.
+ * `self` grants each user read + email-update of ONLY their own row (matched on the
+ * `userId` identity claim). passwordHash is in no policy, so it is never exposed. */
+export function authPolicies(opts = {}) {
+    const table = opts.table ?? "auth_users";
+    const idPath = opts.identityPath ?? "userId";
+    return {
+        admin: [
+            policy("auth:admin:read", table, "read", { fields: ADMIN_READ_FIELDS }),
+            policy("auth:admin:update", table, "update", { fields: ["roles", "email", "active"] }),
+            policy("auth:admin:delete", table, "delete", allow()),
+        ],
+        self: [
+            policy("auth:self:read", table, "read", { where: { username: $identity(idPath) }, fields: SELF_READ_FIELDS }),
+            policy("auth:self:update", table, "update", { where: { username: $identity(idPath) }, fields: ["email"] }),
+        ],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/auth",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Optional credential→JWT login for pramen — signup/login/me + PBKDF2 hashing, issuing HS256 tokens the pramen verifier accepts.",
   "license": "MIT",
   "repository": {
@@ -34,6 +34,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@pramen/server": "0.0.7"
+    "@pramen/server": "0.0.8"
   }
 }

package/src/index.ts

@@ -16,16 +16,18 @@
 // magicLinkSchema too). It is transport-agnostic: you supply sendEmail; pramen owns
 // the token lifecycle. See createMagicLinkAuth below.
 
-import { Entity, mutation, query, BadRequest, Unauthorized } from "@pramen/server";
-import type { HandlerContext } from "@pramen/server";
+import { Entity, mutation, query, defaultTo, unique, hidden, policy, allow, $identity, BadRequest, Unauthorized } from "@pramen/server";
+import type { HandlerContext, Policy } from "@pramen/server";
 
 // --- schema fragment: spread into your defineSchema so the table is migrated ---
 
 export const authSchema = {
   auth_users: Entity((t) => ({
-    username: t.textId(),
-    passwordHash: t.text(),
+    username: t.textId(), // stable identity / PK (= the JWT `sub`); not the email
+    passwordHash: hidden(t.text()), // never readable via the ORM; empty for passwordless users
     roles: t.json(), // string[]
+    email: unique(t.text()), // mutable contact email (nullable, unique); the magic-link key
+    active: defaultTo(t.bool(), true), // deactivation flag — false blocks login (additive, backfills 1)
     createdAt: t.int(),
   })),
 };
@@ -109,6 +111,13 @@ function secretOf(ctx: HandlerContext): string {
 const DEFAULT_ROLES = ["user"];
 const TOKEN_TTL_SECONDS = 3600;
 
+/** Session-token lifetime: AUTH_SESSION_TTL_SECONDS from the env (a deployment can
+ * shorten it to tighten the deactivation/role-change window), else 1h. */
+function sessionTtlOf(ctx: HandlerContext): number {
+  const v = Number(ctx.env.AUTH_SESSION_TTL_SECONDS);
+  return Number.isFinite(v) && v > 0 ? Math.trunc(v) : TOKEN_TTL_SECONDS;
+}
+
 function parseCreds(raw: unknown): { username: string; password: string } {
   const o = (raw ?? {}) as Record<string, unknown>;
   if (typeof o.username !== "string" || o.username.length === 0) throw new Error("username is required");
@@ -131,7 +140,7 @@ export const authHandlers = {
         JSON.stringify(roles),
         Date.now(),
       );
-      const token = await signToken({ sub: input.username, roles }, secretOf(ctx), { ttlSeconds: TOKEN_TTL_SECONDS });
+      const token = await signToken({ sub: input.username, roles }, secretOf(ctx), { ttlSeconds: sessionTtlOf(ctx) });
       return { token, user: { username: input.username, roles } };
     },
     { input: parseCreds },
@@ -140,15 +149,18 @@ export const authHandlers = {
   login: mutation(
     async (ctx, input: { username: string; password: string }) => {
       const rows = await ctx.db.exec(
-        "SELECT username, passwordHash, roles FROM auth_users WHERE username = ? LIMIT 1",
+        "SELECT username, passwordHash, roles, active FROM auth_users WHERE username = ? LIMIT 1",
         input.username,
       );
       const u = rows[0];
       if (!u || !(await verifyPassword(input.password, String(u.passwordHash)))) {
         throw new Unauthorized("invalid username or password");
       }
+      // Only after the password verifies (so this can't enumerate accounts): a
+      // deactivated user gets no new token. Existing tokens expire within the TTL.
+      if (!isActive(u.active)) throw new Unauthorized("account is deactivated");
       const roles = JSON.parse(String(u.roles)) as string[];
-      const token = await signToken({ sub: String(u.username), roles }, secretOf(ctx), { ttlSeconds: TOKEN_TTL_SECONDS });
+      const token = await signToken({ sub: String(u.username), roles }, secretOf(ctx), { ttlSeconds: sessionTtlOf(ctx) });
       return { token, user: { username: String(u.username), roles } };
     },
     { input: parseCreds },
@@ -270,25 +282,180 @@ export function createMagicLinkAuth(opts: MagicLinkOptions) {
         await ctx.db.exec("UPDATE auth_magic_links SET consumedAt = ? WHERE tokenHash = ?", Date.now(), tokenHash);
 
         const email = String(link.email);
-        const existing = await ctx.db.exec("SELECT roles FROM auth_users WHERE username = ? LIMIT 1", email);
+        // Match on the EMAIL column (not username), so a magic link for an address a
+        // password user later set via changeEmail logs into THAT account — username
+        // (the JWT sub) stays the user's stable identity. New users key username = email.
+        const existing = await ctx.db.exec(
+          "SELECT username, roles, active FROM auth_users WHERE email = ? LIMIT 1",
+          email,
+        );
+        let username: string;
         let roles: string[];
         if (existing.length > 0) {
+          if (!isActive(existing[0].active)) throw new Unauthorized("account is deactivated");
+          username = String(existing[0].username);
           roles = JSON.parse(String(existing[0].roles)) as string[];
         } else {
+          username = email;
           roles = defaultRoles;
           await ctx.db.exec(
             // Empty passwordHash can never verify → the user stays passwordless.
-            "INSERT INTO auth_users (username, passwordHash, roles, createdAt) VALUES (?, ?, ?, ?)",
+            "INSERT INTO auth_users (username, passwordHash, roles, email, createdAt) VALUES (?, ?, ?, ?, ?)",
             email,
             "",
             JSON.stringify(roles),
+            email,
             Date.now(),
           );
         }
-        const token = await signToken({ sub: email, roles }, secretOf(ctx), { ttlSeconds: sessionTtl });
-        return { token, user: { username: email, roles } };
+        const token = await signToken({ sub: username, roles }, secretOf(ctx), { ttlSeconds: sessionTtl });
+        return { token, user: { username, roles } };
       },
       { input: parseLinkToken },
     ),
   };
 }
+
+// --- user management ---------------------------------------------------------
+//
+// Admin + self-service operations over `auth_users`, built the pramen way: ordinary
+// handlers over `ctx.db` whose authorization is the ACL, not imperative `if (admin)`
+// checks. They are inert until you grant access — spread `authPolicies()` into your
+// roles (admin manages everyone; the authenticated user manages only itself). Because
+// the admin read policy restricts `fields`, `passwordHash` is never projected back.
+//
+// Role/active changes are baked into the JWT at login, so setUserRoles / setUserActive
+// take effect on the user's NEXT login — not instantly. That lag is the cost of the
+// stateless, verify-only core (no session store, by design). Tune the revocation window
+// with the AUTH_SESSION_TTL_SECONDS env var (default 3600); for immediate revocation an
+// app can keep a per-user denylist in ctx.kv and check it in a route/middleware —
+// deliberately left to the app rather than building a session store into the core.
+
+/** SQLite has no bool: `active` is stored 0/1 (NULL on a pre-column row = active). */
+function isActive(v: unknown): boolean {
+  return v == null || Number(v) !== 0;
+}
+
+function requireUserId(ctx: HandlerContext): string {
+  const id = ctx.identity?.userId;
+  if (typeof id !== "string" || id.length === 0) throw new Unauthorized("authentication required");
+  return id;
+}
+
+// `ctx.db` is schema-typed against the *app's* composed schema, which this package
+// can't import — so address auth_users through a minimal structural view of the ACL'd
+// Db. This is the same ctx.db at runtime: row-scope + field projection still apply.
+interface AuthUsersDb {
+  update(table: "auth_users", id: string, patch: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+  delete(table: "auth_users", id: string): Promise<boolean>;
+}
+const usersDb = (ctx: HandlerContext): AuthUsersDb => ctx.db as unknown as AuthUsersDb;
+
+/** Admin + self-service handlers over `auth_users`. Spread into your handler map
+ * alongside `authHandlers`; gate them by spreading `authPolicies()` into your roles. */
+export const userHandlers = {
+  /** Admin: list users (ACL projects out passwordHash). A non-admin caller granted
+   * only the self policy sees just their own row; ungranted callers get a 403. */
+  listUsers: query(async (ctx, input: { limit?: number; offset?: number }) => {
+    const limit = Math.min(Math.max(Math.trunc(Number(input?.limit ?? 50)) || 50, 1), 200);
+    const offset = Math.max(Math.trunc(Number(input?.offset ?? 0)) || 0, 0);
+    return ctx.db.find({ from: "auth_users", orderBy: { column: "createdAt", dir: "desc" }, limit, offset });
+  }),
+
+  /** Admin: replace a user's roles. The ACL admin update policy permits writing
+   * `roles`; a self-only caller can't (so this is admin-gated declaratively). */
+  setUserRoles: mutation(async (ctx, input: { username: string; roles: string[] }) => {
+    if (typeof input?.username !== "string" || input.username.length === 0) throw new BadRequest("username is required");
+    if (!Array.isArray(input.roles) || !input.roles.every((r) => typeof r === "string" && r.length > 0)) {
+      throw new BadRequest("roles must be a non-empty string[]");
+    }
+    const updated = await usersDb(ctx).update("auth_users", input.username, { roles: input.roles });
+    if (!updated) throw new BadRequest("user not found"); // (or out of the caller's update scope)
+    return updated;
+  }),
+
+  /** Admin: activate / deactivate a user. Deactivating blocks future logins (and
+   * token refresh); existing tokens still expire naturally within the TTL. */
+  setUserActive: mutation(async (ctx, input: { username: string; active: boolean }) => {
+    if (typeof input?.username !== "string" || input.username.length === 0) throw new BadRequest("username is required");
+    if (typeof input?.active !== "boolean") throw new BadRequest("active must be a boolean");
+    if (input.active === false && input.username === ctx.identity?.userId) {
+      throw new BadRequest("cannot deactivate your own account");
+    }
+    const updated = await usersDb(ctx).update("auth_users", input.username, { active: input.active });
+    if (!updated) throw new BadRequest("user not found");
+    return updated;
+  }),
+
+  /** Admin: permanently delete a user. ACL-gated by the admin delete policy; a caller
+   * cannot delete their own account. Deactivation (setUserActive) is usually preferable. */
+  deleteUser: mutation(async (ctx, input: { username: string }) => {
+    if (typeof input?.username !== "string" || input.username.length === 0) throw new BadRequest("username is required");
+    if (input.username === ctx.identity?.userId) throw new BadRequest("cannot delete your own account");
+    const deleted = await usersDb(ctx).delete("auth_users", input.username);
+    if (!deleted) throw new BadRequest("user not found");
+    return { ok: true };
+  }),
+
+  /** Self-service: change the caller's contact email. The ACL self policy scopes the
+   * write to the caller's own row and permits only the `email` field. Email is unique,
+   * so a clash is reported as a clean 400 rather than surfacing the DB constraint as a 500. */
+  changeEmail: mutation(async (ctx, input: { email: string }) => {
+    const userId = requireUserId(ctx);
+    const { email } = parseEmail(input); // validates + normalizes; 400 on a bad address
+    const taken = await ctx.db.exec("SELECT 1 FROM auth_users WHERE email = ? AND username != ? LIMIT 1", email, userId);
+    if (taken.length > 0) throw new BadRequest("email already in use");
+    const updated = await usersDb(ctx).update("auth_users", userId, { email });
+    if (!updated) throw new Unauthorized("authentication required");
+    return updated;
+  }),
+
+  /** Self-service: change the caller's password. A credential op — it reads the
+   * caller's OWN hash (passwordHash is never ACL-readable) to verify the current
+   * password, then writes the new one. Self-scoped by the verified identity, so it
+   * never touches another row; passwordless (magic-link) users have no current
+   * password and are rejected. */
+  changePassword: mutation(async (ctx, input: { currentPassword: string; newPassword: string }) => {
+    const userId = requireUserId(ctx);
+    const current = typeof input?.currentPassword === "string" ? input.currentPassword : "";
+    const next = typeof input?.newPassword === "string" ? input.newPassword : "";
+    if (next.length < 8) throw new BadRequest("newPassword must be at least 8 characters");
+    const rows = await ctx.db.exec("SELECT passwordHash FROM auth_users WHERE username = ? LIMIT 1", userId);
+    const stored = rows[0] ? String(rows[0].passwordHash ?? "") : "";
+    if (stored === "" || !(await verifyPassword(current, stored))) {
+      throw new Unauthorized("current password is incorrect");
+    }
+    await ctx.db.exec("UPDATE auth_users SET passwordHash = ? WHERE username = ?", await hashPassword(next), userId);
+    return { ok: true };
+  }),
+};
+
+// Fields a self-service caller may see of their own row (never passwordHash/roles).
+const SELF_READ_FIELDS = ["username", "email", "active", "createdAt"];
+// Fields an admin may see of any user (never passwordHash).
+const ADMIN_READ_FIELDS = ["username", "roles", "email", "active", "createdAt"];
+
+/** ACL policy fragments that turn on `userHandlers`. Spread `admin` into your admin
+ * role and `self` into your authenticated-user role:
+ *
+ *   role("admin", [...authPolicies().admin, ...yourAdminPolicies])
+ *   role("user",  [...authPolicies().self,  ...yourUserPolicies])
+ *
+ * `admin` grants read (projected) + update of roles/email/active on every user.
+ * `self` grants each user read + email-update of ONLY their own row (matched on the
+ * `userId` identity claim). passwordHash is in no policy, so it is never exposed. */
+export function authPolicies(opts: { table?: string; identityPath?: string } = {}): { admin: Policy[]; self: Policy[] } {
+  const table = opts.table ?? "auth_users";
+  const idPath = opts.identityPath ?? "userId";
+  return {
+    admin: [
+      policy("auth:admin:read", table, "read", { fields: ADMIN_READ_FIELDS }),
+      policy("auth:admin:update", table, "update", { fields: ["roles", "email", "active"] }),
+      policy("auth:admin:delete", table, "delete", allow()),
+    ],
+    self: [
+      policy("auth:self:read", table, "read", { where: { username: $identity(idPath) }, fields: SELF_READ_FIELDS }),
+      policy("auth:self:update", table, "update", { where: { username: $identity(idPath) }, fields: ["email"] }),
+    ],
+  };
+}