@bajustone/fortress 1.0.0-rc.1

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

@@ -0,0 +1,190 @@
+/**
+ * Email verification plugin for fortress.
+ *
+ * Issues hashed, time-limited verification tokens, exposes
+ * `requestVerification` and `verifyEmail` methods on the fortress instance,
+ * and adds the corresponding HTTP routes when mounted via a framework adapter.
+ *
+ * @module
+ */
+
+import type { DatabaseAdapter } from '../../adapters/database';
+import type { FortressPlugin } from '../../core/plugin';
+import type { AuthResult, FortressUser, RequestMeta } from '../../core/types';
+import { generateRefreshToken, hashToken } from '../../core/auth/refresh-token';
+import { Errors } from '../../core/errors';
+
+export interface EmailVerificationConfig {
+  /** Token expiry in seconds (default: 86400 = 24h) */
+  tokenExpirySeconds?: number;
+  /** Block login for unverified users (default: true) */
+  requireVerification?: boolean;
+  /** Called when a verification token is created */
+  onSendVerification?: (email: string, token: string, userId: string) => Promise<void>;
+}
+
+interface VerificationTokenRecord {
+  id: string;
+  userId: string;
+  token: string;
+  email: string;
+  expiresAt: Date;
+  usedAt: Date | null;
+}
+
+export 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>;
+}
+/**
+ * Email verification plugin factory. Returns a {@link FortressPlugin} that
+ * issues hashed verification tokens, exposes `requestVerification` /
+ * `verifyEmail` methods, and (when mounted) the corresponding HTTP routes.
+ */
+export function emailVerification(config: EmailVerificationConfig = {}): FortressPlugin & { readonly name: 'email-verification' } {
+  const tokenExpirySeconds = config.tokenExpirySeconds ?? 86400;
+  const requireVerification = config.requireVerification ?? true;
+
+  async function consumeVerificationToken(
+    db: DatabaseAdapter,
+    rawToken: string,
+    expectedUserId?: string,
+  ): Promise<VerificationTokenRecord> {
+    const hash = await hashToken(rawToken);
+    const usedAt = new Date();
+    const record = await db.update<VerificationTokenRecord>({
+      model: 'email_verification_token',
+      where: [
+        { field: 'token', operator: '=', value: hash },
+        { field: 'usedAt', operator: 'isNull', value: null },
+        { field: 'expiresAt', operator: 'gt', value: usedAt },
+        ...(expectedUserId ? [{ field: 'userId', operator: '=' as const, value: expectedUserId }] : []),
+      ],
+      data: { usedAt },
+    });
+    if (!record)
+      throw Errors.notFound('Invalid or expired verification token');
+
+    await db.update({
+      model: 'user',
+      where: [{ field: 'id', operator: '=', value: record.userId }],
+      data: { email: record.email, emailVerified: true },
+    });
+    return record;
+  }
+
+  return {
+    name: 'email-verification',
+
+    models: [{
+      name: 'email_verification_token',
+      fields: {
+        id: { type: 'number', required: true },
+        userId: { type: 'number', required: true, references: { model: 'user', field: 'id' } },
+        token: { type: 'string', required: true },
+        email: { type: 'string', required: true },
+        expiresAt: { type: 'date', required: true },
+        usedAt: { type: 'date' },
+        createdAt: { type: 'date', required: true },
+      },
+    }],
+
+    hooks: {
+      postAuthGate: {
+        reason: 'email-verification',
+        async evaluate(ctx) {
+          if (!requireVerification || ctx.user.emailVerified)
+            return;
+
+          const tokens = await ctx.db.findMany<VerificationTokenRecord>({
+            model: 'email_verification_token',
+            where: [{ field: 'userId', operator: '=', value: ctx.user.id }],
+          });
+          return tokens.some(token => token.usedAt !== null)
+            ? undefined
+            : { pluginData: { requiresEmailVerification: true } };
+        },
+        async verify(ctx, completion) {
+          if (typeof completion !== 'string')
+            throw Errors.unauthorized('Invalid verification token');
+          await consumeVerificationToken(ctx.db, completion, ctx.user.id);
+        },
+      },
+
+      async afterRegister(ctx, user) {
+        const { raw, hash } = await generateRefreshToken();
+        const expiresAt = new Date(Date.now() + tokenExpirySeconds * 1000);
+
+        await ctx.db.create({
+          model: 'email_verification_token',
+          data: {
+            userId: user.id,
+            token: hash,
+            email: user.email,
+            expiresAt,
+            usedAt: null,
+          },
+        });
+
+        if (config.onSendVerification) {
+          await config.onSendVerification(user.email, raw, user.id);
+        }
+      },
+    },
+
+    methods: ctx => ({
+      async sendVerification(userId: string, email?: string): Promise<{ sent: true }> {
+        const user = await ctx.db.findOne<FortressUser>({
+          model: 'user',
+          where: [{ field: 'id', operator: '=', value: userId }],
+        });
+
+        if (!user)
+          throw Errors.notFound('User not found');
+
+        const targetEmail = email ?? user.email;
+        const { raw, hash } = await generateRefreshToken();
+        const expiresAt = new Date(Date.now() + tokenExpirySeconds * 1000);
+
+        await ctx.db.create({
+          model: 'email_verification_token',
+          data: {
+            userId,
+            token: hash,
+            email: targetEmail,
+            expiresAt,
+            usedAt: null,
+          },
+        });
+
+        if (config.onSendVerification) {
+          await config.onSendVerification(targetEmail, raw, userId);
+        }
+
+        // Raw verification credentials are delivered only through the callback;
+        // returning them to the caller defeats out-of-band verification.
+        return { sent: true };
+      },
+
+      async verify(rawToken: string): Promise<{ userId: string; email: string }> {
+        const record = await ctx.db.transaction(tx => consumeVerificationToken(tx, rawToken));
+        return { userId: record.userId, email: record.email };
+      },
+
+      async completeVerification(
+        continuationToken: string,
+        verificationToken: string,
+        meta?: RequestMeta,
+      ): Promise<AuthResult> {
+        if (!ctx.auth)
+          throw Errors.badRequest('Auth service is unavailable');
+        return ctx.auth.completePendingAuth(continuationToken, verificationToken, meta);
+      },
+    }),
+  };
+}

