Аутентификация: сессии, cookies и JWT

npm init -y
npm pkg set type=module
npm install express@5 express-session@1 argon2@0.45 jose@6
npm install -D typescript @types/node@24 @types/express@5 @types/express-session vitest supertest @types/supertest

{
  "compilerOptions": {
    "noEmit": true,
    "target": "esnext",
    "module": "nodenext",
    "rewriteRelativeImportExtensions": true,
    "erasableSyntaxOnly": true,
    "verbatimModuleSyntax": true,
    "strict": true,
    "skipLibCheck": true,
    "types": ["node"]
  },
  "include": ["src", "test"]
}

import * as argon2 from "argon2";
import { randomUUID } from "node:crypto";

export type Role = "admin" | "manager" | "analyst";

export type User = {
  id: string;
  email: string;
  role: Role;
  passwordHash: string;
};

// Учебное хранилище в памяти. В реальном проекте — таблица в базе данных.
const usersByEmail = new Map<string, User>();

export async function createUser(email: string, password: string, role: Role): Promise<User> {
  const user: User = {
    id: randomUUID(),
    email: email.toLowerCase(),
    role,
    // Argon2id с параметрами библиотеки по умолчанию; соль генерируется сама
    passwordHash: await argon2.hash(password),
  };
  usersByEmail.set(user.email, user);
  return user;
}

export function findUserById(id: string): User | undefined {
  for (const user of usersByEmail.values()) {
    if (user.id === id) return user;
  }
  return undefined;
}

// Хеш-заглушка: для несуществующего email проверка идёт так же долго,
// и время ответа не выдаёт, зарегистрирован ли адрес
const dummyHash = argon2.hash("timing-equalizer-not-a-real-password");

export async function verifyCredentials(email: string, password: string): Promise<User | null> {
  const user = usersByEmail.get(email.toLowerCase());
  const valid = await argon2.verify(user?.passwordHash ?? (await dummyHash), password);
  return user && valid ? user : null;
}

import express, { type NextFunction, type Request, type Response } from "express";
import session from "express-session";
import { findUserById, verifyCredentials, type User } from "./users.ts";

declare module "express-session" {
  interface SessionData {
    userId: string;
    authenticatedAt: number;
  }
}

declare global {
  namespace Express {
    interface Locals {
      user?: User;
    }
  }
}

export const SESSION_COOKIE = "__Host-sid";
const IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 минут без запросов
const ABSOLUTE_TIMEOUT_MS = 8 * 60 * 60 * 1000; // 8 часов с момента входа
const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);

// CSRF: изменяющие запросы принимаем только со своего сайта.
// Основной сигнал — Sec-Fetch-Site, запасной — Origin; без обоих — отказ.
function rejectCrossSite(appOrigin: string) {
  return (req: Request, res: Response, next: NextFunction) => {
    if (SAFE_METHODS.has(req.method)) return next();
    const site = req.get("Sec-Fetch-Site");
    const sameOrigin = site ? site === "same-origin" : req.get("Origin") === appOrigin;
    if (!sameOrigin) {
      res.status(403).json({ error: "cross_site_request" });
      return;
    }
    next();
  };
}

export function requireAuth(req: Request, res: Response, next: NextFunction) {
  const { userId, authenticatedAt } = req.session;
  const user = userId ? findUserById(userId) : undefined;
  const expired = !authenticatedAt || Date.now() - authenticatedAt > ABSOLUTE_TIMEOUT_MS;
  if (!user || expired) {
    req.session.destroy(() => res.status(401).json({ error: "unauthenticated" }));
    return;
  }
  res.locals.user = user;
  next();
}

