Use case: an authentication platform

export const SCHEMA = [
  `CREATE TABLE users (
     id serial PRIMARY KEY,
     email text NOT NULL UNIQUE,
     name text NOT NULL,
     password_hash text,
     email_verified boolean NOT NULL DEFAULT false,
     active boolean NOT NULL DEFAULT true,
     created_at timestamptz NOT NULL DEFAULT now())`,
  `CREATE TABLE user_roles (
     user_id integer NOT NULL REFERENCES users (id),
     role text NOT NULL CHECK (role IN ('student', 'tutor', 'admin')),
     PRIMARY KEY (user_id, role))`,
  `CREATE TABLE sessions (
     id text PRIMARY KEY,
     user_id integer NOT NULL REFERENCES users (id),
     ttl_seconds integer NOT NULL,
     created_at timestamptz NOT NULL,
     last_activity_at timestamptz NOT NULL,
     expires_at timestamptz NOT NULL,
     absolute_expires_at timestamptz,
     user_agent text,
     ip text,
     metadata jsonb)`,
  "CREATE INDEX sessions_user_idx ON sessions (user_id)",
  `CREATE TABLE revoked_tokens (jti text PRIMARY KEY, expires_at timestamptz NOT NULL)`,
  `CREATE TABLE password_resets (
     token_hash text PRIMARY KEY,
     user_id integer NOT NULL REFERENCES users (id),
     expires_at timestamptz NOT NULL,
     used_at timestamptz)`,
  `CREATE TABLE identities (
     provider text NOT NULL,
     provider_id text NOT NULL,
     user_id integer NOT NULL REFERENCES users (id),
     PRIMARY KEY (provider, provider_id))`,
  `CREATE TABLE oauth_logins (
     id_hash text PRIMARY KEY,
     state text NOT NULL,
     code_verifier text NOT NULL,
     expires_at timestamptz NOT NULL)`,
  `CREATE TABLE courses (
     id serial PRIMARY KEY,
     title text NOT NULL,
     tutor_id integer NOT NULL REFERENCES users (id))`,
];

import { toSessionId, toUserId } from "@zudojs/auth";
import type { AuthSession, SessionStore, TokenRevocationStore } from "@zudojs/auth";
import { randomHex } from "@zudojs/crypto";
import type { DatabaseClient } from "@zudojs/database";

interface SessionRow {
  id: string;
  user_id: number;
  created_at: Date;
  last_activity_at: Date;
  expires_at: Date;
  absolute_expires_at: Date | null;
  metadata: Record<string, unknown> | null;
}

function toSession(row: SessionRow): AuthSession {
  return {
    id: toSessionId(row.id),
    userId: toUserId(String(row.user_id)),
    createdAt: row.created_at,
    lastActivityAt: row.last_activity_at,
    expiresAt: row.expires_at,
    ...(row.absolute_expires_at ? { absoluteExpiresAt: row.absolute_expires_at } : {}),
    ...(row.metadata ? { metadata: row.metadata } : {}),
  };
}

/** Sessions in PostgreSQL: they survive restarts and are shared by every server. */
export function createPgSessionStore(db: DatabaseClient): SessionStore {
  return {
    async create({ userId, ttlSeconds = 86_400, absoluteTtlSeconds, userAgent, ip, metadata }) {
      const [row] = await db.queryRawUnsafe<SessionRow[]>(
        `INSERT INTO sessions (id, user_id, ttl_seconds, created_at, last_activity_at, expires_at, absolute_expires_at,
           user_agent, ip, metadata)
         VALUES ($1, $2, $3, now(), now(), now() + make_interval(secs => $3::integer),
                 now() + make_interval(secs => $4::integer), $5, $6, $7)
         RETURNING *`,
        [await randomHex(64), Number(userId), ttlSeconds, absoluteTtlSeconds ?? null, userAgent ?? null, ip ?? null, metadata ?? null],
      );
      return toSession(row!);
    },
    async get(sessionId) {
      const [row] = await db.queryRawUnsafe<SessionRow[]>("SELECT * FROM sessions WHERE id = $1 AND expires_at > now()", [sessionId]);
      return row ? toSession(row) : null;
    },
    async touch(sessionId) {
      await db.executeRawUnsafe(
        `UPDATE sessions SET last_activity_at = now(),
           expires_at = LEAST(now() + make_interval(secs => ttl_seconds), COALESCE(absolute_expires_at, 'infinity'))
         WHERE id = $1 AND expires_at > now()`,
        [sessionId],
      );
    },
    async destroy(sessionId) {
      await db.executeRawUnsafe("DELETE FROM sessions WHERE id = $1", [sessionId]);
    },
    async destroyAllForUser(userId) {
      await db.executeRawUnsafe("DELETE FROM sessions WHERE user_id = $1", [Number(userId)]);
    },
  };
}

/** Used refresh tokens. revokeIfNotRevoked is one INSERT, so two replays cannot both win. */
export function createPgRevocationStore(db: DatabaseClient): TokenRevocationStore {
  return {
    async revoke(jti, expiresAt) {
      await db.executeRawUnsafe(
        "INSERT INTO revoked_tokens (jti, expires_at) VALUES ($1, to_timestamp($2)) ON CONFLICT (jti) DO NOTHING",
        [jti, expiresAt],
      );
    },
    async isRevoked(jti) {
      return (await db.queryRawUnsafe<unknown[]>("SELECT 1 FROM revoked_tokens WHERE jti = $1", [jti])).length > 0;
    },
    async revokeIfNotRevoked(jti, expiresAt) {
      const inserted = await db.queryRawUnsafe<unknown[]>(
        "INSERT INTO revoked_tokens (jti, expires_at) VALUES ($1, to_timestamp($2)) ON CONFLICT (jti) DO NOTHING RETURNING jti",
        [jti, expiresAt],
      );
      return inserted.length === 1;
    },
  };
}

import { hashPassword, normalizeLoginIdentifier, toUserId, verifyPassword } from "@zudojs/auth";
import type { AuthUser, UserId } from "@zudojs/auth";
import type { DatabaseClient } from "@zudojs/database";
import { withTransaction } from "@zudojs/database";
import { ConflictError } from "@zudojs/errors";
import { schema } from "@zudojs/schema";

