@gaonjs/web 0.1.2 → 0.2.0

package/dist/app.d.ts

@@ -0,0 +1,47 @@
+import { type FastifyInstance, type FastifyServerOptions } from 'fastify';
+import { type FastifyCorsOptions } from '@fastify/cors';
+import type { RouteDef } from './routes.js';
+import { type DispatchOptions } from './dispatch.js';
+import { type AppSessionOptions } from './session.js';
+import { type AuthOptions, type JwtAuthOptions } from './auth.js';
+/** 한 앱 정의 — 프리픽스(생략 시 관례)·라우트·컨트롤러 맵. */
+export interface AppSpec {
+    readonly name: string;
+    /** 생략 시 관례: web→'/', 그 외→'/<name>'(§3.3). */
+    readonly prefix?: string;
+    readonly routes: RouteDef;
+    readonly controllers: Record<string, object>;
+    /** 세션 배터리 설정(§7). 생략 시 세션 없음(JWT/API 앱 등). */
+    readonly session?: AppSessionOptions;
+    /**
+     * 인증(§7). 세션 앱은 AuthOptions(기본), API 앱은 JwtAuthOptions(strategy:'jwt').
+     * 세션 앱은 requireAuth 실패 시 로그인 페이지로, JWT 앱은 401 로 응답한다.
+     */
+    readonly auth?: AuthOptions | JwtAuthOptions;
+    /** 요청별 컨텍스트 확장(추가 훅). */
+    readonly dispatch?: DispatchOptions;
+}
+export interface SecurityOptions {
+    /** CORS 설정. 기본은 same-origin 만 허용(origin:false). false 로 완전 비활성. */
+    readonly cors?: FastifyCorsOptions | false;
+    /** rate limit. 기본 100 req/분/IP. false 로 비활성. */
+    readonly rateLimit?: {
+        max?: number;
+        timeWindow?: string | number;
+    } | false;
+}
+export interface CreateAppOptions {
+    readonly apps: readonly AppSpec[];
+    /** Inertia 에셋 버전(전 앱 공통). 클라이언트 불일치 시 풀 리로드. */
+    readonly version?: string;
+    /** 서명 쿠키·CSRF 용 비밀. 생략 시 env GAON_COOKIE_SECRET. */
+    readonly cookieSecret?: string;
+    readonly security?: SecurityOptions;
+    readonly fastify?: FastifyServerOptions;
+}
+/**
+ * 앱 스펙들로 Fastify 인스턴스를 만든다. 쿠키·CORS·rate limit(보안 기본값)을
+ * 켜고, 각 앱의 라우트를 프리픽스 아래 등록한다. listen 은 호출자가 한다.
+ */
+export declare function createApp(opts: CreateAppOptions): Promise<FastifyInstance>;
+export type { RouteDef };

package/dist/app.js

@@ -0,0 +1,63 @@
+// @gaonjs/web · Fastify 앱 팩토리 + 보안 기본값 (§2.5.1)
+//
+// 보안(CORS·rate limit·CSRF)은 코어에 내장하고 **기본으로 켠다** — 별도
+// 패키지를 설치해야 방어가 생기는 방식은 명시적으로 기각했다(§2.5.1). 끄는
+// 것은 명시적 설정으로만 한다.
+//
+// CSRF·세션은 세션 배터리 스텝에서 이 팩토리에 결합된다. 여기서는 HTTP
+// 실행 레이어의 뼈대(쿠키·CORS·rate limit·앱별 라우트 등록)를 놓는다.
+import Fastify from 'fastify';
+import cookie from '@fastify/cookie';
+import cors from '@fastify/cors';
+import rateLimit from '@fastify/rate-limit';
+import { prefixFor, registerApp } from './dispatch.js';
+import { registerSession } from './session.js';
+import { jwtAuthAugment, sessionAuthAugment } from './auth.js';
+/**
+ * 앱 스펙들로 Fastify 인스턴스를 만든다. 쿠키·CORS·rate limit(보안 기본값)을
+ * 켜고, 각 앱의 라우트를 프리픽스 아래 등록한다. listen 은 호출자가 한다.
+ */
+export async function createApp(opts) {
+    const app = Fastify(opts.fastify);
+    const security = opts.security ?? {};
+    // 쿠키 — 세션·CSRF·서명 쿠키의 토대. secret 은 서명 쿠키에만 필요.
+    await app.register(cookie, { secret: opts.cookieSecret ?? process.env.GAON_COOKIE_SECRET });
+    // CORS — 기본 same-origin(origin:false). 크로스 오리진은 명시 설정으로만.
+    if (security.cors !== false) {
+        await app.register(cors, security.cors ?? { origin: false });
+    }
+    // rate limit — 기본 100 req/분/IP.
+    if (security.rateLimit !== false) {
+        const rl = security.rateLimit ?? {};
+        await app.register(rateLimit, { max: rl.max ?? 100, timeWindow: rl.timeWindow ?? '1 minute' });
+    }
+    // 앱마다 캡슐화 스코프에 등록한다 — 세션·CSRF·라우트가 그 앱 프리픽스에
+    // 갇혀 앱별 완전 분리가 성립한다(질문 13). 프리픽스는 스코프가 건다.
+    for (const spec of opts.apps) {
+        const prefix = spec.prefix ?? prefixFor(spec.name);
+        await app.register(async (scope) => {
+            if (spec.session)
+                await registerSession(scope, spec.name, prefix, spec.session);
+            registerApp(scope, { name: spec.name, routes: spec.routes, controllers: spec.controllers }, dispatchOptionsFor(spec, opts.version));
+        }, { prefix });
+    }
+    return app;
+}
+/** 앱의 인증·추가 훅을 디스패치 옵션으로 합성한다. */
+function dispatchOptionsFor(spec, version) {
+    const auth = spec.auth;
+    // JWT 앱은 401(리다이렉트 없음), 세션 앱은 로그인 페이지로.
+    const isJwt = auth != null && 'strategy' in auth && auth.strategy === 'jwt';
+    const authAugment = auth ? (isJwt ? jwtAuthAugment(auth) : sessionAuthAugment(auth)) : undefined;
+    const loginRedirect = auth && !isJwt ? auth.loginRedirect ?? '/login' : undefined;
+    const extra = spec.dispatch?.augment;
+    const augment = authAugment || extra
+        ? async (ctx, request, reply) => {
+            if (authAugment)
+                await authAugment(ctx, request, reply);
+            if (extra)
+                await extra(ctx, request, reply);
+        }
+        : undefined;
+    return { version, loginRedirect, ...spec.dispatch, augment };
+}

package/dist/auth.d.ts

@@ -0,0 +1,38 @@
+import type { FastifyReply, FastifyRequest } from 'fastify';
+import type { ControllerContext, GaonCurrentUser } from './controller.js';
+/** requireAuth 가 던지는 비로그인 신호. 클래스 대신 마커 프로퍼티를 쓴다. */
+export declare function unauthorizedError(): Error;
+/** 던져진 값이 비로그인 신호인지 판정한다(디스패처가 응답 분기에 사용). */
+export declare function isUnauthorized(e: unknown): boolean;
+export interface AuthOptions {
+    /**
+     * session.userId → 사용자 로드. 앱이 도메인 모델로 구현한다(예:
+     * (id) => User.query().where('id','=',BigInt(id)).first()). falsy 반환은
+     * 비로그인 취급. web 이 data 를 직접 import 하지 않게 하는 이음새다.
+     */
+    loadUser(id: unknown): Promise<GaonCurrentUser | null | undefined> | GaonCurrentUser | null | undefined;
+    /** requireAuth 실패 시 리다이렉트 경로(폼/Inertia). 기본 '/login'. */
+    loginRedirect?: string;
+}
+/**
+ * 컨텍스트에 currentUser 를 채우는 augment 를 만든다. 세션의 userId 로
+ * 사용자를 로드해 ctx.currentUser·ctx.auth.user 에 심는다.
+ */
+export declare function sessionAuthAugment(opts: AuthOptions): (ctx: ControllerContext, request: FastifyRequest, _reply: FastifyReply) => Promise<void>;
+export interface JwtAuthOptions {
+    /** JWT 앱임을 표시하는 판별자. */
+    strategy: 'jwt';
+    /** HS256 서명 secret. 앱마다 달라야 토큰이 앱을 넘지 못한다(질문 13). */
+    secret: string;
+    /** 토큰 sub(사용자 id) → 사용자 로드. */
+    loadUser(id: unknown): Promise<GaonCurrentUser | null | undefined> | GaonCurrentUser | null | undefined;
+    /** 액세스 토큰 수명. 기본 '15m'. */
+    accessTtl?: string;
+    /** 리프레시 토큰 수명. 기본 '7d'. */
+    refreshTtl?: string;
+}
+/**
+ * JWT 앱용 augment. Bearer 액세스 토큰으로 currentUser 를 채우고, this.jwt 로
+ * 토큰 발급/재발급 API 를 얹는다(로그인·리프레시 컨트롤러가 사용).
+ */
+export declare function jwtAuthAugment(opts: JwtAuthOptions): (ctx: ControllerContext, request: FastifyRequest, _reply: FastifyReply) => Promise<void>;

