「動いた」と「適合した」を分ける

一つのBrowserでCode Flowが成功しても、OAuth/OIDC全体への適合を証明したことにはなりません。本書は検証結果を次のlayerへ分けます。

unit: PKCE、state consume、OIDC hash、暗号envelope
HTTP integration: endpoint status、error、header、scope
DB integration: one-time、rotation、side effect
Browser E2E: redirect、Cookie境界、Consent UI
provider source: Better Auth 1.7.1のcall path
conformance suite: 選択profileの外部test

「OIDC certified」という表現は、OpenID Foundationの正式なcertificationを取得し公開した場合だけ使います。selected conformance testを通した結果をcertification claimへ言い換えません。

sourceを再現可能にする

upstream-sources.jsonには次を保存します。

{
  "repository": "https://github.com/better-auth/better-auth",
  "tag": "v1.7.1",
  "commit": "2344536054f9164ca5d1670c270d299049ee233e",
  "files": {
    "packages/oauth-provider/src/token.ts": "sha256:..."
  }
}

tagの移動を想定せず、commitとfile hashを合わせます。Bookの説明を新versionへ更新する場合、source差分、schema差分、discovery差分、test結果を一緒に更新します。

protocol matrixを保つ

SPEC_MATRIX.mdは各機能を、公開済み仕様、OAuth 2.1 draftとの関係、ラボ証拠へ分けます。

例としてPKCEなら、normative sourceはRFC 7636とRFC 9700、OAuth 2.1 draftではbaseline、lab evidenceはwrong verifierとCode replay E2Eです。さらにverifier不一致がRFC 7636のinvalid_grantではなくBetter Auth 1.7.1で401 invalid_requestになる差分も記録します。Better Authのoption名だけを根拠欄へ書きません。

継続test checklist

release前に少なくとも次を自動化します。

discoveryのissuerとendpointがpublic originに一致
Redirect URIがexact match以外を拒否
state、iss、nonce mismatchを拒否
PKCEはS256のみ
Codeは一回限り
Refresh Token rotationとreuse failure
resource audienceとscope不足を拒否
Client Credentialsにuser権限が混ざらない
Device polling intervalとexpiry
ID Token signature、audience、at_hash
DPoP htu、htm、ath、jti replay
Token/Cookie/secretがlogやartifactへない

観測性の設計

requestにはrandom trace IDを付け、Client → AS → RSを相関できるようにします。保存するのはendpoint分類、Client ID、grant type、結果、error code、durationです。

保存しないものはAuthorization header、Cookie、Code、verifier、assertion JWT、Token生値、passwordです。Tokenを区別する必要があるlocal labではSHA-256 fingerprintを使いますが、本番telemetryへ同じ設定を無条件に持ち込みません。

最終的な判断表

このBookの実装を別productへ移す前に、次へ答えます。

AS、Client、RS、BFFのownerは誰か
user delegationとservice authorizationを分けたか
Token formatとrevocation要求は合っているか
BrowserにTokenを持たせる理由があるか
Client registrationとsecret/key rotationの運用者は誰か
failureをHTTPだけでなくDB side effectまで確認したか
draft、RFC、library behavior、lab observationを区別したか