export const Registration = schema.object({
  email: schema.string().trim().toLowerCase().email().max(254),
  name: schema.string().trim().min(1).max(80),
  password: schema.string().min(12).max(128),
});

interface UserRow { id: number; email: string; name: string; active: boolean; created_at: Date; roles: string[] }

const SELECT_USER = `SELECT u.id, u.email, u.name, u.active, u.created_at,
  COALESCE(array_agg(r.role ORDER BY r.role) FILTER (WHERE r.role IS NOT NULL), '{}') AS roles
  FROM users u LEFT JOIN user_roles r ON r.user_id = u.id`;

function toAuthUser(row: UserRow): AuthUser {
  return { id: toUserId(String(row.id)), email: row.email, name: row.name, roles: row.roles, active: row.active, createdAt: row.created_at };
}

/** The users table, in the shape @zudojs/auth asks for. */
export function createAccounts(db: DatabaseClient) {
  async function findOne(where: string, value: unknown): Promise<AuthUser | null> {
    const [row] = await db.queryRawUnsafe<UserRow[]>(`${SELECT_USER} WHERE ${where} GROUP BY u.id`, [value]);
    return row ? toAuthUser(row) : null;
  }

  return {
    findUserByEmail: (email: string) => findOne("u.email = $1", normalizeLoginIdentifier(email)),
    findUserById: (id: UserId) => findOne("u.id = $1", Number(id)),

    async checkPassword(id: UserId, password: string): Promise<boolean> {
      const [row] = await db.queryRawUnsafe<{ password_hash: string | null }[]>("SELECT password_hash FROM users WHERE id = $1", [Number(id)]);
      return row?.password_hash ? verifyPassword(password, row.password_hash) : false;
    },

    async register(input: unknown): Promise<AuthUser> {
      const { email, name, password } = Registration.parse(input);
      const passwordHash = await hashPassword(password);
      const id = await withTransaction(db, async (tx) => {
        const [row] = await tx.$queryRawUnsafe<{ id: number }[]>(
          "INSERT INTO users (email, name, password_hash) VALUES ($1, $2, $3) ON CONFLICT (email) DO NOTHING RETURNING id",
          email, name, passwordHash,
        );
        if (!row) throw new ConflictError("An account with this e-mail already exists");
        await tx.$executeRawUnsafe("INSERT INTO user_roles (user_id, role) VALUES ($1, 'student')", row.id);
        return row.id;
      });
      return (await findOne("u.id = $1", id))!;
    },
  };
}

export type Accounts = ReturnType<typeof createAccounts>;

import { AuthError, createAuthService, createMemoryLoginAttemptStore, parseBearerToken } from "@zudojs/auth";
import type { TokenConfig, TokenPayload } from "@zudojs/auth";
import type { DatabaseClient } from "@zudojs/database";
import { AuthenticationError } from "@zudojs/errors";
import type { HttpMiddleware, HttpRouterContext } from "@zudojs/http";
import type { Accounts } from "./accounts.js";
import { createPgRevocationStore, createPgSessionStore } from "./stores.js";

export function createAuth(db: DatabaseClient, accounts: Accounts, token: TokenConfig) {
  const auth = createAuthService({
    token,
    sessionStore: createPgSessionStore(db),
    revocationStore: createPgRevocationStore(db),
    sessionTtlSeconds: 30 * 60,
    absoluteSessionTtlSeconds: 7 * 24 * 60 * 60,
    findUser: accounts.findUserByEmail,
    findUserById: accounts.findUserById,
    verifyPassword: accounts.checkPassword,
    externalSessionMethods: ["oauth"],
    loginThrottle: {
      store: createMemoryLoginAttemptStore({ windowSeconds: 60 }),
      maxFailedAttempts: 5,
      lockoutSeconds: 15 * 60,
    },
  });

  /** Middleware: a valid access token whose session is still alive. */
  const requireUser: HttpMiddleware = async (ctx, next) => {
    const token = parseBearerToken(ctx.request.getHeader("authorization"));
    if (token === null) throw new AuthenticationError("Sign in first");
    try {
      ctx.state.set("user", await auth.verifyToken(token));
    } catch (error) {
      if (error instanceof AuthError) throw new AuthenticationError("Sign in first");
      throw error;
    }
    return next();
  };

  return { auth, requireUser };
}

export function currentUser(ctx: HttpRouterContext): TokenPayload {
  const user = ctx.state.get("user") as TokenPayload | undefined;
  if (!user) throw new Error("requireUser is missing on this route");
  return user;
}

import type { AuthService } from "@zudojs/auth";
import { hashPassword, toUserId } from "@zudojs/auth";
import { generatePasswordResetToken, hashTokenForStorage } from "@zudojs/crypto";
import type { DatabaseClient } from "@zudojs/database";
import { withTransaction } from "@zudojs/database";
import { DomainError } from "@zudojs/errors";
import { schema } from "@zudojs/schema";
import type { Accounts } from "./accounts.js";

export interface Mailer {
  send(to: string, subject: string, text: string): Promise<void>;
}

const ResetRequest = schema.object({ email: schema.string().trim().toLowerCase().max(254) });
const ResetConfirm = schema.object({ token: schema.string().min(20).max(200), password: schema.string().min(12).max(128) });

