@aiquants/auth-react-router 0.1.1

package/src/server/handlers.spec.ts

@@ -0,0 +1,154 @@
+/**
+ * Tests for the auth route handlers (login/logout/callback).
+ * 認証ルートハンドラ (login/logout/callback) のテスト。
+ */
+import type { MyGoogleProfile } from "@aiquants/auth-core"
+import type { Authenticator } from "remix-auth"
+import { describe, expect, it } from "vitest"
+import { createAuthHandlers } from "./handlers"
+import type { AuthServerConfig, LoggerPort } from "./ports"
+import { createAuthSessionStorage } from "./session"
+
+const silentLogger: LoggerPort = { info: () => {}, warn: () => {}, error: () => {} }
+
+const config: AuthServerConfig = {
+    google: { clientId: "cid", clientSecret: "csec", redirectURI: "http://localhost/cb" },
+    session: { secrets: ["test-secret"] },
+    isEmailAllowed: () => true,
+    logger: silentLogger,
+}
+
+const googleProfile: MyGoogleProfile = {
+    id: "107791905418691074770",
+    displayName: "宏治",
+    name: { familyName: "F", givenName: "G" },
+    emails: [{ value: "u@example.com" }],
+    photo: "https://example.com/p.png",
+    accessToken: "at",
+    refreshToken: "rt",
+    expirationDateMs: 1750000000000,
+    provider: "google",
+}
+
+const fakeAuthenticator = (result: MyGoogleProfile | Error): Authenticator<MyGoogleProfile> =>
+    ({
+        authenticate: async () => {
+            if (result instanceof Error) throw result
+            return result
+        },
+    }) as unknown as Authenticator<MyGoogleProfile>
+
+const setup = (authResult: MyGoogleProfile | Error = googleProfile) => {
+    const storage = createAuthSessionStorage(config.session)
+    const handlers = createAuthHandlers(config, storage, fakeAuthenticator(authResult), silentLogger)
+    return { storage, handlers }
+}
+
+describe("loginLoader", () => {
+    it("returns the error query param for unauthenticated users", async () => {
+        const { handlers } = setup()
+        const data = await handlers.loginLoader({ request: new Request("http://localhost/auth/login?error=oops") })
+        expect(data).toEqual({ error: "oops" })
+    })
+
+    it("redirects authenticated users to the post-login path", async () => {
+        const { handlers, storage } = setup()
+        const cookie = await storage.saveSession(new Request("http://localhost/"), googleProfile)
+        try {
+            await handlers.loginLoader({ request: new Request("http://localhost/auth/login", { headers: { Cookie: cookie } }) })
+            expect.unreachable("should have thrown a redirect")
+        } catch (error) {
+            expect((error as Response).headers.get("Location")).toBe("/")
+        }
+    })
+})
+
+describe("loginAction", () => {
+    it("authenticates on the Google form action", async () => {
+        const { handlers } = setup()
+        const form = new FormData()
+        form.set("_action", "Sign In with Google")
+        const user = await handlers.loginAction({ request: new Request("http://localhost/auth/login", { method: "POST", body: form }) })
+        expect(user).toEqual(googleProfile)
+    })
+
+    it("returns null for unknown actions", async () => {
+        const { handlers } = setup()
+        const form = new FormData()
+        form.set("_action", "Something Else")
+        const user = await handlers.loginAction({ request: new Request("http://localhost/auth/login", { method: "POST", body: form }) })
+        expect(user).toBeNull()
+    })
+})
+
+describe("logoutLoader", () => {
+    it("destroys the session and redirects with Set-Cookie", async () => {
+        const { handlers, storage } = setup()
+        const cookie = await storage.saveSession(new Request("http://localhost/"), googleProfile)
+        try {
+            await handlers.logoutLoader({ request: new Request("http://localhost/auth/logout", { headers: { Cookie: cookie } }) })
+            expect.unreachable("should have thrown a redirect")
+        } catch (error) {
+            const res = error as Response
+            expect(res.headers.get("Location")).toBe("/")
+            expect(res.headers.get("Set-Cookie")).toContain("__session=")
+        }
+    })
+})
+
+describe("googleCallbackLoader", () => {
+    it("saves a byte-compatible SessionProfile (no photo) and redirects home", async () => {
+        const { handlers, storage } = setup()
+        try {
+            await handlers.googleCallbackLoader({ request: new Request("http://localhost/auth/api/google/callback?code=x") })
+            expect.unreachable("should have thrown a redirect")
+        } catch (error) {
+            const res = error as Response
+            expect(res.headers.get("Location")).toBe("/")
+            const setCookie = res.headers.get("Set-Cookie")
+            expect(setCookie).toContain("__session=")
+
+            // 保存されたセッションを読み戻し、photo を含まない byte 互換形状を検証
+            const user = await storage.getSessionUser(new Request("http://localhost/", { headers: { Cookie: setCookie ?? "" } }))
+            expect(user).toEqual({
+                id: googleProfile.id,
+                displayName: googleProfile.displayName,
+                name: googleProfile.name,
+                emails: googleProfile.emails,
+                accessToken: "at",
+                refreshToken: "rt",
+                expirationDateMs: 1750000000000,
+                provider: "google",
+                role: undefined,
+            })
+            expect(user && "photo" in user).toBe(false)
+        }
+    })
+
+    it("redirects to the login page on authenticator errors", async () => {
+        const { handlers } = setup(new Error("access_denied"))
+        try {
+            await handlers.googleCallbackLoader({ request: new Request("http://localhost/auth/api/google/callback") })
+            expect.unreachable("should have thrown a redirect")
+        } catch (error) {
+            expect((error as Response).headers.get("Location")).toBe("/auth/login")
+        }
+    })
+
+    it("re-throws Response errors from the authenticator as-is", async () => {
+        const redirectResponse = new Response(null, { status: 302, headers: { Location: "/auth/login?error=x" } })
+        const storage = createAuthSessionStorage(config.session)
+        const authenticator = {
+            authenticate: async () => {
+                throw redirectResponse
+            },
+        } as unknown as Authenticator<MyGoogleProfile>
+        const handlers = createAuthHandlers(config, storage, authenticator, silentLogger)
+        try {
+            await handlers.googleCallbackLoader({ request: new Request("http://localhost/auth/api/google/callback") })
+            expect.unreachable("should have thrown the response")
+        } catch (error) {
+            expect(error).toBe(redirectResponse)
+        }
+    })
+})

