Add typed context and middleware for oRPC procedures

Use implement(contract).$context<APIContext>() for proper type safety in all procedure handlers. Create authMiddleware and loginRequestMiddleware using os.middleware() and apply with .use() on routes requiring auth. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-09 15:36:26 +08:00
parent 829d365e80
commit a4d1f28f3d
12 changed files with 483 additions and 334 deletions
--- a/apps/api-server/src/procedures/auth/create-login-request.ts
+++ b/apps/api-server/src/procedures/auth/create-login-request.ts
@@ -3,9 +3,6 @@
 * First step in the login flow - validates email and returns available auth methods
 */

-import type { APIContext } from "../../context.js";
-import { implement } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
 import {
  COOKIE_DURATIONS,
  COOKIE_NAMES,
@@ -19,8 +16,7 @@ import {
 } from "../../utils/crypto.js";
 import { getGeoInfo, getUserAgent } from "../../utils/geo.js";
 import { isDeviceTrusted } from "../../utils/session.js";
-
-const os = implement(contract);
+import { os } from "../base.js";

 /**
 * Create login request handler
@@ -33,7 +29,6 @@ const os = implement(contract);
 */
 export const createLoginRequest = os.auth.createLoginRequest.handler(
  async ({ input, context }) => {
-    const ctx = context as APIContext;
    const { email: rawEmail } = input;

    // Normalize email to lowercase
@@ -41,14 +36,14 @@ export const createLoginRequest = os.auth.createLoginRequest.handler(

    // Read or generate device fingerprint
    let deviceFingerprint = getCookie(
-      ctx.reqHeaders,
+      context.reqHeaders,
      COOKIE_NAMES.DEVICE_FINGERPRINT,
    );

    if (!deviceFingerprint) {
      deviceFingerprint = generateDeviceFingerprint();
      setCookie(
-        ctx.resHeaders,
+        context.resHeaders,
        COOKIE_NAMES.DEVICE_FINGERPRINT,
        deviceFingerprint,
        COOKIE_OPTIONS.device,
@@ -56,7 +51,7 @@ export const createLoginRequest = os.auth.createLoginRequest.handler(
    }

    // Look up user by email
-    const user = await ctx.db
+    const user = await context.db
      .selectFrom("users")
      .select(["id", "password_hash"])
      .where("email", "=", email)
@@ -70,7 +65,7 @@ export const createLoginRequest = os.auth.createLoginRequest.handler(

      // Set placeholder login request token cookie
      setCookie(
-        ctx.resHeaders,
+        context.resHeaders,
        COOKIE_NAMES.LOGIN_REQUEST_TOKEN,
        placeholderToken,
        COOKIE_OPTIONS.loginRequest,
@@ -89,13 +84,13 @@ export const createLoginRequest = os.auth.createLoginRequest.handler(

    // Check if device is trusted
    const isTrustedDevice = await isDeviceTrusted(
-      ctx.db,
+      context.db,
      userId,
      deviceFingerprint,
    );

    // Check if user has passkey
-    const passkey = await ctx.db
+    const passkey = await context.db
      .selectFrom("passkeys")
      .select(["id"])
      .where("user_id", "=", userId)
@@ -106,13 +101,13 @@ export const createLoginRequest = os.auth.createLoginRequest.handler(
    const hasPassword = user.password_hash !== null;

    // Get geo info and user agent
-    const geo = getGeoInfo(ctx.reqHeaders);
-    const userAgent = getUserAgent(ctx.reqHeaders);
+    const geo = getGeoInfo(context.reqHeaders);
+    const userAgent = getUserAgent(context.reqHeaders);

    // Create login request
    const expiresAt = generateExpiry(COOKIE_DURATIONS.LOGIN_REQUEST);

-    const loginRequest = await ctx.db
+    const loginRequest = await context.db
      .insertInto("login_requests")
      .values({
        user_id: userId,
@@ -132,7 +127,7 @@ export const createLoginRequest = os.auth.createLoginRequest.handler(

    // Set login request token cookie with the real login request ID
    setCookie(
-      ctx.resHeaders,
+      context.resHeaders,
      COOKIE_NAMES.LOGIN_REQUEST_TOKEN,
      loginRequestId,
      COOKIE_OPTIONS.loginRequest,
--- a/apps/api-server/src/procedures/auth/forgot-password.ts
+++ b/apps/api-server/src/procedures/auth/forgot-password.ts
@@ -1,12 +1,3 @@
-import type { APIContext } from "../../context.js";
-import { implement } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
-import { TOKEN_DURATIONS } from "../../utils/cookies.js";
-import { generateExpiry, generateSecureToken } from "../../utils/crypto.js";
-import { sendPasswordResetEmail } from "../../utils/email.js";
-
-const os = implement(contract);
-
 /**
 * Forgot password handler
 * Public procedure (no authentication required)
@@ -14,16 +5,21 @@ const os = implement(contract);
 * Anti-enumeration: Always returns success even if user doesn't exist
 * This prevents attackers from determining which emails are registered
 */
+
+import { TOKEN_DURATIONS } from "../../utils/cookies.js";
+import { generateExpiry, generateSecureToken } from "../../utils/crypto.js";
+import { sendPasswordResetEmail } from "../../utils/email.js";
+import { os } from "../base.js";
+
 export const forgotPassword = os.auth.forgotPassword.handler(
  async ({ input, context }) => {
-    const ctx = context as APIContext;
    const { email } = input;

    // Normalize email to lowercase
    const normalizedEmail = email.toLowerCase();

    // Look up user by email
-    const user = await ctx.db
+    const user = await context.db
      .selectFrom("users")
      .select(["id", "email"])
      .where("email", "=", normalizedEmail)
@@ -32,7 +28,7 @@ export const forgotPassword = os.auth.forgotPassword.handler(
    // If user exists, create password reset token and send email
    if (user) {
      // Delete any existing password reset tokens for this user (security measure)
-      await ctx.db
+      await context.db
        .deleteFrom("password_resets")
        .where("user_id", "=", user.id)
        .execute();
@@ -43,7 +39,7 @@ export const forgotPassword = os.auth.forgotPassword.handler(
      // Create password reset record with 1 hour expiry
      const expiresAt = generateExpiry(TOKEN_DURATIONS.PASSWORD_RESET);

-      await ctx.db
+      await context.db
        .insertInto("password_resets")
        .values({
          user_id: user.id,
--- a/apps/api-server/src/procedures/auth/login-if-completed.ts
+++ b/apps/api-server/src/procedures/auth/login-if-completed.ts
@@ -16,9 +16,6 @@
 *      e. Return { status: 'completed', redirectTo: '/dashboard' or '/auth/trust-device' }
 */

-import type { APIContext } from "../../context.js";
-import { implement } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
 import {
  COOKIE_NAMES,
  COOKIE_OPTIONS,
@@ -32,8 +29,7 @@ import {
  isDeviceTrusted,
  upsertUserDevice,
 } from "../../utils/session.js";
-
-const os = implement(contract);
+import { os } from "../base.js";

 /**
 * Check if a string looks like a UUID (fake token)
@@ -50,11 +46,9 @@ const isUUID = (str: string): boolean => {
 */
 export const loginIfRequestIsCompleted =
  os.auth.loginIfRequestIsCompleted.handler(async ({ context }) => {
-    const ctx = context as APIContext;
-
    // Read login request token from cookie
    const loginRequestToken = getCookie(
-      ctx.reqHeaders,
+      context.reqHeaders,
      COOKIE_NAMES.LOGIN_REQUEST_TOKEN,
    );

@@ -78,7 +72,7 @@ export const loginIfRequestIsCompleted =
    }

    // Fetch login request from database
-    const loginRequest = await ctx.db
+    const loginRequest = await context.db
      .selectFrom("login_requests")
      .select([
        "id",
@@ -115,12 +109,12 @@ export const loginIfRequestIsCompleted =
    }

    // Get current request info
-    const geo = getGeoInfo(ctx.reqHeaders);
-    const userAgent = getUserAgent(ctx.reqHeaders);
+    const geo = getGeoInfo(context.reqHeaders);
+    const userAgent = getUserAgent(context.reqHeaders);

    // Upsert user device
    const deviceId = await upsertUserDevice(
-      ctx.db,
+      context.db,
      userId,
      deviceFingerprint,
      geo,
@@ -129,13 +123,13 @@ export const loginIfRequestIsCompleted =

    // Check if device is already trusted
    const deviceTrusted = await isDeviceTrusted(
-      ctx.db,
+      context.db,
      userId,
      deviceFingerprint,
    );

    // Create session with trusted mode = true (email-confirmed login)
-    const session = await createSession(ctx.db, {
+    const session = await createSession(context.db, {
      userId,
      deviceId,
      trustedMode: true,
@@ -144,21 +138,21 @@ export const loginIfRequestIsCompleted =
    });

    // Delete the login request (it's been consumed)
-    await ctx.db
+    await context.db
      .deleteFrom("login_requests")
      .where("id", "=", String(loginRequestId))
      .execute();

    // Set session cookie
    setCookie(
-      ctx.resHeaders,
+      context.resHeaders,
      COOKIE_NAMES.SESSION_TOKEN,
      session.token,
      COOKIE_OPTIONS.session,
    );

    // Clear login request cookie
-    deleteCookie(ctx.resHeaders, COOKIE_NAMES.LOGIN_REQUEST_TOKEN);
+    deleteCookie(context.resHeaders, COOKIE_NAMES.LOGIN_REQUEST_TOKEN);

    // Determine redirect path based on device trust status
    const redirectTo = deviceTrusted ? "/dashboard" : "/auth/trust-device";
--- a/apps/api-server/src/procedures/auth/login-password-confirm.ts
+++ b/apps/api-server/src/procedures/auth/login-password-confirm.ts
@@ -1,9 +1,3 @@
-import type { APIContext } from "../../context.js";
-import { implement, ORPCError } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
-
-const os = implement(contract);
-
 /**
 * Confirm password login via email link token
 * Public procedure - no authentication required
@@ -17,13 +11,16 @@ const os = implement(contract);
 * This is called when user clicks the confirmation link in their email
 * for untrusted device login attempts.
 */
+
+import { ORPCError } from "@orpc/server";
+import { os } from "../base.js";
+
 export const loginPasswordConfirm = os.auth.loginPasswordConfirm.handler(
  async ({ input, context }) => {
-    const ctx = context as APIContext;
    const { token } = input;

    // Find the login request by token
-    const loginRequest = await ctx.db
+    const loginRequest = await context.db
      .selectFrom("login_requests")
      .select(["id", "expires_at", "completed_at"])
      .where("token", "=", token)
@@ -48,7 +45,7 @@ export const loginPasswordConfirm = os.auth.loginPasswordConfirm.handler(
    }

    // Mark as completed
-    await ctx.db
+    await context.db
      .updateTable("login_requests")
      .set({ completed_at: new Date() })
      .where("id", "=", loginRequest.id)
--- a/apps/api-server/src/procedures/auth/login-password.ts
+++ b/apps/api-server/src/procedures/auth/login-password.ts
@@ -3,16 +3,13 @@
 * Second step in the login flow - verifies password and completes/confirms login
 */

-import type { APIContext } from "../../context.js";
-import { implement, ORPCError } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
+import { ORPCError } from "@orpc/server";
 import { COOKIE_NAMES, getCookie } from "../../utils/cookies.js";
 import { generateSecureToken } from "../../utils/crypto.js";
 import { sendLoginConfirmationEmail } from "../../utils/email.js";
 import { verifyPassword } from "../../utils/password.js";
 import { isDeviceTrusted } from "../../utils/session.js";
-
-const os = implement(contract);
+import { os } from "../base.js";

 /**
 * Check if a string is a valid login request ID (numeric)
@@ -34,12 +31,11 @@ const isValidLoginRequestId = (value: string): boolean => {
 */
 export const loginPassword = os.auth.loginPassword.handler(
  async ({ input, context }) => {
-    const ctx = context as APIContext;
    const { password } = input;

    // Read login request token from cookie
    const loginRequestToken = getCookie(
-      ctx.reqHeaders,
+      context.reqHeaders,
      COOKIE_NAMES.LOGIN_REQUEST_TOKEN,
    );

@@ -65,7 +61,7 @@ export const loginPassword = os.auth.loginPassword.handler(
    const loginRequestId = loginRequestToken;

    // Fetch login request with user data in single query (optimized JOIN)
-    const result = await ctx.db
+    const result = await context.db
      .selectFrom("login_requests")
      .innerJoin("users", "users.id", "login_requests.user_id")
      .select([
@@ -114,12 +110,12 @@ export const loginPassword = os.auth.loginPassword.handler(
    // Password is valid - check if device is trusted
    // If no device fingerprint, treat as untrusted
    const deviceTrusted = result.device_fingerprint
-      ? await isDeviceTrusted(ctx.db, result.user_id, result.device_fingerprint)
+      ? await isDeviceTrusted(context.db, result.user_id, result.device_fingerprint)
      : false;

    if (deviceTrusted) {
      // Device is trusted - complete login immediately
-      await ctx.db
+      await context.db
        .updateTable("login_requests")
        .set({
          completed_at: new Date(),
@@ -130,7 +126,7 @@ export const loginPassword = os.auth.loginPassword.handler(
      // Device is untrusted - generate confirmation token and send email
      const confirmationToken = generateSecureToken();

-      await ctx.db
+      await context.db
        .updateTable("login_requests")
        .set({
          token: confirmationToken,
--- a/apps/api-server/src/procedures/auth/logout.ts
+++ b/apps/api-server/src/procedures/auth/logout.ts
@@ -2,12 +2,8 @@
 * Logout procedure - revokes the current session and clears the session cookie
 */

-import type { AuthenticatedContext } from "../../context.js";
-import { implement } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
 import { COOKIE_NAMES, deleteCookie } from "../../utils/cookies.js";
-
-const os = implement(contract);
+import { authMiddleware, os } from "../base.js";

 /**
 * Logout handler
@@ -15,18 +11,16 @@ const os = implement(contract);
 * - Revokes the current session by setting revoked_at to now()
 * - Clears the session cookie from the response
 */
-export const logout = os.auth.logout.handler(
-  async ({ context }: { context: unknown }) => {
-    const ctx = context as AuthenticatedContext;
+export const logout = os.auth.logout
+  .use(authMiddleware)
+  .handler(async ({ context }) => {
+  // Revoke the current session
+  await context.db
+    .updateTable("sessions")
+    .set({ revoked_at: new Date() })
+    .where("id", "=", String(context.session.id))
+    .execute();

-    // Revoke the current session
-    await ctx.db
-      .updateTable("sessions")
-      .set({ revoked_at: new Date() })
-      .where("id", "=", String(ctx.session.id))
-      .execute();
-
-    // Clear the session cookie
-    deleteCookie(ctx.resHeaders, COOKIE_NAMES.SESSION_TOKEN);
-  },
-);
+  // Clear the session cookie
+  deleteCookie(context.resHeaders, COOKIE_NAMES.SESSION_TOKEN);
+});
--- a/apps/api-server/src/procedures/auth/resend-verification.ts
+++ b/apps/api-server/src/procedures/auth/resend-verification.ts
@@ -1,12 +1,3 @@
-import type { AuthenticatedContext } from "../../context.js";
-import { implement } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
-import { TOKEN_DURATIONS } from "../../utils/cookies.js";
-import { generateExpiry, generateSecureToken } from "../../utils/crypto.js";
-import { sendVerificationEmail } from "../../utils/email.js";
-
-const os = implement(contract);
-
 /**
 * Resend email verification to authenticated user
 * Requires authentication
@@ -18,37 +9,41 @@ const os = implement(contract);
 * 4. Create new email_verifications record with 24 hour expiry
 * 5. Send verification email (stubbed)
 */
-export const resendVerificationEmail = os.auth.resendVerificationEmail.handler(
-  async ({ context }) => {
-    const ctx = context as AuthenticatedContext;

-    // Check if email is already verified
-    if (ctx.user.emailVerifiedAt !== null) {
-      // Email already verified, return early
-      return;
-    }
+import { TOKEN_DURATIONS } from "../../utils/cookies.js";
+import { generateExpiry, generateSecureToken } from "../../utils/crypto.js";
+import { sendVerificationEmail } from "../../utils/email.js";
+import { authMiddleware, os } from "../base.js";

-    // Delete any existing verification tokens for this user
-    await ctx.db
-      .deleteFrom("email_verifications")
-      .where("user_id", "=", ctx.user.id)
-      .execute();
+export const resendVerificationEmail = os.auth.resendVerificationEmail
+  .use(authMiddleware)
+  .handler(async ({ context }) => {
+  // Check if email is already verified
+  if (context.user.emailVerifiedAt !== null) {
+    // Email already verified, return early
+    return;
+  }

-    // Generate new secure token
-    const token = generateSecureToken();
-    const expiresAt = generateExpiry(TOKEN_DURATIONS.EMAIL_VERIFICATION);
+  // Delete any existing verification tokens for this user
+  await context.db
+    .deleteFrom("email_verifications")
+    .where("user_id", "=", context.user.id)
+    .execute();

-    // Create new verification record
-    await ctx.db
-      .insertInto("email_verifications")
-      .values({
-        user_id: ctx.user.id,
-        token,
-        expires_at: expiresAt,
-      })
-      .execute();
+  // Generate new secure token
+  const token = generateSecureToken();
+  const expiresAt = generateExpiry(TOKEN_DURATIONS.EMAIL_VERIFICATION);

-    // Send verification email (stubbed)
-    await sendVerificationEmail(ctx.user.email, token);
-  },
-);
+  // Create new verification record
+  await context.db
+    .insertInto("email_verifications")
+    .values({
+      user_id: context.user.id,
+      token,
+      expires_at: expiresAt,
+    })
+    .execute();
+
+  // Send verification email (stubbed)
+  await sendVerificationEmail(context.user.email, token);
+});
--- a/apps/api-server/src/procedures/auth/reset-password.ts
+++ b/apps/api-server/src/procedures/auth/reset-password.ts
@@ -1,10 +1,3 @@
-import type { APIContext } from "../../context.js";
-import { implement, ORPCError } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
-import { hashPassword, validatePassword } from "../../utils/password.js";
-
-const os = implement(contract);
-
 /**
 * Reset password handler
 * Public procedure (no authentication required)
@@ -12,13 +5,17 @@ const os = implement(contract);
 * Validates the reset token, checks password strength, updates password,
 * marks token as used, and revokes all existing sessions
 */
+
+import { ORPCError } from "@orpc/server";
+import { hashPassword, validatePassword } from "../../utils/password.js";
+import { os } from "../base.js";
+
 export const resetPassword = os.auth.resetPassword.handler(
  async ({ input, context }) => {
-    const ctx = context as APIContext;
    const { token, newPassword } = input;

    // Find the password reset token
-    const passwordReset = await ctx.db
+    const passwordReset = await context.db
      .selectFrom("password_resets")
      .select(["id", "user_id", "expires_at", "used_at"])
      .where("token", "=", token)
@@ -59,7 +56,7 @@ export const resetPassword = os.auth.resetPassword.handler(
    const passwordHash = await hashPassword(newPassword);

    // Update user's password
-    await ctx.db
+    await context.db
      .updateTable("users")
      .set({
        password_hash: passwordHash,
@@ -69,7 +66,7 @@ export const resetPassword = os.auth.resetPassword.handler(
      .execute();

    // Mark the reset token as used
-    await ctx.db
+    await context.db
      .updateTable("password_resets")
      .set({
        used_at: now,
@@ -78,7 +75,7 @@ export const resetPassword = os.auth.resetPassword.handler(
      .execute();

    // Revoke ALL sessions for this user (security measure)
-    await ctx.db
+    await context.db
      .updateTable("sessions")
      .set({
        revoked_at: now,
--- a/apps/api-server/src/procedures/auth/signup.ts
+++ b/apps/api-server/src/procedures/auth/signup.ts
@@ -8,11 +8,10 @@ import type {
 } from "@simplewebauthn/types";
 import type { Kysely } from "kysely";
 import type { DB } from "@reviq/db-schema";
-import type { APIContext } from "../../context.js";
 import type { RPInfo } from "../../utils/webauthn.js";
-import { implement, ORPCError } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
+import { ORPCError } from "@orpc/server";
 import { verifyRegistrationResponse } from "@simplewebauthn/server";
+import { os } from "../base.js";
 import {
  COOKIE_NAMES,
  COOKIE_OPTIONS,
@@ -26,8 +25,6 @@ import { hashPassword, validatePassword } from "../../utils/password.js";
 import { createSession } from "../../utils/session.js";
 import { getRPInfo, KNOWN_AAGUIDS } from "../../utils/webauthn.js";

-const os = implement(contract);
-
 /**
 * Create user with password authentication
 * Validates password strength and creates user record
@@ -208,14 +205,13 @@ export async function signupWithPasskey(
 * - Sends verification email (stubbed)
 */
 export const signup = os.auth.signup.handler(async ({ input, context }) => {
-  const ctx = context as APIContext;
  const { email: rawEmail, password, passkeyInfo } = input;

  // Normalize email to lowercase
  const email = rawEmail.toLowerCase();

  // Check if email already exists (anti-enumeration: return generic error)
-  const existingUser = await ctx.db
+  const existingUser = await context.db
    .selectFrom("users")
    .select(["id"])
    .where("email", "=", email)
@@ -226,17 +222,17 @@ export const signup = os.auth.signup.handler(async ({ input, context }) => {
  }

  // Get geo info and user agent for session creation
-  const geo = getGeoInfo(ctx.reqHeaders);
-  const userAgent = getUserAgent(ctx.reqHeaders);
+  const geo = getGeoInfo(context.reqHeaders);
+  const userAgent = getUserAgent(context.reqHeaders);

  let userId: number;

  // Delegate to appropriate signup function
  if (password) {
-    userId = await signupWithPassword(ctx.db, email, password);
+    userId = await signupWithPassword(context.db, email, password);
  } else if (passkeyInfo) {
-    const rpInfo = getRPInfo(ctx.origin, ctx.allowedOrigins, ctx.rpName);
-    userId = await signupWithPasskey(ctx.db, email, passkeyInfo, rpInfo);
+    const rpInfo = getRPInfo(context.origin, context.allowedOrigins, context.rpName);
+    userId = await signupWithPasskey(context.db, email, passkeyInfo, rpInfo);
  } else {
    // Should never reach here due to schema validation
    throw new ORPCError("BAD_REQUEST", {
@@ -245,7 +241,7 @@ export const signup = os.auth.signup.handler(async ({ input, context }) => {
  }

  // Create session (7 days, trusted mode false initially, no device)
-  const session = await createSession(ctx.db, {
+  const session = await createSession(context.db, {
    userId,
    deviceId: null,
    trustedMode: false,
@@ -255,7 +251,7 @@ export const signup = os.auth.signup.handler(async ({ input, context }) => {

  // Set session cookie
  setCookie(
-    ctx.resHeaders,
+    context.resHeaders,
    COOKIE_NAMES.SESSION_TOKEN,
    session.token,
    COOKIE_OPTIONS.session,
@@ -266,7 +262,7 @@ export const signup = os.auth.signup.handler(async ({ input, context }) => {
  const expiresAt = generateExpiry(TOKEN_DURATIONS.EMAIL_VERIFICATION);

  // Store verification token (store raw token, not hash - it's already high-entropy)
-  await ctx.db
+  await context.db
    .insertInto("email_verifications")
    .values({
      user_id: userId,
--- a/apps/api-server/src/procedures/auth/verify-email.ts
+++ b/apps/api-server/src/procedures/auth/verify-email.ts
@@ -1,9 +1,3 @@
-import type { APIContext } from "../../context.js";
-import { implement, ORPCError } from "@orpc/server";
-import { contract } from "@reviq/api-contract";
-
-const os = implement(contract);
-
 /**
 * Verify user email with token from URL
 * Public procedure - no authentication required
@@ -14,13 +8,16 @@ const os = implement(contract);
 * 3. Update user's email_verified_at timestamp
 * 4. Delete the verification record
 */
+
+import { ORPCError } from "@orpc/server";
+import { os } from "../base.js";
+
 export const verifyEmail = os.auth.verifyEmail.handler(
  async ({ input, context }) => {
-    const ctx = context as APIContext;
    const { token } = input;

    // Find the verification record
-    const verification = await ctx.db
+    const verification = await context.db
      .selectFrom("email_verifications")
      .select(["id", "user_id", "expires_at"])
      .where("token", "=", token)
@@ -35,7 +32,7 @@ export const verifyEmail = os.auth.verifyEmail.handler(
    // Check if token is expired
    if (new Date() > verification.expires_at) {
      // Clean up expired token
-      await ctx.db
+      await context.db
        .deleteFrom("email_verifications")
        .where("id", "=", verification.id)
        .execute();
@@ -46,14 +43,14 @@ export const verifyEmail = os.auth.verifyEmail.handler(
    }

    // Update user's email_verified_at
-    await ctx.db
+    await context.db
      .updateTable("users")
      .set({ email_verified_at: new Date() })
      .where("id", "=", verification.user_id)
      .execute();

    // Delete the verification record
-    await ctx.db
+    await context.db
      .deleteFrom("email_verifications")
      .where("id", "=", verification.id)
      .execute();
--- a/apps/api-server/src/procedures/base.ts
+++ b/apps/api-server/src/procedures/base.ts
@@ -0,0 +1,215 @@
+/**
+ * Base procedures with typed context for oRPC handlers
+ *
+ * Uses implement(contract).$context<T>() to provide proper type safety.
+ * All procedure handlers should import from this file.
+ */
+
+import type {
+  APIContext,
+  AuthenticatedContext,
+  LoginRequestContext,
+  Session,
+  SessionUser,
+} from "../context.js";
+import { implement, ORPCError } from "@orpc/server";
+import { contract } from "@reviq/api-contract";
+import { COOKIE_NAMES, getCookie } from "../utils/cookies.js";
+import { hashToken } from "../utils/crypto.js";
+
+/**
+ * Base implementer with typed APIContext
+ * All procedures should be derived from this
+ */
+export const os = implement(contract).$context<APIContext>();
+
+/**
+ * Auth middleware - validates session/API token and adds user to context
+ * Use with os.use(authMiddleware) to create authenticated procedures
+ */
+export const authMiddleware = os.middleware(async ({ context, next }) => {
+  const { db, reqHeaders } = context;
+
+  // Try session cookie first
+  let tokenHash: string | undefined;
+  const sessionToken = getCookie(reqHeaders, COOKIE_NAMES.SESSION_TOKEN);
+  if (sessionToken) {
+    tokenHash = hashToken(sessionToken);
+  }
+
+  // Fall back to API key header (for CLI)
+  const apiKey = reqHeaders.get("x-api-key");
+  if (!tokenHash && apiKey) {
+    tokenHash = hashToken(apiKey);
+  }
+
+  if (!tokenHash) {
+    throw new ORPCError("UNAUTHORIZED", { message: "No session or API key" });
+  }
+
+  // Look up session (check not expired and not revoked)
+  const session = await db
+    .selectFrom("sessions")
+    .where("token_hash", "=", tokenHash)
+    .where("expires_at", ">", new Date())
+    .where("revoked_at", "is", null)
+    .selectAll()
+    .executeTakeFirst();
+
+  // Fall back to API token if no session found
+  const apiToken = !session
+    ? await db
+        .selectFrom("api_tokens")
+        .where("token_hash", "=", tokenHash)
+        .where("expires_at", ">", new Date())
+        .selectAll()
+        .executeTakeFirst()
+    : undefined;
+
+  const userId = session?.user_id ?? apiToken?.user_id;
+  if (!userId) {
+    throw new ORPCError("UNAUTHORIZED", {
+      message: "Invalid or expired token",
+    });
+  }
+
+  // Update last_used_at for API tokens
+  if (apiToken) {
+    await db
+      .updateTable("api_tokens")
+      .set({ last_used_at: new Date() })
+      .where("id", "=", apiToken.id)
+      .execute();
+  }
+
+  // Fetch user details
+  const user = await db
+    .selectFrom("users")
+    .where("id", "=", userId)
+    .select([
+      "id",
+      "email",
+      "display_name",
+      "email_verified_at",
+      "is_superuser",
+    ])
+    .executeTakeFirst();
+
+  if (!user) {
+    throw new ORPCError("UNAUTHORIZED", {
+      message: "User not found",
+    });
+  }
+
+  const sessionUser: SessionUser = {
+    id: user.id,
+    email: user.email,
+    displayName: user.display_name,
+    emailVerifiedAt: user.email_verified_at,
+    isSuperuser: user.is_superuser,
+  };
+
+  const sessionInfo: Session = session
+    ? {
+        id: Number(session.id),
+        trustedMode: session.trusted_mode,
+        createdAt: session.created_at,
+      }
+    : {
+        // For API token auth, create a synthetic session object
+        id: 0,
+        trustedMode: true,
+        createdAt: apiToken?.created_at ?? new Date(),
+      };
+
+  return next({
+    context: {
+      user: sessionUser,
+      session: sessionInfo,
+    },
+  });
+});
+
+/**
+ * Login request middleware - validates login request token from cookie
+ */
+export const loginRequestMiddleware = os.middleware(async ({ context, next }) => {
+  const { db, reqHeaders } = context;
+
+  // Read login request token from cookie
+  const loginRequestToken = getCookie(
+    reqHeaders,
+    COOKIE_NAMES.LOGIN_REQUEST_TOKEN,
+  );
+
+  if (!loginRequestToken) {
+    throw new ORPCError("BAD_REQUEST", {
+      message: "No login request found",
+    });
+  }
+
+  // Check if token is a valid login request ID (numeric)
+  const num = Number(loginRequestToken);
+  if (Number.isNaN(num) || !Number.isInteger(num) || num <= 0) {
+    throw new ORPCError("BAD_REQUEST", {
+      message: "Invalid login request",
+    });
+  }
+
+  const loginRequestId = loginRequestToken;
+
+  // Fetch login request with user data
+  const result = await db
+    .selectFrom("login_requests")
+    .innerJoin("users", "users.id", "login_requests.user_id")
+    .select([
+      "login_requests.id",
+      "login_requests.user_id",
+      "login_requests.expires_at",
+      "users.email",
+      "users.display_name",
+      "users.email_verified_at",
+      "users.is_superuser",
+    ])
+    .where("login_requests.id", "=", loginRequestId)
+    .where("login_requests.expires_at", ">", new Date())
+    .executeTakeFirst();
+
+  if (!result) {
+    throw new ORPCError("BAD_REQUEST", {
+      message: "Login request expired or not found",
+    });
+  }
+
+  const sessionUser: SessionUser = {
+    id: result.user_id,
+    email: result.email,
+    displayName: result.display_name,
+    emailVerifiedAt: result.email_verified_at,
+    isSuperuser: result.is_superuser,
+  };
+
+  return next({
+    context: {
+      loginRequestId: Number(result.id),
+      user: sessionUser,
+    },
+  });
+});
+
+/**
+ * Superuser middleware - requires admin access (must be used after authMiddleware)
+ */
+export const superuserMiddleware = os.middleware(async ({ context, next }) => {
+  // This middleware should be used after authMiddleware
+  const ctx = context as AuthenticatedContext;
+  if (!ctx.user.isSuperuser) {
+    throw new ORPCError("FORBIDDEN", {
+      message: "Superuser access required",
+    });
+  }
+  return next();
+});
+
+// Type exports for use in procedure files
+export type { APIContext, AuthenticatedContext, LoginRequestContext };