@gaonjs/web 0.1.3 → 0.2.1

package/dist/app.d.ts

@@ -0,0 +1,65 @@
+import { type FastifyInstance, type FastifyServerOptions } from 'fastify';
+import { type FastifyCorsOptions } from '@fastify/cors';
+import { type GaonNats } from '@gaonjs/async';
+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';
+import { type ChannelMap } from './websocket.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;
+    /**
+     * 실시간 채널(§7 · M6). apps/<app>/channels/<이름>.ts 의 default export 를
+     * 이름별로 모은 맵. realtime(NATS)이 설정된 경우에만 활성.
+     */
+    readonly channels?: ChannelMap;
+}
+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;
+    /**
+     * 실시간 백본(§7 · M6). 설정하면 채널(ws)이 활성화된다. nats 커넥션은
+     * 호출자가 소유·종료한다(여기선 채널 런타임만 onClose 로 정리). server 는
+     * 프레즌스 식별자(생략 시 hostname#pid). heartbeatMs 는 프레즌스 하트비트
+     * 주기(생략 시 런타임 기본 10000) — 허브 만료 임계의 1/3 이하로 둔다.
+     */
+    readonly realtime?: {
+        readonly nats: GaonNats;
+        readonly server?: string;
+        readonly heartbeatMs?: number;
+    };
+}
+/**
+ * 앱 스펙들로 Fastify 인스턴스를 만든다. 쿠키·CORS·rate limit(보안 기본값)을
+ * 켜고, 각 앱의 라우트를 프리픽스 아래 등록한다. listen 은 호출자가 한다.
+ */
+export declare function createApp(opts: CreateAppOptions): Promise<FastifyInstance>;
+export type { RouteDef };

package/dist/app.js

@@ -0,0 +1,123 @@
+// @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 { hostname } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { createChannelRuntime } from '@gaonjs/async';
+import { prefixFor, registerApp } from './dispatch.js';
+import { registerSession } from './session.js';
+import { jwtAuthAugment, sessionAuthAugment } from './auth.js';
+import { registerChannels, registerWebSocketSupport, } from './websocket.js';
+import { verifyToken } from './jwt.js';
+/**
+ * 앱 스펙들로 Fastify 인스턴스를 만든다. 쿠키·CORS·rate limit(보안 기본값)을
+ * 켜고, 각 앱의 라우트를 프리픽스 아래 등록한다. listen 은 호출자가 한다.
+ */
+export async function createApp(opts) {
+    const app = Fastify(opts.fastify);
+    const security = opts.security ?? {};
+    // 실시간 채널 런타임 — 프로세스당 하나(전 앱 공유, NATS 는 호출자 소유).
+    let runtime;
+    if (opts.realtime) {
+        const server = opts.realtime.server ?? `${hostname()}#${process.pid}`;
+        runtime = await createChannelRuntime({
+            nats: opts.realtime.nats,
+            server,
+            heartbeatMs: opts.realtime.heartbeatMs,
+        });
+        // 전역 upgrade 훅은 루트에서 한 번만 — 채널 라우트는 앱 스코프에서 정의.
+        await registerWebSocketSupport(app);
+        app.addHook('onClose', async () => {
+            await runtime?.close();
+        });
+    }
+    // 쿠키 — 세션·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));
+            // 채널(ws)은 세션과 같은 스코프에 등록 — 연결이 앱 세션으로 인증된다.
+            if (runtime && spec.channels && Object.keys(spec.channels).length > 0) {
+                registerChannels(scope, {
+                    runtime,
+                    channels: spec.channels,
+                    resolveMember: memberResolverFor(spec),
+                });
+            }
+        }, { 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 };
+}
+/**
+ * 채널 연결의 멤버/사용자를 앱 인증 방식에 맞춰 해석한다. 세션 앱은
+ * session.userId 로, JWT 앱은 쿼리(access_token)로 인증한다(웹소켓은
+ * 커스텀 헤더를 못 실으므로 API 앱은 쿼리 토큰이 관례다). 비로그인은
+ * 익명 연결(공개 채널 허용).
+ */
+function memberResolverFor(spec) {
+    const auth = spec.auth;
+    if (!auth)
+        return undefined;
+    if ('strategy' in auth && auth.strategy === 'jwt') {
+        return async (request) => {
+            const token = request.query?.access_token;
+            if (typeof token === 'string') {
+                const payload = await verifyToken(auth.secret, token);
+                if (payload && payload.typ === 'access' && typeof payload.sub === 'string') {
+                    const user = (await auth.loadUser(payload.sub)) ?? null;
+                    return { member: `user:${payload.sub}`, user };
+                }
+            }
+            return { member: `conn:${randomUUID()}`, user: null };
+        };
+    }
+    const sessionAuth = auth;
+    return async (request) => {
+        const uid = request.session?.userId;
+        if (uid == null)
+            return { member: `conn:${randomUUID()}`, user: null };
+        const user = (await sessionAuth.loadUser(uid)) ?? null;
+        return { member: `user:${String(uid)}`, user };
+    };
+}

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

