@bajustone/fortress 1.0.0-rc.1

package/src/hono/middleware/auth.ts

@@ -0,0 +1,236 @@
+import type { Context, Env, MiddlewareHandler } from 'hono';
+import type { DatabaseAdapter } from '../../adapters/database';
+import type { Fortress } from '../../core/fortress';
+import type { PluginContext } from '../../core/plugin';
+import type { Subject, TokenClaims } from '../../core/types';
+import { FortressError } from '../../core/errors';
+import {
+  chainAdapterWrappers,
+  collectScopeRules,
+  wrapAdapterWithScopeRules,
+} from '../../core/plugin-runner';
+
+/**
+ * Hono `Variables` slot populated by the fortress auth middleware.
+ *
+ * `fortressSubject` is the authoritative principal — set for every
+ * authenticated request regardless of credential type (JWT, api-key, future
+ * OAuth client_credentials, mTLS, ...). `fortressUserId` is a convenience
+ * alias populated **only** when the subject is a `USER`; non-USER subjects
+ * (e.g. `SERVICE_ACCOUNT` via api-key) leave it `undefined`.
+ *
+ * Use {@link FortressEnv} to compose this with your own Hono env types
+ * without casts.
+ */
+export interface FortressVariables {
+  fortressSubject: Subject;
+  fortressUserId?: string;
+  fortressClaims?: TokenClaims;
+  fortressScopes?: string[] | null;
+  fortressDb: DatabaseAdapter;
+  fortressGetScopedDb: (model: string) => Promise<DatabaseAdapter>;
+}
+
+type ExtractVariables<E> = E extends { Variables: infer V } ? V : Record<string, never>;
+type ExtractBindings<E> = E extends { Bindings: infer B } ? B : Record<string, never>;
+
+/**
+ * Generic Hono env that composes {@link FortressVariables} with the host
+ * app's own env types. Use it directly (`Hono<FortressEnv>`) for a
+ * Fortress-only app, or parameterize with your existing env
+ * (`Hono<FortressEnv<MyEnv>>`) to add Fortress's variables on top of
+ * yours — no `Context<AppEnv>` ↔ `Context<FortressEnv>` casts.
+ *
+ * @example
+ * ```ts
+ * interface MyEnv {
+ *   Variables: { requestId: string };
+ *   Bindings: { DB: D1Database };
+ * }
+ *
+ * const app = new Hono<FortressEnv<MyEnv>>();
+ * app.use(createAuthMiddleware(fortress));
+ * app.get('/me', (c) => {
+ *   const requestId = c.get('requestId');     // host-defined, typed
+ *   const subject = getSubject(c);            // fortress-defined, typed
+ *   return c.json({ requestId, subject });
+ * });
+ * ```
+ */
+export interface FortressEnv<TAppEnv extends Env = Env> {
+  Variables: FortressVariables & ExtractVariables<TAppEnv>;
+  Bindings: ExtractBindings<TAppEnv>;
+}
+
+/** Minimum-viable context shape the typed helpers need — works with any `Context<E>` whose `Variables` include {@link FortressVariables}. */
+export type FortressContext<E extends Env = FortressEnv> = Context<E>;
+
+/**
+ * Hono middleware that resolves the request principal and populates the
+ * Hono context with `fortressSubject`, `fortressUserId` (USER alias),
+ * `fortressClaims`, `fortressDb`, and `fortressGetScopedDb`.
+ *
+ * Principal resolution goes through `fortress.resolvePrincipal`, which
+ * tries plugin `resolvePrincipal` hooks (api-key, future OAuth
+ * client_credentials, mTLS) first and then falls back to the JWT bearer
+ * token (cookie-first, `Authorization: Bearer` second). This means the
+ * same Hono app can authenticate browsers (cookies), SPA clients (Bearer),
+ * and service accounts (`Authorization: ApiKey ...` or `X-API-Key`)
+ * without extra wiring on any route.
+ *
+ * `fortressDb` has plugin `wrapAdapter` applied (e.g. tenancy schema
+ * switching). `fortressGetScopedDb(model)` additionally applies
+ * `scopeRules` for the requested model.
+ */
+export function createAuthMiddleware(
+  fortress: Fortress,
+): MiddlewareHandler<FortressEnv> {
+  // Internally typed as the base FortressEnv. The middleware is variance-safe
+  // when mounted on a `Hono<FortressEnv<MyApp>>()` because the augmented env's
+  // Variables are a superset of FortressVariables — Hono accepts the wider
+  // shape during use().
+  return async (c, next) => {
+    const resolved = await fortress.resolvePrincipal(c.req.raw);
+    if (!resolved) {
+      throw new FortressError(
+        'UNAUTHORIZED',
+        'Missing or invalid credentials',
+        401,
+      );
+    }
+
+    const { subject, claims, scopes } = resolved;
+    c.set('fortressSubject', subject);
+    if (subject.type === 'USER')
+      c.set('fortressUserId', subject.id);
+    if (claims)
+      c.set('fortressClaims', claims);
+    if (scopes !== undefined)
+      c.set('fortressScopes', scopes);
+
+    // Build request context for plugin adapter wrappers. The tenant is taken
+    // from the verified JWT claim (set by tenancy's enrichTokenClaims), never
+    // a client header — so a caller can only reach a tenant they belong to.
+    const plugins = fortress.config.plugins ?? [];
+    const requestContext: Record<string, unknown> = {
+      tenantId: claims?.customClaims?.tenantId,
+      ipAddress:
+        c.req.header('X-Forwarded-For') ?? c.req.header('X-Real-IP'),
+      userAgent: c.req.header('User-Agent'),
+    };
+
+    // Chain adapter wrappers (e.g., tenancy schema switching)
+    const wrappedAdapter = chainAdapterWrappers(
+      plugins,
+      fortress.config.database,
+      requestContext,
+    );
+    c.set('fortressDb', wrappedAdapter);
+
+    // Lazy scope rule applicator — routes pick the model they need. Scope
+    // rules key off the subject id; for non-USER subjects the plugins that
+    // care (data-isolation) typically noop, but the call still works.
+    const pluginCtx: PluginContext = {
+      db: wrappedAdapter,
+      config: fortress.config,
+    };
+    c.set(
+      'fortressGetScopedDb',
+      async (model: string): Promise<DatabaseAdapter> => {
+        const scopeRule = await collectScopeRules(
+          plugins,
+          subject.id,
+          model,
+          pluginCtx,
+        );
+        if (!scopeRule)
+          return wrappedAdapter;
+        return wrapAdapterWithScopeRules(wrappedAdapter, scopeRule);
+      },
+    );
+
+    await next();
+  };
+}
+
+/**
+ * Get the authenticated principal from the Hono context. Works for every
+ * subject kind (`USER`, `SERVICE_ACCOUNT`, ...). Generic in the env type
+ * so host apps can pass their own `Context<FortressEnv<MyEnv>>` without
+ * casts.
+ */
+export function getSubject<E extends Env = FortressEnv>(c: Context<E>): Subject {
+  const subject = c.get('fortressSubject' as never) as Subject | undefined;
+  if (!subject) {
+    throw new FortressError('UNAUTHORIZED', 'Not authenticated', 401);
+  }
+  return subject;
+}
+
+/**
+ * Get the authenticated user ID from Hono context. Throws 401 if the
+ * request was authenticated by a non-USER subject (e.g. a service account
+ * via api-key) — use {@link getSubject} for handlers that need to accept
+ * any principal.
+ */
+export function getUserId<E extends Env = FortressEnv>(c: Context<E>): string {
+  const subject = c.get('fortressSubject' as never) as Subject | undefined;
+  if (!subject || subject.type !== 'USER') {
+    throw new FortressError('UNAUTHORIZED', 'User not authenticated', 401);
+  }
+  return subject.id;
+}
+
+/**
+ * Get the authenticated user's JWT claims from Hono context. Claims are
+ * only populated when the request was authenticated via a JWT — api-key
+ * principals have no JWT claims. Throws 401 if unavailable.
+ *
+ * Pass a `TCustomClaims` type parameter to narrow `customClaims` to your
+ * deployment's plugin-augmented claim shape (e.g. tenancy adds
+ * `tenantId` / `tenantCode`).
+ *
+ * @example
+ * ```ts
+ * interface MyClaims { tenantId: string; tenantCode: string }
+ * const claims = getClaims<MyClaims>(c);
+ * claims.customClaims?.tenantCode; // string | undefined
+ * ```
+ */
+export function getClaims<
+  TCustomClaims extends object = Record<string, unknown>,
+  E extends Env = FortressEnv,
+>(c: Context<E>): TokenClaims & { customClaims?: TCustomClaims } {
+  const claims = c.get('fortressClaims' as never) as TokenClaims | undefined;
+  if (!claims) {
+    throw new FortressError('UNAUTHORIZED', 'No JWT claims on this request', 401);
+  }
+  return claims as TokenClaims & { customClaims?: TCustomClaims };
+}
+
+/**
+ * Get the request-scoped database adapter with plugin wrapAdapter applied.
+ */
+export function getDb<E extends Env = FortressEnv>(c: Context<E>): DatabaseAdapter {
+  const db = c.get('fortressDb' as never) as DatabaseAdapter | undefined;
+  if (!db) {
+    throw new FortressError('UNAUTHORIZED', 'Not authenticated', 401);
+  }
+  return db;
+}
+
+/**
+ * Get a model-scoped database adapter with both wrapAdapter and scopeRules applied.
+ */
+export function getScopedDb<E extends Env = FortressEnv>(
+  c: Context<E>,
+  model: string,
+): Promise<DatabaseAdapter> {
+  const fn = c.get('fortressGetScopedDb' as never) as
+    | ((model: string) => Promise<DatabaseAdapter>)
+    | undefined;
+  if (!fn) {
+    throw new FortressError('UNAUTHORIZED', 'Not authenticated', 401);
+  }
+  return fn(model);
+}

