@bajustone/fortress 1.0.0-rc.1

package/src/core/http/handle-request.ts

@@ -0,0 +1,354 @@
+/**
+ * Framework-agnostic HTTP entry point: `fortress.handleRequest(request)`.
+ *
+ * Composes route matching → plugin `before-auth` → token verification →
+ * plugin `after-auth` → fortress-RBAC default-deny → plugin `after-rbac` →
+ * validation → endpoint dispatch → cookie attachment → JSON response.
+ *
+ * Adapters (Hono / Express / SvelteKit) detect Fortress-managed paths and
+ * delegate to this function with the raw `Request`. The returned `Response`
+ * is web-standard and can be returned directly from any framework that
+ * supports `Response`.
+ */
+
+import type { Fortress } from '../fortress';
+import type { Subject, TokenClaims } from '../types';
+import type { RouteEntry } from './match';
+import { resolveCookieConfig } from '../config';
+import { Errors, FortressError } from '../errors';
+import { coerceBySchema, validateRequest } from '../validation';
+import { clearAuthCookies, serializeAuthCookies } from './cookie-serialize';
+import { enforceCsrf, resolveCsrfConfig } from './csrf';
+import { dispatchEndpoint } from './dispatch';
+import { errorToResponse, withCookies } from './error-response';
+import {
+  enforceFortressPermission,
+  getPluginPathPrefixes,
+  isFortressPath,
+} from './fortress-rbac';
+import { buildRouteTable, matchRoute } from './match';
+import { runPluginMiddleware } from './plugin-middleware';
+import { tryPluginPrincipal } from './principal';
+import { extractAccessToken } from './token-extraction';
+
+/**
+ * Build the request handler closure for a Fortress instance. Called once
+ * during `createFortress` and exposed as `fortress.handleRequest`.
+ *
+ * The returned function is `async (request: Request) => Promise<Response>`.
+ * It owns the route table, the resolved cookie config, and the cached
+ * plugin path prefixes — building these once at startup avoids per-request
+ * recomputation.
+ */
+export function buildHandleRequest(
+  fortress: Fortress,
+): (request: Request) => Promise<Response> {
+  const mountedRoutes = new Set(
+    fortress.manifest
+      .filter(route => route.mounted)
+      .map(route => `${route.method.toUpperCase()} ${route.path}`),
+  );
+  const routeTable = buildRouteTable(
+    fortress.endpoints.filter(endpoint => mountedRoutes.has(`${endpoint.method.toUpperCase()} ${endpoint.path}`)),
+  );
+  const cookieConfig = resolveCookieConfig(fortress.config.cookies);
+  // H5: pipeline CSRF check resolved once at startup so per-request cost
+  // is just header / cookie inspection.
+  const csrfConfig = resolveCsrfConfig(fortress.config.csrf);
+  const plugins = fortress.config.plugins ?? [];
+  const pluginPathPrefixes = getPluginPathPrefixes(plugins);
+  const startActiveSpan = fortress.telemetry.tracer.startActiveSpan?.bind(fortress.telemetry.tracer)
+    ?? (async (name, attributes, callback) => callback(
+      fortress.telemetry.tracer.startSpan(name, attributes),
+    ));
+
+  return async function handleRequest(request: Request): Promise<Response> {
+    // Keep the request span active for the entire async pipeline so database,
+    // IAM, and plugin spans inherit it through the configured telemetry
+    // provider. The no-op provider invokes this callback without allocation.
+    return startActiveSpan(
+      'fortress.handleRequest',
+      { 'http.method': request.method },
+      async (span) => {
+        let response: Response | undefined;
+        try {
+          const url = new URL(request.url);
+          const pathname = url.pathname;
+
+          // 1. Plugin before-auth middleware (rate limit, audit log, etc.)
+          await runPluginMiddleware(plugins, fortress.config, 'before-auth', { request });
+
+          // 1a. H5 — CSRF check. Runs before token verification so a malicious
+          //     cross-site POST can't trigger any auth lookup work either. The
+          //     check is a no-op for safe methods, bearer/API-key flows, and
+          //     deployments that opt out.
+          enforceCsrf(request, pathname, csrfConfig, cookieConfig);
+
+          // 2. Match path + method to an endpoint
+          const matched = matchRoute(routeTable, request.method, pathname);
+          if (!matched) {
+            // Only return 404 for fortress-owned paths; otherwise the caller
+            // (an adapter) might want to fall through to its own router.
+            if (isFortressPath(pathname, pluginPathPrefixes)) {
+              throw Errors.notFound(`No endpoint matches ${request.method} ${pathname}`);
+            }
+            // Non-fortress path with no match — also a 404 from this entry point
+            throw Errors.notFound(`No endpoint matches ${request.method} ${pathname}`);
+          }
+          const { endpoint, params } = matched;
+          // Upgrade span attributes now that we know the matched route.
+          // `endpoint.path` is parameterized (e.g. `/iam/roles/:id`) so it's
+          // low-cardinality and safe to put on a span/metric attribute.
+          span.setAttribute('http.route', endpoint.path);
+          span.setAttribute('fortress.handler', endpoint.handler);
+
+          // 3. Principal resolution. Three paths, tried in order:
+          //
+          //    3a. Plugin-backed credential resolvers (api-key, future
+          //        OAuth client_credentials, future mTLS). First plugin to
+          //        return non-null wins — its subject + optional claims
+          //        become the request principal.
+          //    3b. JWT bearer fallback. Used when no plugin resolves the
+          //        request and the endpoint declared `security: 'bearer'`.
+          //    3c. Routes that declare `meta.bearerKind: 'oauth'` (the OAuth
+          //        protocol endpoints — token, userinfo, introspect, revoke,
+          //        authorize, jwks, discovery) self-parse their bearer
+          //        (which is an OAuth access token, not a Fortress JWT) so
+          //        we skip both the resolver chain and the JWT check here.
+          //        Other `/oauth/*` routes — e.g. the consent-flow endpoints
+          //        `/oauth/flows/:flowId{,/approve,/deny}` — default to
+          //        `bearerKind: 'jwt'` and go through the normal auth
+          //        pipeline so a host app SPA can call them with a Fortress
+          //        JWT and have RBAC honoured.
+          let subject: Subject | undefined;
+          let userId: string | undefined;
+          let claims: TokenClaims | undefined;
+          let scopes: string[] | null | undefined;
+          const selfManagedBearer = endpoint.meta?.bearerKind === 'oauth';
+
+          if (!selfManagedBearer) {
+            const resolved = await tryPluginPrincipal(fortress, request);
+            if (resolved) {
+              subject = resolved.subject;
+              claims = resolved.claims;
+              scopes = resolved.scopes;
+            }
+          }
+
+          const requiresBearer = !selfManagedBearer
+            && ((endpoint.meta?.security?.includes('bearer') ?? false) || !!endpoint.meta?.permission);
+          if (!subject && requiresBearer) {
+            const token = extractAccessToken(request, cookieConfig);
+            if (!token)
+              throw Errors.unauthorized('Missing access token');
+            try {
+              claims = await fortress.auth.verifyToken(token);
+              subject = { type: claims.subjectType, id: claims.sub };
+            }
+            catch (err) {
+              if (err instanceof FortressError)
+                throw err;
+              throw Errors.unauthorized('Invalid access token');
+            }
+          }
+
+          // Convenience alias: downstream code that only needs `userId` (adapters,
+          // plugin middleware) still works for USER subjects. Non-user principals
+          // leave `userId` undefined, which is correct — they'd be hitting routes
+          // that RBAC-check via `subject` now.
+          if (subject?.type === 'USER')
+            userId = subject.id;
+
+          if (subject) {
+            span.setAttribute('fortress.subject_type', subject.type);
+          }
+
+          // 4. Plugin after-auth middleware
+          await runPluginMiddleware(plugins, fortress.config, 'after-auth', {
+            request,
+            fortressSubject: subject,
+            fortressUserId: userId,
+            fortressClaims: claims,
+            fortressScopes: scopes,
+          });
+
+          // 5. Fortress-managed default-deny RBAC. Routes flagged
+          //    `bearerKind: 'oauth'` self-authenticate inside their handlers
+          //    (the bearer is an OAuth token, not a JWT) so they're exempt
+          //    from the IAM check too.
+          if (!selfManagedBearer) {
+            await enforceFortressPermission(endpoint, subject, {
+              checkPermission: (subj, resource, action, credentialScopes): Promise<boolean> =>
+                fortress.iam.checkPermission(subj, resource, action, { credentialScopes }),
+            }, scopes);
+          }
+
+          // 6. Plugin after-rbac middleware
+          await runPluginMiddleware(plugins, fortress.config, 'after-rbac', {
+            request,
+            fortressSubject: subject,
+            fortressUserId: userId,
+            fortressClaims: claims,
+            fortressScopes: scopes,
+          });
+
+          // 7. Body parse + validation. Validation reads the body via clone()
+          //    so dispatch can re-read it. We sniff the content-type to know
+          //    whether validateRequest can parse JSON. Skipped for routes
+          //    flagged `bearerKind: 'oauth'` — their bodies are
+          //    `application/x-www-form-urlencoded` and the OAuth dispatcher
+          //    does its own parsing/validation per RFC 6749.
+          if (!selfManagedBearer) {
+            let parsedBody: unknown;
+            if (
+              request.method !== 'GET'
+              && request.method !== 'HEAD'
+              && (request.headers.get('content-type') ?? '').includes('json')
+            ) {
+              parsedBody = await request.clone().json().catch(() => undefined);
+            }
+            const query = Object.fromEntries(url.searchParams);
+            // URL-sourced data is always strings. Coerce query/params to the
+            // types declared in the endpoint's JSON Schema before validation
+            // so `:id`/`?limit=2` don't trip integer/number/boolean checks.
+            const coercedQuery = coerceBySchema(endpoint.input?.query, query);
+            const coercedParams = coerceBySchema(endpoint.input?.params, params);
+            await validateRequest(endpoint.input, { body: parsedBody, query: coercedQuery, params: coercedParams });
+          }
+
+          // 8. Dispatch + serialize. Pass IP/UA from headers as RequestMeta so
+          //    auth handlers can stamp refresh tokens with their origin.
+          const meta = {
+            ipAddress:
+          request.headers.get('x-forwarded-for')
+          ?? request.headers.get('x-real-ip')
+          ?? undefined,
+            userAgent: request.headers.get('user-agent') ?? undefined,
+          };
+          const dispatched = await dispatchEndpoint(fortress, request, endpoint, params, {
+            subject,
+            userId,
+            claims,
+            scopes,
+            meta,
+          });
+
+          // 9. If the endpoint emitted an auth result, serialize cookies.
+          //    Detected by checking the response body for accessToken/refreshToken
+          //    fields. We avoid touching streamed/HTML responses.
+          const cookies = await maybeBuildAuthCookies(
+            endpoint.handler,
+            dispatched,
+            fortress,
+            request,
+          );
+          response = cookies.length > 0
+            ? withCookies(cookies.response, cookies.setCookies)
+            : dispatched;
+          return response;
+        }
+        catch (err) {
+          response = errorToResponse(err, fortress.logger);
+          span.recordException(err);
+          span.setStatus({
+            code: 'error',
+            message: err instanceof Error ? err.message : String(err),
+          });
+          return response;
+        }
+        finally {
+          if (response) {
+            span.setAttribute('http.status_code', response.status);
+            if (response.status >= 200 && response.status < 400) {
+              span.setStatus({ code: 'ok' });
+            }
+            else if (response.status >= 400) {
+              // 4xx/5xx without an exception (e.g. a FortressError already
+              // serialized). Mark the span as error so traces highlight it.
+              span.setStatus({
+                code: 'error',
+                message: `HTTP ${response.status}`,
+              });
+            }
+          }
+          span.end();
+        }
+      },
+    );
+  };
+}
+
+/**
+ * Inspect the dispatched response and, if it's an auth-issuing endpoint
+ * (`login`, `refresh`, `register-and-login`, etc.), build the matching
+ * `Set-Cookie` headers using the resolved cookie config.
+ *
+ * Returns the (possibly clone-replaced) response so callers can use
+ * `withCookies` against the body that was actually consumed.
+ */
+async function maybeBuildAuthCookies(
+  handler: string,
+  response: Response,
+  fortress: Fortress,
+  _request: Request,
+): Promise<{ setCookies: string[]; response: Response; length: number }> {
+  // Logout succeeds only after dispatch revokes the supplied refresh token;
+  // clear both browser credentials on that successful response.
+  if (handler === 'logout') {
+    if (response.status >= 400)
+      return { setCookies: [], response, length: 0 };
+    const setCookies = clearAuthCookies(resolveCookieConfig(fortress.config.cookies));
+    return { setCookies, response, length: setCookies.length };
+  }
+
+  // Only inspect successful auth-related handlers.
+  const isAuthIssuing = handler === 'login'
+    || handler === 'refresh'
+    || handler === 'impersonate'
+    || handler === 'verifyTwoFactor'
+    || handler === 'verifyMagicLink';
+  if (!isAuthIssuing)
+    return { setCookies: [], response, length: 0 };
+  if (response.status >= 400)
+    return { setCookies: [], response, length: 0 };
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!contentType.includes('json'))
+    return { setCookies: [], response, length: 0 };
+
+  // Read the JSON body once and reconstruct the response.
+  const bodyText = await response.clone().text();
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(bodyText);
+  }
+  catch {
+    return { setCookies: [], response, length: 0 };
+  }
+  const obj = parsed as { accessToken?: unknown; refreshToken?: unknown };
+  if (typeof obj?.accessToken !== 'string') {
+    return { setCookies: [], response, length: 0 };
+  }
+
+  const cookieConfig = resolveCookieConfig(fortress.config.cookies);
+  const accessExpiry = fortress.config.jwt.accessTokenExpirySeconds ?? 900;
+  const refreshExpiry = fortress.config.jwt.refreshTokenExpirySeconds ?? 604_800;
+  const setCookies = serializeAuthCookies(
+    {
+      accessToken: obj.accessToken,
+      refreshToken: typeof obj.refreshToken === 'string' ? obj.refreshToken : null,
+    },
+    cookieConfig,
+    { access: accessExpiry, refresh: refreshExpiry },
+  );
+
+  // Reconstruct the response from the consumed body so the caller can stream it.
+  const replaced = new Response(bodyText, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+  return { setCookies, response: replaced, length: setCookies.length };
+}
+
+// Re-export for adapter use
+export type { RouteEntry };