export function createPasswordResets(db: DatabaseClient, accounts: Accounts, auth: AuthService, mailer: Mailer, appUrl: string) {
  return {
    /** Always succeeds from the caller's point of view: it never reveals whether the e-mail has an account. */
    async request(input: unknown): Promise<void> {
      const { email } = ResetRequest.parse(input);
      const user = await accounts.findUserByEmail(email);
      if (!user?.active) return;
      const token = await generatePasswordResetToken();
      await withTransaction(db, async (tx) => {
        await tx.$executeRawUnsafe("DELETE FROM password_resets WHERE user_id = $1", Number(user.id));
        await tx.$executeRawUnsafe(
          "INSERT INTO password_resets (token_hash, user_id, expires_at) VALUES ($1, $2, now() + interval '30 minutes')",
          await hashTokenForStorage(token), Number(user.id),
        );
      });
      await mailer.send(user.email, "Reset your Sabi password", `Open ${appUrl}/reset-password#token=${token} within 30 minutes.`);
    },

    /** Uses the token once, sets the new password and signs the user out everywhere. */
    async confirm(input: unknown): Promise<void> {
      const { token, password } = ResetConfirm.parse(input);
      const tokenHash = await hashTokenForStorage(token);
      const invalid = () => new DomainError("This reset link is invalid or has expired", { code: "RESET_TOKEN_INVALID" });
      const live = "token_hash = $1 AND used_at IS NULL AND expires_at > now()";
      const [found] = await db.queryRawUnsafe<unknown[]>(`SELECT 1 FROM password_resets WHERE ${live}`, [tokenHash]);
      if (!found) throw invalid(); // before the slow hash, so guessing costs the server nothing
      const passwordHash = await hashPassword(password);
      const userId = await withTransaction(db, async (tx) => {
        const [used] = await tx.$queryRawUnsafe<{ user_id: number }[]>(
          `UPDATE password_resets SET used_at = now() WHERE ${live} RETURNING user_id`, tokenHash,
        );
        if (!used) throw invalid(); // another request used it a moment ago
        await tx.$executeRawUnsafe("UPDATE users SET password_hash = $2, email_verified = true WHERE id = $1", used.user_id, passwordHash);
        return toUserId(String(used.user_id));
      });
      await auth.logoutAll(userId);
    },
  };
}

import type { TokenPayload } from "@zudojs/auth";
import { AuthorizationError } from "@zudojs/errors";
import { createPermissionActor, createPermissionEngine, isOwner } from "@zudojs/permissions";

export const ROLES = ["student", "tutor", "admin"] as const;

export const permissions = createPermissionEngine({
  roles: [
    { name: "student", permissions: ["course:read"] },
    {
      name: "tutor",
      inherits: ["student"],
      permissions: ["course:create"],
      rules: [{ name: "own-courses", effect: "allow", resource: "course", action: ["update"], condition: isOwner("tutorId") }],
    },
    { name: "admin", inherits: ["tutor"], permissions: ["course:*", "user:assign-roles"] },
  ],
});

/** Throws 403 unless the signed-in user may do `permission` (on `resource`, when given). */
export async function authorizeUser(user: TokenPayload, permission: string, resource?: Record<string, unknown>): Promise<void> {
  const actor = createPermissionActor(user.sub, { roles: user.roles ?? [] });
  const decision = await permissions.check(actor, permission, resource);
  if (!decision.allowed) throw new AuthorizationError("You may not do this");
}

import { createHash, randomBytes } from "node:crypto";
import { createHttpServer, createNodeHttpAdapter, createResponseContext, createRouter } from "@zudojs/http";

/*
 * A tiny OAuth 2 provider for tests: "Kora ID". It runs on a real port and checks what a
 * real provider checks: the client, the exact redirect URI, PKCE, and single-use codes.
 * The query parameter "as" stands in for the person typing their password at Kora.
 */
export interface KoraPerson { readonly sub: string; readonly email: string; readonly email_verified: boolean; readonly name: string }

export async function startFakeKora(client: { id: string; secret: string; redirectUri: string }, people: Record<string, KoraPerson>) {
  const codes = new Map<string, { challenge: string; person: KoraPerson }>();
  const accessTokens = new Map<string, KoraPerson>();
  const random = () => randomBytes(16).toString("hex");
  const router = createRouter();

  router.get("/authorize", (ctx) => {
    const q = ctx.query as Record<string, string>;
    const person = people[q.as ?? ""];
    if (q.client_id !== client.id || q.redirect_uri !== client.redirectUri || q.code_challenge_method !== "S256" || !person) {
      return createResponseContext({ status: 400 }).json({ error: "invalid_request" });
    }
    const code = random();
    codes.set(code, { challenge: q.code_challenge ?? "", person });
    return createResponseContext().redirect(`${client.redirectUri}?code=${code}&state=${encodeURIComponent(q.state ?? "")}`);
  });

  router.post("/token", (ctx) => {
    const form = new URLSearchParams(new TextDecoder().decode(ctx.request.body as Uint8Array));
    const grant = codes.get(form.get("code") ?? "");
    codes.delete(form.get("code") ?? "");
    const proof = createHash("sha256").update(form.get("code_verifier") ?? "").digest("base64url");
    const clientOk = form.get("client_id") === client.id && form.get("client_secret") === client.secret;
    if (!grant || !clientOk || grant.challenge !== proof || form.get("redirect_uri") !== client.redirectUri) {
      return createResponseContext({ status: 400 }).json({ error: "invalid_grant" });
    }
    const accessToken = random();
    accessTokens.set(accessToken, grant.person);
    return createResponseContext().json({ access_token: accessToken, token_type: "Bearer", expires_in: 3600 });
  });

  router.get("/userinfo", (ctx) => {
    const person = accessTokens.get((ctx.request.getHeader("authorization") ?? "").replace("Bearer ", ""));
    return person ? createResponseContext().json(person) : createResponseContext({ status: 401 }).json({ error: "invalid_token" });
  });

  const server = createHttpServer({
    adapter: createNodeHttpAdapter({ host: "127.0.0.1", port: 0 }),
    handler: async (request) => (await router.dispatch(request)).response,
  });
  await server.start();
  return { base: `http://127.0.0.1:${server.address?.port}`, stop: () => server.stop() };
}

import type { AuthService, UserId } from "@zudojs/auth";
import { toUserId } from "@zudojs/auth";
import {
  createAuthorizationUrl, exchangeCodeForToken, fetchUserInfo, generateState, OAuthStateMismatchError, verifyState,
} from "@zudojs/auth-oauth";
import type { OAuthConfig, OAuthUserInfo } from "@zudojs/auth-oauth";
import { hashTokenForStorage, randomBase64Url } from "@zudojs/crypto";
import type { DatabaseClient } from "@zudojs/database";
import { withTransaction } from "@zudojs/database";
import { DomainError } from "@zudojs/errors";