package/src/server/handlers.ts

@@ -0,0 +1,134 @@
+/**
+ * @module handlers
+ * @description Route handler factories for login / logout / Google callback.
+ * login / logout / Google コールバックのルートハンドラ工場。
+ *
+ * 原本 (quants-react-router routes/_auth+ の 4 ルート + features/logoutAndRedirect.ts) の
+ * サーバー側ロジックを挙動保存で移植。UI (JSX) はアプリ側に残す。
+ * コールバックのセッション保存形状 (SessionProfile、photo/_json/photos を含まない) は
+ * cookie byte 互換のため厳密に保存する。
+ */
+import type { AuthenticationPayload, MyGoogleProfile, SessionProfile } from "@aiquants/auth-core"
+import { redirect } from "react-router"
+import type { Authenticator } from "remix-auth"
+import type { AuthServerConfig, LoggerPort } from "./ports"
+import type { AuthSessionStorage } from "./session"
+
+/** createAuthHandlers が返すハンドラ束。 */
+export type AuthHandlers = ReturnType<typeof createAuthHandlers>
+
+/**
+ * Builds loader/action handlers for the auth routes.
+ * 認証ルート用の loader/action ハンドラ群を生成する。
+ */
+export const createAuthHandlers = (config: AuthServerConfig, storage: AuthSessionStorage, authenticator: Authenticator<MyGoogleProfile>, logger: LoggerPort) => {
+    const loginPath = config.loginPath ?? "/auth/login"
+    const postLoginRedirect = config.postLoginRedirect ?? "/"
+    const postLogoutRedirect = config.postLogoutRedirect ?? "/"
+
+    /**
+     * Login-page loader: redirects authenticated users, passes the error message through.
+     * ログインページ loader。認証済みならリダイレクトし、エラーメッセージを data として返す。
+     */
+    const loginLoader = async ({ request }: { request: Request }): Promise<{ error: string | null }> => {
+        const user = await storage.getSessionUser(request)
+        if (user) {
+            // 認証済みならトップページにリダイレクト
+            throw redirect(postLoginRedirect)
+        }
+        const url = new URL(request.url)
+        const error = url.searchParams.get("error")
+        return { error } // エラーメッセージを loader data として渡す
+    }
+
+    /**
+     * Login action: starts the Google OAuth flow for the "Sign In with Google" form action.
+     * ログイン action。"Sign In with Google" フォーム action で Google OAuth フローを開始する。
+     */
+    const loginAction = async ({ request }: { request: Request }): Promise<MyGoogleProfile | null> => {
+        const formData = await request.clone().formData()
+        const action = String(formData.get("_action"))
+
+        let user: MyGoogleProfile | null = null
+        switch (action) {
+            case "Sign In with Google":
+                user = await authenticator.authenticate("google", request)
+                break
+            default:
+                user = null
+        }
+        return user
+    }
+
+    /**
+     * Destroys the session and returns the Set-Cookie value (logout primitive).
+     * セッションを破棄して Set-Cookie 値を返す (ログアウトの基本操作)。
+     */
+    const logout = async (request: Request) => {
+        return await storage.logout(request)
+    }
+
+    /**
+     * Logs out and redirects with the destroyed-session cookie attached.
+     * ログアウトし、破棄済みセッション Cookie を付与してリダイレクトする。
+     */
+    const logoutAndRedirect = async (request: Request) => {
+        const cookie = await logout(request)
+        const headers = new Headers()
+        headers.append("Set-Cookie", cookie)
+        return redirect(postLogoutRedirect, { headers })
+    }
+
+    /**
+     * Logout-route loader: performs logout and throws the redirect.
+     * ログアウトルート loader。ログアウトを実行してリダイレクトを throw する。
+     */
+    const logoutLoader = async ({ request }: { request: Request }): Promise<never> => {
+        throw await logoutAndRedirect(request)
+    }
+
+    /**
+     * Google OAuth callback loader: authenticates, saves the session and redirects home.
+     * Google OAuth コールバック loader。認証してセッションを保存し、ホームへリダイレクトする。
+     */
+    const googleCallbackLoader = async ({ request }: { request: Request }): Promise<never> => {
+        try {
+            const googleProfile = await authenticator.authenticate("google", request)
+
+            // 認証ペイロードの構築
+            const authenticationPayload: AuthenticationPayload = {
+                accessToken: googleProfile.accessToken,
+                refreshToken: googleProfile.refreshToken,
+                expirationDateMs: googleProfile.expirationDateMs,
+                provider: googleProfile.provider,
+            }
+
+            // セッション内のユーザ情報 (photo/_json/photos を含まない byte 互換形状)
+            const user: SessionProfile = {
+                id: googleProfile.id,
+                displayName: googleProfile.displayName,
+                name: googleProfile.name,
+                emails: googleProfile.emails,
+                ...authenticationPayload,
+                role: googleProfile.role,
+            }
+
+            // 認証後のユーザ情報をセッションに保存
+            const cookie = await storage.saveSession(request, user)
+
+            // ホームへリダイレクト
+            throw redirect(postLoginRedirect, { headers: { "Set-Cookie": cookie } })
+        } catch (error) {
+            // authenticator.authenticate は認証失敗時に Response か Error を throw する。
+            // access_denied のような OAuth エラーでは Error の可能性があるため、
+            // どちらの場合でもログインページへのリダイレクトが安全 (Response はそのまま再 throw)。
+            if (error instanceof Response) {
+                throw error
+            }
+            logger.error("Authentication error:", error)
+            throw redirect(loginPath)
+        }
+    }
+
+    return { loginLoader, loginAction, logoutLoader, logout, logoutAndRedirect, googleCallbackLoader }
+}

