@bajustone/fortress 1.0.0-rc.1

package/examples/hono-app/index.ts

@@ -0,0 +1,1009 @@
+/**
+ * Example Hono app using Fortress
+ *
+ * Demonstrates EVERY feature Fortress offers:
+ *
+ *   Core: registration, login, logout, token refresh, sessions, impersonation,
+ *         RBAC (roles, groups, permissions), password policy
+ *
+ *   Plugins: rate-limit, account-lockout, email-verification, two-factor,
+ *            magic-link, api-key, social-login, tenancy, data-isolation,
+ *            audit-log, webhook, oauth
+ *
+ *   Middleware: auth, RBAC, CSRF, security headers
+ *
+ *   Helpers: getUserId, getClaims, getDb, getScopedDb
+ *
+ * Run:  bun run dev
+ * Or:   bun run examples/hono-app/index.ts
+ */
+import { Hono } from 'hono';
+import { createFortress, email, endpoint, int, obj, str, strict } from '../../src';
+import {
+  convertRoutes,
+  createCsrfMiddleware,
+  createHonoMiddleware,
+  createSecurityHeadersMiddleware,
+  getClaims,
+  getDb,
+  getScopedDb,
+  getSubject,
+  getUserId,
+  mountFortress,
+  protectedRoute,
+  vBody,
+  vParam,
+  vQuery,
+} from '../../src/hono';
+import { accountLockout } from '../../src/plugins/account-lockout';
+import { admin } from '../../src/plugins/admin';
+import { apiKey } from '../../src/plugins/api-key';
+import { auditLog } from '../../src/plugins/audit-log';
+import { dataIsolation } from '../../src/plugins/data-isolation';
+import { emailVerification } from '../../src/plugins/email-verification';
+import { magicLink } from '../../src/plugins/magic-link';
+import { oauth } from '../../src/plugins/oauth';
+import { openapi } from '../../src/plugins/openapi';
+import { rateLimit } from '../../src/plugins/rate-limit';
+import { honoRateLimit } from '../../src/plugins/rate-limit/hono';
+import { socialLogin } from '../../src/plugins/social-login';
+import { tenancy } from '../../src/plugins/tenancy';
+import { twoFactor } from '../../src/plugins/two-factor';
+import { builtinEvents, webhook } from '../../src/plugins/webhook';
+import { createTestAdapter } from '../../src/testing';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 1. Create Fortress instance with ALL plugins
+// ═══════════════════════════════════════════════════════════════════════════
+
+const db = createTestAdapter();
+
+const hostOwnedStatsEndpoint = endpoint('GET', '/api/host-owned-stats')
+  .summary('Host-owned route protected by Fortress metadata')
+  .description('Demonstrates protectedRoute(): this Hono handler is app-owned, but Fortress supplies auth, RBAC, plugin middleware, and validation from endpoint metadata.')
+  .tags('App')
+  .security('bearer')
+  .permission('fortress', 'viewResources')
+  .response(200, 'Host route stats', obj({ users: int(), subjectType: str() }, 'users', 'subjectType'))
+  .handler('hostOwnedStats')
+  .build();
+
+// ── Observability (optional but demonstrated) ─────────────────────────────
+// A minimal console-backed logger satisfies the FortressLogger interface.
+// Drop in `pino()` or `fastify.log` for production.
+const logger = {
+  level: 'info',
+  fatal: (...args: unknown[]): void => console.error('[fortress:fatal]', ...args),
+  error: (...args: unknown[]): void => console.error('[fortress:error]', ...args),
+  warn: (...args: unknown[]): void => console.warn('[fortress:warn]', ...args),
+  // eslint-disable-next-line no-console -- example-only; real apps pass pino()
+  info: (...args: unknown[]): void => console.info('[fortress:info]', ...args),
+  // eslint-disable-next-line no-console -- example-only; real apps pass pino()
+  debug: (...args: unknown[]): void => console.debug('[fortress:debug]', ...args),
+  // eslint-disable-next-line no-console -- example-only; real apps pass pino()
+  trace: (...args: unknown[]): void => console.debug('[fortress:trace]', ...args),
+  silent: (): void => {},
+};
+
+const fortress = createFortress({
+  jwt: {
+    key: 'dev-secret-minimum-32-bytes-long!',
+    // key: ['new-secret-32-bytes-minimum!!!!!!', 'old-secret-32-bytes-minimum!!!!!!'],  // ← secret rotation
+    accessTokenExpirySeconds: 900,
+    refreshTokenExpirySeconds: 604800,
+  },
+  database: db,
+  passwordPolicy: { minLength: 10 },
+  logger,
+  // To wire OpenTelemetry metrics/spans, install @opentelemetry/api and:
+  //
+  //   import { createOtelTelemetry } from '../../src/otel';
+  //   observability: await createOtelTelemetry({ name: 'fortress-example' }),
+  //
+  // The adapter is the ONLY file in the repo that imports @opentelemetry/api
+  // (dynamically), so this example stays workerd/Deno-clean when not used.
+
+  // Plugin order matters — hooks run in array order
+  plugins: [
+    // ── Admin (IAM route protection + bootstrap) ──
+    admin({
+      apiKeyRoutes: true,
+      bootstrap: {
+        enabled: Boolean(process.env.FORTRESS_ADMIN_BOOTSTRAP_SECRET),
+        secret: process.env.FORTRESS_ADMIN_BOOTSTRAP_SECRET,
+      },
+    }),
+
+    // ── Gate plugins (reject early) ──
+    rateLimit({
+      login: { maxPerIp: 100, maxPerAccount: 10, windowSeconds: 60 },
+      register: { maxPerIp: 50, windowSeconds: 60 },
+      refresh: { maxPerIp: 120, windowSeconds: 60 },
+      oauthToken: { maxPerIp: 60, windowSeconds: 60 },
+      apiKeyIssue: { maxPerIp: 10, maxPerUser: 10, windowSeconds: 3600 },
+      // Named rules consumed by honoRateLimit() on user-owned routes.
+      rules: {
+        api: { maxPerIp: 200, maxPerUser: 1000, windowSeconds: 60 },
+      },
+    }),
+    accountLockout({
+      maxFailedAttempts: 3,
+      lockoutDurationSeconds: 60,
+      escalation: true,
+    }),
+    emailVerification({
+      requireVerification: false, // set true in production
+      onSendVerification: async (email, token, userId) => {
+        console.warn(`[email-verification] userId=${userId} email=${email} token=${token}`);
+      },
+    }),
+
+    // ── Auth enhancement plugins ──
+    twoFactor({
+      secretEncryptionKey: process.env.FORTRESS_TOTP_ENCRYPTION_KEY!,
+      totp: { issuer: 'Fortress Example' },
+    }),
+    magicLink({
+      onSendMagicLink: async (email, token) => {
+        console.warn(`[magic-link] email=${email} token=${token}`);
+      },
+    }),
+    apiKey({ prefix: 'fortress', maxKeysPerSubject: 5, routes: true }),
+    // ^ `routes: true` mounts the self-service HTTP endpoints:
+    //   POST   /api-key/keys                   — create a key for the caller
+    //   GET    /api-key/keys                   — list the caller's keys
+    //   DELETE /api-key/keys/:id               — revoke one of the caller's keys
+    //   POST   /api-key/keys/:id/rotate        — rotate one of the caller's keys
+    // The admin plugin above adds admin-side routes when `apiKeyRoutes: true`:
+    //   GET    /admin/users/:userId/api-keys       — list any user's keys
+    //   DELETE /admin/users/:userId/api-keys/:id   — revoke any user's key
+    // Both require the `apiKey:manage` permission (auto-registered into
+    // `fortress-admin` via `/iam/admin/bootstrap`).
+    socialLogin({
+      tokenEncryptionKey: process.env.FORTRESS_SOCIAL_TOKEN_KEY ?? 'dev-social-token-key-32-bytes!!!',
+      providers: [
+        // Placeholder credentials — shows the config API but won't complete real OAuth flows
+        { name: 'google', clientId: 'GOOGLE_CLIENT_ID', clientSecret: 'GOOGLE_SECRET' },
+        { name: 'github', clientId: 'GITHUB_CLIENT_ID', clientSecret: 'GITHUB_SECRET' },
+      ],
+    }),
+
+    // ── Multi-tenancy & data isolation ──
+    tenancy(),
+    dataIsolation({
+      scopes: [{
+        name: 'org',
+        field: 'orgId',
+        models: ['document'],
+        resolveValue: async (userId, ctx) => {
+          const assignment = await ctx.db.findOne<{ scopeValue: string }>({
+            model: 'user_scope_assignment',
+            where: [
+              { field: 'userId', operator: '=', value: userId },
+              { field: 'scopeName', operator: '=', value: 'org' },
+            ],
+          });
+          // Missing assignments fail closed (FORBIDDEN) by default.
+          return assignment?.scopeValue ?? null;
+        },
+      }],
+    }),
+
+    // ── Observability plugins (log last) ──
+    auditLog({ hashChain: true }),
+    webhook({
+      // Declare a custom event alongside the built-in auth events.
+      events: [...builtinEvents(), { name: 'order.shipped', schema: obj({ orderId: str() }, 'orderId') }],
+      delivery: {
+        // Demo transport: log instead of making a real outbound request. Omit
+        // `fetch` in production to use the SSRF-safe (IP-pinning) default.
+        fetch: async (req) => {
+          console.warn(`[webhook] → ${req.url}`, await req.text());
+          return new Response(null, { status: 200 });
+        },
+      },
+    }),
+
+    // ── OAuth server ──
+    oauth({
+      issuerUrl: 'http://localhost:3000',
+      scopePermissionMap: {
+        'read:users': { resource: 'user', action: 'list' },
+      },
+    }),
+
+    // ── Host-owned routes metadata ──
+    // protectedRoute() below uses this endpoint metadata for auth/RBAC and
+    // OpenAPI can include it alongside Fortress-owned endpoints.
+    { name: 'host-routes', routes: { hostOwnedStats: hostOwnedStatsEndpoint } },
+
+    // ── OpenAPI (API docs) ──
+    // convertRoutes turns createRoute-style objects into EndpointDefinitions
+    // using your own schema converter (Zod, Valibot, TypeBox, etc.)
+    openapi({
+      title: 'Fortress Example API',
+      version: '0.0.15',
+      additionalEndpoints: convertRoutes(
+        [
+          // These would normally be imported from your route modules, e.g.:
+          // import { loginRoute, listUsersRoute } from './modules/auth/routes';
+          {
+            method: 'get',
+            path: '/health',
+            tags: ['App'],
+            summary: 'Health check',
+            responses: {
+              200: {
+                description: 'OK',
+                content: { 'application/json': { schema: { type: 'object', properties: { status: { type: 'string' } } } } },
+              },
+            },
+          },
+        ],
+        {
+          // User brings their own converter, e.g. z.toJSONSchema for Zod v4
+          // Here we use identity since schemas are already JSON Schema
+          schemaConverter: s => s as Record<string, unknown>,
+        },
+      ),
+    }),
+  ],
+});
+
+// ── Demonstrate the observer surfaces ─────────────────────────────────────
+// Auth observer: fires on login/failure/logout/register/refresh/token-reuse.
+fortress.auth.addAuthObserver((event) => {
+  logger.info({ event }, `auth.${event.eventType}`);
+});
+
+// IAM observer: fires on role/permission/binding mutations.
+fortress.iam.addIamObserver((event) => {
+  logger.info({ event }, `iam.${event.eventType}`);
+});
+
+// Permission check observer: SYNCHRONOUS, hot path. Keep it bounded.
+fortress.iam.addPermissionCheckObserver((event) => {
+  if (!event.allowed) {
+    logger.warn(
+      { resource: event.resource, action: event.action, cached: event.cached },
+      'permission denied',
+    );
+  }
+});
+
+// Route-security manifest: the same generated inventory adapters use to
+// decide which paths are Fortress-managed. Useful for CI drift checks or
+// startup visibility.
+logger.info(
+  {
+    routes: fortress.manifest.length,
+    rbacRoutes: fortress.manifest.filter(route => route.classification === 'rbac').length,
+  },
+  'fortress route manifest generated',
+);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 2. Create Hono app + middleware
+// ═══════════════════════════════════════════════════════════════════════════
+
+const app = new Hono();
+
+const { authMiddleware, rbacMiddleware, errorHandler, pluginMiddleware } = createHonoMiddleware(fortress, {
+  routeMap: {
+    // User management
+    'GET /api/users': { resource: 'user', action: 'list' },
+    'POST /api/users': { resource: 'user', action: 'create' },
+    // Groups
+    'POST /api/groups': { resource: 'group', action: 'create' },
+    'POST /api/groups/:id/members': { resource: 'group', action: 'manage' },
+    'DELETE /api/groups/:id/members/:userId': { resource: 'group', action: 'manage' },
+    // Audit log
+    'GET /api/audit-log': { resource: 'audit-log', action: 'read' },
+    'POST /api/audit-log/verify-chain': { resource: 'audit-log', action: 'read' },
+    // Webhooks
+    'POST /api/webhooks': { resource: 'webhook', action: 'manage' },
+    'GET /api/webhooks': { resource: 'webhook', action: 'manage' },
+    'DELETE /api/webhooks/:id': { resource: 'webhook', action: 'manage' },
+    // Admin
+    'POST /admin/impersonate': { resource: 'user', action: 'impersonate' },
+    'GET /admin/lockout/:identifier': { resource: 'lockout', action: 'read' },
+    'POST /admin/lockout/:identifier/reset': { resource: 'lockout', action: 'manage' },
+  },
+  skipPaths: ['/health', '/auth/*', '/magic-link/*', '/email/*', '/social/*'],
+});
+
+// Global middleware
+app.use('*', createSecurityHeadersMiddleware());
+app.use('*', createCsrfMiddleware({
+  skipPaths: ['/auth', '/oauth', '/magic-link', '/email', '/social', '/health'],
+}));
+app.onError(errorHandler);
+
+// IAM routes: auth + admin plugin middleware (default deny via admin plugin)
+app.use('/iam/*', authMiddleware);
+app.use('/iam/*', pluginMiddleware.afterAuth);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 3. Public routes
+// ═══════════════════════════════════════════════════════════════════════════
+
+// curl http://localhost:3000/health
+app.get('/health', c => c.json({ status: 'ok' }));
+
+// ── Validated Request Helpers (vBody / vParam / vQuery) ──
+// vBody/vParam/vQuery extract request data AND validate it at runtime against
+// the supplied Standard Schema. On failure they throw FortressError with code
+// VALIDATION_ERROR (HTTP 422) — the same shape every fortress-managed endpoint
+// produces — so the registered Hono error handler formats it identically.
+
+// `email()` enforces the email format at runtime (ReDoS-safe pattern); `strict()`
+// rejects unknown body keys (no over-posting). Both come from the fetcher-backed
+// schema builder re-exported at `@bajustone/fortress/fetcher`.
+const RegisterBody = strict(obj({ email: email(), password: str({ min: 8 }), name: str() }, 'email', 'password', 'name'));
+const LoginBody = obj({ identifier: str(), password: str() }, 'identifier', 'password');
+
+// curl -X POST http://localhost:3000/auth/register -H 'Content-Type: application/json' \
+//   -d '{"email":"new@example.com","password":"MyPassword123!","name":"New User"}'
+app.post('/auth/register', async (c) => {
+  const { email, password, name } = await vBody(c, RegisterBody);
+  const user = await fortress.auth.createUser({ email, password, name });
+  return c.json({ data: user }, 201);
+});
+
+// curl -X POST http://localhost:3000/auth/login -H 'Content-Type: application/json' \
+//   -d '{"identifier":"admin@example.com","password":"Password123!"}'
+app.post('/auth/login', async (c) => {
+  const { identifier, password } = await vBody(c, LoginBody);
+  const result = await fortress.auth.login(identifier, password, {
+    ipAddress: c.req.header('x-forwarded-for'),
+    userAgent: c.req.header('user-agent'),
+  });
+  return c.json({ data: result });
+});
+
+// ── vParam / vQuery demo ──
+// curl 'http://localhost:3000/echo/42?greeting=hello'              → 200 { id: '42', greeting: 'hello' }
+// curl 'http://localhost:3000/echo/42'                             → 422 VALIDATION_ERROR (missing greeting)
+const EchoParam = obj({ id: str('Echo ID') }, 'id');
+const EchoQuery = obj({ greeting: str('Greeting') }, 'greeting');
+app.get('/echo/:id', async (c) => {
+  const { id } = await vParam(c, EchoParam);
+  const { greeting } = await vQuery(c, EchoQuery);
+  return c.json({ id, greeting });
+});
+
+// curl -X POST http://localhost:3000/auth/refresh -H 'Content-Type: application/json' \
+//   -d '{"refreshToken":"<token>"}'
+app.post('/auth/refresh', async (c) => {
+  const { refreshToken } = await c.req.json();
+  const result = await fortress.auth.refresh(refreshToken);
+  return c.json({ data: result });
+});
+
+// curl -X POST http://localhost:3000/auth/logout -H 'Content-Type: application/json' \
+//   -d '{"refreshToken":"<token>"}'
+app.post('/auth/logout', async (c) => {
+  const { refreshToken } = await c.req.json();
+  await fortress.auth.logout(refreshToken);
+  return c.json({ data: { loggedOut: true } });
+});
+
+// ── Magic Link (passwordless login) ──
+
+// curl -X POST http://localhost:3000/magic-link/send -H 'Content-Type: application/json' \
+//   -d '{"email":"admin@example.com"}'
+// (token is logged to console — copy it for the verify step)
+app.post('/magic-link/send', async (c) => {
+  const { email } = await c.req.json();
+  const result = await fortress.plugins['magic-link'].sendMagicLink(email);
+  return c.json({ data: result });
+});
+
+// curl -X POST http://localhost:3000/magic-link/verify -H 'Content-Type: application/json' \
+//   -d '{"token":"<token-from-console>"}'
+app.post('/magic-link/verify', async (c) => {
+  const { token } = await c.req.json();
+  const result = await fortress.plugins['magic-link'].verify(token);
+  return c.json({ data: result });
+});
+
+// ── Email Verification ──
+
+// curl -X POST http://localhost:3000/email/verify -H 'Content-Type: application/json' \
+//   -d '{"token":"<token-from-console>"}'
+app.post('/email/verify', async (c) => {
+  const { token } = await c.req.json();
+  const result = await fortress.plugins['email-verification'].verify(token);
+  return c.json({ data: result });
+});
+
+// ── Social Login ──
+
+// curl http://localhost:3000/social/providers
+app.get('/social/providers', (c) => {
+  const providers = fortress.plugins['social-login'].getProviders();
+  return c.json({ data: providers });
+});
+
+// curl 'http://localhost:3000/social/authorize/google?redirect_uri=http://localhost:3000/callback'
+// (returns authorization URL — in a real app you'd redirect the browser)
+app.get('/social/authorize/:provider', async (c) => {
+  const provider = c.req.param('provider');
+  const redirectUri = c.req.query('redirect_uri') ?? 'http://localhost:3000/callback';
+  const result = await fortress.plugins['social-login'].getAuthorizationUrl(provider, redirectUri);
+  return c.json({ data: result });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 4. Protected auth routes (require JWT)
+// ═══════════════════════════════════════════════════════════════════════════
+
+app.use('/auth/me', authMiddleware);
+app.use('/auth/sessions/*', authMiddleware);
+app.use('/auth/sessions', authMiddleware);
+app.use('/auth/2fa/enable', authMiddleware);
+app.use('/auth/2fa/confirm-setup', authMiddleware);
+app.use('/auth/2fa/disable', authMiddleware);
+app.use('/auth/email/*', authMiddleware);
+app.use('/auth/api-keys/*', authMiddleware);
+app.use('/auth/api-keys', authMiddleware);
+app.use('/auth/social/*', authMiddleware);
+
+// curl http://localhost:3000/auth/me -H 'Authorization: Bearer <token>'
+app.get('/auth/me', async (c) => {
+  const userId = getUserId(c);
+  const claims = getClaims(c);
+  const user = await fortress.auth.me(userId);
+  return c.json({ data: { user, claims } });
+});
+
+// ── Sessions ──
+
+// curl http://localhost:3000/auth/sessions -H 'Authorization: Bearer <token>'
+app.get('/auth/sessions', async (c) => {
+  const userId = getUserId(c);
+  const sessions = await fortress.auth.listSessions(userId);
+  return c.json({ data: sessions });
+});
+
+// curl -X DELETE http://localhost:3000/auth/sessions/1 -H 'Authorization: Bearer <token>'
+app.delete('/auth/sessions/:id', async (c) => {
+  const userId = getUserId(c);
+  const tokenId = c.req.param('id');
+  await fortress.auth.revokeSession(userId, tokenId);
+  return c.json({ data: { revoked: true } });
+});
+
+// curl -X DELETE http://localhost:3000/auth/sessions -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -d '{"currentTokenId":1}'
+app.delete('/auth/sessions', async (c) => {
+  const userId = getUserId(c);
+  const { currentTokenId } = await c.req.json();
+  await fortress.auth.revokeAllOtherSessions(userId, currentTokenId);
+  return c.json({ data: { revokedOthers: true } });
+});
+
+// ── Two-Factor Auth ──
+
+// curl -X POST http://localhost:3000/auth/2fa/enable -H 'Authorization: Bearer <token>'
+app.post('/auth/2fa/enable', async (c) => {
+  const userId = getUserId(c);
+  const result = await fortress.plugins['two-factor'].enable(userId);
+  return c.json({ data: { otpauthUrl: result.otpauthUrl, backupCodes: result.backupCodes } });
+});
+
+// curl -X POST http://localhost:3000/auth/2fa/confirm-setup -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -d '{"code":"123456"}'
+app.post('/auth/2fa/confirm-setup', async (c) => {
+  const userId = getUserId(c);
+  const { code } = await c.req.json();
+  const result = await fortress.plugins['two-factor'].confirmSetup(userId, code, {
+    userAgent: c.req.header('user-agent'),
+  });
+  return c.json({ data: result });
+});
+
+// Pending-login completion is public: the single-use continuation is the credential.
+// curl -X POST http://localhost:3000/auth/2fa/verify \
+//   -H 'Content-Type: application/json' \
+//   -d '{"continuationToken":"<from-pending-login>","code":"123456"}'
+app.post('/auth/2fa/verify', async (c) => {
+  const { continuationToken, code } = await c.req.json();
+  const result = await fortress.plugins['two-factor'].verify(continuationToken, code, {
+    userAgent: c.req.header('user-agent'),
+  });
+  return c.json({ data: result });
+});
+
+// curl -X POST http://localhost:3000/auth/2fa/disable -H 'Authorization: Bearer <token>'
+app.post('/auth/2fa/disable', async (c) => {
+  const userId = getUserId(c);
+  await fortress.plugins['two-factor'].disable(userId);
+  return c.json({ data: { disabled: true } });
+});
+
+// ── Email Verification (resend) ──
+
+// curl -X POST http://localhost:3000/auth/email/send-verification -H 'Authorization: Bearer <token>'
+// (token is logged to console)
+app.post('/auth/email/send-verification', async (c) => {
+  const userId = getUserId(c);
+  const result = await fortress.plugins['email-verification'].sendVerification(userId);
+  return c.json({ data: result });
+});
+
+// ── API Keys ──
+
+// curl -X POST http://localhost:3000/auth/api-keys -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -d '{"name":"My CI Key","scopes":["read:users"]}'
+app.post('/auth/api-keys', async (c) => {
+  const userId = getUserId(c);
+  const { name, scopes } = await c.req.json();
+  const result = await fortress.plugins['api-key'].createKey({ subject: { type: 'USER', id: userId }, name, scopes });
+  return c.json({ data: result }, 201);
+});
+
+// curl http://localhost:3000/auth/api-keys -H 'Authorization: Bearer <token>'
+app.get('/auth/api-keys', async (c) => {
+  const userId = getUserId(c);
+  const keys = await fortress.plugins['api-key'].listKeys({ subject: { type: 'USER', id: userId } });
+  return c.json({ data: keys });
+});
+
+// curl -X DELETE http://localhost:3000/auth/api-keys/1 -H 'Authorization: Bearer <token>'
+app.delete('/auth/api-keys/:id', async (c) => {
+  const userId = getUserId(c);
+  const keyId = c.req.param('id');
+  await fortress.plugins['api-key'].revokeKey({ subject: { type: 'USER', id: userId }, id: keyId });
+  return c.json({ data: { revoked: true } });
+});
+
+// curl -X POST http://localhost:3000/auth/api-keys/1/rotate -H 'Authorization: Bearer <token>'
+app.post('/auth/api-keys/:id/rotate', async (c) => {
+  const userId = getUserId(c);
+  const keyId = c.req.param('id');
+  const result = await fortress.plugins['api-key'].rotateKey({ subject: { type: 'USER', id: userId }, id: keyId });
+  return c.json({ data: result });
+});
+
+// ── Service Accounts ──
+//
+// Service accounts are first-class IAM principals — no sessions or passwords,
+// authenticated by long-lived api keys. Typical use: CI/CD, devices, M2M.
+// These endpoints are admin-facing (the admin user creates service accounts
+// and mints keys for them). Once a key is issued, the service account sends
+// it in `Authorization: ApiKey <key>` or `X-API-Key: <key>` — see
+// `/deploy/run` below for the consuming side.
+
+// curl -X POST http://localhost:3000/admin/service-accounts \
+//   -H 'Authorization: Bearer <admin-token>' \
+//   -H 'Content-Type: application/json' \
+//   -d '{"name":"ci-deploy","displayName":"CI Deploy"}'
+app.post('/admin/service-accounts', async (c) => {
+  const { name, displayName, description } = await c.req.json();
+  const sa = await fortress.iam.createServiceAccount({ name, displayName, description });
+  return c.json({ data: sa }, 201);
+});
+
+// Grant a service account a role.
+// curl -X POST http://localhost:3000/admin/service-accounts/1/roles \
+//   -H 'Authorization: Bearer <admin-token>' -H 'Content-Type: application/json' \
+//   -d '{"roleId":42}'
+app.post('/admin/service-accounts/:id/roles', async (c) => {
+  const saId = c.req.param('id');
+  const { roleId, tenantId } = await c.req.json();
+  await fortress.iam.bindRoleToServiceAccount(saId, String(roleId), tenantId);
+  return c.json({ data: { bound: true } });
+});
+
+// Mint an api key for a service account. The raw key is returned exactly once;
+// store it in your CI secrets store immediately.
+// curl -X POST http://localhost:3000/admin/service-accounts/1/keys \
+//   -H 'Authorization: Bearer <admin-token>' -H 'Content-Type: application/json' \
+//   -d '{"name":"ci-deploy-github-actions"}'
+app.post('/admin/service-accounts/:id/keys', async (c) => {
+  const saId = c.req.param('id');
+  const { name, scopes, expiresAt } = await c.req.json();
+  const result = await fortress.plugins['api-key'].createKey({
+    subject: { type: 'SERVICE_ACCOUNT', id: saId },
+    name,
+    scopes,
+    expiresAt,
+  });
+  return c.json({ data: result }, 201);
+});
+
+// Deactivate (kill-switch) or delete a service account.
+// curl -X PATCH http://localhost:3000/admin/service-accounts/1 \
+//   -H 'Authorization: Bearer <admin-token>' -H 'Content-Type: application/json' \
+//   -d '{"isActive":false}'
+app.patch('/admin/service-accounts/:id', async (c) => {
+  const saId = c.req.param('id');
+  const patch = await c.req.json();
+  const updated = await fortress.iam.updateServiceAccount(saId, patch);
+  return c.json({ data: updated });
+});
+
+// Hard delete (cascades to role bindings, direct permission bindings, and keys).
+// curl -X DELETE http://localhost:3000/admin/service-accounts/1 \
+//   -H 'Authorization: Bearer <admin-token>'
+app.delete('/admin/service-accounts/:id', async (c) => {
+  const saId = c.req.param('id');
+  await fortress.iam.deleteServiceAccount(saId);
+  return c.json({ data: { deleted: true } });
+});
+
+// The consuming side — an endpoint a service account would call. This is
+// mounted under the standard `authMiddleware`, so the api-key plugin's
+// `resolvePrincipal` hook handles `Authorization: ApiKey <key>` /
+// `X-API-Key` headers transparently. A JWT-authenticated browser session
+// would work on exactly the same route.
+//
+// curl -X POST http://localhost:3000/deploy/run -H 'Authorization: ApiKey <key>'
+app.post('/deploy/run', authMiddleware, async (c) => {
+  const subject = getSubject(c);
+  const allowed = await fortress.iam.checkPermission(subject, 'deploy', 'run');
+  if (!allowed)
+    return c.json({ error: 'Forbidden' }, 403);
+
+  // ... trigger the deploy ...
+  return c.json({ data: { deployId: 'dpl_abc123', startedBy: subject } });
+});
+
+// ── Social Login (linked accounts) ──
+
+// curl http://localhost:3000/auth/social/accounts -H 'Authorization: Bearer <token>'
+app.get('/auth/social/accounts', async (c) => {
+  const userId = getUserId(c);
+  const accounts = await fortress.plugins['social-login'].getLinkedAccounts(userId);
+  return c.json({ data: accounts });
+});
+
+// curl -X DELETE http://localhost:3000/auth/social/accounts/google -H 'Authorization: Bearer <token>'
+app.delete('/auth/social/accounts/:provider', async (c) => {
+  const userId = getUserId(c);
+  const provider = c.req.param('provider');
+  await fortress.plugins['social-login'].unlinkAccount(userId, provider);
+  return c.json({ data: { unlinked: true } });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 5. Tenant routes (require JWT)
+// ═══════════════════════════════════════════════════════════════════════════
+
+app.use('/api/tenants/*', authMiddleware);
+app.use('/api/tenants', authMiddleware);
+
+// curl -X POST http://localhost:3000/api/tenants -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -d '{"name":"Acme Corp","taxId":"acme"}'
+app.post('/api/tenants', async (c) => {
+  const { name, taxId, description } = await c.req.json();
+  const tenant = await fortress.plugins.tenancy.createTenant({ name, taxId, description });
+  return c.json({ data: tenant }, 201);
+});
+
+// curl http://localhost:3000/api/tenants -H 'Authorization: Bearer <token>'
+app.get('/api/tenants', async (c) => {
+  const userId = getUserId(c);
+  const tenants = await fortress.plugins.tenancy.getUserTenants(userId);
+  return c.json({ data: tenants });
+});
+
+// curl -X POST http://localhost:3000/api/tenants/switch -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -d '{"taxId":"acme"}'
+app.post('/api/tenants/switch', async (c) => {
+  const userId = getUserId(c);
+  const { taxId } = await c.req.json();
+  // userId is derived server-side from the verified token, never the body.
+  await fortress.plugins.tenancy.switchTenant({ taxId, userId });
+  return c.json({ data: { switched: true } });
+});
+
+// curl -X POST http://localhost:3000/api/tenants/1/members -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -d '{"userId":2}'
+app.post('/api/tenants/:id/members', async (c) => {
+  const tenantId = c.req.param('id');
+  const { userId } = await c.req.json();
+  await fortress.plugins.tenancy.addUserToTenant(userId, tenantId);
+  return c.json({ data: { added: true } });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 6. RBAC-protected routes (require JWT + permissions)
+// ═══════════════════════════════════════════════════════════════════════════
+
+// Rate-limit all /api/* routes using the named 'api' rule defined above.
+// Sits before authMiddleware so abusive unauthenticated hits are rejected
+// early without the cost of principal resolution.
+app.use('/api/*', honoRateLimit(fortress, 'api'));
+
+app.use('/api/users', authMiddleware);
+app.use('/api/groups/*', authMiddleware);
+app.use('/api/groups', authMiddleware);
+app.use('/api/users', rbacMiddleware);
+app.use('/api/groups/*', rbacMiddleware);
+app.use('/api/groups', rbacMiddleware);
+
+// Host-owned route protected by endpoint metadata instead of an adapter routeMap.
+// Runs the same core protections as fortress-managed routes, then calls this
+// Hono handler. Register before mountFortress so the app-owned handler wins.
+// curl http://localhost:3000/api/host-owned-stats -H 'Authorization: Bearer <token>'
+app.get('/api/host-owned-stats', protectedRoute(fortress, hostOwnedStatsEndpoint, async (_c, ctx) => {
+  const users = await fortress.config.database.count({ model: 'user' });
+  return { users, subjectType: ctx.subject?.type ?? 'UNKNOWN' };
+}));
+
+// curl http://localhost:3000/api/users -H 'Authorization: Bearer <token>'
+app.get('/api/users', async (c) => {
+  // getDb() returns the request-scoped adapter (tenant-aware when tenancy plugin is active)
+  const reqDb = getDb(c);
+  const users = await reqDb.findMany({ model: 'user' });
+  return c.json({ data: users });
+});
+
+// curl -X POST http://localhost:3000/api/users -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -H 'X-Fortress-CSRF: 1' \
+//   -d '{"email":"new@example.com","name":"New User"}'
+app.post('/api/users', async (c) => {
+  const body = await c.req.json();
+  const user = await fortress.auth.createUser({ ...body, password: 'TempPassword123!' });
+  return c.json({ data: user }, 201);
+});
+
+// ── Groups ──
+
+// curl -X POST http://localhost:3000/api/groups -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -H 'X-Fortress-CSRF: 1' \
+//   -d '{"name":"engineering","description":"Engineering team"}'
+app.post('/api/groups', async (c) => {
+  const { name, description } = await c.req.json();
+  const group = await fortress.iam.createGroup(name, description);
+  return c.json({ data: group }, 201);
+});
+
+// curl -X POST http://localhost:3000/api/groups/1/members -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -H 'X-Fortress-CSRF: 1' -d '{"userId":2}'
+app.post('/api/groups/:id/members', async (c) => {
+  const groupId = c.req.param('id');
+  const { userId } = await c.req.json();
+  await fortress.iam.addUserToGroup(groupId, userId);
+  return c.json({ data: { added: true } });
+});
+
+// curl -X DELETE http://localhost:3000/api/groups/1/members/2 -H 'Authorization: Bearer <token>'
+app.delete('/api/groups/:id/members/:userId', async (c) => {
+  const groupId = c.req.param('id');
+  const userId = c.req.param('userId');
+  await fortress.iam.removeUserFromGroup(groupId, userId);
+  return c.json({ data: { removed: true } });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 7. Admin routes (require JWT + elevated permissions)
+// ═══════════════════════════════════════════════════════════════════════════
+
+app.use('/api/audit-log/*', authMiddleware);
+app.use('/api/audit-log', authMiddleware);
+app.use('/api/webhooks/*', authMiddleware);
+app.use('/api/webhooks', authMiddleware);
+app.use('/admin/*', authMiddleware);
+app.use('/api/audit-log/*', rbacMiddleware);
+app.use('/api/audit-log', rbacMiddleware);
+app.use('/api/webhooks/*', rbacMiddleware);
+app.use('/api/webhooks', rbacMiddleware);
+app.use('/admin/*', rbacMiddleware);
+
+// ── Audit Log ──
+
+// curl 'http://localhost:3000/api/audit-log?limit=20' -H 'Authorization: Bearer <token>'
+app.get('/api/audit-log', async (c) => {
+  const options: Record<string, unknown> = {};
+  const userId = c.req.query('userId');
+  const eventType = c.req.query('eventType');
+  const limit = c.req.query('limit');
+  if (userId)
+    options.userId = Number(userId);
+  if (eventType)
+    options.eventType = eventType;
+  if (limit)
+    options.limit = Number(limit);
+  const entries = await fortress.plugins['audit-log'].getAuditLog(options);
+  return c.json({ data: entries });
+});
+
+// curl -X POST http://localhost:3000/api/audit-log/verify-chain -H 'Authorization: Bearer <token>' \
+//   -H 'X-Fortress-CSRF: 1'
+app.post('/api/audit-log/verify-chain', async (c) => {
+  const result = await fortress.plugins['audit-log'].verifyChain();
+  return c.json({ data: result });
+});
+
+// ── Impersonation ──
+
+// curl -X POST http://localhost:3000/admin/impersonate -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -H 'X-Fortress-CSRF: 1' -d '{"targetUserId":2}'
+app.post('/admin/impersonate', async (c) => {
+  const adminId = getUserId(c);
+  const { targetUserId, reason } = await c.req.json();
+  const result = await fortress.auth.impersonate(adminId, targetUserId, { reason });
+  return c.json({ data: result });
+});
+
+// ── Account Lockout ──
+
+// curl http://localhost:3000/admin/lockout/user@example.com -H 'Authorization: Bearer <token>'
+app.get('/admin/lockout/:identifier', async (c) => {
+  const identifier = c.req.param('identifier');
+  const status = await fortress.plugins['account-lockout'].getLockoutStatus(identifier);
+  return c.json({ data: status });
+});
+
+// curl -X POST http://localhost:3000/admin/lockout/user@example.com/reset \
+//   -H 'Authorization: Bearer <token>' -H 'X-Fortress-CSRF: 1'
+app.post('/admin/lockout/:identifier/reset', async (c) => {
+  const identifier = c.req.param('identifier');
+  await fortress.plugins['account-lockout'].resetLockout(identifier);
+  return c.json({ data: { reset: true } });
+});
+
+// ── Webhooks ──
+
+// curl -X POST http://localhost:3000/api/webhooks -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -H 'X-Fortress-CSRF: 1' \
+//   -d '{"url":"https://example.com/hook","events":["auth.login.success","order.shipped"]}'
+// A signing secret is generated and returned ONCE on the response — store it now.
+app.post('/api/webhooks', async (c) => {
+  const { url, events, secret } = await c.req.json();
+  const endpoint = await fortress.plugins.webhook.registerEndpoint(url, events, secret ? { secret } : undefined);
+  return c.json({ data: endpoint }, 201);
+});
+
+// curl http://localhost:3000/api/webhooks -H 'Authorization: Bearer <token>'
+app.get('/api/webhooks', async (c) => {
+  const endpoints = await fortress.plugins.webhook.listEndpoints();
+  return c.json({ data: endpoints });
+});
+
+// curl -X DELETE http://localhost:3000/api/webhooks/1 -H 'Authorization: Bearer <token>'
+app.delete('/api/webhooks/:id', async (c) => {
+  const id = c.req.param('id');
+  await fortress.plugins.webhook.removeEndpoint(id);
+  return c.json({ data: { removed: true } });
+});
+
+// Emit a custom event — delivered to every endpoint subscribed to 'order.shipped'.
+// curl -X POST http://localhost:3000/api/events/order-shipped -H 'Authorization: Bearer <token>' \
+//   -H 'Content-Type: application/json' -H 'X-Fortress-CSRF: 1' -d '{"orderId":"o_123"}'
+app.post('/api/events/order-shipped', async (c) => {
+  const { orderId } = await c.req.json();
+  await fortress.plugins.webhook.emit('order.shipped', { orderId }, { idempotencyKey: orderId });
+  return c.json({ data: { emitted: true } });
+});
+
+// ── Data Isolation (demonstrates getScopedDb) ──
+
+app.use('/api/documents', authMiddleware);
+
+// curl http://localhost:3000/api/documents -H 'Authorization: Bearer <token>'
+// getScopedDb() applies row-level isolation — queries are automatically filtered
+// by the user's org scope (configured in the dataIsolation plugin above).
+app.get('/api/documents', async (c) => {
+  const scopedDb = await getScopedDb(c, 'document');
+  const docs = await scopedDb.findMany({ model: 'document' });
+  return c.json({ data: docs });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 8. Mount Fortress routes (auth, IAM, plugins, OAuth, OpenAPI)
+// ═══════════════════════════════════════════════════════════════════════════
+//
+// `mountFortress` registers a single Hono middleware that detects any
+// Fortress-managed path (`/auth/*`, `/iam/*`, `/oauth/*`, `/openapi*`,
+// plugin routes) and delegates to `fortress.handleRequest`. The custom
+// `/auth/*` handlers above are registered FIRST, so Hono's first-match
+// routing means they win — `mountFortress` only handles paths the user
+// did not handle manually.
+//
+// Auth issuing endpoints (login/refresh/impersonate) inside core
+// dispatch automatically attach `Set-Cookie` headers using
+// `FortressConfig.cookies` defaults.
+mountFortress(app, fortress);
+
+// ═══════════════════════════════════════════════════════════════════════════
+// 9. Seed data on startup
+// ═══════════════════════════════════════════════════════════════════════════
+
+async function seed(): Promise<void> {
+  // Create users
+  const admin = await fortress.auth.createUser({
+    email: 'admin@example.com',
+    password: 'Password123!',
+    name: 'Admin User',
+  });
+  const user = await fortress.auth.createUser({
+    email: 'user@example.com',
+    password: 'Password123!',
+    name: 'Regular User',
+  });
+
+  // Mark emails as verified
+  await db.update({ model: 'user', where: [{ field: 'id', operator: '=', value: admin.id }], data: { emailVerified: true } });
+  await db.update({ model: 'user', where: [{ field: 'id', operator: '=', value: user.id }], data: { emailVerified: true } });
+
+  // Bootstrap admin user — creates fortress-admin role with all IAM permissions
+  await fortress.plugins.admin.bootstrap({ userId: admin.id });
+
+  // Create app-specific roles with permissions
+  const adminRole = await fortress.iam.createRole('admin', [
+    { resource: 'user', action: 'list' },
+    { resource: 'user', action: 'create' },
+    { resource: 'user', action: 'read' },
+    { resource: 'user', action: 'impersonate' },
+    { resource: 'group', action: 'create' },
+    { resource: 'group', action: 'manage' },
+    { resource: 'audit-log', action: 'read' },
+    { resource: 'webhook', action: 'manage' },
+    { resource: 'lockout', action: 'read' },
+    { resource: 'lockout', action: 'manage' },
+  ], 'Full admin access');
+
+  const viewerRole = await fortress.iam.createRole('viewer', [
+    { resource: 'user', action: 'list' },
+    { resource: 'user', action: 'read' },
+  ], 'Read-only access');
+
+  // Bind roles
+  await fortress.iam.bindRole('USER', admin.id, adminRole.id);
+  await fortress.iam.bindRole('USER', user.id, viewerRole.id);
+
+  // Create a group and add admin
+  const engineering = await fortress.iam.createGroup('engineering', 'Engineering team');
+  await fortress.iam.addUserToGroup(engineering.id, admin.id);
+
+  // Create a tenant and add admin
+  const tenant = await fortress.plugins.tenancy.createTenant({ name: 'Acme Corp', taxId: 'acme' });
+  await fortress.plugins.tenancy.addUserToTenant(admin.id, tenant.id);
+
+  // Register a webhook endpoint
+  await fortress.plugins.webhook.registerEndpoint(
+    'https://example.com/webhooks',
+    ['LOGIN_SUCCESS', 'REGISTER'],
+    'webhook-signing-secret',
+  );
+
+  // ── Typed in-process client ─────────────────────────────────────────
+  // `fortress.call.*` is the typed client surface. Each handler is
+  // inferred from its EndpointDefinition: input shape matches the body/
+  // query/params schemas, output matches the 2xx response schema.
+  //
+  //   const { accessToken, user } = await fortress.call.login({
+  //     identifier: 'admin@example.com',
+  //     password: 'Password123!',
+  //   });
+  //
+  // Under the hood, each call serializes to a Request, runs through
+  // fortress.handleRequest (full pipeline: middleware → token verify →
+  // RBAC → validation → dispatch), and parses the JSON body. Non-2xx
+  // responses throw a `FortressError` with the original `code`/`statusCode`.
+  // Same type surface a future over-the-wire client SDK will expose.
+
+  console.warn('');
+  console.warn('╔══════════════════════════════════════════════╗');
+  console.warn('║  Fortress Example App                        ║');
+  console.warn('╠══════════════════════════════════════════════╣');
+  console.warn('║  Admin:  admin@example.com / Password123!    ║');
+  console.warn('║  User:   user@example.com  / Password123!    ║');
+  console.warn('║  Tenant: Acme Corp (taxId: acme)             ║');
+  console.warn('║  Group:  engineering                          ║');
+  console.warn('╠══════════════════════════════════════════════╣');
+  console.warn('║  http://localhost:3000                        ║');
+  console.warn('╚══════════════════════════════════════════════╝');
+  console.warn('');
+}
+
+seed().catch(console.error);
+
+export default {
+  port: 3000,
+  fetch: app.fetch,
+};