export const KORA_CALLBACK = "http://localhost:3000/v1/oauth/kora/callback";

export function createKoraSignIn(db: DatabaseClient, auth: AuthService, kora: OAuthConfig) {
  /**
   * The local account for a Kora profile. Only a verified e-mail may create or link an account.
   * Linking to an account whose own e-mail was never verified evicts whoever set its password.
   */
  async function accountFor(profile: OAuthUserInfo): Promise<{ userId: UserId; evicted: boolean }> {
    const [linked] = await db.queryRawUnsafe<{ user_id: number }[]>(
      "SELECT user_id FROM identities WHERE provider = 'kora' AND provider_id = $1",
      [profile.providerId],
    );
    if (linked) return { userId: toUserId(String(linked.user_id)), evicted: false };
    if (profile.emailVerified !== true || !profile.email) {
      throw new DomainError("Kora has not verified this e-mail address", { code: "EMAIL_NOT_VERIFIED" });
    }
    const email = profile.email.toLowerCase();
    return withTransaction(db, async (tx) => {
      const [existing] = await tx.$queryRawUnsafe<{ id: number; email_verified: boolean }[]>(
        "SELECT id, email_verified FROM users WHERE email = $1 FOR UPDATE", email,
      );
      let userId = existing?.id;
      const evicted = existing !== undefined && !existing.email_verified;
      if (userId === undefined) {
        const [created] = await tx.$queryRawUnsafe<{ id: number }[]>(
          "INSERT INTO users (email, name, email_verified) VALUES ($1, $2, true) RETURNING id", email, profile.name ?? email,
        );
        userId = created!.id;
        await tx.$executeRawUnsafe("INSERT INTO user_roles (user_id, role) VALUES ($1, 'student')", userId);
      } else if (evicted) {
        await tx.$executeRawUnsafe("UPDATE users SET password_hash = NULL, email_verified = true WHERE id = $1", userId);
      }
      await tx.$executeRawUnsafe("INSERT INTO identities (provider, provider_id, user_id) VALUES ('kora', $1, $2)", profile.providerId, userId);
      return { userId: toUserId(String(userId)), evicted };
    });
  }

  return {
    /** Step 1: remember state and PKCE verifier on the server; the browser only gets an opaque login id. */
    async start(): Promise<{ url: string; loginId: string }> {
      const state = generateState();
      const { url, codeVerifier } = createAuthorizationUrl(kora, { state, redirectUri: KORA_CALLBACK });
      const loginId = await randomBase64Url(32);
      await db.executeRawUnsafe(
        "INSERT INTO oauth_logins (id_hash, state, code_verifier, expires_at) VALUES ($1, $2, $3, now() + interval '10 minutes')",
        [await hashTokenForStorage(loginId), state, codeVerifier],
      );
      return { url, loginId };
    },

    /** Step 2: the callback. State first, then the code, then the account, then our own session. */
    async finish(loginId: string | undefined, query: Readonly<Record<string, string | string[]>>) {
      const [pending] = loginId === undefined ? [] : await db.queryRawUnsafe<{ state: string; code_verifier: string }[]>(
        "DELETE FROM oauth_logins WHERE id_hash = $1 AND expires_at > now() RETURNING state, code_verifier",
        [await hashTokenForStorage(loginId)],
      );
      const state = typeof query.state === "string" ? query.state : "";
      if (!pending || !verifyState(pending.state, state)) throw new OAuthStateMismatchError();
      if (typeof query.code !== "string" || query.code === "") throw new DomainError("Sign-in was cancelled", { code: "OAUTH_CANCELLED" });

      const tokens = await exchangeCodeForToken(kora, { code: query.code, codeVerifier: pending.code_verifier, redirectUri: KORA_CALLBACK });
      const { userId, evicted } = await accountFor(await fetchUserInfo(kora, tokens.accessToken));
      if (evicted) await auth.logoutAll(userId);
      return auth.createSessionForUser(userId, { method: "oauth", metadata: { provider: "kora" } });
    },
  };
}

import { randomUUID } from "node:crypto";
import { normalizeToBaseError } from "@zudojs/errors";
import { createResponseContext, type HttpRequestContext } from "@zudojs/http";
import type { Logger } from "@zudojs/logger";
import { isSchemaValidationError } from "@zudojs/schema";

/** The error envelope from the REST API lesson, plus the headers some errors carry (Retry-After). */
export function createErrorHandler(logger: Logger) {
  return (thrown: unknown, request: HttpRequestContext) => {
    if (isSchemaValidationError(thrown)) {
      const issues = thrown.issues.map((issue) => ({ path: issue.path.join(".") || "(body)", message: issue.message }));
      return createResponseContext({ status: 400 }).json({ error: { code: "VALIDATION_FAILED", message: "The request is not valid", issues } });
    }
    const error = normalizeToBaseError(thrown);
    if (error.expose && error.statusCode < 500) {
      const response = createResponseContext({ status: error.statusCode });
      const headers = (thrown as { headers?: Record<string, string> }).headers ?? {};
      for (const [name, value] of Object.entries(headers)) response.setHeader(name, value);
      return response.json({ error: { code: error.code, message: error.message } });
    }
    const requestId = randomUUID();
    logger.error("Request failed", { requestId, method: request.method, path: request.path, error: thrown instanceof Error ? thrown : String(thrown) });
    return createResponseContext({ status: 500 }).json({ error: { code: "INTERNAL", message: "Something went wrong on our side", requestId } });
  };
}

import type { TokenConfig } from "@zudojs/auth";
import { parseCookies, toUserId } from "@zudojs/auth";
import type { OAuthConfig } from "@zudojs/auth-oauth";
import type { DatabaseClient } from "@zudojs/database";
import { withTransaction } from "@zudojs/database";
import { NotFoundError } from "@zudojs/errors";
import {
  badRequest, createHttpServer, createNodeHttpAdapter, createRateLimitMiddleware, createResponseContext, createRouter,
} from "@zudojs/http";
import type { HttpRouterContext } from "@zudojs/http";
import type { Logger } from "@zudojs/logger";
import { schema } from "@zudojs/schema";
import { createAccounts } from "./accounts.js";
import { createAuth, currentUser } from "./auth.js";
import { createErrorHandler } from "./errors.js";
import { createKoraSignIn } from "./kora.js";
import { createPasswordResets, type Mailer } from "./resets.js";
import { authorizeUser, ROLES } from "./roles.js";

