@bajustone/fortress 1.0.0-rc.1

package/src/plugins/data-isolation/data-isolation.test.ts

@@ -0,0 +1,197 @@
+import type { PluginContext } from '../../core/plugin';
+import { describe, expect, it } from 'vitest';
+import { createTestAdapter } from '../../testing';
+import { dataIsolation } from './index';
+
+describe('data-isolation plugin', () => {
+  it('generates scope rules for matching models', async () => {
+    const db = createTestAdapter();
+    const plugin = dataIsolation({
+      scopes: [{
+        name: 'site',
+        field: 'siteId',
+        models: ['sale', 'inventory'],
+        resolveValue: async () => 3,
+      }],
+    });
+
+    const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+    const rules = await plugin.scopeRules!('1', 'sale', ctx);
+
+    expect(rules).not.toBeNull();
+    expect(rules!.filters).toEqual([{ field: 'siteId', operator: '=', value: 3 }]);
+    expect(rules!.defaults).toEqual({ siteId: 3 });
+  });
+
+  it('returns null for non-matching models', async () => {
+    const db = createTestAdapter();
+    const plugin = dataIsolation({
+      scopes: [{
+        name: 'site',
+        field: 'siteId',
+        models: ['sale'],
+        resolveValue: async () => 3,
+      }],
+    });
+
+    const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+    const rules = await plugin.scopeRules!('1', 'user', ctx);
+
+    expect(rules).toBeNull();
+  });
+
+  it('stacks multiple scopes for same model', async () => {
+    const db = createTestAdapter();
+    const plugin = dataIsolation({
+      scopes: [
+        { name: 'org', field: 'orgId', models: ['sale'], resolveValue: async () => 7 },
+        { name: 'site', field: 'siteId', models: ['sale'], resolveValue: async () => 3 },
+      ],
+    });
+
+    const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+    const rules = await plugin.scopeRules!('1', 'sale', ctx);
+
+    expect(rules!.filters).toHaveLength(2);
+    expect(rules!.defaults).toEqual({ orgId: 7, siteId: 3 });
+  });
+
+  it('supports wildcard * model matching', async () => {
+    const db = createTestAdapter();
+    const plugin = dataIsolation({
+      scopes: [{
+        name: 'tenant',
+        field: 'tenantId',
+        models: ['*'],
+        resolveValue: async () => 1,
+      }],
+    });
+
+    const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+    const rules = await plugin.scopeRules!('1', 'anything', ctx);
+
+    expect(rules).not.toBeNull();
+    expect(rules!.filters[0].value).toBe(1);
+  });
+
+  it.each([null, undefined])('denies by default when an applicable scope resolves to %s', async (value) => {
+    const db = createTestAdapter();
+    const plugin = dataIsolation({
+      scopes: [{
+        name: 'site',
+        field: 'siteId',
+        models: ['sale'],
+        resolveValue: async () => value,
+      }],
+    });
+
+    const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+
+    await expect(plugin.scopeRules!('1', 'sale', ctx)).rejects.toMatchObject({
+      code: 'FORBIDDEN',
+      message: 'Data isolation scope \'site\' could not be resolved',
+    });
+  });
+
+  it('supports explicit unsafe legacy skip mode for unresolved scopes', async () => {
+    const db = createTestAdapter();
+    const plugin = dataIsolation({
+      unresolvedScope: 'skip',
+      scopes: [{
+        name: 'site',
+        field: 'siteId',
+        models: ['sale'],
+        resolveValue: async () => null,
+      }],
+    });
+
+    const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+
+    await expect(plugin.scopeRules!('1', 'sale', ctx)).resolves.toBeNull();
+  });
+
+  describe('bypass methods', () => {
+    it('withoutScope bypasses a specific scope', async () => {
+      const db = createTestAdapter();
+      const plugin = dataIsolation({
+        scopes: [
+          { name: 'org', field: 'orgId', models: ['sale'], resolveValue: async () => 7 },
+          { name: 'site', field: 'siteId', models: ['sale'], resolveValue: async () => 3 },
+        ],
+      });
+
+      const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+      const methods = plugin.methods!(ctx) as { withoutScope: <T>(name: string, fn: () => Promise<T>) => Promise<T> };
+
+      const rules = await methods.withoutScope('site', async () => {
+        return plugin.scopeRules!('1', 'sale', ctx);
+      });
+
+      expect(rules!.filters).toHaveLength(1);
+      expect(rules!.filters[0].field).toBe('orgId');
+    });
+
+    it('withoutScope explicitly bypasses an unresolved named scope', async () => {
+      const db = createTestAdapter();
+      const plugin = dataIsolation({
+        scopes: [{ name: 'site', field: 'siteId', models: ['sale'], resolveValue: async () => null }],
+      });
+      const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+      const methods = plugin.methods!(ctx) as { withoutScope: <T>(name: string, fn: () => Promise<T>) => Promise<T> };
+
+      await expect(
+        methods.withoutScope('site', () => plugin.scopeRules!('1', 'sale', ctx)),
+      ).resolves.toBeNull();
+    });
+
+    it('unscoped bypasses all scopes', async () => {
+      const db = createTestAdapter();
+      const plugin = dataIsolation({
+        scopes: [
+          { name: 'org', field: 'orgId', models: ['sale'], resolveValue: async () => 7 },
+          { name: 'site', field: 'siteId', models: ['sale'], resolveValue: async () => 3 },
+        ],
+      });
+
+      const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+      const methods = plugin.methods!(ctx) as { unscoped: <T>(fn: () => Promise<T>) => Promise<T> };
+
+      const rules = await methods.unscoped(async () => {
+        return plugin.scopeRules!('1', 'sale', ctx);
+      });
+
+      expect(rules).toBeNull();
+    });
+
+    // H4 regression: pre-fix, `unscoped()` set a module-level flag so a
+    // concurrent request would see no isolation while the first request
+    // was still awaiting inside the bypass window.
+    it('unscoped does not leak across concurrent async flows (H4)', async () => {
+      const db = createTestAdapter();
+      const plugin = dataIsolation({
+        scopes: [
+          { name: 'org', field: 'orgId', models: ['sale'], resolveValue: async () => 7 },
+        ],
+      });
+      const ctx: PluginContext = { db, config: { jwt: { key: 'x'.repeat(32) }, database: db } };
+      const methods = plugin.methods!(ctx) as { unscoped: <T>(fn: () => Promise<T>) => Promise<T> };
+
+      // Flow A holds an unscoped window open across an await.
+      // Flow B asks for scope rules in the middle.
+      const flowB = (async (): Promise<unknown> => {
+        // Microtask-delay so flow A is already "inside" unscoped().
+        await Promise.resolve();
+        return plugin.scopeRules!('1', 'sale', ctx);
+      })();
+      const flowA = methods.unscoped(async () => {
+        await new Promise(r => setTimeout(r, 5));
+        return 'a-done';
+      });
+
+      const [flowAResult, flowBResult] = await Promise.all([flowA, flowB]);
+      expect(flowAResult).toBe('a-done');
+      // Flow B is in its own async context — still scoped.
+      expect((flowBResult as { filters: { field: string }[] }).filters[0].field).toBe('orgId');
+    });
+  });
+});

