@manablox/auth 0.2.0 → 0.4.0

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');

package/src/index.ts

@@ -1,164 +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 { APIError } from 'better-auth/api';
-import { bearer } from 'better-auth/plugins';
-import type { ApiKeyService } from './api-key.js';
-import { hashPassword, MIN_PASSWORD_LENGTH, verifyPassword } from './password.js';
-import type { Principal } from './rbac.js';
-
-export * from './api-key.js';
-export * from './password.js';
-export * from './rbac.js';
-export * from './user.service.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>;
-  /**
-   * 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 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: MIN_PASSWORD_LENGTH,
-      password: {
-        hash: hashPassword,
-        verify: ({ hash: stored, password }) => verifyPassword(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: {
-          // Sign-up is the only path that creates a user through better-auth; accounts
-          // an administrator creates are written by `UserService` and never pass here.
-          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.
- */
-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,
-    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.
- */
-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/password.ts

@@ -1,17 +0,0 @@
-/**
- * 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 async function hashPassword(password: string): Promise<string> {
-  const { hash } = await import('@node-rs/argon2');
-  return hash(password, { memoryCost: 19456, timeCost: 2, parallelism: 1 });
-}
-
-export async function verifyPassword(stored: string, password: string): Promise<boolean> {
-  const { verify } = await import('@node-rs/argon2');
-  return verify(stored, password);
-}
-
-/** Matches better-auth's `minPasswordLength`, so a password set here signs in there. */
-export const MIN_PASSWORD_LENGTH = 12;

package/src/rbac.ts

@@ -1,134 +0,0 @@
-import {
-  ALL_PERMISSIONS,
-  type ContentPermission,
-  grantsCover,
-  intersectGrants,
-  ManabloxError,
-  type Permission,
-  permissionsFor,
-  type SpaceRole,
-  typesCoveredBy,
-} from '@manablox/core';
-
-export {
-  ALL_PERMISSIONS,
-  BUILT_IN_ROLES,
-  type BuiltInRole,
-  CONTENT_ACTIONS,
-  type ContentAction,
-  type ContentPermission,
-  type Grant,
-  grantsCover,
-  intersectGrants,
-  isBuiltInRole,
-  normaliseGrants,
-  PERMISSION_GROUPS,
-  type Permission,
-  type PermissionGroup,
-  parseGrant,
-  permissionsFor,
-  type SpaceRole,
-  typesCoveredBy,
-} from '@manablox/core';
-
-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>;
-  /**
-   * 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 function grantsIn(principal: Principal, spaceId: string): readonly string[] {
-  const role = principal.spaces[spaceId];
-  if (!role) return [];
-  return principal.permissions?.[spaceId] ?? permissionsFor(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.
- */
-export function effectiveGrants(principal: Principal, spaceId: string): readonly string[] {
-  if (principal.allowedSpaceIds && !principal.allowedSpaceIds.includes(spaceId)) return [];
-  const held = principal.role === 'superadmin' ? ALL_PERMISSIONS : grantsIn(principal, spaceId);
-  return principal.allowedGrants ? intersectGrants(held, principal.allowedGrants) : held;
-}
-
-export function can(
-  principal: Principal | null,
-  spaceId: string | null,
-  permission: Permission,
-  typeId?: string | null,
-): 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.allowedGrants && !grantsCover(principal.allowedGrants, permission, typeId)) {
-    return false;
-  }
-  if (principal.role === 'superadmin') return true;
-  if (!spaceId) return false;
-  return grantsCover(grantsIn(principal, spaceId), permission, typeId);
-}
-
-export function assertCan(
-  principal: Principal | null,
-  spaceId: string | null,
-  permission: Permission,
-  typeId?: string | null,
-): void {
-  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.
- */
-export function allowedTypeIds(
-  principal: Principal | null,
-  spaceId: string,
-  permission: ContentPermission,
-): string[] | null {
-  if (!principal) return [];
-  if (principal.role === 'superadmin' && !principal.allowedGrants) return null;
-  return typesCoveredBy(effectiveGrants(principal, spaceId), permission);
-}
-
-/** 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/src/user.service.ts

@@ -1,192 +0,0 @@
-import { ManabloxError } from '@manablox/core';
-import {
-  type MembershipRow,
-  type Repositories,
-  rethrowUniqueViolation,
-  type SpaceRow,
-  type UserRow,
-  type UserUpdateData,
-} from '@manablox/db';
-import { hashPassword } from './password.js';
-
-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 }>;
-}
-
-/**
- * `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: string | undefined) => (error: unknown) =>
-  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.
- */
-export class UserService {
-  constructor(private readonly repos: Repositories) {}
-
-  async get(userId: string): Promise<UserDetail> {
-    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: { limit: number; offset: number }, search?: string) {
-    const page = await this.repos.users.list(pagination, search);
-    return { ...page, items: page.items.map(summary) };
-  }
-
-  async create(input: CreateUserInput): Promise<UserSummary> {
-    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));
-    return summary(user);
-  }
-
-  async update(userId: string, input: UpdateUserInput): Promise<UserSummary> {
-    const data: UserUpdateData = {};
-    if (input.name !== undefined) data.name = input.name.trim();
-    if (input.email !== undefined) data.email = normaliseEmail(input.email);
-    const user = await this.repos.users.update(userId, data).catch(emailConflict(data.email));
-    return summary(user);
-  }
-
-  /** Changing the instance role; the last superadmin cannot step down. */
-  async setRole(userId: string, role: InstanceRole): Promise<UserSummary> {
-    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: string, password: string): Promise<void> {
-    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: string, userId: string, reason: string | null): Promise<UserSummary> {
-    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: string): Promise<UserSummary> {
-    return summary(await this.repos.users.setBanned(userId, false, null));
-  }
-
-  async delete(actorId: string, userId: string): Promise<void> {
-    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: string): Promise<void> {
-    await this.require(userId);
-    await this.repos.users.revokeSessions(userId);
-  }
-
-  // -------------------------------------------------------------------------
-  // Internals
-  // -------------------------------------------------------------------------
-
-  private async require(userId: string): Promise<UserRow> {
-    const user = await this.repos.users.findById(userId);
-    if (!user) throw ManabloxError.notFound('user.notFound', { id: userId });
-    return user;
-  }
-
-  private assertNotSelf(actorId: string, userId: string): void {
-    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.
-   */
-  private async assertNotLastSuperadmin(userId: string): Promise<void> {
-    const user = await this.require(userId);
-    if (user.role !== 'superadmin') return;
-    const count = await this.repos.users.countByRole('superadmin');
-    if (count <= 1) throw ManabloxError.badRequest('user.lastSuperadmin', { id: userId });
-  }
-}
-
-function summary(user: UserRow): UserSummary {
-  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: string): string {
-  return email.trim().toLowerCase();
-}

package/test/api-key.test.ts

@@ -1,18 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { parseApiKey } from '../src/api-key.js';
-
-describe('parseApiKey', () => {
-  it('keeps a secret that itself contains the separator', () => {
-    expect(parseApiKey('mbx_0123456789ab_ab_cd-ef_gh')).toEqual({
-      prefix: '0123456789ab',
-      secret: 'ab_cd-ef_gh',
-    });
-  });
-
-  it('refuses another prefix, a malformed lookup part, or an empty secret', () => {
-    expect(parseApiKey('abc_0123456789ab_secret')).toBeNull();
-    expect(parseApiKey('mbx_0123_secret')).toBeNull();
-    expect(parseApiKey('mbx_0123456789ab_')).toBeNull();
-    expect(parseApiKey('not a key')).toBeNull();
-  });
-});