create-wakii-stack 0.0.0-stage → 0.1.0

package/stack-template/services/auth-svc/src/db/schema.ts

@@ -0,0 +1,39 @@
+// schema.ts — drizzle definition của schema `auth` (epic VU-59 — auth-svc owns
+// schema riêng, spec §Kiến trúc). 2 bảng: users (seed từ contracts/auth/users.json
+// GIỮ UUID) + refresh_tokens (opaque rotation CAS — token-contract.md §2–3).
+// KHÔNG có canonical DDL trong contracts/db (schema này thuộc auth-svc, khác
+// tasks-schema.sql của node-svc) — cấu trúc định nghĩa tại đây + migration 0000.
+import { sql } from 'drizzle-orm';
+import { index, pgSchema, text, timestamp, uniqueIndex, uuid, varchar } from 'drizzle-orm/pg-core';
+
+export const authSchema = pgSchema('auth');
+
+export const users = authSchema.table('users', {
+  id: uuid('id').primaryKey(), // seeded users giữ nguyên UUID fixture users.json
+  // lowercase-normalized ở tầng route TRƯỚC lưu/lookup — unique chặn race 409
+  email: varchar('email', { length: 255 }).notNull(),
+  displayName: text('display_name').notNull(),
+  // roles: nguồn sự thật khi sign JWT — mirror token claims (token-contract §1)
+  roles: text('roles').array().notNull().default(sql`'{"user"}'::text[]`),
+  passwordHash: text('password_hash').notNull(), // argon2id — KHÔNG bao giờ ra response
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => [uniqueIndex('users_email_unique').on(t.email)]);
+
+export const refreshTokens = authSchema.table('refresh_tokens', {
+  id: uuid('id').primaryKey(),
+  userId: uuid('user_id').notNull().references(() => users.id, { onDelete: 'cascade' }),
+  // sha256 hex của raw token — lookup key + CAS target; DB KHÔNG có raw
+  tokenHash: varchar('token_hash', { length: 64 }).notNull(),
+  expiresAt: timestamp('expires_at', { withTimezone: true }).notNull(), // now + 7d
+  revokedAt: timestamp('revoked_at', { withTimezone: true }), // NULL = còn sống
+  replacedBy: uuid('replaced_by'), // rotation: trỏ id token mới (không FK — token mới có thể đã bị purge)
+  createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+}, (t) => [
+  uniqueIndex('refresh_tokens_token_hash_unique').on(t.tokenHash),
+  index('idx_refresh_tokens_user_id').on(t.userId),
+]);
+
+export type UserRow = typeof users.$inferSelect;
+export type NewUserRow = typeof users.$inferInsert;
+export type RefreshTokenRow = typeof refreshTokens.$inferSelect;
+export type NewRefreshTokenRow = typeof refreshTokens.$inferInsert;

package/stack-template/services/auth-svc/src/db/seed.ts

@@ -0,0 +1,60 @@
+// seed.ts — seed user fixture từ contracts/auth/users.json (spec §Kiến trúc):
+// GIỮ UUID + displayName + roles của fixture; password_hash = argon2id(AUTH_DEV_PASSWORD)
+// (decision #10 — default demo-password, cùng nguồn e2e + svc-activity);
+// idempotent ON CONFLICT (id) DO NOTHING — boot lại không đè user đã register
+// thêm thông tin. users.json KHÔNG chứa password (chỉ $comment mapping) — file
+// này đọc MỖI LẦN BOOT, hash runtime.
+import { readFileSync } from 'node:fs';
+import { hashPassword } from '../auth-crypto.js';
+import type { AuthRepo, NewUserInput } from '../repo.js';
+
+export interface FixtureUserEntry {
+  id: string;
+  email: string;
+  displayName: string;
+  roles: string[];
+}
+
+export interface SeedLog {
+  warn(msg: string, fields?: object): void;
+  info(msg: string, fields?: object): void;
+}
+
+export interface SeedResult {
+  inserted: number;
+  skipped: number;
+}
+
+export async function seedUsersFromFixture(
+  repo: AuthRepo,
+  fixturePath: string,
+  devPassword: string,
+  log: SeedLog,
+): Promise<SeedResult> {
+  const parsed: unknown = JSON.parse(readFileSync(fixturePath, 'utf8')); // thiếu/sai file = fail-fast boot
+  const users = (parsed as { users?: FixtureUserEntry[] }).users;
+  if (!Array.isArray(users) || users.length === 0) {
+    throw new Error(`users fixture "${fixturePath}" không có mảng users — kiểm contracts/auth/users.json`);
+  }
+
+  // 1 hash argon2id chung cho mọi fixture user (dev password chung — decision #10)
+  const passwordHash = await hashPassword(devPassword);
+  const result: SeedResult = { inserted: 0, skipped: 0 };
+  for (const entry of users) {
+    if (!entry.id || !entry.email || !entry.displayName) {
+      throw new Error(`users fixture entry thiếu id/email/displayName: ${JSON.stringify(entry)}`);
+    }
+    const input: NewUserInput = {
+      id: entry.id,
+      email: entry.email.trim().toLowerCase(),
+      displayName: entry.displayName,
+      roles: Array.isArray(entry.roles) && entry.roles.length > 0 ? entry.roles : ['user'],
+      passwordHash,
+    };
+    const inserted = await repo.insertUserIfAbsent(input);
+    if (inserted) result.inserted += 1;
+    else result.skipped += 1;
+  }
+  log.info('seed users fixture done', { inserted: result.inserted, skipped: result.skipped });
+  return result;
+}

package/stack-template/services/auth-svc/src/env.test.ts

@@ -0,0 +1,55 @@
+// env.test.ts — fail-fast env (conventions/06): thiếu bắt buộc = throw liệt kê
+// tên biến; ACCESS_TOKEN_TTL phải là duration hợp lệ (jsonwebtoken parse);
+// AUTH_DEV_PASSWORD default 'demo-password' (spec decision #10).
+import { describe, expect, it } from 'vitest';
+import { loadEnv } from './env.js';
+
+const BASE = {
+  DATABASE_URL: 'postgres://boilerplate:x@localhost:5432/boilerplate',
+  JWT_SECRET: 'test-secret-at-least-32-characters!!',
+  ACCESS_TOKEN_TTL: '30m',
+};
+
+describe('loadEnv (auth-svc)', () => {
+  it('thiếu env bắt buộc → throw liệt kê tên biến (conventions/06 rule 6)', () => {
+    expect(() => loadEnv({})).toThrow(/DATABASE_URL.*JWT_SECRET.*ACCESS_TOKEN_TTL/s);
+  });
+
+  it('đủ env → parse đúng; PORT default 8090 (conventions/05); LOG_LEVEL default info', () => {
+    const env = loadEnv({ ...BASE });
+    expect(env.port).toBe(8090);
+    expect(env.databaseUrl).toBe(BASE.DATABASE_URL);
+    expect(env.jwtSecret).toBe(BASE.JWT_SECRET);
+    expect(env.accessTokenTtl).toBe('30m');
+    expect(env.logLevel).toBe('info');
+  });
+
+  it('AUTH_DEV_PASSWORD default demo-password (decision #10); USERS_FIXTURE_PATH optional → null', () => {
+    const env = loadEnv({ ...BASE });
+    expect(env.authDevPassword).toBe('demo-password');
+    expect(env.usersFixturePath).toBeNull();
+    const withFixture = loadEnv({
+      ...BASE,
+      AUTH_DEV_PASSWORD: 'other-dev-pass',
+      USERS_FIXTURE_PATH: '/app/users.json',
+    });
+    expect(withFixture.authDevPassword).toBe('other-dev-pass');
+    expect(withFixture.usersFixturePath).toBe('/app/users.json');
+  });
+
+  it('ACCESS_TOKEN_TTL sai format → throw (không để jsonwebtoken nổ giữa request)', () => {
+    expect(() => loadEnv({ ...BASE, ACCESS_TOKEN_TTL: 'banana' })).toThrow(/ACCESS_TOKEN_TTL/);
+    expect(() => loadEnv({ ...BASE, ACCESS_TOKEN_TTL: '' })).toThrow(/ACCESS_TOKEN_TTL/);
+    // các unit hợp lệ (giây/phút/giờ/ngày — token-contract §1 dùng m)
+    expect(() => loadEnv({ ...BASE, ACCESS_TOKEN_TTL: '1800s' })).not.toThrow();
+    expect(() => loadEnv({ ...BASE, ACCESS_TOKEN_TTL: '1h' })).not.toThrow();
+  });
+
+  it('PORT invalid → throw nhắc conventions/05 (auth-svc = 8090)', () => {
+    expect(() => loadEnv({ ...BASE, PORT: 'nope' })).toThrow(/PORT/);
+  });
+
+  it('LOG_LEVEL ngoài 4 giá trị → throw', () => {
+    expect(() => loadEnv({ ...BASE, LOG_LEVEL: 'loud' })).toThrow(/LOG_LEVEL/);
+  });
+});

package/stack-template/services/auth-svc/src/env.ts

@@ -0,0 +1,57 @@
+// env.ts — parse + fail-fast env config (conventions/06: 100% env-var, không
+// fallback im lặng cho secret). AUTH_DEV_PASSWORD default 'demo-password' là
+// CHỦ ĐÍCH theo spec decision #10 (e2e + svc-activity + seed cùng một nguồn —
+// không phải secret, giá trị dev fixture được document trong .env.example).
+export interface Env {
+  port: number;
+  databaseUrl: string;
+  jwtSecret: string;
+  accessTokenTtl: string; // duration jsonwebtoken parse được ('30m' — token-contract §1)
+  authDevPassword: string; // chỉ seed dùng — login verify với hash đã lưu
+  usersFixturePath: string | null; // optional — thiếu = bỏ seed (register vẫn chạy)
+  corsDevOrigin: string; // rỗng = deny-by-default (conventions/07)
+  logLevel: 'debug' | 'info' | 'warn' | 'error';
+}
+
+const TTL_PATTERN = /^\d+(ms|s|m|h|d)$/;
+
+export function loadEnv(source: NodeJS.ProcessEnv = process.env): Env {
+  const missing: string[] = [];
+  const need = (name: string): string => {
+    const v = source[name];
+    if (!v || v.trim() === '') missing.push(name);
+    return v ?? '';
+  };
+
+  const portRaw = source.PORT;
+  const port = Number(portRaw || '8090');
+  const databaseUrl = need('DATABASE_URL');
+  const jwtSecret = need('JWT_SECRET');
+  const accessTokenTtl = need('ACCESS_TOKEN_TTL');
+  const logLevelRaw = source.LOG_LEVEL ?? 'info';
+
+  if (Number.isNaN(port) || port <= 0) {
+    throw new Error(`PORT invalid: "${portRaw}" (conventions/05: auth-svc = 8090)`);
+  }
+  if (accessTokenTtl && !TTL_PATTERN.test(accessTokenTtl.trim())) {
+    throw new Error(`ACCESS_TOKEN_TTL invalid: "${accessTokenTtl}" (dạng duration: 30m | 1800s | 1h — token-contract.md §1)`);
+  }
+  if (!['debug', 'info', 'warn', 'error'].includes(logLevelRaw)) {
+    throw new Error(`LOG_LEVEL invalid: "${logLevelRaw}" (debug|info|warn|error)`);
+  }
+  if (missing.length > 0) {
+    throw new Error(`Missing required env vars: ${missing.join(', ')} (platform/.env.example)`);
+  }
+
+  return {
+    port,
+    databaseUrl,
+    jwtSecret,
+    accessTokenTtl: accessTokenTtl.trim(),
+    // decision #10 — default demo-password (seeded fixture users)
+    authDevPassword: source.AUTH_DEV_PASSWORD?.trim() || 'demo-password',
+    usersFixturePath: source.USERS_FIXTURE_PATH?.trim() || null,
+    corsDevOrigin: source.CORS_DEV_ORIGIN ?? '',
+    logLevel: logLevelRaw as Env['logLevel'],
+  };
+}

package/stack-template/services/auth-svc/src/logger.ts

@@ -0,0 +1,31 @@
+// logger.ts — pino JSON shape chung (conventions/03): ts ISO-8601 UTC ms,
+// level, service, msg, requestId. Không console.log — mọi log qua đây.
+// REDACT MỞ RỘNG cho auth: password + refreshToken tuyệt đối không vào log
+// (spec slice SF-2: "KHÔNG log password/refresh").
+import pino from 'pino';
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+export function authSvcLogger(level: LogLevel = 'info'): pino.Logger {
+  return pino({
+    level,
+    base: { service: 'auth-svc' },
+    timestamp: () => `,"ts":"${new Date().toISOString()}"`,
+    // conventions/03 + token-contract: không log JWT/password/refresh token
+    redact: {
+      paths: [
+        'authorization',
+        'req.headers.authorization',
+        'password',
+        '*.password',
+        'token',
+        '*.token',
+        'refreshToken',
+        '*.refreshToken',
+        'refresh_token',
+        '*.refresh_token',
+      ],
+      censor: '[REDACTED]',
+    },
+  });
+}

package/stack-template/services/auth-svc/src/plugins/auth.ts

@@ -0,0 +1,70 @@
+// auth.ts — JWT verify cho endpoint CẦN Bearer (logout-all). auth-svc là
+// ISSUER của token, nhưng logout-all tự verify đúng luật lớp 2 (token-contract
+// §6): signature HS256 + expiry + iss LITERAL "auth-mock" — giá trị PINNED,
+// ⚠️ KHÔNG đổi thành "auth-svc" (3 service + 2 CI workflow hardcode chuỗi này;
+// đổi = follow-up riêng ngoài epic — token-contract.md §8).
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import jwt from 'jsonwebtoken';
+
+export const JWT_ISSUER = 'auth-mock';
+
+export interface JwtUser {
+  sub: string;
+  email: string;
+  roles: string[];
+}
+
+declare module 'fastify' {
+  interface FastifyRequest {
+    user?: JwtUser;
+  }
+}
+
+export function verifyToken(
+  authorization: string | undefined,
+  jwtSecret: string,
+): { ok: true; user: JwtUser } | { ok: false; reason: string } {
+  if (!authorization || !authorization.startsWith('Bearer ')) {
+    return { ok: false, reason: 'missing bearer token' };
+  }
+  const token = authorization.slice('Bearer '.length).trim();
+  try {
+    const payload = jwt.verify(token, jwtSecret, {
+      algorithms: ['HS256'],
+      issuer: JWT_ISSUER,
+    });
+    if (typeof payload === 'string' || typeof payload.sub !== 'string') {
+      return { ok: false, reason: 'invalid claims' };
+    }
+    return {
+      ok: true,
+      user: {
+        sub: payload.sub,
+        email: typeof payload.email === 'string' ? payload.email : '',
+        roles: Array.isArray(payload.roles) ? (payload.roles as string[]) : [],
+      },
+    };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : 'verify failed' };
+  }
+}
+
+/** preHandler cho logout-all — fail → 401 envelope UNAUTHORIZED (conventions/04). */
+export function requireBearer(jwtSecret: string) {
+  return (request: FastifyRequest, reply: FastifyReply, done: () => void): void => {
+    const result = verifyToken(request.headers.authorization, jwtSecret);
+    if (!result.ok) {
+      reply.status(401).send({
+        error: {
+          code: 'UNAUTHORIZED',
+          message: 'Missing or invalid JWT',
+          requestId: request.id,
+          details: null,
+        },
+      });
+      return;
+    }
+    request.user = result.user;
+    done();
+  };
+}

