create-entity-app-server 0.0.3

package/src/app/plugins/oauth/config.ts

@@ -0,0 +1,182 @@
+/**
+ * OAuth 설정 로더 + 프로바이더별 유틸리티
+ *
+ * plugins/oauth/config.json 을 읽어 파싱한다.
+ * Apple client_secret JWT 자동 생성도 담당.
+ */
+
+import jwt from "jsonwebtoken";
+import { env } from "@gateway/api";
+import { serverConfig } from "@gateway/api";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { substituteEnvVars } from "../../../system/config/env-substitution.ts";
+import type { OAuthConfig, OAuthProviderConfig } from "./types/index.ts";
+
+let _cfg: OAuthConfig | null | undefined;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const CONFIG_PATH = join(__dirname, "config.json");
+
+export function getOAuthConfig(): OAuthConfig | null {
+    if (_cfg !== undefined) return _cfg;
+    try {
+        const raw = substituteEnvVars(readFileSync(CONFIG_PATH, "utf-8"));
+        _cfg = JSON.parse(raw) as OAuthConfig;
+        return _cfg;
+    } catch {
+        _cfg = null;
+        return _cfg;
+    }
+}
+
+export function isOAuthEnabled(): boolean {
+    return getOAuthConfig()?.enabled === true;
+}
+
+export function getProvider(name: string): OAuthProviderConfig | undefined {
+    const cfg = getOAuthConfig();
+    if (!cfg?.enabled) return undefined;
+    return cfg.providers.find(
+        (p) => p.driver.toLowerCase() === name.toLowerCase(),
+    );
+}
+
+export function getStateSecret(): string {
+    return getOAuthConfig()?.state_secret || env.JWT_SECRET;
+}
+
+/** 게이트웨이 자체 callback URL — oauth.json 의 redirect_url 을 덮어씀 */
+export function buildCallbackUrl(provider: string): string {
+    const base = (serverConfig.baseUrl ?? "").replace(/\/$/, "");
+    return `${base}/api/v1/oauth/${provider}/callback`;
+}
+
+export function getDefaultScopes(driver: string): string[] {
+    switch (driver) {
+        case "google":
+            return ["openid", "email", "profile"];
+        case "github":
+            return ["read:user", "user:email"];
+        case "naver":
+            return ["name", "email"];
+        case "apple":
+            return ["name", "email"];
+        case "line":
+            return ["openid", "profile", "email"];
+        case "linkedin":
+            return ["openid", "profile", "email"];
+        default:
+            return ["email", "profile"];
+    }
+}
+
+export interface ProviderEndpoints {
+    authUrl: string;
+    tokenUrl: string;
+}
+
+export function getEndpoints(p: OAuthProviderConfig): ProviderEndpoints {
+    const driver = p.driver.toLowerCase();
+    switch (driver) {
+        case "google":
+            return {
+                authUrl:
+                    p.auth_url ||
+                    "https://accounts.google.com/o/oauth2/v2/auth",
+                tokenUrl: p.token_url || "https://oauth2.googleapis.com/token",
+            };
+        case "github":
+            return {
+                authUrl:
+                    p.auth_url || "https://github.com/login/oauth/authorize",
+                tokenUrl:
+                    p.token_url ||
+                    "https://github.com/login/oauth/access_token",
+            };
+        case "naver":
+            return {
+                authUrl:
+                    p.auth_url || "https://nid.naver.com/oauth2.0/authorize",
+                tokenUrl: p.token_url || "https://nid.naver.com/oauth2.0/token",
+            };
+        case "kakao":
+            return {
+                authUrl:
+                    p.auth_url || "https://kauth.kakao.com/oauth/authorize",
+                tokenUrl: p.token_url || "https://kauth.kakao.com/oauth/token",
+            };
+        case "apple":
+            return {
+                authUrl:
+                    p.auth_url || "https://appleid.apple.com/auth/authorize",
+                tokenUrl: p.token_url || "https://appleid.apple.com/auth/token",
+            };
+        case "line":
+            return {
+                authUrl:
+                    p.auth_url ||
+                    "https://access.line.me/oauth2/v2.1/authorize",
+                tokenUrl:
+                    p.token_url || "https://api.line.me/oauth2/v2.1/token",
+            };
+        case "linkedin":
+            return {
+                authUrl:
+                    p.auth_url ||
+                    "https://www.linkedin.com/oauth/v2/authorization",
+                tokenUrl:
+                    p.token_url ||
+                    "https://www.linkedin.com/oauth/v2/accessToken",
+            };
+        default:
+            if (!p.auth_url || !p.token_url) {
+                throw new Error(
+                    `auth_url and token_url are required for custom provider "${p.driver}"`,
+                );
+            }
+            return { authUrl: p.auth_url, tokenUrl: p.token_url };
+    }
+}
+
+/**
+ * Apple Sign-In client_secret JWT (ES256) 자동 생성
+ * jsonwebtoken이 ES256을 지원하므로 PEM 키를 그대로 sign에 전달
+ */
+export function generateAppleClientSecret(p: OAuthProviderConfig): string {
+    if (!p.apple_team_id || !p.apple_key_id || !p.apple_private_key) {
+        throw new Error(
+            "apple_team_id, apple_key_id, apple_private_key are required",
+        );
+    }
+    const now = Math.floor(Date.now() / 1000);
+    return jwt.sign(
+        {
+            iss: p.apple_team_id,
+            iat: now,
+            exp: now + 15_552_000, // 6개월 (Apple 최대)
+            aud: "https://appleid.apple.com",
+            sub: p.client_id,
+        },
+        p.apple_private_key,
+        {
+            algorithm: "ES256",
+            header: { alg: "ES256", kid: p.apple_key_id },
+        } as jwt.SignOptions,
+    );
+}
+
+/** Apple 또는 다른 프로바이더의 실제 client_secret 반환 */
+export function resolveClientSecret(p: OAuthProviderConfig): string {
+    const driver = p.driver.toLowerCase();
+    if (
+        driver === "apple" &&
+        !p.client_secret &&
+        p.apple_team_id &&
+        p.apple_key_id &&
+        p.apple_private_key
+    ) {
+        return generateAppleClientSecret(p);
+    }
+    return p.client_secret;
+}

