@bajustone/fortress 1.0.0-rc.1

package/src/core/plugin-methods-map.ts

@@ -0,0 +1,75 @@
+import type { ApiKeyMethods } from '../plugins/api-key';
+import type { AuditLogMethods } from '../plugins/audit-log';
+import type { DataIsolationMethods } from '../plugins/data-isolation';
+import type { EmailVerificationMethods } from '../plugins/email-verification';
+import type { MagicLinkMethods } from '../plugins/magic-link';
+import type { OAuthMethods } from '../plugins/oauth';
+import type { OpenAPIMethods } from '../plugins/openapi';
+import type { SocialLoginMethods } from '../plugins/social-login';
+import type { TenancyMethods } from '../plugins/tenancy';
+import type { TwoFactorMethods } from '../plugins/two-factor';
+import type { WebAuthnMethods } from '../plugins/webauthn';
+import type { EndpointDefinition, InferEndpointCallInput, InferEndpointSuccessResponse } from './endpoint';
+import type { CallOptions } from './http/call';
+import type { FortressPlugin } from './plugin';
+
+/**
+ * Type-level map of every built-in plugin name to its method-surface
+ * interface. {@link InferPlugins} uses this to expose typed plugin methods
+ * on the fortress instance.
+ */
+export interface PluginMethodsMap {
+  'api-key': ApiKeyMethods;
+  'audit-log': AuditLogMethods;
+  'data-isolation': DataIsolationMethods;
+  'email-verification': EmailVerificationMethods;
+  'magic-link': MagicLinkMethods;
+  'oauth': OAuthMethods;
+  'openapi': OpenAPIMethods;
+  'social-login': SocialLoginMethods;
+  'tenancy': TenancyMethods;
+  'two-factor': TwoFactorMethods;
+  'webauthn': WebAuthnMethods;
+}
+
+/** Infer the typed plugin-methods record from a `plugins` tuple passed to {@link createFortress}. */
+export type InferPlugins<T extends readonly FortressPlugin[]> = {
+  [P in T[number] as P['name']]: P['name'] extends keyof PluginMethodsMap
+    ? PluginMethodsMap[P['name']]
+    : Record<string, (...args: any[]) => any>;
+};
+
+// ── Typed call map helpers ──────────────────────────────────────────
+
+/** Distributes a union into an intersection — the classic TS trick. Used by {@link InferPluginCallMap}. */
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+
+/**
+ * Turn a record of {@link EndpointDefinition}s into a record of typed
+ * callables: each key becomes a function whose input is the endpoint's
+ * inferred body+query+params intersection and whose output is the inferred
+ * success-response body.
+ */
+export type CallableForEndpoints<E> = E extends Record<string, EndpointDefinition<any, any, any, any>>
+  ? {
+      [K in keyof E]: (
+        input: InferEndpointCallInput<E[K]>,
+        options?: CallOptions,
+      ) => Promise<InferEndpointSuccessResponse<E[K]>>;
+    }
+  : Record<string, never>;
+
+/**
+ * Infer the typed call surface contributed by a plugins tuple. Walks every
+ * plugin's `routes` record (if present) and unions the callables into one
+ * flat object keyed by handler name.
+ */
+export type InferPluginCallMap<T extends readonly FortressPlugin[]> = UnionToIntersection<
+  T[number] extends infer P
+    ? P extends { routes?: infer R }
+      ? R extends Record<string, EndpointDefinition<any, any, any, any>>
+        ? CallableForEndpoints<R>
+        : Record<string, never>
+      : Record<string, never>
+    : Record<string, never>
+>;

package/src/core/plugin-runner.test.ts

