@bajustone/fortress 1.0.0-rc.1

package/src/hono/middleware/rbac.ts

@@ -0,0 +1,131 @@
+import type { MiddlewareHandler } from 'hono';
+import type { Fortress } from '../../core/fortress';
+import type { FortressEnv } from './auth';
+import { FortressError } from '../../core/errors';
+
+/** A `(resource, action)` IAM mapping for an HTTP route. */
+export interface RouteMapping {
+  resource: string;
+  action: string;
+}
+
+/** Options accepted by {@link createRbacMiddleware} (and the Hono adapter factory). */
+export interface RbacOptions {
+  /** Declarative route-to-resource mapping: 'METHOD /path' → { resource, action } */
+  routeMap?: Record<string, RouteMapping>;
+  /** Dynamic mapping function (used if routeMap doesn't match) */
+  mapRequest?: (method: string, path: string) => RouteMapping | null;
+  /** Paths that skip permission checks entirely (supports * wildcards) */
+  skipPaths?: string[];
+  /** Behavior for non-skipped routes absent from routeMap/mapRequest. */
+  unmappedRoutes?: 'allow' | 'deny';
+  /** @deprecated Use `unmappedRoutes: 'deny'`. */
+  defaultDeny?: boolean;
+}
+
+/**
+ * Hono middleware that checks IAM permissions for **user-owned routes**
+ * via a declarative route map. Fortress-managed routes (`/auth/*`,
+ * `/iam/*`, plugin paths) are protected automatically inside
+ * `fortress.handleRequest` — this middleware only handles routes the
+ * caller registered themselves.
+ *
+ * Lookup order:
+ * 1. {@link RbacOptions.skipPaths} — if matched, allow.
+ * 2. {@link RbacOptions.routeMap} — exact `'METHOD /path'` then
+ *    parameterized match.
+ * 3. {@link RbacOptions.mapRequest} — dynamic resolver fallback.
+ * 4. No mapping found → allow, unless {@link RbacOptions.defaultDeny} is set,
+ *    in which case the route is refused with a 403 (fail closed).
+ *
+ * Throws {@link FortressError} on missing/insufficient permissions.
+ */
+export function createRbacMiddleware(
+  fortress: Fortress,
+  options?: RbacOptions,
+): MiddlewareHandler<FortressEnv> {
+  const routeMap = options?.routeMap ?? {};
+  const skipPaths = options?.skipPaths ?? [];
+  const skipPatterns = skipPaths.map(p => pathToRegex(p));
+  const unmappedRoutes = options?.unmappedRoutes
+    ?? (options?.defaultDeny ? 'deny' : 'allow');
+
+  return async (c, next) => {
+    const path = c.req.path;
+    const method = c.req.method;
+
+    if (skipPatterns.some(pattern => pattern.test(path))) {
+      await next();
+      return;
+    }
+
+    const key = `${method} ${path}`;
+    let mapping: RouteMapping | null = routeMap[key] ?? null;
+
+    if (!mapping) {
+      mapping = findRouteMapMatch(method, path, routeMap);
+    }
+
+    if (!mapping && options?.mapRequest) {
+      mapping = options.mapRequest(method, path);
+    }
+
+    if (!mapping) {
+      if (unmappedRoutes === 'deny') {
+        // Fail closed: an unmapped route is refused rather than treated as
+        // public. Genuinely public routes belong in skipPaths.
+        throw new FortressError('FORBIDDEN', 'No permission mapping for this route', 403);
+      }
+      // No declarative mapping — caller treats this as a public route from
+      // the adapter's perspective. (Fortress-managed paths have already
+      // been caught and protected inside fortress.handleRequest.)
+      await next();
+      return;
+    }
+
+    const subject = c.get('fortressSubject');
+    if (!subject) {
+      throw new FortressError('UNAUTHORIZED', 'Not authenticated', 401);
+    }
+
+    const allowed = await fortress.iam.checkPermission(subject, mapping.resource, mapping.action, {
+      credentialScopes: c.get('fortressScopes'),
+    });
+    if (!allowed) {
+      throw new FortressError('FORBIDDEN', 'Insufficient permissions', 403);
+    }
+
+    await next();
+  };
+}
+
+/**
+ * Match a request against parameterized route map entries.
+ * 'GET /api/users/:id' matches 'GET /api/users/123'
+ */
+function findRouteMapMatch(method: string, path: string, routeMap: Record<string, RouteMapping>): RouteMapping | null {
+  for (const [pattern, mapping] of Object.entries(routeMap)) {
+    const [patternMethod, patternPath] = pattern.split(' ', 2);
+    if (patternMethod !== method)
+      continue;
+
+    const regex = pathToRegex(patternPath);
+    if (regex.test(path))
+      return mapping;
+  }
+  return null;
+}
+
+/**
+ * Convert a route pattern to a regex.
+ * :param → [^/]+
+ * → .*
+ */
+function pathToRegex(pattern: string): RegExp {
+  const regexStr = pattern
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/:[^/]+/g, '[^/]+')
+    .replace(/\\\*/g, '.*')
+    .replace(/\//g, '\\/');
+  return new RegExp(`^${regexStr}$`);
+}

