Gatekeeper Lesson 4 Walkthrough: withApiGuard

// apps/web/src/app/api/notes/route.ts (example)
export const GET = withApiGuard(listNotes, { feature: 'core-drive', requireScope: 'notes:read' });
export const POST = withApiGuard(createNote, { feature: 'core-drive', requireScope: 'notes:write' });

git switch main
git pull origin main
git switch -c feature/P2L4-api-guard

import postgres, { type Sql } from 'postgres';

// Connections to the throwaway database tests/with-test-db.sh builds from our migrations.
// Each factory opens a new single-connection client; the test file that creates it ends it
// in afterAll, so every file owns its connections' lifecycle.

/** Reads a connection URL tests/with-test-db.sh exports; fails loudly when run outside it */
export function requireTestEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`${name} is not set; run this test through tests/with-test-db.sh`);
  }

  return value;
}

/** supabase_auth_admin: creates and deletes users the way Supabase Auth does */
export function createTestAuthDb(): Sql {
  return postgres(requireTestEnv('TEST_AUTH_DATABASE_URL'), { max: 1 });
}

/** postgres: the privileged migration/seed role, the only one that writes entitlements */
export function createTestAdminDb(): Sql {
  return postgres(requireTestEnv('TEST_ADMIN_DATABASE_URL'), { max: 1 });
}

/** app_runtime: the role withRLS uses for every user request */
export function createTestRuntimeDb(): Sql {
  return postgres(requireTestEnv('DATABASE_URL'), { max: 1 });
}

/** A Request to a fixed test URL, optionally carrying headers such as Authorization */
export function createMockHttpRequest(headers?: HeadersInit): Request {
  return new Request('http://localhost/api/test', { headers });
}

import {
  AuthError,
  AuthSessionMissingError,
  type SupabaseClient,
  type User,
  type UserResponse,
} from '@supabase/supabase-js';

import type { KeyBasedApiCaller, SessionBasedApiCaller } from '../../src/api/auth';
import type { RlsTx } from '../../src/db';

// Shared mock values. Every export carries its full qualifier (MOCK_…, createMock…), so a
// reader of any test file can tell a mock from real code without opening this file.

export const MOCK_AUTH_TOKEN = 'bearer mocked-auth-token';

export const MOCK_USER = { id: 'mock-user-id' } as User;

export const MOCK_SESSION_CALLER: SessionBasedApiCaller = { kind: 'session', userId: MOCK_USER.id };

export const MOCK_KEY_CALLER: KeyBasedApiCaller = {
  kind: 'key',
  userId: MOCK_USER.id,
  keyId: 'mock-key-id',
  scopes: ['notes:read'],
};

/** Stands in for withRLS's transaction where the code under test only passes it along */
export const MOCK_RLS_TX = {} as RlsTx;

export const MOCK_AUTH_USER_RESPONSE: {
  validUser: UserResponse;
  invalidUser: UserResponse;
  error: UserResponse;
} = {
  validUser: { data: { user: MOCK_USER }, error: null },
  invalidUser: { data: { user: null }, error: new AuthSessionMissingError() },
  error: { data: { user: null }, error: new AuthError('boom') },
};

/** A Supabase server client whose auth.getUser() resolves to one of the responses above */
export function createMockSupabaseServerClient(
  state: keyof typeof MOCK_AUTH_USER_RESPONSE,
): SupabaseClient {
  return {
    auth: {
      getUser: async () => MOCK_AUTH_USER_RESPONSE[state],
    },
  } as unknown as SupabaseClient;
}

import 'server-only';

import { withRLS, type RlsTx } from '../db';
import { resolveApiCaller, type ApiCaller } from './auth';
import { getEnabledFeatures } from '../features/entitlements';

export interface GuardOptions {
  /** Key of the feature the caller must be entitled to */
  feature?: string;
  /** Scope an API-key caller must hold; session callers skip this check */
  requireScope?: string;
}

export interface ApiHandlerArgs<Ctx> {
  tx: RlsTx;
  caller: ApiCaller;
  req: Request;
  /** Next.js's second route-handler argument (e.g. `{ params }`), passed through untouched */
  ctx: Ctx;
}

export type ApiHandler<Ctx> = (args: ApiHandlerArgs<Ctx>) => Promise<Response>;

