/** * 원격 /mcp 를 OAuth 2.1 리소스 서버로 만드는 토큰 검증 계층. * * 인가 서버(internal-api `Oauth::*`)가 발급하는 access token 은 서명 토큰이 아니라 * `SecureRandom.urlsafe_base64(48)` 불투명 문자열이고, DB 에는 SHA256 다이제스트만 남는다 * (`OauthAccessGrant`). 그래서 JWKS 로컬 검증이 성립하지 않는다 — 인가 서버에 물어보는 * introspection 만이 유일한 검증 경로다. * * ⚠️ 선행 필요: 인가 서버에 아래 엔드포인트가 있어야 이 모듈이 실제로 통과시킬 수 있다. * 현재 internal-api 에는 `OauthAccessGrant.authenticate` 모델 메서드만 있고 HTTP 로 노출된 * introspection 은 없다. 계약은 아래 IntrospectionResponse 주석 참조. * * Cloudflare Workers 런타임 — node:crypto 를 쓰지 않는다. */ export type TokenRejectReason = 'missing_token' | 'invalid_token' | 'insufficient_scope' | 'server_error'; export interface VerifiedToken { /** 원문 access token — 로그·응답에 절대 싣지 않는다 */ token: string; scopes: string[]; clientId?: string; project?: { appId: string; name: string; providerName: string; } | null; /** * internal-api 호출에 쓸 관리자 세션 토큰. * internal-api 의 `alive!` 는 JWT 세션만 받으므로, OAuth access token 을 그대로 보내면 통과하지 못한다. * introspection 응답이 이 값을 내려줘야 admin 도구가 동작한다. */ sessionToken: string; } export interface TokenRejection { reason: TokenRejectReason; /** WWW-Authenticate 의 error 파라미터로 나갈 값 */ error: string; /** 사용자에게 보여줄 설명 — 내부 구현(키 ID, 검증 단계)을 드러내지 않는다 */ description: string; status: 401 | 403; requiredScope?: string; } export type TokenVerification = { ok: true; value: VerifiedToken; } | { ok: false; rejection: TokenRejection; }; /** * 인가 서버 introspection 응답 계약 (RFC 7662 기반 + 부트페이 확장). * * ``` * POST {authorizationServer}/oauth/introspect * Content-Type: application/x-www-form-urlencoded * token= * resource=<이 MCP 서버의 resource identifier> * * → 200 { * "active": true, * "scope": "project.product.read project.product.write", * "aud": "https://mcp.bootpay.ai/mcp", * "exp": 1790000000, * "client_id": "...", * "project": { "app_id": "...", "name": "...", "seller": "..." }, * "session_token": "" * } * → 200 { "active": false } // 만료·위조·폐기 — 이유를 구분해 알려주지 않는다 * ``` */ export interface IntrospectionResponse { active: boolean; scope?: string; aud?: string | string[]; exp?: number; client_id?: string; project?: { app_id?: string; name?: string; seller?: string; } | null; session_token?: string; } export interface TokenVerifierOptions { /** 인가 서버 origin. 예: https://internal.bootapi.com */ authorizationServer: string; /** 이 MCP 서버의 resource identifier (RFC 8707). audience 대조 기준. */ resource: string; /** 기본 요구 스코프 */ requiredScopes?: string[]; timeoutMs?: number; /** 테스트·대체 구현 주입용 */ fetchImpl?: typeof fetch; } /** `Authorization: Bearer xxx` 에서 토큰만 꺼낸다. 형식이 다르면 null. */ export declare function extractBearerToken(authorization: string | null | undefined): string | null; export declare class TokenVerifier { private readonly options; constructor(options: TokenVerifierOptions); get resource(): string; verify(authorization: string | null | undefined, requiredScopes?: string[]): Promise; private introspect; } /** 401/403 응답에 붙일 WWW-Authenticate 헤더 값 */ export declare function buildWwwAuthenticate(rejection: TokenRejection, resourceMetadataUrl: string): string; /** RFC 9728 보호 리소스 메타데이터 문서 */ export declare function protectedResourceMetadata(opts: { resource: string; authorizationServers: string[]; scopesSupported: string[]; documentationUrl?: string; }): Record; //# sourceMappingURL=token-verify.d.ts.map