package/src/hono/middleware/security-headers.test.ts

@@ -0,0 +1,88 @@
+import { Hono } from 'hono';
+import { describe, expect, it } from 'vitest';
+import { createSecurityHeadersMiddleware } from './security-headers';
+
+describe('security headers middleware', () => {
+  it('sets all default security headers', async () => {
+    const app = new Hono();
+    app.use('*', createSecurityHeadersMiddleware());
+    app.get('/test', c => c.text('ok'));
+
+    const res = await app.request('/test');
+    expect(res.status).toBe(200);
+    expect(res.headers.get('Strict-Transport-Security')).toBe('max-age=63072000; includeSubDomains');
+    expect(res.headers.get('X-Frame-Options')).toBe('DENY');
+    expect(res.headers.get('X-Content-Type-Options')).toBe('nosniff');
+    expect(res.headers.get('Content-Security-Policy')).toBe('default-src \'self\'');
+    expect(res.headers.get('Referrer-Policy')).toBe('strict-origin-when-cross-origin');
+    expect(res.headers.get('X-Permitted-Cross-Domain-Policies')).toBe('none');
+  });
+
+  it('sets security headers on error responses', async () => {
+    const app = new Hono();
+    app.use('*', createSecurityHeadersMiddleware());
+    app.get('/error', () => {
+      throw new Error('boom');
+    });
+
+    const res = await app.request('/error');
+    expect(res.status).toBe(500);
+    expect(res.headers.get('X-Content-Type-Options')).toBe('nosniff');
+    expect(res.headers.get('X-Frame-Options')).toBe('DENY');
+  });
+
+  it('allows custom CSP', async () => {
+    const app = new Hono();
+    app.use('*', createSecurityHeadersMiddleware({
+      contentSecurityPolicy: 'default-src \'self\'; script-src \'self\' cdn.example.com',
+    }));
+    app.get('/test', c => c.text('ok'));
+
+    const res = await app.request('/test');
+    expect(res.headers.get('Content-Security-Policy')).toBe('default-src \'self\'; script-src \'self\' cdn.example.com');
+  });
+
+  it('allows disabling individual headers', async () => {
+    const app = new Hono();
+    app.use('*', createSecurityHeadersMiddleware({
+      frameOptions: false,
+      contentSecurityPolicy: false,
+      referrerPolicy: false,
+    }));
+    app.get('/test', c => c.text('ok'));
+
+    const res = await app.request('/test');
+    expect(res.headers.get('X-Frame-Options')).toBeNull();
+    expect(res.headers.get('Content-Security-Policy')).toBeNull();
+    expect(res.headers.get('Referrer-Policy')).toBeNull();
+    // Others still present
+    expect(res.headers.get('X-Content-Type-Options')).toBe('nosniff');
+  });
+
+  it('supports HSTS preload', async () => {
+    const app = new Hono();
+    app.use('*', createSecurityHeadersMiddleware({ hstsPreload: true }));
+    app.get('/test', c => c.text('ok'));
+
+    const res = await app.request('/test');
+    expect(res.headers.get('Strict-Transport-Security')).toBe('max-age=63072000; includeSubDomains; preload');
+  });
+
+  it('disables HSTS when maxAge is 0', async () => {
+    const app = new Hono();
+    app.use('*', createSecurityHeadersMiddleware({ hstsMaxAge: 0 }));
+    app.get('/test', c => c.text('ok'));
+
+    const res = await app.request('/test');
+    expect(res.headers.get('Strict-Transport-Security')).toBeNull();
+  });
+
+  it('allows SAMEORIGIN for X-Frame-Options', async () => {
+    const app = new Hono();
+    app.use('*', createSecurityHeadersMiddleware({ frameOptions: 'SAMEORIGIN' }));
+    app.get('/test', c => c.text('ok'));
+
+    const res = await app.request('/test');
+    expect(res.headers.get('X-Frame-Options')).toBe('SAMEORIGIN');
+  });
+});