package/src/plugins/magic-link/index.ts

@@ -0,0 +1,129 @@
+/**
+ * Passwordless magic-link plugin for fortress.
+ *
+ * Issues short-lived hashed tokens delivered out-of-band (typically by email)
+ * and exchanges a valid token for a fortress access/refresh token pair.
+ * Useful as a passwordless sign-in flow or as a recovery mechanism.
+ *
+ * @module
+ */
+
+import type { FortressPlugin } from '../../core/plugin';
+import type { AuthResult, FortressUser, RequestMeta } from '../../core/types';
+import { generateRefreshToken, hashToken } from '../../core/auth/refresh-token';
+import { Errors } from '../../core/errors';
+
+export interface MagicLinkConfig {
+  /** Token expiry in seconds. Default: 600 (10 minutes). */
+  tokenExpirySeconds?: number;
+  /** Called when a magic link token is created -- send the link to the user */
+  onSendMagicLink?: (email: string, token: string) => Promise<void>;
+}
+
+export interface MagicLinkMethods {
+  sendMagicLink: (email: string) => Promise<{ sent: true }>;
+  verify: (rawToken: string, meta?: RequestMeta) => Promise<AuthResult>;
+}
+
+interface MagicLinkTokenRecord {
+  id: string;
+  email: string;
+  token: string;
+  expiresAt: Date;
+  usedAt: Date | null;
+  createdAt: Date;
+}
+
+/**
+ * Magic link plugin factory. Returns a {@link FortressPlugin} that issues
+ * short-lived hashed tokens for passwordless sign-in. Tokens are typically
+ * delivered out-of-band (email) and exchanged for fortress access/refresh
+ * tokens via the verify endpoint.
+ */
+export function magicLink(config: MagicLinkConfig = {}): FortressPlugin & { readonly name: 'magic-link' } {
+  const tokenExpirySeconds = config.tokenExpirySeconds ?? 600;
+
+  return {
+    name: 'magic-link',
+
+    models: [{
+      name: 'magic_link_token',
+      fields: {
+        id: { type: 'number', required: true },
+        email: { type: 'string', required: true },
+        token: { type: 'string', required: true },
+        expiresAt: { type: 'date', required: true },
+        usedAt: { type: 'date' },
+        createdAt: { type: 'date', required: true },
+      },
+    }],
+
+    methods: ctx => ({
+      async sendMagicLink(email: string): Promise<{ sent: true }> {
+        const { raw, hash } = await generateRefreshToken();
+        const expiresAt = new Date(Date.now() + tokenExpirySeconds * 1000);
+
+        await ctx.db.create({
+          model: 'magic_link_token',
+          data: {
+            email,
+            token: hash,
+            expiresAt,
+            usedAt: null,
+          },
+        });
+
+        if (config.onSendMagicLink) {
+          await config.onSendMagicLink(email, raw);
+        }
+
+        return { sent: true };
+      },
+
+      async verify(rawToken: string, meta?: RequestMeta): Promise<AuthResult> {
+        const hash = await hashToken(rawToken);
+        const usedAt = new Date();
+        const record = await ctx.db.transaction(tx => tx.update<MagicLinkTokenRecord>({
+          model: 'magic_link_token',
+          where: [
+            { field: 'token', operator: '=', value: hash },
+            { field: 'usedAt', operator: 'isNull', value: null },
+            { field: 'expiresAt', operator: 'gt', value: usedAt },
+          ],
+          data: { usedAt },
+        }));
+        if (!record)
+          throw Errors.notFound('Invalid or expired magic link token');
+
+        // Find or create user by email (JIT provisioning)
+        let user = await ctx.db.findOne<FortressUser>({
+          model: 'user',
+          where: [{ field: 'email', operator: '=', value: record.email }],
+        });
+
+        if (!user) {
+          user = await ctx.auth!.createUser({
+            email: record.email,
+            name: record.email.split('@')[0],
+          }) as FortressUser;
+        }
+
+        // Possession of the single-use link proves control of this address.
+        // Mark both JIT-created and existing matching accounts verified before
+        // running post-auth gates, otherwise email-verification blocks the
+        // very login that established ownership.
+        if (!user.emailVerified) {
+          await ctx.db.update({
+            model: 'user',
+            where: [{ field: 'id', operator: '=', value: user.id }],
+            data: { emailVerified: true },
+          });
+        }
+
+        if (!ctx.auth)
+          throw Errors.badRequest('Auth service is unavailable');
+        return ctx.auth.completePluginAuth(user.id, 'magic-link', meta);
+      },
+    }),
+  };
+}