const Login = schema.object({ email: schema.string().max(254), password: schema.string().min(1).max(128) });
const Refresh = schema.object({ refreshToken: schema.string().min(1).max(4096) });
const NewCourse = schema.object({ title: schema.string().trim().min(3).max(120) });
const RoleUpdate = schema.object({ roles: schema.array(schema.enum(ROLES)).min(1).max(3) });
const Id = schema.object({ id: schema.coerce.number().int().min(1).max(2_147_483_647) });

function body(ctx: HttpRouterContext): unknown {
  try {
    return JSON.parse(new TextDecoder().decode(ctx.request.body as Uint8Array));
  } catch {
    throw badRequest("The body is not valid JSON");
  }
}
const json = (status: number, data?: unknown) => (data === undefined ? createResponseContext({ status }) : createResponseContext({ status }).json(data));
const perMinute = (max: number) => createRateLimitMiddleware({ max, windowMs: 60_000 });

export interface PlatformOptions {
  readonly db: DatabaseClient;
  readonly tokens: TokenConfig;
  readonly kora: OAuthConfig;
  readonly mailer: Mailer;
  readonly logger: Logger;
  /** Per client address; tests that log in many times raise it. */
  readonly loginsPerMinute?: number;
}

export function createPlatform({ db, tokens, kora, mailer, logger, loginsPerMinute = 10 }: PlatformOptions) {
  const accounts = createAccounts(db);
  const { auth, requireUser } = createAuth(db, accounts, tokens);
  const resets = createPasswordResets(db, accounts, auth, mailer, "https://sabi.example");
  const koraSignIn = createKoraSignIn(db, auth, kora);
  const signedIn = { middleware: [requireUser] };
  const router = createRouter();

  router.post("/v1/users", async (ctx) => {
    const user = await accounts.register(body(ctx));
    return json(201, { id: user.id, email: user.email, roles: user.roles });
  }, { middleware: [perMinute(20)] });

  router.post("/v1/sessions", async (ctx) => {
    const { email, password } = Login.parse(body(ctx));
    const client = { ip: ctx.request.remoteAddress, userAgent: ctx.request.getHeader("user-agent")?.slice(0, 200) };
    const { tokens: pair } = await auth.login({ identifier: email, password }, client);
    return json(201, pair);
  }, { middleware: [perMinute(loginsPerMinute)] });

  router.post("/v1/sessions/refresh", async (ctx) => json(200, await auth.refresh(Refresh.parse(body(ctx)).refreshToken)));

  router.delete("/v1/sessions/current", async (ctx) => {
    const { sid } = currentUser(ctx);
    if (sid !== undefined) await auth.logout(sid);
    return json(204);
  }, signedIn);

  router.delete("/v1/sessions", async (ctx) => {
    await auth.logoutAll(currentUser(ctx).sub);
    return json(204);
  }, signedIn);

  router.get("/v1/me", async (ctx) => {
    const user = await accounts.findUserById(currentUser(ctx).sub);
    return json(200, { id: user?.id, email: user?.email, roles: user?.roles });
  }, signedIn);

  router.post("/v1/password-resets", async (ctx) => {
    await resets.request(body(ctx));
    return json(202, { message: "If the address has an account, a reset link is on its way." });
  }, { middleware: [perMinute(5)] });

  router.post("/v1/password-resets/confirm", async (ctx) => {
    await resets.confirm(body(ctx));
    return json(204);
  }, { middleware: [perMinute(10)] });

  router.get("/v1/oauth/kora", async () => {
    const { url, loginId } = await koraSignIn.start();
    return createResponseContext().cookie("kora_login", loginId, { maxAge: 600, path: "/v1/oauth/kora" }).redirect(url);
  });

  router.get("/v1/oauth/kora/callback", async (ctx) => {
    const loginId = parseCookies(ctx.request.getHeader("cookie")).kora_login;
    const { tokens: pair } = await koraSignIn.finish(loginId, ctx.query);
    return json(200, pair).cookie("kora_login", "", { maxAge: 0, path: "/v1/oauth/kora" });
  });

  router.get("/v1/courses", async (ctx) => {
    await authorizeUser(currentUser(ctx), "course:read");
    return json(200, await db.queryRawUnsafe(`SELECT id, title, tutor_id AS "tutorId" FROM courses ORDER BY id`));
  }, signedIn);

  router.post("/v1/courses", async (ctx) => {
    const user = currentUser(ctx);
    await authorizeUser(user, "course:create");
    const { title } = NewCourse.parse(body(ctx));
    const [course] = await db.queryRawUnsafe<unknown[]>(
      `INSERT INTO courses (title, tutor_id) VALUES ($1, $2) RETURNING id, title, tutor_id AS "tutorId"`, [title, Number(user.sub)],
    );
    return json(201, course);
  }, signedIn);

  router.patch("/v1/courses/:id", async (ctx) => {
    const user = currentUser(ctx);
    const { id } = Id.parse(ctx.params);
    const [course] = await db.queryRawUnsafe<{ id: number; tutorId: number }[]>(`SELECT id, tutor_id AS "tutorId" FROM courses WHERE id = $1`, [id]);
    if (!course) throw new NotFoundError(`Course ${id} not found`);
    await authorizeUser(user, "course:update", course);
    const { title } = NewCourse.parse(body(ctx));
    await db.executeRawUnsafe("UPDATE courses SET title = $2 WHERE id = $1", [id, title]);
    return json(200, { id, title, tutorId: course.tutorId });
  }, signedIn);

  router.put("/v1/users/:id/roles", async (ctx) => {
    const admin = currentUser(ctx);
    await authorizeUser(admin, "user:assign-roles");
    const { id } = Id.parse(ctx.params);
    const { roles } = RoleUpdate.parse(body(ctx));
    if (String(id) === admin.sub) throw badRequest("You cannot change your own roles");
    if (!(await accounts.findUserById(toUserId(String(id))))) throw new NotFoundError(`User ${id} not found`);
    await withTransaction(db, async (tx) => {
      await tx.$executeRawUnsafe("DELETE FROM user_roles WHERE user_id = $1", id);
      for (const role of new Set(roles)) await tx.$executeRawUnsafe("INSERT INTO user_roles (user_id, role) VALUES ($1, $2)", id, role);
    });
    await auth.logoutAll(toUserId(String(id)));
    return json(200, { id, roles: [...new Set(roles)].sort() });
  }, signedIn);

  const server = createHttpServer({
    adapter: createNodeHttpAdapter({ host: "127.0.0.1", port: 0 }),
    handler: async (request) => (await router.dispatch(request)).response,
    errorHandler: createErrorHandler(logger),
  });
  return { server, auth, accounts };
}

