認証

auth は、各操作の security の指定に基づいて認証を行うミドルウェアです。利用者が用意するのは、それぞれの資格情報を取得する方法だけです。

import { auth, createClient } from "./api.ts";

const api = createClient({
  middleware: [
    auth({
      // キーには components.securitySchemes のスキーム名を使う。
      bearer: (scopes) => getToken(scopes),
      // 未設定の変数は、それを使う選択肢を飛ばす。
      apiKey: process.env.API_KEY,
    }),
  ],
});

資格情報の選択

キーには components.securitySchemes の名前（型は SecuritySchemeName）を指定します。値はそれぞれ Credential 型（文字列、または文字列を返す関数。関数は非同期でも可）または undefined です。関数はリクエストごとに、セキュリティ要件に列挙された値（スコープ。OAuth 2.0 と OpenID Connect 以外のスキームではロール名）とミドルウェアのコンテキストを引数として呼び出されます。値または関数の戻り値が undefined か "" のときは、その資格情報は利用できないものとして扱われます。

auth はリクエストごとに、操作の security に並ぶ選択肢のうち、必要な資格情報がすべてそろっている最初の選択肢を採用します。リクエストに何も追加しない選択肢（空の要件 {}、または mutualTLS だけの選択肢）は、ほかに利用可能な選択肢がないときに限って使われます。どの選択肢も利用できないときは、資格情報を付けずにリクエストを送信し、受け付けるかどうかはサーバーが判断します。

資格情報の送信方法

セキュリティスキーム	送信形式
http（bearer）、oauth2、openIdConnect	Authorization: Bearer <credential>
http（basic）	Authorization: Basic <credential, base64-encoded>（資格情報は user:password 形式）
その他の http スキーム	Authorization: <scheme> <credential>
apiKey（ヘッダー）	指定された名前のヘッダー
apiKey（クエリーまたはクッキー）	指定された名前のクエリーパラメーターまたはクッキー（パーセントエンコード済み）
mutualTLS	なし（fetch の実装側で TLS を設定）

ブラウザーは fetch で設定された Cookie ヘッダーを無視するため、クッキーで送信する API キーは Node.js と Bun でのみ機能します。

資格情報が送信されないとき

auth は OpenAPI ドキュメントの security だけに従うため、security: [] が指定された操作には資格情報を送信しません。また、ドキュメントで securitySchemes が宣言されていても security 要件が宣言されていないときは、どの操作にも資格情報を送信しません。ドキュメントの記述にかかわらず、すべてのリクエストにヘッダーを付与して送信するには、代わりにクライアントの headers オプションを使用してください。