package/src/plugins/data-isolation/index.ts

@@ -0,0 +1,157 @@
+/**
+ * Row-level data isolation plugin for fortress.
+ *
+ * Lets you scope read/write access to a database row by per-user assignments,
+ * for example "user can only see rows where `org_id` equals their assigned
+ * org". Works with any database adapter via the core `scopeRules` capability.
+ *
+ * @module
+ */
+
+import type { ScopeRule } from '../../adapters/database/types';
+import type { FortressPlugin, PluginContext } from '../../core/plugin';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { Errors } from '../../core/errors';
+
+export interface DataIsolationScope {
+  /** Scope name for identification and bypass control */
+  name: string;
+  /** Column name that holds the scoping value in the target tables */
+  field: string;
+  /** Which models (tables) this scope applies to. Use ['*'] for all models. */
+  models: string[];
+  /** Resolve the current user's value for this scope */
+  resolveValue: (userId: string, ctx: PluginContext) => Promise<unknown>;
+}
+
+export interface DataIsolationConfig {
+  scopes: DataIsolationScope[];
+  /**
+   * Behavior when an applicable scope resolves to `null` or `undefined`.
+   * Defaults to `'deny'`. `'skip'` is an unsafe legacy compatibility mode
+   * that removes that scope's row isolation for the operation.
+   */
+  unresolvedScope?: 'deny' | 'skip';
+}
+
+/**
+ * Per-request bypass state. Stored in `AsyncLocalStorage` so concurrent
+ * requests don't trample each other's `unscoped()` / `withoutScope()`
+ * windows. The pre-fix implementation used module-level globals — one
+ * request's `unscoped()` await would silently disable isolation for every
+ * other in-flight request handling the same async tick (H4).
+ *
+ * Runtime support: `AsyncLocalStorage` is Node core and is implemented by
+ * Bun, Deno, Cloudflare Workers (with the `nodejs_compat` flag and a
+ * compatibility date of 2024-09-23 or later), and Vercel Edge. This plugin
+ * uses only the universally-supported subset — `run()` and `getStore()`,
+ * never `enterWith()`/`disable()` — and wraps native async callbacks, so the
+ * workerd "thenable context-loss" caveat does not apply. The only hot-path
+ * call is the cheap `getStore()` read in `scopeRules`. This is also the
+ * direction of the TC39 AsyncContext proposal (Stage 2), so the approach is
+ * standards-track rather than a Node-specific hack.
+ *
+ * The dependency is scoped to this module — importing the main
+ * `@bajustone/fortress` entry only pulls in plugin *types*, not
+ * `node:async_hooks`, so it loads only when this plugin is actually used.
+ * On a runtime that genuinely lacks `node:async_hooks`, importing the
+ * plugin throws at import time.
+ */
+interface BypassState {
+  all: boolean;
+  scopes: Set<string>;
+}
+
+const bypassStore = new AsyncLocalStorage<BypassState>();
+
+function currentBypassState(): BypassState | undefined {
+  return bypassStore.getStore();
+}
+
+export interface DataIsolationMethods {
+  withoutScope: <T>(scopeName: string, fn: () => Promise<T>) => Promise<T>;
+  unscoped: <T>(fn: () => Promise<T>) => Promise<T>;
+}
+/**
+ * Data isolation plugin factory. Returns a {@link FortressPlugin} that scopes
+ * read and write access to a database row by per-user scope assignments,
+ * enforcing isolation through the core `scopeRules` capability.
+ */
+export function dataIsolation(config: DataIsolationConfig): FortressPlugin & { readonly name: 'data-isolation' } {
+  return {
+    name: 'data-isolation',
+
+    models: [{
+      name: 'user_scope_assignment',
+      fields: {
+        id: { type: 'number', required: true },
+        userId: { type: 'number', required: true, references: { model: 'user', field: 'id' } },
+        scopeName: { type: 'string', required: true },
+        scopeValue: { type: 'string', required: true },
+        createdAt: { type: 'date', required: true },
+      },
+    }],
+
+    async scopeRules(userId: string, model: string, ctx: PluginContext): Promise<ScopeRule | null> {
+      const state = currentBypassState();
+      if (state?.all)
+        return null;
+
+      const filters: ScopeRule['filters'] = [];
+      const defaults: ScopeRule['defaults'] = {};
+
+      for (const scope of config.scopes) {
+        if (state?.scopes.has(scope.name))
+          continue;
+
+        // Check if this scope applies to the queried model
+        const applies = scope.models.includes('*') || scope.models.includes(model);
+        if (!applies)
+          continue;
+
+        const value = await scope.resolveValue(userId, ctx);
+        if (value === undefined || value === null) {
+          if (config.unresolvedScope === 'skip')
+            continue;
+          throw Errors.forbidden(`Data isolation scope '${scope.name}' could not be resolved`);
+        }
+
+        filters.push({ field: scope.field, operator: '=', value });
+        defaults[scope.field] = value;
+      }
+
+      return filters.length > 0 ? { filters, defaults } : null;
+    },
+
+    methods: () => ({
+      /**
+       * Execute a callback with a specific scope bypassed.
+       * Queries within the callback will not have the named scope filter applied.
+       *
+       * The bypass is async-context-local: it applies only to async work
+       * spawned inside `fn` and never leaks across concurrent requests.
+       */
+      async withoutScope<T>(scopeName: string, fn: () => Promise<T>): Promise<T> {
+        const existing = currentBypassState();
+        const nextScopes = new Set(existing?.scopes ?? []);
+        nextScopes.add(scopeName);
+        const next: BypassState = { all: existing?.all ?? false, scopes: nextScopes };
+        return bypassStore.run(next, fn);
+      },
+
+      /**
+       * Execute a callback with all scopes bypassed.
+       * Use with caution \u2014 no row-level isolation is applied.
+       *
+       * The bypass is async-context-local. Calls outside the callback (and
+       * concurrent requests running on different async contexts) are
+       * unaffected.
+       */
+      async unscoped<T>(fn: () => Promise<T>): Promise<T> {
+        const existing = currentBypassState();
+        const next: BypassState = { all: true, scopes: new Set(existing?.scopes ?? []) };
+        return bypassStore.run(next, fn);
+      },
+    }),
+  };
+}