/** The error-shape table from contracts.md: one place maps a code to its status and message */
const GUARD_ERRORS = {
  UNAUTHENTICATED: { status: 401, error: 'Unauthorized' },
  SCOPE_MISSING: { status: 403, error: 'Forbidden' },
  FEATURE_DISABLED: { status: 403, error: 'Feature disabled' },
  INTERNAL: { status: 500, error: 'Internal error' },
} as const;

type GuardErrorCode = keyof typeof GUARD_ERRORS;

function guardError(code: GuardErrorCode): Response {
  const { status, error } = GUARD_ERRORS[code];

  return Response.json({ error, code }, { status });
}

/** Scopes only narrow what an API key may do; a session caller has no scopes to check */
function isMissingScope(caller: ApiCaller, scope?: string): boolean {
  return caller.kind === 'key' && scope !== undefined && !caller.scopes.includes(scope);
}

/**
 * Wraps a route handler with authentication, scope and feature checks, and runs it
 * inside one RLS transaction for the caller. Every App Router route handler must use it.
 * @param handler Runs only for an authenticated, permitted caller
 * @param opts Feature the caller must be entitled to, and scope a key caller must hold
 * @returns A Next.js route handler
 * @description
 * - It runs from cheapest to most expensive
 * - A request stops at the first failure
 */
export function withApiGuard<Ctx = unknown>(
  handler: ApiHandler<Ctx>,
  opts: GuardOptions = {},
): (req: Request, ctx: Ctx) => Promise<Response> {
  return async function apiGuard(req, ctx) {
    try {
      const caller = await resolveApiCaller(req);
      if (!caller) {
        return guardError('UNAUTHENTICATED');
      }

      // Needs no database, so it runs before a transaction (and a pooled connection) is taken
      if (isMissingScope(caller, opts.requireScope)) {
        return guardError('SCOPE_MISSING');
      }

      // `return await`, not `return`: the try/catch only catches a rejection it awaits.
      // Without it, a rejection skips our catch: no log, and no { error, code } body.
      return await withRLS(caller.userId, async (tx) => {
        if (opts.feature && !(await getEnabledFeatures(tx)).includes(opts.feature)) {
          return guardError('FEATURE_DISABLED');
        }

        return handler({ tx, caller, req, ctx });
      });
    } catch (error) {
      // withRLS has already rolled the transaction back. Lesson 5 replaces this with api.error.
      console.error('withApiGuard: unhandled error', error);
      return guardError('INTERNAL');
    }
  };
}

// Public API surface: route handlers import withApiGuard from @sidekick/core/api.
// resolveApiCaller stays internal; only the guard calls it.
export { type ApiHandler, type ApiHandlerArgs, type GuardOptions, withApiGuard } from './guard';
export type { ApiCaller } from './auth';

"./api": "./src/api/index.ts",

import { beforeEach, describe, expect, it, vi } from 'vitest';

import { createMockHttpRequest } from '../../tests/helpers/http';
import { MOCK_KEY_CALLER, MOCK_RLS_TX, MOCK_SESSION_CALLER } from '../../tests/helpers/mocks';
import { withRLS } from '../db';
import { getEnabledFeatures } from '../features/entitlements';
import { resolveApiCaller } from './auth';
import { type ApiHandler, withApiGuard } from './guard';

vi.mock('./auth', () => ({ resolveApiCaller: vi.fn() }));
vi.mock('../db', () => ({ withRLS: vi.fn() }));
vi.mock('../features/entitlements', () => ({ getEnabledFeatures: vi.fn() }));

const mockHandler = vi.fn<ApiHandler<unknown>>();