package/src/hono/middleware/auth.types.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Type-level tests for the Hono adapter typed helpers (P1-6).
+ *
+ * Uses `expectTypeOf` for compile-time assertions. The body of every `it`
+ * is intentionally type-only and contains no runtime assertions; vitest
+ * runs them once just to confirm the file imports cleanly.
+ */
+
+import type { Subject, TokenClaims } from '../../core/types';
+import type { FortressEnv } from './auth';
+import { Hono } from 'hono';
+import { describe, expectTypeOf, it } from 'vitest';
+import { getClaims, getSubject, getUserId } from './auth';
+
+interface MyEnv {
+  Variables: { requestId: string };
+  Bindings: { DB: 'pretend-binding' };
+}
+
+interface MyCustomClaims {
+  tenantId: string;
+  tenantCode: string;
+}
+
+describe('fortressEnv<TAppEnv> composition', () => {
+  it('exposes both host and fortress variables on a composed env', () => {
+    // Build a context typed as FortressEnv<MyEnv> and verify the types.
+    type Composed = FortressEnv<MyEnv>;
+    type Variables = Composed['Variables'];
+
+    expectTypeOf<Variables['fortressSubject']>().toEqualTypeOf<Subject>();
+    expectTypeOf<Variables['requestId']>().toEqualTypeOf<string>();
+    expectTypeOf<Composed['Bindings']['DB']>().toEqualTypeOf<'pretend-binding'>();
+  });
+
+  it('app = new Hono<FortressEnv<MyEnv>>() retains host variables', () => {
+    const app = new Hono<FortressEnv<MyEnv>>();
+    app.get('/x', (c) => {
+      const requestId = c.get('requestId');
+      expectTypeOf(requestId).toEqualTypeOf<string>();
+      return c.json({ requestId });
+    });
+  });
+});
+
+describe('typed helpers accept any FortressEnv-compatible context', () => {
+  it('getSubject works on the default FortressEnv', () => {
+    const app = new Hono<FortressEnv>();
+    app.get('/x', (c) => {
+      const subject = getSubject(c);
+      expectTypeOf(subject).toEqualTypeOf<Subject>();
+      return c.json({ subject });
+    });
+  });
+
+  it('getSubject / getUserId work on FortressEnv<MyEnv> without casts', () => {
+    const app = new Hono<FortressEnv<MyEnv>>();
+    app.get('/y', (c) => {
+      const subject = getSubject(c);
+      const userId = getUserId(c);
+      expectTypeOf(subject).toEqualTypeOf<Subject>();
+      expectTypeOf(userId).toEqualTypeOf<string>();
+      return c.json({ subject, userId });
+    });
+  });
+
+  it('getClaims narrows customClaims via the type parameter', () => {
+    const app = new Hono<FortressEnv>();
+    app.get('/z', (c) => {
+      const claims = getClaims<MyCustomClaims>(c);
+      expectTypeOf(claims).toEqualTypeOf<TokenClaims & { customClaims?: MyCustomClaims }>();
+      if (claims.customClaims) {
+        expectTypeOf(claims.customClaims.tenantId).toEqualTypeOf<string>();
+        expectTypeOf(claims.customClaims.tenantCode).toEqualTypeOf<string>();
+      }
+      return c.json({ ok: true });
+    });
+  });
+});
+
+describe('fortressEnv default keeps existing callers working', () => {
+  it('hono<FortressEnv> still resolves to a usable env', () => {
+    type Variables = FortressEnv['Variables'];
+    expectTypeOf<Variables['fortressSubject']>().toEqualTypeOf<Subject>();
+    // The unconstrained generic falls back to an empty bindings/extra-vars
+    // shape; Hono accepts it as a valid Env and the typed helpers work.
+    const app = new Hono<FortressEnv>();
+    app.get('/x', (c) => {
+      const subject = getSubject(c);
+      expectTypeOf(subject).toEqualTypeOf<Subject>();
+      return c.json({ subject });
+    });
+  });
+});