package/src/hono/middleware/security-headers.ts

@@ -0,0 +1,68 @@
+import type { MiddlewareHandler } from 'hono';
+
+/** Options accepted by {@link createSecurityHeadersMiddleware}. */
+export interface SecurityHeadersConfig {
+  /** Strict-Transport-Security max-age in seconds. Default: 63072000 (2 years). Set to 0 to disable. */
+  hstsMaxAge?: number;
+  /** Include subdomains in HSTS. Default: true. */
+  hstsIncludeSubdomains?: boolean;
+  /** HSTS preload flag. Default: false. */
+  hstsPreload?: boolean;
+  /** X-Frame-Options value. Default: 'DENY'. Set to false to disable. */
+  frameOptions?: 'DENY' | 'SAMEORIGIN' | false;
+  /** X-Content-Type-Options nosniff. Default: true. */
+  noSniff?: boolean;
+  /** Content-Security-Policy value. Default: "default-src 'self'". Set to false to disable. */
+  contentSecurityPolicy?: string | false;
+  /** Referrer-Policy value. Default: 'strict-origin-when-cross-origin'. Set to false to disable. */
+  referrerPolicy?: string | false;
+  /** X-Permitted-Cross-Domain-Policies value. Default: 'none'. Set to false to disable. */
+  permittedCrossDomainPolicies?: string | false;
+}
+
+/**
+ * Hono middleware that sets security-related HTTP headers.
+ * All headers are enabled by default with secure values.
+ */
+export function createSecurityHeadersMiddleware(config: SecurityHeadersConfig = {}): MiddlewareHandler {
+  const hstsMaxAge = config.hstsMaxAge ?? 63072000;
+  const hstsIncludeSubdomains = config.hstsIncludeSubdomains ?? true;
+  const hstsPreload = config.hstsPreload ?? false;
+  const frameOptions = config.frameOptions ?? 'DENY';
+  const noSniff = config.noSniff ?? true;
+  const csp = config.contentSecurityPolicy ?? 'default-src \'self\'';
+  const referrerPolicy = config.referrerPolicy ?? 'strict-origin-when-cross-origin';
+  const crossDomain = config.permittedCrossDomainPolicies ?? 'none';
+
+  // Pre-build HSTS header value
+  let hstsValue: string | null = null;
+  if (hstsMaxAge > 0) {
+    hstsValue = `max-age=${hstsMaxAge}`;
+    if (hstsIncludeSubdomains)
+      hstsValue += '; includeSubDomains';
+    if (hstsPreload)
+      hstsValue += '; preload';
+  }
+
+  return async (c, next) => {
+    try {
+      await next();
+    }
+    finally {
+      // Apply to success and error responses alike. Security headers should
+      // not disappear on the responses most likely to contain diagnostics.
+      if (hstsValue)
+        c.header('Strict-Transport-Security', hstsValue);
+      if (frameOptions)
+        c.header('X-Frame-Options', frameOptions);
+      if (noSniff)
+        c.header('X-Content-Type-Options', 'nosniff');
+      if (csp)
+        c.header('Content-Security-Policy', csp);
+      if (referrerPolicy)
+        c.header('Referrer-Policy', referrerPolicy);
+      if (crossDomain)
+        c.header('X-Permitted-Cross-Domain-Policies', crossDomain);
+    }
+  };
+}