package/src/server/logger.ts

@@ -0,0 +1,14 @@
+/**
+ * @module logger
+ * @description Default console-backed logger used when no logger port is injected.
+ * ロガーポート未注入時に使う console ベースの既定ロガー。
+ */
+import type { LoggerPort } from "./ports"
+
+/** console ベースの既定ロガー (ライブラリ既定のフォールバックとして意図的に console を使用)。 */
+export const defaultLogger: LoggerPort = {
+    // biome-ignore lint/suspicious/noConsole: ロガー未注入時の意図的な console フォールバック
+    info: (...args: unknown[]) => console.info("[Auth]", ...args),
+    warn: (...args: unknown[]) => console.warn("[Auth]", ...args),
+    error: (...args: unknown[]) => console.error("[Auth]", ...args),
+}

package/src/server/ports.ts

@@ -0,0 +1,89 @@
+/**
+ * @module ports
+ * @description DI port types for the React Router auth adapter.
+ * React Router 認証アダプタの DI ポート型定義。
+ *
+ * アプリ固有の結合 (env・backend HTTP・DB 由来の写真解決・DB ウォームアップ・テストバックドア) は
+ * すべてここで定義するポートとして注入する。パッケージ内には汎用ロジックだけを置く。
+ */
+import type { AuthMessages, SessionProfile } from "@aiquants/auth-core"
+
+/** OAuth Google の資格情報とオプション (scopes はアプリ注入 — sanledge が拡張)。 */
+export type GoogleOAuthConfig = {
+    clientId: string
+    clientSecret: string
+    redirectURI: string
+    /** 追加スコープ (既定は openid profile email)。 */
+    scopes?: string[]
+    accessType?: "online" | "offline"
+    includeGrantedScopes?: boolean
+    prompt?: "none" | "consent" | "select_account"
+}
+
+/** セッション cookie 設定 (既定は __session/lax/30 日)。secrets のみ必須。 */
+export type SessionConfig = {
+    secrets: string[]
+    /** cookie 名。既定 "__session" (変更すると全ライブセッションが無効化されるため既定を推奨)。 */
+    cookieName?: string
+    /** 有効期間 (秒)。既定 60*60*24*30。 */
+    maxAge?: number
+    /** Secure 属性。既定は NODE_ENV === "production"。 */
+    secure?: boolean
+    /** セッション内のユーザーキー。既定 "user"。 */
+    sessionKey?: string
+}
+
+/** バックエンド (FastAPI) 認証ポート。verify → allowlist → signup の順で呼ばれる。 */
+export type BackendAuthPort = {
+    /** GET /openid/verify 相当。ok なら true。 */
+    verify: (provider: string, accessToken: string) => Promise<boolean>
+    /** POST /openid/signup?overwrite_existing=true 相当 (毎ログイン実行)。 */
+    signup: (provider: string, accessToken: string) => Promise<unknown>
+}
+
+/** ユーザー写真解決ポート (drizzle TDOpenid 等はアプリ側)。キャッシュ + dedup はパッケージ内。 */
+export type UserPhotoPort = (openid: string) => Promise<string>
+
+/** 毎リクエストの DB 接続ウォームアップ (quants は 2 プール、sanledge は 1 プール)。 */
+export type WarmupPort = () => Promise<void>
+
+/** テストバックドア (quants は mock_user_id パース + 名前マップ、sanledge は固定 id)。 */
+export type MockUserPort = {
+    /** このリクエストでバックドアを使うか (NODE_ENV/cookie の判定はアプリ側)。 */
+    enabled: (request: Request) => boolean
+    /** バックドア時に返すセッションプロファイル。 */
+    resolve: (request: Request) => SessionProfile
+}
+
+/** ロガーポート (既定は console)。 */
+export type LoggerPort = {
+    info: (...args: unknown[]) => void
+    warn: (...args: unknown[]) => void
+    error: (...args: unknown[]) => void
+}
+
+/** 認証サーバーの集約設定。 */
+export type AuthServerConfig = {
+    google: GoogleOAuthConfig
+    session: SessionConfig
+    /** allowlist 判定 (auth-core の emailDomainAllowlist を推奨)。 */
+    isEmailAllowed: (email: string | null | undefined) => boolean
+    /** バックエンド verify/signup。省略時はスキップ (フロント単独運用)。 */
+    backendAuth?: BackendAuthPort
+    /** ユーザー写真解決。省略時は常に空文字。 */
+    getUserPhoto?: UserPhotoPort
+    /** 毎リクエストのウォームアップ。省略時は何もしない。 */
+    warmup?: WarmupPort
+    /** テストバックドア。省略時は無効 (本番安全側)。 */
+    mockUser?: MockUserPort
+    /** ログインページのパス。既定 "/auth/login"。 */
+    loginPath?: string
+    /** ログイン成功後のリダイレクト先。既定 "/"。 */
+    postLoginRedirect?: string
+    /** ログアウト後のリダイレクト先。既定 "/"。 */
+    postLogoutRedirect?: string
+    /** エラーメッセージ上書き (既定は日本語の原本文言)。 */
+    messages?: Partial<AuthMessages>
+    /** ロガー (既定 console)。 */
+    logger?: LoggerPort
+}

