@plott/webkit-auth0.4.0

Next.js(App Router) 인증 코어입니다. 세션 쿠키·proxy 토큰 갱신·인증 라우트·BFF·브라우저 로그인(리다이렉트·팝업·네이티브 브릿지·비밀번호)과, @plott/webkit-api 클라이언트에 끼우는 인증 플러그인(auth.bearer())을 맡습니다. 세션 저장 방식과 토큰 발급자는 구현 패키지를 끼워 정합니다 — 보통 @plott/webkit-auth-session-cookie 와 @plott/webkit-auth-oauth.

서드파티 런타임 의존성이 없습니다. peer: @plott/webkit-api, next >=16.4.1 <17(16.4.1 아래는 보안 패치가 빠진 버전 — GHSA-673q-mjm6-r5xr 등), react ^19.3.

진입점

설정(AuthConfig)

브라우저가 버리는 쿠키 조합(__Host- + Domain, http + __Secure-, 오리진을 덮지 않는 Domain)과 겹치는 수단 라우트는 시작할 때 멈춥니다. 운영(NODE_ENV=production)에서 origin 을 비우면 시작할 때 경고합니다.

업스트림 주소·로케일·전달 헤더는 이 설정에 없습니다 — @plott/webkit-api 클라이언트의 설정과 플러그인입니다.

인증 플러그인(auth.bearer())

import { createApiClient } from "@plott/webkit-api";import { requestContext } from "@plott/webkit-api/next";import type { Auth } from "@plott/webkit-auth/server";
declare const auth: Auth;
export const api = createApiClient({ baseUrl: "https://api.example.com", use: [requestContext(), auth.bearer()] });

토큰을 받은 서버는 그 토큰을 다른 서버에 다시 쓸 수 있습니다. 이 세션의 토큰을 받아야 하는 서버(토큰의 aud)의 클라이언트에만 끼우세요.

다른 앱의 세션은 auth.linked(이름).bearer() 입니다. 이 앱의 요청 Bearer 는 넘기지 않고, 401 은 ApiError 그대로입니다(이 앱의 세션을 끝내지 않습니다). 설정에 없는 이름은 «언제나 없음»으로 동작하고 시작할 때 경고합니다.

배치·시스템 호출은 auth.runWithAuthContext({ bearer }, fn) 으로 그 일의 토큰을 주거나, runWithIncoming(값, fn, { mode: "replace" })(@plott/webkit-api/next)로 사용자 요청을 보지 않게 합니다.

인증 라우트

코어: <basePath>/session, providers, refresh(?returnTo=&reason=rejected&proof=), logout(POST).

기본 수단:

verificationCode·passwordLogin 은 VerificationPort·PasswordPort(타입은 @plott/webkit-auth)를 받습니다. 포트가 없으면(undefined) 시작할 때 멈추고, 수단을 켜지 않은 라우트는 404 입니다. webviewHandoff() 는 라우트가 없고 proxy 단계만 있습니다.

로그인 수단 만들기(AuthMethod)

import { NextResponse } from "next/server";import type { AuthMethod } from "@plott/webkit-auth/server";import type { Session } from "@plott/webkit-auth";
declare function myIssuer(body: Record<string, unknown>, current: Session | null): Promise<Session>;
export const hello: AuthMethod = {  id: "hello",  routes: {    hello: {      POST: async (req, kit) => {        kit.requireSameOrigin(req);        const session = await myIssuer(await kit.readJson(req), await kit.readSession(req));        return kit.respondWithSession(req, NextResponse.json({ ok: true }), session);      },    },  },};

createAuth({ ..., methods: [...defaultMethods(), hello] }) 로 켭니다.

kit(RouteKit)은 쿠키 속성·Next basePath·오류 응답 모양을 맞춰 줍니다: readSession, respondWithSession, requireSameOrigin, readJson, jsonError, errorRedirect, loginRedirect, loginOutcome, clientIp, pub·at. proxy 단계는 proxy(req, { cfg, session, headers }) 가 { session, replaced } 를 돌려줍니다.

붙이기

auth.ts 에서 한 번 만들고 proxy.ts·라우트·화면이 같은 auth 를 씁니다.

import { createAuth } from "@plott/webkit-auth/server";import { oauth, type OAuthProvider, type ProviderIssuer } from "@plott/webkit-auth-oauth";import { cookieSession } from "@plott/webkit-auth-session-cookie";
declare const origin: string;declare const secret: string;declare const issuer: ProviderIssuer;declare const providers: OAuthProvider[];
export const auth = createAuth({ origin, sessionStore: cookieSession({ secrets: [secret] }), backend: oauth({ issuer, providers }) });

app/auth/[...auth]/route.ts 는 export const { GET, POST } = auth.handlers, proxy.ts 는 export const proxy = auth.proxy(또는 auth.proxy(req, next))입니다. 서버 컴포넌트·서버 액션은 auth.requireSession({ kind }) 로 세션을 요구하고, 업스트림 호출을 try/catch 로 감싸 auth.handleAuthError(e) 에 넘깁니다. 클라이언트에는 getSessionView() 의 값을 <SessionProvider session={...} basePath> 로 내립니다. basePath 는 브라우저 경로(Next basePath 포함)입니다.

auth.bff({ api, allow }) 는 클라이언트 컴포넌트가 업스트림을 부르는 같은 오리진 통로입니다. 토큰은 서버에서만 붙고, allow(path, method) 가 거짓인 경로는 404 입니다.

포트

오류 코드

?error=<code> 로 오류 페이지에 전달되며 문구는 앱이 정합니다.

기본으로 지키는 것

그 밖

• 서드파티 런타임 의존성이 없습니다. 인증 컨텍스트(getContext)는 runWithAuthContext 로 덮어쓴 값이 있으면 그것이, 없으면 들어온 요청에서 매번 파생한 값이 쓰입니다. 덮어쓴 값이 있을 때는 들어온 요청의 쿠키·Authorization 을 보지 않습니다.
• 쿠키를 여는 일은 한 렌더 안에서 값마다 한 번만 합니다(React cache).
• 앱 WebView 와의 통신(네이티브 로그인 포함)은 @plott/webkit-native 하나가 맡습니다. authClient 는 기본으로 브릿지를 쓰지 않고, authClient({ nativeBridge: asAuthBridge(bridge) }) 로 연결합니다. 메시지 모양은 네이티브 브릿지 계약 에 있습니다.
• 팝업·로그아웃 알림에 쓰는 이름(메시지 종류·채널·창 이름·저장소 키·결과 요소 id)은 모두 접두 webkit-auth 로 시작합니다.
• 증상별 대응은 트러블슈팅에 있습니다.
• 각 항목의 동작은 test/ 의 양성·음성 테스트가 기록합니다.