@manablox/auth 0.2.0 → 0.3.0

package/dist/index.js

@@ -0,0 +1,418 @@
+import { rethrowUniqueViolation, schema } from "@manablox/db";
+import { betterAuth } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { APIError } from "better-auth/api";
+import { bearer } from "better-auth/plugins";
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { ALL_PERMISSIONS, ALL_PERMISSIONS as ALL_PERMISSIONS$1, BUILT_IN_ROLES, CONTENT_ACTIONS, ManabloxError, PERMISSION_GROUPS, grantsCover, grantsCover as grantsCover$1, intersectGrants, intersectGrants as intersectGrants$1, isBuiltInRole, normaliseGrants, parseGrant, permissionsFor, permissionsFor as permissionsFor$1, typesCoveredBy, typesCoveredBy as typesCoveredBy$1 } from "@manablox/core";
+import { and, eq, sql } from "drizzle-orm";
+//#region src/password.ts
+/**
+* Argon2id, the current OWASP recommendation over bcrypt — which also silently truncates
+* passwords at 72 bytes. One definition serves better-auth's own sign-in path and the
+* accounts an administrator creates, so both write the same hash format.
+*/
+async function hashPassword(password) {
+	const { hash } = await import("@node-rs/argon2");
+	return hash(password, {
+		memoryCost: 19456,
+		timeCost: 2,
+		parallelism: 1
+	});
+}
+async function verifyPassword(stored, password) {
+	const { verify } = await import("@node-rs/argon2");
+	return verify(stored, password);
+}
+/** Matches better-auth's `minPasswordLength`, so a password set here signs in there. */
+const MIN_PASSWORD_LENGTH = 12;
+//#endregion
+//#region src/api-key.ts
+const PREFIX = "mbx";
+/**
+* Takes a presented key apart. The secret is base64url and may itself contain `_`, so
+* the key is not split on it: the prefix is a fixed twelve hex characters and the
+* secret is whatever follows.
+*/
+function parseApiKey(presented) {
+	const match = /^([a-z]+)_([0-9a-f]{12})_([A-Za-z0-9_-]+)$/.exec(presented);
+	if (!match || match[1] !== PREFIX) return null;
+	return {
+		prefix: match[2],
+		secret: match[3]
+	};
+}
+/**
+* Long-lived credentials for headless consumers.
+*
+* Keys are stored as a SHA-256 digest, never in plaintext, and are looked up by an
+* indexed non-secret prefix so verification is one indexed read plus one constant-time
+* comparison — not a scan-and-compare over every row.
+*/
+var ApiKeyService = class {
+	db;
+	repos;
+	constructor(db, repos) {
+		this.db = db;
+		this.repos = repos;
+	}
+	async issue(userId, name, options = {}) {
+		const secret = randomBytes(32).toString("base64url");
+		const prefix = randomBytes(6).toString("hex");
+		const key = `${PREFIX}_${prefix}_${secret}`;
+		const [row] = await this.db.insert(schema.apikeys).values({
+			userId,
+			name,
+			prefix,
+			start: key.slice(0, 12),
+			key: digest(secret),
+			expiresAt: options.expiresAt ?? null,
+			spaceIds: options.spaceIds?.length ? options.spaceIds : null,
+			permissions: options.permissions ?? null
+		}).returning();
+		if (!row) throw new ManabloxError("apiKey.create.failed");
+		return {
+			id: row.id,
+			name,
+			key,
+			prefix
+		};
+	}
+	/**
+	* Deletes the row rather than clearing `enabled`: a revoked key is never listed again
+	* or re-enabled, so a disabled row is only a secret digest left lying around.
+	*/
+	async revoke(id) {
+		await this.db.delete(schema.apikeys).where(eq(schema.apikeys.id, id));
+	}
+	async list(userId) {
+		return this.db.select({
+			id: schema.apikeys.id,
+			name: schema.apikeys.name,
+			start: schema.apikeys.start,
+			enabled: schema.apikeys.enabled,
+			expiresAt: schema.apikeys.expiresAt,
+			lastRequest: schema.apikeys.lastRequest,
+			spaceIds: schema.apikeys.spaceIds,
+			permissions: schema.apikeys.permissions,
+			createdAt: schema.apikeys.createdAt
+		}).from(schema.apikeys).where(eq(schema.apikeys.userId, userId));
+	}
+	async resolve(presented) {
+		const parsed = parseApiKey(presented);
+		if (!parsed) return null;
+		const { prefix, secret } = parsed;
+		const row = (await this.db.select().from(schema.apikeys).where(and(eq(schema.apikeys.prefix, prefix), eq(schema.apikeys.enabled, true))).limit(1))[0];
+		if (!row) return null;
+		if (row.expiresAt && row.expiresAt.getTime() < Date.now()) return null;
+		const expected = Buffer.from(row.key, "hex");
+		const actual = Buffer.from(digest(secret), "hex");
+		if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) return null;
+		this.db.update(schema.apikeys).set({ lastRequest: /* @__PURE__ */ new Date() }).where(eq(schema.apikeys.id, row.id)).catch(() => void 0);
+		const user = await this.repos.users.findById(row.userId);
+		if (!user || user.banned) return null;
+		const resolved = await this.repos.users.principal(user.id);
+		if (!resolved) return null;
+		const allowed = row.spaceIds?.length ? new Set(row.spaceIds) : null;
+		const spaces = {};
+		const permissions = {};
+		for (const [spaceId, role] of Object.entries(resolved.spaces)) {
+			if (allowed && !allowed.has(spaceId)) continue;
+			spaces[spaceId] = role;
+			const grants = resolved.permissions[spaceId];
+			if (grants) permissions[spaceId] = grants;
+		}
+		return {
+			userId: user.id,
+			email: user.email,
+			role: user.role,
+			spaces,
+			permissions,
+			viaApiKey: true,
+			allowedSpaceIds: allowed ? [...allowed] : null,
+			allowedGrants: row.permissions
+		};
+	}
+	/** Removes expired keys; scheduled by the jobs package. */
+	async pruneExpired() {
+		return (await this.db.delete(schema.apikeys).where(sql`${schema.apikeys.expiresAt} is not null and ${schema.apikeys.expiresAt} < now()`).returning({ id: schema.apikeys.id })).length;
+	}
+};
+const digest = (secret) => createHash("sha256").update(secret).digest("hex");
+//#endregion
+//#region src/rbac.ts
+/** The grants a principal's role gives in a space, whatever kind of role it is. */
+function grantsIn(principal, spaceId) {
+	const role = principal.spaces[spaceId];
+	if (!role) return [];
+	return principal.permissions?.[spaceId] ?? permissionsFor$1(role);
+}
+/**
+* What a principal can actually do in a space: the role's grants (everything, for a
+* superadmin) narrowed by an API key's restriction, if the request came through one.
+*/
+function effectiveGrants(principal, spaceId) {
+	if (principal.allowedSpaceIds && !principal.allowedSpaceIds.includes(spaceId)) return [];
+	const held = principal.role === "superadmin" ? ALL_PERMISSIONS$1 : grantsIn(principal, spaceId);
+	return principal.allowedGrants ? intersectGrants$1(held, principal.allowedGrants) : held;
+}
+function can(principal, spaceId, permission, typeId) {
+	if (!principal) return false;
+	if (principal.allowedSpaceIds && (!spaceId || !principal.allowedSpaceIds.includes(spaceId))) return false;
+	if (principal.allowedGrants && !grantsCover$1(principal.allowedGrants, permission, typeId)) return false;
+	if (principal.role === "superadmin") return true;
+	if (!spaceId) return false;
+	return grantsCover$1(grantsIn(principal, spaceId), permission, typeId);
+}
+function assertCan(principal, spaceId, permission, typeId) {
+	if (can(principal, spaceId, permission, typeId)) return;
+	if (!principal) throw ManabloxError.unauthorized();
+	throw ManabloxError.forbidden("auth.forbidden", {
+		permission,
+		spaceId,
+		...typeId ? { typeId } : {}
+	});
+}
+/**
+* The content types a principal may perform an action on in a space, or `null` for
+* every type — what a listing narrows its filter to.
+*/
+function allowedTypeIds(principal, spaceId, permission) {
+	if (!principal) return [];
+	if (principal.role === "superadmin" && !principal.allowedGrants) return null;
+	return typesCoveredBy$1(effectiveGrants(principal, spaceId), permission);
+}
+/** Roles used by field-level `readRoles`/`writeRoles` checks. */
+function actorRoles(principal, spaceId) {
+	if (!principal) return [];
+	const roles = [principal.role];
+	if (spaceId && principal.spaces[spaceId]) roles.push(principal.spaces[spaceId]);
+	return roles;
+}
+//#endregion
+//#region src/user.service.ts
+/**
+* `users_email_key` is enforced in the database, so a taken address arrives as a
+* Postgres unique violation and would surface as an opaque 500.
+*/
+const emailConflict = (email) => (error) => rethrowUniqueViolation(error, {
+	constraint: "email",
+	key: "user.email.taken",
+	path: ["email"],
+	params: { email: email ?? "" },
+	errorKey: "user.validation.failed"
+});
+/**
+* Instance-wide user administration: the accounts, their instance role, and whether they
+* may sign in at all. Space membership stays with `SpaceService`, because it is a
+* property of the space.
+*
+* Every rule here exists to keep the instance reachable: an administrator cannot lock
+* themself out, and the instance always keeps at least one superadmin.
+*/
+var UserService = class {
+	repos;
+	constructor(repos) {
+		this.repos = repos;
+	}
+	async get(userId) {
+		const user = await this.repos.users.findById(userId);
+		if (!user) throw ManabloxError.notFound("user.notFound", { id: userId });
+		const memberships = await this.repos.users.membershipsWithSpaces(userId);
+		return {
+			...summary(user),
+			memberships: memberships.map((row) => ({
+				spaceId: row.spaceId,
+				role: row.role,
+				space: row.space
+			}))
+		};
+	}
+	async list(pagination, search) {
+		const page = await this.repos.users.list(pagination, search);
+		return {
+			...page,
+			items: page.items.map(summary)
+		};
+	}
+	async create(input) {
+		const email = normaliseEmail(input.email);
+		return summary(await this.repos.users.create({
+			name: input.name.trim(),
+			email,
+			role: input.role,
+			passwordHash: await hashPassword(input.password)
+		}).catch(emailConflict(email)));
+	}
+	async update(userId, input) {
+		const data = {};
+		if (input.name !== void 0) data.name = input.name.trim();
+		if (input.email !== void 0) data.email = normaliseEmail(input.email);
+		return summary(await this.repos.users.update(userId, data).catch(emailConflict(data.email)));
+	}
+	/** Changing the instance role; the last superadmin cannot step down. */
+	async setRole(userId, role) {
+		if (role !== "superadmin") await this.assertNotLastSuperadmin(userId);
+		return summary(await this.repos.users.setRole(userId, role));
+	}
+	/**
+	* A new password, and every session gone with the old one: whoever held the account
+	* before the reset does not keep it afterwards.
+	*/
+	async setPassword(userId, password) {
+		await this.require(userId);
+		await this.repos.users.setPasswordHash(userId, await hashPassword(password));
+		await this.repos.users.revokeSessions(userId);
+	}
+	/** A banned user is signed out everywhere and refused on the next request. */
+	async ban(actorId, userId, reason) {
+		this.assertNotSelf(actorId, userId);
+		await this.assertNotLastSuperadmin(userId);
+		const user = await this.repos.users.setBanned(userId, true, reason);
+		await this.repos.users.revokeSessions(userId);
+		return summary(user);
+	}
+	async unban(userId) {
+		return summary(await this.repos.users.setBanned(userId, false, null));
+	}
+	async delete(actorId, userId) {
+		this.assertNotSelf(actorId, userId);
+		await this.require(userId);
+		await this.assertNotLastSuperadmin(userId);
+		await this.repos.users.delete(userId);
+	}
+	/** Signs the user out of every device without touching the account. */
+	async revokeSessions(userId) {
+		await this.require(userId);
+		await this.repos.users.revokeSessions(userId);
+	}
+	async require(userId) {
+		const user = await this.repos.users.findById(userId);
+		if (!user) throw ManabloxError.notFound("user.notFound", { id: userId });
+		return user;
+	}
+	assertNotSelf(actorId, userId) {
+		if (actorId === userId) throw ManabloxError.badRequest("user.self.protected", { id: userId });
+	}
+	/**
+	* Whatever happens to `userId`, one superadmin must remain — otherwise the instance
+	* has no one left who can create a space or manage users, and no way back.
+	*/
+	async assertNotLastSuperadmin(userId) {
+		if ((await this.require(userId)).role !== "superadmin") return;
+		if (await this.repos.users.countByRole("superadmin") <= 1) throw ManabloxError.badRequest("user.lastSuperadmin", { id: userId });
+	}
+};
+function summary(user) {
+	return {
+		id: user.id,
+		name: user.name,
+		email: user.email,
+		image: user.image,
+		role: user.role,
+		banned: user.banned,
+		banReason: user.banReason,
+		createdAt: user.createdAt,
+		updatedAt: user.updatedAt
+	};
+}
+/** Lower-cased and trimmed, as better-auth stores it, so two spellings cannot coexist. */
+function normaliseEmail(email) {
+	return email.trim().toLowerCase();
+}
+//#endregion
+//#region src/index.ts
+function createAuth(config, db, callbacks = {}) {
+	return betterAuth({
+		secret: config.secret,
+		...config.baseUrl ? { baseURL: config.baseUrl } : {},
+		trustedOrigins: config.trustedOrigins ?? [],
+		database: drizzleAdapter(db, {
+			provider: "pg",
+			schema: {
+				user: schema.users,
+				session: schema.sessions,
+				account: schema.accounts,
+				verification: schema.verifications,
+				apikey: schema.apikeys
+			}
+		}),
+		emailAndPassword: {
+			enabled: config.emailAndPassword ?? true,
+			minPasswordLength: 12,
+			password: {
+				hash: hashPassword,
+				verify: ({ hash: stored, password }) => verifyPassword(stored, password)
+			}
+		},
+		session: {
+			expiresIn: config.sessionMaxAge ?? 604800,
+			updateAge: 86400,
+			cookieCache: {
+				enabled: true,
+				maxAge: 300
+			}
+		},
+		plugins: [bearer()],
+		databaseHooks: { user: { create: {
+			before: async (user) => {
+				if (!callbacks.allowSignUp || await callbacks.allowSignUp()) return { data: user };
+				throw new APIError("FORBIDDEN", { message: "auth.signUp.closed" });
+			},
+			after: async (user) => {
+				await callbacks.onUserCreated?.(user.id);
+			}
+		} } },
+		advanced: { database: { generateId: () => crypto.randomUUID() } }
+	});
+}
+/**
+* Resolves a request's session into a `Principal`, including its space memberships.
+* Returns `null` for anonymous requests rather than throwing — route guards decide.
+*/
+async function resolvePrincipal(auth, repos, headers, apiKeys) {
+	const presented = headers.get("x-api-key");
+	if (presented && apiKeys) {
+		const principal = await apiKeys.resolve(presented);
+		if (principal) return principal;
+	}
+	const session = await auth.api.getSession({ headers });
+	if (!session?.user) return null;
+	const principal = await repos.users.principal(session.user.id);
+	if (!principal || principal.banned) return null;
+	return {
+		userId: session.user.id,
+		email: session.user.email,
+		role: principal.role,
+		spaces: principal.spaces,
+		permissions: principal.permissions
+	};
+}
+/**
+* Promotes the very first account to `superadmin` and grants it ownership of every
+* existing space, so a fresh install is reachable.
+*
+* Called from better-auth's user-create hook rather than at startup, so it fires for an
+* account created after the server is already running.
+*/
+async function promoteFirstUser(manablox, repos, userId) {
+	if (await repos.users.count() !== 1) return;
+	const user = await repos.users.findById(userId);
+	if (!user || user.role === "superadmin") return;
+	await repos.users.setRole(userId, "superadmin");
+	for (const space of await repos.spaces.all()) await repos.users.grant(userId, space.id, "owner");
+	manablox.logger.info({ email: user.email }, "first account promoted to superadmin");
+}
+/** Covers an instance whose first account predates this behaviour. */
+function attachBootstrapOwner(manablox, repos) {
+	manablox.hooks.on("after:start", async () => {
+		const { items } = await repos.users.list({
+			limit: 1,
+			offset: 0
+		});
+		const first = items[0];
+		if (first && await repos.users.count() === 1) await promoteFirstUser(manablox, repos, first.id);
+	}, { source: "@manablox/auth" });
+}
+//#endregion
+export { ALL_PERMISSIONS, ApiKeyService, BUILT_IN_ROLES, CONTENT_ACTIONS, MIN_PASSWORD_LENGTH, PERMISSION_GROUPS, UserService, actorRoles, allowedTypeIds, assertCan, attachBootstrapOwner, can, createAuth, effectiveGrants, grantsCover, grantsIn, hashPassword, intersectGrants, isBuiltInRole, normaliseGrants, parseApiKey, parseGrant, permissionsFor, promoteFirstUser, resolvePrincipal, typesCoveredBy, verifyPassword };

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@manablox/auth",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "dependencies": {
-    "@manablox/core": "0.2.0",
-    "@manablox/db": "0.2.0",
+    "@manablox/core": "0.3.0",
+    "@manablox/db": "0.3.0",
     "better-auth": "^1.7.2",
     "drizzle-orm": "^0.45.2",
     "@node-rs/argon2": "^2.2.0"
