@bajustone/fortress 1.0.0-rc.1

package/src/plugins/openapi/spec-builder.ts

@@ -0,0 +1,287 @@
+import type { ComponentSchemas, EndpointDefinition, SecurityRequirement } from '../../core/endpoint';
+import type { JSONSchema } from '../../core/json-schema';
+
+/** Minimal OpenAPI 3.1 spec shape produced by {@link buildOpenAPISpec}. */
+export interface OpenAPISpec {
+  openapi: string;
+  info: { title: string; version: string; description?: string };
+  servers?: Array<{ url: string; description?: string }>;
+  tags?: Array<{ name: string; description?: string }>;
+  paths: Record<string, Record<string, OpenAPIOperation>>;
+  components: {
+    schemas: Record<string, JSONSchema>;
+    securitySchemes: Record<string, OpenAPISecurityScheme>;
+  };
+}
+
+interface OpenAPIOperation {
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  tags?: string[];
+  deprecated?: boolean;
+  security?: Array<Record<string, string[]>>;
+  parameters?: OpenAPIParameter[];
+  requestBody?: {
+    required?: boolean;
+    content: { 'application/json': { schema: JSONSchema } };
+  };
+  responses: Record<string, {
+    description: string;
+    content?: { 'application/json': { schema: JSONSchema } };
+  }>;
+}
+
+interface OpenAPIParameter {
+  name: string;
+  in: 'query' | 'path';
+  required?: boolean;
+  description?: string;
+  schema: JSONSchema;
+}
+
+interface OpenAPISecurityScheme {
+  type: string;
+  scheme?: string;
+  bearerFormat?: string;
+  name?: string;
+  in?: string;
+}
+
+/** Options accepted by {@link buildOpenAPISpec}. */
+export interface SpecBuilderOptions {
+  title: string;
+  version: string;
+  description?: string;
+  servers?: Array<{ url: string; description?: string }>;
+  /** Optional top-level OpenAPI tags. */
+  tags?: Array<{ name: string; description?: string }>;
+  /**
+   * Operation ID strategy. Defaults to the historical Fortress method+path
+   * generator. `fortress.toOpenAPI()` defaults this to `'handler'` so host
+   * specs match the endpoint contract names consumers already chose.
+   */
+  operationId?: 'methodPath' | 'handler' | ((endpoint: EndpointDefinition) => string | undefined);
+}
+
+const SECURITY_SCHEMES: Record<string, OpenAPISecurityScheme> = {
+  bearer: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+  basic: { type: 'http', scheme: 'basic' },
+  apiKey: { type: 'apiKey', name: 'X-API-Key', in: 'header' },
+};
+
+const SECURITY_MAP: Record<SecurityRequirement, Record<string, string[]>> = {
+  bearer: { bearerAuth: [] },
+  basic: { basicAuth: [] },
+  apiKey: { apiKeyAuth: [] },
+  none: {},
+};
+
+const RE_LEADING_SLASH = /^\//;
+const RE_PARAM_COLON = /\/:(\w+)/g;
+const RE_SLASH = /\//g;
+const RE_NON_WORD = /\W/g;
+
+function toOperationId(method: string, path: string): string {
+  // /auth/sessions/:id → auth_sessions_id, POST → post_auth_sessions_id
+  const normalized = path
+    .replace(RE_LEADING_SLASH, '')
+    .replace(RE_PARAM_COLON, '/$1')
+    .replace(RE_SLASH, '_')
+    .replace(RE_NON_WORD, '_');
+  return `${method.toLowerCase()}_${normalized}`;
+}
+
+function extractPathParams(path: string, paramSchemas?: JSONSchema): OpenAPIParameter[] {
+  const params: OpenAPIParameter[] = [];
+  const matches = path.matchAll(/:(\w+)/g);
+
+  for (const match of matches) {
+    const name = match[1];
+    const schema = paramSchemas?.properties?.[name] ?? { type: 'string' as const };
+    params.push({
+      name,
+      in: 'path',
+      required: true,
+      description: schema.description,
+      schema: { type: schema.type ?? 'string' },
+    });
+  }
+
+  return params;
+}
+
+function extractQueryParams(querySchema?: JSONSchema): OpenAPIParameter[] {
+  if (!querySchema?.properties)
+    return [];
+
+  const params: OpenAPIParameter[] = [];
+  const required = new Set(querySchema.required ?? []);
+
+  for (const [name, schema] of Object.entries(querySchema.properties)) {
+    params.push({
+      name,
+      in: 'query',
+      required: required.has(name),
+      description: schema.description,
+      schema,
+    });
+  }
+
+  return params;
+}
+
+function toOpenAPIPath(path: string): string {
+  return path.replace(/:(\w+)/g, '{$1}');
+}
+
+/**
+ * Deep-clean Standard Schema / runtime-only fields from schema objects before
+ * embedding them in OpenAPI. Fortress schemas are JSON Schema objects with a
+ * `~standard` validator attached; external schema adapters can also hang
+ * functions or undefined values off the object. OpenAPI must receive pure
+ * JSON-serializable JSON Schema, so strip any key beginning with `~`, any
+ * function value, and any `undefined` value recursively.
+ */
+function cleanSchema<T>(value: T): T {
+  if (Array.isArray(value))
+    return value.map(cleanSchema) as T;
+
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(([key]) => !key.startsWith('~'))
+        .filter(([, entry]) => typeof entry !== 'function' && entry !== undefined)
+        .map(([key, entry]) => [key, cleanSchema(entry)]),
+    ) as T;
+  }
+
+  return value;
+}
+
+function resolveOperationId(endpoint: EndpointDefinition, options: SpecBuilderOptions): string | undefined {
+  if (typeof options.operationId === 'function')
+    return options.operationId(endpoint);
+  if (options.operationId === 'handler')
+    return endpoint.handler;
+  return toOperationId(endpoint.method, endpoint.path);
+}
+
+/** Walk every endpoint definition and component-schemas record and emit a complete OpenAPI 3.1 {@link OpenAPISpec}. */
+export function buildOpenAPISpec(
+  endpoints: EndpointDefinition[],
+  componentSchemas: ComponentSchemas,
+  options: SpecBuilderOptions,
+): OpenAPISpec {
+  const paths: Record<string, Record<string, OpenAPIOperation>> = {};
+  const usedSecuritySchemes = new Set<string>();
+
+  for (const ep of endpoints) {
+    const openAPIPath = toOpenAPIPath(ep.path);
+    const method = ep.method.toLowerCase();
+
+    if (!paths[openAPIPath]) {
+      paths[openAPIPath] = {};
+    }
+
+    const operation: OpenAPIOperation = {
+      operationId: resolveOperationId(ep, options),
+      responses: {},
+    };
+
+    // Meta
+    if (ep.meta) {
+      if (ep.meta.summary)
+        operation.summary = ep.meta.summary;
+      if (ep.meta.description)
+        operation.description = ep.meta.description;
+      if (ep.meta.tags)
+        operation.tags = ep.meta.tags;
+      if (ep.meta.deprecated)
+        operation.deprecated = true;
+
+      // Security
+      if (ep.meta.security) {
+        const secArr: Array<Record<string, string[]>> = [];
+        for (const s of ep.meta.security) {
+          if (s === 'none') {
+            secArr.push({});
+          }
+          else {
+            secArr.push(SECURITY_MAP[s]);
+            usedSecuritySchemes.add(s);
+          }
+        }
+        operation.security = secArr;
+      }
+    }
+
+    // Parameters
+    const params: OpenAPIParameter[] = [
+      ...extractPathParams(ep.path, cleanSchema(ep.input?.params)),
+      ...extractQueryParams(cleanSchema(ep.input?.query)),
+    ];
+    if (params.length > 0) {
+      operation.parameters = params;
+    }
+
+    // Request body
+    if (ep.input?.body) {
+      operation.requestBody = {
+        required: true,
+        content: { 'application/json': { schema: cleanSchema(ep.input.body) } },
+      };
+    }
+
+    // Responses
+    if (ep.responses) {
+      for (const [status, resp] of Object.entries(ep.responses)) {
+        const entry: { description: string; content?: { 'application/json': { schema: JSONSchema } } } = {
+          description: resp.description,
+        };
+        if (resp.schema) {
+          entry.content = { 'application/json': { schema: cleanSchema(resp.schema) } };
+        }
+        operation.responses[status] = entry;
+      }
+    }
+    else {
+      operation.responses['200'] = { description: 'Success' };
+    }
+
+    paths[openAPIPath][method] = operation;
+  }
+
+  // Build security schemes (only include those actually used)
+  const securitySchemes: Record<string, OpenAPISecurityScheme> = {};
+  const schemeNameMap: Record<string, string> = { bearer: 'bearerAuth', basic: 'basicAuth', apiKey: 'apiKeyAuth' };
+  for (const scheme of usedSecuritySchemes) {
+    const name = schemeNameMap[scheme];
+    if (name && SECURITY_SCHEMES[scheme]) {
+      securitySchemes[name] = SECURITY_SCHEMES[scheme];
+    }
+  }
+
+  const spec: OpenAPISpec = {
+    openapi: '3.1.0',
+    info: {
+      title: options.title,
+      version: options.version,
+      ...(options.description && { description: options.description }),
+    },
+    paths,
+    components: {
+      schemas: cleanSchema(componentSchemas),
+      securitySchemes,
+    },
+  };
+
+  if (options.servers && options.servers.length > 0) {
+    spec.servers = options.servers;
+  }
+  if (options.tags && options.tags.length > 0) {
+    spec.tags = options.tags;
+  }
+
+  return spec;
+}