package/src/hono/middleware/csrf.test.ts

@@ -0,0 +1,127 @@
+import { Hono } from 'hono';
+import { describe, expect, it } from 'vitest';
+import { createCsrfMiddleware } from './csrf';
+
+describe('csrf middleware', () => {
+  it('allows GET requests without CSRF header', async () => {
+    const app = new Hono();
+    app.use('/*', createCsrfMiddleware());
+    app.get('/api/data', c => c.json({ ok: true }));
+
+    const res = await app.request('/api/data', { method: 'GET' });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ ok: true });
+  });
+
+  it('allows POST requests with valid CSRF header', async () => {
+    const app = new Hono();
+    app.use('/*', createCsrfMiddleware());
+    app.post('/api/data', c => c.json({ ok: true }));
+
+    const res = await app.request('/api/data', {
+      method: 'POST',
+      headers: { 'X-Fortress-CSRF': '1' },
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ ok: true });
+  });
+
+  it('blocks POST requests without CSRF header (403)', async () => {
+    const app = new Hono();
+    app.use('/*', createCsrfMiddleware());
+    app.post('/api/data', c => c.json({ ok: true }));
+
+    const res = await app.request('/api/data', {
+      method: 'POST',
+    });
+
+    expect(res.status).toBe(403);
+    const body = await res.json();
+    expect(body.error).toBe('CSRF_MISSING');
+  });
+
+  it('allows requests to skip paths', async () => {
+    const app = new Hono();
+    app.use('/*', createCsrfMiddleware({ skipPaths: ['/webhook'] }));
+    app.post('/webhook', c => c.json({ ok: true }));
+
+    const res = await app.request('/webhook', {
+      method: 'POST',
+    });
+
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ ok: true });
+  });
+
+  it('matches skip paths at segment boundaries', async () => {
+    const app = new Hono();
+    app.use('/*', createCsrfMiddleware({ skipPaths: ['/webhook'] }));
+    app.post('/webhook/delivery', c => c.json({ ok: true }));
+    app.post('/webhook-evil', c => c.json({ ok: true }));
+
+    expect((await app.request('/webhook/delivery', { method: 'POST' })).status).toBe(200);
+    expect((await app.request('/webhook-evil', { method: 'POST' })).status).toBe(403);
+  });
+
+  it('blocks cross-site requests (Sec-Fetch-Site: cross-site)', async () => {
+    const app = new Hono();
+    app.use('/*', createCsrfMiddleware());
+    app.post('/api/data', c => c.json({ ok: true }));
+
+    const res = await app.request('/api/data', {
+      method: 'POST',
+      headers: {
+        'X-Fortress-CSRF': '1',
+        'Sec-Fetch-Site': 'cross-site',
+      },
+    });
+
+    expect(res.status).toBe(403);
+    const body = await res.json();
+    expect(body.error).toBe('CSRF_REJECTED');
+  });
+
+  it('custom header name works', async () => {
+    const app = new Hono();
+    app.use('/*', createCsrfMiddleware({ headerName: 'X-Custom-CSRF' }));
+    app.post('/api/data', c => c.json({ ok: true }));
+
+    // Should fail with default header name
+    const res1 = await app.request('/api/data', {
+      method: 'POST',
+      headers: { 'X-Fortress-CSRF': '1' },
+    });
+    expect(res1.status).toBe(403);
+
+    // Should succeed with custom header name
+    const res2 = await app.request('/api/data', {
+      method: 'POST',
+      headers: { 'X-Custom-CSRF': '1' },
+    });
+    expect(res2.status).toBe(200);
+  });
+
+  it('custom safe methods work', async () => {
+    const app = new Hono();
+    app.use('/*', createCsrfMiddleware({ safeMethods: ['GET', 'HEAD', 'OPTIONS', 'POST'] }));
+    app.post('/api/data', c => c.json({ ok: true }));
+    app.put('/api/data', c => c.json({ ok: true }));
+
+    // POST is now safe, should pass without CSRF header
+    const res1 = await app.request('/api/data', {
+      method: 'POST',
+    });
+    expect(res1.status).toBe(200);
+
+    // PUT is not safe, should fail without CSRF header
+    const res2 = await app.request('/api/data', {
+      method: 'PUT',
+    });
+    expect(res2.status).toBe(403);
+  });
+});