package/dist/auth.js

@@ -0,0 +1,78 @@
+// @gaonjs/web · 인증 코어 (currentUser · requireAuth · 세션 로그인)
+//
+// 세션 쿠키가 기본 인증이다(§7). 로그인은 세션에 사용자 id 를 심고
+// (this.auth.login), 요청마다 그 id 로 사용자를 로드해 this.currentUser 에
+// 채운다. 보호 라우트는 this.requireAuth() 가드로 지킨다 — 비로그인이면
+// 예외를 던져 디스패처가 로그인 페이지로 보내거나(폼/Inertia) 401(API)로 답한다.
+//
+// web 은 도메인(모델·DB)을 모른다 — 사용자 로드는 앱이 loadUser 로 주입한다
+// (의존 방향 §3.2 보호: web→data 직접 의존 없음).
+import { signToken, verifyToken } from './jwt.js';
+const UNAUTHORIZED = Symbol.for('gaon.web.unauthorized');
+/** requireAuth 가 던지는 비로그인 신호. 클래스 대신 마커 프로퍼티를 쓴다. */
+export function unauthorizedError() {
+    const e = new Error('Unauthorized');
+    e[UNAUTHORIZED] = true;
+    return e;
+}
+/** 던져진 값이 비로그인 신호인지 판정한다(디스패처가 응답 분기에 사용). */
+export function isUnauthorized(e) {
+    return typeof e === 'object' && e !== null && e[UNAUTHORIZED] === true;
+}
+/**
+ * 컨텍스트에 currentUser 를 채우는 augment 를 만든다. 세션의 userId 로
+ * 사용자를 로드해 ctx.currentUser·ctx.auth.user 에 심는다.
+ */
+export function sessionAuthAugment(opts) {
+    return async (ctx, request, _reply) => {
+        const sess = request.session;
+        const uid = sess?.userId;
+        if (uid == null)
+            return;
+        const user = (await opts.loadUser(uid)) ?? null;
+        ctx.currentUser = user;
+        ctx.auth.user = user;
+    };
+}
+/** Authorization: Bearer <token> 에서 토큰만 뽑는다. */
+function bearer(request) {
+    const h = request.headers.authorization;
+    if (typeof h === 'string' && h.startsWith('Bearer '))
+        return h.slice(7).trim();
+}
+/**
+ * JWT 앱용 augment. Bearer 액세스 토큰으로 currentUser 를 채우고, this.jwt 로
+ * 토큰 발급/재발급 API 를 얹는다(로그인·리프레시 컨트롤러가 사용).
+ */
+export function jwtAuthAugment(opts) {
+    const accessTtl = opts.accessTtl ?? '15m';
+    const refreshTtl = opts.refreshTtl ?? '7d';
+    const api = {
+        async issue(user) {
+            const sub = String(user.id);
+            return {
+                accessToken: await signToken(opts.secret, sub, 'access', accessTtl),
+                refreshToken: await signToken(opts.secret, sub, 'refresh', refreshTtl),
+            };
+        },
+        async refresh(refreshToken) {
+            const payload = await verifyToken(opts.secret, refreshToken);
+            if (!payload || payload.typ !== 'refresh' || typeof payload.sub !== 'string')
+                return null;
+            return { accessToken: await signToken(opts.secret, payload.sub, 'access', accessTtl) };
+        },
+    };
+    return async (ctx, request, _reply) => {
+        ;
+        ctx.jwt = api;
+        const token = bearer(request);
+        if (!token)
+            return;
+        const payload = await verifyToken(opts.secret, token);
+        if (!payload || payload.typ !== 'access' || typeof payload.sub !== 'string')
+            return;
+        const user = (await opts.loadUser(payload.sub)) ?? null;
+        ctx.currentUser = user;
+        ctx.auth.user = user;
+    };
+}

package/dist/controller.d.ts

@@ -0,0 +1,103 @@
+import type { FastifyReply, FastifyRequest } from 'fastify';
+/** 렌더 결과 — 페이지 이름 + props. 타입 브리지 입력(§6.2). */
+export interface Rendered<P> {
+    readonly page: string;
+    readonly props: P;
+}
+/**
+ * 리다이렉트 결과. Rendered<P>(page·props)와 구조가 겹치지 않아야 한다 —
+ * 겹치면 타입 브리지 PropsOf 가 리다이렉트를 렌더로 오인한다. 디스패처는
+ * `'redirect' in result` 로 분기한다.
+ */
+export interface Redirect {
+    readonly redirect: string;
+}
+/** JSON 응답 결과 — API/JWT 앱이 Inertia 대신 순수 데이터를 반환할 때. */
+export interface JsonResult {
+    readonly json: unknown;
+    readonly status?: number;
+}
+export type ActionResult<P = unknown> = Rendered<P> | Redirect | JsonResult | void;
+/**
+ * 현재 로그인 사용자의 모양. 앱이 declaration merging 으로 자기 User 필드를
+ * 얹는다(GaonRouteMap·GaonTables 와 동일 관례) — `gaon g auth` 스캐폴드가
+ * 이 병합을 생성한다. 빈 인터페이스라 실제 타입 있는 레코드(RowOf 등)를
+ * loadUser 반환으로 그대로 받을 수 있고, 병합 후 this.currentUser 필드에
+ * 타입 접근이 열린다.
+ */
+export interface GaonCurrentUser {
+}
+/** this.auth — 현재 사용자와 로그인/로그아웃(세션 조작). */
+export interface AuthApi {
+    readonly user: GaonCurrentUser | null;
+    /** 세션에 사용자 id 를 심어 로그인 상태로 만든다. */
+    login(user: {
+        id: unknown;
+    }): void;
+    /** 세션에서 사용자를 지운다. */
+    logout(): void;
+}
+export interface JwtTokens {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+}
+/** this.jwt — JWT 앱(API)에서 토큰을 발급·재발급한다. 세션 앱에는 없다. */
+export interface JwtApi {
+    /** 로그인 성공 시 액세스+리프레시 토큰을 발급한다(응답 본문으로 반환). */
+    issue(user: {
+        id: unknown;
+    }): Promise<JwtTokens>;
+    /** 리프레시 토큰으로 새 액세스 토큰을 발급한다. 무효면 null. */
+    refresh(refreshToken: string): Promise<{
+        accessToken: string;
+    } | null>;
+}
+/**
+ * 액션 본문의 `this`. render 는 항상 있고, 실행 레이어에서 request/reply·
+ * 세션·인증이 채워진다(세션·인증 스텝에서 확장). 단위 테스트의 기본
+ * 컨텍스트는 render/redirect/params 만 순수 구현하고 request/reply 는 없다.
+ */
+export interface ControllerContext {
+    render<P>(page: string, props: P): Rendered<P>;
+    redirect(to: string): Redirect;
+    /** JSON 응답(API/JWT 앱). 값은 응답 경계에서 직렬화된다(bigint/Date/hidden §4.2). */
+    json(data: unknown, status?: number): JsonResult;
+    /**
+     * 폼 입력을 모델 form 의 Row 모양으로 읽는다. 현재는 요청 본문의 타입
+     * 있는 통로다 — 스키마 파생 검증(실패 시 자동 422, §5.2)은 model 의 form
+     * 이 런타임 컬럼 메타를 실어야 가능하며(현재 form._row 는 팬텀), 그 확장은
+     * data 레이어와 함께 후속으로 둔다.
+     */
+    params<T>(form: {
+        readonly _row: T;
+    }): T;
+    /**
+     * 세션 저장소(§7 세션 배터리). 세션 앱에서만 존재하고, JWT/API 앱은
+     * undefined 다. 로그인은 `this.session.userId = ...` 로 사용자를 심는다.
+     */
+    readonly session: Record<string, unknown> | undefined;
+    /** CSRF 토큰을 발급한다(세션에 시크릿 저장). 페이지가 폼/헤더로 되돌려 보낸다. */
+    csrfToken(): string;
+    /** 현재 로그인 사용자. 비로그인 시 null. 인증 설정이 있는 앱에서 채워진다(§7). */
+    currentUser: GaonCurrentUser | null;
+    readonly auth: AuthApi;
+    /** JWT 앱(API)에서만 존재하는 토큰 발급 API. 세션 앱은 undefined. */
+    readonly jwt?: JwtApi;
+    /**
+     * 보호 라우트 가드. 비로그인이면 예외를 던져 디스패처가 로그인 페이지로
+     * 리다이렉트(폼/Inertia)하거나 401(API)로 응답한다. 로그인 상태면 사용자를 돌려준다.
+     */
+    requireAuth(): GaonCurrentUser;
+    readonly request: FastifyRequest;
+    readonly reply: FastifyReply;
+}
+/** 디스패처가 raw(미바인딩) 액션 맵을 꺼내는 키. */
+export declare const RAW_ACTIONS: unique symbol;
+/** 컨트롤러 객체에서 raw 액션 맵을 읽는다(디스패처 전용). */
+export declare function rawActions(ctrl: object): Record<string, (...a: unknown[]) => unknown>;
+/**
+ * 액션 객체를 반환한다. 반환 객체의 각 액션은 기본 컨텍스트에 바인딩돼
+ * 있어(단위 테스트용) c.index() 로 직접 호출된다. 동시에 raw 액션 맵을
+ * 심볼로 실어, 디스패처가 요청별 컨텍스트로 action.call(ctx) 하게 한다.
+ */
+export declare function controller<A extends object>(actions: A & ThisType<ControllerContext>): A;

