@rangka/core 0.0.1

package/src/auth/scopes.ts

@@ -0,0 +1,146 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type { ResolvedModel } from '../schema/types.js';
+import type { DatabaseClient } from '../db/client.js';
+import type { ScopeFilter, RequestContext } from './types.js';
+import type { ScopeRegistry } from './scope-registry.js';
+import { getAuthContext } from './session.js';
+import { BadRequestError, ForbiddenError } from '../errors.js';
+import { isNil } from '../helpers/coerce.js';
+
+export { applyScopeFiltersToQuery } from './scope-filters.js';
+
+export interface ScopeHookContext {
+  model: ResolvedModel;
+  scopeRegistry: ScopeRegistry;
+  db: DatabaseClient;
+  filterProviders?: FilterProvider[];
+}
+
+export type FilterProvider = (
+  model: ResolvedModel,
+  authCtx: RequestContext,
+  request: FastifyRequest,
+) => ScopeFilter[] | Promise<ScopeFilter[]>;
+
+export function createScopeHook(ctx: ScopeHookContext) {
+  const { model, scopeRegistry, db, filterProviders } = ctx;
+  const binding = scopeRegistry.getModelBinding(model.qualifiedName);
+
+  return async function scopeHook(request: FastifyRequest, _reply: FastifyReply): Promise<void> {
+    const authCtx = getAuthContext(request);
+    if (!authCtx.permissions || !authCtx.user) return;
+
+    const filters: ScopeFilter[] = [];
+
+    if (binding) {
+      const activeValue = resolveActiveScopeValue(request, binding.scopeName, authCtx.user);
+      if (!activeValue) {
+        throw new BadRequestError(
+          'MISSING_SCOPE',
+          `Active scope value for "${binding.scopeName}" is required. Set it via X-Active-Scope header or user default.`,
+        );
+      }
+
+      const exists = await validateScopeValueExists(db, binding.scopeModel, activeValue);
+      if (!exists) {
+        throw new BadRequestError(
+          'INVALID_SCOPE',
+          `Scope value "${activeValue}" does not exist in "${binding.scopeModel}".`,
+        );
+      }
+
+      filters.push({ field: binding.column, operator: 'eq', value: activeValue });
+    }
+
+    if (filterProviders) {
+      for (const provider of filterProviders) {
+        const extra = await provider(model, authCtx, request);
+        filters.push(...extra);
+      }
+    }
+
+    authCtx.scopeFilters = filters;
+    (request as any).authContext = authCtx;
+  };
+}
+
+export function createScopeWriteGuard(ctx: ScopeHookContext) {
+  const { model, scopeRegistry } = ctx;
+  const binding = scopeRegistry.getModelBinding(model.qualifiedName);
+
+  return async function scopeWriteGuard(
+    request: FastifyRequest,
+    _reply: FastifyReply,
+  ): Promise<void> {
+    if (request.method === 'GET') return;
+    if (!binding) return;
+
+    const authCtx = getAuthContext(request);
+    if (!authCtx.scopeFilters?.length) return;
+
+    const body = request.body as Record<string, unknown> | undefined;
+    if (!body) return;
+
+    const scopeFilter = authCtx.scopeFilters.find((f) => f.field === binding.column);
+    if (!scopeFilter) return;
+
+    const fieldValue = body[binding.column];
+
+    if (request.method === 'POST') {
+      if (isNil(fieldValue)) {
+        body[binding.column] = scopeFilter.value;
+        return;
+      }
+    }
+
+    if (fieldValue !== undefined && fieldValue !== scopeFilter.value) {
+      throw new ForbiddenError(
+        'SCOPE_VIOLATION',
+        `Cannot write to scope "${binding.scopeName}": ${binding.column} must be "${scopeFilter.value}".`,
+      );
+    }
+  };
+}
+
+function resolveActiveScopeValue(
+  request: FastifyRequest,
+  scopeName: string,
+  user: Record<string, unknown>,
+): string | undefined {
+  const headerValue = parseScopeHeader(request);
+  if (headerValue?.[scopeName]) {
+    return String(headerValue[scopeName]);
+  }
+
+  const defaultField = `default_${scopeName}`;
+  if (user[defaultField]) {
+    return String(user[defaultField]);
+  }
+
+  return undefined;
+}
+
+function parseScopeHeader(request: FastifyRequest): Record<string, string> | undefined {
+  const header = request.headers['x-active-scope'];
+  if (!header || typeof header !== 'string') return undefined;
+
+  try {
+    return JSON.parse(header);
+  } catch {
+    return undefined;
+  }
+}
+
+async function validateScopeValueExists(
+  db: DatabaseClient,
+  scopeModel: string,
+  value: string,
+): Promise<boolean> {
+  const result = await db
+    .selectFrom(scopeModel)
+    .where('id', '=', value)
+    .selectAll()
+    .executeTakeFirst();
+  return result !== undefined;
+}