package/src/hono/openapi.ts

@@ -0,0 +1,237 @@
+/**
+ * Hono OpenAPI adapter for Fortress.
+ *
+ * Schema-library agnostic — accepts a converter function from the user.
+ * Users pass their own JSON Schema → schema-library converter (Zod, Valibot, etc.).
+ *
+ * Users pass their schema library's JSON Schema converter:
+ *   - Zod v4: `z.fromJSONSchema`
+ *   - TypeBox: schemas are JSON Schema natively
+ *   - ArkType: `@ark/jsonschema`
+ */
+
+import type { EndpointDefinition } from '../core/endpoint';
+import type { Fortress } from '../core/fortress';
+import type { JSONSchema } from '../core/json-schema';
+
+/**
+ * A function that converts a JSON Schema to whatever schema type your
+ * framework adapter expects (e.g. Zod schema, Valibot schema). Used by
+ * {@link buildRouteDefinition} so fortress's OpenAPI generator stays
+ * schema-library agnostic.
+ */
+export type SchemaConverter<T = unknown> = (jsonSchema: JSONSchema) => T;
+
+interface MountOptions<T = unknown> {
+  /** Convert JSON Schema → your schema library (e.g., jsonSchemaToZod from '@bajustone/fortress/zod') */
+  schemaConverter: SchemaConverter<T>;
+  /** Paths to skip (won't be mounted) */
+  skipPaths?: string[];
+  /** Function to create a route definition from an endpoint (framework-specific) */
+  createRoute: (def: Record<string, unknown>) => unknown;
+  /** Function to register security schemes on the app */
+  registerSecuritySchemes?: (app: unknown) => void;
+}
+
+interface GenericOpenAPIApp {
+  openapi: (route: unknown, handler: (...args: any[]) => any) => void;
+}
+
+function toOpenAPIPath(path: string): string {
+  return path.replace(/:(\w+)/g, '{$1}');
+}
+
+/**
+ * Build a framework-agnostic route definition object from an EndpointDefinition.
+ * The schemaConverter transforms JSON Schema into whatever the target framework expects.
+ */
+export function buildRouteDefinition<T>(
+  ep: EndpointDefinition,
+  schemaConverter: SchemaConverter<T>,
+): Record<string, unknown> {
+  const openAPIPath = toOpenAPIPath(ep.path);
+  const method = ep.method.toLowerCase() as 'get' | 'post' | 'put' | 'delete' | 'patch';
+
+  const routeDef: Record<string, unknown> = {
+    method,
+    path: openAPIPath,
+    operationId: ep.handler,
+    responses: {} as Record<number, { description: string; content?: Record<string, unknown> }>,
+  };
+
+  if (ep.meta?.summary)
+    routeDef.summary = ep.meta.summary;
+  if (ep.meta?.description)
+    routeDef.description = ep.meta.description;
+  if (ep.meta?.tags)
+    routeDef.tags = ep.meta.tags;
+  if (ep.meta?.deprecated)
+    routeDef.deprecated = true;
+
+  // Security
+  if (ep.meta?.security) {
+    const sec: Array<Record<string, string[]>> = [];
+    for (const s of ep.meta.security) {
+      if (s === 'none')
+        sec.push({});
+      else if (s === 'bearer')
+        sec.push({ bearerAuth: [] });
+      else if (s === 'basic')
+        sec.push({ basicAuth: [] });
+      else if (s === 'apiKey')
+        sec.push({ apiKeyAuth: [] });
+    }
+    routeDef.security = sec;
+  }
+
+  // Request
+  const request: Record<string, unknown> = {};
+
+  if (ep.input?.body) {
+    request.body = {
+      content: {
+        'application/json': { schema: schemaConverter(ep.input.body) },
+      },
+    };
+  }
+
+  if (ep.input?.params?.properties) {
+    const shape: Record<string, unknown> = {};
+    const required = new Set(ep.input.params.required ?? []);
+
+    for (const [key, schema] of Object.entries(ep.input.params.properties)) {
+      const converted = schemaConverter({ ...schema, type: schema.type ?? 'string' });
+      shape[key] = required.has(key) ? converted : converted;
+    }
+    // Wrap params in an object schema
+    request.params = schemaConverter({
+      type: 'object',
+      properties: ep.input.params.properties,
+      required: ep.input.params.required,
+    });
+  }
+
+  if (ep.input?.query?.properties) {
+    request.query = schemaConverter(ep.input.query);
+  }
+
+  if (Object.keys(request).length > 0) {
+    routeDef.request = request;
+  }
+
+  // Responses
+  const responses: Record<number, { description: string; content?: Record<string, unknown> }> = {};
+  if (ep.responses) {
+    for (const [status, resp] of Object.entries(ep.responses)) {
+      const entry: { description: string; content?: Record<string, unknown> } = {
+        description: resp.description,
+      };
+      if (resp.schema) {
+        entry.content = {
+          'application/json': { schema: schemaConverter(resp.schema) },
+        };
+      }
+      responses[Number(status)] = entry;
+    }
+  }
+  else {
+    responses[200] = { description: 'Success' };
+  }
+  routeDef.responses = responses;
+
+  return routeDef;
+}
+
+/**
+ * Auto-mount all Fortress endpoints on an OpenAPI-compatible Hono app.
+ *
+ * Schema-library agnostic: you provide the converter.
+ *
+ * @example
+ * ```ts
+ * import { OpenAPIHono, createRoute } from '@hono/zod-openapi';
+ * import { mountFortressOpenAPI } from '@bajustone/fortress/hono';
+ * import { jsonSchemaToZod } from '@bajustone/fortress/zod';
+ *
+ * const app = new OpenAPIHono();
+ * mountFortressOpenAPI(app, fortress, {
+ *   schemaConverter: jsonSchemaToZod,
+ *   createRoute,
+ * });
+ * ```
+ */
+export function mountFortressOpenAPI<T>(
+  app: GenericOpenAPIApp & { openAPIRegistry?: { registerComponent: (type: string, name: string, schema: Record<string, unknown>) => void } },
+  fortress: Fortress,
+  options: MountOptions<T>,
+): void {
+  const skipPaths = new Set(options.skipPaths ?? []);
+
+  // Register security schemes if the app supports it
+  if (app.openAPIRegistry) {
+    app.openAPIRegistry.registerComponent('securitySchemes', 'bearerAuth', {
+      type: 'http',
+      scheme: 'bearer',
+      bearerFormat: 'JWT',
+    });
+    app.openAPIRegistry.registerComponent('securitySchemes', 'basicAuth', {
+      type: 'http',
+      scheme: 'basic',
+    });
+    app.openAPIRegistry.registerComponent('securitySchemes', 'apiKeyAuth', {
+      type: 'apiKey',
+      name: 'X-API-Key',
+      in: 'header',
+    });
+  }
+
+  // Custom security scheme registration
+  options.registerSecuritySchemes?.(app);
+
+  for (const ep of fortress.endpoints) {
+    if (skipPaths.has(ep.path))
+      continue;
+
+    const routeDef = buildRouteDefinition(ep, options.schemaConverter);
+    const route = options.createRoute(routeDef);
+    const handler = createAutoHandler(fortress, ep);
+
+    app.openapi(route, handler);
+  }
+}
+
+/**
+ * Get all Fortress endpoint definitions as framework route definitions.
+ * Returns a map of `{ [handlerName]: routeDef }`.
+ */
+export function getFortressRoutes<T>(
+  fortress: Fortress,
+  schemaConverter: SchemaConverter<T>,
+  createRoute: (def: Record<string, unknown>) => unknown,
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+
+  for (const ep of fortress.endpoints) {
+    const routeDef = buildRouteDefinition(ep, schemaConverter);
+    result[ep.handler] = createRoute(routeDef);
+  }
+
+  return result;
+}
+
+// ── Auto-handler wiring ──────���──────────────────────────────────────
+
+function createAutoHandler(fortress: Fortress, _ep: EndpointDefinition): (c: any) => Promise<Response> {
+  return async (c: any) => {
+    const raw = c.req?.raw as Request | undefined;
+    if (raw)
+      return fortress.handleRequest(raw);
+
+    const request = new Request(c.req.url, {
+      method: c.req.method,
+      headers: c.req.raw?.headers ?? undefined,
+      body: ['GET', 'HEAD'].includes(c.req.method) ? undefined : await c.req.text(),
+    });
+    return fortress.handleRequest(request);
+  };
+}