package/dist/controller.js

@@ -0,0 +1,67 @@
+// @gaonjs/web · controller() 런타임 (M3 타입 브리지 + M5 실행 레이어)
+//
+// 설계 §5.2: `controller({ async index() { return this.render(...) } })`.
+// 액션은 this.render(page, props) 로 페이지·props 를, this.redirect(to) 로
+// 리다이렉트를 반환한다. 렌더 반환 타입(Rendered<P>)이 타입 브리지
+// (.gaon/routes.d.ts)를 거쳐 Vue 페이지의 pageProps<K>() 로 흐른다(§6.2·§6.3).
+//
+// ThisType 주의(§13.4-1 의 model 교훈과 동형): 액션 제네릭에 제약을 걸면
+// ThisType 추론이 조용히 붕괴한다 → **무제약 A + ThisType 교차**로 둔다.
+//
+// 실행 레이어(M5): dispatch.ts 가 요청마다 새 컨텍스트를 만들어 액션을
+// 그 컨텍스트로 호출한다. 그래서 controller() 는 raw(미바인딩) 액션을
+// 심볼로 노출한다. 반환 객체 자체는 기본 컨텍스트에 바인딩돼 있어 단위
+// 테스트에서 c.index() 를 그대로 호출할 수 있다(this.render 동작).
+/** 요청 없이 호출되는 기본 컨텍스트(단위 테스트·타입 브리지). */
+const defaultContext = {
+    render(page, props) {
+        return { page, props };
+    },
+    redirect(to) {
+        return { redirect: to };
+    },
+    json(data, status) {
+        return { json: data, status };
+    },
+    params(_form) {
+        return undefined;
+    },
+    session: undefined,
+    csrfToken() {
+        return '';
+    },
+    currentUser: null,
+    auth: { user: null, login() { }, logout() { } },
+    requireAuth() {
+        throw new Error('requireAuth: 인증 컨텍스트가 없습니다(단위 테스트 기본 컨텍스트).');
+    },
+    // request/reply 는 실제 요청에서만 존재한다 — 기본 컨텍스트(단위 테스트·타입
+    // 브리지)는 의도적으로 생략하므로 unknown 경유로 캐스트한다.
+};
+/** 디스패처가 raw(미바인딩) 액션 맵을 꺼내는 키. */
+export const RAW_ACTIONS = Symbol.for('gaon.web.rawActions');
+/** 컨트롤러 객체에서 raw 액션 맵을 읽는다(디스패처 전용). */
+export function rawActions(ctrl) {
+    return ctrl[RAW_ACTIONS];
+}
+/**
+ * 액션 객체를 반환한다. 반환 객체의 각 액션은 기본 컨텍스트에 바인딩돼
+ * 있어(단위 테스트용) c.index() 로 직접 호출된다. 동시에 raw 액션 맵을
+ * 심볼로 실어, 디스패처가 요청별 컨텍스트로 action.call(ctx) 하게 한다.
+ */
+export function controller(actions) {
+    const raw = {};
+    const bound = {};
+    for (const [name, fn] of Object.entries(actions)) {
+        if (typeof fn === 'function') {
+            const f = fn;
+            raw[name] = f;
+            bound[name] = f.bind(defaultContext);
+        }
+        else {
+            bound[name] = fn;
+        }
+    }
+    Object.defineProperty(bound, RAW_ACTIONS, { value: raw, enumerable: false });
+    return bound;
+}

package/dist/dispatch.d.ts

@@ -0,0 +1,30 @@
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+import type { RouteDef } from './routes.js';
+import { type ControllerContext } from './controller.js';
+/** 한 앱의 디스패치 재료 — 라우트·컨트롤러 맵. */
+export interface AppDispatch {
+    readonly name: string;
+    readonly routes: RouteDef;
+    /** 컨트롤러 이름 → controller() 객체. */
+    readonly controllers: Record<string, object>;
+}
+/** 컨텍스트에 요청별로 얹히는 확장(인증 스텝이 채운다). */
+export interface ContextExtras {
+    augment?(ctx: ControllerContext, request: FastifyRequest, reply: FastifyReply): void | Promise<void>;
+}
+export interface DispatchOptions extends ContextExtras {
+    /** Inertia 에셋 버전 — 클라이언트와 불일치 시 풀 리로드. */
+    readonly version?: string;
+    /**
+     * requireAuth 실패 시 리다이렉트 경로. 세션 앱은 로그인 페이지로 보내고,
+     * 미설정(API/JWT 앱)이면 401 로 응답한다.
+     */
+    readonly loginRedirect?: string;
+}
+/**
+ * 한 앱의 라우트를 (프리픽스가 이미 걸린) Fastify 스코프에 등록한다.
+ * 컨트롤러에 없는 액션은 라우팅하지 않는다 — 라우트 표는 후보이고 구현이 진실이다.
+ */
+export declare function registerApp(app: FastifyInstance, dispatch: AppDispatch, opts?: DispatchOptions): void;
+/** web 앱은 '/', 그 외는 '/<name>' (§3.3 프리픽스 관례). */
+export declare function prefixFor(name: string): string;

package/dist/dispatch.js