package/src/app/plugins/oauth/docs/README.md

@@ -0,0 +1,160 @@
+# OAuth 2.0 소셜 로그인 플러그인
+
+Google, GitHub, Naver, Kakao, Apple, Line 소셜 로그인을 지원합니다. PKCE 및 state 기반 CSRF 방어가 내장되어 있습니다.
+
+---
+
+## 목차
+
+- [개요](#개요)
+- [설정](#설정)
+- [환경변수](#환경변수)
+- [API](#api)
+- [로그인 흐름](#로그인-흐름)
+- [운영 팁](#운영-팁)
+
+---
+
+## 개요
+
+| 항목            | 내용                                      |
+| --------------- | ----------------------------------------- |
+| 지원 프로바이더 | Google, GitHub, Naver, Kakao, Apple, Line |
+| CSRF 방어       | state 토큰 (HMAC, TTL 600초)              |
+| PKCE            | Apple, Line 기본 활성화                   |
+| 계정 병합       | 동일 이메일 기존 계정과 자동 연동 가능    |
+
+> 기본 비활성화(`enabled: false`)입니다. 사용할 프로바이더의 OAuth 앱을 등록하고 환경변수를 설정한 후 활성화하세요.
+
+---
+
+## 설정
+
+`config.json` 핵심 구조:
+
+```json
+{
+    "enabled": false,
+    "state_secret": "${OAUTH_STATE_SECRET}",
+    "state_ttl_sec": 600,
+    "success_redirect_url": "${OAUTH_SUCCESS_REDIRECT_URL}",
+    "failure_redirect_url": "${OAUTH_FAILURE_REDIRECT_URL}",
+    "providers": [
+        {
+            "driver": "google",
+            "client_id": "${GOOGLE_CLIENT_ID}",
+            "client_secret": "${GOOGLE_CLIENT_SECRET}",
+            "redirect_url": "/v1/oauth/google/callback",
+            "scopes": ["openid", "email", "profile"]
+        },
+        {
+            "driver": "apple",
+            "client_id": "${APPLE_CLIENT_ID}",
+            "redirect_url": "/v1/oauth/apple/callback",
+            "scopes": ["name", "email"],
+            "pkce": true,
+            "apple_team_id": "${APPLE_TEAM_ID}",
+            "apple_key_id": "${APPLE_KEY_ID}",
+            "apple_private_key": "${APPLE_PRIVATE_KEY}"
+        }
+    ]
+}
+```
+
+### 설정 항목
+
+| 항목                       | 설명                                 |
+| -------------------------- | ------------------------------------ |
+| `state_secret`             | state 토큰 서명 비밀키 (CSRF 방어용) |
+| `state_ttl_sec`            | state 토큰 유효 시간 (기본 600초)    |
+| `success_redirect_url`     | 로그인 성공 후 리다이렉트 URL        |
+| `failure_redirect_url`     | 로그인 실패 후 리다이렉트 URL        |
+| `providers[].driver`       | 프로바이더 식별자                    |
+| `providers[].redirect_url` | 콜백 URL (서버 내부 경로)            |
+| `providers[].scopes`       | 요청할 권한 범위                     |
+| `providers[].pkce`         | PKCE 활성화 (Apple, Line 권장)       |
+
+---
+
+## 환경변수
+
+```env
+OAUTH_STATE_SECRET=랜덤_비밀키_32자_이상
+
+# Google
+GOOGLE_CLIENT_ID=...
+GOOGLE_CLIENT_SECRET=...
+
+# GitHub
+GITHUB_CLIENT_ID=...
+GITHUB_CLIENT_SECRET=...
+
+# Naver
+NAVER_CLIENT_ID=...
+NAVER_CLIENT_SECRET=...
+
+# Kakao
+KAKAO_CLIENT_ID=...
+KAKAO_CLIENT_SECRET=...
+
+# Apple
+APPLE_CLIENT_ID=com.example.app
+APPLE_TEAM_ID=...
+APPLE_KEY_ID=...
+APPLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n..."
+
+# Line
+LINE_CLIENT_ID=...
+LINE_CLIENT_SECRET=...
+
+# 리다이렉트
+OAUTH_SUCCESS_REDIRECT_URL=https://example.com/login/success
+OAUTH_FAILURE_REDIRECT_URL=https://example.com/login/fail
+```
+
+---
+
+## API
+
+### 소셜 로그인
+
+| 메서드 | 경로                               | 설명                                     |
+| ------ | ---------------------------------- | ---------------------------------------- |
+| `GET`  | `/api/v1/oauth/:provider`          | 프로바이더 인증 페이지로 리다이렉트      |
+| `GET`  | `/api/v1/oauth/:provider/callback` | OAuth 콜백 처리 (JWT 발급 후 리다이렉트) |
+| `POST` | `/api/v1/oauth/:provider/callback` | Apple Sign-In 콜백 (POST 형식)           |
+
+`provider` 값: `google`, `github`, `naver`, `kakao`, `apple`, `line`
+
+### 계정 연동 관리
+
+| 메서드   | 경로                                      | 인증     | 설명                      |
+| -------- | ----------------------------------------- | -------- | ------------------------- |
+| `POST`   | `/api/v1/account/oauth/link`              | JWT 필요 | 소셜 계정 추가 연동       |
+| `DELETE` | `/api/v1/account/oauth/link/:provider`    | JWT 필요 | 특정 프로바이더 연동 해제 |
+| `GET`    | `/api/v1/account/oauth/providers`         | JWT 필요 | 연동된 프로바이더 목록    |
+| `POST`   | `/api/v1/account/oauth/refresh/:provider` | JWT 필요 | 소셜 액세스 토큰 갱신     |
+
+---
+
+## 로그인 흐름
+
+```
+1. 클라이언트  → GET /api/v1/oauth/google
+2. 서버        → 302 Redirect → Google 인증 페이지
+3. 사용자 동의
+4. Google      → GET /api/v1/oauth/google/callback?code=...&state=...
+5. 서버        → state 검증 → 코드 교환 → 사용자 정보 조회
+6. 서버        → 계정 생성/조회 → JWT 발급
+7. 서버        → 302 Redirect → success_redirect_url#token=...
+```
+
+---
+
+## 운영 팁
+
+- 각 프로바이더 개발자 콘솔에서 `redirect_url`을 허용 URL로 등록 필수
+- Apple Sign-In은 `https://` 도메인에서만 동작 (로컬호스트 테스트 불가)
+- `OAUTH_STATE_SECRET`은 충분히 긴 랜덤 값 사용 (openssl rand -hex 32)
+- 동일 이메일로 여러 소셜 계정 연동 시 계정 병합 정책을 사전에 결정할 것
+- Kakao는 비즈니스 앱 전환 후 이메일 수집 가능

package/src/app/plugins/oauth/entities/account_oauth.json

@@ -0,0 +1,74 @@
+{
+    "name": "account_oauth",
+    "description": "소셜 로그인 OAuth 프로바이더 연동 정보. 사용자 환경에 맞게 fields를 자유롭게 확장할 수 있습니다.",
+    "history": false,
+    "hard_delete": true,
+    "fields": {
+        "account_seq": {
+            "index": true,
+            "required": true,
+            "comment": "계정 seq"
+        },
+        "provider": {
+            "index": true,
+            "type": [
+                "google",
+                "github",
+                "naver",
+                "kakao",
+                "apple"
+            ],
+            "required": true
+        },
+        "provider_id": {
+            "index": true,
+            "type": "string",
+            "required": true,
+            "comment": "프로바이더 고유 사용자 ID"
+        },
+        "status": {
+            "index": true,
+            "type": [
+                "active",
+                "unlinked"
+            ],
+            "default": "active"
+        },
+        "email": {
+            "type": "email",
+            "comment": "프로바이더에서 제공한 이메일"
+        },
+        "name": {
+            "type": "string",
+            "comment": "프로바이더에서 제공한 이름"
+        },
+        "profile_image": {
+            "type": "string",
+            "comment": "프로필 이미지 URL"
+        },
+        "access_token": {
+            "type": "string",
+            "comment": "OAuth access token (암호화 저장)"
+        },
+        "refresh_token": {
+            "type": "string",
+            "comment": "OAuth refresh token (암호화 저장)"
+        },
+        "token_expires_at": {
+            "type": "string",
+            "comment": "access token 만료 시각 (RFC3339)"
+        },
+        "raw": {
+            "type": "json",
+            "comment": "프로바이더 원본 응답 (디버깅용)"
+        },
+        "linked_at": {
+            "type": "string",
+            "comment": "연결 시각"
+        },
+        "unlinked_at": {
+            "type": "string",
+            "comment": "연결 해제 시각"
+        }
+    }
+}