@@ -1,14 +1,103 @@
+import type { FastifyReply, FastifyRequest } from 'fastify';
+/** 렌더 결과 — 페이지 이름 + props. 타입 브리지 입력(§6.2). */
 export interface Rendered<P> {
     readonly page: string;
     readonly props: P;
 }
-/** 액션 본문의 `this` — M3 최소는 render 만. */
+/**
+ * 리다이렉트 결과. 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>;
 /**
- * 액션 객체를 그대로 반환하되, 본문의 `this` 를 ControllerContext 로
- * 준다(ThisType). 런타임에서는 각 액션을 context 에 바인딩해, 실제
- * 호출 시 `this.render` 가 동작하게 한다.
+ * 액션 객체를 반환한다. 반환 객체의 각 액션은 기본 컨텍스트에 바인딩돼
+ * 있어(단위 테스트용) c.index() 로 직접 호출된다. 동시에 raw 액션 맵을
+ * 심볼로 실어, 디스패처가 요청별 컨텍스트로 action.call(ctx) 하게 한다.
  */
 export declare function controller<A extends object>(actions: A & ThisType<ControllerContext>): A;

package/dist/controller.js

@@ -1,29 +1,67 @@
-// @gaonjs/web · controller() 최소 런타임 (M3 — 최소 웹 레이어)
+// @gaonjs/web · controller() 런타임 (M3 타입 브리지 + M5 실행 레이어)
 //
 // 설계 §5.2: `controller({ async index() { return this.render(...) } })`.
-// 액션은 `this.render(page, props)` 로 페이지와 props 를 반환하고, 그
-// 반환 타입(Rendered<P>)이 타입 브리지(.gaon/routes.d.ts)를 거쳐 Vue
-// 페이지의 pageProps<K>() 로 흐른다(§6.2·§6.3).
+// 액션은 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 교차**로
-// 둔다. 타입 회귀 테스트(controller.test-d.ts)로 고정한다.
+// ThisType 주의(§13.4-1 의 model 교훈과 동형): 액션 제네릭에 제약을 걸면
+// ThisType 추론이 조용히 붕괴한다 → **무제약 A + ThisType 교차**로 둔다.
 //
-// this.params·auth·redirect 등 나머지 실행 시맨틱은 후속 마일스톤이다.
-const context = {
+// 실행 레이어(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];
+}
 /**
- * 액션 객체를 그대로 반환하되, 본문의 `this` 를 ControllerContext 로
- * 준다(ThisType). 런타임에서는 각 액션을 context 에 바인딩해, 실제
- * 호출 시 `this.render` 가 동작하게 한다.
+ * 액션 객체를 반환한다. 반환 객체의 각 액션은 기본 컨텍스트에 바인딩돼
+ * 있어(단위 테스트용) c.index() 로 직접 호출된다. 동시에 raw 액션 맵을
+ * 심볼로 실어, 디스패처가 요청별 컨텍스트로 action.call(ctx) 하게 한다.
  */
 export function controller(actions) {
+    const raw = {};
     const bound = {};
     for (const [name, fn] of Object.entries(actions)) {
-        bound[name] = typeof fn === 'function' ? fn.bind(context) : fn;
+        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}`;
+}