@plott/webkit-auth-oauth0.4.0

@plott/webkit-auth 의 AuthBackend 구현입니다. OAuth 2.0/OIDC 클라이언트(Authorization Code + PKCE)로 제공자(IdP)에 로그인하고, 발급자에 따라 토큰을 세션으로 만듭니다. 서버에서 받은 Bearer 토큰을 검증하는 /bearer 진입점도 있습니다.

모든 로그인 수단(브라우저 로그인, 인증 코드, 매직 링크, 비밀번호, 네이티브 소셜 토큰, WebView 핸드오프)은 «토큰 응답 → 세션» 하나로 모입니다. 업스트림 호출은 언제나 Authorization: Bearer <세션 액세스 토큰> 하나입니다. redirect_uri·state·트랜잭션 쿠키·동시 갱신 합치기는 코어(@plott/webkit-auth)가 하고, 이 패키지는 다시 만들지 않습니다.

진입점

붙이기

서비스의 Authorization Server(AS)가 세션 토큰을 줍니다. 소셜 토큰·인증 코드·WebView 토큰을 모두 AS 토큰으로 바꿉니다.

import { authorizationServer, oauth, type OAuthProvider } from "@plott/webkit-auth-oauth";
declare const issuer: string;declare const tokenEndpoint: string;declare const revocationEndpoint: string;declare const verificationEndpoint: string;declare const verificationGrantType: string;declare const clientId: string;declare const clientSecret: string;declare const providers: OAuthProvider[];
export const backend = oauth({  issuer: authorizationServer({ issuer, tokenEndpoint, revocationEndpoint, verificationEndpoint, verificationGrantType, clientId, clientSecret }),  providers,});

IdP 가 준 토큰을 그대로 세션 토큰으로 쓰려면(사내 SSO) 제공자가 발급자입니다.

import { oauth, providerIssuer } from "@plott/webkit-auth-oauth";import { keycloak } from "@plott/webkit-auth-provider-keycloak";
declare const clientId: string;
export const backend = oauth({  issuer: providerIssuer("keycloak"),  providers: [keycloak({ issuer: "https://sso.example.com/realms/<realm>", clientId })],});

oauth() 는 발급자가 할 수 있는 기능만 싣습니다. 교환(exchange)은 AuthBackend 에, 인증 코드는 verification 포트(verificationEndpoint 가 있을 때), 비밀번호는 password 포트(passwordEndpoint 가 있을 때)에 실립니다. 앱은 defaultMethods(backend) 로 포트가 있는 수단만 켭니다. 없는 기능은 라우트(404)와 proxy 단계가 꺼집니다.

oauth(opts) 의 defaultExpiresIn(기본 300)은 토큰 응답에 expires_in 이 없을 때 쓰는 수명(초)입니다. 양의 유한한 숫자가 아니면 시작할 때 멈춥니다.

• 교환(exchange): 우리 AS 가 발급자일 때만
• 인증 코드 확인·발송(verification 포트의 verificationComplete·verificationStart): verificationEndpoint 가 있을 때
• 비밀번호(password 포트의 passwordLogin): passwordEndpoint 가 있을 때(비밀번호 로그인은 인증 코드 그랜트로 마칩니다)

발급자

authorizationServer 옵션:

제공자

정해진 IdP 는 @plott/webkit-auth-provider-* 패키지를 씁니다. 목록에 없는 IdP 는 직접 정의합니다.

import { oauth2Provider, oidcProvider } from "@plott/webkit-auth-oauth";
declare const clientId: string;declare const clientSecret: string;
export const line = oidcProvider({ id: "line", issuer: "https://access.line.me", clientId, clientSecret, scope: "openid profile" });

백엔드 옵션

받은 Bearer 토큰 검증(/bearer)

내 서버가 Authorization: Bearer <JWT> 를 받아 «이 토큰이 우리 발급자가 이 API 용으로 준 것인가»를 확인합니다. 서버 전용입니다.

import { createBearerVerifier } from "@plott/webkit-auth-oauth/bearer";
const bearer = createBearerVerifier({  issuer: "https://sso.example.com/realms/<realm>",  authorizedParty: "my-api",});
export async function GET(req: Request) {  const who = await bearer.verify(req);  if (!who) return new Response(null, { status: 401 });  return Response.json({ sub: who.sub });}

verify 는 토큰 문자열·Authorization 헤더 값·Headers·headers 를 가진 요청을 받아 주체 또는 null 을 돌려줍니다. verifyOrThrow 는 거절 때 BearerError(코어 AuthError, 상태 401, 코드 invalid_token)를 던지며, error.reason 에 이유 코드(missing·malformed·algorithm·type·invalid_signature·expired·not_yet_valid·issuer·audience·authorized_party·scope·email_unverified·email_domain·claims·jwks_unavailable)가 있고 토큰은 어디에도 없습니다.

기본으로 지키는 것

그 밖

의존성: openid-client, jose. peer: @plott/webkit-auth. 각 항목의 동작은 test/ 의 양성·음성 테스트가 기록합니다.