@bajustone/fortress 1.0.0-rc.1

package/src/core/manifest/drift.ts

@@ -0,0 +1,103 @@
+import type { OpenAPISpec } from '../../plugins/openapi/spec-builder';
+import type { EndpointDefinition } from '../endpoint';
+import type { Fortress } from '../fortress';
+import type { RouteManifestEntry } from './route-manifest';
+import { buildRouteManifest } from './route-manifest';
+
+export interface RouteManifestDrift {
+  mountedMissingFromManifest: string[];
+  manifestMissingFromMounted: string[];
+  openapiMissingFromManifest: string[];
+  manifestMissingFromOpenapi: string[];
+  rbacPermissionMismatches: Array<{
+    route: string;
+    expected?: string;
+    actual?: string;
+  }>;
+}
+
+export interface DetectRouteManifestDriftOptions {
+  manifest?: RouteManifestEntry[];
+  openapi?: OpenAPISpec;
+}
+
+function endpointKey(route: Pick<EndpointDefinition, 'method' | 'path'>): string {
+  return `${route.method.toUpperCase()} ${route.path}`;
+}
+
+function manifestKey(route: Pick<RouteManifestEntry, 'method' | 'path'>): string {
+  return `${route.method.toUpperCase()} ${route.path}`;
+}
+
+function toOpenAPIPath(path: string): string {
+  return path.replace(/:(\w+)/g, '{$1}');
+}
+
+function fromOpenAPIPath(path: string): string {
+  return path.replace(/\{(\w+)\}/g, ':$1');
+}
+
+function permissionKey(permission: { resource: string; action: string } | undefined): string | undefined {
+  return permission ? `${permission.resource}:${permission.action}` : undefined;
+}
+
+function diffSets(expected: Set<string>, actual: Set<string>): string[] {
+  return [...expected].filter(item => !actual.has(item)).sort();
+}
+
+export function detectRouteManifestDrift(
+  fortress: Pick<Fortress, 'endpoints' | 'config' | 'manifest'>,
+  options: DetectRouteManifestDriftOptions = {},
+): RouteManifestDrift {
+  const canonicalManifest = buildRouteManifest(fortress);
+  const manifest = options.manifest ?? fortress.manifest ?? canonicalManifest;
+
+  const mounted = new Set(canonicalManifest.filter(entry => entry.mounted).map(manifestKey));
+  const manifestMountedRoutes = new Set(manifest.filter(entry => entry.mounted).map(manifestKey));
+  const manifestRoutes = new Set(manifest.map(manifestKey));
+
+  let openapiRoutes = new Set<string>();
+  if (options.openapi) {
+    for (const [path, operations] of Object.entries(options.openapi.paths)) {
+      for (const method of Object.keys(operations))
+        openapiRoutes.add(`${method.toUpperCase()} ${fromOpenAPIPath(path)}`);
+    }
+  }
+  else {
+    openapiRoutes = new Set(fortress.endpoints.map(ep => `${ep.method.toUpperCase()} ${toOpenAPIPath(ep.path)}`).map(key => key.replace(/\{(\w+)\}/g, ':$1')));
+  }
+
+  const endpointPermissions = new Map<string, string | undefined>();
+  for (const endpoint of fortress.endpoints)
+    endpointPermissions.set(endpointKey(endpoint), permissionKey(endpoint.meta?.permission));
+
+  const rbacPermissionMismatches: RouteManifestDrift['rbacPermissionMismatches'] = [];
+  for (const entry of manifest) {
+    const key = manifestKey(entry);
+    const expected = endpointPermissions.get(key);
+    const actual = permissionKey(entry.permission);
+    if (expected !== actual) {
+      rbacPermissionMismatches.push({ route: key, expected, actual });
+      continue;
+    }
+    if (entry.classification === 'rbac' && !actual) {
+      rbacPermissionMismatches.push({ route: key, expected, actual });
+    }
+  }
+
+  return {
+    mountedMissingFromManifest: diffSets(mounted, manifestMountedRoutes),
+    manifestMissingFromMounted: diffSets(manifestMountedRoutes, mounted),
+    openapiMissingFromManifest: diffSets(openapiRoutes, manifestRoutes),
+    manifestMissingFromOpenapi: diffSets(manifestRoutes, openapiRoutes),
+    rbacPermissionMismatches,
+  };
+}
+
+export function hasRouteManifestDrift(drift: RouteManifestDrift): boolean {
+  return drift.mountedMissingFromManifest.length > 0
+    || drift.manifestMissingFromMounted.length > 0
+    || drift.openapiMissingFromManifest.length > 0
+    || drift.manifestMissingFromOpenapi.length > 0
+    || drift.rbacPermissionMismatches.length > 0;
+}