package/src/hono/middleware/csrf.ts

@@ -0,0 +1,68 @@
+import type { MiddlewareHandler } from 'hono';
+
+/** Options accepted by {@link createCsrfMiddleware}. */
+export interface CsrfConfig {
+  /** Header name to check. Default: 'X-Fortress-CSRF'. */
+  headerName?: string;
+  /** Paths to skip CSRF checking. */
+  skipPaths?: string[];
+  /** HTTP methods that don't need CSRF checking. Default: ['GET', 'HEAD', 'OPTIONS']. */
+  safeMethods?: string[];
+}
+
+/**
+ * CSRF middleware using the custom-header strategy.
+ *
+ * Browsers enforce CORS preflight on custom headers, so cross-origin requests
+ * cannot set them without explicit server permission. This middleware requires
+ * a specific header to be present on non-safe HTTP methods.
+ *
+ * Additionally checks `Sec-Fetch-Site` to reject cross-site requests.
+ */
+export function createCsrfMiddleware(config?: CsrfConfig): MiddlewareHandler {
+  const headerName = config?.headerName ?? 'X-Fortress-CSRF';
+  const skipPaths = config?.skipPaths ?? [];
+  const safeMethods = config?.safeMethods ?? ['GET', 'HEAD', 'OPTIONS'];
+
+  return async (c, next): Promise<Response | void> => {
+    const method = c.req.method.toUpperCase();
+
+    // Safe methods don't need CSRF protection
+    if (safeMethods.includes(method)) {
+      await next();
+      return;
+    }
+
+    // Check skip paths at segment boundaries: `/foo` covers `/foo/bar` but
+    // never `/foobar`. A trailing `/*` is accepted as subtree notation.
+    const path = new URL(c.req.url).pathname;
+    if (matchesSkipPath(path, skipPaths)) {
+      await next();
+      return;
+    }
+
+    // Check Sec-Fetch-Site header - reject cross-site requests
+    const fetchSite = c.req.header('Sec-Fetch-Site');
+    if (fetchSite === 'cross-site') {
+      return c.json({ error: 'CSRF_REJECTED', message: 'Cross-site requests are not allowed' }, 403);
+    }
+
+    // Require the custom CSRF header
+    const csrfHeader = c.req.header(headerName);
+    if (!csrfHeader) {
+      return c.json({ error: 'CSRF_MISSING', message: 'Missing CSRF header' }, 403);
+    }
+
+    await next();
+  };
+}
+
+function matchesSkipPath(path: string, skipPaths: string[]): boolean {
+  return skipPaths.some((configured) => {
+    const withoutWildcard = configured.endsWith('/*') ? configured.slice(0, -2) : configured;
+    const base = withoutWildcard.length > 1 && withoutWildcard.endsWith('/')
+      ? withoutWildcard.slice(0, -1)
+      : withoutWildcard;
+    return path === base || path.startsWith(`${base}/`);
+  });
+}

