@bajustone/fortress 1.0.0-rc.1

package/docs/admin-recipes.md

@@ -0,0 +1,227 @@
+# Admin and operator recipes
+
+Fortress is API-first by design — there is no reference UI shipped with
+the library. The `admin` plugin (`@bajustone/fortress/plugins/admin`)
+already exposes IAM CRUD as HTTP routes; this page collects the
+**operator-workflow recipes** that combine those routes (and a few
+service-layer helpers) into common admin tasks.
+
+Drop these into your own admin app (Next.js / SvelteKit / Hono) or wire
+them to a CLI. Every recipe is plain HTTP or `fortress.iam.*` /
+`fortress.plugins.*` calls — no extra dependencies beyond what's
+already installed.
+
+## Setup
+
+Mount the admin plugin so the IAM endpoints exist:
+
+```ts
+import { admin } from '@bajustone/fortress/plugins/admin';
+import { apiKey } from '@bajustone/fortress/plugins/api-key';
+
+createFortress({
+  // ...
+  plugins: [
+    admin({ apiKeyRoutes: true }),  // also mounts admin api-key routes
+    apiKey({ prefix: 'fortress', routes: true }),
+    // ... rest of your plugins
+  ],
+});
+```
+
+Bootstrap the first admin user once:
+
+```sh
+curl -X POST https://your-app/iam/admin/bootstrap \
+  -H 'Authorization: Bearer <a freshly-issued JWT for the user>' \
+  -H 'Content-Type: application/json' \
+  -d '{}'
+```
+
+This creates the `fortress-admin` role with every `fortress:*`
+permission and binds it to the calling user. Run once per deployment;
+subsequent calls 409 unless the role is empty.
+
+## Users
+
+Standard auth endpoints handle most user lifecycle:
+
+| Task | API |
+|---|---|
+| Create user | `POST /auth/register` or `fortress.auth.createUser(...)` |
+| Disable user | `fortress.auth.setUserActive(userId, false)` |
+| Reset password (admin) | `fortress.auth.setUserPassword(userId, newPassword)` |
+| Force email re-verification | clear `email_verified` row, call email-verification plugin's `send` method |
+| Delete user | `fortress.auth.deleteUser(userId)` — cascades to sessions, role bindings, direct perms |
+
+## Roles, groups, permissions
+
+`@bajustone/fortress/plugins/admin` routes:
+
+```
+POST   /iam/roles                          create role
+DELETE /iam/roles/:id                      delete role
+GET    /iam/roles                          list roles
+GET    /iam/permissions                    list permissions
+POST   /iam/permissions/bind/user          bind a permission to a user
+POST   /iam/permissions/bind/group         bind to a group
+POST   /iam/permissions/bind/service-account  bind to a service account
+DELETE /iam/permissions/bind/*             unbind variants
+POST   /iam/role-bindings/user             bind a role to a user
+POST   /iam/role-bindings/group            bind a role to a group
+POST   /iam/role-bindings/service-account  bind a role to a service account
+DELETE /iam/role-bindings/*                unbind variants
+POST   /iam/groups                         create group
+POST   /iam/groups/:id/members             add user to group
+DELETE /iam/groups/:id/members/:userId     remove user from group
+```
+
+All require an authenticated user with the matching `fortress:*`
+permission (e.g. `fortress:createRole`). The admin bootstrap binds them
+to the first admin.
+
+For declarative management (recommended for production), use
+**policy-as-code** instead — see [docs/policy-as-code.md](./policy-as-code.md).
+
+## Sessions and revocation
+
+```ts
+// List sessions for a user (callable from an admin route).
+const sessions = await fortress.auth.listSessions(userId);
+
+// Revoke a single session.
+await fortress.auth.revokeSession(userId, sessionId);
+
+// Revoke every refresh token for a user (forces logout everywhere on
+// next access-token expiry; access tokens are stateless so they remain
+// valid until they expire — keep TTL short).
+await fortress.auth.revokeAllSessions(userId);
+```
+
+To force-logout immediately even before access-token expiry, set the
+user inactive (`setUserActive(userId, false)`); the auth pipeline
+rejects requests whose JWT subject resolves to an inactive user.
+
+## Service accounts and API keys
+
+Service accounts are first-class IAM subjects. They have no sessions —
+they authenticate via API keys.
+
+```ts
+// Create the service account.
+const sa = await fortress.iam.createServiceAccount({
+  name: 'ci-bot',
+  displayName: 'CI Bot',
+});
+
+// Bind a role to it.
+const role = (await fortress.iam.getRoles()).find(r => r.name === 'editor')!;
+await fortress.iam.bindRoleToServiceAccount(sa.id, role.id);
+
+// Mint an API key for the service account (admin plugin route, requires apiKey:manage).
+const res = await fetch(`/admin/service-accounts/${sa.id}/api-keys`, {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${adminJwt}` },
+  body: JSON.stringify({ name: 'ci-pipeline' }),
+});
+const { key } = await res.json();  // returned ONCE; store in secret manager
+```
+
+API keys carry `subjectType: 'SERVICE_ACCOUNT'`; the resolver populates
+the request principal so RBAC works the same as for users.
+
+## OAuth clients
+
+OAuth clients have secrets; manage via the OAuth plugin's admin
+methods (`fortress.plugins.oauth.createClient(...)`,
+`updateClient(...)`, `deleteClient(...)`). Secrets are returned **once**
+on create — re-issue with `rotateClientSecret(clientId)` and update RPs
+out-of-band.
+
+For policy-as-code: OAuth clients are intentionally NOT covered by the
+policy file (secrets do not belong in a checked-in JSON file). Track
+them in your secret manager and run create/update via a one-off script.
+
+## Audit logs
+
+```ts
+// Read a page of audit log entries.
+const page = await fortress.plugins['audit-log'].listEntries({
+  limit: 100,
+  offset: 0,
+  // optional filters:
+  eventType: 'LOGIN_FAILURE',
+  userId,
+  after: new Date(Date.now() - 7 * 24 * 3600 * 1000),
+});
+
+// Verify the hash chain (when hashChain: true was passed at plugin construction).
+const verified = await fortress.plugins['audit-log'].verifyChain();
+if (!verified.ok) {
+  console.error(`Chain broken at index ${verified.brokenAt}`);
+}
+```
+
+The verifier walks every row and recomputes the SHA-256 chain. Run as a
+scheduled job; alert when `ok === false`.
+
+## Permission debugging — "why does user X have permission Y?"
+
+Fortress ships `explainPermission` for this exact question:
+
+```ts
+import { explainPermission } from '@bajustone/fortress';
+
+const explain = await explainPermission(
+  fortress.config.database,
+  fortress.iam,
+  { type: 'USER', id: 42 },
+  'article',
+  'delete',
+);
+
+console.log(explain.allowed);          // true | false
+console.log(explain.sources);          // every grant + its source (role / direct / group)
+console.log(explain.roleBindings);     // roles the user is bound to
+console.log(explain.groupMemberships); // groups the user belongs to
+```
+
+Each source carries enough context to point a human at the misconfig:
+
+```ts
+explain.sources[0]
+// {
+//   via: 'role',
+//   role: 'editor',
+//   group: { id: 7, name: 'eng' },          // when inherited via group
+//   permission: { id, resource, action, effect, conditions, description }
+// }
+```
+
+With `rbac.evaluationMode: 'deny-overrides'`, any matching `DENY` source
+flips `allowed` to `false` regardless of matching `ALLOW` sources. In the
+default `allow-only` mode, DENY entries are intentionally ignored. Wildcard permissions
+(`resource: '*'`, `action: '*'`) match every check; you'll see them
+listed as sources when they apply.
+
+Wrap this in an admin route and you have a one-click "why does this
+permission resolve the way it does" debugger.
+
+## Building an admin console UI
+
+The library doesn't ship one. Wire the routes above to your framework
+of choice; common starting points:
+
+- **Hono + React/HTMX:** drop the existing admin plugin routes under
+  `/admin/*`, build a small SPA against them. The `mountFortress` call
+  already mounts every IAM route.
+- **SvelteKit:** use the SvelteKit adapter; build admin pages under
+  `/routes/admin/+page.server.ts` that call `fortress.iam.*` directly.
+  No HTTP roundtrip needed.
+- **CLI:** wrap the IAM methods in a thin commander/citty CLI; useful
+  for one-off ops and for environments without admin UI access.
+
+In every case, gate the routes/pages with `permission('fortress', '...')`
+declarations on the endpoint (`fortress` will RBAC-check before
+dispatch) or `fortress.iam.checkPermission(subject, 'fortress', '...')`
+in your handler.

package/docs/architecture.md

@@ -0,0 +1,434 @@
+# Architecture and plugin authoring
+
+## Request pipeline
+
+Every framework adapter delegates Fortress-owned routes to:
+
+```typescript
+const response = await fortress.handleRequest(request);
+```
+
+The pipeline runs in this order:
+
+1. `before-auth` plugin middleware
+2. CSRF for unsafe cookie-authenticated requests
+3. route matching
+4. plugin principal resolvers, then JWT fallback
+5. `after-auth` plugin middleware
+6. endpoint permission check
+7. `after-rbac` plugin middleware
+8. body, query, and parameter validation
+9. endpoint dispatch
+10. auth-cookie serialization
+
+Use the same pipeline without an HTTP server:
+
+```typescript
+const result = await fortress.call.login({
+  identifier: 'alice@example.com',
+  password: 'correct-horse-battery-staple',
+});
+```
+
+Direct service calls skip HTTP middleware, CSRF, route permissions, and request schemas:
+
+```typescript
+await fortress.auth.login(identifier, password);
+await fortress.iam.checkPermission(subject, 'post', 'read');
+```
+
+Auth and IAM service hooks and observers still run.
+
+## Instance composition
+
+`createFortress()`:
+
+1. validates JWT keys and session options;
+2. wraps the database with observability;
+3. creates auth and IAM services;
+4. registers plugin methods, hooks, middleware, routes, and principal resolvers;
+5. merges core, plugin, and host endpoint metadata;
+6. builds `manifest`, `handleRequest`, and `call`.
+
+```typescript
+const fortress = createFortress({ database, jwt: { key }, plugins });
+
+fortress.auth;
+fortress.iam;
+fortress.plugins;
+fortress.call;
+fortress.endpoints;
+fortress.manifest;
+fortress.handleRequest;
+fortress.migrate;
+fortress.syncPermissionsFromManifest;
+fortress.toOpenAPI;
+```
+
+Startup rejects:
+
+- JWT keys shorter than 32 UTF-8 bytes;
+- non-positive `jwt.session` values;
+- duplicate plugin names;
+- duplicate routes or call keys between plugins;
+- `security: ['none']` combined with a permission;
+- use of the reserved `__host` plugin name when top-level `routes` are set.
+
+A plugin may intentionally replace a core route. Two plugins cannot own the same route.
+
+## Endpoint metadata
+
+An endpoint definition supplies request schemas, response schemas, security, IAM permission, OpenAPI metadata, and a handler name:
+
+```typescript
+import { endpoint, obj, str } from '@bajustone/fortress';
+
+const createPost = endpoint('POST', '/posts')
+  .summary('Create a post')
+  .security('bearer')
+  .permission('post', 'create')
+  .body(obj({ title: str() }, 'title'))
+  .response(201, 'Created', obj({ id: str() }, 'id'))
+  .handler('createPost')
+  .build();
+```
+
+Register application-owned metadata at the top level:
+
+```typescript
+const fortress = createFortress({
+  database,
+  jwt: { key },
+  routes: { createPost },
+});
+```
+
+Top-level routes appear in `fortress.endpoints`, the manifest, OpenAPI, and protection helpers. The host router still dispatches them. They do not create `fortress.call` methods.
+
+To create a mounted and callable endpoint, define a plugin with matching `routes` and `methods` keys.
+
+## Write a route plugin
+
+```typescript
+import {
+  endpoint,
+  obj,
+  str,
+  type FortressPlugin,
+} from '@bajustone/fortress';
+
+const greetingEndpoint = endpoint('POST', '/greetings')
+  .security('bearer')
+  .permission('greeting', 'create')
+  .body(obj({ name: str() }, 'name'))
+  .response(200, 'Greeting', obj({ message: str() }, 'message'))
+  .handler('createGreeting')
+  .build();
+
+export function greetings() {
+  return {
+    name: 'greetings',
+    routes: { createGreeting: greetingEndpoint },
+    methods: () => ({
+      async createGreeting(input: { name: string }) {
+        return { message: `Hello ${input.name}` };
+      },
+    }),
+  } as const satisfies FortressPlugin;
+}
+```
+
+```typescript
+const fortress = createFortress({
+  database,
+  jwt: { key },
+  plugins: [greetings()] as const,
+});
+
+await fortress.call.createGreeting(
+  { name: 'Alice' },
+  { headers: { authorization: `Bearer ${token}` } },
+);
+```
+
+The route record key, endpoint handler, and method key must match.
+
+## Add lifecycle hooks
+
+```typescript
+export function loginPolicy(): FortressPlugin {
+  return {
+    name: 'login-policy',
+    hooks: {
+      async beforeLogin(ctx) {
+        if (await isBlocked(ctx.email)) {
+          return {
+            stop: true,
+            response: { error: 'ACCOUNT_BLOCKED' },
+          };
+        }
+      },
+      async onLoginFailure(ctx) {
+        await recordFailure(ctx.identifier);
+      },
+      async afterLogin(ctx, result) {
+        await recordSuccess(result.user.id);
+        ctx.responseHeaders.set('X-Auth-Method', result.method);
+        return result;
+      },
+    },
+  };
+}
+```
+
+Hooks run in plugin registration order.
+
+Use these before token issuance:
+
+- `beforeLogin`
+- `beforeRegister`
+- `beforeTokenRefresh`
+- `postAuthGate`
+
+Use these for committed side effects:
+
+- `afterLogin`
+- `afterRegister`
+- `afterTokenRefresh`
+- `onLoginFailure`
+
+A thrown `afterLogin`, `afterRegister`, or `afterTokenRefresh` hook is logged and skipped. It cannot roll back an issued session or created user. A plugin that must deny authentication belongs before token issuance.
+
+## Add a pending authentication gate
+
+```typescript
+import { Errors, type FortressPlugin } from '@bajustone/fortress';
+
+export function securityQuestion(): FortressPlugin {
+  return {
+    name: 'security-question',
+    hooks: {
+      postAuthGate: {
+        reason: 'two-factor',
+        maxAttempts: 5,
+        cooldownSeconds: 60,
+        async evaluate({ user }) {
+          if (await requiresQuestion(user.id))
+            return { pluginData: { prompt: 'First school?' } };
+        },
+        async verify({ user }, completion) {
+          if (!await checkAnswer(user.id, completion))
+            throw Errors.unauthorized('Invalid answer');
+        },
+      },
+    },
+  };
+}
+```
+
+A gate returns a pending auth result before tokens exist:
+
+```typescript
+const result = await fortress.auth.login(email, password);
+
+if (result.status === 'pending') {
+  const completed = await fortress.auth.completePendingAuth(
+    result.pending.continuationToken,
+    answer,
+  );
+}
+```
+
+Use an existing `PendingReason` or add a new reason to the core union before publishing a plugin.
+
+## Resolve a custom credential
+
+Principal resolvers run in plugin order before JWT verification. Return `null` when the credential is absent so the next resolver can try.
+
+```typescript
+export function signedRequest(): FortressPlugin {
+  return {
+    name: 'signed-request',
+    async resolvePrincipal(request) {
+      const signature = request.headers.get('X-Signature');
+      if (!signature)
+        return null;
+
+      const serviceAccountId = await verifySignature(signature, request);
+      return {
+        subject: { type: 'SERVICE_ACCOUNT', id: serviceAccountId },
+        scopes: ['orders:write'],
+      };
+    },
+  };
+}
+```
+
+Scopes narrow the subject's IAM permissions. They never grant a permission the subject does not already have.
+
+## Add request middleware
+
+```typescript
+export function requestAudit(): FortressPlugin {
+  return {
+    name: 'request-audit',
+    middleware: [{
+      path: '/orders/*',
+      position: 'after-rbac',
+      async handler(_plugin, context, next) {
+        await audit(
+          context.fortressSubject,
+          new URL(context.request.url).pathname,
+        );
+        await next();
+      },
+    }],
+  };
+}
+```
+
+Positions:
+
+| Position | Identity | Permission result | Use |
+|---|---:|---:|---|
+| `before-auth` | no | no | rate limits, request normalization |
+| `after-auth` | yes | no | account state, identity-aware controls |
+| `after-rbac` | yes | yes | authorized audit and request context |
+
+## Extend JWT claims
+
+```typescript
+export function tenantClaims(): FortressPlugin {
+  return {
+    name: 'tenant-claims',
+    async enrichTokenClaims(userId, { db }) {
+      const membership = await findMembership(db, userId);
+      return {
+        tenantId: membership.id,
+        tenantCode: membership.code,
+      };
+    },
+  };
+}
+```
+
+Claims are shallow-merged in plugin order. Later plugins overwrite duplicate keys and emit a development warning.
+
+## Scope database access
+
+`scopeRules` adds model filters. `wrapAdapter` replaces the request-scoped adapter when a plugin needs transaction or schema behavior.
+
+```typescript
+export function organizationScope(): FortressPlugin {
+  return {
+    name: 'organization-scope',
+    async scopeRules(userId, model) {
+      if (model !== 'post')
+        return null;
+
+      const organizationId = await organizationFor(userId);
+      return {
+        filters: [{ field: 'organizationId', operator: '=', value: organizationId }],
+        defaults: { organizationId },
+      };
+    },
+  };
+}
+```
+
+Read the scoped adapter from framework context:
+
+```typescript
+const db = await getScopedDb(c, 'post');
+const posts = await db.findMany({ model: 'post' });
+```
+
+Use the bundled [data-isolation plugin](plugins/data-isolation.md) for row-level filtering and [tenancy plugin](plugins/tenancy.md) for PostgreSQL schema isolation.
+
+## Database contract
+
+Plugins use the same adapter as core:
+
+```typescript
+interface DatabaseAdapter {
+  create(args): Promise<unknown>;
+  findOne(args): Promise<unknown | null>;
+  findMany(args): Promise<unknown[]>;
+  update(args): Promise<unknown | null>;
+  delete(args): Promise<void>;
+  count(args): Promise<number>;
+  transaction<T>(fn: (tx: DatabaseAdapter) => Promise<T>): Promise<T>;
+  rawQuery?<T>(sql: string, params?: unknown[]): Promise<T[]>;
+  dialect?: 'sqlite' | 'pg';
+}
+```
+
+Portable `rawQuery` SQL uses `?` placeholders. The adapter translates them for its driver.
+
+Core operators:
+
+```typescript
+'=' | '!=' | 'in' | 'gt' | 'lt' | 'gte' | 'lte' | 'isNull'
+```
+
+Adapters may support additional operators. The Drizzle adapter also supports `like`.
+
+## Auth data flow
+
+### Login
+
+1. Run `beforeLogin` hooks.
+2. Resolve the login identifier.
+3. verify user state and password with timing-safe miss behavior.
+4. run post-auth gates.
+5. enrich claims.
+6. create the access token and refresh-token family.
+7. run failure-contained after hooks.
+8. emit auth observers.
+
+### Refresh
+
+1. hash and find the refresh token;
+2. reject expiry, inactivity, absolute lifetime, or fingerprint policy failures;
+3. detect reuse and revoke the family;
+4. rotate the token in the same family;
+5. refresh claims and session metadata;
+6. run failure-contained after hooks;
+7. return the new pair.
+
+The database stores refresh-token hashes, not raw tokens.
+
+## IAM data flow
+
+```typescript
+await fortress.iam.checkPermission(subject, resource, action, context);
+```
+
+The check:
+
+1. verifies that a user subject still exists and is active;
+2. loads global permissions from the optional cache or tenant permissions from the database;
+3. collects role, group, and direct grants;
+4. narrows with credential scopes;
+5. evaluates resource/action wildcards and conditions;
+6. applies `allow-only` or `deny-overrides`;
+7. emits a synchronous permission-check event.
+
+Tenant checks bypass the global permission cache. User activation is checked before cached grants, so deactivation denies immediately.
+
+## Package boundaries
+
+| Entry point | Purpose |
+|---|---|
+| `@bajustone/fortress` | core, schemas, endpoints, policy, migrations |
+| `@bajustone/fortress/hono` | Hono mount, middleware, validation, protection |
+| `@bajustone/fortress/express` | Express mount, middleware, validation, protection |
+| `@bajustone/fortress/sveltekit` | handle hook, actions, locals, validation, protection |
+| `@bajustone/fortress/drizzle` | adapter, SQLite/PG schemas, DB error mapping |
+| `@bajustone/fortress/drizzle/pg` | PostgreSQL schema only |
+| `@bajustone/fortress/testing` | in-memory adapter and drift checks |
+| `@bajustone/fortress/otel` | OpenTelemetry provider adapter |
+| `@bajustone/fortress/fetcher` | outbound client and schema tooling |
+| `@bajustone/fortress/plugins/*` | optional plugins |
+
+Core does not import framework adapters. Framework adapters only translate their request/response APIs to the web-standard core.