@manablox/auth 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
+import { ALL_PERMISSIONS, AuditActor, AuthConfig, BUILT_IN_ROLES, BuiltInRole, CONTENT_ACTIONS, ContentAction, ContentPermission, ContentPermission as ContentPermission$1, Grant, Manablox, PERMISSION_GROUPS, Permission, Permission as Permission$1, PermissionGroup, SpaceRole, SpaceRole as SpaceRole$1, grantsCover, intersectGrants, isBuiltInRole, normaliseGrants, parseGrant, permissionsFor, typesCoveredBy } from "@manablox/core";
 import { Database, MembershipRow, Repositories, SpaceRow } from "@manablox/db";
-import { ALL_PERMISSIONS, AuthConfig, BUILT_IN_ROLES, BuiltInRole, CONTENT_ACTIONS, ContentAction, ContentPermission, ContentPermission as ContentPermission$1, Grant, Manablox, PERMISSION_GROUPS, Permission, Permission as Permission$1, PermissionGroup, SpaceRole, SpaceRole as SpaceRole$1, grantsCover, intersectGrants, isBuiltInRole, normaliseGrants, parseGrant, permissionsFor, typesCoveredBy } from "@manablox/core";
 //#region src/rbac.d.ts
 export interface Principal {
   userId: string;
@@ -15,6 +15,9 @@ export interface Principal {
   permissions?: Record<string, readonly string[]>;
   /** True when the request authenticated with an API key rather than a session. */
   viaApiKey?: boolean;
+  /** The key that authenticated the request, for the audit log. */
+  apiKeyId?: string | null;
+  apiKeyName?: string | null;
   /**
    * Spaces this principal is confined to, or `null`/absent for no confinement. Set by an
    * API key that was issued with a space restriction: it narrows the key below its
@@ -28,6 +31,14 @@ export interface Principal {
    */
   allowedGrants?: readonly string[] | null;
 }
+/**
+ * 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.
+ */
+export declare function auditActorFor(principal: Principal | null, request?: {
+  headers: Headers;
+  requestId?: string | null | undefined;
+}): AuditActor;
 /** The grants a principal's role gives in a space, whatever kind of role it is. */
 export declare function grantsIn(principal: Principal, spaceId: string): readonly string[];
 /**
@@ -174,12 +185,20 @@ export declare class UserService {
    * before the reset does not keep it afterwards.
    */
   setPassword(userId: string, password: string): Promise<void>;
+  /**
+   * 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.
+   */
+  changePassword(userId: string, currentPassword: string, password: string): Promise<void>;
   /** A banned user is signed out everywhere and refused on the next request. */
   ban(actorId: string, userId: string, reason: string | null): Promise<UserSummary>;
   unban(userId: string): Promise<UserSummary>;
   delete(actorId: string, userId: string): Promise<void>;
   /** Signs the user out of every device without touching the account. */
   revokeSessions(userId: string): Promise<void>;
+  /** Accounts are instance-wide, so their entries carry no space. */
+  private audit;
   private require;
   private assertNotSelf;
   /**
@@ -202,6 +221,12 @@ export interface AuthCallbacks {
    * created by an administrator rather than by whoever finds the login page.
    */
   allowSignUp?: () => Promise<boolean>;
+  /** Runs after a session row is created: a sign-in. */
+  onSessionCreated?: (session: {
+    userId: string;
+    ipAddress?: string | null | undefined;
+    userAgent?: string | null | undefined;
+  }) => Promise<void>;
 }
 export declare function createAuth(config: AuthConfig, db: Database, callbacks?: AuthCallbacks): import("better-auth").Auth<{
   secret: string;
@@ -279,6 +304,20 @@ export declare function createAuth(config: AuthConfig, db: Database, callbacks?:
         } & Record<string, unknown>) => Promise<void>;
       };
     };
+    session: {
+      create: {
+        after: (session: {
+          id: string;
+          createdAt: Date;
+          updatedAt: Date;
+          userId: string;
+          expiresAt: Date;
+          token: string;
+          ipAddress?: string | null | undefined;
+          userAgent?: string | null | undefined;
+        } & Record<string, unknown>) => Promise<void>;
+      };
+    };
   };
   advanced: {
     database: {

package/dist/index.js

@@ -1,10 +1,10 @@
+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 { 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
 /**
@@ -71,6 +71,30 @@ var ApiKeyService = class {
 			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,
@@ -83,7 +107,19 @@ var ApiKeyService = class {
 	* 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));
+		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({
@@ -129,18 +165,68 @@ var ApiKeyService = class {
 			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() {
-		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 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];
@@ -237,32 +323,64 @@ var UserService = class {
 	}
 	async create(input) {
 		const email = normaliseEmail(input.email);
-		return summary(await this.repos.users.create({
+		const user = await this.repos.users.create({
 			name: input.name.trim(),
 			email,
 			role: input.role,
 			passwordHash: await hashPassword(input.password)
-		}).catch(emailConflict(email)));
+		}).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);
-		return summary(await this.repos.users.update(userId, data).catch(emailConflict(data.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);
-		return summary(await this.repos.users.setRole(userId, role));
+		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) {
-		await this.require(userId);
+		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) {
@@ -270,21 +388,53 @@ var UserService = class {
 		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) {
-		return summary(await this.repos.users.setBanned(userId, false, null));
+		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);
-		await this.require(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) {
-		await this.require(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);
@@ -354,15 +504,20 @@ function createAuth(config, db, callbacks = {}) {
 			}
 		},
 		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);
-			}
-		} } },
+		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() } }
 	});
 }
@@ -401,6 +556,18 @@ async function promoteFirstUser(manablox, repos, 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. */
@@ -415,4 +582,4 @@ function attachBootstrapOwner(manablox, repos) {
 	}, { 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 };
+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,6 +1,6 @@
 {
   "name": "@manablox/auth",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "exports": {
     ".": {
@@ -11,8 +11,8 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "dependencies": {
-    "@manablox/core": "0.3.0",
-    "@manablox/db": "0.3.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"