import { randomBytes } from "node:crypto";
import { createLogger } from "@zudojs/logger";
import { startFakeKora, type KoraPerson } from "./fake-kora.js";
import { createPlatform } from "./http.js";
import { KORA_CALLBACK } from "./kora.js";
import { SCHEMA } from "./schema.js";
import { openDatabase } from "./sql.js";

/* DEMO ONLY: random secrets for each run. Your app reads them from the environment. */
const secret = () => randomBytes(32).toString("base64url");

export const KORA_PEOPLE: Record<string, KoraPerson> = {
  ada: { sub: "kora-1001", email: "ada@example.com", email_verified: true, name: "Ada Obi" },
  bola: { sub: "kora-1002", email: "bola@example.com", email_verified: true, name: "Bola Ade" },
  eve: { sub: "kora-6666", email: "ada@example.com", email_verified: false, name: "Eve" },
};

export interface Reply { readonly status: number; readonly headers: Headers; readonly body: any }

/** Starts Sabi's account platform and a fake Kora ID, each on a free port. */
export async function startSabi({ log = console.log, loginsPerMinute = 10 }: { log?: (line: string) => void; loginsPerMinute?: number } = {}) {
  const koraClient = { id: "sabi-web", secret: secret(), redirectUri: KORA_CALLBACK };
  const kora = await startFakeKora(koraClient, KORA_PEOPLE);
  const db = await openDatabase(SCHEMA);
  const outbox: { to: string; subject: string; text: string }[] = [];
  const platform = createPlatform({
    db,
    loginsPerMinute,
    tokens: { accessSecret: secret(), refreshSecret: secret(), issuer: "sabi", audience: "sabi-api" },
    kora: {
      provider: "custom",
      clientId: koraClient.id,
      clientSecret: koraClient.secret,
      authorizeUrl: "https://id.kora.example/authorize",
      tokenUrl: "https://id.kora.example/token",
      userInfoUrl: "https://id.kora.example/userinfo",
      allowedRedirectUris: [KORA_CALLBACK],
      scopes: ["openid", "email", "profile"],
      // Tests only: Kora's public address is served by the fake on this machine.
      fetch: (url, init) => fetch(url.replace("https://id.kora.example", kora.base), init),
    },
    mailer: { send: async (to, subject, text) => void outbox.push({ to, subject, text }) },
    logger: createLogger({
      name: "sabi",
      transports: [
        (entry) => {
          const { error } = entry.metadata as { error?: { name: string; message: string } };
          log(`[${entry.levelName}] ${entry.message}: ${error?.name}: ${error?.message}`);
        },
      ],
    }),
  });
  await platform.server.start();
  const base = `http://127.0.0.1:${platform.server.address?.port}`;

  async function call(method: string, path: string, data?: unknown, token?: string, headers: Record<string, string> = {}): Promise<Reply> {
    const response = await fetch(base + path, {
      method,
      redirect: "manual",
      headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}), ...headers },
      body: data === undefined ? undefined : JSON.stringify(data),
    });
    const text = await response.text();
    return { status: response.status, headers: response.headers, body: text ? JSON.parse(text) : null };
  }

  async function stop(): Promise<void> {
    await platform.server.stop();
    await kora.stop();
    await db.disconnect();
  }

  return { db, base, kora, outbox, call, stop, auth: platform.auth };
}

import { startSabi, type Reply } from "./sabi.js";

const sabi = await startSabi();
const show = (label: string, r: Reply) => console.log(`${label} -> ${r.status}`, r.body?.error ? r.body.error.code : "");
const password = "ada's long passphrase";

const joined = await sabi.call("POST", "/v1/users", { email: "Ada@Example.com", name: "Ada", password, roles: ["admin"] });
console.log("register ->", joined.status, joined.body);

const laptop = (await sabi.call("POST", "/v1/sessions", { email: "ada@example.com", password })).body;
const phone = (await sabi.call("POST", "/v1/sessions", { email: "ada@example.com", password })).body;
console.log("tokens:", Object.keys(laptop), laptop.expiresIn);
show("me on laptop", await sabi.call("GET", "/v1/me", undefined, laptop.accessToken));

const refreshed = await sabi.call("POST", "/v1/sessions/refresh", { refreshToken: laptop.refreshToken });
show("refresh", refreshed);
show("refresh with the old token again", await sabi.call("POST", "/v1/sessions/refresh", { refreshToken: laptop.refreshToken }));
show("laptop's new token after the replay", await sabi.call("GET", "/v1/me", undefined, refreshed.body.accessToken));
show("phone after the replay", await sabi.call("GET", "/v1/me", undefined, phone.accessToken));

const again = (await sabi.call("POST", "/v1/sessions", { email: "ada@example.com", password })).body;
show("log out", await sabi.call("DELETE", "/v1/sessions/current", undefined, again.accessToken));
show("same token after log out", await sabi.call("GET", "/v1/me", undefined, again.accessToken));
const rows = await sabi.db.queryRawUnsafe<{ n: number }[]>("SELECT count(*)::int AS n FROM sessions");
console.log("sessions left:", rows[0]?.n);
await sabi.stop();