package/src/plugins/magic-link/magic-link.test.ts

@@ -0,0 +1,156 @@
+import type { Fortress } from '../../core/fortress';
+import type { AuthResult } from '../../core/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createFortress } from '../../core/fortress';
+import { createTestAdapter } from '../../testing';
+import { magicLink } from './index';
+
+const SECRET = 'magic-link-test-secret-32chars!!';
+
+describe('magic-link plugin', () => {
+  let fortress: Fortress<any>;
+  let capturedToken: string | null;
+  let capturedEmail: string | null;
+  const onSend = vi.fn(async (email: string, token: string) => {
+    capturedEmail = email;
+    capturedToken = token;
+  });
+
+  beforeEach(() => {
+    capturedToken = null;
+    capturedEmail = null;
+    onSend.mockClear();
+
+    fortress = createFortress({
+      jwt: { key: SECRET },
+      database: createTestAdapter(),
+      plugins: [magicLink({ onSendMagicLink: onSend })],
+    });
+  });
+
+  describe('sendMagicLink', () => {
+    it('creates a token record and calls onSendMagicLink', async () => {
+      const send = fortress.plugins['magic-link'].sendMagicLink as (email: string) => Promise<{ sent: true }>;
+      const result = await send('alice@example.com');
+
+      expect(result).toEqual({ sent: true });
+      expect(onSend).toHaveBeenCalledOnce();
+      expect(capturedEmail).toBe('alice@example.com');
+      expect(capturedToken).toBeTruthy();
+    });
+  });
+
+  describe('verify', () => {
+    it('returns user info and access token for existing user', async () => {
+      // Pre-create the user
+      await fortress.auth.createUser({
+        email: 'bob@example.com',
+        name: 'Bob',
+        password: 'password-123456',
+      });
+
+      const send = fortress.plugins['magic-link'].sendMagicLink as (email: string) => Promise<{ sent: true }>;
+      await send('bob@example.com');
+
+      const verify = fortress.plugins['magic-link'].verify as (token: string) => Promise<AuthResult>;
+      const result = await verify(capturedToken!);
+
+      expect(result.user.email).toBe('bob@example.com');
+      expect(result.user.id).toBeDefined();
+      expect(result.status === 'success' ? result.accessToken : null).toBeTruthy();
+    });
+
+    it('verifies through the core HTTP endpoint and attaches auth cookies', async () => {
+      const send = fortress.plugins['magic-link'].sendMagicLink as (email: string) => Promise<{ sent: true }>;
+      await send('bob@example.com');
+
+      const response = await fortress.handleRequest(new Request('http://localhost/auth/magic-link/verify', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token: capturedToken }),
+      }));
+      expect(response.status).toBe(200);
+      await expect(response.json()).resolves.toMatchObject({
+        status: 'success',
+        method: 'magic-link',
+        user: { email: 'bob@example.com' },
+      });
+      expect(response.headers.getSetCookie().length).toBeGreaterThan(0);
+    });
+
+    it('runs configured post-auth gates before issuing tokens', async () => {
+      const database = createTestAdapter();
+      const gated = createFortress({
+        jwt: { key: SECRET },
+        database,
+        plugins: [
+          magicLink({ onSendMagicLink: onSend }),
+          {
+            name: 'factor',
+            hooks: {
+              postAuthGate: {
+                reason: 'two-factor',
+                evaluate: async () => ({ pluginData: { requires2FA: true } }),
+                verify: async () => {},
+              },
+            },
+          },
+        ],
+      });
+      const send = gated.plugins['magic-link'].sendMagicLink as (email: string) => Promise<{ sent: true }>;
+      const verify = gated.plugins['magic-link'].verify as (token: string) => Promise<AuthResult>;
+      await send('gated@example.com');
+
+      const result = await verify(capturedToken!);
+      expect(result.status).toBe('pending');
+      expect(result.status === 'pending' ? result.pending?.reason : undefined).toBe('two-factor');
+      expect(await database.count({ model: 'refresh_token' })).toBe(0);
+    });
+
+    it('auto-creates user for unknown email (JIT provisioning)', async () => {
+      const send = fortress.plugins['magic-link'].sendMagicLink as (email: string) => Promise<{ sent: true }>;
+      await send('newuser@example.com');
+
+      const verify = fortress.plugins['magic-link'].verify as (token: string) => Promise<AuthResult>;
+      const result = await verify(capturedToken!);
+
+      expect(result.user.email).toBe('newuser@example.com');
+      expect(result.user.id).toBeDefined();
+      expect(result.status === 'success' ? result.accessToken : null).toBeTruthy();
+
+      // Confirm the user was actually created
+      const user = await fortress.auth.me(result.user.id);
+      expect(user.email).toBe('newuser@example.com');
+      expect(user.name).toBe('newuser');
+    });
+
+    it('rejects expired tokens', async () => {
+      const expiredFortress = createFortress({
+        jwt: { key: SECRET },
+        database: createTestAdapter(),
+        plugins: [magicLink({ tokenExpirySeconds: -1, onSendMagicLink: onSend })],
+      });
+
+      const send = expiredFortress.plugins['magic-link'].sendMagicLink as (email: string) => Promise<{ sent: true }>;
+      await send('expired@example.com');
+
+      const verify = expiredFortress.plugins['magic-link'].verify as (token: string) => Promise<unknown>;
+      await expect(verify(capturedToken!)).rejects.toThrow('Invalid or expired magic link token');
+    });
+
+    it('rejects already-used tokens', async () => {
+      const send = fortress.plugins['magic-link'].sendMagicLink as (email: string) => Promise<{ sent: true }>;
+      await send('carol@example.com');
+
+      const verify = fortress.plugins['magic-link'].verify as (token: string) => Promise<unknown>;
+      await verify(capturedToken!);
+
+      await expect(verify(capturedToken!)).rejects.toThrow('Invalid or expired magic link token');
+    });
+
+    it('rejects invalid tokens', async () => {
+      const verify = fortress.plugins['magic-link'].verify as (token: string) => Promise<unknown>;
+      await expect(verify('bogus-token')).rejects.toThrow('Invalid or expired magic link token');
+    });
+  });
+});

