@manablox/auth 0.1.0

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@manablox/auth",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "@manablox/core": "0.1.0",
+    "@manablox/db": "0.1.0",
+    "better-auth": "^1.7.2",
+    "drizzle-orm": "^0.45.2",
+    "@node-rs/argon2": "^2.2.0"
+  },
+  "devDependencies": {
+    "@manablox/config-typescript": "0.0.0",
+    "@types/node": "^26.4.1",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/api-key.ts

@@ -0,0 +1,143 @@
+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

@@ -0,0 +1,155 @@
+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

@@ -0,0 +1,146 @@
+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

@@ -0,0 +1,58 @@
+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

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

package/vitest.config.ts

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