@@ -0,0 +1,121 @@
+// @gaonjs/web · 디스패치 (라우트 표 → Fastify 등록 → 컨트롤러 실행)
+//
+// routes.ts 가 만든 RouteDef.entries 를 돌며, 각 엔트리의 컨트롤러에 해당
+// 액션이 실제로 구현돼 있으면 Fastify 라우트로 등록한다(없는 액션은 건너뜀).
+// 요청마다 새 컨텍스트를 만들어 액션을 그 컨텍스트로 호출하고(§5.2), 결과를
+// Inertia 응답으로 내보낸다.
+//
+// 앱별 프리픽스는 createApp 의 캡슐화 스코프(register({ prefix }))가 담당하므로,
+// 여기서는 라우트를 프리픽스 없는 상대 경로로 등록한다 — 세션·CSRF 도 같은
+// 스코프에 갇혀 앱별 완전 분리가 성립한다(질문 13).
+import { rawActions, } from './controller.js';
+import { inertiaRedirect, renderInertia } from './inertia.js';
+import { serializeProps } from './serialize.js';
+import { isUnauthorized, unauthorizedError } from './auth.js';
+function buildContext(request, reply) {
+    // 세션·CSRF 는 @fastify/session · csrf-protection 이 전역 증강으로 붙이지만,
+    // 세션 배터리를 등록한 앱에서만 런타임에 존재한다(JWT/API 앱은 undefined).
+    const req = request;
+    const rep = reply;
+    const sess = req.session;
+    const auth = {
+        user: null,
+        login(user) {
+            // 세션은 Redis 에 JSON 으로 직렬화된다 — bigint PK 는 JSON 에서 던지므로
+            // id 를 문자열로 저장한다. loadUser 가 다시 BigInt 로 되돌린다.
+            if (sess)
+                sess.userId = String(user.id);
+        },
+        logout() {
+            if (sess)
+                delete sess.userId;
+        },
+    };
+    return {
+        render(page, props) {
+            return { page, props };
+        },
+        redirect(to) {
+            return { redirect: to };
+        },
+        json(data, status) {
+            return { json: data, status };
+        },
+        params(_form) {
+            return (request.body ?? {});
+        },
+        session: sess,
+        csrfToken: () => (rep.generateCsrf ? rep.generateCsrf() : ''),
+        currentUser: null,
+        auth,
+        requireAuth() {
+            if (this.currentUser == null)
+                throw unauthorizedError();
+            return this.currentUser;
+        },
+        request,
+        reply,
+    };
+}
+function finish(request, reply, result, version) {
+    if (result == null) {
+        reply.code(204).send();
+        return;
+    }
+    if ('redirect' in result) {
+        inertiaRedirect(request, reply, result.redirect);
+        return;
+    }
+    if ('json' in result) {
+        reply
+            .code(result.status ?? 200)
+            .header('Content-Type', 'application/json; charset=utf-8')
+            .send(JSON.stringify(serializeProps(result.json)));
+        return;
+    }
+    renderInertia(request, reply, result.page, result.props, { version });
+}
+/**
+ * 한 앱의 라우트를 (프리픽스가 이미 걸린) Fastify 스코프에 등록한다.
+ * 컨트롤러에 없는 액션은 라우팅하지 않는다 — 라우트 표는 후보이고 구현이 진실이다.
+ */
+export function registerApp(app, dispatch, opts = {}) {
+    for (const entry of dispatch.routes.entries) {
+        const ctrl = dispatch.controllers[entry.controller];
+        if (!ctrl)
+            continue;
+        const actions = rawActions(ctrl);
+        const fn = actions?.[entry.action];
+        if (typeof fn !== 'function')
+            continue;
+        const handler = async (request, reply) => {
+            const ctx = buildContext(request, reply);
+            if (opts.augment)
+                await opts.augment(ctx, request, reply);
+            let result;
+            try {
+                result = (await fn.call(ctx));
+            }
+            catch (err) {
+                if (isUnauthorized(err)) {
+                    // 세션 앱: 로그인 페이지로. API/JWT 앱: 401.
+                    if (opts.loginRedirect)
+                        inertiaRedirect(request, reply, opts.loginRedirect);
+                    else
+                        reply.code(401).send({ error: 'Unauthorized' });
+                    return reply;
+                }
+                throw err;
+            }
+            if (reply.sent)
+                return reply; // 가드 등이 이미 응답했으면 그대로 둔다
+            finish(request, reply, result, opts.version);
+            return reply;
+        };
+        app.route({ method: entry.method.toUpperCase(), url: entry.path, handler });
+    }
+}
+/** web 앱은 '/', 그 외는 '/<name>' (§3.3 프리픽스 관례). */
+export function prefixFor(name) {
+    return name === 'web' ? '/' : `/${name}`;
+}

package/dist/generator.d.ts

@@ -0,0 +1,23 @@
+export interface DiscoveredRoute {
+    /** 라우트 맵 키 — `<controller>#<action>`. */
+    readonly key: string;
+    /** 이 컨트롤러의 import 바인딩 이름(파일 내 유일·유효 식별자). */
+    readonly binding: string;
+    /** `.gaon/routes.d.ts` 기준 컨트롤러 import 지정자(.js, posix). */
+    readonly importPath: string;
+    /** 컨트롤러 액션 이름. */
+    readonly action: string;
+}
+/** outDir(.gaon) 기준 상대 import 지정자 (.ts→.js, posix, ./·../ 보정). */
+export declare function toImportSpecifier(outDir: string, file: string): string;
+/** 컨트롤러 이름 → 파일 내 유효·유일 import 바인딩. */
+export declare function bindingName(controller: string): string;
+/**
+ * 앱 디렉터리를 스캔해 라우트 목록을 수집한다.
+ * routes.ts 가 없으면 빈 목록(앱에 라우트가 아직 없을 수 있다).
+ */
+export declare function collectRoutes(appDir: string, outDir: string): Promise<DiscoveredRoute[]>;
+/** 수집된 라우트 목록 → routes.d.ts 소스 텍스트. */
+export declare function renderRoutesDts(routes: DiscoveredRoute[]): string;
+/** 전 과정: 앱 스캔 → 렌더 → apps/<app>/.gaon/routes.d.ts 기록. 텍스트 반환. */
+export declare function generateRoutesDts(appDir: string, outFile: string): Promise<string>;

package/dist/generator.js