@@ -0,0 +1,233 @@
+/* eslint-disable ts/no-unsafe-function-type -- test uses Function type for plugin methods */
+import type { DatabaseAdapter } from '../adapters/database';
+import type { FortressConfig } from './config';
+import type { FortressPlugin } from './plugin';
+
+import { describe, expect, it, vi } from 'vitest';
+import {
+  chainAdapterWrappers,
+  collectScopeRules,
+  executePluginMiddleware,
+  mergeTokenClaims,
+  processPlugins,
+  wrapAdapterWithScopeRules,
+} from './plugin-runner';
+
+const mockDb = {} as DatabaseAdapter;
+const mockConfig = { jwt: { key: 'plugin-runner-test-secret-32ch!!' }, database: mockDb } as FortressConfig;
+
+function testPlugin(overrides: Partial<FortressPlugin> = {}): FortressPlugin {
+  return { name: 'test-plugin', ...overrides };
+}
+
+describe('processPlugins', () => {
+  it('returns empty object for plugins with no methods', () => {
+    const result = processPlugins([testPlugin()], mockDb, mockConfig);
+    expect(result['test-plugin']).toEqual({});
+  });
+
+  it('exposes plugin methods by plugin name', () => {
+    const plugin = testPlugin({
+      name: 'my-plugin',
+      methods: () => ({
+        greet: (name: string) => `hello ${name}`,
+      }),
+    });
+    const result = processPlugins([plugin], mockDb, mockConfig);
+    expect((result['my-plugin'].greet as Function)('world')).toBe('hello world');
+  });
+
+  it('passes PluginContext to methods factory', () => {
+    const methodsFn = vi.fn(() => ({}));
+    processPlugins([testPlugin({ methods: methodsFn })], mockDb, mockConfig);
+    expect(methodsFn).toHaveBeenCalledWith({ db: mockDb, config: mockConfig });
+  });
+
+  it('handles multiple plugins', () => {
+    const plugins = [
+      testPlugin({ name: 'a', methods: () => ({ foo: () => 1 }) }),
+      testPlugin({ name: 'b', methods: () => ({ bar: () => 2 }) }),
+    ];
+    const result = processPlugins(plugins, mockDb, mockConfig);
+    expect(Object.keys(result)).toEqual(['a', 'b']);
+  });
+});
+
+describe('chainAdapterWrappers', () => {
+  it('returns base adapter when no plugins wrap', () => {
+    const result = chainAdapterWrappers([testPlugin()], mockDb, {});
+    expect(result).toBe(mockDb);
+  });
+
+  it('chains wrappers in registration order', () => {
+    const calls: string[] = [];
+    const plugins = [
+      testPlugin({
+        name: 'first',
+        wrapAdapter: (adapter) => {
+          calls.push('first');
+          return { ...adapter, _first: true } as unknown as DatabaseAdapter;
+        },
+      }),
+      testPlugin({
+        name: 'second',
+        wrapAdapter: (adapter) => {
+          calls.push('second');
+          return { ...adapter, _second: true } as unknown as DatabaseAdapter;
+        },
+      }),
+    ];
+
+    const result = chainAdapterWrappers(plugins, mockDb, {}) as unknown as Record<string, unknown>;
+    expect(calls).toEqual(['first', 'second']);
+    expect(result._first).toBe(true);
+    expect(result._second).toBe(true);
+  });
+
+  it('passes request context to wrapAdapter', () => {
+    const wrapFn = vi.fn(adapter => adapter);
+    const plugin = testPlugin({ wrapAdapter: wrapFn });
+    const ctx = { tenantId: '5' };
+
+    chainAdapterWrappers([plugin], mockDb, ctx);
+    expect(wrapFn).toHaveBeenCalledWith(mockDb, ctx);
+  });
+});
+
+describe('mergeTokenClaims', () => {
+  it('returns empty object when no plugins enrich claims', async () => {
+    const result = await mergeTokenClaims([testPlugin()], '1', { db: mockDb, config: mockConfig });
+    expect(result).toEqual({});
+  });
+
+  it('merges claims from multiple plugins', async () => {
+    const plugins = [
+      testPlugin({
+        name: 'tenancy',
+        enrichTokenClaims: async () => ({ tenantId: '5' }),
+      }),
+      testPlugin({
+        name: 'custom',
+        enrichTokenClaims: async () => ({ role: 'admin' }),
+      }),
+    ];
+
+    const result = await mergeTokenClaims(plugins, '1', { db: mockDb, config: mockConfig });
+    expect(result).toEqual({ tenantId: '5', role: 'admin' });
+  });
+
+  it('later plugin wins on key conflict', async () => {
+    const plugins = [
+      testPlugin({
+        name: 'a',
+        enrichTokenClaims: async () => ({ key: 'first' }),
+      }),
+      testPlugin({
+        name: 'b',
+        enrichTokenClaims: async () => ({ key: 'second' }),
+      }),
+    ];
+
+    const result = await mergeTokenClaims(plugins, '1', { db: mockDb, config: mockConfig });
+    expect(result.key).toBe('second');
+  });
+});
+
+describe('executePluginMiddleware', () => {
+  it('canonicalizes double and trailing slashes before path matching', async () => {
+    const handler = vi.fn(async (_ctx, _request, next) => next());
+    const plugin = testPlugin({
+      middleware: [{ position: 'before-auth', path: '/auth/login', handler }],
+    });
+    const request = {
+      request: new Request('http://localhost/auth//login/'),
+    };
+
+    await executePluginMiddleware(
+      [plugin],
+      'before-auth',
+      '/auth//login/',
+      { db: mockDb, config: mockConfig },
+      request,
+    );
+    expect(handler).toHaveBeenCalledOnce();
+  });
+});
+
+describe('collectScopeRules', () => {
+  it('returns null when no plugins have scope rules', async () => {
+    const result = await collectScopeRules([testPlugin()], '1', 'sale', { db: mockDb, config: mockConfig });
+    expect(result).toBeNull();
+  });
+
+  it('returns null when plugin returns null for the model', async () => {
+    const plugin = testPlugin({
+      scopeRules: async () => null,
+    });
+    const result = await collectScopeRules([plugin], '1', 'sale', { db: mockDb, config: mockConfig });
+    expect(result).toBeNull();
+  });
+
+  it('collects filters and defaults from a single plugin', async () => {
+    const plugin = testPlugin({
+      scopeRules: async () => ({
+        filters: [{ field: 'siteId', operator: '=', value: 3 }],
+        defaults: { siteId: 3 },
+      }),
+    });
+
+    const result = await collectScopeRules([plugin], '1', 'sale', { db: mockDb, config: mockConfig });
+    expect(result).toEqual({
+      filters: [{ field: 'siteId', operator: '=', value: 3 }],
+      defaults: { siteId: 3 },
+    });
+  });
+
+  it('stacks filters and merges defaults from multiple plugins', async () => {
+    const plugins = [
+      testPlugin({
+        name: 'org',
+        scopeRules: async () => ({
+          filters: [{ field: 'orgId', operator: '=', value: 7 }],
+          defaults: { orgId: 7 },
+        }),
+      }),
+      testPlugin({
+        name: 'site',
+        scopeRules: async () => ({
+          filters: [{ field: 'siteId', operator: '=', value: 3 }],
+          defaults: { siteId: 3 },
+        }),
+      }),
+    ];
+
+    const result = await collectScopeRules(plugins, '1', 'sale', { db: mockDb, config: mockConfig });
+    expect(result?.filters).toHaveLength(2);
+    expect(result?.defaults).toEqual({ orgId: 7, siteId: 3 });
+  });
+});
+
+describe('wrapAdapterWithScopeRules', () => {
+  it('forces scoped defaults on create and rejects scoped-field updates', async () => {
+    const adapter = {
+      ...mockDb,
+      create: vi.fn(async params => params.data),
+      update: vi.fn(async params => params.data),
+      transaction: async (fn: (tx: DatabaseAdapter) => Promise<unknown>) => fn(adapter as unknown as DatabaseAdapter),
+    } as unknown as DatabaseAdapter & { create: ReturnType<typeof vi.fn>; update: ReturnType<typeof vi.fn> };
+
+    const scoped = wrapAdapterWithScopeRules(adapter, {
+      filters: [{ field: 'orgId', operator: '=', value: 'org-1' }],
+      defaults: { orgId: 'org-1' },
+    });
+
+    await scoped.create({ model: 'post', data: { title: 'hello', orgId: 'attacker-org' } });
+    expect(adapter.create).toHaveBeenCalledWith({ model: 'post', data: { title: 'hello', orgId: 'org-1' } });
+
+    await expect(scoped.update({
+      model: 'post',
+      where: [{ field: 'id', operator: '=', value: '1' }],
+      data: { orgId: 'attacker-org' },
+    })).rejects.toThrow('Cannot update scoped field \'orgId\'');
+  });
+});

