@bajustone/fortress 1.0.0-rc.1

package/src/core/http/outbound.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared client for fortress's *outbound* HTTP — OAuth token exchange, OIDC
+ * discovery, provider userinfo, GitHub profile, and the HIBP breach check.
+ *
+ * Built on `@bajustone/fetcher` so every outbound call gets:
+ *   - a **timeout** (native `fetch` has none, so a hung upstream would block a
+ *     login/registration indefinitely);
+ *   - the **never-throws** contract — transport failures (network/timeout)
+ *     resolve to a `Response` with `ok === false` rather than rejecting, so
+ *     call sites branch on `.ok`/`.result()` instead of try/catch;
+ *   - optional **schema-validated parsing** via a per-call `responseSchema`.
+ *
+ * Always invoked with absolute URLs, so `baseUrl` is unused (an absolute path
+ * overrides it in fetcher).
+ */
+import type { Middleware } from '@bajustone/fetcher';
+import { createFetch } from '@bajustone/fetcher';
+
+/** Default outbound timeout (ms), covering headers and full body consumption. */
+export const OUTBOUND_TIMEOUT_MS = 10_000;
+
+function requestWithSignal(request: Request, signal: AbortSignal): Request {
+  return new Request(request, request.body
+    ? { signal, body: request.body, duplex: 'half' } as RequestInit
+    : { signal });
+}
+
+/**
+ * Keep the deadline alive until the response body is consumed. A fetch-only
+ * timeout stops at response headers, allowing a peer to dribble the body
+ * forever after returning an immediate 200 response.
+ */
+function fullExchangeTimeout(ms: number): Middleware {
+  return async (request, next) => {
+    const controller = new AbortController();
+    const userSignal = request.signal;
+    const abortFromUser = (): void => controller.abort(userSignal.reason);
+    if (userSignal.aborted)
+      abortFromUser();
+    else
+      userSignal.addEventListener('abort', abortFromUser, { once: true });
+
+    const timer = setTimeout(() => {
+      controller.abort(new DOMException(`Request timed out after ${ms}ms`, 'TimeoutError'));
+    }, ms);
+    let cleaned = false;
+    const cleanup = (): void => {
+      if (cleaned)
+        return;
+      cleaned = true;
+      clearTimeout(timer);
+      userSignal.removeEventListener('abort', abortFromUser);
+    };
+
+    try {
+      const response = await next(requestWithSignal(request, controller.signal));
+      if (!response.body) {
+        cleanup();
+        return response;
+      }
+
+      const reader = response.body.getReader();
+      const body = new ReadableStream<Uint8Array>({
+        async pull(streamController) {
+          try {
+            const chunk = await reader.read();
+            if (chunk.done) {
+              cleanup();
+              streamController.close();
+            }
+            else {
+              streamController.enqueue(chunk.value);
+            }
+          }
+          catch (error) {
+            cleanup();
+            streamController.error(error);
+          }
+        },
+        async cancel(reason) {
+          cleanup();
+          await reader.cancel(reason);
+        },
+      });
+
+      return new Response(body, {
+        headers: response.headers,
+        status: response.status,
+        statusText: response.statusText,
+      });
+    }
+    catch (error) {
+      cleanup();
+      throw error;
+    }
+  };
+}
+
+/** Create an outbound client whose deadline covers headers and response body. */
+export function createOutboundClient(timeoutMs: number = OUTBOUND_TIMEOUT_MS): ReturnType<typeof createFetch> {
+  return createFetch({ baseUrl: '', middleware: [fullExchangeTimeout(timeoutMs)] });
+}
+
+/** Shared fetcher client for Fortress outbound HTTP. */
+export const outboundClient = createOutboundClient();

package/src/core/http/plugin-middleware.ts