package/src/server/session.spec.ts

@@ -0,0 +1,113 @@
+/**
+ * Tests for the session storage factory (cookie shape, backdoor port, guards).
+ * セッションストレージファクトリのテスト (cookie 形状・バックドアポート・ガード)。
+ */
+import type { SessionProfile } from "@aiquants/auth-core"
+import { describe, expect, it } from "vitest"
+import type { MockUserPort } from "./ports"
+import { createAuthSessionStorage } from "./session"
+
+const SECRET = "test-secret"
+
+const profile: SessionProfile = {
+    id: "107791905418691074770",
+    displayName: "宏治",
+    name: { familyName: "Mock", givenName: "User" },
+    emails: [{ value: "mock@example.com" }],
+    accessToken: "at",
+    refreshToken: "rt",
+    expirationDateMs: 1750000000000,
+    provider: "google",
+}
+
+const request = (cookie?: string) => new Request("http://localhost/", cookie ? { headers: { Cookie: cookie } } : undefined)
+
+describe("createAuthSessionStorage", () => {
+    it("throws when secrets are missing (fail-closed)", () => {
+        expect(() => createAuthSessionStorage({ secrets: [] })).toThrow("REMIX_SESSION_SECRET must be set")
+        expect(() => createAuthSessionStorage({ secrets: [""] })).toThrow("REMIX_SESSION_SECRET must be set")
+    })
+
+    it("commits a byte-compatible __session cookie (httpOnly/lax/30d)", async () => {
+        const storage = createAuthSessionStorage({ secrets: [SECRET] })
+        const cookie = await storage.saveSession(request(), profile)
+
+        expect(cookie.startsWith("__session=")).toBe(true)
+        expect(cookie).toContain("HttpOnly")
+        expect(cookie).toContain("SameSite=Lax")
+        expect(cookie).toContain(`Max-Age=${60 * 60 * 24 * 30}`)
+        expect(cookie).toContain("Path=/")
+    })
+
+    it("roundtrips the session user under the 'user' key without extra fields", async () => {
+        const storage = createAuthSessionStorage({ secrets: [SECRET] })
+        const cookie = await storage.saveSession(request(), profile)
+        const user = await storage.getSessionUser(request(cookie))
+
+        expect(user).toEqual(profile)
+        // photo/_json/photos を含まない byte 互換形状
+        expect(user && "photo" in user).toBe(false)
+    })
+
+    it("returns undefined without a session cookie", async () => {
+        const storage = createAuthSessionStorage({ secrets: [SECRET] })
+        expect(await storage.getSessionUser(request())).toBeUndefined()
+    })
+
+    it("uses the injected mockUser port when enabled", async () => {
+        const mockUser: MockUserPort = {
+            enabled: (req) => req.headers.get("Cookie")?.includes("mock_user=true") ?? false,
+            resolve: () => ({ ...profile, displayName: "太郎" }),
+        }
+        const storage = createAuthSessionStorage({ secrets: [SECRET] }, { mockUser })
+
+        const mocked = await storage.getSessionUser(request("mock_user=true"))
+        expect(mocked?.displayName).toBe("太郎")
+        // バックドア条件を満たさないリクエストは通常経路 (cookie 無し → undefined)
+        expect(await storage.getSessionUser(request())).toBeUndefined()
+    })
+
+    it("is backdoor-disabled by default (no port injected)", async () => {
+        const storage = createAuthSessionStorage({ secrets: [SECRET] })
+        expect(await storage.getSessionUser(request("mock_user=true; mock_user_id=8"))).toBeUndefined()
+    })
+
+    it("requireUser redirects to the login path when unauthenticated", async () => {
+        const storage = createAuthSessionStorage({ secrets: [SECRET] })
+        try {
+            await storage.requireUser(request())
+            expect.unreachable("should have thrown a redirect")
+        } catch (error) {
+            expect(error).toBeInstanceOf(Response)
+            expect((error as Response).headers.get("Location")).toBe("/auth/login")
+        }
+    })
+
+    it("requireAdminUser redirects non-admin users to the root", async () => {
+        const storage = createAuthSessionStorage({ secrets: [SECRET] })
+        const cookie = await storage.saveSession(request(), profile)
+        try {
+            await storage.requireAdminUser(request(cookie))
+            expect.unreachable("should have thrown a redirect")
+        } catch (error) {
+            expect(error).toBeInstanceOf(Response)
+            expect((error as Response).headers.get("Location")).toBe("/")
+        }
+    })
+
+    it("requireAdminUser passes admin users through", async () => {
+        const storage = createAuthSessionStorage({ secrets: [SECRET] })
+        const cookie = await storage.saveSession(request(), { ...profile, role: "admin" })
+        const user = await storage.requireAdminUser(request(cookie))
+        expect(user.role).toBe("admin")
+    })
+
+    it("logout destroys the session cookie", async () => {
+        const storage = createAuthSessionStorage({ secrets: [SECRET] })
+        const cookie = await storage.saveSession(request(), profile)
+        const destroyed = await storage.logout(request(cookie))
+        // 破棄 cookie は即時失効する
+        expect(destroyed).toContain("__session=")
+        expect(destroyed).toContain("Expires=Thu, 01 Jan 1970")
+    })
+})

