WebEntity: verify()

クライアントから送信されたリクエストを検証します。

この関数は非同期関数です。

構文

webEntity.verify({ method, path, body, headers, query }) => Promise<object>

引数

• request: object

  クライアントから送信されたリクエストの内容を表すオブジェクトです。

  • method: "GET" | "HEAD" | "POST" | "PUT" | "DELETE" | "OPTIONS" | "PATCH"

    リクエストされた HTTP メソッド名です。

  • path: string

    リクエストされたパスです。

  • body: string | Buffer | { [key: string]: string | Uint8Array }

    リクエストのボディです。

  • headers: { [header_name: string]: object }

    リクエストのヘッダをまとめたオブジェクトです。各プロパティは次のようになっています：

    • headers[header_name: string]: { value: string, params: ({ [param_name: string]: string })? }[]

      リクエストのあるヘッダ名 header_name のヘッダ情報を表すオブジェクトです。

      ヘッダの構文はヘッダ毎に異なりますが、同名のヘッダ行を複数行定義したり、単一のヘッダ行で複数の値を持つことがあります。そのため、各ヘッダ名に対してそのヘッダの値を表すオブジェクトの配列が対応付けられています。

      ヘッダに副次的なパラメタがあれば params に設定されます。なければ params は null です。

  • query: { [param_name: string]: any }

    リクエストのクエリパラメタです。

返値: Promise<object>

リクエストの検証結果を表すオブジェクトです。

オブジェクトの内容は認証結果および認証スキームに依存し、それぞれ異なる型のオブジェクトが返却される可能性があります。Promise が内包する値は以下のいずれかのプロパティを持ちます:

• Promise<({ ok })>
• Promise<({ ok, scheme, status, reason })>

各プロパティは次の意味を持ちます:

• ok: boolean

  Web 認証に成功したかどうかです。true なら Web 認証に成功したことを表し、false は認証に失敗したことを表します。

• scheme: string

  Web 認証に「失敗した」プロトコルのスキーム名です。

• status: number?

  Web 認証に「失敗した」ことを通知する HTTP ステータスコードです。通常は以下のいずれかが設定されます：

  • 400 Bad Request
  • 401 Unauthorized
  • 403 Forbidden

• reason: ({ [param_name: string]: string | number | boolean | null })?

  「失敗した」Web 認証の詳細を記述したオブジェクトです。

  詳細は認証スキームによって異なるが、例えば Bearer スキームであれば reason は以下のプロパティを持ちます：

  • error: string

    エラーコードを表す文字列です。

    IETF RFC 6750, 3.1 によれば、以下のいずれかの値が設定されます：

    • "invalid_request" 400 Bad Request に相当する。
    • "invalid_token" 401 Unauthorized に相当する。
    • "insufficient_scope" 403 Forbidden に相当する。

  • error_description: string

    人間可読な認証エラーの説明。

scheme、status、reason は認証失敗時のみ設定されるプロパティです。ok が false であっても必ずしも scheme などの他のプロパティが設定されるとは限りません。

例えばリクエストが Authorization ヘッダを持たなかった場合や Authorization ヘッダが指定するスキームを、対象の WebEntity が提供していなかった場合などでは scheme は設定されません。

また status と reason は特定のスキームの検証失敗に対して与えられるプロパティであり、これらのプロパティが設定されている際には常に scheme プロパティも設定されているはずです。

解説

リクエストの Authorization ヘッダの値を検証し、対応するスキームの認証プロトコルが提供されていれば、そのプロトコルが実装する AbstractAuthProtocol::verify() を呼び出します。

返値には対象の AbstractAuthProtocol::verify() の返値が使用されます。

もし対象の WebEntity が認証プロトコルを要求しない場合、この関数は常に Promise<({ ok: true })> を返します。

もしリクエストが Authorization ヘッダを持たなかった場合、この関数は常に Promise<({ ok: false })> を返します。

もしリクエストの Authorization ヘッダが指示する認証スキームを対象の WebEntity が提供していなかった場合、この関数は常に Promise<({ ok: false })> を返します。