feat(core,api): Phase 1.9.3 인증 백엔드 구현 완료

packages/core:
- auth/services: UserAuthService, JwtSessionManagerImpl, WhitelistServiceImpl,
  AdminPinServiceImpl, TotpServiceImpl, hashPassword/verifyPassword 구현
- 의존성 추가: bcryptjs, jsonwebtoken, otplib

apps/api:
- POST /auth/login (whitelist 검사 → 비밀번호 검증 → TOTP 분기)
- POST /auth/totp/verify|enroll|confirm (TOTP 챌린지 완료 / 등록)
- POST /auth/pin/verify (관리자 PIN 검증)
- POST /auth/password/change (임시 비밀번호 강제 변경)
- POST /auth/password/recovery/issue|confirm (관리자 토큰 발급 / 복구)
- POST /auth/refresh (리프레시 토큰 회전)
- POST /auth/logout (세션 폐기)
- requireAuth 미들웨어 (Bearer JWT 검증)
- DB 마이그레이션: 001_auth_schema.sql (users, sessions, totp, whitelist, admin_pin, recovery_tokens)
- env: JWT_SECRET, JWT_REFRESH_SECRET, TOTP_ISSUER 추가
- CJS/ESM 혼용 해결: import type with { "resolution-mode": "import" }

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: SOIV

.env.example

@@ -10,3 +10,9 @@ DATABASE_URL=postgresql://fieldstack:fieldstack@localhost:5432/fieldstack
 # SQLite (경량 단독 인스턴스용)
 # DB_PROVIDER=sqlite
 # SQLITE_PATH=./data/database.db
+
+# ── Auth ─────────────────────────────────────────────────────
+# 프로덕션에서 반드시 32자 이상의 랜덤 문자열로 교체
+# JWT_SECRET=change-me-to-a-random-32-char-secret
+# JWT_REFRESH_SECRET=change-me-to-another-random-secret
+TOTP_ISSUER=Fieldstack

apps/api/src/app.ts

@@ -1,14 +1,36 @@
-import express from 'express';
+import path from 'node:path';
+
 import cors from 'cors';
+import express from 'express';
 
-import { healthRouter } from './routes/health';
+import type {
+  AdminPinServiceImpl,
+  DbProvider,
+  JwtSessionManagerImpl,
+  TotpServiceImpl,
+  UserAuthService,
+  WhitelistServiceImpl,
+} from '@fieldstack/core' with { "resolution-mode": "import" };
+
+import { validateEnv } from './config/env';
 import { errorHandler } from './middleware/error';
+import { createAuthRouter } from './routes/auth';
+import { healthRouter } from './routes/health';
 