package/src/server/session.ts

@@ -0,0 +1,127 @@
+/**
+ * @module session
+ * @description Cookie session storage factory with a DI test backdoor.
+ * DI テストバックドア付きの cookie セッションストレージファクトリ。
+ *
+ * 原本 (quants-react-router session.server.ts) を挙動保存で移植。相違点は
+ * (1) module-level の env throw をファクトリ引数検証へ移した、
+ * (2) テストバックドア (mock_user cookie) をハードコードから `mockUser` ポート注入に変えた、
+ * の 2 点のみ。cookie 形状 (`__session`/httpOnly/lax/30d、キー "user") は byte 互換。
+ */
+import type { SessionProfile } from "@aiquants/auth-core"
+import { createCookieSessionStorage, redirect } from "react-router"
+import type { MockUserPort, SessionConfig } from "./ports"
+
+/** createAuthSessionStorage が返すセッション操作束。 */
+export type AuthSessionStorage = ReturnType<typeof createAuthSessionStorage>
+
+/**
+ * Builds the cookie session storage and session helpers.
+ * cookie セッションストレージとセッションヘルパー群を生成する。
+ *
+ * @throws secrets が空の場合 (fail-closed の設定ガード)。
+ */
+export const createAuthSessionStorage = (config: SessionConfig, options?: { mockUser?: MockUserPort; loginPath?: string; postLoginRedirect?: string }) => {
+    // ファクトリ実行時検証 (import 時副作用の排除)
+    if (!config.secrets || config.secrets.length === 0 || config.secrets.some((s) => !s)) {
+        throw new Error("REMIX_SESSION_SECRET must be set")
+    }
+
+    const sessionKey = config.sessionKey ?? "user"
+    const maxAge = config.maxAge ?? 60 * 60 * 24 * 30
+    const loginPath = options?.loginPath ?? "/auth/login"
+    const postLoginRedirect = options?.postLoginRedirect ?? "/"
+    const mockUser = options?.mockUser
+
+    const sessionStorage = createCookieSessionStorage({
+        cookie: {
+            name: config.cookieName ?? "__session",
+            httpOnly: true, // for security reasons, make this cookie http only
+            path: "/", // remember to add this so the cookie will work in all routes
+            sameSite: "lax", // this helps with CSRF
+            secrets: config.secrets,
+            secure: config.secure ?? process.env.NODE_ENV === "production",
+            maxAge,
+        },
+    })
+
+    /**
+     * Reads the session from the request cookie.
+     * リクエストの Cookie からセッションを取得する。
+     */
+    const getSession = async (request: Request) => {
+        return await sessionStorage.getSession(request.headers.get("Cookie"))
+    }
+
+    /**
+     * Reads the session user, honoring the injected test backdoor when enabled.
+     * セッションからユーザー情報を取得する (注入されたテストバックドアが有効ならそれを返す)。
+     */
+    const getSessionUser = async (request: Request): Promise<SessionProfile | undefined> => {
+        // テストバックドア (ポート注入時のみ有効。判定条件はアプリ側の enabled に委譲)
+        if (mockUser?.enabled(request)) {
+            return mockUser.resolve(request)
+        }
+
+        const session = await getSession(request)
+        const user = session.get(sessionKey) as SessionProfile | undefined
+        return user
+    }
+
+    /**
+     * Saves the user into the session and returns the Set-Cookie value.
+     * セッションへユーザー情報を保存し、Set-Cookie 値を返す。
+     */
+    const saveSession = async (request: Request, user: SessionProfile) => {
+        const session = await getSession(request)
+        session.set(sessionKey, user)
+        return await sessionStorage.commitSession(session)
+    }
+
+    /**
+     * Authenticated-user guard: redirects to the login page when absent.
+     * 認証ユーザーガード。未認証ならログインページへリダイレクトする。
+     */
+    const requireUser = async (request: Request) => {
+        const sessionUser = await getSessionUser(request)
+        if (sessionUser === undefined) {
+            throw redirect(loginPath)
+        }
+        return sessionUser as SessionProfile
+    }
+
+    /**
+     * Admin-user guard: redirects to the app root when the role is not "admin".
+     * 管理者ユーザーガード。role が "admin" でなければルートへリダイレクトする。
+     */
+    const requireAdminUser = async (request: Request) => {
+        const sessionUser = await requireUser(request)
+        if (sessionUser?.role !== "admin") {
+            throw redirect(postLoginRedirect)
+        }
+        return sessionUser
+    }
+
+    /**
+     * Destroys the session and returns the Set-Cookie value (logout primitive).
+     * セッションを破棄して Set-Cookie 値を返す (ログアウトの基本操作)。
+     */
+    const logout = async (request: Request) => {
+        const session = await getSession(request)
+        const cookie = await sessionStorage.destroySession(session)
+        return cookie
+    }
+
+    return {
+        sessionStorage,
+        sessionKey,
+        getSession,
+        getSessionUser,
+        saveSession,
+        requireUser,
+        requireAdminUser,
+        logout,
+        commitSession: sessionStorage.commitSession,
+        destroySession: sessionStorage.destroySession,
+    }
+}

package/src/server.ts

@@ -0,0 +1,14 @@
+/**
+ * @aiquants/auth-react-router/server — server-side auth adapter barrel.
+ * サーバーサイド認証アダプタのバレル。
+ */
+
+export type { AuthServer } from "./server/auth-server"
+export { createAuthServer } from "./server/auth-server"
+export { createAuthenticate, GoogleInvalidGrantError, TokenRefreshError } from "./server/authenticate"
+export { createAuthenticateInLoader } from "./server/authenticate-in-loader"
+export { createGoogleAuthenticator } from "./server/google-strategy"
+export { createAuthHandlers } from "./server/handlers"
+export type { AuthServerConfig, BackendAuthPort, GoogleOAuthConfig, LoggerPort, MockUserPort, SessionConfig, UserPhotoPort, WarmupPort } from "./server/ports"
+export type { AuthSessionStorage } from "./server/session"
+export { createAuthSessionStorage } from "./server/session"