register -> 201 { id: '1', email: 'ada@example.com', roles: [ 'student' ] }
tokens: [ 'accessToken', 'refreshToken', 'expiresIn', 'tokenType' ] 900
me on laptop -> 200
refresh -> 200
refresh with the old token again -> 401 ERR_TOKEN_REVOKED
laptop's new token after the replay -> 401 ERR_AUTHENTICATION_FAILED
phone after the replay -> 401 ERR_AUTHENTICATION_FAILED
log out -> 204
same token after log out -> 401 ERR_AUTHENTICATION_FAILED
sessions left: 0

import { startSabi, type Reply } from "./sabi.js";

const sabi = await startSabi();
const show = (label: string, r: Reply) => console.log(`${label} -> ${r.status}`, r.body?.error?.code ?? r.body?.message ?? "");
await sabi.call("POST", "/v1/users", { email: "ada@example.com", name: "Ada", password: "old passphrase 2025" });
const before = (await sabi.call("POST", "/v1/sessions", { email: "ada@example.com", password: "old passphrase 2025" })).body;

show("reset for Ada", await sabi.call("POST", "/v1/password-resets", { email: "ADA@example.com" }));
show("reset for a stranger", await sabi.call("POST", "/v1/password-resets", { email: "nobody@example.com" }));
console.log("e-mails sent:", sabi.outbox.map((mail) => `${mail.to}: ${mail.subject}`));

const token = sabi.outbox[0]!.text.match(/token=(\S+)/)![1]!;
const stored = await sabi.db.queryRawUnsafe<{ token_hash: string }[]>("SELECT token_hash FROM password_resets");
console.log("token starts with", token.slice(0, 6), "| stored as", stored[0]!.token_hash.length, "hex characters, not the token:", stored[0]!.token_hash !== token);

show("confirm with a guessed token", await sabi.call("POST", "/v1/password-resets/confirm", { token: "reset_" + "A".repeat(43), password: "new passphrase 2026" }));
show("confirm", await sabi.call("POST", "/v1/password-resets/confirm", { token, password: "new passphrase 2026" }));
show("confirm again with the same link", await sabi.call("POST", "/v1/password-resets/confirm", { token, password: "attacker passphrase" }));
show("session from before the reset", await sabi.call("GET", "/v1/me", undefined, before.accessToken));
show("old password", await sabi.call("POST", "/v1/sessions", { email: "ada@example.com", password: "old passphrase 2025" }));
show("new password", await sabi.call("POST", "/v1/sessions", { email: "ada@example.com", password: "new passphrase 2026" }));

await sabi.call("POST", "/v1/password-resets", { email: "ada@example.com" });
await sabi.db.executeRawUnsafe("UPDATE password_resets SET expires_at = now() - interval '1 minute'"); // 31 minutes later
const late = sabi.outbox[1]!.text.match(/token=(\S+)/)![1]!;
show("confirm after 30 minutes", await sabi.call("POST", "/v1/password-resets/confirm", { token: late, password: "another passphrase" }));
await sabi.stop();

reset for Ada -> 202 If the address has an account, a reset link is on its way.
reset for a stranger -> 202 If the address has an account, a reset link is on its way.
e-mails sent: [ 'ada@example.com: Reset your Sabi password' ]
token starts with reset_ | stored as 64 hex characters, not the token: true
confirm with a guessed token -> 422 RESET_TOKEN_INVALID
confirm -> 204
confirm again with the same link -> 422 RESET_TOKEN_INVALID
session from before the reset -> 401 ERR_AUTHENTICATION_FAILED
old password -> 401 ERR_INVALID_CREDENTIALS
new password -> 201
confirm after 30 minutes -> 422 RESET_TOKEN_INVALID

import { startSabi, type Reply } from "./sabi.js";

const sabi = await startSabi();
const show = (label: string, r: Reply) => console.log(`${label} -> ${r.status}`, r.body?.error?.code ?? JSON.stringify(r.body ?? ""));
const passwordOf = (email: string) => `${email} long passphrase`;
const register = async (email: string) =>
  (await sabi.call("POST", "/v1/users", { email, name: email.split("@")[0], password: passwordOf(email) })).body.id as string;
const logIn = async (email: string) =>
  (await sabi.call("POST", "/v1/sessions", { email, password: passwordOf(email) })).body.accessToken as string;

const graceId = await register("grace@sabi.example");
await sabi.db.executeRawUnsafe("INSERT INTO user_roles (user_id, role) VALUES ($1, 'admin')", [Number(graceId)]); // seed script
const admin = await logIn("grace@sabi.example");
const tundeId = await register("tunde@example.com");
const student = await logIn("tunde@example.com");

show("student creates a course", await sabi.call("POST", "/v1/courses", { title: "Algebra 1" }, student));
show("student makes himself tutor", await sabi.call("PUT", `/v1/users/${tundeId}/roles`, { roles: ["tutor"] }, student));
show("admin makes Tunde a tutor", await sabi.call("PUT", `/v1/users/${tundeId}/roles`, { roles: ["student", "tutor"] }, admin));
show("Tunde's old token", await sabi.call("GET", "/v1/courses", undefined, student));

const tutor = await logIn("tunde@example.com");
show("tutor creates a course", await sabi.call("POST", "/v1/courses", { title: "Algebra 1" }, tutor));
show("admin creates a course", await sabi.call("POST", "/v1/courses", { title: "Chemistry" }, admin));
show("tutor renames his course", await sabi.call("PATCH", "/v1/courses/1", { title: "Algebra for beginners" }, tutor));
show("tutor renames Grace's course", await sabi.call("PATCH", "/v1/courses/2", { title: "Tunde's now" }, tutor));
show("tutor reads courses", await sabi.call("GET", "/v1/courses", undefined, tutor));
show("admin changes own roles", await sabi.call("PUT", `/v1/users/${graceId}/roles`, { roles: ["student"] }, admin));
await sabi.stop();

student creates a course -> 403 ERR_FORBIDDEN
student makes himself tutor -> 403 ERR_FORBIDDEN
admin makes Tunde a tutor -> 200 {"id":2,"roles":["student","tutor"]}
Tunde's old token -> 401 ERR_AUTHENTICATION_FAILED
tutor creates a course -> 201 {"id":1,"title":"Algebra 1","tutorId":2}
admin creates a course -> 201 {"id":2,"title":"Chemistry","tutorId":1}
tutor renames his course -> 200 {"id":1,"title":"Algebra for beginners","tutorId":2}
tutor renames Grace's course -> 403 ERR_FORBIDDEN
tutor reads courses -> 200 [{"id":1,"title":"Algebra for beginners","tutorId":2},{"id":2,"title":"Chemistry","tutorId":1}]
admin changes own roles -> 400 BAD_REQUEST

