@manablox/auth 0.2.0 → 0.3.0

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();
-  });
-});

package/test/rbac.test.ts

@@ -1,128 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  actorRoles,
-  allowedTypeIds,
-  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);
-    }
-  });
-
-  describe('a custom role', () => {
-    const TYPE = 'type-1';
-    const blogger = principal({
-      spaces: { [SPACE]: 'blogger' },
-      permissions: { [SPACE]: ['space:read', 'content:read', `content:write:${TYPE}`] },
-    });
-
-    it('answers from its own grants rather than the built-in table', () => {
-      expect(can(blogger, SPACE, 'content:read')).toBe(true);
-      expect(can(blogger, SPACE, 'asset:read')).toBe(false);
-    });
-
-    it('holds a content action for every type, or for the types named', () => {
-      expect(can(blogger, SPACE, 'content:read', 'type-2')).toBe(true);
-      expect(can(blogger, SPACE, 'content:write', TYPE)).toBe(true);
-      expect(can(blogger, SPACE, 'content:write', 'type-2')).toBe(false);
-      // Asked without a type: does the role write anything at all?
-      expect(can(blogger, SPACE, 'content:write')).toBe(true);
-      expect(can(blogger, SPACE, 'content:publish')).toBe(false);
-    });
-
-    it('tells a listing which types to narrow to', () => {
-      expect(allowedTypeIds(blogger, SPACE, 'content:read')).toBeNull();
-      expect(allowedTypeIds(blogger, SPACE, 'content:write')).toEqual([TYPE]);
-      expect(allowedTypeIds(blogger, SPACE, 'content:publish')).toEqual([]);
-      expect(allowedTypeIds(principal({ role: 'superadmin' }), SPACE, 'content:write')).toBeNull();
-    });
-
-    it('is nothing in a space where the name is unknown and no grants came along', () => {
-      const ghost = principal({ spaces: { [SPACE]: 'ghost' } });
-      expect(can(ghost, SPACE, 'content:read')).toBe(false);
-    });
-  });
-
-  describe('an API key confined to grants', () => {
-    const TYPE = 'type-1';
-    const key = principal({
-      spaces: { [SPACE]: 'editor' },
-      viaApiKey: true,
-      allowedGrants: ['content:read', `content:write:${TYPE}`, 'space:delete'],
-    });
-
-    it('never widens the owner: a grant the role lacks stays refused', () => {
-      expect(can(key, SPACE, 'space:delete')).toBe(false);
-    });
-
-    it('narrows the owner to the grants named', () => {
-      expect(can(key, SPACE, 'content:read')).toBe(true);
-      expect(can(key, SPACE, 'content:write', TYPE)).toBe(true);
-      expect(can(key, SPACE, 'content:write', 'type-2')).toBe(false);
-      expect(can(key, SPACE, 'asset:read')).toBe(false);
-      expect(allowedTypeIds(key, SPACE, 'content:write')).toEqual([TYPE]);
-    });
-
-    it('binds a superadmin too', () => {
-      const root = principal({ role: 'superadmin', spaces: {}, allowedGrants: ['content:read'] });
-      expect(can(root, SPACE, 'content:read')).toBe(true);
-      expect(can(root, SPACE, 'space:delete')).toBe(false);
-      expect(allowedTypeIds(root, SPACE, 'content:read')).toBeNull();
-      expect(allowedTypeIds(root, SPACE, 'content:write')).toEqual([]);
-    });
-  });
-});

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