package/src/core/http/match.test.ts

@@ -0,0 +1,122 @@
+import type { EndpointDefinition } from '../endpoint';
+import { describe, expect, it } from 'vitest';
+import { buildRouteTable, matchRoute } from './match';
+
+function ep(method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH', path: string, handler: string): EndpointDefinition {
+  return {
+    method,
+    path,
+    handler,
+  };
+}
+
+describe('matchRoute', () => {
+  const table = buildRouteTable([
+    ep('GET', '/auth/me', 'me'),
+    ep('POST', '/auth/login', 'login'),
+    ep('GET', '/iam/roles', 'getRoles'),
+    ep('POST', '/iam/roles', 'createRole'),
+    ep('DELETE', '/iam/roles/:id', 'deleteRole'),
+    ep('GET', '/iam/users/:id/permissions', 'getUserPermissions'),
+    ep('DELETE', '/iam/groups/:id/users/:userId', 'removeUserFromGroup'),
+  ]);
+
+  it('matches an exact static route', () => {
+    const m = matchRoute(table, 'GET', '/auth/me');
+    expect(m?.endpoint.handler).toBe('me');
+    expect(m?.params).toEqual({});
+  });
+
+  it('respects HTTP method', () => {
+    expect(matchRoute(table, 'POST', '/auth/me')).toBeNull();
+    expect(matchRoute(table, 'GET', '/iam/roles')?.endpoint.handler).toBe('getRoles');
+    expect(matchRoute(table, 'POST', '/iam/roles')?.endpoint.handler).toBe('createRole');
+  });
+
+  it('extracts a single path param', () => {
+    const m = matchRoute(table, 'DELETE', '/iam/roles/42');
+    expect(m?.endpoint.handler).toBe('deleteRole');
+    expect(m?.params).toEqual({ id: '42' });
+  });
+
+  it('extracts multiple path params', () => {
+    const m = matchRoute(table, 'DELETE', '/iam/groups/3/users/7');
+    expect(m?.endpoint.handler).toBe('removeUserFromGroup');
+    expect(m?.params).toEqual({ id: '3', userId: '7' });
+  });
+
+  it('returns null when segment counts differ', () => {
+    expect(matchRoute(table, 'GET', '/iam/roles/extra')).toBeNull();
+  });
+
+  it('returns null when no route matches', () => {
+    expect(matchRoute(table, 'GET', '/nope')).toBeNull();
+  });
+
+  it('case-insensitive on method', () => {
+    expect(matchRoute(table, 'get', '/auth/me')?.endpoint.handler).toBe('me');
+  });
+
+  it('url-decodes path param values', () => {
+    const m = matchRoute(table, 'GET', '/iam/users/hello%20world/permissions');
+    expect(m?.params.id).toBe('hello world');
+  });
+
+  it.each([
+    [
+      [
+        ep('GET', '/users/:id', 'param'),
+        ep('GET', '/users/me', 'static'),
+      ],
+      'static',
+    ],
+    [
+      [
+        ep('GET', '/users/me', 'static'),
+        ep('GET', '/users/:id', 'param'),
+      ],
+      'static',
+    ],
+  ] as const)('prefers /users/me over /users/:id regardless of registration order', (routes, handler) => {
+    const m = matchRoute(buildRouteTable(routes), 'GET', '/users/me');
+    expect(m?.endpoint.handler).toBe(handler);
+    expect(m?.params).toEqual({});
+  });
+
+  it.each([
+    [
+      [
+        ep('GET', '/users/*', 'wildcard'),
+        ep('GET', '/users/:id', 'param'),
+        ep('GET', '/users/me', 'static'),
+      ],
+      'static',
+      '/users/me',
+      {},
+    ],
+    [
+      [
+        ep('GET', '/users/me', 'static'),
+        ep('GET', '/users/*', 'wildcard'),
+        ep('GET', '/users/:id', 'param'),
+      ],
+      'param',
+      '/users/alice',
+      { id: 'alice' },
+    ],
+    [
+      [
+        ep('GET', '/accounts/:id', 'param'),
+        ep('GET', '/users/me', 'static'),
+        ep('GET', '/users/*', 'wildcard'),
+      ],
+      'wildcard',
+      '/users/alice',
+      {},
+    ],
+  ] as const)('uses static, param, then wildcard precedence deterministically', (routes, handler, path, params) => {
+    const m = matchRoute(buildRouteTable(routes), 'GET', path);
+    expect(m?.endpoint.handler).toBe(handler);
+    expect(m?.params).toEqual(params);
+  });
+});