package/src/hono/middleware/error-handler.ts

@@ -0,0 +1,12 @@
+import type { ErrorHandler } from 'hono';
+import { errorToResponse } from '../../core/http/error-response';
+
+/**
+ * Hono error handler that maps FortressError to HTTP responses.
+ * Delegates to the framework-agnostic `errorToResponse` in core so the
+ * mapping (status codes, `Retry-After`, sanitized 500s) stays consistent
+ * across Hono / Express / SvelteKit / `fortress.handleRequest`.
+ */
+export function createErrorHandler(): ErrorHandler {
+  return err => errorToResponse(err);
+}

package/src/hono/middleware/plugin-middleware.ts

@@ -0,0 +1,35 @@
+import type { MiddlewareHandler } from 'hono';
+import type { Fortress } from '../../core/fortress';
+import type { PluginRequestContext } from '../../core/http/plugin-middleware';
+import type { MiddlewareDefinition } from '../../core/plugin';
+import type { FortressEnv } from './auth';
+import { executePluginMiddleware } from '../../core/plugin-runner';
+
+/**
+ * Hono middleware that executes plugin-defined middleware for a given position.
+ *
+ * Normalizes Hono's context to the shared {@link PluginRequestContext}, so
+ * plugin middleware receives the same web-standard Request and resolved auth
+ * fields under core, Hono, and Express.
+ */
+export function createPluginMiddleware(
+  fortress: Fortress,
+  position: MiddlewareDefinition['position'],
+): MiddlewareHandler<FortressEnv> {
+  const plugins = fortress.config.plugins ?? [];
+
+  return async (c, next) => {
+    const path = c.req.path;
+    const ctx = { db: fortress.config.database, config: fortress.config };
+    const requestContext: PluginRequestContext = {
+      request: c.req.raw,
+      fortressSubject: c.get('fortressSubject'),
+      fortressUserId: c.get('fortressUserId'),
+      fortressClaims: c.get('fortressClaims'),
+      fortressScopes: c.get('fortressScopes'),
+    };
+
+    await executePluginMiddleware(plugins, position, path, ctx, requestContext);
+    await next();
+  };
+}