@@ -0,0 +1,67 @@
+/**
+ * Framework-agnostic plugin middleware execution for `fortress.handleRequest`
+ * and adapter handles.
+ *
+ * Wraps {@link executePluginMiddleware} from `plugin-runner.ts` so the
+ * caller can hand it a {@link PluginRequestContext} (a duck-typed object with
+ * `fortressUserId` and friends) instead of a framework-specific Hono context
+ * or Express request.
+ *
+ * Plugins that short-circuit do so by throwing a {@link FortressError}; the
+ * caller is expected to wrap this in a try/catch and translate via
+ * `errorToResponse`.
+ */
+
+import type { FortressConfig } from '../config';
+import type { FortressPlugin, MiddlewareDefinition, PluginContext } from '../plugin';
+import type { Subject, TokenClaims } from '../types';
+import { executePluginMiddleware } from '../plugin-runner';
+
+/**
+ * Object passed to plugin middleware as the "request" argument when running
+ * inside `fortress.handleRequest` or any framework adapter that delegates to
+ * core. Carries the web-standard `Request` plus the resolved auth context.
+ *
+ * The shape is intentionally compatible with the existing admin-plugin
+ * `extractUserId` helper, which checks `'fortressUserId' in request`.
+ */
+export interface PluginRequestContext {
+  request: Request;
+  /**
+   * The resolved principal for this request, if any. Populated from a
+   * plugin `resolvePrincipal` hit or the JWT fallback. Plugins preferring
+   * subject-level identity (non-USER principals) should read this instead
+   * of `fortressUserId`.
+   */
+  fortressSubject?: Subject;
+  /**
+   * Convenience alias — set only when the resolved subject is a `USER`.
+   * Non-USER principals (e.g. `SERVICE_ACCOUNT` via api-key) leave this
+   * field undefined; consumers should fall back to `fortressSubject`.
+   */
+  fortressUserId?: string;
+  fortressClaims?: TokenClaims;
+  /** Credential-level narrowing scopes (for example API-key scopes), if any. */
+  fortressScopes?: string[] | null;
+}
+
+/**
+ * Run all plugin middleware for the given phase against a request path.
+ *
+ * The path is extracted from `ctx.request.url.pathname` so plugins can
+ * filter by path pattern. Errors thrown by plugin handlers propagate to the
+ * caller.
+ */
+export async function runPluginMiddleware(
+  plugins: readonly FortressPlugin[],
+  config: FortressConfig,
+  phase: MiddlewareDefinition['position'],
+  ctx: PluginRequestContext,
+): Promise<void> {
+  if (plugins.length === 0)
+    return;
+
+  const pluginCtx: PluginContext = { db: config.database, config };
+  const path = new URL(ctx.request.url).pathname;
+  await executePluginMiddleware(plugins, phase, path, pluginCtx, ctx);
+}

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