@@ -0,0 +1,120 @@
+// @gaonjs/web · routes.d.ts 생성기 (M3 — 타입 브리지, 앱별)
+//
+// 앱 하나(apps/<app>)의 `routes.ts` 를 실행해 참조 컨트롤러를 얻고,
+// 각 컨트롤러 파일(controllers/<name>.ts)의 default export 에서 **실제
+// 구현된 액션 키**를 읽어 `.gaon/routes.d.ts` 를 낳는다.
+//
+// 생성 파일은 **타입 참조만** 담는다(CLAUDE.md 규칙 3):
+//   '<ctrl>#<action>': (typeof <ctrl>)['<action>']
+// TanStack Router·Nuxt 가 검증한 방식이며, 참조만 담아 tsserver 부하가
+// 거의 없다(설계 §6.3). 실제 액션 타입 계산은 전부 추론에 맡긴다.
+import { readdir, stat } from 'node:fs/promises';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join, relative, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** outDir(.gaon) 기준 상대 import 지정자 (.ts→.js, posix, ./·../ 보정). */
+export function toImportSpecifier(outDir, file) {
+    let rel = relative(resolve(outDir), resolve(file)).replace(/\\/g, '/');
+    rel = rel.replace(/\.ts$/, '.js');
+    if (!rel.startsWith('.'))
+        rel = './' + rel;
+    return rel;
+}
+/** 컨트롤러 이름 → 파일 내 유효·유일 import 바인딩. */
+export function bindingName(controller) {
+    return 'c_' + controller.replace(/[^A-Za-z0-9_]/g, '_');
+}
+/** ESM 캐시 우회 — 워치 재생성 시 편집 반영(§generator.ts 와 동일 기법). */
+async function importFresh(file) {
+    const st = await stat(file);
+    return (await import(`${pathToFileURL(file).href}?t=${st.mtimeMs}-${st.size}`));
+}
+function isRouteDef(v) {
+    return typeof v === 'object' && v !== null && Array.isArray(v.controllers);
+}
+/** default export(actions 객체)에서 함수 값을 가진 키만 액션으로 취한다. */
+function actionKeys(mod) {
+    const def = mod.default;
+    if (typeof def !== 'object' || def === null)
+        return [];
+    return Object.entries(def)
+        .filter(([, v]) => typeof v === 'function')
+        .map(([k]) => k)
+        .sort();
+}
+/**
+ * 앱 디렉터리를 스캔해 라우트 목록을 수집한다.
+ * routes.ts 가 없으면 빈 목록(앱에 라우트가 아직 없을 수 있다).
+ */
+export async function collectRoutes(appDir, outDir) {
+    const routesFile = join(resolve(appDir), 'routes.ts');
+    const controllersDir = join(resolve(appDir), 'controllers');
+    const routesMod = await importFresh(routesFile);
+    const def = routesMod.default;
+    if (!isRouteDef(def)) {
+        throw new Error(`[@gaonjs/web] ${routesFile} 의 default export 가 routes(...) 결과가 아닙니다.\n` +
+            `→ routes.ts 를 \`export default routes((r) => { ... })\` 형태로 작성하세요.`);
+    }
+    const existing = new Set(await listControllerFiles(controllersDir));
+    const found = [];
+    for (const ctrl of def.controllers) {
+        const file = join(controllersDir, `${ctrl}.ts`);
+        if (!existing.has(file)) {
+            throw new Error(`[@gaonjs/web] 라우트가 참조하는 컨트롤러가 없습니다: ${ctrl}\n` +
+                `→ ${file} 에 \`export default controller({ ... })\` 를 만드세요.`);
+        }
+        const mod = await importFresh(file);
+        const importPath = toImportSpecifier(outDir, file);
+        const binding = bindingName(ctrl);
+        for (const action of actionKeys(mod)) {
+            found.push({ key: `${ctrl}#${action}`, binding, importPath, action });
+        }
+    }
+    return found.sort((a, b) => a.key.localeCompare(b.key));
+}
+async function listControllerFiles(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return []; // controllers 디렉터리가 아직 없을 수 있다
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.endsWith('.ts') && !e.name.endsWith('.d.ts'))
+        .map((e) => join(dir, e.name));
+}
+/** 수집된 라우트 목록 → routes.d.ts 소스 텍스트. */
+export function renderRoutesDts(routes) {
+    const lines = [];
+    lines.push('// AUTO-GENERATED by @gaonjs/web — 편집 금지.');
+    lines.push('// `gaon check` / `gaon dev` 가 검사·개발 중 이 파일을 재생성한다(§6.3).');
+    // 컨트롤러별 import (바인딩 유일) — 등장 순서 안정화.
+    const seen = new Map(); // binding → importPath
+    for (const r of routes)
+        if (!seen.has(r.binding))
+            seen.set(r.binding, r.importPath);
+    for (const [binding, importPath] of seen) {
+        lines.push(`import type ${binding} from '${importPath}'`);
+    }
+    lines.push('');
+    lines.push('declare global {');
+    lines.push('  interface GaonRouteMap {');
+    for (const r of routes) {
+        lines.push(`    '${r.key}': (typeof ${r.binding})['${r.action}']`);
+    }
+    lines.push('  }');
+    lines.push('}');
+    lines.push('');
+    lines.push('export {}');
+    lines.push('');
+    return lines.join('\n');
+}
+/** 전 과정: 앱 스캔 → 렌더 → apps/<app>/.gaon/routes.d.ts 기록. 텍스트 반환. */
+export async function generateRoutesDts(appDir, outFile) {
+    const outDir = dirname(resolve(outFile));
+    const text = renderRoutesDts(await collectRoutes(appDir, outDir));
+    await mkdir(outDir, { recursive: true });
+    await writeFile(outFile, text, 'utf8');
+    return text;
+}

package/dist/index.d.ts

@@ -1,2 +1,13 @@
 export declare const version: string;
-export declare const status: "planned";
+export { routes, type RouteBuilder, type RouteDef, type RouteEntry, type HttpMethod, } from "./routes.js";
+export { controller, rawActions, RAW_ACTIONS, type Rendered, type Redirect, type JsonResult, type ActionResult, type ControllerContext, type AuthApi, type JwtApi, type JwtTokens, type GaonCurrentUser, } from "./controller.js";
+export { collectRoutes, renderRoutesDts, generateRoutesDts, toImportSpecifier, bindingName, type DiscoveredRoute, } from "./generator.js";
+export { createApp, type AppSpec, type SecurityOptions, type CreateAppOptions, } from "./app.js";
+export { registerApp, prefixFor, type AppDispatch, type DispatchOptions, type ContextExtras, } from "./dispatch.js";
+export { registerSession, type AppSessionOptions, } from "./session.js";
+export { redisSessionStore, type RedisStoreOptions, } from "./redisStore.js";
+export { sessionAuthAugment, jwtAuthAugment, unauthorizedError, isUnauthorized, type AuthOptions, type JwtAuthOptions, } from "./auth.js";
+export { signToken, verifyToken, type TokenType } from "./jwt.js";
+export { hashPassword, verifyPassword } from "./password.js";
+export { renderInertia, inertiaRedirect, type InertiaPage, type InertiaOptions, } from "./inertia.js";
+export { serializeProps } from "./serialize.js";

package/dist/index.js

@@ -1,8 +1,32 @@
 /**
  * @gaonjs/web — Gaon 웹 레이어 (Fastify 통합·라우팅·보안 기본값).
  *
- * 구현은 로드맵 M2 이후. 현재는 개발 상태만 노출하는 스텁이다.
+ * 타입 브리지 이음새(M3: routes() DSL·controller() 헬퍼·routes.d.ts 생성기)와
+ * HTTP 실행 레이어(M5: Fastify 앱 팩토리·라우트 디스패치·Inertia 응답·보안
+ * 기본값)를 함께 제공한다.
  */
 import { VERSION } from "@gaonjs/core";
 export const version = VERSION;
-export const status = "planned";
+// 라우팅 DSL (§5.1) — 타입 브리지 + 실행 레이어 라우트 표
+export { routes, } from "./routes.js";
+// controller() — this.render/redirect/params/currentUser (§5.2·§7)
+export { controller, rawActions, RAW_ACTIONS, } from "./controller.js";
+// routes.d.ts 생성기 (앱별 타입 브리지)
+export { collectRoutes, renderRoutesDts, generateRoutesDts, toImportSpecifier, bindingName, } from "./generator.js";
+// HTTP 실행 레이어 (Fastify 앱 팩토리·보안 기본값)
+export { createApp, } from "./app.js";
+// 라우트 디스패치 (라우트 표 → Fastify 등록)
+export { registerApp, prefixFor, } from "./dispatch.js";
+// 세션 배터리 (앱별 분리 + CSRF · Redis 스토어)
+export { registerSession, } from "./session.js";
+export { redisSessionStore, } from "./redisStore.js";
+// 인증 코어 (currentUser · requireAuth · 세션 로그인 · JWT)
+export { sessionAuthAugment, jwtAuthAugment, unauthorizedError, isUnauthorized, } from "./auth.js";
+// JWT 토큰 크립토 (API 앱 · HS256)
+export { signToken, verifyToken } from "./jwt.js";
+// 비밀번호 해싱 (bcrypt · hidden passwordDigest §4.2)
+export { hashPassword, verifyPassword } from "./password.js";
+// Inertia 프로토콜 (서버측 렌더링 계약)
+export { renderInertia, inertiaRedirect, } from "./inertia.js";
+// 응답 경계 직렬화 (hidden 제외 §4.2)
+export { serializeProps } from "./serialize.js";

package/dist/inertia.d.ts

@@ -0,0 +1,24 @@
+import type { FastifyReply, FastifyRequest } from 'fastify';
+/** Inertia 페이지 객체 — 응답 본문(JSON) 또는 data-page(HTML)에 실린다. */
+export interface InertiaPage {
+    readonly component: string;
+    readonly props: unknown;
+    readonly url: string;
+    readonly version: string;
+}
+export interface InertiaOptions {
+    /** 에셋 버전 — 클라이언트와 불일치하면 풀 리로드를 강제한다. 기본 ''. */
+    readonly version?: string;
+    /** 최초(비-Inertia) 요청에 쓰는 HTML 문서 셸. 기본 셸은 #app + data-page. */
+    readonly rootTemplate?: (page: InertiaPage) => string;
+}
+/**
+ * render 결과(page + props)를 Inertia 응답으로 내보낸다.
+ * props 는 응답 경계에서 직렬화된다(Date/bigint→string, hidden 제외 §4.2).
+ */
+export declare function renderInertia(request: FastifyRequest, reply: FastifyReply, page: string, props: unknown, opts?: InertiaOptions): void;
+/**
+ * Inertia 규약에 맞는 리다이렉트. 변경 메서드(PUT/PATCH/DELETE) 뒤에는 303
+ * 이어야 브라우저·클라이언트가 GET 으로 팔로우한다(그 외 302).
+ */
+export declare function inertiaRedirect(request: FastifyRequest, reply: FastifyReply, to: string): void;

