@manablox/auth 0.1.0 → 0.3.0

package/README.md

@@ -0,0 +1,20 @@
+# `@manablox/auth`
+
+Sessions, API keys and permissions. better-auth owns sign-in and sessions; this package wraps it, resolves a `Principal` from a request, checks a permission against the role table, and issues and verifies API keys, including ones restricted to a set of spaces.
+
+## Exports
+
+- `createAuth`, `resolvePrincipal`
+- `can`, `assertCan`, `actorRoles`, `Permission`, `Principal`
+- `ApiKeyService`
+- `promoteFirstUser`, `attachBootstrapOwner` — the first account is the superadmin
+
+## Depends on
+
+@manablox/db, better-auth
+
+## Test
+
+```sh
+pnpm --filter @manablox/auth test
+```

package/dist/index.d.ts

@@ -0,0 +1,305 @@
+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;
+  email: string;
+  /** Instance-wide role; `superadmin` short-circuits every space check. */
+  role: string;
+  /** Space id → the name of the role held there. */
+  spaces: Record<string, SpaceRole$1>;
+  /**
+   * Space id → the grants that role carries, resolved when the principal is. Absent for
+   * a space whose role is built in: those are answered from the table above.
+   */
+  permissions?: Record<string, readonly string[]>;
+  /** True when the request authenticated with an API key rather than a session. */
+  viaApiKey?: boolean;
+  /**
+   * 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
+   * owner's own access and, unlike a role, it also binds a superadmin.
+   */
+  allowedSpaceIds?: string[] | null;
+  /**
+   * Grants this principal is confined to, or `null`/absent for no confinement. Set by an
+   * API key issued with a permission restriction: like `allowedSpaceIds` it only ever
+   * narrows the owner's own access, and it binds a superadmin too.
+   */
+  allowedGrants?: readonly string[] | null;
+}
+/** 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[];
+/**
+ * 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.
+ */
+export declare function effectiveGrants(principal: Principal, spaceId: string): readonly string[];
+export declare function can(principal: Principal | null, spaceId: string | null, permission: Permission$1, typeId?: string | null): boolean;
+export declare function assertCan(principal: Principal | null, spaceId: string | null, permission: Permission$1, typeId?: string | null): void;
+/**
+ * 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.
+ */
+export declare function allowedTypeIds(principal: Principal | null, spaceId: string, permission: ContentPermission$1): string[] | null;
+/** Roles used by field-level `readRoles`/`writeRoles` checks. */
+export declare function actorRoles(principal: Principal | null, spaceId: string | null): string[];
+//#endregion
+//#region src/api-key.d.ts
+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;
+}
+/**
+ * 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 declare function parseApiKey(presented: string): {
+  prefix: string;
+  secret: string;
+} | null;
+/**
+ * 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 declare class ApiKeyService {
+  private readonly db;
+  private readonly repos;
+  constructor(db: Database, repos: Repositories);
+  issue(userId: string, name: string, options?: IssueApiKeyOptions): Promise<IssuedApiKey>;
+  /**
+   * 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.
+   */
+  revoke(id: string): Promise<void>;
+  list(userId: string): Promise<{
+    id: string;
+    name: string | null;
+    start: string | null;
+    enabled: boolean;
+    expiresAt: Date | null;
+    lastRequest: Date | null;
+    spaceIds: string[] | null;
+    permissions: string[] | null;
+    createdAt: Date;
+  }[]>;
+  resolve(presented: string): Promise<Principal | null>;
+  /** Removes expired keys; scheduled by the jobs package. */
+  pruneExpired(): Promise<number>;
+}
+//#endregion
+//#region src/password.d.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.
+ */
+export declare function hashPassword(password: string): Promise<string>;
+export declare function verifyPassword(stored: string, password: string): Promise<boolean>;
+/** Matches better-auth's `minPasswordLength`, so a password set here signs in there. */
+export declare const MIN_PASSWORD_LENGTH = 12;
+//#endregion
+//#region src/user.service.d.ts
+export type InstanceRole = 'superadmin' | 'editor';
+export interface CreateUserInput {
+  name: string;
+  email: string;
+  password: string;
+  role: InstanceRole;
+}
+export interface UpdateUserInput {
+  name?: string | undefined;
+  email?: string | undefined;
+}
+/** A user row without anything a directory listing should not carry. */
+export interface UserSummary {
+  id: string;
+  name: string;
+  email: string;
+  image: string | null;
+  role: string;
+  banned: boolean;
+  banReason: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+export interface UserDetail extends UserSummary {
+  memberships: Array<{
+    spaceId: string;
+    role: MembershipRow['role'];
+    space: SpaceRow;
+  }>;
+}
+/**
+ * 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.
+ */
+export declare class UserService {
+  private readonly repos;
+  constructor(repos: Repositories);
+  get(userId: string): Promise<UserDetail>;
+  list(pagination: {
+    limit: number;
+    offset: number;
+  }, search?: string): Promise<{
+    total: number;
+    limit: number;
+    offset: number;
+    items: UserSummary[];
+  }>;
+  create(input: CreateUserInput): Promise<UserSummary>;
+  update(userId: string, input: UpdateUserInput): Promise<UserSummary>;
+  /** Changing the instance role; the last superadmin cannot step down. */
+  setRole(userId: string, role: InstanceRole): Promise<UserSummary>;
+  /**
+   * A new password, and every session gone with the old one: whoever held the account
+   * before the reset does not keep it afterwards.
+   */
+  setPassword(userId: 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>;
+  private require;
+  private assertNotSelf;
+  /**
+   * 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.
+   */
+  private assertNotLastSuperadmin;
+}
+//#endregion
+//#region src/index.d.ts
+export type ManabloxAuth = ReturnType<typeof createAuth>;
+/** better-auth, wired to the Drizzle schema. Sessions are rows, so concurrent devices
+ * each hold their own. */
+export interface AuthCallbacks {
+  /** Runs after a user row is created, inside better-auth's own transaction path. */
+  onUserCreated?: (userId: string) => Promise<void>;
+  /**
+   * Whether the public sign-up endpoint may create an account right now. Absent means
+   * always. The host closes it once the first account exists, so every later account is
+   * created by an administrator rather than by whoever finds the login page.
+   */
+  allowSignUp?: () => Promise<boolean>;
+}
+export declare function createAuth(config: AuthConfig, db: Database, callbacks?: AuthCallbacks): import("better-auth").Auth<{
+  secret: string;
+  baseURL?: string;
+  trustedOrigins: string[];
+  database: (options: import("better-auth").BetterAuthOptions) => import("better-auth").DBAdapter<import("better-auth").BetterAuthOptions>;
+  emailAndPassword: {
+    enabled: boolean;
+    minPasswordLength: number;
+    password: {
+      hash: typeof hashPassword;
+      verify: ({ hash: stored, password }: {
+        hash: string;
+        password: string;
+      }) => Promise<boolean>;
+    };
+  };
+  session: {
+    expiresIn: number;
+    updateAge: number;
+    cookieCache: {
+      enabled: true;
+      maxAge: number;
+    };
+  };
+  plugins: [{
+    id: "bearer";
+    version: string;
+    hooks: {
+      before: {
+        matcher(context: import("better-auth").HookEndpointContext): boolean;
+        handler: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<{
+          context: {
+            headers: Headers;
+          };
+        } | undefined>>;
+      }[];
+      after: {
+        matcher(context: import("better-auth").HookEndpointContext): true;
+        handler: import("better-auth").Middleware<import("better-auth").MiddlewareOptions, (inputContext: import("better-auth").MiddlewareInputContext<import("better-auth").MiddlewareOptions>) => Promise<void>>;
+      }[];
+    };
+    options: import("better-auth/plugins").BearerOptions | undefined;
+  }];
+  databaseHooks: {
+    user: {
+      create: {
+        before: (user: {
+          id: string;
+          createdAt: Date;
+          updatedAt: Date;
+          email: string;
+          emailVerified: boolean;
+          name: string;
+          image?: string | null | undefined;
+        } & Record<string, unknown>) => Promise<{
+          data: {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            email: string;
+            emailVerified: boolean;
+            name: string;
+            image?: string | null | undefined;
+          } & Record<string, unknown>;
+        }>;
+        after: (user: {
+          id: string;
+          createdAt: Date;
+          updatedAt: Date;
+          email: string;
+          emailVerified: boolean;
+          name: string;
+          image?: string | null | undefined;
+        } & Record<string, unknown>) => Promise<void>;
+      };
+    };
+  };
+  advanced: {
+    database: {
+      generateId: () => `${string}-${string}-${string}-${string}-${string}`;
+    };
+  };
+}>;
+/**
+ * Resolves a request's session into a `Principal`, including its space memberships.
+ * Returns `null` for anonymous requests rather than throwing — route guards decide.
+ */
+export declare function resolvePrincipal(auth: ManabloxAuth, repos: Repositories, headers: Headers, apiKeys?: ApiKeyService): Promise<Principal | null>;
+/**
+ * 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.
+ */
+export declare function promoteFirstUser(manablox: Manablox, repos: Repositories, userId: string): Promise<void>;
+/** Covers an instance whose first account predates this behaviour. */
+export declare function attachBootstrapOwner(manablox: Manablox, repos: Repositories): void;
+//#endregion
+export { ALL_PERMISSIONS, BUILT_IN_ROLES, type BuiltInRole, CONTENT_ACTIONS, type ContentAction, type ContentPermission, type Grant, PERMISSION_GROUPS, type Permission, type PermissionGroup, type SpaceRole, grantsCover, intersectGrants, isBuiltInRole, normaliseGrants, parseGrant, permissionsFor, typesCoveredBy };

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.1.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.1.0",
-    "@manablox/db": "0.1.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,143 +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;
-}
-
-const PREFIX = 'mbx';
-
-/**
- * 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,
-      })
-      .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,
-        createdAt: schema.apikeys.createdAt,
-      })
-      .from(schema.apikeys)
-      .where(eq(schema.apikeys.userId, userId));
-  }
-
-  async resolve(presented: string): Promise<Principal | null> {
-    const parts = presented.split('_');
-    if (parts.length !== 3 || parts[0] !== PREFIX) return null;
-    const [, prefix, secret] = parts as [string, string, string];
-
-    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 memberships = await this.repos.users.memberships(user.id);
-    const allowed = row.spaceIds?.length ? new Set(row.spaceIds) : null;
-    const spaces: Record<string, SpaceRole> = {};
-    for (const membership of memberships) {
-      if (allowed && !allowed.has(membership.spaceId)) continue;
-      spaces[membership.spaceId] = membership.role;
-    }
-
-    return {
-      userId: user.id,
-      email: user.email,
-      role: user.role,
-      spaces,
-      viaApiKey: true,
-      allowedSpaceIds: allowed ? [...allowed] : null,
-    };
-  }
-
-  /** 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');

package/src/index.ts

@@ -1,155 +0,0 @@
-import type { AuthConfig, Manablox } from '@manablox/core';
-import type { Database, Repositories } from '@manablox/db';
-import { schema } from '@manablox/db';
-import { betterAuth } from 'better-auth';
-import { drizzleAdapter } from 'better-auth/adapters/drizzle';
-import { bearer } from 'better-auth/plugins';
-import type { ApiKeyService } from './api-key.js';
-import type { Principal } from './rbac.js';
-
-export * from './api-key.js';
-export * from './rbac.js';
-
-export type ManabloxAuth = ReturnType<typeof createAuth>;
-
-/** better-auth, wired to the Drizzle schema. Sessions are rows, so concurrent devices
- * each hold their own. */
-export interface AuthCallbacks {
-  /** Runs after a user row is created, inside better-auth's own transaction path. */
-  onUserCreated?: (userId: string) => Promise<void>;
-}
-
-export function createAuth(config: AuthConfig, db: Database, callbacks: AuthCallbacks = {}) {
-  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,
-      // Argon2id: memory-hard, and the current OWASP recommendation over bcrypt, which
-      // also silently truncates passwords at 72 bytes.
-      password: {
-        hash: async (password) => {
-          const { hash } = await import('@node-rs/argon2');
-          return hash(password, { memoryCost: 19456, timeCost: 2, parallelism: 1 });
-        },
-        verify: async ({ hash: stored, password }) => {
-          const { verify } = await import('@node-rs/argon2');
-          return verify(stored, password);
-        },
-      },
-    },
-
-    session: {
-      expiresIn: config.sessionMaxAge ?? 60 * 60 * 24 * 7,
-      updateAge: 60 * 60 * 24,
-      cookieCache: { enabled: true, maxAge: 60 * 5 },
-    },
-
-    // `bearer` lets a non-browser client present the session token as an Authorization
-    // header instead of a cookie. Long-lived machine credentials are handled separately
-    // by `ApiKeyService` below — better-auth 1.7 ships no api-key plugin.
-    plugins: [bearer()],
-
-    databaseHooks: {
-      user: {
-        create: {
-          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.
- */
-export async function resolvePrincipal(
-  auth: ManabloxAuth,
-  repos: Repositories,
-  headers: Headers,
-  apiKeys?: ApiKeyService,
-): Promise<Principal | null> {
-  // An `x-api-key` header takes precedence: it identifies a machine consumer and never
-  // carries a browser session's ambient authority.
-  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;
-
-  // Role and memberships come from the database, not from the session payload, so a
-  // permission change takes effect on the next request rather than when better-auth's
-  // session cache happens to expire.
-  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,
-  };
-}
-
-/**
- * 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.
- */
-export async function promoteFirstUser(
-  manablox: Manablox,
-  repos: Repositories,
-  userId: string,
-): Promise<void> {
-  const count = await repos.users.count();
-  if (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. */
-export function attachBootstrapOwner(manablox: Manablox, repos: Repositories): void {
-  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' },
-  );
-}

package/src/rbac.ts

@@ -1,146 +0,0 @@
-import { ManabloxError } from '@manablox/core';
-
-export type SpaceRole = 'owner' | 'admin' | 'editor' | 'author' | 'viewer';
-
-export type Permission =
-  | 'space:read'
-  | 'space:write'
-  | 'space:delete'
-  | 'contentType:read'
-  | 'contentType:write'
-  | 'contentType:delete'
-  | 'content:read'
-  | 'content:write'
-  | 'content:delete'
-  | 'content:publish'
-  | 'asset:read'
-  | 'asset:write'
-  | 'asset:delete'
-  | 'user:read'
-  | 'user:write'
-  | 'webhook:read'
-  | 'webhook:write';
-
-/** Role → permission mapping. */
-const ROLE_PERMISSIONS: Record<SpaceRole, Permission[]> = {
-  owner: [
-    'space:read',
-    'space:write',
-    'space:delete',
-    'contentType:read',
-    'contentType:write',
-    'contentType:delete',
-    'content:read',
-    'content:write',
-    'content:delete',
-    'content:publish',
-    'asset:read',
-    'asset:write',
-    'asset:delete',
-    'user:read',
-    'user:write',
-    'webhook:read',
-    'webhook:write',
-  ],
-  admin: [
-    'space:read',
-    'space:write',
-    'contentType:read',
-    'contentType:write',
-    'contentType:delete',
-    'content:read',
-    'content:write',
-    'content:delete',
-    'content:publish',
-    'asset:read',
-    'asset:write',
-    'asset:delete',
-    'user:read',
-    'user:write',
-    'webhook:read',
-    'webhook:write',
-  ],
-  editor: [
-    'space:read',
-    'contentType:read',
-    'content:read',
-    'content:write',
-    'content:delete',
-    'content:publish',
-    'asset:read',
-    'asset:write',
-    'asset:delete',
-    'user:read',
-    'webhook:read',
-  ],
-  // An author may write and delete, but never publish — the reason the role exists.
-  author: [
-    'space:read',
-    'contentType:read',
-    'content:read',
-    'content:write',
-    'content:delete',
-    'asset:read',
-    'asset:write',
-    'user:read',
-  ],
-  viewer: ['space:read', 'contentType:read', 'content:read', 'asset:read', 'user:read'],
-};
-
-export interface Principal {
-  userId: string;
-  email: string;
-  /** Instance-wide role; `superadmin` short-circuits every space check. */
-  role: string;
-  /** Space id → role in that space. */
-  spaces: Record<string, SpaceRole>;
-  /** True when the request authenticated with an API key rather than a session. */
-  viaApiKey?: boolean;
-  /**
-   * 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
-   * owner's own access and, unlike a role, it also binds a superadmin.
-   */
-  allowedSpaceIds?: string[] | null;
-}
-
-export function permissionsFor(role: SpaceRole): readonly Permission[] {
-  return ROLE_PERMISSIONS[role] ?? [];
-}
-
-export function can(
-  principal: Principal | null,
-  spaceId: string | null,
-  permission: Permission,
-): boolean {
-  if (!principal) return false;
-  // Checked ahead of the superadmin short-circuit: a restricted key must not reach
-  // outside its spaces, and an instance-wide operation has no space to be inside.
-  if (principal.allowedSpaceIds && (!spaceId || !principal.allowedSpaceIds.includes(spaceId))) {
-    return false;
-  }
-  if (principal.role === 'superadmin') return true;
-  if (!spaceId) return false;
-
-  const role = principal.spaces[spaceId];
-  if (!role) return false;
-  return ROLE_PERMISSIONS[role].includes(permission);
-}
-
-export function assertCan(
-  principal: Principal | null,
-  spaceId: string | null,
-  permission: Permission,
-): void {
-  if (can(principal, spaceId, permission)) return;
-  if (!principal) throw ManabloxError.unauthorized();
-  throw ManabloxError.forbidden('auth.forbidden', { permission, spaceId });
-}
-
-/** Roles used by field-level `readRoles`/`writeRoles` checks. */
-export function actorRoles(principal: Principal | null, spaceId: string | null): string[] {
-  if (!principal) return [];
-  const roles = [principal.role];
-  if (spaceId && principal.spaces[spaceId]) roles.push(principal.spaces[spaceId]);
-  return roles;
-}

package/test/rbac.test.ts

@@ -1,58 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { actorRoles, assertCan, can, type Principal, permissionsFor } from '../src/rbac.js';
-
-const SPACE = 'space-1';
-
-const principal = (over: Partial<Principal> = {}): Principal => ({
-  userId: 'u1',
-  email: 'u@example.com',
-  role: 'editor',
-  spaces: { [SPACE]: 'editor' },
-  ...over,
-});
-
-describe('rbac', () => {
-  it('denies everything to an anonymous caller', () => {
-    expect(can(null, SPACE, 'content:read')).toBe(false);
-    expect(() => assertCan(null, SPACE, 'content:read')).toThrow(/unauthorized/);
-  });
-
-  it('lets an author write but not publish — the reason the role exists', () => {
-    const author = principal({ spaces: { [SPACE]: 'author' } });
-    expect(can(author, SPACE, 'content:write')).toBe(true);
-    expect(can(author, SPACE, 'content:publish')).toBe(false);
-    expect(() => assertCan(author, SPACE, 'content:publish')).toThrow(/forbidden/);
-  });
-
-  it('confines a viewer to reads', () => {
-    const viewer = principal({ spaces: { [SPACE]: 'viewer' } });
-    expect(can(viewer, SPACE, 'content:read')).toBe(true);
-    expect(can(viewer, SPACE, 'content:write')).toBe(false);
-    expect(can(viewer, SPACE, 'asset:write')).toBe(false);
-  });
-
-  it('grants nothing in a space the user is not a member of', () => {
-    expect(can(principal(), 'other-space', 'content:read')).toBe(false);
-  });
-
-  it('short-circuits every check for a superadmin', () => {
-    const root = principal({ role: 'superadmin', spaces: {} });
-    expect(can(root, 'any-space', 'space:delete')).toBe(true);
-  });
-
-  it('reserves space deletion for the owner', () => {
-    expect(can(principal({ spaces: { [SPACE]: 'admin' } }), SPACE, 'space:delete')).toBe(false);
-    expect(can(principal({ spaces: { [SPACE]: 'owner' } }), SPACE, 'space:delete')).toBe(true);
-  });
-
-  it('exposes the roles a field-level permission check needs', () => {
-    expect(actorRoles(principal({ role: 'editor' }), SPACE)).toEqual(['editor', 'editor']);
-    expect(actorRoles(null, SPACE)).toEqual([]);
-  });
-
-  it('never grants a write permission through a read-only role', () => {
-    for (const permission of permissionsFor('viewer')) {
-      expect(permission.endsWith(':read')).toBe(true);
-    }
-  });
-});

package/tsconfig.json

@@ -1 +0,0 @@
-{ "extends": "@manablox/config-typescript/library.json", "include": ["src", "test"] }

package/vitest.config.ts

@@ -1,2 +0,0 @@
-import { defineConfig } from 'vitest/config';
-export default defineConfig({ test: { environment: 'node', include: ['test/**/*.test.ts'] } });