package/src/core/manifest/route-manifest.test.ts

@@ -0,0 +1,142 @@
+import type { EndpointDefinition } from '../endpoint';
+import { describe, expect, it } from 'vitest';
+import { authEndpoints } from '../auth/auth-endpoints';
+import { endpoint, obj, str } from '../schema-builder';
+import { detectRouteManifestDrift, hasRouteManifestDrift } from './drift';
+import { buildRouteManifest } from './route-manifest';
+
+function fakeFortress(endpoints: EndpointDefinition[], plugins: any[] = [], csrf: any = undefined) {
+  return {
+    endpoints,
+    config: { plugins, csrf },
+    get manifest() {
+      return buildRouteManifest(this as any);
+    },
+  };
+}
+
+describe('route manifest', () => {
+  it('classifies public, authenticated, rbac, and oauth protocol routes', () => {
+    const routes = {
+      publicPing: endpoint('GET', '/plugin/ping')
+        .summary('Ping')
+        .security('none')
+        .response(200, 'OK', obj({ ok: str() }, 'ok'))
+        .handler('publicPing')
+        .build(),
+      me: endpoint('GET', '/plugin/me')
+        .summary('Me')
+        .security('bearer')
+        .response(200, 'OK', obj({ ok: str() }, 'ok'))
+        .handler('me')
+        .build(),
+      admin: endpoint('POST', '/plugin/admin')
+        .summary('Admin')
+        .security('bearer')
+        .permission('plugin', 'admin')
+        .response(200, 'OK', obj({ ok: str() }, 'ok'))
+        .handler('admin')
+        .build(),
+      token: {
+        ...endpoint('POST', '/oauth/token')
+          .summary('Token')
+          .security('none')
+          .response(200, 'OK', obj({ ok: str() }, 'ok'))
+          .handler('token')
+          .build(),
+        meta: { summary: 'Token', security: ['none'], bearerKind: 'oauth' as const },
+      },
+    };
+    const plugin = {
+      name: 'plugin',
+      routes,
+    };
+    const rateLimitPlugin = {
+      name: 'rate-limit',
+      middleware: [{ path: '/plugin/admin', position: 'before-auth', handler: async (_ctx: unknown, _req: unknown, next: () => Promise<void>) => next() }],
+    };
+    const fortress = fakeFortress(Object.values(routes) as EndpointDefinition[], [plugin, rateLimitPlugin]);
+
+    const manifest = buildRouteManifest(fortress as any);
+    expect(manifest.map(entry => [entry.method, entry.path, entry.plugin, entry.classification])).toEqual([
+      ['GET', '/plugin/me', 'plugin', 'authenticated'],
+      ['GET', '/plugin/ping', 'plugin', 'public'],
+      ['POST', '/oauth/token', 'plugin', 'oauth-protocol'],
+      ['POST', '/plugin/admin', 'plugin', 'rbac'],
+    ]);
+    expect(manifest.find(entry => entry.path === '/plugin/admin')).toMatchObject({
+      permission: { resource: 'plugin', action: 'admin' },
+      csrfApplicable: true,
+      rateLimited: true,
+      mounted: true,
+    });
+  });
+
+  it('snapshots the core auth manifest subset', () => {
+    const endpoints = Object.values(authEndpoints) as EndpointDefinition[];
+    const manifest = buildRouteManifest(fakeFortress(endpoints) as any);
+
+    expect(manifest).toMatchSnapshot();
+    expect(manifest.every(entry => entry.classification !== 'default-deny')).toBe(true);
+  });
+
+  it('does not report valid metadata-only host routes as manifest drift', () => {
+    const host = endpoint('GET', '/host')
+      .summary('Host route')
+      .security('none')
+      .response(200, 'OK', obj({ ok: str() }, 'ok'))
+      .handler('host')
+      .build() as EndpointDefinition;
+    const fortress = fakeFortress([host]);
+    const drift = detectRouteManifestDrift(fortress as any);
+
+    expect(buildRouteManifest(fortress as any)[0]).toMatchObject({ mounted: false, plugin: null });
+    expect(hasRouteManifestDrift(drift)).toBe(false);
+  });
+
+  it('detects drift in mounted routes, OpenAPI routes, and RBAC permissions', () => {
+    const endpointDef = endpoint('POST', '/things/:id')
+      .summary('Update thing')
+      .security('bearer')
+      .permission('thing', 'update')
+      .response(200, 'OK', obj({ ok: str() }, 'ok'))
+      .handler('updateThing')
+      .build() as EndpointDefinition;
+    const otherEndpointDef = endpoint('POST', '/other/:id')
+      .summary('Update other thing')
+      .security('bearer')
+      .permission('other', 'update')
+      .response(200, 'OK', obj({ ok: str() }, 'ok'))
+      .handler('updateOtherThing')
+      .build() as EndpointDefinition;
+    const fortress = fakeFortress(
+      [endpointDef, otherEndpointDef],
+      [{ name: 'test-routes', routes: { updateThing: endpointDef, updateOtherThing: otherEndpointDef } }],
+    );
+    const manifest = buildRouteManifest(fortress as any);
+
+    const brokenManifest = [
+      { ...manifest.find(entry => entry.path === '/things/:id')!, path: '/things/:otherId' },
+      {
+        ...manifest.find(entry => entry.path === '/other/:id')!,
+        permission: undefined,
+        classification: 'authenticated' as const,
+      },
+    ];
+    const drift = detectRouteManifestDrift(fortress as any, { manifest: brokenManifest, openapi: {
+      openapi: '3.1.0',
+      info: { title: 'x', version: '1' },
+      paths: { '/things/{id}': { post: { responses: { 200: { description: 'OK' } } } as any } },
+      components: { schemas: {}, securitySchemes: {} },
+    } });
+
+    expect(hasRouteManifestDrift(drift)).toBe(true);
+    expect(drift.mountedMissingFromManifest).toEqual(['POST /things/:id']);
+    expect(drift.manifestMissingFromMounted).toEqual(['POST /things/:otherId']);
+    expect(drift.rbacPermissionMismatches).toContainEqual({
+      route: 'POST /other/:id',
+      expected: 'other:update',
+      actual: undefined,
+    });
+  });
+});