package/src/plugins/email-verification/email-verification.test.ts

@@ -0,0 +1,199 @@
+import type { Fortress } from '../../core/fortress';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createFortress } from '../../core/fortress';
+import { createTestAdapter } from '../../testing';
+import { emailVerification } from './index';
+
+const SECRET = 'email-verify-test-secret-32chars!';
+
+describe('email-verification plugin', () => {
+  let fortress: Fortress<any>;
+  let capturedToken: string | null;
+  let capturedEmail: string | null;
+  const onSend = vi.fn(async (email: string, token: string, _userId: string) => {
+    capturedEmail = email;
+    capturedToken = token;
+  });
+
+  beforeEach(() => {
+    capturedToken = null;
+    capturedEmail = null;
+    onSend.mockClear();
+
+    fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      plugins: [emailVerification({ onSendVerification: onSend })],
+    });
+  });
+
+  describe('afterRegister hook', () => {
+    it('calls onSendVerification when user is created', async () => {
+      await fortress.auth.createUser({
+        email: 'alice@example.com',
+        name: 'Alice',
+        password: 'password-123456',
+      });
+
+      expect(onSend).toHaveBeenCalledOnce();
+      expect(capturedEmail).toBe('alice@example.com');
+      expect(capturedToken).toBeTruthy();
+    });
+  });
+
+  describe('verify method', () => {
+    it('verifies a valid token', async () => {
+      await fortress.auth.createUser({
+        email: 'alice@example.com',
+        name: 'Alice',
+        password: 'password-123456',
+      });
+
+      const result = await (fortress.plugins['email-verification'].verify as (token: string) => Promise<{ userId: string; email: string }>)(capturedToken!);
+
+      expect(result.email).toBe('alice@example.com');
+      expect(result.userId).toBeDefined();
+    });
+
+    it('rejects already-used token', async () => {
+      await fortress.auth.createUser({
+        email: 'bob@example.com',
+        name: 'Bob',
+        password: 'password-123456',
+      });
+
+      const verify = fortress.plugins['email-verification'].verify as (token: string) => Promise<unknown>;
+      await verify(capturedToken!);
+
+      await expect(verify(capturedToken!)).rejects.toThrow('Invalid or expired verification token');
+    });
+
+    it('rejects invalid token', async () => {
+      const verify = fortress.plugins['email-verification'].verify as (token: string) => Promise<unknown>;
+      await expect(verify('bogus-token')).rejects.toThrow('Invalid or expired verification token');
+    });
+
+    it('rejects expired token', async () => {
+      // Create with negative expiry to guarantee token is already expired
+      const shortFortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [emailVerification({ tokenExpirySeconds: -1, onSendVerification: onSend })],
+      });
+
+      await shortFortress.auth.createUser({
+        email: 'carol@example.com',
+        name: 'Carol',
+        password: 'password-123456',
+      });
+
+      const verify = shortFortress.plugins['email-verification'].verify as (token: string) => Promise<unknown>;
+      await expect(verify(capturedToken!)).rejects.toThrow('Invalid or expired verification token');
+    });
+  });
+
+  describe('post-auth gate', () => {
+    it('holds unverified login and completes after token verification', async () => {
+      await fortress.auth.createUser({
+        email: 'dave@example.com',
+        name: 'Dave',
+        password: 'password-123456',
+      });
+
+      const result = await fortress.auth.login('dave@example.com', 'password-123456');
+      expect(result.status).toBe('pending');
+      expect(result.pluginData?.requiresEmailVerification).toBe(true);
+      expect(await fortress.config.database.count({ model: 'refresh_token' })).toBe(0);
+      if (result.status !== 'pending' || !result.pending)
+        throw new Error('Expected email-verification continuation');
+
+      const complete = fortress.plugins['email-verification'].completeVerification as (
+        continuationToken: string,
+        verificationToken: string,
+      ) => Promise<unknown>;
+      await expect(complete(result.pending.continuationToken, capturedToken!)).resolves.toMatchObject({
+        status: 'success',
+      });
+    });
+
+    it('allows verified user login', async () => {
+      await fortress.auth.createUser({
+        email: 'eve@example.com',
+        name: 'Eve',
+        password: 'password-123456',
+      });
+
+      // Verify email first
+      const verify = fortress.plugins['email-verification'].verify as (token: string) => Promise<unknown>;
+      await verify(capturedToken!);
+
+      // Login should succeed
+      const result = await fortress.auth.login('eve@example.com', 'password-123456');
+      if (result.status !== 'success')
+        throw new Error('Expected successful login');
+      expect(result.accessToken).toBeTruthy();
+      expect(result.user.email).toBe('eve@example.com');
+    });
+  });
+
+  describe('sendVerification method', () => {
+    it('generates a new token for existing user', async () => {
+      const user = await fortress.auth.createUser({
+        email: 'frank@example.com',
+        name: 'Frank',
+        password: 'password-123456',
+      });
+
+      onSend.mockClear();
+      const sendVerification = fortress.plugins['email-verification'].sendVerification as (userId: string) => Promise<{ sent: true }>;
+      const result = await sendVerification(user.id);
+
+      expect(result).toEqual({ sent: true });
+      expect(onSend).toHaveBeenCalledOnce();
+    });
+
+    it('adopts a changed email only after its token is verified', async () => {
+      const user = await fortress.auth.createUser({
+        email: 'old@example.com',
+        name: 'Changed',
+        password: 'password-123456',
+      });
+      onSend.mockClear();
+      const methods = fortress.plugins['email-verification'];
+      await methods.sendVerification(user.id, 'new@example.com');
+      const token = onSend.mock.calls[0]![1];
+
+      const findUser = () => fortress.config.database.findOne<{ email: string; emailVerified: boolean }>({
+        model: 'user',
+        where: [{ field: 'id', operator: '=', value: user.id }],
+      });
+      expect((await findUser())?.email).toBe('old@example.com');
+      await methods.verify(token);
+      expect(await findUser()).toMatchObject({
+        email: 'new@example.com',
+        emailVerified: true,
+      });
+    });
+  });
+
+  describe('requireVerification: false', () => {
+    it('allows login without verification', async () => {
+      const noRequireFortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [emailVerification({ requireVerification: false })],
+      });
+
+      await noRequireFortress.auth.createUser({
+        email: 'grace@example.com',
+        name: 'Grace',
+        password: 'password-123456',
+      });
+
+      const result = await noRequireFortress.auth.login('grace@example.com', 'password-123456');
+      if (result.status !== 'success')
+        throw new Error('Expected successful login');
+      expect(result.accessToken).toBeTruthy();
+    });
+  });
+});