@@ -0,0 +1,345 @@
+/**
+ * Unit tests for the shared request-principal resolver
+ * (`src/core/http/principal.ts`). Exercises the plugin-chain + JWT
+ * fallback pipeline that both `handleRequest` and the adapter user-route
+ * middleware delegate to.
+ */
+
+import type { Fortress } from '../fortress';
+import type { FortressPlugin } from '../plugin';
+import type { Subject } from '../types';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { apiKey } from '../../plugins/api-key';
+import { createTestAdapter } from '../../testing';
+import { createFortress } from '../fortress';
+import { resolveRequestPrincipal, tryPluginPrincipal } from './principal';
+
+const SECRET = 'principal-resolver-test-secret-32char!';
+
+async function makeFortressWithApiKey() {
+  const fortress: Fortress<any> = createFortress({
+    jwt: { key: SECRET },
+    database: createTestAdapter(),
+    plugins: [apiKey({ prefix: 'test' })],
+  });
+  const user = await fortress.auth.createUser({
+    email: 'u@example.com',
+    name: 'User',
+    password: 'password-123456',
+  });
+  const sa = await fortress.iam.createServiceAccount({ name: 'ci-bot' });
+  const userKey = await fortress.plugins['api-key'].createKey({
+    subject: { type: 'USER', id: user.id },
+    name: 'user-key',
+  });
+  const saKey = await fortress.plugins['api-key'].createKey({
+    subject: { type: 'SERVICE_ACCOUNT', id: sa.id },
+    name: 'sa-key',
+  });
+  return { fortress, user, sa, userKey: userKey.key, saKey: saKey.key };
+}
+
+describe('tryPluginPrincipal', () => {
+  it('returns null when no plugin is registered', async () => {
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+    });
+    const result = await tryPluginPrincipal(
+      fortress,
+      new Request('http://localhost/api/anything'),
+    );
+    expect(result).toBeNull();
+  });
+
+  it('returns null when a plugin is registered but no credential is present', async () => {
+    const { fortress } = await makeFortressWithApiKey();
+    const result = await tryPluginPrincipal(
+      fortress,
+      new Request('http://localhost/api/anything'),
+    );
+    expect(result).toBeNull();
+  });
+
+  it('resolves a USER subject from Authorization: ApiKey', async () => {
+    const { fortress, user, userKey } = await makeFortressWithApiKey();
+    const result = await tryPluginPrincipal(
+      fortress,
+      new Request('http://localhost/api/anything', {
+        headers: { authorization: `ApiKey ${userKey}` },
+      }),
+    );
+    expect(result).not.toBeNull();
+    expect(result?.subject).toEqual({ type: 'USER', id: user.id });
+  });
+
+  it('resolves a SERVICE_ACCOUNT subject from X-API-Key', async () => {
+    const { fortress, sa, saKey } = await makeFortressWithApiKey();
+    const result = await tryPluginPrincipal(
+      fortress,
+      new Request('http://localhost/api/anything', {
+        headers: { 'x-api-key': saKey },
+      }),
+    );
+    expect(result).not.toBeNull();
+    expect(result?.subject).toEqual({ type: 'SERVICE_ACCOUNT', id: sa.id });
+  });
+
+  it('returns null for an unknown api-key', async () => {
+    const { fortress } = await makeFortressWithApiKey();
+    const result = await tryPluginPrincipal(
+      fortress,
+      new Request('http://localhost/api/anything', {
+        headers: { authorization: 'ApiKey test_sk_not-a-real-key' },
+      }),
+    );
+    expect(result).toBeNull();
+  });
+
+  it('walks plugins in registration order — first non-null wins', async () => {
+    // Two synthetic resolving plugins: only the second would return non-null
+    // if the first deferred. Assert the first-registered plugin wins when
+    // both would match.
+    const calls: string[] = [];
+    const firstHit: FortressPlugin = {
+      name: 'first',
+      resolvePrincipal: async () => {
+        calls.push('first');
+        return { subject: { type: 'USER', id: '100' } };
+      },
+    };
+    const secondHit: FortressPlugin = {
+      name: 'second',
+      resolvePrincipal: async () => {
+        calls.push('second');
+        return { subject: { type: 'USER', id: '200' } };
+      },
+    };
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      plugins: [firstHit, secondHit],
+    });
+    const result = await tryPluginPrincipal(
+      fortress,
+      new Request('http://localhost/api/anything'),
+    );
+    expect(result?.subject).toEqual({ type: 'USER', id: '100' });
+    expect(calls).toEqual(['first']); // second never ran
+  });
+
+  it('defers to the next plugin when a resolver returns null', async () => {
+    const calls: string[] = [];
+    const firstDefers: FortressPlugin = {
+      name: 'first',
+      resolvePrincipal: async () => {
+        calls.push('first');
+        return null;
+      },
+    };
+    const secondHit: FortressPlugin = {
+      name: 'second',
+      resolvePrincipal: async () => {
+        calls.push('second');
+        return { subject: { type: 'SERVICE_ACCOUNT', id: '42' } };
+      },
+    };
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      plugins: [firstDefers, secondHit],
+    });
+    const result = await tryPluginPrincipal(
+      fortress,
+      new Request('http://localhost/api/anything'),
+    );
+    expect(result?.subject).toEqual({ type: 'SERVICE_ACCOUNT', id: '42' });
+    expect(calls).toEqual(['first', 'second']);
+  });
+
+  it('skips plugins that do not implement resolvePrincipal', async () => {
+    const unrelated: FortressPlugin = { name: 'unrelated' };
+    const hit: FortressPlugin = {
+      name: 'hit',
+      resolvePrincipal: async () => ({ subject: { type: 'USER', id: '7' } }),
+    };
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      plugins: [unrelated, hit],
+    });
+    const result = await tryPluginPrincipal(
+      fortress,
+      new Request('http://localhost/'),
+    );
+    expect(result?.subject).toEqual({ type: 'USER', id: '7' });
+  });
+});
+
+describe('resolveRequestPrincipal', () => {
+  let fortress: Awaited<ReturnType<typeof makeFortressWithApiKey>>['fortress'];
+  let user: Awaited<ReturnType<typeof makeFortressWithApiKey>>['user'];
+  let sa: Awaited<ReturnType<typeof makeFortressWithApiKey>>['sa'];
+  let userKey: string;
+  let saKey: string;
+  let validAccessToken: string;
+
+  beforeEach(async () => {
+    const setup = await makeFortressWithApiKey();
+    fortress = setup.fortress;
+    user = setup.user;
+    sa = setup.sa;
+    userKey = setup.userKey;
+    saKey = setup.saKey;
+
+    const login = await fortress.auth.login('u@example.com', 'password-123456');
+    if (login.status !== 'success')
+      throw new Error('login should succeed');
+    validAccessToken = login.accessToken;
+  });
+
+  it('returns null when no credential is present', async () => {
+    const result = await resolveRequestPrincipal(
+      fortress,
+      new Request('http://localhost/api'),
+    );
+    expect(result).toBeNull();
+  });
+
+  it('resolves via the plugin chain BEFORE trying the JWT', async () => {
+    // Present BOTH a valid JWT and an api-key. The plugin-resolved principal
+    // should win (this matches handle-request semantics and is the whole
+    // reason we wired the chain into user-route middleware).
+    const result = await resolveRequestPrincipal(
+      fortress,
+      new Request('http://localhost/api', {
+        headers: {
+          'authorization': `Bearer ${validAccessToken}`,
+          'x-api-key': saKey,
+        },
+      }),
+    );
+    expect(result?.subject).toEqual({ type: 'SERVICE_ACCOUNT', id: sa.id });
+  });
+
+  it('falls back to JWT bearer when no plugin matches', async () => {
+    const result = await resolveRequestPrincipal(
+      fortress,
+      new Request('http://localhost/api', {
+        headers: { authorization: `Bearer ${validAccessToken}` },
+      }),
+    );
+    expect(result?.subject).toEqual({ type: 'USER', id: user.id });
+    expect(result?.claims).toBeDefined();
+    expect(result?.claims?.sub).toBe(user.id);
+  });
+
+  it('resolves a USER api-key via the plugin chain', async () => {
+    const result = await resolveRequestPrincipal(
+      fortress,
+      new Request('http://localhost/api', {
+        headers: { authorization: `ApiKey ${userKey}` },
+      }),
+    );
+    expect(result?.subject).toEqual({ type: 'USER', id: user.id });
+    // api-key path doesn't carry JWT claims
+    expect(result?.claims).toBeUndefined();
+  });
+
+  it('returns null (does NOT throw) for an invalid JWT', async () => {
+    const result = await resolveRequestPrincipal(
+      fortress,
+      new Request('http://localhost/api', {
+        headers: { authorization: 'Bearer definitely-not-a-jwt' },
+      }),
+    );
+    expect(result).toBeNull();
+  });
+
+  it('returns null (does NOT throw) for a malformed JWT with tampered signature', async () => {
+    // Take a real JWT and flip the FIRST signature char. Mangling the last
+    // base64url char is non-deterministic — the trailing char only carries a
+    // few significant bits, so a different char can decode to the same
+    // signature bytes (and occasionally the original char already is the
+    // replacement). A mid-segment char carries full bits, so flipping it
+    // always invalidates the signature.
+    const parts = validAccessToken.split('.');
+    const sig = parts[2];
+    parts[2] = (sig[0] === 'A' ? 'B' : 'A') + sig.slice(1);
+    const bad = parts.join('.');
+    const result = await resolveRequestPrincipal(
+      fortress,
+      new Request('http://localhost/api', {
+        headers: { authorization: `Bearer ${bad}` },
+      }),
+    );
+    expect(result).toBeNull();
+  });
+
+  it('reads the access token from the configured cookie as JWT fallback', async () => {
+    const result = await resolveRequestPrincipal(
+      fortress,
+      new Request('http://localhost/api', {
+        headers: {
+          cookie: `${fortress.cookies.accessName}=${validAccessToken}`,
+        },
+      }),
+    );
+    expect(result?.subject).toEqual({ type: 'USER', id: user.id });
+  });
+
+  it('resolves a SERVICE_ACCOUNT principal even though it has no USER analogue', async () => {
+    const result = await resolveRequestPrincipal(
+      fortress,
+      new Request('http://localhost/api', {
+        headers: { 'x-api-key': saKey },
+      }),
+    );
+    expect(result?.subject.type).toBe('SERVICE_ACCOUNT');
+    expect(result?.subject.id).toBe(sa.id);
+  });
+});
+
+describe('fortress.resolvePrincipal (instance method)', () => {
+  it('exposes the same resolver as the module-level helper', async () => {
+    const { fortress, userKey } = await makeFortressWithApiKey();
+    const result = await fortress.resolvePrincipal(
+      new Request('http://localhost/', {
+        headers: { authorization: `ApiKey ${userKey}` },
+      }),
+    );
+    expect(result?.subject.type).toBe('USER');
+  });
+
+  it('returns null when no credential is present', async () => {
+    const { fortress } = await makeFortressWithApiKey();
+    const result = await fortress.resolvePrincipal(
+      new Request('http://localhost/'),
+    );
+    expect(result).toBeNull();
+  });
+});
+
+// Guard against the regression where plugins list is passed via `unknown` and
+// silently loses its type. The resolver accepts any Subject shape back from a
+// plugin and threads it through unchanged.
+describe('resolveRequestPrincipal — subject shape pass-through', () => {
+  it('preserves arbitrary SubjectType values from plugins', async () => {
+    const custom: FortressPlugin = {
+      name: 'group-resolver',
+      resolvePrincipal: async (): Promise<{ subject: Subject }> => ({
+        subject: { type: 'GROUP', id: '99' },
+      }),
+    };
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      plugins: [custom],
+    });
+    const result = await resolveRequestPrincipal(
+      fortress,
+      new Request('http://localhost/'),
+    );
+    expect(result?.subject).toEqual({ type: 'GROUP', id: '99' });
+  });
+});