package/src/plugins/rate-limit/express.test.ts

@@ -0,0 +1,89 @@
+/**
+ * Drives the expressRateLimit middleware directly (no real Express runtime)
+ * to confirm it calls the plugin's check() and surfaces errors via next(err).
+ */
+
+import type { MinimalExpressRequest } from './express';
+import { describe, expect, it } from 'vitest';
+import { FortressError } from '../../core/errors';
+import { createFortress } from '../../core/fortress';
+import { createTestAdapter } from '../../testing';
+import { expressRateLimit } from './express';
+import { rateLimit } from './index';
+
+const SECRET = 'express-rate-limit-wrapper-test-secret32!';
+
+function setup(maxPerIp: number) {
+  const fortress = createFortress({
+    jwt: { key: SECRET },
+    database: createTestAdapter(),
+    plugins: [rateLimit({ rules: { api: { maxPerIp, windowSeconds: 60 } } })],
+  });
+  return fortress;
+}
+
+function mockReq(overrides: Partial<MinimalExpressRequest> = {}): MinimalExpressRequest {
+  return { headers: {}, ...overrides };
+}
+
+async function invoke(
+  mw: (req: MinimalExpressRequest, res: unknown, next: (err?: unknown) => void) => void,
+  req: MinimalExpressRequest,
+): Promise<{ err?: unknown; called: boolean }> {
+  return new Promise((resolve) => {
+    let called = false;
+    mw(req, {}, (err?: unknown) => {
+      called = true;
+      resolve({ err, called });
+    });
+  });
+}
+
+describe('expressRateLimit (framework wrapper)', () => {
+  it('calls next() under the limit and next(FortressError) when exceeded', async () => {
+    const fortress = setup(2);
+    const mw = expressRateLimit(fortress, 'api');
+
+    const r1 = await invoke(mw, mockReq({ ip: '10.0.0.1' }));
+    const r2 = await invoke(mw, mockReq({ ip: '10.0.0.1' }));
+    expect(r1.err).toBeUndefined();
+    expect(r2.err).toBeUndefined();
+
+    const r3 = await invoke(mw, mockReq({ ip: '10.0.0.1' }));
+    expect(r3.err).toBeInstanceOf(FortressError);
+    expect((r3.err as FortressError).code).toBe('RATE_LIMITED');
+    expect((r3.err as FortressError).retryAfter).toBeGreaterThan(0);
+  });
+
+  it('falls back to x-forwarded-for when req.ip is missing', async () => {
+    const fortress = setup(1);
+    const mw = expressRateLimit(fortress, 'api');
+
+    // First request with XFF only — should pass.
+    const r1 = await invoke(mw, mockReq({ headers: { 'x-forwarded-for': '10.0.0.9' } }));
+    expect(r1.err).toBeUndefined();
+
+    // Same XFF, second hit — should be limited.
+    const r2 = await invoke(mw, mockReq({ headers: { 'x-forwarded-for': '10.0.0.9' } }));
+    expect(r2.err).toBeInstanceOf(FortressError);
+  });
+
+  it('keys by user when fortressUserId is present and keyByUser is on (default)', async () => {
+    const fortress = setup(1);
+    const mw = expressRateLimit(fortress, 'api');
+
+    // User 1 gets one hit, then blocked on same IP+user combo.
+    const r1 = await invoke(mw, mockReq({ ip: '10.0.0.5', fortressUserId: '1' }));
+    const r2 = await invoke(mw, mockReq({ ip: '10.0.0.5', fortressUserId: '1' }));
+    expect(r1.err).toBeUndefined();
+    expect(r2.err).toBeInstanceOf(FortressError);
+  });
+
+  it('throws synchronously during setup when the plugin is not registered', () => {
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+    });
+    expect(() => expressRateLimit(fortress, 'api')).toThrow(/rate-limit plugin is not registered/);
+  });
+});