package/src/core/http/match.ts

@@ -0,0 +1,126 @@
+/**
+ * Endpoint route matching shared by dispatch and fortress-RBAC.
+ *
+ * Builds a path-segment table from {@link EndpointDefinition}s and matches
+ * incoming `(method, pathname)` pairs against it. Supports `:param` segments
+ * and returns extracted path parameters alongside the matched endpoint.
+ */
+
+import type { EndpointDefinition } from '../endpoint';
+
+/** Minimal route shape accepted by the matcher. */
+export interface RouteLike {
+  method: string;
+  path: string;
+}
+
+/** Route table entry built from an {@link EndpointDefinition} or manifest entry. */
+export interface RouteEntry<T extends RouteLike = EndpointDefinition> {
+  endpoint: T;
+  method: string;
+  segments: string[];
+  paramNames: string[];
+}
+
+/** Higher values are more specific when two routes have the same shape. */
+function segmentSpecificity(segment: string): number {
+  if (segment === '*')
+    return 0;
+  if (segment.startsWith(':'))
+    return 1;
+  return 2;
+}
+
+/** Successful match: the endpoint/route plus extracted path parameters. */
+export interface RouteMatch<T extends RouteLike = EndpointDefinition> {
+  endpoint: T;
+  params: Record<string, string>;
+}
+
+/** Normalize path separators so route and middleware matching share one form. */
+export function canonicalizePath(pathname: string): string {
+  const segments = pathname.split('/').filter(Boolean);
+  return segments.length === 0 ? '/' : `/${segments.join('/')}`;
+}
+
+/**
+ * Pre-build a route table from endpoint definitions. Adapters call this once
+ * at startup and hand the result to {@link matchRoute} on every request.
+ */
+export function buildRouteTable<T extends RouteLike>(endpoints: readonly T[]): RouteEntry<T>[] {
+  const table = endpoints.map((ep) => {
+    const segments = canonicalizePath(ep.path).split('/').filter(Boolean);
+    const paramNames: string[] = [];
+    for (const seg of segments) {
+      if (seg.startsWith(':'))
+        paramNames.push(seg.slice(1));
+    }
+    return {
+      endpoint: ep,
+      method: ep.method.toUpperCase(),
+      segments,
+      paramNames,
+    };
+  });
+
+  // Match specificity lexicographically so a static segment always wins over
+  // a parameter (and a parameter over a wildcard), independent of registration
+  // order. Stable sorting retains registration order for duplicate patterns.
+  return table
+    .map((route, index) => ({ route, index }))
+    .sort((a, b) => {
+      const length = Math.max(a.route.segments.length, b.route.segments.length);
+      for (let i = 0; i < length; i++) {
+        const difference = segmentSpecificity(b.route.segments[i] ?? '')
+          - segmentSpecificity(a.route.segments[i] ?? '');
+        if (difference !== 0)
+          return difference;
+      }
+      return a.index - b.index;
+    })
+    .map(({ route }) => route);
+}
+
+/**
+ * Find the endpoint that matches a `(method, pathname)` pair. Returns the
+ * matched endpoint and any extracted `:param` values, or `null` if nothing
+ * matches.
+ *
+ * Matching is segment-by-segment with literal segments compared verbatim,
+ * `:param` segments capturing into `params`, and `*` matching any one segment.
+ * Static segments take priority over params, which take priority over
+ * wildcards, independent of registration order.
+ */
+export function matchRoute<T extends RouteLike>(
+  table: RouteEntry<T>[],
+  method: string,
+  pathname: string,
+): RouteMatch<T> | null {
+  const upperMethod = method.toUpperCase();
+  const pathSegments = canonicalizePath(pathname).split('/').filter(Boolean);
+
+  for (const route of table) {
+    if (route.method !== upperMethod)
+      continue;
+    if (route.segments.length !== pathSegments.length)
+      continue;
+
+    const params: Record<string, string> = {};
+    let matched = true;
+    for (let i = 0; i < route.segments.length; i++) {
+      const routeSeg = route.segments[i];
+      const pathSeg = pathSegments[i];
+      if (routeSeg.startsWith(':')) {
+        params[routeSeg.slice(1)] = decodeURIComponent(pathSeg);
+      }
+      else if (routeSeg !== '*' && routeSeg !== pathSeg) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched)
+      return { endpoint: route.endpoint, params };
+  }
+
+  return null;
+}

package/src/core/http/outbound.test.ts

@@ -0,0 +1,34 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createOutboundClient } from './outbound';
+
+describe('outbound full-exchange timeout', () => {
+  afterEach(() => vi.restoreAllMocks());
+
+  it('keeps the deadline active while the response body is consumed', async () => {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+      const request = input as Request;
+      const body = new ReadableStream<Uint8Array>({
+        start(controller) {
+          request.signal.addEventListener('abort', () => {
+            controller.error(request.signal.reason);
+          }, { once: true });
+        },
+      });
+      return new Response(body, { status: 200 });
+    });
+
+    const client = createOutboundClient(20);
+    const response = await client.get('https://slow.example.test/data');
+
+    await expect(response.text()).rejects.toThrow(/timed out/i);
+  });
+
+  it('clears the deadline after a complete body is read', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue(new Response('{"ok":true}', { status: 200 }));
+    const client = createOutboundClient(100);
+
+    const response = await client.get('https://example.test/data');
+
+    await expect(response.json()).resolves.toEqual({ ok: true });
+  });
+});