package/src/core/manifest/route-manifest.ts

@@ -0,0 +1,154 @@
+import type { EndpointDefinition, EndpointPermission, HttpMethod, SecurityRequirement } from '../endpoint';
+import type { Fortress } from '../fortress';
+import type { FortressPlugin, MiddlewareDefinition } from '../plugin';
+import { authEndpoints } from '../auth/auth-endpoints';
+import { resolveCsrfConfig } from '../http/csrf';
+import { iamEndpoints } from '../iam/iam-endpoints';
+
+export type RouteClassification = 'public' | 'authenticated' | 'rbac' | 'oauth-protocol' | 'default-deny';
+
+export interface RouteManifestEntry {
+  method: HttpMethod;
+  path: string;
+  handler: string;
+  plugin: string | null;
+  classification: RouteClassification;
+  permission?: EndpointPermission;
+  security: SecurityRequirement[];
+  bearerKind?: 'jwt' | 'oauth';
+  csrfApplicable: boolean;
+  rateLimited: boolean;
+  mounted: boolean;
+}
+
+interface EndpointWithOrigin {
+  endpoint: EndpointDefinition;
+  plugin: string | null;
+}
+
+const SAFE_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+function endpointKey(endpoint: Pick<EndpointDefinition, 'method' | 'path'>): string {
+  return `${endpoint.method.toUpperCase()} ${endpoint.path}`;
+}
+
+function classifyEndpoint(endpoint: EndpointDefinition): RouteClassification {
+  const security = endpoint.meta?.security ?? [];
+  if (endpoint.meta?.bearerKind === 'oauth')
+    return 'oauth-protocol';
+  if (security.includes('none'))
+    return 'public';
+  if (endpoint.meta?.permission)
+    return 'rbac';
+  if (security.includes('bearer') || security.includes('apiKey') || security.includes('basic'))
+    return 'authenticated';
+  return 'default-deny';
+}
+
+function pathPatternToRegex(pattern: string): RegExp {
+  const regexStr = pattern
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/:[^/]+/g, '[^/]+')
+    .replace(/\\\*/g, '.*')
+    .replace(/\//g, '\\/');
+  return new RegExp(`^${regexStr}$`);
+}
+
+function middlewareMatchesEndpoint(middleware: MiddlewareDefinition, endpoint: EndpointDefinition): boolean {
+  if (!pathPatternToRegex(middleware.path).test(endpoint.path))
+    return false;
+
+  const methods = (middleware as MiddlewareDefinition & { methods?: string[] }).methods;
+  if (methods && !methods.map(m => m.toUpperCase()).includes(endpoint.method.toUpperCase()))
+    return false;
+
+  return true;
+}
+
+function isRateLimited(endpoint: EndpointDefinition, plugins: readonly FortressPlugin[]): boolean {
+  for (const plugin of plugins) {
+    if (plugin.name !== 'rate-limit')
+      continue;
+    for (const middleware of plugin.middleware ?? []) {
+      if (middlewareMatchesEndpoint(middleware, endpoint))
+        return true;
+    }
+  }
+
+  // The rate-limit plugin's login/register/refresh protections are hook-based,
+  // not path middleware. Surface those as rate-limited in the manifest too.
+  if (plugins.some(plugin => plugin.name === 'rate-limit')) {
+    if (endpoint.method === 'POST' && endpoint.path === '/auth/login')
+      return true;
+    if (endpoint.method === 'POST' && endpoint.path === '/auth/register')
+      return true;
+    if (endpoint.method === 'POST' && endpoint.path === '/auth/refresh')
+      return true;
+  }
+
+  return false;
+}
+
+function csrfApplies(endpoint: EndpointDefinition, fortress: Pick<Fortress, 'config'>): boolean {
+  const csrf = resolveCsrfConfig(fortress.config.csrf);
+  if (!csrf.enabled)
+    return false;
+  if (SAFE_METHODS.has(endpoint.method.toUpperCase()))
+    return false;
+  for (const skip of csrf.skipPaths) {
+    if (endpoint.path === skip || endpoint.path.startsWith(`${skip}/`))
+      return false;
+  }
+  return true;
+}
+
+function collectEndpointOrigins(fortress: Pick<Fortress, 'endpoints' | 'config'>): EndpointWithOrigin[] {
+  const origins = new Map<string, EndpointWithOrigin>();
+
+  const coreAuth = Object.values(authEndpoints) as EndpointDefinition[];
+  const coreIam = Object.values(iamEndpoints) as EndpointDefinition[];
+  for (const endpoint of coreAuth)
+    origins.set(endpointKey(endpoint), { endpoint, plugin: 'auth' });
+  for (const endpoint of coreIam)
+    origins.set(endpointKey(endpoint), { endpoint, plugin: 'iam' });
+
+  for (const endpoint of Object.values(fortress.config.routes ?? {}) as EndpointDefinition[]) {
+    origins.set(endpointKey(endpoint), { endpoint, plugin: null });
+  }
+  for (const plugin of fortress.config.plugins ?? []) {
+    for (const endpoint of Object.values(plugin.routes ?? {}) as EndpointDefinition[]) {
+      origins.set(endpointKey(endpoint), { endpoint, plugin: plugin.name });
+    }
+  }
+
+  const byKey = new Map<string, EndpointWithOrigin>();
+  for (const endpoint of fortress.endpoints) {
+    const key = endpointKey(endpoint);
+    byKey.set(key, origins.get(key) ?? { endpoint, plugin: null });
+  }
+  return [...byKey.values()];
+}
+
+export function buildRouteManifest(fortress: Pick<Fortress, 'endpoints' | 'config'>): RouteManifestEntry[] {
+  const plugins = fortress.config.plugins ?? [];
+  return collectEndpointOrigins(fortress)
+    .map(({ endpoint, plugin }) => {
+      const security = endpoint.meta?.security ?? [];
+      return {
+        method: endpoint.method,
+        path: endpoint.path,
+        handler: endpoint.handler,
+        plugin,
+        classification: classifyEndpoint(endpoint),
+        ...(endpoint.meta?.permission ? { permission: endpoint.meta.permission } : {}),
+        security,
+        ...(endpoint.meta?.bearerKind ? { bearerKind: endpoint.meta.bearerKind } : {}),
+        csrfApplicable: csrfApplies(endpoint, fortress),
+        rateLimited: isRateLimited(endpoint, plugins),
+        // Top-level host routes are metadata/protection declarations only.
+        // Framework adapters must fall through to the host's own handler.
+        mounted: plugin !== null,
+      };
+    })
+    .sort((a, b) => `${a.method} ${a.path}`.localeCompare(`${b.method} ${b.path}`));
+}