package/src/auth/seed.ts

@@ -0,0 +1,44 @@
+import type { DatabaseClient } from '../db/client.js';
+import { hashPassword } from './password.js';
+
+export async function seedCoreData(db: DatabaseClient): Promise<void> {
+  const existing = await db
+    .selectFrom('core.user')
+    .select('id')
+    .where('email', '=', 'system@rangka.local')
+    .executeTakeFirst();
+
+  if (existing) return;
+
+  const adminRole = await db
+    .insertInto('core.role')
+    .values({
+      id: crypto.randomUUID(),
+      name: 'Administrator',
+      inherits: JSON.stringify([]),
+      permissions: JSON.stringify({}),
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  const systemUser = await db
+    .insertInto('core.user')
+    .values({
+      id: crypto.randomUUID(),
+      email: 'system@rangka.local',
+      password_hash: hashPassword('admin'),
+      full_name: 'System Administrator',
+      enabled: true,
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+
+  await db
+    .insertInto('core.user_role')
+    .values({
+      id: crypto.randomUUID(),
+      user_id: systemUser.id,
+      role_id: adminRole.id,
+    })
+    .execute();
+}

package/src/auth/session.ts

@@ -0,0 +1,178 @@
+import { randomBytes } from 'node:crypto';
+import type { FastifyRequest, FastifyReply } from 'fastify';
+import type { DatabaseClient } from '../db/client.js';
+import { BadRequestError, UnauthorizedError } from '../errors.js';
+import type { PermissionRegistry } from './permission-registry.js';
+import type { AuthUser, AuthSession, RequestContext } from './types.js';
+
+const TOKEN_BYTES = 32;
+const SESSION_DURATION_MS = 24 * 60 * 60 * 1000;
+
+export function generateToken(): string {
+  return randomBytes(TOKEN_BYTES).toString('hex');
+}
+
+// Extracts Bearer token, validates the session, loads the user and their permissions,
+// then attaches everything to request.authContext for downstream guards.
+export function createAuthHook(db: DatabaseClient, permissionRegistry: PermissionRegistry) {
+  return async function authHook(request: FastifyRequest, _reply: FastifyReply): Promise<void> {
+    const ctx: RequestContext = {};
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (request as any).authContext = ctx;
+
+    const token = extractBearerToken(request);
+    if (!token) {
+      throw new UnauthorizedError('Missing or invalid Authorization header');
+    }
+
+    const session = await findActiveSession(db, token);
+    if (!session) {
+      throw new UnauthorizedError('Invalid or expired session token');
+    }
+
+    const user = await findEnabledUser(db, session.user_id);
+    if (!user) {
+      throw new UnauthorizedError('User not found or disabled');
+    }
+
+    const roleNames = await getUserRoleNames(db, user.id);
+    const permissions = permissionRegistry.resolvePermissionsForRoles(roleNames);
+
+    ctx.user = user;
+    ctx.session = session;
+    ctx.permissions = permissions;
+    ctx.roles = roleNames;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    (request as any).authContext = ctx;
+  };
+}
+
+export function getAuthContext(request: FastifyRequest): RequestContext {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (request as any).authContext ?? {};
+}
+
+// --- Session CRUD handlers ---
+
+export interface SessionCreateBody {
+  email: string;
+  password: string;
+}
+
+// POST /session — authenticates with email/password, returns a session token.
+export function createSessionHandler(db: DatabaseClient) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const { verifyPassword } = await import('./password.js');
+    const body = request.body as SessionCreateBody | undefined;
+
+    if (!body?.email || !body?.password) {
+      throw new BadRequestError('VALIDATION_ERROR', 'Email and password are required');
+    }
+
+    const user = await findEnabledUser(db, body.email, 'email');
+    if (!user) {
+      throw new UnauthorizedError('Invalid credentials');
+    }
+
+    if (!verifyPassword(body.password, user.password_hash)) {
+      throw new UnauthorizedError('Invalid credentials');
+    }
+
+    const session = await insertSession(db, user.id);
+
+    return reply.status(201).send({
+      data: { token: session.token, expires_at: session.expires_at },
+    });
+  };
+}
+
+// DELETE /session — destroys the current session.
+export function deleteSessionHandler(db: DatabaseClient) {
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const ctx = getAuthContext(request);
+    if (!ctx.session) {
+      throw new UnauthorizedError('Not authenticated');
+    }
+
+    await db.deleteFrom('core.session').where('id', '=', ctx.session.id).execute();
+    return reply.status(204).send();
+  };
+}
+
+// Invalidates all existing sessions for a user and creates a fresh one.
+export async function regenerateSessionToken(db: DatabaseClient, userId: string): Promise<string> {
+  await db.deleteFrom('core.session').where('user_id', '=', userId).execute();
+  const session = await insertSession(db, userId);
+  return session.token;
+}
+
+// --- Helpers ---
+
+function extractBearerToken(request: FastifyRequest): string | null {
+  const header = request.headers.authorization;
+  if (!header?.startsWith('Bearer ')) return null;
+  const token = header.slice(7);
+  return token || null;
+}
+
+async function findActiveSession(db: DatabaseClient, token: string): Promise<AuthSession | null> {
+  const session = (await db
+    .selectFrom('core.session')
+    .selectAll()
+    .where('token', '=', token)
+    .executeTakeFirst()) as AuthSession | undefined;
+
+  if (!session) return null;
+
+  const isExpired = new Date(session.expires_at).getTime() < Date.now();
+  return isExpired ? null : session;
+}
+
+async function findEnabledUser(
+  db: DatabaseClient,
+  value: string,
+  by: 'id' | 'email' = 'id',
+): Promise<AuthUser | null> {
+  const user = (await db
+    .selectFrom('core.user')
+    .selectAll()
+    .where(by, '=', value)
+    .executeTakeFirst()) as AuthUser | undefined;
+
+  if (!user || !user.enabled) return null;
+  return user;
+}
+
+async function getUserRoleNames(db: DatabaseClient, userId: string): Promise<string[]> {
+  const userRoles = await db
+    .selectFrom('core.user_role')
+    .selectAll()
+    .where('user_id', '=', userId)
+    .execute();
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const roleIds = userRoles.map((ur: any) => ur.role_id);
+  if (roleIds.length === 0) return [];
+
+  const roles = await db.selectFrom('core.role').selectAll().where('id', 'in', roleIds).execute();
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return roles.map((r: any) => r.name);
+}
+
+async function insertSession(db: DatabaseClient, userId: string) {
+  const token = generateToken();
+  const now = new Date();
+  const expiresAt = new Date(now.getTime() + SESSION_DURATION_MS);
+
+  return await db
+    .insertInto('core.session')
+    .values({
+      id: crypto.randomUUID(),
+      token,
+      user_id: userId,
+      expires_at: expiresAt.toISOString(),
+      created_at: now.toISOString(),
+    })
+    .returningAll()
+    .executeTakeFirstOrThrow();
+}

package/src/auth/types.ts

@@ -0,0 +1,50 @@
+import type { RolesConfig, ModelPermissions } from '@rangka/shared';
+
+export interface AuthUser {
+  id: string;
+  email: string;
+  full_name: string;
+  enabled: boolean;
+  password_hash: string;
+  [key: string]: unknown;
+}
+
+export interface AuthSession {
+  id: string;
+  token: string;
+  user_id: string;
+  expires_at: Date;
+  created_at: Date;
+  permission_version?: number;
+}
+
+export interface ResolvedPermissions {
+  models: Record<string, ModelPermissions>;
+  pages: string[];
+  version: number;
+}
+
+export interface RequestContext {
+  user?: AuthUser;
+  session?: AuthSession;
+  permissions?: ResolvedPermissions;
+  roles?: string[];
+  scopeFilters?: ScopeFilter[];
+}
+
+export interface ScopeFilter {
+  field: string;
+  operator: string;
+  value: unknown;
+}
+
+export interface RegisteredRole {
+  name: string;
+  config: RolesConfig[string];
+  app: string;
+}
+
+export interface PermissionCacheEntry {
+  permissions: ResolvedPermissions;
+  version: number;
+}

package/src/boot/__tests__/page-scanning.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect, vi } from 'vitest';
+import * as path from 'node:path';
+import { ProjectScanner } from '../project-scanner.js';
+import { validatePageSources, detectDuplicatePageKeys } from '../page-utils.js';
+import type { PageDefinition } from '@rangka/shared';
+
+const FIXTURE_ROOT = path.resolve(__dirname, '../../../../../tests/fixtures/basic-app');
+
+describe('ProjectScanner - page scanning', () => {
+  it('discovers pages from modules with pages directory', async () => {
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    expect(result.app.pages).toBeDefined();
+    expect(result.app.pages!.length).toBe(2);
+
+    const pageKeys = result.app.pages!.map((p) => p.page.key);
+    expect(pageKeys).toContain('sales.customers');
+    expect(pageKeys).toContain('sales.orders');
+
+    for (const entry of result.app.pages!) {
+      expect(entry.module).toBe('sales');
+    }
+  });
+
+  it('returns no pages field when no pages directory exists', async () => {
+    const scanner = new ProjectScanner(
+      path.resolve(__dirname, '../../../../../tests/fixtures/basic-app'),
+    );
+    const result = await scanner.scan();
+
+    if (result.app.pages) {
+      expect(result.app.pages.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('logs warning and continues when a page file has import error', async () => {
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+    const scanner = new ProjectScanner(FIXTURE_ROOT);
+    const result = await scanner.scan();
+
+    expect(result.app.pages).toBeDefined();
+    expect(result.app.pages!.length).toBeGreaterThan(0);
+
+    warnSpy.mockRestore();
+  });
+});
+
+describe('detectDuplicatePageKeys', () => {
+  it('emits warning for duplicate page keys', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'sales',
+        page: { key: 'sales.orders', label: 'Orders', type: 'collection', body: [] },
+      },
+      {
+        module: 'crm',
+        page: { key: 'sales.orders', label: 'Orders CRM', type: 'collection', body: [] },
+      },
+    ];
+
+    const warnings = detectDuplicatePageKeys(pages);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].pageKey).toBe('sales.orders');
+    expect(warnings[0].message).toContain('Duplicate page key');
+  });
+
+  it('no warnings when all keys are unique', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'sales',
+        page: { key: 'sales.orders', label: 'Orders', type: 'collection', body: [] },
+      },
+      {
+        module: 'sales',
+        page: { key: 'sales.customers', label: 'Customers', type: 'collection', body: [] },
+      },
+    ];
+
+    const warnings = detectDuplicatePageKeys(pages);
+    expect(warnings).toHaveLength(0);
+  });
+});
+
+describe('validatePageSources', () => {
+  const knownModels = new Set(['sales.order', 'sales.customer', 'contacts.contact']);
+
+  it('passes when all source models exist', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'sales',
+        page: {
+          key: 'sales.orders',
+          label: 'Orders',
+          type: 'collection',
+          body: [{ type: 'data', source: { model: 'sales.order' }, children: [] }],
+        },
+      },
+    ];
+
+    const warnings = validatePageSources(pages, knownModels);
+    expect(warnings).toHaveLength(0);
+  });
+
+  it('warns when body widget references non-existent model', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'sales',
+        page: {
+          key: 'sales.broken',
+          label: 'Broken',
+          type: 'collection',
+          body: [{ type: 'data', source: { model: 'sales.nonexistent' }, children: [] }],
+        },
+      },
+    ];
+
+    const warnings = validatePageSources(pages, knownModels);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].pageKey).toBe('sales.broken');
+    expect(warnings[0].location).toBe('body[0]');
+    expect(warnings[0].message).toContain('sales.nonexistent');
+  });
+
+  it('warns when nested widget references non-existent model', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'sales',
+        page: {
+          key: 'sales.detail',
+          label: 'Detail',
+          type: 'collection',
+          body: [
+            {
+              type: 'data',
+              source: { model: 'sales.order' },
+              children: [{ type: 'data', source: { model: 'contacts.missing' }, children: [] }],
+            },
+          ],
+        },
+      },
+    ];
+
+    const warnings = validatePageSources(pages, knownModels);
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0].location).toBe('body[0].children[0]');
+    expect(warnings[0].message).toContain('contacts.missing');
+  });
+
+  it('no warnings for widgets without model sources', () => {
+    const pages: Array<{ module: string; page: PageDefinition }> = [
+      {
+        module: 'reports',
+        page: {
+          key: 'reports.revenue',
+          label: 'Revenue',
+          type: 'dashboard',
+          body: [
+            { type: 'text', props: { content: 'Revenue Report' } },
+            { type: 'button', props: { label: 'Refresh' } },
+          ],
+        },
+      },
+    ];
+
+    const warnings = validatePageSources(pages, knownModels);
+    expect(warnings).toHaveLength(0);
+  });
+});