package/src/plugins/oauth/id-token.ts

@@ -0,0 +1,86 @@
+/**
+ * OIDC Core 1.0 id_token issuer.
+ *
+ * Responsibilities:
+ * - Build the standard claims (`iss`, `sub`, `aud`, `iat`, `exp`, plus
+ *   conditional `nonce`, `auth_time`).
+ * - Add scope-gated identity claims (`email`, `email_verified`, `name`,
+ *   `preferred_username`) that match what the userinfo endpoint emits, so
+ *   RPs that decode the id_token directly see the same view as RPs that
+ *   call userinfo.
+ * - Sign with the active RS256 key and tag the JWS header with `kid`.
+ *
+ * @module
+ */
+
+import type { FortressUser } from '../../core/types';
+import type { ActiveSigningKey } from './jwks';
+import { SignJWT } from 'jose';
+
+/** Inputs to {@link issueIdToken}. All times are in seconds. */
+export interface IdTokenParams {
+  user: FortressUser;
+  clientId: string;
+  /** OIDC Core \u00a72: same value as the AS issuer URL in discovery. */
+  issuerUrl: string;
+  /** Lifetime in seconds (default 1h). */
+  ttlSeconds?: number;
+  /** Echoed verbatim if the authorize request supplied one (\u00a73.1.3.7). */
+  nonce?: string;
+  /**
+   * Unix seconds when the user authenticated (\u00a72). Required when
+   * `max_age` was used. Omit on refresh when the original authentication
+   * time was not persisted; never substitute the refresh time.
+   */
+  authTimeSeconds?: number;
+  /** Space-separated scope; gates the identity claims. */
+  scope: string | null;
+  /** Pre-resolved active signing key from {@link getActiveSigningKey}. */
+  signingKey: ActiveSigningKey;
+}
+
+/**
+ * Build and sign an OIDC id_token. Returns the compact JWS string.
+ *
+ * Claim coverage (OIDC Core \u00a72 + \u00a75.1):
+ * - `iss`, `sub`, `aud`, `iat`, `exp` always
+ * - `auth_time` and `nonce` when supplied
+ * - `email`, `email_verified` only when scope contains `email`
+ * - `name`, `preferred_username` when scope contains `profile`
+ * - `updated_at` always (mirrors userinfo)
+ */
+export async function issueIdToken(params: IdTokenParams): Promise<string> {
+  const ttl = params.ttlSeconds ?? 3600;
+  const now = Math.floor(Date.now() / 1000);
+  const scopes = params.scope ? params.scope.split(' ').filter(Boolean) : [];
+  const exposeEmail = scopes.includes('email');
+  const exposeProfile = scopes.includes('profile');
+
+  // Standard + scope-gated identity claims.
+  const claims: Record<string, unknown> = {};
+  if (params.authTimeSeconds !== undefined)
+    claims.auth_time = params.authTimeSeconds;
+  if (params.nonce)
+    claims.nonce = params.nonce;
+  if (exposeEmail) {
+    claims.email = params.user.email;
+    if (typeof params.user.emailVerified === 'boolean')
+      claims.email_verified = params.user.emailVerified;
+  }
+  if (exposeProfile) {
+    claims.name = params.user.name;
+    claims.preferred_username = params.user.email;
+  }
+  if (params.user.updatedAt) {
+    claims.updated_at = Math.floor(new Date(params.user.updatedAt).getTime() / 1000);
+  }
+
+  return new SignJWT(claims)
+    .setProtectedHeader({ alg: 'RS256', kid: params.signingKey.kid, typ: 'JWT' })
+    .setIssuer(params.issuerUrl)
+    .setSubject(String(params.user.id))
+    .setAudience(params.clientId)
+    .setIssuedAt(now)
+    .setExpirationTime(now + ttl)
+    .sign(params.signingKey.privateKey);
+}