package/src/core/migrate.test.ts

@@ -0,0 +1,72 @@
+import type { DatabaseAdapter } from '../adapters/database';
+import { describe, expect, it, vi } from 'vitest';
+import { createDrizzleAdapter } from '../drizzle/adapter';
+import { createTestAdapter } from '../testing';
+import { createFortress } from './fortress';
+
+const SECRET = 'fortress-migrate-test-secret-32!';
+
+function createBareSqliteAdapter(): DatabaseAdapter {
+  // eslint-disable-next-line ts/no-require-imports
+  const BetterSqlite3 = require('better-sqlite3');
+  // eslint-disable-next-line ts/no-require-imports
+  const { drizzle } = require('drizzle-orm/better-sqlite3');
+  return createDrizzleAdapter(drizzle(new BetterSqlite3(':memory:')));
+}
+
+describe('fortress.migrate', () => {
+  it('runs fortress migrations and reports the applied result', async () => {
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createBareSqliteAdapter(),
+    });
+
+    const result = await fortress.migrate();
+
+    expect(result.fortress.applied.length).toBeGreaterThan(0);
+    expect(result.fortress.toVersion).toBeGreaterThan(0);
+    expect(result.appRan).toBe(false);
+  });
+
+  it('calls migrateApp after fortress migrations complete', async () => {
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+    });
+
+    const callOrder: string[] = [];
+    const migrateApp = vi.fn(async () => {
+      callOrder.push('app');
+    });
+
+    // Stub the fortress-side step indirectly by recording from the result
+    const result = await fortress.migrate({ migrateApp });
+
+    expect(migrateApp).toHaveBeenCalledOnce();
+    expect(result.appRan).toBe(true);
+    expect(callOrder).toEqual(['app']);
+  });
+
+  it('is idempotent — re-running applies nothing', async () => {
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+    });
+
+    await fortress.migrate();
+    const second = await fortress.migrate();
+    expect(second.fortress.applied).toEqual([]);
+  });
+
+  it('propagates errors from migrateApp', async () => {
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+    });
+
+    const err = new Error('app migration failed');
+    await expect(
+      fortress.migrate({ migrateApp: async () => { throw err; } }),
+    ).rejects.toThrow('app migration failed');
+  });
+});