@manablox/auth 0.2.0 → 0.4.0

package/dist/index.js

@@ -0,0 +1,585 @@
+import { ALL_PERMISSIONS, ALL_PERMISSIONS as ALL_PERMISSIONS$1, BUILT_IN_ROLES, CONTENT_ACTIONS, ManabloxError, PERMISSION_GROUPS, diffRecords, grantsCover, grantsCover as grantsCover$1, intersectGrants, intersectGrants as intersectGrants$1, isBuiltInRole, normaliseGrants, parseGrant, permissionsFor, permissionsFor as permissionsFor$1, systemActor, typesCoveredBy, typesCoveredBy as typesCoveredBy$1 } from "@manablox/core";
+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 { 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");
+		await this.repos.audit.record({
+			action: "apiKey.issue",
+			targetKind: "apiKey",
+			targetId: row.id,
+			targetLabel: name,
+			changes: [
+				{
+					path: "expiresAt",
+					from: null,
+					to: row.expiresAt
+				},
+				{
+					path: "spaceIds",
+					from: null,
+					to: row.spaceIds
+				},
+				{
+					path: "permissions",
+					from: null,
+					to: row.permissions
+				}
+			],
+			meta: { userId }
+		});
+		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) {
+		const [row] = await this.db.delete(schema.apikeys).where(eq(schema.apikeys.id, id)).returning({
+			id: schema.apikeys.id,
+			name: schema.apikeys.name,
+			userId: schema.apikeys.userId
+		});
+		if (!row) return;
+		await this.repos.audit.record({
+			action: "apiKey.revoke",
+			targetKind: "apiKey",
+			targetId: row.id,
+			targetLabel: row.name,
+			meta: { userId: row.userId }
+		});
+	}
+	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,
+			apiKeyId: row.id,
+			apiKeyName: row.name,
+			allowedSpaceIds: allowed ? [...allowed] : null,
+			allowedGrants: row.permissions
+		};
+	}
+	/** Removes expired keys; scheduled by the jobs package. */
+	async pruneExpired() {
+		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,
+			name: schema.apikeys.name
+		});
+		if (deleted.length) await this.repos.audit.record({
+			action: "apiKey.prune",
+			targetKind: "apiKey",
+			meta: { removed: deleted.map((row) => ({
+				id: row.id,
+				name: row.name
+			})) }
+		});
+		return deleted.length;
+	}
+};
+const digest = (secret) => createHash("sha256").update(secret).digest("hex");
+//#endregion
+//#region src/rbac.ts
+/**
+* The principal as the audit log records it: a user, or a user through an API key, with
+* the request's client details beside it. Anonymous requests act as the system.
+*/
+function auditActorFor(principal, request) {
+	const detail = {};
+	if (request) {
+		const ip = request.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || request.headers.get("x-real-ip");
+		if (ip) detail.ip = ip;
+		const userAgent = request.headers.get("user-agent");
+		if (userAgent) detail.userAgent = userAgent.slice(0, 300);
+		if (request.requestId) detail.requestId = request.requestId;
+	}
+	if (!principal) return {
+		kind: "system",
+		id: null,
+		label: "anonymous",
+		detail
+	};
+	if (principal.viaApiKey) {
+		detail.apiKeyId = principal.apiKeyId ?? null;
+		detail.apiKeyName = principal.apiKeyName ?? null;
+		return {
+			kind: "apikey",
+			id: principal.userId,
+			label: principal.email,
+			detail
+		};
+	}
+	return {
+		kind: "user",
+		id: principal.userId,
+		label: principal.email,
+		detail
+	};
+}
+/** 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);
+		const user = await this.repos.users.create({
+			name: input.name.trim(),
+			email,
+			role: input.role,
+			passwordHash: await hashPassword(input.password)
+		}).catch(emailConflict(email));
+		await this.audit("user.create", user, diffRecords(null, summary(user)));
+		return summary(user);
+	}
+	async update(userId, input) {
+		const before = await this.require(userId);
+		const data = {};
+		if (input.name !== void 0) data.name = input.name.trim();
+		if (input.email !== void 0) data.email = normaliseEmail(input.email);
+		const user = await this.repos.users.update(userId, data).catch(emailConflict(data.email));
+		await this.audit("user.update", user, diffRecords(summary(before), summary(user)));
+		return summary(user);
+	}
+	/** Changing the instance role; the last superadmin cannot step down. */
+	async setRole(userId, role) {
+		const before = await this.require(userId);
+		if (role !== "superadmin") await this.assertNotLastSuperadmin(userId);
+		const user = await this.repos.users.setRole(userId, role);
+		await this.audit("user.setRole", user, [{
+			path: "role",
+			from: before.role,
+			to: user.role
+		}]);
+		return summary(user);
+	}
+	/**
+	* 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) {
+		const user = await this.require(userId);
+		await this.repos.users.setPasswordHash(userId, await hashPassword(password));
+		await this.repos.users.revokeSessions(userId);
+		await this.audit("user.setPassword", user, []);
+	}
+	/**
+	* The account holder changing their own password: the current one must be right, and
+	* unlike an administrator's reset the other sessions stay signed in, since the person
+	* holding the account is the one making the change.
+	*/
+	async changePassword(userId, currentPassword, password) {
+		const user = await this.require(userId);
+		const stored = await this.repos.users.passwordHash(userId);
+		if (!stored || !await verifyPassword(stored, currentPassword)) throw ManabloxError.validation([{
+			key: "user.password.incorrect",
+			path: ["currentPassword"]
+		}], "user.validation.failed");
+		if (currentPassword === password) throw ManabloxError.validation([{
+			key: "user.password.sameAsCurrent",
+			path: ["password"]
+		}], "user.validation.failed");
+		await this.repos.users.setPasswordHash(userId, await hashPassword(password));
+		await this.audit("user.changePassword", user, []);
+	}
+	/** 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);
+		await this.audit("user.ban", user, [{
+			path: "banned",
+			from: false,
+			to: true
+		}, {
+			path: "banReason",
+			from: null,
+			to: reason
+		}]);
+		return summary(user);
+	}
+	async unban(userId) {
+		const before = await this.require(userId);
+		const user = await this.repos.users.setBanned(userId, false, null);
+		await this.audit("user.unban", user, [{
+			path: "banned",
+			from: before.banned,
+			to: false
+		}, {
+			path: "banReason",
+			from: before.banReason,
+			to: null
+		}]);
+		return summary(user);
+	}
+	async delete(actorId, userId) {
+		this.assertNotSelf(actorId, userId);
+		const user = await this.require(userId);
+		await this.assertNotLastSuperadmin(userId);
+		await this.repos.users.delete(userId);
+		await this.audit("user.delete", user, diffRecords(summary(user), null));
+	}
+	/** Signs the user out of every device without touching the account. */
+	async revokeSessions(userId) {
+		const user = await this.require(userId);
+		await this.repos.users.revokeSessions(userId);
+		await this.audit("user.revokeSessions", user, []);
+	}
+	/** Accounts are instance-wide, so their entries carry no space. */
+	audit(action, user, changes) {
+		return this.repos.audit.record({
+			action,
+			targetKind: "user",
+			targetId: user.id,
+			targetLabel: user.email,
+			changes
+		});
+	}
+	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);
+				}
+			} },
+			session: { create: { after: async (session) => {
+				await callbacks.onSessionCreated?.(session);
+			} } }
+		},
+		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");
+	await repos.audit.record({
+		actor: systemActor("first account"),
+		action: "user.promote",
+		targetKind: "user",
+		targetId: user.id,
+		targetLabel: user.email,
+		changes: [{
+			path: "role",
+			from: user.role,
+			to: "superadmin"
+		}]
+	});
+	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, auditActorFor, 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.4.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.4.0",
+    "@manablox/db": "0.4.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"
   }