describe('withApiGuard', () => {
  beforeEach(() => {
    vi.resetAllMocks();
    vi.mocked(resolveApiCaller).mockResolvedValue(MOCK_SESSION_CALLER);
    // Run the callback the way withRLS does, minus the database
    vi.mocked(withRLS).mockImplementation(async (_userId, fn) => fn(MOCK_RLS_TX));
    vi.mocked(getEnabledFeatures).mockResolvedValue(['core-drive']);
    mockHandler.mockResolvedValue(Response.json({ ok: true }));
  });

  it('responds 401 without opening a transaction when there is no caller', async () => {
    vi.mocked(resolveApiCaller).mockResolvedValue(undefined);
    const response = await withApiGuard(mockHandler)(createMockHttpRequest(), undefined);

    expect(response.status).toBe(401);
    expect(await response.json()).toEqual({ error: 'Unauthorized', code: 'UNAUTHENTICATED' });
    expect(withRLS).not.toHaveBeenCalled();
    expect(mockHandler).not.toHaveBeenCalled();
  });

  it('responds 403 without opening a transaction when a key caller lacks the scope', async () => {
    vi.mocked(resolveApiCaller).mockResolvedValue(MOCK_KEY_CALLER);
    const guarded = withApiGuard(mockHandler, { requireScope: 'notes:write' });
    const response = await guarded(createMockHttpRequest(), undefined);

    expect(response.status).toBe(403);
    expect(await response.json()).toEqual({ error: 'Forbidden', code: 'SCOPE_MISSING' });
    expect(withRLS).not.toHaveBeenCalled();
    expect(mockHandler).not.toHaveBeenCalled();
  });

  it('lets a key caller with the scope through', async () => {
    vi.mocked(resolveApiCaller).mockResolvedValue(MOCK_KEY_CALLER);
    const guarded = withApiGuard(mockHandler, { requireScope: 'notes:read' });
    const response = await guarded(createMockHttpRequest(), undefined);

    expect(response.status).toBe(200);
    expect(mockHandler).toHaveBeenCalledOnce();
  });

  it('skips the scope check for session callers', async () => {
    const guarded = withApiGuard(mockHandler, { requireScope: 'notes:write' });
    const response = await guarded(createMockHttpRequest(), undefined);

    expect(response.status).toBe(200);
    expect(mockHandler).toHaveBeenCalledOnce();
  });

  it('responds 403 when the caller is not entitled to the feature', async () => {
    const guarded = withApiGuard(mockHandler, { feature: 'taxila' });
    const response = await guarded(createMockHttpRequest(), undefined);

    expect(response.status).toBe(403);
    expect(await response.json()).toEqual({ error: 'Feature disabled', code: 'FEATURE_DISABLED' });
    expect(getEnabledFeatures).toHaveBeenCalledWith(MOCK_RLS_TX);
    expect(mockHandler).not.toHaveBeenCalled();
  });

  it('does not read entitlements when no feature is required', async () => {
    const response = await withApiGuard(mockHandler)(createMockHttpRequest(), undefined);

    expect(response.status).toBe(200);
    expect(getEnabledFeatures).not.toHaveBeenCalled();
  });

  it('runs the handler in the caller’s transaction and passes ctx through', async () => {
    const mockRequest = createMockHttpRequest();
    const mockCtx = { params: Promise.resolve({ id: 'note-1' }) };
    const guarded = withApiGuard(mockHandler, { feature: 'core-drive' });
    const response = await guarded(mockRequest, mockCtx);

    expect(withRLS).toHaveBeenCalledWith(MOCK_SESSION_CALLER.userId, expect.any(Function));
    expect(mockHandler).toHaveBeenCalledWith({
      tx: MOCK_RLS_TX,
      caller: MOCK_SESSION_CALLER,
      req: mockRequest,
      ctx: mockCtx,
    });
    expect(await response.json()).toEqual({ ok: true });
  });

  it.each([
    [
      'the handler',
      () => mockHandler.mockRejectedValue(new Error('relation "notes" does not exist')),
    ],
    ['resolveApiCaller', () => vi.mocked(resolveApiCaller).mockRejectedValue(new Error('no env'))],
  ])('turns a throw in %s into a generic 500', async (_where, makeItThrow) => {
    makeItThrow();
    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
    const response = await withApiGuard(mockHandler)(createMockHttpRequest(), undefined);

    expect(response.status).toBe(500);
    // Exactly the generic body: no message, stack or SQL reaches the client
    expect(await response.json()).toEqual({ error: 'Internal error', code: 'INTERNAL' });
    expect(consoleErrorSpy).toHaveBeenCalledOnce();
  });
});

pnpm --filter @sidekick/core test

import { randomUUID } from 'node:crypto';
import { eq } from 'drizzle-orm';
import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';

import { withApiGuard } from '../../src/api';
import { resolveApiCaller } from '../../src/api/auth';
import { profiles } from '../../src/db/schema';
import { createTestAdminDb, createTestAuthDb } from '../helpers/db';
import { createMockHttpRequest } from '../helpers/http';

// Proves the guard end to end on a database built from our migrations. Only the caller
// is mocked (there is no Supabase Auth here); withRLS, the RLS policies, entitlements,
// commit and rollback all run for real. Runs inside tests/with-test-db.sh.
vi.mock('../../src/api/auth', () => ({ resolveApiCaller: vi.fn() }));

