@gaonjs/web 0.1.3 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,14 @@
 export declare const version: string;
-export declare const status: "planned";
-export { routes, type RouteBuilder, type RouteDef, type HttpMethod, } from "./routes.js";
-export { controller, type Rendered, type ControllerContext, } from "./controller.js";
+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";
+export { registerChannels, registerWebSocketSupport, type ChannelMap, type MemberIdentity, type MemberResolver, type RegisterChannelsOptions, } from "./websocket.js";

package/dist/index.js

@@ -1,16 +1,34 @@
 /**
  * @gaonjs/web — Gaon 웹 레이어 (Fastify 통합·라우팅·보안 기본값).
  *
- * 전체 실행 레이어(HTTP 바인딩·미들웨어·render)는 후속 마일스톤이다.
- * M3 에서는 타입 브리지 이음새만 놓는다: routes() DSL·controller() 헬퍼와
- * routes.d.ts 생성기(§6.3).
+ * 타입 브리지 이음새(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 (M3 최소 — 타입 브리지용)
+// 라우팅 DSL (§5.1) — 타입 브리지 + 실행 레이어 라우트 표
 export { routes, } from "./routes.js";
-// controller() 최소 런타임 (M3 — this.render)
-export { controller, } from "./controller.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";
+// 실시간 채널 전송 (WebSocket · §7 M6)
+export { registerChannels, registerWebSocketSupport, } from "./websocket.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

@@ -1,8 +1,15 @@
 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 식 리소스 라우팅 — 표준 액션을 컨트롤러 <name> 에 연결. */
+    /** 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;
@@ -11,12 +18,10 @@ export interface RouteBuilder {
     delete(path: string, target: string): void;
 }
 export interface RouteDef {
-    /** 이 앱 라우트가 참조하는 컨트롤러 이름들(정렬·중복제거). 타입 브리지 입력. */
+    /** 참조 컨트롤러 이름들(정렬·중복제거). 타입 브리지 입력. */
     readonly controllers: readonly string[];
+    /** 실행 레이어용 라우트 엔트리(선언 순서). */
+    readonly entries: readonly RouteEntry[];
 }
-/**
- * 라우트 정의 빌더를 실행해 참조 컨트롤러 목록을 수집한다.
- * `get('/about', 'pages#about')` 처럼 `controller#action` 대상은
- * `#` 앞부분(컨트롤러)만 취한다.
- */
+/** 라우트 정의 빌더를 실행해 컨트롤러 목록과 라우트 엔트리를 수집한다. */
 export declare function routes(build: (r: RouteBuilder) => void): RouteDef;

package/dist/routes.js

@@ -1,30 +1,63 @@
-// @gaonjs/web · 라우팅 DSL (M3 최소 구현 — 타입 브리지용)
+// @gaonjs/web · 라우팅 DSL (§5.1)
 //
-// 설계 §5.1 의 `routes((r) => { r.resources('posts') })` 형태다. M3 는
-// 타입 브리지(routes.d.ts) 생성을 위해 **어느 컨트롤러가 이 앱 라우트에
-// 참조되는지**만 기록하면 된다. 실제 라우팅 매칭·미들웨어·HTTP 바인딩은
-// @gaonjs/web 후속 마일스톤이다 — 여기서는 그 이음새만 놓는다.
-/**
- * 라우트 정의 빌더를 실행해 참조 컨트롤러 목록을 수집한다.
- * `get('/about', 'pages#about')` 처럼 `controller#action` 대상은
- * `#` 앞부분(컨트롤러)만 취한다.
- */
+// `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 addTarget = (target) => {
-        const ctrl = target.split('#')[0]?.trim();
-        if (ctrl)
-            controllers.add(ctrl);
+    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) => void controllers.add(name),
-        resource: (name) => void controllers.add(name),
-        get: (_p, t) => addTarget(t),
-        post: (_p, t) => addTarget(t),
-        put: (_p, t) => addTarget(t),
-        patch: (_p, t) => addTarget(t),
-        delete: (_p, t) => addTarget(t),
+        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() };
+    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/dist/websocket.d.ts

@@ -0,0 +1,28 @@
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import type { ChannelDef, ChannelRuntime } from '@gaonjs/async';
+/**
+ * @fastify/websocket 을 등록한다. 전역 upgrade 훅을 걸므로 서버당 **한 번만**
+ * (루트에서) 호출해야 한다. 라우트(registerChannels)는 이후 어느 스코프에서든
+ * 정의할 수 있다.
+ */
+export declare function registerWebSocketSupport(app: FastifyInstance): Promise<void>;
+export type ChannelMap = Record<string, ChannelDef<unknown>>;
+/** 연결 주체(멤버 식별자 + 인증 사용자). */
+export interface MemberIdentity {
+    readonly member: string;
+    readonly user: unknown;
+}
+export type MemberResolver = (request: FastifyRequest) => Promise<MemberIdentity> | MemberIdentity;
+export interface RegisterChannelsOptions {
+    readonly runtime: ChannelRuntime;
+    readonly channels: ChannelMap;
+    /** 연결 주체 해석(세션·JWT). 생략 시 세션 userId 또는 익명. */
+    readonly resolveMember?: MemberResolver;
+    /** ws 라우트 경로(스코프 프리픽스 이후). 기본 '/gaon/ws/:channel'. */
+    readonly path?: string;
+}
+/**
+ * 앱 스코프에 채널 ws 라우트를 등록한다. 연결마다 멤버를 해석하고 런타임에
+ * join 을 위임하며, 소켓 메시지를 채널 정의의 onMessage 로 흘린다.
+ */
+export declare function registerChannels(scope: FastifyInstance, opts: RegisterChannelsOptions): void;