@bajustone/fortress 1.0.0-rc.1

package/docs/plugins/data-isolation.md

@@ -0,0 +1,186 @@
+# Data Isolation Plugin
+
+## Overview
+
+The `data-isolation` plugin adds row-level data isolation to Fortress. It works with any database by automatically injecting WHERE filters on reads and default values on creates based on configurable scopes.
+
+Unlike the `tenancy` plugin (which uses PostgreSQL schema-per-tenant isolation), this plugin operates at the row level and supports any database backend.
+
+Runtime note: scoped bypass helpers (`withoutScope()` and `unscoped()`) use
+`node:async_hooks` / `AsyncLocalStorage` to keep bypass state local to the
+current async request. Use this plugin in Node/Bun-compatible runtimes that
+provide `node:async_hooks`; edge/browser-like runtimes may need a custom
+request-context wrapper or should avoid those bypass helpers.
+
+## Installation
+
+Import the `dataIsolation` factory and pass it in the `plugins` array when creating a Fortress instance:
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { dataIsolation } from '@bajustone/fortress/plugins/data-isolation';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    dataIsolation({
+      scopes: [
+        {
+          name: 'organization',
+          field: 'orgId',
+          models: ['post', 'comment'],
+          resolveValue: async (userId, ctx) => {
+            const user = await ctx.db.findOne({
+              model: 'user',
+              where: [{ field: 'id', operator: '=', value: userId }],
+            });
+            return user?.orgId;
+          },
+        },
+      ],
+    }),
+  ],
+});
+```
+
+Once registered, methods are available at `fortress.plugins['data-isolation']` with full type safety.
+
+## Configuration
+
+The `DataIsolationConfig` requires a `scopes` array:
+
+| Option | Type | Required | Description |
+|---|---|---|---|
+| `scopes` | `DataIsolationScope[]` | Yes | Array of scope definitions that control row-level filtering. |
+| `unresolvedScope` | `'deny' \| 'skip'` | No | Behavior for a nullish applicable scope. Defaults to secure `'deny'`. `'skip'` is unsafe legacy compatibility mode. |
+
+Each `DataIsolationScope` has the following fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `name` | `string` | Scope name for identification and bypass control. |
+| `field` | `string` | Column name that holds the scoping value in the target tables. |
+| `models` | `string[]` | Which models (tables) this scope applies to. Use `['*']` for all models. |
+| `resolveValue` | `(userId: string, ctx: PluginContext) => Promise<unknown>` | Async function that returns the current user's value for this scope. |
+
+## How It Works
+
+The plugin implements `scopeRules`, which the database adapter calls on every query:
+
+- **Reads** (`findOne`, `findMany`, `count`) -- A WHERE filter is added: `WHERE {field} = {resolvedValue}`.
+- **Creates** (`create`) -- The scoping field is set as a default value: `data.{field} = {resolvedValue}`.
+
+If an applicable `resolveValue` returns `null` or `undefined`, the plugin fails closed by default with a `FORBIDDEN` error. Scope resolution happens before a scoped adapter is returned, so both reads and creates are denied rather than becoming unscoped or accepting caller-controlled scope fields.
+
+For migration only, `unresolvedScope: 'skip'` restores the unsafe legacy behavior of omitting an unresolved filter. This can expose every row and permit cross-scope creates; do not use it as an authorization bypass. Use the explicit async-context-local `withoutScope()` or `unscoped()` helpers for reviewed administrative operations.
+
+```ts
+// Unsafe legacy compatibility only — remove after scope assignments are complete.
+dataIsolation({
+  unresolvedScope: 'skip',
+  scopes: [/* ... */],
+});
+```
+
+### Example behavior
+
+With a scope `{ name: 'organization', field: 'orgId', models: ['post'] }` and a user whose `orgId` is `'acme'`:
+
+```ts
+// This query:
+db.findMany({ model: 'post' });
+// Becomes: SELECT * FROM post WHERE orgId = 'acme'
+
+// This create:
+db.create({ model: 'post', data: { title: 'Hello' } });
+// Becomes: INSERT INTO post (title, orgId) VALUES ('Hello', 'acme')
+```
+
+## API Reference
+
+| Method | Signature | Returns |
+|---|---|---|
+| `withoutScope` | `<T>(scopeName: string, fn: () => Promise<T>)` | `Promise<T>` |
+| `unscoped` | `<T>(fn: () => Promise<T>)` | `Promise<T>` |
+
+### withoutScope
+
+Temporarily bypasses a specific named scope. Queries within the callback run without that scope's filter:
+
+```ts
+await fortress.plugins['data-isolation'].withoutScope('organization', async () => {
+  // Queries here run without the 'organization' filter
+  const allPosts = await db.findMany({ model: 'post' });
+});
+```
+
+### unscoped
+
+Temporarily bypasses all scopes. Use with caution -- no row-level isolation is applied within the callback:
+
+```ts
+await fortress.plugins['data-isolation'].unscoped(async () => {
+  // No scoping at all
+  const everything = await db.findMany({ model: 'post' });
+});
+```
+
+## Using Scoped DB in Middleware
+
+In Hono and Express, use the `getScopedDb` helper to get a database adapter with isolation applied:
+
+```ts
+app.get('/api/posts', async (c) => {
+  const scopedDb = await getScopedDb(c, 'post');
+  const posts = await scopedDb.findMany({ model: 'post' });
+  // Only returns posts the current user has access to
+});
+```
+
+## Example
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { dataIsolation } from '@bajustone/fortress/plugins/data-isolation';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    dataIsolation({
+      scopes: [
+        {
+          name: 'organization',
+          field: 'orgId',
+          models: ['post', 'comment', 'invoice'],
+          resolveValue: async (userId, ctx) => {
+            const user = await ctx.db.findOne({
+              model: 'user',
+              where: [{ field: 'id', operator: '=', value: userId }],
+            });
+            return user?.orgId;
+          },
+        },
+        {
+          name: 'department',
+          field: 'deptId',
+          models: ['ticket'],
+          resolveValue: async (userId, ctx) => {
+            const user = await ctx.db.findOne({
+              model: 'user',
+              where: [{ field: 'id', operator: '=', value: userId }],
+            });
+            return user?.deptId;
+          },
+        },
+      ],
+    }),
+  ],
+});
+
+// Admin operation that needs cross-org visibility:
+await fortress.plugins['data-isolation'].withoutScope('organization', async () => {
+  const allInvoices = await db.findMany({ model: 'invoice' });
+});
+```