export function createApp(options: { sessionSecret: string; appOrigin: string }) {
  if (options.sessionSecret.length < 32) throw new Error("SESSION_SECRET is too short");

  const app = express();
  app.set("trust proxy", 1); // HTTPS завершается на прокси (Nginx, балансировщик)
  app.use(express.json({ limit: "10kb" }));
  app.use(rejectCrossSite(options.appOrigin));
  app.use(
    session({
      name: SESSION_COOKIE,
      secret: options.sessionSecret,
      resave: false,
      saveUninitialized: false, // не создаём сессию до входа
      rolling: true, // продлеваем cookie при каждом ответе: тайм-аут бездействия
      cookie: {
        httpOnly: true,
        secure: true,
        sameSite: "lax",
        path: "/",
        maxAge: IDLE_TIMEOUT_MS,
      },
    }),
  );

  app.post("/login", async (req, res, next) => {
    const { email, password } = req.body ?? {};
    if (typeof email !== "string" || typeof password !== "string" || password.length > 256) {
      res.status(400).json({ error: "invalid_request" });
      return;
    }
    const user = await verifyCredentials(email, password);
    if (!user) {
      // Один и тот же ответ для «нет такого email» и «неверный пароль»
      res.status(401).json({ error: "invalid_credentials" });
      return;
    }
    // Новый ID сессии после входа — защита от фиксации сессии
    req.session.regenerate((err) => {
      if (err) return next(err);
      req.session.userId = user.id;
      req.session.authenticatedAt = Date.now();
      req.session.save((err) => (err ? next(err) : res.status(204).end()));
    });
  });

  app.get("/me", requireAuth, (req, res) => {
    const { id, email, role } = res.locals.user!;
    res.json({ id, email, role });
  });

  app.post("/logout", (req, res, next) => {
    // Сессия удаляется на сервере: украденная копия cookie тоже перестаёт работать
    req.session.destroy((err) => {
      if (err) return next(err);
      res.clearCookie(SESSION_COOKIE, { path: "/", httpOnly: true, secure: true, sameSite: "lax" });
      res.status(204).end();
    });
  });

  return app;
}

import { createApp } from "./app.ts";
import { createUser } from "./users.ts";

const sessionSecret = process.env.SESSION_SECRET;
if (!sessionSecret) throw new Error("SESSION_SECRET is not set");
const port = Number(process.env.PORT ?? 3000);

const app = createApp({
  sessionSecret,
  appOrigin: process.env.APP_ORIGIN ?? `http://localhost:${port}`,
});

if (process.env.NODE_ENV !== "production") {
  // Демо-пользователь только для локального запуска
  await createUser("admin@example.com", "correct horse battery staple", "admin");
}

app.listen(port, () => console.log(`http://localhost:${port}`));

npx tsc -p .
export SESSION_SECRET=$(node -e "console.log(require('node:crypto').randomBytes(32).toString('hex'))")
PORT=3917 node src/server.ts

$ curl -i -X POST http://127.0.0.1:3917/login \
    -H "Content-Type: application/json" -H "Origin: http://localhost:3917" \
    -H "X-Forwarded-Proto: https" \
    -d '{"email":"admin@example.com","password":"correct horse battery staple"}'
HTTP/1.1 204 No Content
Set-Cookie: __Host-sid=s%3AfuTZ…; Path=/; Expires=Sun, 11 Oct 2026 23:47:55 GMT; HttpOnly; Secure; SameSite=Lax

$ curl http://127.0.0.1:3917/me -H "Cookie: __Host-sid=s%3AfuTZ…"
{"id":"42c620b1-f267-4410-8b36-bf939acd4128","email":"admin@example.com","role":"admin"}

$ curl -i -X POST http://127.0.0.1:3917/logout -H "Cookie: __Host-sid=s%3AfuTZ…"
HTTP/1.1 403 Forbidden

import type { Express } from "express";
import request from "supertest";
import { SESSION_COOKIE } from "../src/app.ts";

// Так выглядит запрос со своего сайта, прошедший через HTTPS-прокси
export const SAME_ORIGIN = { "X-Forwarded-Proto": "https", "Sec-Fetch-Site": "same-origin" };

export function sessionCookie(res: request.Response): string | undefined {
  const cookies = res.get("Set-Cookie") ?? [];
  return cookies.find((c) => c.startsWith(`${SESSION_COOKIE}=`))?.split(";")[0];
}

export async function login(app: Express, email: string, password: string) {
  const res = await request(app).post("/login").set(SAME_ORIGIN).send({ email, password });
  return { res, cookie: sessionCookie(res) };
}

import { randomBytes } from "node:crypto";
import request from "supertest";
import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
import { createApp } from "../src/app.ts";
import { createUser } from "../src/users.ts";
import { login, SAME_ORIGIN, sessionCookie } from "./helpers.ts";

const app = createApp({
  sessionSecret: randomBytes(32).toString("hex"),
  appOrigin: "https://app.example.com",
});
const EMAIL = "anna@example.com";
const PASSWORD = "long-and-unique-passphrase";

beforeAll(async () => {
  await createUser(EMAIL, PASSWORD, "manager");
});

afterEach(() => {
  vi.useRealTimers();
});