@@ -20,10 +20,17 @@
   "devDependencies": {
     "@manablox/config-typescript": "0.0.0",
     "@types/node": "^26.4.1",
+    "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"
   },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md"
+  ],
   "scripts": {
+    "build": "tsdown",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"
   }

package/src/api-key.ts

@@ -1,164 +0,0 @@
-import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
-import { ManabloxError } from '@manablox/core';
-import { type Database, type Repositories, schema } from '@manablox/db';
-import { and, eq, sql } from 'drizzle-orm';
-import type { Principal, SpaceRole } from './rbac.js';
-
-export interface IssuedApiKey {
-  id: string;
-  name: string;
-  /** The full secret, shown once at creation and never recoverable afterwards. */
-  key: string;
-  prefix: string;
-}
-
-export interface IssueApiKeyOptions {
-  expiresAt?: Date | undefined;
-  /** Spaces the key may act in. `null`/omitted issues an unrestricted key. */
-  spaceIds?: string[] | null | undefined;
-  /** Grants the key may use. `null`/omitted leaves the owner's role as the limit. */
-  permissions?: string[] | null | undefined;
-}
-
-const PREFIX = 'mbx';
-
-/**
- * Takes a presented key apart. The secret is base64url and may itself contain `_`, so
- * the key is not split on it: the prefix is a fixed twelve hex characters and the
- * secret is whatever follows.
- */
-export function parseApiKey(presented: string): { prefix: string; secret: string } | null {
-  const match = /^([a-z]+)_([0-9a-f]{12})_([A-Za-z0-9_-]+)$/.exec(presented);
-  if (!match || match[1] !== PREFIX) return null;
-  return { prefix: match[2] as string, secret: match[3] as string };
-}
-
-/**
- * Long-lived credentials for headless consumers.
- *
- * Keys are stored as a SHA-256 digest, never in plaintext, and are looked up by an
- * indexed non-secret prefix so verification is one indexed read plus one constant-time
- * comparison — not a scan-and-compare over every row.
- */
-export class ApiKeyService {
-  constructor(
-    private readonly db: Database,
-    private readonly repos: Repositories,
-  ) {}
-
-  async issue(
-    userId: string,
-    name: string,
-    options: IssueApiKeyOptions = {},
-  ): Promise<IssuedApiKey> {
-    const secret = randomBytes(32).toString('base64url');
-    const prefix = randomBytes(6).toString('hex');
-    const key = `${PREFIX}_${prefix}_${secret}`;
-
-    const [row] = await this.db
-      .insert(schema.apikeys)
-      .values({
-        userId,
-        name,
-        prefix,
-        start: key.slice(0, 12),
-        key: digest(secret),
-        expiresAt: options.expiresAt ?? null,
-        spaceIds: options.spaceIds?.length ? options.spaceIds : null,
-        permissions: options.permissions ?? null,
-      })
-      .returning();
-
-    if (!row) throw new ManabloxError('apiKey.create.failed');
-    return { id: row.id, name, key, prefix };
-  }
-
-  /**
-   * Deletes the row rather than clearing `enabled`: a revoked key is never listed again
-   * or re-enabled, so a disabled row is only a secret digest left lying around.
-   */
-  async revoke(id: string): Promise<void> {
-    await this.db.delete(schema.apikeys).where(eq(schema.apikeys.id, id));
-  }
-
-  async list(userId: string) {
-    return this.db
-      .select({
-        id: schema.apikeys.id,
-        name: schema.apikeys.name,
-        start: schema.apikeys.start,
-        enabled: schema.apikeys.enabled,
-        expiresAt: schema.apikeys.expiresAt,
-        lastRequest: schema.apikeys.lastRequest,
-        spaceIds: schema.apikeys.spaceIds,
-        permissions: schema.apikeys.permissions,
-        createdAt: schema.apikeys.createdAt,
-      })
-      .from(schema.apikeys)
-      .where(eq(schema.apikeys.userId, userId));
-  }
-
-  async resolve(presented: string): Promise<Principal | null> {
-    const parsed = parseApiKey(presented);
-    if (!parsed) return null;
-    const { prefix, secret } = parsed;
-
-    const rows = await this.db
-      .select()
-      .from(schema.apikeys)
-      .where(and(eq(schema.apikeys.prefix, prefix), eq(schema.apikeys.enabled, true)))
-      .limit(1);
-
-    const row = rows[0];
-    if (!row) return null;
-    if (row.expiresAt && row.expiresAt.getTime() < Date.now()) return null;
-
-    const expected = Buffer.from(row.key, 'hex');
-    const actual = Buffer.from(digest(secret), 'hex');
-    if (expected.length !== actual.length || !timingSafeEqual(expected, actual)) return null;
-
-    // Best-effort touch; a failure here must never fail the request.
-    void this.db
-      .update(schema.apikeys)
-      .set({ lastRequest: new Date() })
-      .where(eq(schema.apikeys.id, row.id))
-      .catch(() => undefined);
-
-    const user = await this.repos.users.findById(row.userId);
-    if (!user || user.banned) return null;
-
-    const resolved = await this.repos.users.principal(user.id);
-    if (!resolved) return null;
-    const allowed = row.spaceIds?.length ? new Set(row.spaceIds) : null;
-    const spaces: Record<string, SpaceRole> = {};
-    const permissions: Record<string, string[]> = {};
-    for (const [spaceId, role] of Object.entries(resolved.spaces)) {
-      if (allowed && !allowed.has(spaceId)) continue;
-      spaces[spaceId] = role;
-      const grants = resolved.permissions[spaceId];
-      if (grants) permissions[spaceId] = grants;
-    }
-
-    return {
-      userId: user.id,
-      email: user.email,
-      role: user.role,
-      spaces,
-      permissions,
-      viaApiKey: true,
-      allowedSpaceIds: allowed ? [...allowed] : null,
-      allowedGrants: row.permissions,
-    };
-  }
-
-  /** Removes expired keys; scheduled by the jobs package. */
-  async pruneExpired(): Promise<number> {
-    const deleted = await this.db
-      .delete(schema.apikeys)
-      .where(sql`${schema.apikeys.expiresAt} is not null and ${schema.apikeys.expiresAt} < now()`)
-      .returning({ id: schema.apikeys.id });
-    return deleted.length;
-  }
-}
-
-const digest = (secret: string): string => createHash('sha256').update(secret).digest('hex');