package/dist/inertia.js

@@ -0,0 +1,74 @@
+// @gaonjs/web · Inertia 프로토콜 (서버측 렌더링 계약)
+//
+// 컨트롤러의 render('posts/Index', props) 는 프론트엔드를 모른다 — 서버 계약은
+// "페이지 이름 + 직렬화된 props" 뿐이다(§6.1·§6.4). 그 계약을 HTTP 로 실어
+// 나르는 것이 Inertia 프로토콜이다:
+//
+//  · X-Inertia 요청(SPA 네비게이션): JSON { component, props, url, version } 응답.
+//  · 최초 요청(브라우저 문서 로드): HTML 셸에 페이지 객체를 data-page 로 임베드.
+//    실제 마운트는 프론트 어댑터(@gaonjs/vue)와 앱 엔트리가 수행한다.
+//  · 리다이렉트: PUT/PATCH/DELETE 뒤에는 303(그래야 브라우저가 GET 으로 팔로우),
+//    그 외 302. 버전 불일치 GET 은 409 + X-Inertia-Location 으로 풀 리로드 유도.
+//
+// 참조: Inertia.js 프로토콜(https://inertiajs.com/the-protocol) — Laravel 어댑터가
+// 검증한 규약을 그대로 따른다.
+import { serializeProps } from './serialize.js';
+function isInertia(request) {
+    return request.headers['x-inertia'] === 'true';
+}
+/** data-page 속성에 안전하게 넣기 위한 HTML 속성 이스케이프. */
+function escapeAttr(json) {
+    return json
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/'/g, ''')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+function defaultRoot(page) {
+    const data = escapeAttr(JSON.stringify(page));
+    // 앱 엔트리(스캐폴드가 생성)가 #app 을 마운트하고 data-page 를 읽는다.
+    return ('<!doctype html>\n' +
+        '<html>\n<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"></head>\n' +
+        `<body><div id="app" data-page="${data}"></div></body>\n</html>\n`);
+}
+/**
+ * render 결과(page + props)를 Inertia 응답으로 내보낸다.
+ * props 는 응답 경계에서 직렬화된다(Date/bigint→string, hidden 제외 §4.2).
+ */
+export function renderInertia(request, reply, page, props, opts = {}) {
+    const version = opts.version ?? '';
+    const pageObject = {
+        component: page,
+        props: serializeProps(props),
+        url: request.url,
+        version,
+    };
+    // 버전 불일치(X-Inertia GET): 409 + Location 으로 클라이언트가 풀 리로드.
+    if (isInertia(request) && request.method === 'GET') {
+        const clientVersion = request.headers['x-inertia-version'];
+        if (clientVersion !== undefined && clientVersion !== version) {
+            reply.header('X-Inertia-Location', request.url).code(409).send();
+            return;
+        }
+    }
+    if (isInertia(request)) {
+        reply
+            .header('X-Inertia', 'true')
+            .header('Vary', 'X-Inertia')
+            .header('Content-Type', 'application/json; charset=utf-8')
+            .send(JSON.stringify(pageObject));
+        return;
+    }
+    const root = opts.rootTemplate ?? defaultRoot;
+    reply.header('Content-Type', 'text/html; charset=utf-8').send(root(pageObject));
+}
+/**
+ * Inertia 규약에 맞는 리다이렉트. 변경 메서드(PUT/PATCH/DELETE) 뒤에는 303
+ * 이어야 브라우저·클라이언트가 GET 으로 팔로우한다(그 외 302).
+ */
+export function inertiaRedirect(request, reply, to) {
+    const m = request.method;
+    const code = m === 'PUT' || m === 'PATCH' || m === 'DELETE' ? 303 : 302;
+    reply.header('Location', to).code(code).send();
+}

package/dist/jwt.d.ts

@@ -0,0 +1,7 @@
+import { type JWTPayload } from 'jose';
+/** typ 클레임으로 액세스/리프레시를 구분한다. */
+export type TokenType = 'access' | 'refresh';
+/** sub(사용자 id) + typ 을 담은 HS256 토큰을 만든다. ttl 예: '15m', '7d'. */
+export declare function signToken(secret: string, sub: string, typ: TokenType, ttl: string): Promise<string>;
+/** 토큰을 검증한다. 유효하면 payload, 만료·위조·불일치면 null(예외를 삼킨다). */
+export declare function verifyToken(secret: string, token: string): Promise<JWTPayload | null>;

package/dist/jwt.js