-export function createApp() {
+// ── App 팩토리 ────────────────────────────────────────────────
+
+export interface AppServices {
+  jwtManager: JwtSessionManagerImpl;
+  whitelist: WhitelistServiceImpl;
+  adminPin: AdminPinServiceImpl;
+  totpService: TotpServiceImpl;
+  userAuth: UserAuthService;
+}
+
+export function createApp(services?: AppServices) {
   const app = express();
 
   // ── Middleware ────────────────────────────────────────────────
-  // 개발: 모든 origin 허용 / 프로덕션: 단일 포트 통합 서빙이므로 CORS 불필요
   if (process.env['NODE_ENV'] !== 'production') {
     app.use(cors());
   }
@@ -19,18 +41,57 @@ export function createApp() {
   // ── Core routes ───────────────────────────────────────────────
   app.use('/health', healthRouter);
 
-  // TODO(Phase 1.9.3): 인증 라우트 마운트 (POST /auth/login 등)
-  // TODO(Phase 1.9.2): 모듈 라우트 마운트 (DB 초기화 완료 후)
+  if (services) {
+    app.use('/auth', createAuthRouter(services));
+  }
 
   // ── Error handler (반드시 마지막) ─────────────────────────────
   app.use(errorHandler);
 
   return app;
 }
 
-// ── DB 초기화 (서버 시작 시 호출) ────────────────────────────
+// ── DB 초기화 ────────────────────────────────────────────────
 
-export async function initDb(): Promise<void> {
+export async function initDb(): Promise<DbProvider> {
   const { getDb } = await import('@fieldstack/core');
-  await getDb();
+  return getDb();
+}
+
+// ── 마이그레이션 실행 ─────────────────────────────────────────
+
+export async function runMigrations(db: DbProvider): Promise<void> {
+  const { FileMigrationRunner } = await import('@fieldstack/core');
+  const coreDir = path.join(__dirname, 'db', 'migrations', 'core');
+  const runner = new FileMigrationRunner(db, 'core', coreDir);
+  await runner.run();
+}
+
+// ── 서비스 초기화 ─────────────────────────────────────────────
+
+export async function initServices(db: DbProvider): Promise<AppServices> {
+  const env = validateEnv(process.env);
+
+  const {
+    JwtSessionManagerImpl,
+    WhitelistServiceImpl,
+    AdminPinServiceImpl,
+    TotpServiceImpl,
+    UserAuthService,
+  } = await import('@fieldstack/core');
+
+  const accessSecret = env.JWT_SECRET ?? 'dev-access-secret-change-in-production';
+  const refreshSecret = env.JWT_REFRESH_SECRET ?? 'dev-refresh-secret-change-in-production';
+
+  if (env.NODE_ENV === 'production' && !env.JWT_SECRET) {
+    throw new Error('[fieldstack][api] JWT_SECRET must be set in production');
+  }
+
+  const jwtManager = new JwtSessionManagerImpl(db, accessSecret, refreshSecret);
+  const whitelist = new WhitelistServiceImpl(db);
+  const adminPin = new AdminPinServiceImpl(db);
+  const totpService = new TotpServiceImpl(db, env.TOTP_ISSUER);
+  const userAuth = new UserAuthService(db, jwtManager, whitelist, totpService);
+
+  return { jwtManager, whitelist, adminPin, totpService, userAuth };
 }

apps/api/src/config/env.ts

@@ -8,6 +8,10 @@ const EnvSchema = z.object({
   DB_PROVIDER: z.enum(['postgres', 'sqlite']).default('postgres'),
   DATABASE_URL: z.string().url().optional(),
   SQLITE_PATH: z.string().optional(),
+  // Auth
+  JWT_SECRET: z.string().min(32).optional(),
+  JWT_REFRESH_SECRET: z.string().min(32).optional(),
+  TOTP_ISSUER: z.string().default('Fieldstack'),
 }).refine(
   (env) => env.DB_PROVIDER !== 'postgres' || Boolean(env.DATABASE_URL),
   { message: 'DATABASE_URL is required when DB_PROVIDER=postgres', path: ['DATABASE_URL'] },

apps/api/src/db/migrations/core/001_auth_schema.sql

@@ -0,0 +1,58 @@
+-- ── 001_auth_schema.sql ─────────────────────────────────────────
+-- Core 인증 스키마: users, sessions, totp, whitelist, admin_pin, recovery
+
+CREATE TABLE IF NOT EXISTS users (
+  id               {{UUID_PRIMARY_KEY}},
+  email            TEXT        NOT NULL UNIQUE,
+  password_hash    TEXT        NOT NULL,
+  is_temp_password BOOLEAN     NOT NULL DEFAULT {{BOOLEAN_FALSE}},
+  created_at       TIMESTAMPTZ NOT NULL DEFAULT {{NOW}},
+  updated_at       TIMESTAMPTZ NOT NULL DEFAULT {{NOW}}
+);
+
+CREATE TABLE IF NOT EXISTS sessions (
+  id                 UUID        PRIMARY KEY,
+  user_id            UUID        NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  refresh_token_hash TEXT        NOT NULL UNIQUE,
+  expires_at         TIMESTAMPTZ NOT NULL,
+  created_at         TIMESTAMPTZ NOT NULL DEFAULT {{NOW}}
+);
+
+CREATE TABLE IF NOT EXISTS totp_credentials (
+  user_id    UUID        PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+  secret     TEXT        NOT NULL,
+  verified   BOOLEAN     NOT NULL DEFAULT {{BOOLEAN_FALSE}},
+  created_at TIMESTAMPTZ NOT NULL DEFAULT {{NOW}}
+);
+
+CREATE TABLE IF NOT EXISTS totp_challenges (
+  id         UUID        PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id    UUID        NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  expires_at TIMESTAMPTZ NOT NULL,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT {{NOW}}
+);
+
+CREATE TABLE IF NOT EXISTS whitelist_rules (
+  id         {{UUID_PRIMARY_KEY}},
+  type       TEXT        NOT NULL CHECK (type IN ('email', 'domain')),
+  value      TEXT        NOT NULL,
+  enabled    BOOLEAN     NOT NULL DEFAULT {{BOOLEAN_TRUE}},
+  created_at TIMESTAMPTZ NOT NULL DEFAULT {{NOW}}
+);
+
+-- 관리자 PIN (단일 행 보장)
+CREATE TABLE IF NOT EXISTS admin_pin (
+  id         INT         PRIMARY KEY DEFAULT 1,
+  pin_hash   TEXT        NOT NULL,
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT {{NOW}},
+  CHECK      (id = 1)
+);
+
+CREATE TABLE IF NOT EXISTS password_recovery_tokens (
+  id         {{UUID_PRIMARY_KEY}},
+  user_id    UUID        NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  token_hash TEXT        NOT NULL UNIQUE,
+  expires_at TIMESTAMPTZ NOT NULL,
+  used       BOOLEAN     NOT NULL DEFAULT {{BOOLEAN_FALSE}},
+  created_at TIMESTAMPTZ NOT NULL DEFAULT {{NOW}}
+);

apps/api/src/index.ts

@@ -1,7 +1,7 @@
 import 'dotenv/config';
 
 import { validateEnv } from './config/env';
-import { createApp, initDb } from './app';
+import { createApp, initDb, initServices, runMigrations } from './app';
 
 // ── 환경변수 검증 (누락·오류 시 즉시 종료) ────────────────────
 const env = validateEnv(process.env);
@@ -17,13 +17,18 @@ if (env.INSTALL_MODE === 'bypass') {
   console.warn('[fieldstack][api] DEV INSTALL BYPASS ACTIVE');
 }
 
-// ── DB 초기화 → 서버 시작 ─────────────────────────────────────
+// ── DB 초기화 → 마이그레이션 → 서비스 초기화 → 서버 시작 ─────
 async function start() {
+  let services;
+
   if (env.DB_PROVIDER === 'postgres' && env.DATABASE_URL) {
-    await initDb();
+    const db = await initDb();
+    await runMigrations(db);
+    services = await initServices(db);
+    console.log('[fieldstack][api] DB initialized and migrations applied');
   }
 
-  const app = createApp();
+  const app = createApp(services);
   app.listen(env.PORT, () => {
     console.log(`[fieldstack][api] server listening on http://localhost:${env.PORT}`);
   });

apps/api/src/middleware/require-auth.ts

@@ -0,0 +1,30 @@
+import type { NextFunction, Request, Response } from 'express';
+
+import type { JwtSessionManagerImpl } from '@fieldstack/core' with { "resolution-mode": "import" };
+
+declare global {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace Express {
+    interface Request {
+      auth?: { userId: string; sessionId: string };
+    }
+  }
+}
+
+export function requireAuth(jwtManager: JwtSessionManagerImpl) {
+  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const header = req.headers.authorization;
+    if (!header?.startsWith('Bearer ')) {
+      res.status(401).json({ success: false, error: 'Unauthorized' });
+      return;
+    }
+
+    try {
+      const token = header.slice(7);
+      req.auth = await jwtManager.verifyAccessToken(token);
+      next();
+    } catch {
+      res.status(401).json({ success: false, error: 'Invalid or expired token' });
+    }
+  };
+}