@pramen/auth 0.0.7 → 0.0.9

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,132 @@ export declare function createMagicLinkAuth(opts: MagicLinkOptions): {
         };
     }>;
 };
+/** Build admin + self-service handlers over a users table (default `auth_users`).
+ * Pass `table` to operate over your OWN authSchema-shaped table — e.g. one with an
+ * extra `tenants` column — without renaming it: the handlers manage username/roles/
+ * email/active/delete and ignore any extra columns. Spread the result into your
+ * handler map and gate it with the matching `authPolicies({ table })`. The table must
+ * have a `username` primary key and (for changeEmail/changePassword) `email`/
+ * `passwordHash` columns. */
+export declare function createUserHandlers(opts?: {
+    table?: string;
+}): {
+    /** 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;
+    }>;
+};
+/** The default user-management handlers over `auth_users`. Equivalent to
+ * `createUserHandlers()`; spread alongside `authHandlers`. */
+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 the user-management handlers. 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.
+ *
+ * For a custom table, pass the same `table` you gave `createUserHandlers`, a unique
+ * `prefix` (policy names must be unique across roles when you wire more than one
+ * instance), and `adminReadFields`/`adminWriteFields` to expose/permit extra columns
+ * (e.g. a `tenants` column managed by your own setUserTenants handler). */
+export declare function authPolicies(opts?: {
+    table?: string;
+    identityPath?: string;
+    prefix?: string;
+    adminReadFields?: string[];
+    adminWriteFields?: string[];
+    selfReadFields?: string[];
+    selfWriteFields?: 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,191 @@ 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);
+            // Key on the USERNAME (the immutable identity = the JWT sub), NOT the mutable
+            // `email` column: a magic-link user's username IS their email address, so this
+            // both matches existing users and avoids resolving login by a mutable, unverified
+            // field (which would let a changeEmail squat another address — and would miss
+            // pre-`email`-column users on upgrade, colliding on the username PK).
+            const existing = await ctx.db.exec("SELECT roles, active FROM auth_users WHERE username = ? LIMIT 1", email);
             let roles;
             if (existing.length > 0) {
+                if (!isActive(existing[0].active))
+                    throw new Unauthorized("account is deactivated");
                 roles = JSON.parse(String(existing[0].roles));
             }
             else {
                 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());
+                // No email column set: it stays a pure contact attribute (set via changeEmail),
+                // so a new passwordless user can never collide with a password user's contact email.
+                await ctx.db.exec("INSERT INTO auth_users (username, passwordHash, roles, createdAt) VALUES (?, ?, ?, ?)", email, "", JSON.stringify(roles), Date.now());
             }
             const token = await signToken({ sub: email, roles }, secretOf(ctx), { ttlSeconds: sessionTtl });
             return { token, user: { username: email, 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;
+// The users table must be a valid SQL identifier (it's interpolated into the raw exec
+// strings below). It's app config, never request input, but guard it anyway.
+function assertIdentifier(table) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table))
+        throw new Error(`@pramen/auth: invalid table name ${JSON.stringify(table)}`);
+    return table;
+}
+/** Build admin + self-service handlers over a users table (default `auth_users`).
+ * Pass `table` to operate over your OWN authSchema-shaped table — e.g. one with an
+ * extra `tenants` column — without renaming it: the handlers manage username/roles/
+ * email/active/delete and ignore any extra columns. Spread the result into your
+ * handler map and gate it with the matching `authPolicies({ table })`. The table must
+ * have a `username` primary key and (for changeEmail/changePassword) `email`/
+ * `passwordHash` columns. */
+export function createUserHandlers(opts = {}) {
+    const table = assertIdentifier(opts.table ?? "auth_users");
+    return {
+        /** 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: table, 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(table, 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(table, 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(table, 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 ${table} 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(table, 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 ${table} 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 ${table} SET passwordHash = ? WHERE username = ?`, await hashPassword(next), userId);
+            return { ok: true };
+        }),
+    };
+}
+/** The default user-management handlers over `auth_users`. Equivalent to
+ * `createUserHandlers()`; spread alongside `authHandlers`. */
+export const userHandlers = createUserHandlers();
+// 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 the user-management handlers. 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.
+ *
+ * For a custom table, pass the same `table` you gave `createUserHandlers`, a unique
+ * `prefix` (policy names must be unique across roles when you wire more than one
+ * instance), and `adminReadFields`/`adminWriteFields` to expose/permit extra columns
+ * (e.g. a `tenants` column managed by your own setUserTenants handler). */
+export function authPolicies(opts = {}) {
+    const table = opts.table ?? "auth_users";
+    const idPath = opts.identityPath ?? "userId";
+    const p = opts.prefix ?? "auth";
+    const adminRead = opts.adminReadFields ?? ADMIN_READ_FIELDS;
+    const adminWrite = opts.adminWriteFields ?? ["roles", "email", "active"];
+    const selfRead = opts.selfReadFields ?? SELF_READ_FIELDS;
+    const selfWrite = opts.selfWriteFields ?? ["email"];
+    return {
+        admin: [
+            policy(`${p}:admin:read`, table, "read", { fields: adminRead }),
+            policy(`${p}:admin:update`, table, "update", { fields: adminWrite }),
+            policy(`${p}:admin:delete`, table, "delete", allow()),
+        ],
+        self: [
+            policy(`${p}:self:read`, table, "read", { where: { username: $identity(idPath) }, fields: selfRead }),
+            policy(`${p}:self:update`, table, "update", { where: { username: $identity(idPath) }, fields: selfWrite }),
+        ],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/auth",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "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.9"
   }
 }

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,14 +282,21 @@ 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);
+        // Key on the USERNAME (the immutable identity = the JWT sub), NOT the mutable
+        // `email` column: a magic-link user's username IS their email address, so this
+        // both matches existing users and avoids resolving login by a mutable, unverified
+        // field (which would let a changeEmail squat another address — and would miss
+        // pre-`email`-column users on upgrade, colliding on the username PK).
+        const existing = await ctx.db.exec("SELECT roles, active FROM auth_users WHERE username = ? LIMIT 1", email);
         let roles: string[];
         if (existing.length > 0) {
+          if (!isActive(existing[0].active)) throw new Unauthorized("account is deactivated");
           roles = JSON.parse(String(existing[0].roles)) as string[];
         } else {
           roles = defaultRoles;
+          // No email column set: it stays a pure contact attribute (set via changeEmail),
+          // so a new passwordless user can never collide with a password user's contact email.
           await ctx.db.exec(
-            // Empty passwordHash can never verify → the user stays passwordless.
             "INSERT INTO auth_users (username, passwordHash, roles, createdAt) VALUES (?, ?, ?, ?)",
             email,
             "",
@@ -292,3 +311,184 @@ export function createMagicLinkAuth(opts: MagicLinkOptions) {
     ),
   };
 }
+
+// --- 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 the users table 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 UsersDb {
+  update(table: string, id: string, patch: Record<string, unknown>): Promise<Record<string, unknown> | undefined>;
+  delete(table: string, id: string): Promise<boolean>;
+}
+const usersDb = (ctx: HandlerContext): UsersDb => ctx.db as unknown as UsersDb;
+
+// The users table must be a valid SQL identifier (it's interpolated into the raw exec
+// strings below). It's app config, never request input, but guard it anyway.
+function assertIdentifier(table: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(table)) throw new Error(`@pramen/auth: invalid table name ${JSON.stringify(table)}`);
+  return table;
+}
+
+/** Build admin + self-service handlers over a users table (default `auth_users`).
+ * Pass `table` to operate over your OWN authSchema-shaped table — e.g. one with an
+ * extra `tenants` column — without renaming it: the handlers manage username/roles/
+ * email/active/delete and ignore any extra columns. Spread the result into your
+ * handler map and gate it with the matching `authPolicies({ table })`. The table must
+ * have a `username` primary key and (for changeEmail/changePassword) `email`/
+ * `passwordHash` columns. */
+export function createUserHandlers(opts: { table?: string } = {}) {
+  const table = assertIdentifier(opts.table ?? "auth_users");
+  return {
+    /** 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: table, 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(table, 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(table, 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(table, 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 ${table} 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(table, 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 ${table} 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 ${table} SET passwordHash = ? WHERE username = ?`, await hashPassword(next), userId);
+      return { ok: true };
+    }),
+  };
+}
+
+/** The default user-management handlers over `auth_users`. Equivalent to
+ * `createUserHandlers()`; spread alongside `authHandlers`. */
+export const userHandlers = createUserHandlers();
+
+// 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 the user-management handlers. 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.
+ *
+ * For a custom table, pass the same `table` you gave `createUserHandlers`, a unique
+ * `prefix` (policy names must be unique across roles when you wire more than one
+ * instance), and `adminReadFields`/`adminWriteFields` to expose/permit extra columns
+ * (e.g. a `tenants` column managed by your own setUserTenants handler). */
+export function authPolicies(opts: {
+  table?: string;
+  identityPath?: string;
+  prefix?: string;
+  adminReadFields?: string[];
+  adminWriteFields?: string[];
+  selfReadFields?: string[];
+  selfWriteFields?: string[];
+} = {}): { admin: Policy[]; self: Policy[] } {
+  const table = opts.table ?? "auth_users";
+  const idPath = opts.identityPath ?? "userId";
+  const p = opts.prefix ?? "auth";
+  const adminRead = opts.adminReadFields ?? ADMIN_READ_FIELDS;
+  const adminWrite = opts.adminWriteFields ?? ["roles", "email", "active"];
+  const selfRead = opts.selfReadFields ?? SELF_READ_FIELDS;
+  const selfWrite = opts.selfWriteFields ?? ["email"];
+  return {
+    admin: [
+      policy(`${p}:admin:read`, table, "read", { fields: adminRead }),
+      policy(`${p}:admin:update`, table, "update", { fields: adminWrite }),
+      policy(`${p}:admin:delete`, table, "delete", allow()),
+    ],
+    self: [
+      policy(`${p}:self:read`, table, "read", { where: { username: $identity(idPath) }, fields: selfRead }),
+      policy(`${p}:self:update`, table, "update", { where: { username: $identity(idPath) }, fields: selfWrite }),
+    ],
+  };
+}