@everystack/auth 0.1.0 → 0.2.0

package/src/testing.ts

@@ -0,0 +1,232 @@
+/**
+ * @everystack/auth/testing — E2E test helpers for authorization and security.
+ *
+ * Provides tools for testing multiple roles, seeding test users, and making
+ * authenticated requests against any everystack handler — local or deployed.
+ *
+ * Features:
+ *   - createTestAuth(secret)    — sign/verify JWTs for any role
+ *   - seedTestUser(sql, opts)   — ensure a test user exists with known credentials
+ *   - createTestRoles(secret)   — pre-built tokens for anon/authenticated/admin
+ *
+ * Works against any environment — local dev, CI, deployed stages.
+ * For deployed stages, retrieve secrets via: sst secret get JWT_SECRET --stage <name>
+ *
+ * @see docs/testing.md for the full testing guide
+ */
+
+import { createJwt } from './jwt';
+import { hmacNode } from './jwt/hmac-node';
+import { hashPassword } from './passwords';
+
+/** Validates a SQL identifier (table/column name) to prevent injection. */
+function assertIdentifier(name: string, label: string): void {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
+    throw new Error(`${label} contains invalid characters: ${name}`);
+  }
+}
+
+// ─── createTestAuth ──────────────────────────────────────────────────────────
+
+export interface TestAuthOptions {
+  /** Token lifetime in seconds. Default: 3600 (1 hour). */
+  ttlSec?: number;
+  /** Default claims merged into every sign() call. */
+  defaults?: Record<string, unknown>;
+}
+
+export interface TestAuth {
+  /** Sign a JWT with the given claims. Auto-fills iat/exp if not present. */
+  sign(claims: Record<string, unknown>): Promise<string>;
+  /** Verify a token and return its claims, or null if invalid/expired. */
+  verify(token: string): Promise<Record<string, unknown> | null>;
+  /** Decode a token without verification. For debugging only. */
+  decode(token: string): Record<string, unknown> | null;
+}
+
+/**
+ * Create a test auth helper bound to a JWT secret.
+ *
+ * @param secret - The JWT_SECRET used by the handler under test.
+ * @param options - Optional defaults and TTL override.
+ */
+export function createTestAuth(secret: string, options?: TestAuthOptions): TestAuth {
+  if (!secret) throw new Error('createTestAuth: secret is required');
+
+  const jwt = createJwt({
+    secret,
+    hmac: hmacNode,
+    ttlSec: options?.ttlSec ?? 3600,
+    includeJti: false,
+  });
+
+  const defaults = options?.defaults ?? {};
+
+  return {
+    async sign(claims: Record<string, unknown>): Promise<string> {
+      return jwt.sign({ ...defaults, ...claims });
+    },
+    verify: (token: string) => jwt.verify(token),
+    decode: (token: string) => jwt.decode(token),
+  };
+}
+
+// ─── createTestRoles ─────────────────────────────────────────────────────────
+
+export interface TestRoles {
+  /** No token — represents an unauthenticated request. */
+  anon: null;
+  /** JWT for a regular authenticated user. */
+  authenticated: string;
+  /** JWT for an admin/super user. */
+  admin: string;
+  /** Sign a custom token with arbitrary claims. */
+  sign(claims: Record<string, unknown>): Promise<string>;
+}
+
+/**
+ * Create pre-signed tokens for common test roles.
+ *
+ * Usage:
+ *   const roles = await createTestRoles(process.env.JWT_SECRET!, {
+ *     authenticated: { user_id: 42, user_state: 'active' },
+ *     admin: { user_id: 1, user_state: 'super', role: 'admin' },
+ *   });
+ *
+ *   // Unauthenticated request
+ *   await fetch('/api/contents', { headers: {} });
+ *
+ *   // Authenticated request
+ *   await fetch('/api/rpc/get_user', {
+ *     headers: { Authorization: `Bearer ${roles.authenticated}` },
+ *   });
+ *
+ *   // Admin request
+ *   await fetch('/api/rpc/admin_action', {
+ *     headers: { Authorization: `Bearer ${roles.admin}` },
+ *   });
+ */
+export async function createTestRoles(
+  secret: string,
+  claims: {
+    authenticated: Record<string, unknown>;
+    admin: Record<string, unknown>;
+  },
+): Promise<TestRoles> {
+  const auth = createTestAuth(secret);
+  const [authenticated, admin] = await Promise.all([
+    auth.sign({ role: 'authenticated', ...claims.authenticated }),
+    auth.sign({ role: 'admin', ...claims.admin }),
+  ]);
+
+  return {
+    anon: null,
+    authenticated,
+    admin,
+    sign: (c) => auth.sign(c),
+  };
+}
+
+// ─── seedTestUser ────────────────────────────────────────────────────────────
+
+export interface SeedTestUserOptions {
+  /** Email for the test user. */
+  email: string;
+  /** Plaintext password (stored as bcrypt hash). */
+  password: string;
+  /** Users table name. Default: 'users'. */
+  table?: string;
+  /** Email column name. Default: 'email'. */
+  emailColumn?: string;
+  /** Password column name. Default: 'encrypted_password'. */
+  passwordColumn?: string;
+  /**
+   * Called after the user is created (first run only).
+   * Use for app-specific setup: set name, activate, create system lists, etc.
+   */
+  afterCreate?: (sql: any, userId: number) => Promise<void>;
+}
+
+export interface TestUser {
+  /** Database ID of the test user. */
+  id: number;
+  /** Email address. */
+  email: string;
+  /** Plaintext password (for tests that call auth.sign_in directly). */
+  password: string;
+}
+
+/**
+ * Ensure a test user exists with known credentials.
+ *
+ * Idempotent — creates the user on first run, returns the existing one on
+ * subsequent runs. Password is always reset to ensure it matches.
+ *
+ * Requires a postgres.js sql client (not Drizzle).
+ *
+ * Usage:
+ *   const testUser = await seedTestUser(sql, {
+ *     email: process.env.TEST_USER_EMAIL!,
+ *     password: process.env.TEST_USER_PASSWORD!,
+ *     afterCreate: async (sql, userId) => {
+ *       // App-specific setup: set name, activate, etc.
+ *       await sql`UPDATE users SET first_name = 'E2E', last_name = 'Test', state = 'active' WHERE id = ${userId}`;
+ *     },
+ *   });
+ *
+ * For deployed stages, store credentials in SST secrets:
+ *   sst secret set TEST_USER_EMAIL "e2e-test@app.com" --stage dev
+ *   sst secret set TEST_USER_PASSWORD "test-password" --stage dev
+ */
+export async function seedTestUser(
+  sql: any,
+  options: SeedTestUserOptions,
+): Promise<TestUser> {
+  const {
+    email,
+    password,
+    table = 'users',
+    emailColumn = 'email',
+    passwordColumn = 'encrypted_password',
+    afterCreate,
+  } = options;
+
+  if (!email) throw new Error('seedTestUser: email is required');
+  if (!password) throw new Error('seedTestUser: password is required');
+  assertIdentifier(table, 'table');
+  assertIdentifier(emailColumn, 'emailColumn');
+  assertIdentifier(passwordColumn, 'passwordColumn');
+
+  const hash = await hashPassword(password);
+
+  // Check if user exists
+  const existing = await sql.unsafe(
+    `SELECT id::int FROM ${table} WHERE ${emailColumn} = $1 LIMIT 1`,
+    [email],
+  );
+
+  if (existing.length > 0) {
+    // Ensure password matches (may have been rotated)
+    await sql.unsafe(
+      `UPDATE ${table} SET ${passwordColumn} = $1 WHERE id = $2`,
+      [hash, existing[0].id],
+    );
+    return { id: existing[0].id, email, password };
+  }
+
+  // Create the user with minimal columns — apps can customize via afterCreate
+  const created = await sql.unsafe(
+    `INSERT INTO ${table} (${emailColumn}, ${passwordColumn}, created_at, updated_at)
+     VALUES ($1, $2, NOW(), NOW())
+     RETURNING id::int`,
+    [email, hash],
+  );
+
+  const userId = created[0].id;
+
+  if (afterCreate) {
+    await afterCreate(sql, userId);
+  }
+
+  return { id: userId, email, password };
+}