package/src/hono/protect.ts

@@ -0,0 +1,87 @@
+import type { Context, Env, MiddlewareHandler } from 'hono';
+import type { EndpointDefinition } from '../core/endpoint';
+import type { Fortress } from '../core/fortress';
+import type {
+  ProtectedRouteContext,
+  ProtectedRouteHandler,
+  ProtectedRouteTarget,
+  ProtectOptions,
+} from '../core/http/protect';
+import { protect } from '../core/http/protect';
+
+/**
+ * Hono-flavoured host callback. `E` flows in from the endpoint passed to
+ * `protectedRoute()`, so `ctx.body` / `ctx.query` / `ctx.params` / `ctx.input`
+ * are typed from the endpoint's phantom generics.
+ *
+ * `HEnv` is Hono's environment generic (renamed from `E` so it no longer
+ * collides with the endpoint generic). String targets degrade to the
+ * loose default just like the core helper.
+ */
+export type HonoProtectedRouteHandler<
+
+  E extends EndpointDefinition<any, any, any, any> = EndpointDefinition,
+  HEnv extends Env = Env,
+  TResult = unknown,
+> = (
+  c: Context<HEnv>,
+  ctx: ProtectedRouteContext<E>,
+) => TResult | Response | Promise<TResult | Response>;
+
+/**
+ * Wrap a host-owned Hono route in Fortress's route protection pipeline.
+ *
+ * Two overloads, mirroring `protect()`:
+ *
+ * - **Typed target** — passing an `EndpointDefinition` flows its phantom
+ *   generics through `ctx.body` / `ctx.query` / `ctx.params` / `ctx.input`.
+ * - **String target** — passing a unique `handler` name keeps the loose
+ *   `Record<string, unknown>` / `unknown` typing.
+ */
+export function protectedRoute<
+
+  E extends EndpointDefinition<any, any, any, any>,
+  HEnv extends Env = Env,
+  TResult = unknown,
+>(
+  fortress: Fortress,
+  target: E,
+  handler: HonoProtectedRouteHandler<E, HEnv, TResult>,
+  options?: ProtectOptions,
+): MiddlewareHandler<HEnv>;
+export function protectedRoute<HEnv extends Env = Env, TResult = unknown>(
+  fortress: Fortress,
+  target: string,
+  handler: HonoProtectedRouteHandler<EndpointDefinition, HEnv, TResult>,
+  options?: ProtectOptions,
+): MiddlewareHandler<HEnv>;
+export function protectedRoute(
+  fortress: Fortress,
+  target: ProtectedRouteTarget,
+
+  handler: HonoProtectedRouteHandler<any, any, unknown>,
+  options: ProtectOptions = {},
+): MiddlewareHandler {
+  return async (c) => {
+    // Cast: core `protect` overloads require a concrete branch; impl is loose.
+    const protectedHandler = (protect as (
+      f: Fortress,
+      t: ProtectedRouteTarget,
+      h: ProtectedRouteHandler,
+      o?: ProtectOptions,
+    ) => (request: Request) => Promise<Response>)(
+      fortress,
+      target,
+      ctx => handler(c, ctx),
+      { ...options, method: options.method ?? c.req.method },
+    );
+    return protectedHandler(c.req.raw);
+  };
+}
+
+export type {
+  ProtectedRouteContext,
+  ProtectedRouteHandler,
+  ProtectedRouteTarget,
+  ProtectOptions,
+};