package/src/core/plugin-runner.ts

@@ -0,0 +1,276 @@
+import type { DatabaseAdapter } from '../adapters/database';
+import type { ScopeRule, WhereClause } from '../adapters/database/types';
+import type { AuthService } from './auth/auth-service';
+import type { FortressConfig } from './config';
+import type { PluginRequestContext } from './http/plugin-middleware';
+import type { IamService } from './iam/iam-service';
+import type { FortressLogger } from './observability/logger';
+import type { FortressPlugin, MiddlewareDefinition, PluginContext } from './plugin';
+import { Errors } from './errors';
+import { canonicalizePath } from './http/match';
+
+/**
+ * Process registered plugins and return their exposed methods.
+ */
+
+export function processPlugins(
+  plugins: readonly FortressPlugin[],
+  db: DatabaseAdapter,
+  config: FortressConfig,
+  auth?: AuthService,
+  iam?: IamService,
+  logger?: FortressLogger,
+  // eslint-disable-next-line ts/no-unsafe-function-type -- plugin methods are dynamically typed
+): Record<string, Record<string, Function>> {
+  const ctx: PluginContext = { db, config, auth, iam, logger };
+  // eslint-disable-next-line ts/no-unsafe-function-type -- plugin methods are dynamically typed
+  const result: Record<string, Record<string, Function>> = {};
+
+  for (const plugin of plugins) {
+    result[plugin.name] = plugin.methods?.(ctx) ?? {};
+  }
+
+  return result;
+}
+
+/**
+ * Chain wrapAdapter from all plugins in registration order.
+ * Each wrapper receives the result of the previous.
+ */
+export function chainAdapterWrappers(
+  plugins: readonly FortressPlugin[],
+  baseAdapter: DatabaseAdapter,
+  requestContext: Record<string, unknown>,
+): DatabaseAdapter {
+  let adapter = baseAdapter;
+
+  for (const plugin of plugins) {
+    if (plugin.wrapAdapter) {
+      adapter = plugin.wrapAdapter(adapter, requestContext);
+    }
+  }
+
+  return adapter;
+}
+
+/**
+ * Collect and merge enrichTokenClaims from all plugins.
+ * Later plugins override earlier ones on key conflicts.
+ */
+export async function mergeTokenClaims(
+  plugins: readonly FortressPlugin[],
+  userId: string,
+  ctx: PluginContext,
+): Promise<Record<string, unknown>> {
+  const merged: Record<string, unknown> = {};
+
+  for (const plugin of plugins) {
+    if (plugin.enrichTokenClaims) {
+      const claims = await plugin.enrichTokenClaims(userId, ctx);
+      if (process.env.NODE_ENV !== 'production') {
+        for (const key of Object.keys(claims)) {
+          if (key in merged) {
+            ctx.logger?.warn(
+              { plugin: plugin.name, claim: key },
+              `plugin overwrites token claim '${key}'`,
+            );
+          }
+        }
+      }
+      Object.assign(merged, claims);
+    }
+  }
+
+  return merged;
+}
+
+/**
+ * Collect and stack scopeRules from all plugins for a given model.
+ * All filters are AND'd together. All defaults are merged.
+ */
+export async function collectScopeRules(
+  plugins: readonly FortressPlugin[],
+  userId: string,
+  model: string,
+  ctx: PluginContext,
+): Promise<ScopeRule | null> {
+  const allFilters: WhereClause[] = [];
+  const allDefaults: Record<string, unknown> = {};
+
+  for (const plugin of plugins) {
+    if (!plugin.scopeRules) {
+      continue;
+    }
+    const rule = await plugin.scopeRules(userId, model, ctx);
+    if (!rule) {
+      continue;
+    }
+    allFilters.push(...rule.filters);
+    Object.assign(allDefaults, rule.defaults);
+  }
+
+  if (allFilters.length === 0 && Object.keys(allDefaults).length === 0) {
+    return null;
+  }
+
+  return { filters: allFilters, defaults: allDefaults };
+}
+
+/**
+ * Wrap a DatabaseAdapter to auto-apply scope rules on every operation.
+ * Reads (findOne, findMany, count) get extra WHERE clauses.
+ * Writes (create) get default values merged into data.
+ * Mutations (update, delete) get extra WHERE clauses to prevent cross-scope changes.
+ */
+export function wrapAdapterWithScopeRules(
+  adapter: DatabaseAdapter,
+  scopeRule: ScopeRule,
+): DatabaseAdapter {
+  const { filters, defaults } = scopeRule;
+
+  return {
+    ...adapter,
+
+    create: <T>(params: {
+      model: string;
+      data: Record<string, unknown>;
+    }): Promise<T> =>
+      adapter.create<T>({
+        ...params,
+        data: { ...params.data, ...defaults },
+      }),
+
+    findOne: <T>(params: {
+      model: string;
+      where: WhereClause[];
+    }): Promise<T | null> =>
+      adapter.findOne<T>({
+        ...params,
+        where: [...params.where, ...filters],
+      }),
+
+    findMany: <T>(params: {
+      model: string;
+      where?: WhereClause[];
+      limit?: number;
+      offset?: number;
+      sortBy?: { field: string; direction: 'asc' | 'desc' };
+    }): Promise<T[]> =>
+      adapter.findMany<T>({
+        ...params,
+        where: [...(params.where ?? []), ...filters],
+      }),
+
+    update: <T>(params: {
+      model: string;
+      where: WhereClause[];
+      data: Record<string, unknown>;
+    }): Promise<T | null> => Promise.resolve().then(() => {
+      for (const key of Object.keys(defaults)) {
+        if (Object.hasOwn(params.data, key))
+          throw Errors.forbidden(`Cannot update scoped field '${key}'`);
+      }
+      return adapter.update<T>({
+        ...params,
+        where: [...params.where, ...filters],
+      });
+    }),
+
+    delete: (params: { model: string; where: WhereClause[] }): Promise<void> =>
+      adapter.delete({
+        ...params,
+        where: [...params.where, ...filters],
+      }),
+
+    count: (params: {
+      model: string;
+      where?: WhereClause[];
+    }): Promise<number> =>
+      adapter.count({
+        ...params,
+        where: [...(params.where ?? []), ...filters],
+      }),
+
+    transaction: <T>(fn: (tx: DatabaseAdapter) => Promise<T>): Promise<T> =>
+      adapter.transaction(tx => fn(wrapAdapterWithScopeRules(tx, scopeRule))),
+  };
+}
+
+/**
+ * Get all model definitions declared by plugins.
+ */
+export function collectPluginModels(
+  plugins: readonly FortressPlugin[],
+): { pluginName: string; models: FortressPlugin['models'] }[] {
+  return plugins
+    .filter(p => p.models && p.models.length > 0)
+    .map(p => ({ pluginName: p.name, models: p.models }));
+}
+
+/**
+ * Convert a middleware path pattern to a regex.
+ * Supports `:param` (single segment) and `*` (wildcard).
+ */
+function middlewarePathToRegex(pattern: string): RegExp {
+  const regexStr = canonicalizePath(pattern)
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/:[^/]+/g, '[^/]+')
+    .replace(/\\\*/g, '.*')
+    .replace(/\//g, '\\/');
+  return new RegExp(`^${regexStr}$`);
+}
+
+/**
+ * Collect all middleware definitions from plugins matching a given position.
+ * Returns them in plugin registration order.
+ */
+export function collectPluginMiddleware(
+  plugins: readonly FortressPlugin[],
+  position: MiddlewareDefinition['position'],
+): { plugin: FortressPlugin; middleware: MiddlewareDefinition }[] {
+  const result: { plugin: FortressPlugin; middleware: MiddlewareDefinition }[] = [];
+  for (const plugin of plugins) {
+    if (!plugin.middleware)
+      continue;
+    for (const mw of plugin.middleware) {
+      if (mw.position === position) {
+        result.push({ plugin, middleware: mw });
+      }
+    }
+  }
+  return result;
+}
+
+/**
+ * Execute plugin middleware for a given position and request path.
+ *
+ * Iterates through all plugins in registration order, filters by position,
+ * matches the middleware path pattern against the request path, and chains
+ * handlers so each `next()` invokes the next matching middleware.
+ */
+export async function executePluginMiddleware(
+  plugins: readonly FortressPlugin[],
+  position: MiddlewareDefinition['position'],
+  requestPath: string,
+  ctx: PluginContext,
+  request: PluginRequestContext,
+): Promise<void> {
+  const canonicalRequestPath = canonicalizePath(requestPath);
+  const matching = collectPluginMiddleware(plugins, position)
+    .filter(({ middleware: mw }) => middlewarePathToRegex(mw.path).test(canonicalRequestPath));
+
+  if (matching.length === 0)
+    return;
+
+  // Build a chain where each handler's `next` calls the next middleware
+  let index = 0;
+
+  async function runNext(): Promise<void> {
+    if (index >= matching.length)
+      return;
+    const current = matching[index++];
+    await current.middleware.handler(ctx, request, runNext);
+  }
+
+  await runNext();
+}