const testAuthDb = createTestAuthDb();
const testAdminDb = createTestAdminDb();

const entitledUserId = randomUUID();
const otherUserId = randomUUID();

function mockSignedInAs(userId: string) {
  vi.mocked(resolveApiCaller).mockResolvedValue({ kind: 'session', userId });
}

// Reads as postgres, which bypasses RLS, so the check doesn't depend on the code under test
async function getProfileEmail(userId: string) {
  const [row] = await testAdminDb`SELECT email FROM profiles WHERE id = ${userId}`;
  return row.email;
}

beforeAll(async () => {
  // The 0005 trigger creates each user's profile
  await testAuthDb`INSERT INTO auth.users ${testAuthDb(
    [
      { id: entitledUserId, email: '[email protected]' },
      { id: otherUserId, email: '[email protected]' },
    ],
    'id',
    'email',
  )}`;

  await testAdminDb`INSERT INTO user_feature_entitlements (user_id, feature_key)
    VALUES (${entitledUserId}, 'core-drive')`;
});

afterAll(async () => {
  await testAuthDb.end();
  await testAdminDb.end();
});

beforeEach(() => {
  vi.resetAllMocks();
});

describe('withApiGuard on a real database', () => {
  it('lets an entitled user reach a feature route', async () => {
    mockSignedInAs(entitledUserId);
    const guarded = withApiGuard(async () => Response.json({ ok: true }), {
      feature: 'core-drive',
    });

    const response = await guarded(createMockHttpRequest(), undefined);
    expect(response.status).toBe(200);
  });

  it('responds 403 to a user who is not entitled to the feature', async () => {
    mockSignedInAs(otherUserId);
    const mockHandler = vi.fn(async () => Response.json({ ok: true }));
    const guarded = withApiGuard(mockHandler, { feature: 'core-drive' });

    const response = await guarded(createMockHttpRequest(), undefined);
    expect(response.status).toBe(403);
    expect(await response.json()).toEqual({ error: 'Feature disabled', code: 'FEATURE_DISABLED' });
    expect(mockHandler).not.toHaveBeenCalled();
  });

  it('gives the handler a transaction that sees only the caller’s profile', async () => {
    mockSignedInAs(entitledUserId);
    const guarded = withApiGuard(async ({ tx }) =>
      Response.json(await tx.select({ id: profiles.id }).from(profiles)),
    );

    const response = await guarded(createMockHttpRequest(), undefined);
    expect(await response.json()).toEqual([{ id: entitledUserId }]);
  });

  it('rolls back the handler’s write when it throws', async () => {
    mockSignedInAs(entitledUserId);
    vi.spyOn(console, 'error').mockImplementation(() => {});
    const guarded = withApiGuard(async ({ tx, caller }) => {
      await tx
        .update(profiles)
        .set({ email: '[email protected]' })
        .where(eq(profiles.id, caller.userId));
      throw new Error('failed after the write');
    });

    const response = await guarded(createMockHttpRequest(), undefined);
    expect(response.status).toBe(500);
    expect(await getProfileEmail(entitledUserId)).toBe('[email protected]');
  });

  it('keeps the handler’s write when it returns an error response instead of throwing', async () => {
    mockSignedInAs(otherUserId);
    const guarded = withApiGuard(async ({ tx, caller }) => {
      await tx
        .update(profiles)
        .set({ email: '[email protected]' })
        .where(eq(profiles.id, caller.userId));
      return Response.json({ error: 'Invalid input', code: 'VALIDATION_ERROR' }, { status: 400 });
    });

    const response = await guarded(createMockHttpRequest(), undefined);
    expect(response.status).toBe(400);
    // Only a throw rolls back: handlers must validate before they write
    expect(await getProfileEmail(otherUserId)).toBe('[email protected]');
  });
});

pnpm --filter @sidekick/core test:integration

pnpm prettier:check
pnpm turbo lint typecheck build test --force
pnpm --filter @sidekick/core test:integration

git add packages/core/package.json packages/core/src/api packages/core/tests/integration/guard.test.ts
git commit -m "feat(core): add withApiGuard with RLS transaction and entitlement check"
git fetch origin main
git rebase --onto origin/main chore/core-test-helpers feature/P2L4-api-guard
git push -u origin feature/P2L4-api-guard --force-with-lease
gh pr create --base main --fill