@@ -0,0 +1,29 @@
+// @gaonjs/web · JWT 토큰 (API 앱 옵션 · §7 질문 4)
+//
+// 세션 쿠키가 기본이고, JWT 는 API 전용 앱을 위한 옵션이다(app.config 에서 선택).
+// 액세스 토큰(짧은 수명)으로 요청을 인증하고, 리프레시 토큰(긴 수명)으로 액세스
+// 토큰을 재발급한다. 서명은 HS256(jose) — 앱마다 secret 이 달라 토큰이 앱을
+// 넘지 못한다(질문 13 — API 앱의 앱별 분리).
+import { SignJWT, jwtVerify } from 'jose';
+function keyOf(secret) {
+    return new TextEncoder().encode(secret);
+}
+/** sub(사용자 id) + typ 을 담은 HS256 토큰을 만든다. ttl 예: '15m', '7d'. */
+export function signToken(secret, sub, typ, ttl) {
+    return new SignJWT({ typ })
+        .setProtectedHeader({ alg: 'HS256' })
+        .setSubject(sub)
+        .setIssuedAt()
+        .setExpirationTime(ttl)
+        .sign(keyOf(secret));
+}
+/** 토큰을 검증한다. 유효하면 payload, 만료·위조·불일치면 null(예외를 삼킨다). */
+export async function verifyToken(secret, token) {
+    try {
+        const { payload } = await jwtVerify(token, keyOf(secret));
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/password.d.ts

@@ -0,0 +1,4 @@
+/** 평문 비밀번호를 bcrypt 다이제스트로 해싱한다(passwordDigest 컬럼에 저장). */
+export declare function hashPassword(plain: string): Promise<string>;
+/** 평문과 저장된 다이제스트를 상수시간 비교한다. */
+export declare function verifyPassword(plain: string, digest: string): Promise<boolean>;

package/dist/password.js

@@ -0,0 +1,17 @@
+// @gaonjs/web · 비밀번호 해싱 (§7 인증)
+//
+// 해시는 bcrypt 로 한다(설계 §7 "bcrypt or argon2"). 순수 JS 구현인 bcryptjs
+// 를 쓰는 이유: 네이티브 빌드(node-gyp)가 없어 어느 환경에서나 설치가 확실하다
+// (AI 첫 시도 성공률 §1.2). 해시 결과는 스키마의 hidden 컬럼(passwordDigest)에
+// 담기며, 직렬화 경계에서 타입·런타임 양쪽으로 페이지 노출이 막힌다(§4.2).
+import bcrypt from 'bcryptjs';
+/** bcrypt cost. 10 은 보안/지연의 통상 균형점. */
+const COST = 10;
+/** 평문 비밀번호를 bcrypt 다이제스트로 해싱한다(passwordDigest 컬럼에 저장). */
+export function hashPassword(plain) {
+    return bcrypt.hash(plain, COST);
+}
+/** 평문과 저장된 다이제스트를 상수시간 비교한다. */
+export function verifyPassword(plain, digest) {
+    return bcrypt.compare(plain, digest);
+}

package/dist/redisStore.d.ts

@@ -0,0 +1,10 @@
+import type { Redis } from 'ioredis';
+import type { SessionStore } from '@fastify/session';
+export interface RedisStoreOptions {
+    /** 앱별 세션 키 prefix — 완전 분리의 축. 예: 'gaon:sess:web:'. */
+    readonly prefix: string;
+    /** 세션 만료(초). session.cookie.maxAge 가 있으면 그 값을 우선한다. */
+    readonly ttlSeconds: number;
+}
+/** ioredis 인스턴스를 @fastify/session Store 로 감싼다. */
+export declare function redisSessionStore(redis: Redis, opts: RedisStoreOptions): SessionStore;

package/dist/redisStore.js

@@ -0,0 +1,37 @@
+// @gaonjs/web · Redis 세션 스토어 (@fastify/session Store 구현)
+//
+// 세션은 Redis 에 둔다(§7.4 — 캐시/세션 기본 Redis, 개발·테스트도 실 Redis).
+// 앱별 키 prefix 로 세션 저장 공간을 완전히 분리한다(§ 질문 13 — 앱 간 로그인
+// 공유 불허). 인메모리 기본 스토어는 프로세스가 여럿이면 세션이 새므로
+// 운영 경로가 아니다(@fastify/session 문서도 경고).
+/** ioredis 인스턴스를 @fastify/session Store 로 감싼다. */
+export function redisSessionStore(redis, opts) {
+    const keyOf = (sid) => `${opts.prefix}${sid}`;
+    const ttlOf = (session) => {
+        const maxAge = session.cookie?.maxAge;
+        if (typeof maxAge === 'number' && maxAge > 0)
+            return Math.ceil(maxAge / 1000);
+        return opts.ttlSeconds;
+    };
+    return {
+        set(sessionId, session, callback) {
+            const payload = JSON.stringify(session);
+            redis
+                .set(keyOf(sessionId), payload, 'EX', ttlOf(session))
+                .then(() => callback(null))
+                .catch((err) => callback(err));
+        },
+        get(sessionId, callback) {
+            redis
+                .get(keyOf(sessionId))
+                .then((raw) => callback(null, raw ? JSON.parse(raw) : null))
+                .catch((err) => callback(err));
+        },
+        destroy(sessionId, callback) {
+            redis
+                .del(keyOf(sessionId))
+                .then(() => callback(null))
+                .catch((err) => callback(err));
+        },
+    };
+}

package/dist/routes.d.ts

@@ -0,0 +1,27 @@
+export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
+/** 실행 레이어가 소비하는 라우트 엔트리. path 는 앱 프리픽스 이전의 상대 경로. */
+export interface RouteEntry {
+    readonly method: HttpMethod;
+    readonly path: string;
+    readonly controller: string;
+    readonly action: string;
+}
+export interface RouteBuilder {
+    /** Rails 식 복수 리소스 — index/new/create/show/edit/update/destroy. */
+    resources(name: string): void;
+    /** 단수 리소스(세션 등) — new/create/show/update/destroy (index·:id 없음). */
+    resource(name: string): void;
+    get(path: string, target: string): void;
+    post(path: string, target: string): void;
+    put(path: string, target: string): void;
+    patch(path: string, target: string): void;
+    delete(path: string, target: string): void;
+}
+export interface RouteDef {
+    /** 참조 컨트롤러 이름들(정렬·중복제거). 타입 브리지 입력. */
+    readonly controllers: readonly string[];
+    /** 실행 레이어용 라우트 엔트리(선언 순서). */
+    readonly entries: readonly RouteEntry[];
+}
+/** 라우트 정의 빌더를 실행해 컨트롤러 목록과 라우트 엔트리를 수집한다. */
+export declare function routes(build: (r: RouteBuilder) => void): RouteDef;

package/dist/routes.js

@@ -0,0 +1,63 @@
+// @gaonjs/web · 라우팅 DSL (§5.1)
+//
+// `routes((r) => { r.resources('posts') })` 형태다. 두 소비자가 있다:
+//  · 타입 브리지(routes.d.ts 생성기): 어느 컨트롤러가 참조되는지(controllers).
+//  · 실행 레이어(dispatch): method·path·controller·action 엔트리(entries).
+//
+// resources/resource 는 Rails 관례로 표준 액션을 전개한다. 실제로 어떤
+// 액션이 등록되는지는 디스패처가 컨트롤러에 그 액션이 구현돼 있는지로
+// 거른다 — 라우트 표는 후보이고, 없는 액션은 라우팅되지 않는다.
+function resourcesEntries(name) {
+    return [
+        { method: 'get', path: `/${name}`, controller: name, action: 'index' },
+        { method: 'get', path: `/${name}/new`, controller: name, action: 'new' },
+        { method: 'post', path: `/${name}`, controller: name, action: 'create' },
+        { method: 'get', path: `/${name}/:id`, controller: name, action: 'show' },
+        { method: 'get', path: `/${name}/:id/edit`, controller: name, action: 'edit' },
+        { method: 'patch', path: `/${name}/:id`, controller: name, action: 'update' },
+        { method: 'delete', path: `/${name}/:id`, controller: name, action: 'destroy' },
+    ];
+}
+function resourceEntries(name) {
+    return [
+        { method: 'get', path: `/${name}/new`, controller: name, action: 'new' },
+        { method: 'post', path: `/${name}`, controller: name, action: 'create' },
+        { method: 'get', path: `/${name}`, controller: name, action: 'show' },
+        { method: 'patch', path: `/${name}`, controller: name, action: 'update' },
+        { method: 'delete', path: `/${name}`, controller: name, action: 'destroy' },
+    ];
+}
+/** `controller#action` 대상을 파싱한다. action 생략 시 관례로 채우지 않고 그대로 둔다. */
+function parseTarget(target) {
+    const [controller, action] = target.split('#');
+    return { controller: (controller ?? '').trim(), action: (action ?? '').trim() };
+}
+/** 라우트 정의 빌더를 실행해 컨트롤러 목록과 라우트 엔트리를 수집한다. */
+export function routes(build) {
+    const controllers = new Set();
+    const entries = [];
+    const manual = (method, path, target) => {
+        const { controller, action } = parseTarget(target);
+        if (controller) {
+            controllers.add(controller);
+            entries.push({ method, path, controller, action });
+        }
+    };
+    const r = {
+        resources: (name) => {
+            controllers.add(name);
+            entries.push(...resourcesEntries(name));
+        },
+        resource: (name) => {
+            controllers.add(name);
+            entries.push(...resourceEntries(name));
+        },
+        get: (p, t) => manual('get', p, t),
+        post: (p, t) => manual('post', p, t),
+        put: (p, t) => manual('put', p, t),
+        patch: (p, t) => manual('patch', p, t),
+        delete: (p, t) => manual('delete', p, t),
+    };
+    build(r);
+    return { controllers: [...controllers].sort(), entries };
+}

package/dist/serialize.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 컨트롤러 props 를 JSON-safe 페이지 props 로 변환한다.
+ * Date→ISO 문자열, bigint→문자열, 함수 제거, hidden 컬럼 제외, 중첩 재귀.
+ */
+export declare function serializeProps<T>(value: T): unknown;

package/dist/serialize.js

@@ -0,0 +1,46 @@
+// @gaonjs/web · 응답 경계 직렬화 (render → Inertia props 변환)
+//
+// 컨트롤러가 render(page, props) 로 넘긴 props 는 그대로 JSON 이 아니다(§4.4):
+// 모델 레코드에는 메서드·관계 함수가 붙어 있고, Date·bigint 는 JSON 위에서
+// 문자열이 되며(bigint 는 JSON.stringify 가 던진다), hidden 컬럼(예:
+// passwordDigest)은 노출되면 안 된다(§4.2).
+//
+// 이 변환은 프론트엔드 중립이다(§6.4 — 서버 계약은 "페이지 이름 + 직렬화된
+// props" 뿐). 따라서 render→응답을 소유한 web 이 런타임을 갖고, @gaonjs/vue
+// 는 이 JSON 모양에 대응하는 타입 매핑(Serialized<T>)과 클라이언트 이음새를
+// 담당한다. hidden 판정 지식(HIDDEN_COLUMNS 마커)의 출처는 @gaonjs/core 다.
+import { HIDDEN_COLUMNS } from '@gaonjs/core';
+/**
+ * 컨트롤러 props 를 JSON-safe 페이지 props 로 변환한다.
+ * Date→ISO 문자열, bigint→문자열, 함수 제거, hidden 컬럼 제외, 중첩 재귀.
+ */
+export function serializeProps(value) {
+    return serialize(value);
+}
+function serialize(value) {
+    if (value === null || value === undefined)
+        return value;
+    if (typeof value === 'bigint')
+        return value.toString();
+    if (value instanceof Date)
+        return value.toISOString();
+    if (Array.isArray(value))
+        return value.map(serialize);
+    if (typeof value === 'object') {
+        // 모델 레코드는 HIDDEN_COLUMNS 마커(비열거)로 제외할 컬럼명을 싣는다.
+        const hidden = value[HIDDEN_COLUMNS];
+        const out = {};
+        for (const key of Object.keys(value)) {
+            if (hidden && hidden.includes(key))
+                continue;
+            const v = value[key];
+            if (typeof v === 'function')
+                continue; // 메서드·관계 함수는 직렬화하지 않는다
+            out[key] = serialize(v);
+        }
+        return out;
+    }
+    if (typeof value === 'function')
+        return undefined;
+    return value;
+}

package/dist/session.d.ts

@@ -0,0 +1,27 @@
+import type { FastifyInstance } from 'fastify';
+import { Redis } from 'ioredis';
+export interface AppSessionOptions {
+    /** 세션 스토어 백엔드(Redis 인스턴스). redisUrl 과 택일. 앱별 prefix 로 분리된다. */
+    readonly redis?: Redis;
+    /** Redis 접속 URL. redis 인스턴스 대신 이걸 주면 프레임웍이 클라이언트를 만든다(스캐폴드 DX). */
+    readonly redisUrl?: string;
+    /** 서명 secret — 32자 이상(@fastify/session 요구). 앱마다 달라야 분리가 완성된다. */
+    readonly secret: string;
+    /** 세션 쿠키 이름. 생략 시 `<app>_sid`. */
+    readonly cookieName?: string;
+    /** Redis 키 prefix. 생략 시 `gaon:sess:<app>:`. */
+    readonly redisPrefix?: string;
+    /** 세션 만료(초). 기본 7일. */
+    readonly ttlSeconds?: number;
+    /** 쿠키 Secure. 기본 NODE_ENV==='production'. */
+    readonly secure?: boolean;
+    /** SameSite. 기본 'lax'. */
+    readonly sameSite?: 'lax' | 'strict' | 'none';
+    /** CSRF 보호. 기본 켬(§2.5.1). 명시적으로만 끈다. */
+    readonly csrf?: boolean;
+}
+/**
+ * 한 앱 스코프에 세션(+CSRF)을 등록한다. createApp 이 앱별 캡슐화 스코프
+ * 안에서 호출하므로, 세션·쿠키·CSRF 가 그 앱의 라우트에만 적용된다.
+ */
+export declare function registerSession(scope: FastifyInstance, appName: string, prefix: string, opts: AppSessionOptions): Promise<void>;

package/dist/session.js

@@ -0,0 +1,76 @@
+// @gaonjs/web · 세션 배터리 (앱별 완전 분리 + CSRF)
+//
+// 세션 쿠키가 기본 인증 방식이다(§7 · 질문 4). 앱별로 세션을 **완전히
+// 분리**한다(질문 13 — 앱 간 로그인 공유 불허): 각 앱은 자기만의
+//  · 세션 쿠키 이름(`<app>_sid`)
+//  · 서명 secret
+//  · Redis 키 prefix
+//  · 쿠키 path(앱 프리픽스)
+// 를 갖는다. 이는 Fastify 캡슐화 스코프(createApp 이 앱마다 register)에서
+// 세션 플러그인을 앱 단위로 등록해 달성한다.
+//
+// CSRF 는 보안 기본값으로 켠다(§2.5.1). 세션에 시크릿을 두고(@fastify/session
+// 연동), 상태 변경 메서드(POST/PUT/PATCH/DELETE)에 토큰 검증을 강제한다.
+// 토큰은 X-CSRF-TOKEN 헤더(Inertia/axios 관례) 또는 폼 _csrf 로 받는다.
+import { Redis } from 'ioredis';
+import session from '@fastify/session';
+import csrf from '@fastify/csrf-protection';
+import { redisSessionStore } from './redisStore.js';
+const DEFAULT_TTL_SECONDS = 7 * 24 * 60 * 60; // 7일
+const UNSAFE = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+function csrfToken(req) {
+    const header = req.headers['x-csrf-token'];
+    if (typeof header === 'string')
+        return header;
+    const body = req.body;
+    if (body && typeof body._csrf === 'string')
+        return body._csrf;
+}
+/**
+ * 한 앱 스코프에 세션(+CSRF)을 등록한다. createApp 이 앱별 캡슐화 스코프
+ * 안에서 호출하므로, 세션·쿠키·CSRF 가 그 앱의 라우트에만 적용된다.
+ */
+export async function registerSession(scope, appName, prefix, opts) {
+    const ttlSeconds = opts.ttlSeconds ?? DEFAULT_TTL_SECONDS;
+    const secure = opts.secure ?? process.env.NODE_ENV === 'production';
+    // redis 인스턴스 우선, 없으면 redisUrl 로 만든다(프레임웍 소유 → onClose 에서 정리).
+    let redis = opts.redis;
+    if (!redis) {
+        if (!opts.redisUrl) {
+            throw new Error(`[@gaonjs/web] 세션 설정에 redis 인스턴스나 redisUrl 이 필요합니다.\n` +
+                `→ app.config 의 session 에 { redisUrl: 'redis://127.0.0.1:6379' } 를 추가하세요.`);
+        }
+        redis = new Redis(opts.redisUrl);
+        scope.addHook('onClose', async () => {
+            await redis.quit();
+        });
+    }
+    await scope.register(session, {
+        secret: opts.secret,
+        cookieName: opts.cookieName ?? `${appName}_sid`,
+        saveUninitialized: false,
+        store: redisSessionStore(redis, {
+            prefix: opts.redisPrefix ?? `gaon:sess:${appName}:`,
+            ttlSeconds,
+        }),
+        cookie: {
+            httpOnly: true,
+            secure,
+            sameSite: opts.sameSite ?? 'lax',
+            path: prefix, // 쿠키를 앱 프리픽스로 스코프 — 분리 방어 한 겹 더
+            maxAge: ttlSeconds * 1000,
+        },
+    });
+    if (opts.csrf !== false) {
+        await scope.register(csrf, {
+            sessionPlugin: '@fastify/session',
+            getToken: csrfToken,
+        });
+        // 상태 변경 메서드에 토큰 검증을 강제한다(안전 메서드는 통과).
+        scope.addHook('preHandler', (req, reply, done) => {
+            if (!UNSAFE.has(req.method))
+                return done();
+            scope.csrfProtection(req, reply, done);
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaonjs/web",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Gaon 웹 레이어: Fastify 통합·파일 기반 라우팅·보안 기본값 (구현 예정)",
   "type": "module",
   "license": "MIT",
@@ -24,7 +24,16 @@
     "README.md"
   ],
   "dependencies": {
-    "@gaonjs/core": "0.1.2"
+    "@fastify/cookie": "^11.1.2",
+    "@fastify/cors": "^11.3.0",
+    "@fastify/csrf-protection": "^8.0.0",
+    "@fastify/rate-limit": "^11.1.0",
+    "@fastify/session": "^11.1.2",
+    "bcryptjs": "^3.0.3",
+    "fastify": "^5.10.0",
+    "ioredis": "^5.11.1",
+    "jose": "^6.2.4",
+    "@gaonjs/core": "0.1.3"
   },
   "scripts": {
     "build": "node ../../node_modules/typescript/bin/tsc -p tsconfig.json"