package/stack-template/services/auth-svc/src/repo.drizzle.integration.test.ts

@@ -0,0 +1,182 @@
+// repo.drizzle.integration.test.ts — rotation CAS + seed CHẠY TRÊN POSTGRES
+// THẬT (plan Task 2 Step 5: "integration vs postgres local"). Gate bằng env
+// AUTH_SVC_TEST_DATABASE_URL — thiếu = skip (unit suite vẫn xanh không DB).
+// Chạy: AUTH_SVC_TEST_DATABASE_URL="postgres://...@localhost:5432/boilerplate" pnpm test
+// (CI services-auth-svc.yml cấp qua service container postgres:16.)
+import { randomBytes, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { eq } from 'drizzle-orm';
+import { describe, expect, it, afterAll, beforeAll } from 'vitest';
+import { closeDb, createDb } from './db/client.js';
+import { runMigrations } from './db/migrate.js';
+import { migrationsFolder } from './app.js';
+import { seedUsersFromFixture } from './db/seed.js';
+import { DrizzleAuthRepo } from './repo.drizzle.js';
+import { hashPassword, sha256Hex } from './auth-crypto.js';
+import { refreshTokens, users } from './db/schema.js';
+
+const TEST_URL = process.env.AUTH_SVC_TEST_DATABASE_URL ?? '';
+const d = TEST_URL ? describe : describe.skip;
+
+const here = dirname(fileURLToPath(import.meta.url));
+const FIXTURE = resolve(here, '../../../contracts/auth/users.json');
+
+d('DrizzleAuthRepo — postgres thật (rotation CAS + seed idempotent)', () => {
+  const { pool, db } = createDb(TEST_URL);
+  const repo = new DrizzleAuthRepo(db);
+  let fixtureUsers: Array<{ id: string; email: string; displayName: string; roles: string[] }> = [];
+
+  beforeAll(async () => {
+    await runMigrations(db, migrationsFolder());
+    fixtureUsers = JSON.parse(readFileSync(FIXTURE, 'utf8')).users;
+  });
+
+  afterAll(async () => {
+    await closeDb({ pool, db });
+  });
+
+  // ---------------------------------------------------------- schema+seed
+
+  it('migration 0000: 2 bảng auth.users + auth.refresh_tokens tồn tại với đúng cột', async () => {
+    const cols = await db.execute(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (await import('drizzle-orm')).sql`select table_name, column_name from information_schema.columns where table_schema='auth' order by table_name, ordinal_position`,
+    );
+    const names = cols.rows.map((r) => `${(r as { table_name: string }).table_name}.${(r as { column_name: string }).column_name}`);
+    for (const must of [
+      'users.id', 'users.email', 'users.display_name', 'users.roles', 'users.password_hash', 'users.created_at',
+      'refresh_tokens.id', 'refresh_tokens.user_id', 'refresh_tokens.token_hash', 'refresh_tokens.expires_at',
+      'refresh_tokens.revoked_at', 'refresh_tokens.replaced_by', 'refresh_tokens.created_at',
+    ]) {
+      expect(names).toContain(must);
+    }
+  });
+
+  it('seed idempotent: re-seed KHÔNG đè/dupplicate — 5 user fixture ổn định, UUID giữ nguyên', async () => {
+    const log = { warn: () => {}, info: () => {}, error: () => {} } as never;
+    // Chạy 2 lần LIÊN TIẾP: lần 2 (re-seed) PHẢI insert 0 — ON CONFLICT (id)
+    // DO NOTHING. `first` = 0 hoặc 5 tuỳ DB đã seed sẵn hay chưa (fresh CI
+    // container → 5); không assert cứng `first` (review P1 VU-61 round 1).
+    const first = await seedUsersFromFixture(repo, FIXTURE, 'demo-password', log);
+    const second = await seedUsersFromFixture(repo, FIXTURE, 'demo-password', log);
+    expect(second.inserted).toBe(0);
+    expect([0, 5]).toContain(first.inserted);
+
+    const rows = await db.select().from(users).where(eq(users.id, '11111111-1111-4111-8111-111111111111'));
+    expect(rows).toHaveLength(1);
+    expect(rows[0].email).toBe('alice@demo.local');
+    expect(rows[0].roles).toEqual(['admin']);
+    expect(rows[0].displayName).toBe('Alice Demo');
+
+    const all = await repo.listUsers();
+    expect(all.filter((u) => fixtureUsers.some((f) => f.id === u.id))).toHaveLength(5);
+  });
+
+  it('seeded user login được bằng AUTH_DEV_PASSWORD (argon2id verify)', async () => {
+    const alice = await repo.getUserByEmail('alice@demo.local');
+    expect(alice).not.toBeNull();
+    expect(await verify(alice!.passwordHash, 'demo-password')).toBe(true);
+    expect(await verify(alice!.passwordHash, 'wrong')).toBe(false);
+  });
+
+  // ------------------------------------------------------------ users CRUD
+
+  it('createUser → thành công; email lowercase trùng → nổ 23505 (route map → 409; normalize là việc route)', async () => {
+    const id = randomUUID();
+    const hash = await hashPassword('super-secret-1');
+    const email = `u-${id}@example.com`; // route gửi lowercase-normalized — repo nhận như-given
+    await repo.createUser({ id, email, displayName: 'U', roles: ['user'], passwordHash: hash });
+    await expect(
+      repo.createUser({ id: randomUUID(), email, displayName: 'Dup', roles: ['user'], passwordHash: hash }),
+    ).rejects.toMatchObject({ code: '23505' });
+  });
+
+  it('insertUserIfAbsent: id đã có → false, KHÔNG đè (ON CONFLICT (id) DO NOTHING)', async () => {
+    const id = randomUUID();
+    const hash = await hashPassword('super-secret-1');
+    expect(await repo.insertUserIfAbsent({ id, email: `s-${id}@example.com`, displayName: 'S', roles: ['user'], passwordHash: hash })).toBe(true);
+    expect(await repo.insertUserIfAbsent({ id, email: `other-${id}@example.com`, displayName: 'Other', roles: ['user'], passwordHash: hash })).toBe(false);
+    expect((await repo.getUserById(id))!.email).toBe(`s-${id}@example.com`);
+  });
+
+  // --------------------------------------------------------- rotation CAS
+
+  it('rotation: old revoked + replaced_by + row mới trong CÙNG tx; token hết hạn KHÔNG thắng CAS (0-rows → reuse)', async () => {
+    const uid = randomUUID();
+    await repo.createUser({ id: uid, email: `rot-${uid}@example.com`, displayName: 'Rot', roles: ['user'], passwordHash: await hashPassword('x'.repeat(10)) });
+
+    const raw = randomBytes(32).toString('base64url');
+    const expired = { id: randomUUID(), userId: uid, tokenHash: sha256Hex(raw), expiresAt: new Date(Date.now() - 1000) };
+    await repo.insertRefreshToken(expired);
+
+    const next = { id: randomUUID(), tokenHash: sha256Hex(randomBytes(32).toString('base64url')), expiresAt: new Date(Date.now() + 7 * 24 * 3600 * 1000) };
+    const result = await repo.rotateRefreshToken(expired.tokenHash, next);
+    expect(result).toEqual({ status: 'reuse' }); // expires_at > now() enforce TTL — token-contract §3
+    // reuse → revoke-all (chỉ có 1 row expired — vẫn revoked_at NOT NULL)
+    const row = (await db.select().from(refreshTokens).where(eq(refreshTokens.id, expired.id)))[0];
+    expect(row.revokedAt).not.toBeNull();
+  });
+
+  it('REUSE trên postgres: repo trả reuse + TẤT CẢ token user revoked', async () => {
+    const uid = randomUUID();
+    await repo.createUser({ id: uid, email: `reuse-${uid}@example.com`, displayName: 'Reuse', roles: ['user'], passwordHash: await hashPassword('x'.repeat(10)) });
+
+    const raw1 = randomBytes(32).toString('base64url');
+    await repo.insertRefreshToken({ id: randomUUID(), userId: uid, tokenHash: sha256Hex(raw1), expiresAt: new Date(Date.now() + 3600_000) });
+    const next1 = { id: randomUUID(), tokenHash: sha256Hex(randomBytes(32).toString('base64url')), expiresAt: new Date(Date.now() + 7 * 24 * 3600 * 1000) };
+    expect(await repo.rotateRefreshToken(sha256Hex(raw1), next1)).toEqual({ status: 'ok', userId: uid });
+
+    // old1 reuse → reuse branch revoke-all (next1 cũng chết)
+    expect(await repo.rotateRefreshToken(sha256Hex(raw1), { id: randomUUID(), tokenHash: 'na', expiresAt: new Date() })).toEqual({ status: 'reuse' });
+    const rows = await db.select().from(refreshTokens).where(eq(refreshTokens.userId, uid));
+    expect(rows.length).toBe(2);
+    expect(rows.every((r) => r.revokedAt !== null)).toBe(true);
+  });
+
+  it('2 refresh ĐỒNG THỜI cùng old token: ĐÚNG 1 thắng CAS, 1 reuse — CAS atomic trên postgres', async () => {
+    const uid = randomUUID();
+    await repo.createUser({ id: uid, email: `race-${uid}@example.com`, displayName: 'Race', roles: ['user'], passwordHash: await hashPassword('x'.repeat(10)) });
+    const raw = randomBytes(32).toString('base64url');
+    await repo.insertRefreshToken({ id: randomUUID(), userId: uid, tokenHash: sha256Hex(raw), expiresAt: new Date(Date.now() + 3600_000) });
+
+    const mkNext = () => ({ id: randomUUID(), tokenHash: sha256Hex(randomBytes(32).toString('base64url')), expiresAt: new Date(Date.now() + 7 * 24 * 3600 * 1000) });
+    const [a, b] = await Promise.all([
+      repo.rotateRefreshToken(sha256Hex(raw), mkNext()),
+      repo.rotateRefreshToken(sha256Hex(raw), mkNext()),
+    ]);
+    const statuses = [a.status, b.status].sort();
+    expect(statuses).toEqual(['ok', 'reuse']);
+    // strict: user không còn token sống nào
+    const live = await db.select().from(refreshTokens).where(eq(refreshTokens.userId, uid));
+    expect(live.filter((r) => r.revokedAt === null)).toHaveLength(0);
+  });
+
+  it('token lạ (không row) → unknown, không đổi gì trong DB', async () => {
+    const before = await db.select().from(refreshTokens);
+    const result = await repo.rotateRefreshToken(sha256Hex(randomBytes(32).toString('base64url')), {
+      id: randomUUID(), tokenHash: 'x', expiresAt: new Date(),
+    });
+    expect(result).toEqual({ status: 'unknown' });
+    const after = await db.select().from(refreshTokens);
+    expect(after).toEqual(before); // 0 mutation
+  });
+
+  it('logout idempotent + logout-all revoke mọi token user', async () => {
+    const uid = randomUUID();
+    await repo.createUser({ id: uid, email: `lo-${uid}@example.com`, displayName: 'Lo', roles: ['user'], passwordHash: await hashPassword('x'.repeat(10)) });
+    const raws = [randomBytes(32).toString('base64url'), randomBytes(32).toString('base64url')];
+    for (const raw of raws) {
+      await repo.insertRefreshToken({ id: randomUUID(), userId: uid, tokenHash: sha256Hex(raw), expiresAt: new Date(Date.now() + 3600_000) });
+    }
+    await repo.revokeByTokenHash(sha256Hex(raws[0]));
+    await repo.revokeByTokenHash(sha256Hex(raws[0])); // lần 2 — no-op
+    await repo.revokeAllForUser(uid);
+    const rows = await db.select().from(refreshTokens).where(eq(refreshTokens.userId, uid));
+    expect(rows.every((r) => r.revokedAt !== null)).toBe(true);
+  });
+});
+
+// import muộn để gate skip không cần load — verify từ @node-rs/argon2
+import { verify } from '@node-rs/argon2';

package/stack-template/services/auth-svc/src/repo.drizzle.ts

@@ -0,0 +1,144 @@
+// repo.drizzle.ts — DrizzleAuthRepo: postgres thật. ĐIỂM NÓNG = rotateRefresh
+// Token — CAS atomic TRONG 1 TRANSACTION (token-contract.md §3 + review SF-1
+// c2bd165: INSERT token mới CÙNG tx với CAS UPDATE — trượt bước nào rollback
+// cả hai, không bao giờ có trạng thái "đã revoke cũ nhưng chưa có cặp mới").
+import { and, asc, eq, gt, isNull, sql } from 'drizzle-orm';
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { refreshTokens, users } from './db/schema.js';
+import type {
+  AuthRepo,
+  AuthUser,
+  AuthUserWithHash,
+  FixtureUser,
+  NewRefreshTokenInput,
+  NewUserInput,
+  RotateResult,
+} from './repo.js';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type Executor = NodePgDatabase | any; // NodePgDatabase | tx (cùng bề mặt query)
+
+export class DrizzleAuthRepo implements AuthRepo {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async ping(): Promise<void> {
+    await this.db.execute(sql`select 1`);
+  }
+
+  async listUsers(): Promise<FixtureUser[]> {
+    const rows = await this.db
+      .select({ id: users.id, email: users.email, roles: users.roles })
+      .from(users)
+      .orderBy(asc(users.createdAt), asc(users.id));
+    return rows;
+  }
+
+  async getUserByEmail(email: string): Promise<AuthUserWithHash | null> {
+    const rows = await this.db
+      .select()
+      .from(users)
+      .where(eq(users.email, email.trim().toLowerCase()))
+      .limit(1);
+    return rows[0] ? this.toUserWithHash(rows[0]) : null;
+  }
+
+  async getUserById(id: string): Promise<AuthUser | null> {
+    const rows = await this.db.select().from(users).where(eq(users.id, id)).limit(1);
+    const u = rows[0];
+    return u ? { id: u.id, email: u.email, displayName: u.displayName, roles: u.roles } : null;
+  }
+
+  async createUser(input: NewUserInput): Promise<AuthUser> {
+    // Email UNIQUE chặn race 2 register đồng thời. drizzle-orm ≥0.44 bọc PG
+    // error trong DrizzleQueryError (code nằm ở .cause.code) — normalize lại
+    // để giữ đúng contract AuthRepo: throw error có .code = '23505'.
+    try {
+      const rows = await this.db
+        .insert(users)
+        .values({ ...input, roles: [...input.roles] })
+        .returning({ id: users.id, email: users.email, displayName: users.displayName, roles: users.roles });
+      return rows[0];
+    } catch (err) {
+      const code = (err as { code?: string }).code ?? (err as { cause?: { code?: string } }).cause?.code;
+      if (code === '23505') {
+        const dup = new Error('duplicate key value violates unique constraint "users_email_unique"') as Error & { code: string };
+        dup.code = '23505';
+        throw dup;
+      }
+      throw err;
+    }
+  }
+
+  async insertUserIfAbsent(input: NewUserInput): Promise<boolean> {
+    const rows = await this.db
+      .insert(users)
+      .values({ ...input, roles: [...input.roles] })
+      .onConflictDoNothing({ target: users.id })
+      .returning({ id: users.id });
+    return rows.length > 0;
+  }
+
+  async insertRefreshToken(input: NewRefreshTokenInput): Promise<void> {
+    await this.db.insert(refreshTokens).values(input);
+  }
+
+  // Rotation CAS — chạy trong 1 tx: SELECT row cũ theo token_hash → CAS UPDATE
+  // (revoked_at IS NULL AND expires_at > now() — enforce TTL 7d) → thắng:
+  // INSERT token mới cùng tx; thua 0-rows: reuse-detect → revoke-all user rồi
+  // COMMIT (revoke-all phải được giữ lại — không rollback nhánh này).
+  async rotateRefreshToken(oldTokenHash: string, next: Omit<NewRefreshTokenInput, 'userId'>): Promise<RotateResult> {
+    return this.db.transaction(async (tx): Promise<RotateResult> => {
+      const found = await tx
+        .select({ id: refreshTokens.id, userId: refreshTokens.userId })
+        .from(refreshTokens)
+        .where(eq(refreshTokens.tokenHash, oldTokenHash))
+        .limit(1);
+      const old = found[0];
+      if (!old) return { status: 'unknown' }; // token lạ — không biết user, không revoke gì
+
+      const cas = await tx
+        .update(refreshTokens)
+        .set({ revokedAt: sql`now()`, replacedBy: next.id })
+        .where(
+          and(
+            eq(refreshTokens.id, old.id),
+            isNull(refreshTokens.revokedAt),
+            gt(refreshTokens.expiresAt, sql`now()`),
+          ),
+        )
+        .returning({ id: refreshTokens.id });
+
+      if (cas.length === 0) {
+        // reuse-detect strict — revoke TẤT CẢ refresh token của user (§3)
+        await tx
+          .update(refreshTokens)
+          .set({ revokedAt: sql`now()` })
+          .where(and(eq(refreshTokens.userId, old.userId), isNull(refreshTokens.revokedAt)));
+        return { status: 'reuse' };
+      }
+
+      await tx.insert(refreshTokens).values({ ...next, userId: old.userId }); // cùng tx với CAS — atomic
+      return { status: 'ok', userId: old.userId };
+    });
+  }
+
+  async revokeByTokenHash(tokenHash: string): Promise<void> {
+    // Idempotent: đã revoked/không tồn tại = 0 rows updated — logout vẫn 204
+    await this.db
+      .update(refreshTokens)
+      .set({ revokedAt: sql`now()` })
+      .where(and(eq(refreshTokens.tokenHash, tokenHash), isNull(refreshTokens.revokedAt)));
+  }
+
+  async revokeAllForUser(userId: string): Promise<void> {
+    await this.db
+      .update(refreshTokens)
+      .set({ revokedAt: sql`now()` })
+      .where(and(eq(refreshTokens.userId, userId), isNull(refreshTokens.revokedAt)));
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private toUserWithHash(row: any): AuthUserWithHash {
+    return { id: row.id, email: row.email, displayName: row.displayName, roles: row.roles, passwordHash: row.passwordHash };
+  }
+}