package/docs/plugins/email-verification.md

@@ -0,0 +1,121 @@
+# Email verification
+
+Register the plugin and deliver raw verification tokens through your mail provider:
+
+```typescript
+import { emailVerification } from '@bajustone/fortress/plugins/email-verification';
+
+const fortress = createFortress({
+  database,
+  jwt: { key },
+  plugins: [emailVerification({
+    tokenExpirySeconds: 24 * 60 * 60,
+    requireVerification: true,
+    onSendVerification: async (email, token) => {
+      const url = `https://app.example.com/verify?token=${encodeURIComponent(token)}`;
+      await mailer.send({ to: email, text: url });
+    },
+  })] as const,
+});
+```
+
+| Option | Default | Use |
+|---|---:|---|
+| `tokenExpirySeconds` | `86400` | Token lifetime |
+| `requireVerification` | `true` | Hold login before session issuance |
+| `onSendVerification` | — | Deliver the raw token |
+
+Fortress stores only the SHA-256 token hash.
+
+## Registration
+
+Creating a user creates and sends a token:
+
+```typescript
+await fortress.auth.createUser({
+  email: 'alice@example.com',
+  name: 'Alice',
+  password: 'correct-horse-battery-staple',
+});
+```
+
+`afterRegister` is a committed side-effect hook. If token creation or delivery throws, Fortress logs the failure and keeps the created user. Retry delivery with `sendVerification`:
+
+```typescript
+await fortress.plugins['email-verification'].sendVerification(userId);
+```
+
+Send a changed-address token without changing the account immediately:
+
+```typescript
+await fortress.plugins['email-verification'].sendVerification(
+  userId,
+  'new-address@example.com',
+);
+```
+
+The new address is adopted only after that token is verified.
+
+## Complete a pending login
+
+With `requireVerification: true`, correct primary credentials return `pending` instead of issuing tokens:
+
+```typescript
+const login = await fortress.auth.login(email, password);
+
+if (login.status === 'pending' && login.pending.reason === 'email-verification') {
+  const result = await fortress.plugins['email-verification'].completeVerification(
+    login.pending.continuationToken,
+    tokenFromEmail,
+    { ipAddress, userAgent },
+  );
+
+  if (result.status === 'success') {
+    result.accessToken;
+    result.refreshToken;
+  }
+}
+```
+
+`completeVerification` consumes both the single-use continuation and the email token, then reruns any remaining post-auth gates before issuing a session.
+
+## Verify outside login
+
+Use `verify` for a standalone verification page:
+
+```typescript
+const verified = await fortress.plugins['email-verification'].verify(tokenFromUrl);
+// { userId, email }
+```
+
+A token is accepted only when it:
+
+- matches a stored hash;
+- has not been used;
+- has not expired;
+- belongs to the pending user when completing login.
+
+Consumption and the user update run transactionally. Invalid, used, expired, or mismatched tokens throw `NOT_FOUND` without revealing which check failed.
+
+## Methods
+
+```typescript
+interface EmailVerificationMethods {
+  sendVerification(
+    userId: string,
+    email?: string,
+  ): Promise<{ sent: true }>;
+
+  verify(
+    rawToken: string,
+  ): Promise<{ userId: string; email: string }>;
+
+  completeVerification(
+    continuationToken: string,
+    verificationToken: string,
+    meta?: RequestMeta,
+  ): Promise<AuthResult>;
+}
+```
+
+The plugin owns no HTTP routes. Use its methods in host routes. The core auth pipeline owns pending-auth continuation behavior.

package/docs/plugins/magic-link.md

@@ -0,0 +1,123 @@
+# Magic Link Plugin
+
+## Overview
+
+The `magic-link` plugin adds passwordless authentication via one-time email tokens to Fortress. Users receive a time-limited link that logs them in without a password. If no account exists for the given email, one is created automatically (JIT provisioning).
+
+Tokens are generated using cryptographically secure random bytes and hashed with SHA-256 before storage. Each token is single-use.
+
+## Installation
+
+Import the `magicLink` factory and pass it in the `plugins` array when creating a Fortress instance:
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { magicLink } from '@bajustone/fortress/plugins/magic-link';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    magicLink({
+      tokenExpirySeconds: 600,
+      onSendMagicLink: async (email, token) => {
+        await sendEmail(email, `Login: https://myapp.com/auth/magic?token=${token}`);
+      },
+    }),
+  ],
+});
+```
+
+Once registered, methods are available at `fortress.plugins['magic-link']` with full type safety.
+
+## Configuration
+
+All fields on `MagicLinkConfig` are optional:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `tokenExpirySeconds` | `number` | `600` (10 minutes) | How long a magic link token remains valid, in seconds. |
+| `onSendMagicLink` | `(email: string, token: string) => Promise<void>` | `undefined` | Callback invoked when a magic link token is created. Use this to send the email containing the link. |
+
+## API Reference
+
+| Method | Signature | Returns |
+|---|---|---|
+| `sendMagicLink` | `(email: string)` | `Promise<{ sent: true }>` |
+| `verify` | `(rawToken: string, meta?: RequestMeta)` | `Promise<AuthResult>` |
+
+### sendMagicLink
+
+Generates a magic link token and delivers it via the `onSendMagicLink` callback:
+
+```ts
+await fortress.plugins['magic-link'].sendMagicLink('alice@example.com');
+```
+
+The user does not need to exist in the database. If they do not exist, the account is created when the link is verified.
+
+### verify
+
+Atomically consumes a magic-link token and returns the unified auth result:
+
+```ts
+const result = await fortress.plugins['magic-link'].verify(rawToken);
+
+if (result.status === 'success') {
+  console.log(result.user.id);
+  console.log(result.user.email);
+  console.log(result.accessToken, result.refreshToken);
+}
+else if (result.status === 'pending') {
+  // Another configured post-auth gate must complete first.
+  console.log(result.pending.reason, result.pending.continuationToken);
+}
+```
+
+The equivalent HTTP endpoint is `POST /auth/magic-link/verify` with `{ token }`.
+
+This method:
+1. Hashes the raw token and looks it up in the database.
+2. Checks that the token has not been used and has not expired.
+3. Marks the token as used (`usedAt` timestamp).
+4. Finds the user by email, or creates a new account if none exists (JIT provisioning).
+5. Runs every configured post-auth gate and issues an access/refresh session only when they all pass.
+
+Throws:
+- `NotFound` -- Invalid or unknown token.
+- `BadRequest` -- Token already used.
+- `BadRequest` -- Token expired.
+
+## Example
+
+```ts
+import { createFortress } from '@bajustone/fortress';
+import { magicLink } from '@bajustone/fortress/plugins/magic-link';
+
+const fortress = createFortress({
+  jwt: { key: 'your-secret-at-least-32-bytes!!' },
+  database: adapter,
+  plugins: [
+    magicLink({
+      tokenExpirySeconds: 300, // 5 minutes
+      onSendMagicLink: async (email, token) => {
+        await mailer.send({
+          to: email,
+          subject: 'Your login link',
+          html: `<a href="https://myapp.com/auth/magic?token=${token}">Click to sign in</a>`,
+        });
+      },
+    }),
+  ],
+});
+
+// Step 1: User requests a magic link
+await fortress.plugins['magic-link'].sendMagicLink('alice@example.com');
+
+// Step 2: User clicks the link -- your handler calls verify
+const result = await fortress.plugins['magic-link'].verify(tokenFromUrl);
+
+if (result.status === 'success') {
+  // The user is authenticated with result.accessToken/result.refreshToken.
+}
+```