@bajustone/fortress 1.0.0-rc.1

package/docs/plugins/openapi.md

@@ -0,0 +1,250 @@
+# OpenAPI Plugin
+
+## Overview
+
+The `openapi` plugin generates an OpenAPI 3.1 specification from all Fortress endpoints (auth, IAM, plugins, and top-level host `routes`) and serves a Scalar interactive API reference UI. It automatically discovers routes from your Fortress configuration, so the spec stays in sync without manual upkeep.
+
+If you only need a spec object for a build script or client code generator, use the standalone `toOpenAPI()` helper instead of installing the plugin. This keeps codegen paths env/DB-free:
+
+```ts
+import { toOpenAPI } from '@bajustone/fortress';
+import { appEndpointList } from './routes/v1/endpoints';
+
+const spec = toOpenAPI(appEndpointList, {
+  title: 'My API',
+  version: '1.0.0',
+  servers: [{ url: 'http://localhost:3001', description: 'Local' }],
+  tags: [{ name: 'Schools' }],
+});
+```
+
+If you already have a configured instance, `fortress.toOpenAPI()` emits a spec from `fortress.endpoints` by default.
+
+Use the `additionalEndpoints` option with the `convertRoutes` utility to merge routes that are not already registered as Fortress endpoint definitions.
+
+## Installation
+
+Import the `openapi` factory and pass it in the `plugins` array when creating a Fortress instance:
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { openapi } from '@bajustone/fortress/plugins/openapi';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    openapi({
+      title: 'My API',
+      version: '1.0.0',
+      description: 'Auth and IAM powered by Fortress',
+    }),
+  ],
+});
+```
+
+Once registered, methods are available at `fortress.plugins['openapi']` with full type safety.
+
+This gives you two routes out of the box:
+
+- `GET /openapi.json` -- the OpenAPI 3.1 JSON spec
+- `GET /openapi` -- Scalar interactive UI
+
+Both routes are public (no authentication required).
+
+## Configuration
+
+All fields on `OpenAPIConfig` are optional:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | `'Fortress Auth API'` | API title displayed in the spec and UI. |
+| `version` | `string` | `'1.0.0'` | API version. |
+| `description` | `string` | -- | API description included in the spec's `info` block. |
+| `servers` | `Array<{ url: string; description?: string }>` | -- | Server URL(s) for the spec. |
+| `tags` | `Array<{ name: string; description?: string }>` | -- | Top-level OpenAPI tags. |
+| `operationId` | `'methodPath' \| 'handler' \| ((endpoint) => string \| undefined)` | `'methodPath'` | Operation ID strategy. |
+| `specPath` | `string` | `'/openapi.json'` | Path to serve the JSON spec. |
+| `uiPath` | `string` | `'/openapi'` | Path to serve the Scalar UI. |
+| `disableUI` | `boolean` | `false` | When `true`, only the JSON spec route is registered. |
+| `includeCoreAuth` | `boolean` | `true` | Include core auth endpoints (login, register, refresh, etc.) in the spec. |
+| `includeCoreIam` | `boolean` | `true` | Include core IAM endpoints (roles, groups, permissions, etc.) in the spec. |
+| `additionalSchemas` | `ComponentSchemas` | -- | Extra component schemas to merge into `components.schemas`. |
+| `additionalEndpoints` | `EndpointDefinition[]` | -- | Extra endpoint definitions to include in the spec, typically produced by `convertRoutes`. |
+
+## Usage
+
+### Basic setup
+
+With no options, the plugin includes all core auth endpoints, all core IAM endpoints, and every registered plugin's routes:
+
+```ts
+openapi()
+```
+
+### Customizing the spec paths
+
+```ts
+openapi({
+  specPath: '/api/docs/spec.json',
+  uiPath: '/api/docs',
+})
+```
+
+### Disabling the Scalar UI
+
+If you only need the JSON spec (for example, to feed into a code generator), disable the UI:
+
+```ts
+openapi({
+  disableUI: true,
+})
+```
+
+### Excluding core endpoints
+
+To generate a spec that only contains plugin and application routes:
+
+```ts
+openapi({
+  includeCoreAuth: false,
+  includeCoreIam: false,
+})
+```
+
+### Adding server URLs
+
+```ts
+openapi({
+  servers: [
+    { url: 'https://api.example.com', description: 'Production' },
+    { url: 'http://localhost:3000', description: 'Local development' },
+  ],
+})
+```
+
+## Merging Application Routes
+
+The most powerful feature of the OpenAPI plugin is the ability to merge your application's own routes into the same spec as Fortress endpoints. This produces a single unified API reference.
+
+### Zod-free frozen converters
+
+`@bajustone/fortress/hono` exports three supported converter contracts:
+
+- `identitySchemaConverter` — returns raw JSON Schema unchanged for tooling that consumes JSON Schema directly.
+- `fetcherSchemaConverter` — compiles JSON Schema to a validating Standard Schema V1 using the pinned `@bajustone/fetcher` runtime; use with `hono-openapi` / `@hono/standard-validator` without Zod.
+- `toJSONSchemaConverter` — extracts JSON Schema from Fortress or fetcher builder schemas when importing app routes with `convertRoutes`.
+
+```ts
+import {
+  convertRoutes,
+  fetcherSchemaConverter,
+  mountFortressOpenAPI,
+  toJSONSchemaConverter,
+} from '@bajustone/fortress/hono';
+
+mountFortressOpenAPI(app, fortress, {
+  createRoute, // from your Hono OpenAPI integration
+  schemaConverter: fetcherSchemaConverter,
+});
+
+const appEndpoints = convertRoutes(appRoutes, {
+  prefix: '/api/v1',
+  schemaConverter: toJSONSchemaConverter,
+});
+```
+
+These export names and signatures are part of the frozen Hono/OpenAPI public surface.
+
+### Using `convertRoutes`
+
+The `convertRoutes` utility (exported from `@bajustone/fortress/hono` or `@bajustone/fortress/express`) converts `createRoute`-style route objects into Fortress `EndpointDefinition[]`. It is schema-library agnostic -- you provide a converter function that turns your schema objects into JSON Schema.
+
+```ts
+import { openapi } from '@bajustone/fortress/plugins/openapi';
+import { convertRoutes } from '@bajustone/fortress/hono'; // or /express
+import { z } from 'zod';
+
+// Your application routes defined with createRoute
+import { loginRoute, listUsersRoute } from './modules/auth/routes';
+import { listSchoolsRoute } from './modules/sdms/routes';
+
+openapi({
+  title: 'My API',
+  version: '1.0.0',
+  description: 'Unified spec: fortress + app endpoints',
+  additionalEndpoints: convertRoutes(
+    [loginRoute, listUsersRoute, listSchoolsRoute],
+    { prefix: '/api/v1', schemaConverter: z.toJSONSchema },
+  ),
+})
+```
+
+### `convertRoutes` options
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `schemaConverter` | `(schema: unknown) => JSONSchema` | Yes | Converts your schema objects to JSON Schema. For Zod v4 use `z.toJSONSchema`. Works with any schema library. |
+| `prefix` | `string` | No | Path prefix to prepend to every route (e.g., `'/api/v1'`). |
+
+### Supported route shape
+
+`convertRoutes` accepts any object matching the `ExternalRoute` interface, which is compatible with the shape returned by `@hono/zod-openapi`'s `createRoute`:
+
+```ts
+interface ExternalRoute {
+  method: string;
+  path: string;
+  tags?: string[];
+  summary?: string;
+  description?: string;
+  deprecated?: boolean;
+  security?: Array<Record<string, string[]>>;
+  request?: {
+    body?: { content: { 'application/json': { schema: unknown } } };
+    params?: unknown;
+    query?: unknown;
+  };
+  responses: Record<number | string, {
+    description: string;
+    content?: { 'application/json': { schema: unknown } };
+  }>;
+}
+```
+
+### Adding raw `EndpointDefinition` objects
+
+If you prefer to skip `convertRoutes`, you can pass `EndpointDefinition[]` directly:
+
+```ts
+import type { EndpointDefinition } from '@bajustone/fortress';
+
+const myEndpoint: EndpointDefinition = {
+  method: 'GET',
+  path: '/api/v1/health',
+  handler: 'healthCheck',
+  meta: { summary: 'Health check', tags: ['System'], security: ['none'] },
+  responses: { 200: { description: 'OK' } },
+};
+
+openapi({
+  additionalEndpoints: [myEndpoint],
+})
+```
+
+## API Reference
+
+| Method | Signature | Returns |
+|---|---|---|
+| `generateSpec` | `()` | `OpenAPISpec` -- full OpenAPI 3.1 spec object (cached after first call) |
+| `getSpec` | `()` | `Record<string, unknown>` -- the spec as a plain object (used by the JSON route) |
+| `getUI` | `()` | `string` -- Scalar HTML page (used by the UI route) |
+
+## How It Works
+
+1. **Endpoint discovery** -- On the first call to `generateSpec`, the plugin collects endpoints from three sources: core auth endpoints, core IAM endpoints, and all registered plugins (excluding itself). Consumer-provided `additionalEndpoints` are appended last.
+2. **Schema merging** -- Component schemas from core auth, core IAM, and `additionalSchemas` are merged into the spec's `components.schemas`.
+3. **Spec building** -- The collected endpoints and schemas are passed to the internal `buildOpenAPISpec` function, which produces a valid OpenAPI 3.1.0 document. Path parameters using `:param` syntax are converted to `{param}` format. Operation IDs are auto-generated from the HTTP method and path.
+4. **Security scheme detection** -- Security schemes (Bearer JWT, Basic, API Key) are only included in the spec when at least one endpoint references them, keeping the output clean.
+5. **Caching** -- The generated spec is cached after the first call. The spec is regenerated only when a new Fortress instance is created.
+6. **Scalar UI** -- The UI route serves a lightweight HTML page that loads the Scalar API reference library from a CDN and points it at the JSON spec path.

package/docs/plugins/rate-limit.md

@@ -0,0 +1,223 @@
+# Rate Limit Plugin
+
+## Overview
+
+The `rate-limit` plugin adds sliding-window rate limiting to Fortress. It covers:
+
+- **Built-in auth endpoints**: `/auth/login`, `/auth/register`, `/auth/refresh`, plus OAuth token issuance (`/oauth/token`) and API-key creation (`/api-key/keys`) when those plugins are mounted.
+- **User-owned routes**: exposes `fortress.plugins['rate-limit'].check(ruleName, keys)` and per-framework middleware wrappers so any route in your app can be rate-limited against a shared, named rule.
+
+Attempts are tracked by IP address, authenticated user (when keyed that way), or both. When a limit is exceeded, a `FortressError` with code `RATE_LIMITED` and a `retryAfter` value (in seconds) is thrown — adapters translate this into a 429 with a `Retry-After` header automatically.
+
+## Installation
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { rateLimit } from '@bajustone/fortress/plugins/rate-limit';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    rateLimit({
+      // Built-in Fortress endpoint blocks — each is opt-in; omitting a block
+      // disables rate-limiting for that endpoint.
+      login:       { maxPerIp: 10, maxPerAccount: 5, windowSeconds: 900 },
+      register:    { maxPerIp: 3,  windowSeconds: 3600 },
+      refresh:     { maxPerIp: 60, windowSeconds: 60 },
+      oauthToken:  { maxPerIp: 60, windowSeconds: 60 },
+      apiKeyIssue: { maxPerIp: 10, maxPerUser: 10, windowSeconds: 3600 },
+
+      // Named rules for your own routes + programmatic check() calls.
+      rules: {
+        api:    { maxPerIp: 200, maxPerUser: 1000, windowSeconds: 60 },
+        strict: { maxPerIp: 5,   windowSeconds: 60 },
+      },
+    }),
+  ],
+});
+```
+
+## Configuration
+
+### Endpoint blocks
+
+| Block | Default state | Applied at | Default values |
+|---|---|---|---|
+| `login` | **Always on** | `beforeLogin` hook | `{ maxPerIp: 10, maxPerAccount: 5, windowSeconds: 900 }` |
+| `register` | **Always on** | `beforeRegister` hook | `{ maxPerIp: 3, windowSeconds: 3600 }` |
+| `refresh` | Opt-in | `beforeTokenRefresh` hook | `{ maxPerIp: 60, maxPerUser: 60, windowSeconds: 60 }` |
+| `oauthToken` | Opt-in | Path middleware on `POST /oauth/token` (before-auth) | `{ maxPerIp: 60, windowSeconds: 60 }` |
+| `apiKeyIssue` | Opt-in | Path middleware on `POST /api-key/keys` (after-auth) | `{ maxPerIp: 10, maxPerUser: 10, windowSeconds: 3600 }` |
+
+**Gate blocks (`login`, `register`) default on.** They're the first line of defense against credential stuffing and mass registration; leaving them opt-in would let a version bump silently remove DoS protection. To turn one off explicitly:
+
+```ts
+rateLimit({
+  login: { disabled: true },
+  register: { disabled: true },
+})
+```
+
+**Other endpoints are opt-in** — present the block to enable it (with defaults merged), omit to disable.
+
+### Rule shape (`rules` + `paths`)
+
+```ts
+interface RateLimitRule {
+  maxPerIp?: number;      // per-client-IP limit
+  maxPerUser?: number;    // per-authenticated-user limit (no-op if no userId)
+  windowSeconds: number;
+  keyPrefix?: string;     // defaults to rule name
+}
+```
+
+A rule with both `maxPerIp` and `maxPerUser` evaluates each key independently — whichever fills up first short-circuits with `RATE_LIMITED`.
+
+### Path bindings (advanced)
+
+Bind a named rule (or inline rule) to any Fortress-handled path glob. Matching uses `:param` and `*` wildcards.
+
+```ts
+rateLimit({
+  rules: { webhooks: { maxPerIp: 20, windowSeconds: 60 } },
+  paths: [
+    { match: '/webhooks/*', methods: ['POST'], rule: 'webhooks' },
+    { match: '/internal/*', position: 'after-auth',
+      rule: { maxPerIp: 1000, maxPerUser: 100, windowSeconds: 60 } },
+  ],
+})
+```
+
+`position: 'before-auth'` (default) matches any request against the IP. `after-auth` runs after principal resolution so `maxPerUser` can apply. Path bindings only fire for routes dispatched through `fortress.handleRequest`.
+
+### `paths` vs the per-framework wrapper
+
+The config-driven `paths` list and the per-framework wrappers (`honoRateLimit` / `expressRateLimit` / `svelteKitRateLimit`) both apply a named rule to a route. Pick by deployment shape:
+
+| Use this… | …when |
+|---|---|
+| `honoRateLimit(fortress, 'api')` / `expressRateLimit(...)` / `svelteKitRateLimit(...)` | You have a framework middleware layer and want to limit routes the framework serves (either your own or Fortress-mounted). |
+| `paths: [{ match: '/foo/*', rule: 'api' }]` | Serverless / framework-less deployments that call `fortress.handleRequest` directly, or when you prefer declarative config co-located with the rest of the rate-limit setup. |
+
+Both target the same store. **Don't stack both on the same path** — each match increments the counter, so double-wrapping halves the effective limit.
+
+## Rate-limiting your own routes
+
+The plugin exposes a `check(ruleName, keys)` method and ready-made middleware wrappers for Hono, Express, and SvelteKit.
+
+### Programmatic API
+
+```ts
+// Works from any context — route handlers, jobs, WebSocket messages, etc.
+await fortress.plugins['rate-limit'].check('api', {
+  ip: request.ip,
+  userId: session.userId,
+});
+// throws FortressError(RATE_LIMITED) when the limit is exceeded.
+```
+
+### Hono
+
+```ts
+import { honoRateLimit } from '@bajustone/fortress/plugins/rate-limit/hono';
+
+app.use('/api/*', honoRateLimit(fortress, 'api'));
+// Extracts IP from X-Forwarded-For / X-Real-IP and fortressUserId from the
+// Hono context (populated by the fortress auth middleware). Pair with the
+// fortress Hono errorHandler so 429 responses carry Retry-After.
+```
+
+### Express
+
+```ts
+import { expressRateLimit } from '@bajustone/fortress/plugins/rate-limit/express';
+
+app.use('/api', expressRateLimit(fortress, 'api'));
+// Uses req.ip / forwarding headers and req.fortressUserId set by the
+// fortress Express auth middleware. Errors flow through next(err) into the
+// standard fortress error handler.
+```
+
+### SvelteKit
+
+```ts
+// hooks.server.ts
+import { svelteKitRateLimit } from '@bajustone/fortress/plugins/rate-limit/sveltekit';
+
+export const handle = async ({ event, resolve }) => {
+  if (event.url.pathname.startsWith('/api/')) {
+    await svelteKitRateLimit(fortress, 'api', event);
+  }
+  return resolve(event);
+};
+```
+
+## Methods-only plugins (magic-link, 2FA, email-verification)
+
+These plugins expose methods rather than HTTP routes — you wire them into your own endpoints. Rate-limit them the same way you'd rate-limit any app route: call `check()` (or the per-framework wrapper) in your handler before invoking the plugin method.
+
+```ts
+app.post('/auth/magic-link/send', async (c) => {
+  await fortress.plugins['rate-limit'].check('strict', {
+    ip: c.req.header('x-forwarded-for'),
+  });
+  const { email } = await c.req.json();
+  return c.json(await fortress.plugins['magic-link'].sendMagicLink(email));
+});
+```
+
+## How It Works
+
+### IPv6 normalization
+
+IPv6 addresses are normalized to their `/64` prefix to prevent bypass via address rotation within an allocated block. IPv4-mapped IPv6 addresses (`::ffff:1.2.3.4`) are stripped to the IPv4 form. IPv4 addresses are used as-is. Missing IPs fall through as `unknown` — still counted against the `unknown` bucket so smuggling via a stripped header doesn't get a free pass.
+
+### Sliding window algorithm
+
+The default in-memory store records a timestamp for each request. On each check, timestamps older than the window are pruned, and the remaining count is compared to the limit. A background cleanup runs every 60 seconds to prune stale entries.
+
+### Key format
+
+Keys are namespaced by rule name:
+- `<rule>:ip:<normalized-ip>` for per-IP counters
+- `<rule>:user:<userId>` for per-user counters
+
+Set `keyPrefix` on a rule to override the namespace (useful when sharing a store with other tooling).
+
+## Custom Store
+
+Provide a custom `RateLimitStore` for distributed deployments (e.g., Redis):
+
+```ts
+interface RateLimitStore {
+  increment: (key: string, windowMs: number) => Promise<{ count: number; resetAt: number }>;
+  get: (key: string) => Promise<{ count: number; resetAt: number } | null>;
+}
+```
+
+| Method | Description |
+|---|---|
+| `increment(key, windowMs)` | Increment the counter for `key` within a sliding window of `windowMs` milliseconds. Returns the current count and the timestamp (ms) when the oldest entry in the window expires. |
+| `get(key)` | Return the current counter for `key`, or `null` if no record exists. |
+
+```ts
+rateLimit({
+  login: { maxPerIp: 10, maxPerAccount: 5, windowSeconds: 900 },
+  store: myRedisStore, // implements RateLimitStore
+});
+```
+
+## Example: handling the error
+
+```ts
+import { FortressError } from '@bajustone/fortress';
+
+try {
+  await fortress.auth.login('alice@example.com', 'wrong-password');
+} catch (err) {
+  if (err instanceof FortressError && err.code === 'RATE_LIMITED') {
+    console.log(`Try again in ${err.retryAfter} seconds`);
+  }
+}
+```