package/src/core/http/principal.ts

@@ -0,0 +1,86 @@
+/**
+ * Shared principal resolution for `fortress.handleRequest` and user-route
+ * adapters (Hono / Express / SvelteKit).
+ *
+ * Plugins that register a `resolvePrincipal` capability (e.g. `api-key`) are
+ * tried in registration order; the first non-null result wins. If no plugin
+ * resolves the request, a JWT bearer token is attempted as a fallback.
+ *
+ * Two variants are exported:
+ *
+ * - {@link tryPluginPrincipal} — only walks the plugin chain. Used by
+ *   `handle-request.ts`, which needs to decide whether to enforce the JWT
+ *   fallback based on the endpoint's `security` metadata.
+ * - {@link resolveRequestPrincipal} — plugin chain + non-throwing JWT
+ *   fallback. Used by adapter user-route middleware so that API keys and
+ *   cookies/bearer tokens authenticate uniformly on *any* route, not just
+ *   Fortress-owned routes.
+ */
+
+import type { Fortress } from '../fortress';
+import type { Subject, TokenClaims } from '../types';
+
+/** Result of a successful principal resolution. */
+export interface ResolvedPrincipal {
+  subject: Subject;
+  claims?: TokenClaims;
+  /** Credential-level narrowing scopes (e.g. API-key scopes). null/undefined = unscoped. */
+  scopes?: string[] | null;
+}
+
+/**
+ * Walk the `resolvePrincipal` plugin chain. Returns the first non-null
+ * result, or null if every plugin deferred.
+ */
+export async function tryPluginPrincipal(
+  fortress: Fortress,
+  request: Request,
+): Promise<ResolvedPrincipal | null> {
+  const plugins = fortress.config.plugins ?? [];
+  for (const plugin of plugins) {
+    if (!plugin.resolvePrincipal)
+      continue;
+    const resolved = await plugin.resolvePrincipal(request, {
+      db: fortress.config.database,
+      config: fortress.config,
+      auth: fortress.auth,
+      iam: fortress.iam,
+    });
+    if (resolved)
+      return { subject: resolved.subject, claims: resolved.claims, scopes: resolved.scopes };
+  }
+  return null;
+}
+
+/**
+ * Resolve a request principal by trying the plugin chain first, then falling
+ * back to the configured JWT bearer token (cookie-first, `Authorization:
+ * Bearer` second).
+ *
+ * Non-throwing: returns `null` if no credential is present **or** the JWT
+ * fails verification. Adapter user-route middleware calls this so RBAC can
+ * decide how to handle the missing principal (401 for protected routes,
+ * anonymous pass for public ones).
+ */
+export async function resolveRequestPrincipal(
+  fortress: Fortress,
+  request: Request,
+): Promise<ResolvedPrincipal | null> {
+  const plugin = await tryPluginPrincipal(fortress, request);
+  if (plugin)
+    return plugin;
+
+  const token = fortress.extractAccessToken(request);
+  if (!token)
+    return null;
+  try {
+    const claims = await fortress.auth.verifyToken(token);
+    return {
+      subject: { type: claims.subjectType, id: claims.sub },
+      claims,
+    };
+  }
+  catch {
+    return null;
+  }
+}