package/src/plugins/rate-limit/express.ts

@@ -0,0 +1,86 @@
+/**
+ * Express middleware wrapper for the rate-limit plugin.
+ *
+ * Thin adapter that extracts the client IP (and optional authenticated
+ * userId) from an Express request and delegates to
+ * `fortress.plugins['rate-limit'].check(rule, keys)`. A `FortressError` with
+ * code `RATE_LIMITED` is passed to `next(err)` on exceed — the Express error
+ * middleware (`createErrorMiddleware` from `@bajustone/fortress/express`)
+ * renders a proper 429 with `Retry-After`.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { expressRateLimit } from '@bajustone/fortress/plugins/rate-limit/express';
+ *
+ * const app = express();
+ * app.use('/api', expressRateLimit(fortress, 'api'));
+ * ```
+ *
+ * @module
+ */
+
+import type { Fortress } from '../../core/fortress';
+
+// Minimal Express-compatible types so users bring their own express version.
+/** Shape fortress reads from; compatible with any modern Express request. */
+export interface MinimalExpressRequest {
+  ip?: string;
+  headers: Record<string, string | string[] | undefined>;
+  fortressUserId?: string;
+}
+
+export interface ExpressRateLimitOptions {
+  /**
+   * Include the authenticated user in the key (requires fortress auth
+   * middleware to have run first, populating `req.fortressUserId`). Defaults
+   * to `true` — falls back to IP-only when no user is present.
+   */
+  keyByUser?: boolean;
+  /** Override IP extraction. Default uses `req.ip` then forwarding headers. */
+  extractIp?: (req: MinimalExpressRequest) => string | undefined;
+}
+
+interface RateLimitCheck {
+  check: (rule: string, keys: { ip?: string; userId?: string }) => Promise<void>;
+}
+
+function defaultExtractIp(req: MinimalExpressRequest): string | undefined {
+  if (req.ip)
+    return req.ip;
+  const xff = req.headers['x-forwarded-for'];
+  if (typeof xff === 'string')
+    return xff.split(',')[0].trim();
+  if (Array.isArray(xff) && xff.length > 0)
+    return xff[0].split(',')[0].trim();
+  const xri = req.headers['x-real-ip'];
+  return typeof xri === 'string' ? xri : undefined;
+}
+
+/**
+ * Returns an Express middleware that rate-limits requests against the named
+ * rule defined in your `rateLimit({ rules: { ... } })` config.
+ */
+export function expressRateLimit(
+  fortress: Fortress,
+  ruleName: string,
+  options: ExpressRateLimitOptions = {},
+): (req: MinimalExpressRequest, _res: unknown, next: (err?: unknown) => void) => void {
+  const methods = fortress.plugins['rate-limit'] as unknown as RateLimitCheck | undefined;
+  if (!methods?.check) {
+    throw new Error(
+      'rate-limit plugin is not registered — add rateLimit({...}) to your FortressConfig.plugins',
+    );
+  }
+  const extractIp = options.extractIp ?? defaultExtractIp;
+  const keyByUser = options.keyByUser ?? true;
+
+  return (req, _res, next) => {
+    const ip = extractIp(req);
+    const userId = keyByUser ? req.fortressUserId : undefined;
+    methods
+      .check(ruleName, { ip, userId })
+      .then(() => next())
+      .catch(next);
+  };
+}