describe("вход по сессии", () => {
  it("неверный пароль: 401 и никакой cookie", async () => {
    const { res, cookie } = await login(app, EMAIL, "wrong-password");
    expect(res.status).toBe(401);
    expect(res.body).toEqual({ error: "invalid_credentials" });
    expect(cookie).toBeUndefined();
  });

  it("неизвестный email: тот же ответ, что и при неверном пароле", async () => {
    const { res } = await login(app, "nobody@example.com", PASSWORD);
    expect(res.status).toBe(401);
    expect(res.body).toEqual({ error: "invalid_credentials" });
  });

  it("без cookie защищённый маршрут отвечает 401", async () => {
    const res = await request(app).get("/me").set(SAME_ORIGIN);
    expect(res.status).toBe(401);
  });

  it("успешный вход ставит защищённую cookie и открывает /me", async () => {
    const { res, cookie } = await login(app, EMAIL, PASSWORD);
    expect(res.status).toBe(204);
    const setCookie = res.get("Set-Cookie")!.join("; ");
    expect(setCookie).toMatch(/^__Host-sid=/);
    expect(setCookie).toMatch(/; Path=\//);
    expect(setCookie).toMatch(/; HttpOnly/);
    expect(setCookie).toMatch(/; Secure/);
    expect(setCookie).toMatch(/; SameSite=Lax/);

    const me = await request(app).get("/me").set(SAME_ORIGIN).set("Cookie", cookie!);
    expect(me.status).toBe(200);
    expect(me.body).toMatchObject({ email: EMAIL, role: "manager" });
  });

  it("вход выдаёт новый ID сессии, старый перестаёт работать", async () => {
    const first = await login(app, EMAIL, PASSWORD);
    const res = await request(app)
      .post("/login").set(SAME_ORIGIN).set("Cookie", first.cookie!)
      .send({ email: EMAIL, password: PASSWORD });
    const second = sessionCookie(res);
    expect(second).toBeDefined();
    expect(second).not.toBe(first.cookie);

    const old = await request(app).get("/me").set(SAME_ORIGIN).set("Cookie", first.cookie!);
    expect(old.status).toBe(401);
  });

  it("после выхода старая cookie больше не работает", async () => {
    const { cookie } = await login(app, EMAIL, PASSWORD);
    const out = await request(app).post("/logout").set(SAME_ORIGIN).set("Cookie", cookie!);
    expect(out.status).toBe(204);

    const me = await request(app).get("/me").set(SAME_ORIGIN).set("Cookie", cookie!);
    expect(me.status).toBe(401);
  });

  it("POST с чужого сайта отклоняется, сессия остаётся", async () => {
    const { cookie } = await login(app, EMAIL, PASSWORD);
    const out = await request(app)
      .post("/logout")
      .set({ ...SAME_ORIGIN, "Sec-Fetch-Site": "cross-site" })
      .set("Cookie", cookie!);
    expect(out.status).toBe(403);

    const me = await request(app).get("/me").set(SAME_ORIGIN).set("Cookie", cookie!);
    expect(me.status).toBe(200);
  });

  it("сессия заканчивается через 8 часов даже при активности", async () => {
    vi.useFakeTimers({ toFake: ["Date"] });
    const start = Date.now();
    const { cookie } = await login(app, EMAIL, PASSWORD);
    const step = 20 * 60 * 1000; // запрос каждые 20 минут — idle-тайм-аут не срабатывает

    for (let i = 1; i <= 24; i++) {
      vi.setSystemTime(start + i * step);
      const me = await request(app).get("/me").set(SAME_ORIGIN).set("Cookie", cookie!);
      expect(me.status).toBe(200);
    }
    vi.setSystemTime(start + 25 * step); // 8 ч 20 мин после входа
    const late = await request(app).get("/me").set(SAME_ORIGIN).set("Cookie", cookie!);
    expect(late.status).toBe(401);
  });
});

import type { NextFunction, Request, Response } from "express";
import { errors, jwtVerify, SignJWT, type JWTPayload } from "jose";
import { randomUUID } from "node:crypto";

declare global {
  namespace Express {
    interface Locals {
      tokenSubject?: string;
    }
  }
}

export const ALG = "HS256";
export const ISSUER = "https://api.example.com";
export const AUDIENCE = "https://api.example.com/v1";
export const TYP = "app-access+jwt"; // явный тип токена (RFC 8725, §3.11)

export function loadJwtSecret(hex: string | undefined): Uint8Array {
  // HS256: ключ не короче 256 бит из криптостойкого генератора, а не пароль
  if (!hex || !/^(?:[0-9a-f]{2}){32,}$/i.test(hex)) throw new Error("JWT_SECRET must be at least 32 random bytes in hex");
  return Buffer.from(hex, "hex");
}

export async function issueAccessToken(userId: string, secret: Uint8Array): Promise<string> {
  return new SignJWT()
    .setProtectedHeader({ alg: ALG, typ: TYP })
    .setSubject(userId)
    .setIssuer(ISSUER)
    .setAudience(AUDIENCE)
    .setIssuedAt()
    .setExpirationTime("10m") // короткая жизнь: отозвать JWT до exp сложно
    .setJti(randomUUID())
    .sign(secret);
}

export async function verifyAccessToken(token: string, secret: Uint8Array): Promise<JWTPayload> {
  const { payload } = await jwtVerify(token, secret, {
    algorithms: [ALG], // только ожидаемый алгоритм
    issuer: ISSUER,
    audience: AUDIENCE,
    typ: TYP,
    requiredClaims: ["sub", "exp", "jti"],
  });
  return payload;
}

export function requireBearer(secret: Uint8Array) {
  return async (req: Request, res: Response, next: NextFunction) => {
    const match = /^Bearer (\S+)$/i.exec(req.get("Authorization") ?? "");
    if (!match) {
      res.set("WWW-Authenticate", "Bearer").status(401).json({ error: "unauthenticated" });
      return;
    }
    try {
      const payload = await verifyAccessToken(match[1], secret);
      res.locals.tokenSubject = payload.sub;
      next();
    } catch (err) {
      if (!(err instanceof errors.JOSEError)) throw err;
      res.set("WWW-Authenticate", 'Bearer error="invalid_token"').status(401).json({ error: "invalid_token" });
    }
  };
}

import express from "express";
import { errors, SignJWT, UnsecuredJWT } from "jose";
import { randomBytes } from "node:crypto";
import request from "supertest";
import { describe, expect, it } from "vitest";
import {
  ALG, AUDIENCE, ISSUER, TYP,
  issueAccessToken, loadJwtSecret, requireBearer, verifyAccessToken,
} from "../src/tokens.ts";

const secret = loadJwtSecret(randomBytes(32).toString("hex"));

const app = express();
app.get("/api/me", requireBearer(secret), (req, res) => {
  res.json({ sub: res.locals.tokenSubject });
});

describe("JWT access-токен", () => {
  it("валидный токен открывает маршрут", async () => {
    const token = await issueAccessToken("user-42", secret);
    const res = await request(app).get("/api/me").set("Authorization", `Bearer ${token}`);
    expect(res.status).toBe(200);
    expect(res.body).toEqual({ sub: "user-42" });
  });

  it("без токена: 401 и заголовок WWW-Authenticate", async () => {
    const res = await request(app).get("/api/me");
    expect(res.status).toBe(401);
    expect(res.get("WWW-Authenticate")).toBe("Bearer");
  });

  it("подменённый payload не проходит проверку подписи", async () => {
    const [header, , signature] = (await issueAccessToken("user-42", secret)).split(".");
    const payload = Buffer.from(JSON.stringify({ sub: "admin" })).toString("base64url");
    const forged = `${header}.${payload}.${signature}`;

    await expect(verifyAccessToken(forged, secret)).rejects.toThrow(errors.JWSSignatureVerificationFailed);
    const res = await request(app).get("/api/me").set("Authorization", `Bearer ${forged}`);
    expect(res.status).toBe(401);
    expect(res.get("WWW-Authenticate")).toBe('Bearer error="invalid_token"');
  });

  it('токен с alg "none" отклоняется', async () => {
    const unsigned = new UnsecuredJWT({})
      .setSubject("admin").setIssuer(ISSUER).setAudience(AUDIENCE).setExpirationTime("10m").encode();
    await expect(verifyAccessToken(unsigned, secret)).rejects.toThrow(errors.JOSEError);
  });

  it("просроченный токен отклоняется", async () => {
    const hourAgo = Math.floor(Date.now() / 1000) - 3600;
    const expired = await new SignJWT()
      .setProtectedHeader({ alg: ALG, typ: TYP })
      .setSubject("user-42").setIssuer(ISSUER).setAudience(AUDIENCE).setJti("t-1")
      .setIssuedAt(hourAgo).setExpirationTime(hourAgo + 600)
      .sign(secret);
    await expect(verifyAccessToken(expired, secret)).rejects.toThrow(errors.JWTExpired);
  });

  it("токен для другого сервиса (aud) отклоняется", async () => {
    const foreign = await new SignJWT()
      .setProtectedHeader({ alg: ALG, typ: TYP })
      .setSubject("user-42").setIssuer(ISSUER).setAudience("https://billing.example.com").setJti("t-2")
      .setIssuedAt().setExpirationTime("10m")
      .sign(secret);
    await expect(verifyAccessToken(foreign, secret)).rejects.toThrow(errors.JWTClaimValidationFailed);
  });
});

$ npx vitest run test/
 RUN  v5.0.3 ~/auth-demo

 Test Files  2 passed (2)
      Tests  14 passed (14)