@bajustone/fortress 1.0.0-rc.1

package/src/core/fortress.ts

@@ -0,0 +1,550 @@
+import type { OpenAPISpec } from '../plugins/openapi/spec-builder';
+import type { AuthEvent, AuthService } from './auth/auth-service';
+import type { FortressConfig, ResolvedCookieConfig } from './config';
+import type { EndpointDefinition } from './endpoint';
+import type { AuthCookiePayload } from './http/cookie-serialize';
+import type { PluginRequestContext } from './http/plugin-middleware';
+import type { ResolvedPrincipal } from './http/principal';
+import type { IamEvent, IamService, PermissionCheckEvent } from './iam/iam-service';
+import type { PermissionSyncOptions, PermissionSyncResult } from './iam/permission-sync';
+import type { RouteManifestEntry } from './manifest/route-manifest';
+import type { MigrationApplyResult } from './migrations/engine';
+import type { FortressLogger } from './observability/logger';
+import type { TelemetryProvider } from './observability/types';
+import type { ToOpenAPIOptions } from './openapi';
+import type { FortressPlugin, MiddlewareDefinition } from './plugin';
+import type { CallableForEndpoints, InferPluginCallMap, InferPlugins } from './plugin-methods-map';
+import { authEndpoints } from './auth/auth-endpoints';
+import { createAuthService } from './auth/auth-service';
+import { resolveCookieConfig } from './config';
+import { Errors } from './errors';
+import { buildCall } from './http/call';
+import { serializeAuthCookies as serializeAuthCookiesFn } from './http/cookie-serialize';
+import { buildHandleRequest } from './http/handle-request';
+import { canonicalizePath } from './http/match';
+import { runPluginMiddleware as runPluginMiddlewareFn } from './http/plugin-middleware';
+import { resolveRequestPrincipal as resolveRequestPrincipalFn } from './http/principal';
+import { extractAccessToken as extractAccessTokenFn } from './http/token-extraction';
+import { iamEndpoints } from './iam/iam-endpoints';
+import { createIamService } from './iam/iam-service';
+import { runPermissionSync } from './iam/permission-sync';
+import { buildRouteManifest } from './manifest/route-manifest';
+import { migrateUp } from './migrations/engine';
+import { instrumentAdapter } from './observability/db-instrumentation';
+import { SILENT_LOGGER } from './observability/logger';
+import { NO_OP_TELEMETRY } from './observability/types';
+import { toOpenAPI as endpointsToOpenAPI } from './openapi';
+import { processPlugins } from './plugin-runner';
+
+/**
+ * Typed in-process call surface. Composes auth + IAM endpoint callables
+ * with any plugin-contributed routes (derived from the plugins tuple).
+ *
+ * Each handler becomes a `(input, options?) => Promise<successBody>` where
+ * the input shape is the inferred intersection of the endpoint's body,
+ * query, and params schemas, and the output is the inferred 2xx response
+ * type. Non-2xx responses throw a `FortressError`.
+ */
+export type TypedCall<T extends readonly FortressPlugin[]>
+  = & CallableForEndpoints<typeof authEndpoints>
+    & CallableForEndpoints<typeof iamEndpoints>
+    & InferPluginCallMap<T>;
+
+/**
+ * Configured fortress instance returned by {@link createFortress}. Holds the
+ * core auth and IAM services, the resolved config, every endpoint definition
+ * (auth + IAM + plugin routes), and the typed plugin method surface.
+ *
+ * Also exposes the framework-agnostic HTTP entry points
+ * ({@link Fortress.handleRequest}, {@link Fortress.runPluginMiddleware},
+ * {@link Fortress.extractAccessToken}, {@link Fortress.serializeAuthCookies})
+ * that adapters delegate to. See `src/core/http/`.
+ */
+
+export interface Fortress<
+  // eslint-disable-next-line ts/no-unsafe-function-type -- fallback type for untyped plugin access
+  TPlugins = Record<string, Record<string, Function>>,
+  TCall = Record<string, (input?: any, options?: any) => Promise<any>>,
+> {
+  auth: AuthService;
+  iam: IamService;
+  plugins: TPlugins;
+  /**
+   * Typed in-process client. Each key is a handler name (from the core
+   * auth/IAM endpoint records or a plugin's `routes` record); each value is
+   * an async function whose input/output types are inferred from the
+   * endpoint's declared body/query/params/response schemas.
+   *
+   * Under the hood, each callable serializes its input to a `Request` and
+   * delegates to `fortress.handleRequest`, so middleware, token
+   * verification, RBAC, and validation all run — the same path a network
+   * client would eventually hit. See `src/core/http/call.ts`.
+   */
+  call: TCall;
+  config: Readonly<FortressConfig>;
+  /** All endpoint definitions (auth + IAM + plugins) with JSON Schema metadata. */
+  endpoints: EndpointDefinition[];
+  /** Canonical generated route-security manifest derived from endpoint metadata. */
+  manifest: RouteManifestEntry[];
+  /** Resolved auth-cookie names and attributes (NODE_ENV-aware). */
+  cookies: ResolvedCookieConfig;
+  /** Resolved logger (defaults to a silent no-op when `config.logger` is unset). */
+  logger: FortressLogger;
+  /** Resolved telemetry provider (defaults to a no-op when `config.observability` is unset). */
+  telemetry: TelemetryProvider;
+  /**
+   * Handle a Fortress-managed request and return a web-standard `Response`.
+   * Composes plugin middleware, token verification, default-deny RBAC,
+   * validation, and dispatch.
+   *
+   * Adapters call this for paths owned by Fortress (e.g. `/auth/*`,
+   * `/iam/*`, plugin-registered routes). See `src/core/http/handle-request.ts`.
+   */
+  handleRequest: (request: Request) => Promise<Response>;
+  /**
+   * Run plugin middleware at a given lifecycle phase, passing a duck-typed
+   * request context. Adapters call this on user-owned routes so plugins
+   * like rate-limit and audit-log still apply outside Fortress paths.
+   */
+  runPluginMiddleware: (
+    phase: MiddlewareDefinition['position'],
+    ctx: PluginRequestContext,
+  ) => Promise<void>;
+  /**
+   * Extract the access token from a request, preferring the configured
+   * cookie and falling back to `Authorization: Bearer`.
+   */
+  extractAccessToken: (request: Request) => string | null;
+  /**
+   * Resolve the request principal by trying plugin `resolvePrincipal`
+   * hooks (e.g. `api-key`) first, then falling back to the configured JWT
+   * bearer token. Non-throwing — returns `null` when no credential is
+   * present or the JWT fails to verify.
+   *
+   * Adapter user-route middleware calls this so api-keys, cookies, and
+   * bearer tokens authenticate uniformly on user-owned routes — not just
+   * Fortress-owned routes dispatched through `handleRequest`.
+   */
+  resolvePrincipal: (request: Request) => Promise<ResolvedPrincipal | null>;
+  /**
+   * Serialize an auth result (or pair of tokens) into one or two
+   * `Set-Cookie` header values using the resolved cookie config and the
+   * configured token expiries.
+   */
+  serializeAuthCookies: (payload: AuthCookiePayload) => string[];
+  /**
+   * Run Fortress's pending schema migrations against the configured database
+   * and, optionally, an application-supplied migration step afterwards.
+   *
+   * Fortress migrations always run first because app schemas commonly
+   * reference fortress tables (foreign keys to `user.id`, etc.). The
+   * `migrateApp` callback (when provided) is awaited after Fortress
+   * migrations complete, so a host can do something like:
+   *
+   * ```ts
+   * await fortress.migrate({
+   *   migrateApp: () => migrate(db, { migrationsFolder: './drizzle' }),
+   * });
+   * ```
+   *
+   * Eliminates the two-step "forget to call `migrateUp` and silently
+   * have no auth tables" footgun.
+   */
+  migrate: (opts?: MigrateOptions) => Promise<MigrateResult>;
+  /**
+   * Seed permissions discovered on registered endpoints (`fortress.endpoints`)
+   * into the IAM database and, optionally, bind them onto a set of default
+   * roles. Idempotent — re-running adds only what's missing and never
+   * revokes anything that was already there.
+   *
+   * Typical bootstrap sequence:
+   *
+   * ```ts
+   * await fortress.migrate({ migrateApp: () => migrate(db, '...') });
+   * await fortress.syncPermissionsFromManifest({
+   *   defaultRoles: { admin: '*', member: ['school:read', 'school:list'] },
+   * });
+   * ```
+   *
+   * Replaces the seed script every consumer used to write that walked
+   * `fortress.endpoints`, deduped `(resource, action)` pairs, and called
+   * `iam.createPermission(...)` for each.
+   */
+  syncPermissionsFromManifest: (opts?: PermissionSyncOptions) => Promise<PermissionSyncResult>;
+  /**
+   * Emit a complete OpenAPI 3.1 spec from the endpoint definitions Fortress
+   * knows about: core auth/IAM routes, plugin routes, and any top-level
+   * host `routes` registered on {@link FortressConfig}.
+   *
+   * This is the programmatic companion to the OpenAPI plugin. Use it when
+   * you already own the docs route or when a build script needs to write
+   * `openapi.json` for client codegen:
+   *
+   * ```ts
+   * const spec = fortress.toOpenAPI({
+   *   title: 'My API',
+   *   version: '0.0.0',
+   *   servers: [{ url: 'http://localhost:3001', description: 'Local' }],
+   *   tags: [{ name: 'Schools' }],
+   * });
+   * ```
+   *
+   * Defaults to endpoint `handler` names for `operationId`, matching most
+   * host route-contract files. Pass `operationId: 'methodPath'` to keep the
+   * historical OpenAPI-plugin ID style.
+   */
+  toOpenAPI: (opts?: FortressToOpenAPIOptions) => OpenAPISpec;
+}
+
+/** Options accepted by {@link Fortress.toOpenAPI}. */
+export interface FortressToOpenAPIOptions extends ToOpenAPIOptions {
+  /** Override the endpoints to emit. Defaults to `fortress.endpoints`. */
+  endpoints?: EndpointDefinition[];
+}
+
+/** Options accepted by {@link Fortress.migrate}. */
+export interface MigrateOptions {
+  /**
+   * Optional host-app migration step. Runs after Fortress migrations
+   * complete; any thrown error propagates after Fortress migrations have
+   * already been applied. Library-agnostic: pass any `() => Promise<void>`
+   * — e.g. drizzle's `migrate(db, { migrationsFolder })`, Knex's
+   * `db.migrate.latest()`, a hand-rolled SQL runner.
+   */
+  migrateApp?: () => Promise<void>;
+  /**
+   * Override the migration dialect. Defaults to the adapter's `dialect`
+   * property (matches the behavior of {@link migrateUp}).
+   */
+  dialect?: 'sqlite' | 'pg';
+  /** Stop applying Fortress migrations after this version. Defaults to the latest. */
+  targetVersion?: number;
+}
+
+/** Result returned by {@link Fortress.migrate}. */
+export interface MigrateResult {
+  /** Result of the Fortress-managed migration step. */
+  fortress: MigrationApplyResult;
+  /** `true` if `migrateApp` was supplied and ran to completion. */
+  appRan: boolean;
+}
+
+/**
+ * Type-safe helper to retrieve a plugin's methods from a Fortress instance.
+ *
+ * Since plugin methods are dynamically typed at runtime, this helper lets
+ * consumers provide a known interface for type-safe access without casting.
+ *
+ * @example
+ * ```ts
+ * interface TwoFactorMethods {
+ *   setup: (userId: string) => Promise<{ secret: string; qrCode: string }>;
+ *   verify: (userId: string, code: string) => Promise<boolean>;
+ * }
+ *
+ * const twoFactor = getPluginMethods<TwoFactorMethods>(fortress, 'two-factor');
+ * const result = await twoFactor.setup(userId); // fully typed
+ * ```
+ */
+export function getPluginMethods<T>(fortress: Fortress, pluginName: string): T {
+  const methods = fortress.plugins[pluginName];
+  if (!methods) {
+    throw Errors.notFound(`Plugin '${pluginName}' is not registered`);
+  }
+  return methods as T;
+}
+
+const MIN_SECRET_BYTES = 32;
+
+/**
+ * Build a configured {@link Fortress} instance from a {@link FortressConfig}.
+ *
+ * Validates the JWT secret strength, deduplicates and processes the plugin
+ * list, wires up auth/IAM services, and returns the assembled instance with
+ * type-safe plugin method access for any plugins listed in the config.
+ */
+export function createFortress<const T extends readonly FortressPlugin[]>(
+  config: FortressConfig & { plugins?: T },
+): Fortress<InferPlugins<T>, TypedCall<T>> {
+  // Validate JWT key strength (HS256 shared-secret bytes).
+  const keys = Array.isArray(config.jwt.key) ? config.jwt.key : [config.jwt.key];
+  for (const key of keys) {
+    if (new TextEncoder().encode(key).length < MIN_SECRET_BYTES) {
+      throw Errors.badRequest(
+        `JWT key must be at least ${MIN_SECRET_BYTES} bytes for HS256 security. Got ${new TextEncoder().encode(key).length} bytes.`,
+      );
+    }
+  }
+
+  const session = config.jwt.session;
+  if (session) {
+    for (const [name, value] of Object.entries(session)) {
+      if (value != null && (!Number.isInteger(value) || value <= 0)) {
+        throw Errors.badRequest(`jwt.session.${name} must be a positive integer`);
+      }
+    }
+  }
+
+  // Synthesize a virtual plugin from any top-level `routes` field so host
+  // apps don't have to hand-roll a one-field plugin just to register their
+  // own endpoints. Prepended to the plugin list so its routes appear before
+  // explicit plugins in the manifest, matching the registration order a
+  // user would write themselves.
+  const HOST_ROUTES_PLUGIN_NAME = '__host';
+  const userPlugins = config.plugins ?? [];
+  if (config.routes) {
+    const collision = userPlugins.find(p => p.name === HOST_ROUTES_PLUGIN_NAME);
+    if (collision) {
+      throw Errors.badRequest(
+        `Plugin name '${HOST_ROUTES_PLUGIN_NAME}' is reserved for top-level \`routes\`; rename your plugin.`,
+      );
+    }
+  }
+  const hostRoutesPlugin: FortressPlugin | null = config.routes
+    ? { name: HOST_ROUTES_PLUGIN_NAME, routes: config.routes }
+    : null;
+  const plugins = hostRoutesPlugin ? [hostRoutesPlugin, ...userPlugins] : userPlugins;
+
+  // Resolve observability defaults. SILENT_LOGGER and NO_OP_TELEMETRY are
+  // zero-allocation singletons — if the caller doesn't opt in, Fortress
+  // never writes to stderr and every metric/span call is a no-op.
+  const logger = config.logger ?? SILENT_LOGGER;
+  const telemetry = config.observability ?? NO_OP_TELEMETRY;
+
+  // Wrap the adapter with DB instrumentation. When `telemetry` is the
+  // no-op default, the wrapper records into a no-op histogram — essentially
+  // free. When a real OTel adapter is wired, every Fortress-internal query
+  // (and every plugin query that also uses this adapter) emits the stable
+  // `db.client.operation.duration` metric with standard attributes.
+  const db = instrumentAdapter(config.database, telemetry);
+
+  // Validate plugin name uniqueness
+  const pluginNames = new Set<string>();
+  for (const plugin of plugins) {
+    if (pluginNames.has(plugin.name)) {
+      throw Errors.badRequest(`Duplicate plugin name: '${plugin.name}'`);
+    }
+    pluginNames.add(plugin.name);
+  }
+
+  // Token-verify histogram is built before the auth service so it can be
+  // passed in via deps. Kept here (not inside auth-service) so the metric
+  // catalog lives in one place.
+  const tokenVerifyDuration = telemetry.meter.createHistogram('fortress.auth.token_verify.duration', {
+    unit: 's',
+    description: 'JWT access token verification latency',
+    boundaries: [0.0001, 0.0005, 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1],
+  });
+
+  const auth = createAuthService(db, config, plugins, { logger, telemetry, tokenVerifyDuration });
+  const iam = createIamService(db, config, { logger, telemetry });
+  const pluginMethods = processPlugins(plugins, db, config, auth, iam, logger);
+
+  // --- Wire built-in telemetry observers ------------------------------
+  //
+  // Translate AuthEvent / IamEvent / PermissionCheckEvent into metric
+  // updates. Attribute keys follow the Prometheus `.total` convention
+  // for counters and seconds for durations. User IDs are NEVER placed
+  // on metric attributes (cardinality bomb) — they go on spans/logs.
+  const authEventCounter = telemetry.meter.createCounter('fortress.auth.events.total', {
+    description: 'Auth lifecycle events (login, register, refresh, logout, token reuse)',
+  });
+  const iamEventCounter = telemetry.meter.createCounter('fortress.iam.events.total', {
+    description: 'IAM mutation events (role/permission/binding/group changes)',
+  });
+  const permissionCheckDuration = telemetry.meter.createHistogram('fortress.iam.permission_check.duration', {
+    unit: 's',
+    description: 'Permission check latency',
+    boundaries: [0.0001, 0.0005, 0.001, 0.005, 0.01, 0.05, 0.1, 0.5, 1],
+  });
+  const cacheHitCounter = telemetry.meter.createCounter('fortress.iam.permission_check.cache.hits', {
+    description: 'Permission check resolved from cache',
+  });
+  const cacheMissCounter = telemetry.meter.createCounter('fortress.iam.permission_check.cache.misses', {
+    description: 'Permission check that hit the database',
+  });
+
+  auth.addAuthObserver((event: AuthEvent) => {
+    authEventCounter.add(1, {
+      event: event.eventType,
+      outcome: event.outcome ?? 'n/a',
+      method: event.method ?? 'n/a',
+    });
+  });
+
+  iam.addIamObserver((event: IamEvent) => {
+    iamEventCounter.add(1, { event: event.eventType });
+  });
+
+  iam.addPermissionCheckObserver((event: PermissionCheckEvent) => {
+    permissionCheckDuration.record(event.durationSeconds, {
+      subject_type: event.subjectType,
+      result: event.allowed ? 'allow' : 'deny',
+      cached: event.cached ? 'true' : 'false',
+    });
+    if (event.cached) {
+      cacheHitCounter.add(1);
+    }
+    else {
+      cacheMissCounter.add(1);
+    }
+  });
+
+  // Wire IAM events → audit log if the plugin is registered
+  if (pluginMethods['audit-log']?.logCustomEvent) {
+    const logCustomEvent = pluginMethods['audit-log'].logCustomEvent as (event: IamEvent) => Promise<void>;
+    iam.addIamObserver(event => logCustomEvent(event));
+  }
+
+  // Assemble all endpoint definitions. A plugin may intentionally override a
+  // core route, but two plugins claiming the same method+path is ambiguous and
+  // therefore rejected instead of depending on registration order.
+  const endpointMap = new Map<string, EndpointDefinition>();
+  const endpointOwners = new Map<string, string>();
+  const coreEndpoints: EndpointDefinition[] = [
+    ...Object.values(authEndpoints) as EndpointDefinition[],
+    ...Object.values(iamEndpoints) as EndpointDefinition[],
+  ];
+  for (const ep of coreEndpoints) {
+    const routeKey = `${ep.method.toUpperCase()} ${canonicalizePath(ep.path)}`;
+    endpointMap.set(routeKey, ep);
+    endpointOwners.set(routeKey, 'core');
+  }
+  for (const plugin of plugins) {
+    for (const ep of Object.values(plugin.routes ?? {}) as EndpointDefinition[]) {
+      const routeKey = `${ep.method.toUpperCase()} ${canonicalizePath(ep.path)}`;
+      const owner = endpointOwners.get(routeKey);
+      if (owner && owner !== 'core') {
+        throw Errors.badRequest(
+          `Duplicate endpoint ${routeKey} declared by plugins "${owner}" and "${plugin.name}"`,
+        );
+      }
+      endpointMap.set(routeKey, ep);
+      endpointOwners.set(routeKey, plugin.name);
+    }
+  }
+  const endpoints = Array.from(endpointMap.values());
+
+  // L-tier: fail-fast on `security: ['none']` + `permission` collisions.
+  // The two are mutually exclusive: an unauthenticated route has no subject
+  // to evaluate the permission against, so default-deny RBAC would always
+  // reject it. Catch the misconfiguration at startup, not at first request.
+  const oauthSelfAuthAllowlist = new Set([
+    'GET /oauth/authorize',
+    'POST /oauth/token',
+    'POST /oauth/introspect',
+    'POST /oauth/revoke',
+    'GET /oauth/userinfo',
+    'GET /oauth/.well-known/openid-configuration',
+    'GET /oauth/.well-known/jwks.json',
+  ]);
+  for (const ep of endpoints) {
+    const security = ep.meta?.security ?? [];
+    if (security.includes('none') && ep.meta?.permission) {
+      throw Errors.badRequest(
+        `Endpoint ${ep.method} ${ep.path} declares security:['none'] AND a permission `
+        + `(${ep.meta.permission.resource}:${ep.meta.permission.action}). These are mutually `
+        + `exclusive — default-deny RBAC would reject every request.`,
+      );
+    }
+
+    // P3.6: `bearerKind: 'oauth'` means "this handler self-authenticates"
+    // and therefore skips the normal plugin/JWT/RBAC/JSON-validation
+    // pipeline. It is intentionally reserved for the OAuth protocol routes
+    // that parse form bodies or OAuth access tokens themselves. Any other
+    // route trying to use it is almost certainly a latent auth bypass.
+    if (ep.meta?.bearerKind === 'oauth' && !oauthSelfAuthAllowlist.has(`${ep.method} ${ep.path}`)) {
+      throw Errors.badRequest(
+        `Endpoint ${ep.method} ${ep.path} sets bearerKind:'oauth' but is not an approved self-auth OAuth protocol route.`,
+      );
+    }
+  }
+
+  // Resolve cookie config once at startup so all HTTP entry points share names.
+  const cookies = resolveCookieConfig(config.cookies);
+
+  // Build the framework-agnostic HTTP auxiliary closures upfront. `handleRequest`
+  // and `call` both get bound after the instance is constructed because
+  // they need the assembled `Fortress` object (route table is built from
+  // `endpoints`; `call` delegates to `handleRequest`).
+  let routeManifest: RouteManifestEntry[] | undefined;
+
+  const instance: Fortress<InferPlugins<T>, TypedCall<T>> = {
+    auth,
+    iam,
+    plugins: pluginMethods as InferPlugins<T>,
+    call: {} as TypedCall<T>,
+    config,
+    endpoints,
+    get manifest(): RouteManifestEntry[] {
+      routeManifest ??= buildRouteManifest(this as Fortress);
+      return routeManifest;
+    },
+    cookies,
+    logger,
+    telemetry,
+    handleRequest: undefined as unknown as (request: Request) => Promise<Response>,
+    runPluginMiddleware: (phase, ctx): Promise<void> => runPluginMiddlewareFn(plugins, config, phase, ctx),
+    extractAccessToken: (request: Request): string | null => extractAccessTokenFn(request, cookies),
+    resolvePrincipal: (request: Request): Promise<ResolvedPrincipal | null> =>
+      resolveRequestPrincipalFn(instance as Fortress, request),
+    serializeAuthCookies: (payload: AuthCookiePayload): string[] =>
+      serializeAuthCookiesFn(payload, cookies, {
+        access: config.jwt.accessTokenExpirySeconds ?? 900,
+        refresh: config.jwt.refreshTokenExpirySeconds ?? 604_800,
+      }),
+    async migrate(opts?: MigrateOptions): Promise<MigrateResult> {
+      // Fortress migrations first — app schemas commonly FK to fortress
+      // tables, so this order is the safe default. Unwrap the instrumented
+      // adapter so `db.dialect` reflects the underlying engine.
+      const fortressResult = await migrateUp(db, opts?.dialect, opts?.targetVersion);
+      let appRan = false;
+      if (opts?.migrateApp) {
+        await opts.migrateApp();
+        appRan = true;
+      }
+      return { fortress: fortressResult, appRan };
+    },
+    syncPermissionsFromManifest(opts?: PermissionSyncOptions): Promise<PermissionSyncResult> {
+      return runPermissionSync(iam, opts?.endpoints ?? instance.endpoints, opts);
+    },
+    toOpenAPI(opts?: FortressToOpenAPIOptions): OpenAPISpec {
+      return endpointsToOpenAPI(opts?.endpoints ?? instance.endpoints, opts);
+    },
+  };
+
+  instance.handleRequest = buildHandleRequest(instance as Fortress);
+
+  // Assemble the typed call map. Core auth/IAM handlers come first; plugin
+  // routes are layered on top so they can override a core handler that
+  // shares a key (matches the `endpointMap` dedup order).
+  const callEndpoints: Record<string, EndpointDefinition> = {
+    ...(authEndpoints as unknown as Record<string, EndpointDefinition>),
+    ...(iamEndpoints as unknown as Record<string, EndpointDefinition>),
+  };
+  const callOwners = new Map<string, string>();
+  for (const key of Object.keys(callEndpoints))
+    callOwners.set(key, 'core');
+  for (const plugin of plugins) {
+    // Top-level `routes` are metadata for manifest/OpenAPI/protected host
+    // routes; they do not come with plugin methods, so exposing them through
+    // `fortress.call.*` would create a runtime `NOT_FOUND` footgun. If a
+    // consumer wants typed in-process callables for custom routes, use a real
+    // plugin that supplies both `routes` and matching `methods`.
+    if (plugin.name === HOST_ROUTES_PLUGIN_NAME)
+      continue;
+    for (const [key, endpoint] of Object.entries(plugin.routes ?? {}) as [string, EndpointDefinition][]) {
+      const owner = callOwners.get(key);
+      if (owner && owner !== 'core') {
+        throw Errors.badRequest(
+          `Duplicate fortress.call key "${key}" declared by plugins "${owner}" and "${plugin.name}"`,
+        );
+      }
+      callEndpoints[key] = endpoint;
+      callOwners.set(key, plugin.name);
+    }
+  }
+  instance.call = buildCall(instance as Fortress, callEndpoints) as TypedCall<T>;
+
+  return instance;
+}