package/src/plugins/rate-limit/hono.test.ts

@@ -0,0 +1,60 @@
+import { Hono } from 'hono';
+import { describe, expect, it } from 'vitest';
+import { createFortress } from '../../core/fortress';
+import { createHonoMiddleware } from '../../hono';
+import { createTestAdapter } from '../../testing';
+import { honoRateLimit } from './hono';
+import { rateLimit } from './index';
+
+const SECRET = 'hono-rate-limit-wrapper-test-secret-32!';
+
+describe('honoRateLimit (framework wrapper)', () => {
+  function setup(ruleMaxPerIp: number) {
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      plugins: [
+        rateLimit({
+          rules: { api: { maxPerIp: ruleMaxPerIp, windowSeconds: 60 } },
+        }),
+      ],
+    });
+    const { errorHandler } = createHonoMiddleware(fortress);
+    const app = new Hono();
+    app.onError(errorHandler);
+    app.use('/api/*', honoRateLimit(fortress, 'api'));
+    app.get('/api/things', c => c.json({ ok: true }));
+    return { fortress, app };
+  }
+
+  it('allows requests under the limit and blocks the next with 429 + Retry-After', async () => {
+    const { app } = setup(2);
+    const headers = { 'x-forwarded-for': '10.0.0.1' };
+
+    const r1 = await app.request('/api/things', { headers });
+    const r2 = await app.request('/api/things', { headers });
+    expect(r1.status).toBe(200);
+    expect(r2.status).toBe(200);
+
+    const r3 = await app.request('/api/things', { headers });
+    expect(r3.status).toBe(429);
+    expect(r3.headers.get('Retry-After')).toBeTruthy();
+  });
+
+  it('keys by IP — different forwarded-for values have separate buckets', async () => {
+    const { app } = setup(1);
+
+    const a = await app.request('/api/things', { headers: { 'x-forwarded-for': '10.0.0.2' } });
+    const b = await app.request('/api/things', { headers: { 'x-forwarded-for': '10.0.0.3' } });
+    expect(a.status).toBe(200);
+    expect(b.status).toBe(200); // different IP, still in budget
+  });
+
+  it('throws synchronously during setup when the plugin is not registered', () => {
+    const fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+    });
+    expect(() => honoRateLimit(fortress, 'api')).toThrow(/rate-limit plugin is not registered/);
+  });
+});

