HonoからBetter Authへ渡す境界

Authorization Serverの外側は小さなHono applicationです。

const app = new Hono()

app.all('/api/auth/*', (c) => auth.handler(c.req.raw))
app.get('/.well-known/*', (c) => auth.handler(c.req.raw))

HonoはNode listener、CORS、trace ID、lab-only inspectorを担当します。OAuth protocolのparameter validation、Client認証、Token発行はauth.handlerの内側へ委ねます。独自endpointでcodeやTokenを作らないことが境界です。

Provider設定を読む

中心になる設定は次の形です。

betterAuth({
  baseURL: 'http://localhost:4100',
  basePath: '/api/auth',
  database: drizzleAdapter(db, { provider: 'pg', schema }),
  plugins: [
    jwt({ jwt: { issuer: AUTH_ISSUER } }),
    oauthProvider({
      loginPage: '/sign-in',
      consentPage: '/consent',
      scopes: SUPPORTED_SCOPES,
      resources: [notesResource],
      allowDynamicClientRegistration: false,
      refreshTokenReuseInterval: 0,
      dpop: { proofMaxAgeSeconds: 300, signingAlgorithms: ['ES256'] }
    }),
    oauthDeviceAuthorization({ verificationUri: '/device' })
  ]
})

baseURLとbasePathを合わせたhttp://localhost:4100/api/authがissuerです。Browser向け画面のoriginではなく、Tokenを発行した主体を一意に示すidentifierとして扱います。

scopesには表示名、説明、riskを持つcatalogを渡します。Consent UIも同じcatalogを読むため、ASが認可語彙のownerになります。Clientが任意の説明文を差し込む構成にはしません。

resourcesはNotes APIのidentifierと許可scopeを結び付けます。enforcePerClientResources: trueにより、Clientをresourceへ明示的にlinkしない限り、そのresource向けTokenを得られません。

ここにはBetter Auth 1.7.1固有の注意があります。allowedScopesはAccess Token用scopeだけでなく、その要求の有効scope全体との交差集合を取ります。同じAuthorization Requestでresourceとopenid profile emailを要求するラボでは、Notes用scopeに加えてOIDC scopeとoffline_accessもallowlistへ含めます。含めないとopenidが有効scopeから脱落し、ID Tokenは発行されません。この挙動はpackages/oauth-provider/src/resources.tsのresolveResourcePolicy()とtoken.tsのeffectiveScopesから確認できます。

pluginの初期化で起きること

Better Auth 1.7.1のoauthProvider()は、plugin schema、endpoint、rate limit、初期化hookを返します。初期化時には設定されたresourceをDBへseedします。本書ではresourceSeedMode: 'overwrite'を選び、設定fileをlocal labの正とします。

これはproductionで常に正解という意味ではありません。管理画面でresourceを更新する運用ならmergeやinsertOnlyを検討します。重要なのは「設定とDBのどちらがownerか」を決めることです。

sourceを読む起点は次です。

packages/oauth-provider/src/oauth.ts: plugin本体とendpoint構成
packages/oauth-provider/src/authorize.ts: 認可要求の処理
packages/oauth-provider/src/token.ts: grantごとのToken発行
packages/oauth-provider/src/resources.ts: resource seedとpolicy
packages/oauth-provider/src/device-code.ts: Device extension

本書のupstream-sources.jsonには、これらを取得したcommit 2344536054f9164ca5d1670c270d299049ee233eと各fileのSHA-256があります。

DBで確認する

schema生成後、次のrecord群が責務ごとに分かれます。

oauth_client: Redirect URI、Grant、Client認証方式、PKCE要求
oauth_resource: audienceと許可scope、署名policy
oauth_client_resource: ClientとResourceの許可関係
oauth_consent: user・client・scopeの承認
oauth_authorization_code: 一時codeとPKCE challenge
oauth_access_token / oauth_refresh_token: 発行済みcredential
jwks: ID TokenやJWT Access Tokenの署名鍵

BrowserへDB内容をそのまま見せるdebug endpointは作りません。OAUTH_LAB_MODE=trueかつloopback requestのときだけ、allowlistしたfieldをredactして返すInspectorを用意します。

failureから設定ミスを見つける

Redirect URIが登録規則に合わなければseed自体がinvalid_redirect_uriで失敗します。未linkのresourceを要求すればinvalid_targetです。未登録scopeならinvalid_scopeです。

この早い失敗は不便ではなく、Client metadataを曖昧なまま運用へ持ち込まないための検証です。次章からは、登録済みPublic ClientがAuthorization endpointへ送るrequestを一項目ずつ組み立てます。