import { startSabi } from "./sabi.js";

const sabi = await startSabi();

/** Plays the browser: start at Sabi, sign in at Kora as `person`, come back to the callback. */
async function signInWithKora(person: string, options: { dropCookie?: boolean; replay?: boolean } = {}) {
  const start = await sabi.call("GET", "/v1/oauth/kora");
  const cookie = (start.headers.get("set-cookie") ?? "").split(";")[0]!;
  const authorize = new URL(start.headers.get("location")!);
  authorize.searchParams.set("as", person);
  const atKora = await fetch(authorize.toString().replace("https://id.kora.example", sabi.kora.base), { redirect: "manual" });
  const back = new URL(atKora.headers.get("location")!);
  const callback = () => sabi.call("GET", back.pathname + back.search, undefined, undefined, options.dropCookie ? {} : { cookie });
  const first = await callback();
  return options.replay ? callback() : first;
}
const me = async (token: string) => (await sabi.call("GET", "/v1/me", undefined, token)).body;

// Ada has a password account and has verified her e-mail. Mallory registered bola@example.com before Bola did.
await sabi.call("POST", "/v1/users", { email: "ada@example.com", name: "Ada", password: "ada's long passphrase" });
await sabi.db.executeRawUnsafe("UPDATE users SET email_verified = true WHERE email = 'ada@example.com'");
const mallory = { email: "bola@example.com", password: "mallory's passphrase" };
await sabi.call("POST", "/v1/users", { ...mallory, name: "Bola" });
const malloryToken = (await sabi.call("POST", "/v1/sessions", mallory)).body.accessToken;

const start = await sabi.call("GET", "/v1/oauth/kora");
console.log("start ->", start.status, start.headers.get("location")?.split("?")[0], (start.headers.get("set-cookie") ?? "").split("=")[0]);
for (const person of ["ada", "bola", "ada"]) {
  const reply = await signInWithKora(person);
  console.log(`${person} via Kora ->`, reply.status, await me(reply.body.accessToken));
}
console.log("Mallory's session ->", (await sabi.call("GET", "/v1/me", undefined, malloryToken)).status);
console.log("Mallory's password ->", (await sabi.call("POST", "/v1/sessions", mallory)).status);

const eve = await signInWithKora("eve");
console.log("eve (unverified ada@example.com) ->", eve.status, eve.body.error.code);
const forged = await signInWithKora("bola", { dropCookie: true });
console.log("callback without the login cookie ->", forged.status, forged.body.error.code);
const replayed = await signInWithKora("bola", { replay: true });
console.log("same callback twice ->", replayed.status, replayed.body.error.code);
await sabi.stop();

start -> 302 https://id.kora.example/authorize kora_login
ada via Kora -> 200 { id: '1', email: 'ada@example.com', roles: [ 'student' ] }
bola via Kora -> 200 { id: '2', email: 'bola@example.com', roles: [ 'student' ] }
ada via Kora -> 200 { id: '1', email: 'ada@example.com', roles: [ 'student' ] }
Mallory's session -> 401
Mallory's password -> 401
eve (unverified ada@example.com) -> 422 EMAIL_NOT_VERIFIED
callback without the login cookie -> 400 OAUTH_STATE_MISMATCH
same callback twice -> 400 OAUTH_STATE_MISMATCH

import { defineConfig } from "vitest/config";

export default defineConfig({ test: { include: ["tests/**/*.test.ts"], testTimeout: 20_000, hookTimeout: 30_000 } });

import { startVitest } from "vitest/node";

/** Runs test files with Vitest and prints one line per test. */
export async function runTests(...files: string[]): Promise<void> {
  const vitest = await startVitest("test", files, { watch: false, reporters: [] });
  for (const file of vitest.state.getTestModules()) {
    for (const error of file.errors()) console.log(`× ${file.relativeModuleId}: ${error.message}`);
    for (const test of file.children.allTests()) {
      const { state, errors = [] } = test.result();
      console.log(`${state === "passed" ? "✓" : "×"} ${test.fullName}`);
      for (const error of errors) console.log(`    ${error.message}`);
    }
  }
  await vitest.close();
}

import { startSabi } from "../sabi.js";

export type Sabi = Awaited<ReturnType<typeof startSabi>>;

export const passwordOf = (email: string) => `${email} long passphrase`;

export async function logIn(sabi: Sabi, email: string, password = passwordOf(email)) {
  const reply = await sabi.call("POST", "/v1/sessions", { email, password });
  return { status: reply.status, headers: reply.headers, access: reply.body.accessToken as string, refresh: reply.body.refreshToken as string };
}

export async function signUp(sabi: Sabi, email: string) {
  const joined = await sabi.call("POST", "/v1/users", { email, name: "Test", password: passwordOf(email), roles: ["admin"] });
  return { id: joined.body.id as string, roles: joined.body.roles as string[], ...(await logIn(sabi, email)) };
}

export const meStatus = async (sabi: Sabi, token: string) => (await sabi.call("GET", "/v1/me", undefined, token)).status;

/** Plays the browser through Kora: start, sign in at the fake Kora as `person`, return to the callback. */
export async function signInWithKora(sabi: Sabi, person: string, cookieOverride?: string) {
  const start = await sabi.call("GET", "/v1/oauth/kora");
  const cookie = cookieOverride ?? (start.headers.get("set-cookie") ?? "").split(";")[0]!;
  const authorize = new URL(start.headers.get("location")!);
  authorize.searchParams.set("as", person);
  const atKora = await fetch(authorize.toString().replace("https://id.kora.example", sabi.kora.base), { redirect: "manual" });
  const back = new URL(atKora.headers.get("location")!);
  return sabi.call("GET", back.pathname + back.search, undefined, undefined, { cookie });
}