package/src/plugins/rate-limit/hono.ts

@@ -0,0 +1,74 @@
+/**
+ * Hono middleware wrapper for the rate-limit plugin.
+ *
+ * Thin adapter that extracts the client IP (and optional authenticated
+ * userId) from a Hono context and delegates to
+ * `fortress.plugins['rate-limit'].check(rule, keys)`. A `FortressError` with
+ * code `RATE_LIMITED` is thrown when the limit is exceeded — pair this with
+ * `createHonoMiddleware(fortress).errorHandler` (or any handler that calls
+ * `errorToResponse`) to render a proper 429 with `Retry-After`.
+ *
+ * @example
+ * ```ts
+ * import { Hono } from 'hono';
+ * import { honoRateLimit } from '@bajustone/fortress/plugins/rate-limit/hono';
+ *
+ * const app = new Hono();
+ * app.use('/api/*', honoRateLimit(fortress, 'api'));
+ * ```
+ *
+ * @module
+ */
+
+import type { Context, MiddlewareHandler } from 'hono';
+import type { Fortress } from '../../core/fortress';
+
+export interface HonoRateLimitOptions {
+  /**
+   * Include the authenticated user in the key (requires fortress auth
+   * middleware to have run first, populating `fortressUserId`). Defaults to
+   * `true` — falls back to IP-only when no user is present.
+   */
+  keyByUser?: boolean;
+  /** Override IP extraction. Default reads `X-Forwarded-For` then `X-Real-IP`. */
+  extractIp?: (c: Context) => string | undefined;
+}
+
+interface RateLimitCheck {
+  check: (rule: string, keys: { ip?: string; userId?: string }) => Promise<void>;
+}
+
+function defaultExtractIp(c: Context): string | undefined {
+  const xff = c.req.header('x-forwarded-for');
+  if (xff)
+    return xff.split(',')[0].trim();
+  return c.req.header('x-real-ip');
+}
+
+/**
+ * Returns a Hono middleware that rate-limits requests against the named rule
+ * defined in your `rateLimit({ rules: { ... } })` config.
+ */
+export function honoRateLimit(
+  fortress: Fortress,
+  ruleName: string,
+  options: HonoRateLimitOptions = {},
+): MiddlewareHandler {
+  const methods = fortress.plugins['rate-limit'] as unknown as RateLimitCheck | undefined;
+  if (!methods?.check) {
+    throw new Error(
+      'rate-limit plugin is not registered — add rateLimit({...}) to your FortressConfig.plugins',
+    );
+  }
+  const extractIp = options.extractIp ?? defaultExtractIp;
+  const keyByUser = options.keyByUser ?? true;
+
+  return async (c, next) => {
+    const ip = extractIp(c);
+    const userId = keyByUser
+      ? (c.get('fortressUserId' as never) as string | undefined)
+      : undefined;
+    await methods.check(ruleName, { ip, userId });
+    await next();
+  };
+}