kych

api-kych.rst (21849B)

---

 ..
   This file is part of GNU TALER.
   Copyright (C) 2024, 2025 Taler Systems SA
 
   TALER is free software; you can redistribute it and/or modify it under the
   terms of the GNU Affero General Public License as published by the Free Software
   Foundation; either version 2.1, or (at your option) any later version.
 
   TALER is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License along with
   TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
 
 .. _kych-api:
 
 ===============================
 KyCH OAuth2 Gateway RESTful API
 ===============================
 
 The KyCH OAuth2 Gateway provides OAuth 2.0 authorization using OID4VP
 (OpenID for Verifiable Presentations) with the Swiyu Verifier. It allows
 OAuth 2.0 clients (such as a Taler exchange) to verify user identity via
 SD-JWT Verifiable Credentials stored in the user's Swiyu Wallet.
 
 The high-level flow is:
 
 1. An OAuth 2.0 client is registered with KyCH (via configuration file or CLI tool).
 
 2. When the client needs to verify a user's identity, it calls ``/setup/$CLIENT_ID``
    with its client secret to obtain a ``nonce``.
 
 3. The client redirects the user-agent to ``/authorize/$NONCE`` with OAuth 2.0
    parameters (``response_type``, ``client_id``, ``redirect_uri``, ``state``, ``scope``).
 
 4. KyCH initiates a verification request with the Swiyu Verifier and returns
    a ``verification_url`` (QR code URL) for the user to scan with their Swiyu Wallet.
 
 5. The user scans the QR code and presents their verifiable credential to the
    Swiyu Verifier.
 
 6. Upon successful verification, Swiyu Verifier sends a webhook notification to
    KyCH's ``/notification`` endpoint.
 
 7. The client polls ``/status/$VERIFICATION_ID`` or the user calls
    ``/finalize/$VERIFICATION_ID`` to be redirected back to the client with an
    authorization code.
 
 8. The client exchanges the authorization code for an access token via ``/token``.
 
 9. The client retrieves the verified identity claims via ``/info``.
 
 .. contents:: Table of Contents
   :local:
 
 
 .. _kych-config:
 
 -----------------------
 Receiving Configuration
 -----------------------
 
 .. http:get:: /config
 
   Returns the public configuration of the KyCH service, including supported
   verifiable credential types and available claims. Clients can use this
   endpoint to discover which claims they can request during authorization.
 
   This endpoint does not require authentication and can be used for health
   checks and service discovery.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     The service is operational. Returns a `KyCHConfigResponse` containing
     the service configuration.
 
   .. ts:def:: KyCHConfigResponse
 
     interface KyCHConfigResponse {
       // Service identifier. Always "KyCH OAuth2 Gateway".
       name: "kych-oauth2-gateway";
 
       // Semantic version of the KyCH service (e.g., "1.0.0").
       version: string;
 
       // Health status indicator. "healthy" indicates the service is
       // ready to accept requests.
       status: "healthy";
 
       // Verifiable credential type identifier configured for this
       // KyCH instance. For Swiss Beta ID, this is "betaid-sdjwt".
       vc_type: string;
 
       // Credential format. SD-JWT credentials use "vc+sd-jwt".
       vc_format: string;
 
       // List of cryptographic signature algorithms accepted for
       // credential verification (e.g., ["ES256"]).
       vc_algorithms: string[];
 
       // List of claim names that clients can request via the scope
       // parameter. Only claims in this list are valid scope values.
       // Examples: "family_name", "given_name", "birth_date", "age_over_18".
       vc_claims: string[];
     }
 
 
 .. _kych-setup:
 
 -----
 Setup
 -----
 
 .. http:post:: /setup/$CLIENT_ID
 
   Initiates a new KYC verification session for the specified client. This is
   the first step in the verification flow and must be called by the client
   (e.g., Taler exchange) before redirecting the user to the authorization
   endpoint.
 
   The client authenticates using HTTP Bearer authentication with its client
   secret. Upon success, KyCH creates a new session in ``pending`` status and
   returns a cryptographically random nonce that identifies this session.
 
   **Request:**
 
   :reqheader Authorization: Required. Must be ``Bearer $CLIENT_SECRET`` where
     ``$CLIENT_SECRET`` is the secret registered for this client.
 
   The request body must be empty.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Session created successfully. Returns a `KyCHSetupResponse` containing
     the session nonce.
 
   :http:statuscode:`401 Unauthorized`:
     Authentication failed. Either the ``Authorization`` header is missing,
     malformed, or contains an invalid client secret. The client should verify
     that it is using the correct secret for the specified ``$CLIENT_ID``.
 
   :http:statuscode:`404 Not found`:
     The ``$CLIENT_ID`` in the URL path does not match any registered client.
     The client must be registered via configuration file or CLI before use.
 
   .. ts:def:: KyCHSetupResponse
 
     interface KyCHSetupResponse {
       // Cryptographically random nonce (base64-encoded) that identifies
       // this verification session. The client must include this nonce
       // in the URL when redirecting the user to /authorize/$NONCE.
       // The nonce is single-use and expires after a configured timeout.
       nonce: string;
     }
 
 
 .. _kych-authorize:
 
 ---------
 Authorize
 ---------
 
 .. http:get:: /authorize/$NONCE
 
   The OAuth 2.0 authorization endpoint. The client redirects the user's browser
   to this endpoint to begin the credential verification process.
 
   When called, KyCH performs the following steps:
 
   1. Validates the session identified by ``$NONCE`` exists and is in ``pending`` status.
   2. Validates the OAuth 2.0 parameters (response_type, client_id, redirect_uri, scope).
   3. Creates a verification request with the configured Swiyu Verifier.
   4. Stores the verification details and transitions the session to ``authorized`` status.
   5. Returns either an HTML page with a QR code or a JSON response, depending on
      the ``Accept`` header.
 
   The returned ``verification_url`` should be rendered as a QR code for the user
   to scan with their Swiyu Wallet. On mobile devices, the ``verification_deeplink``
   can be used to launch the wallet app directly.
 
   **Request:**
 
   :param NONCE: The session nonce obtained from ``/setup``. This is a URL path
     parameter, not a query parameter.
 
   :query response_type: Required. Must be ``code`` for the authorization code
     grant flow. Other values are rejected with ``400 Bad Request``.
 
   :query client_id: Required. The client identifier. Must match the client that
     created this session via ``/setup``. Mismatches are rejected.
 
   :query redirect_uri: Required. The URI where the user will be redirected after
     verification completes. Must exactly match the redirect URI registered for
     this client in KyCH's configuration. Mismatches are rejected for security.
 
   :query state: Required. An opaque value generated by the client for CSRF
     protection. KyCH stores this value and includes it in all subsequent
     responses and redirects. The client must verify the state matches when
     receiving the callback to prevent cross-site request forgery attacks.
 
   :query scope: Required. Space-delimited list of credential claims to request
     from the user's verifiable credential. Each claim must be in the list
     returned by ``/config``. Example: ``family_name given_name age_over_18``.
     The user will be asked to consent to disclosing these specific claims.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Verification request created successfully. If the ``Accept`` header includes
     ``text/html``, returns an HTML page containing a QR code and JavaScript that
     polls the status endpoint. Otherwise, returns a `KyCHAuthorizeResponse` JSON
     object containing the verification URL.
 
   :http:statuscode:`400 Bad Request`:
     One or more request parameters are invalid:
 
     - ``response_type`` is not ``code``
     - ``redirect_uri`` does not match the registered URI for this client
     - ``scope`` contains claims not in the allowed list
     - Required parameters are missing
 
   :http:statuscode:`404 Not found`:
     No session exists for the provided ``$NONCE``. The nonce may have never
     existed, or it may have already been used (nonces are single-use).
 
   :http:statuscode:`409 Conflict`:
     The session exists but is not in ``pending`` status. This occurs if
     ``/authorize`` is called multiple times for the same nonce, or if the
     session has already progressed to a later state.
 
   :http:statuscode:`410 Gone`:
     The session has expired. Sessions have a limited lifetime configured on
     the server. The client should call ``/setup`` to create a new session.
 
   :http:statuscode:`502 Bad Gateway`:
     KyCH failed to communicate with the Swiyu Verifier when creating the
     verification request. This may indicate network issues or verifier
     unavailability. The client may retry after a delay.
 
   .. ts:def:: KyCHAuthorizeResponse
 
     interface KyCHAuthorizeResponse {
       // UUID assigned by the Swiyu Verifier to identify this verification
       // request. Used in the /status and /finalize endpoint URLs.
       verificationId: string;
 
       // URL that encodes the OID4VP verification request. This URL should
       // be rendered as a QR code for the user to scan with their Swiyu
       // Wallet. The wallet will retrieve the presentation request from
       // the Swiyu Verifier using this URL.
       verification_url: string;
 
       // Deep link URL for mobile devices. When opened on a device with
       // the Swiyu Wallet installed, this launches the wallet app directly
       // instead of requiring QR code scanning. Only present if the Swiyu
       // Verifier provides it.
       verification_deeplink?: string;
 
       // The state parameter echoed back unchanged. The client should
       // verify this matches the state it sent to detect CSRF attacks.
       state: string;
     }
 
 
 .. _kych-status:
 
 ------
 Status
 ------
 
 .. http:get:: /status/$VERIFICATION_ID
 
   Polls the current status of a verification request. Clients (or the browser
   JavaScript on the authorize page) use this endpoint to detect when the user
   has completed the verification process.
 
   The ``state`` parameter is required and must match the state from the original
   authorization request. This prevents unauthorized parties from polling
   verification status.
 
   **Request:**
 
   :param VERIFICATION_ID: The verification ID returned by ``/authorize``.
 
   :query state: Required. The state parameter from the original authorization
     request. Must match exactly. This provides CSRF protection and prevents
     unauthorized status polling.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Returns a `KyCHStatusResponse` containing the current verification status.
 
   :http:statuscode:`403 Forbidden`:
     The ``state`` parameter does not match the state associated with this
     verification. This may indicate a CSRF attack or that the wrong state
     was provided.
 
   :http:statuscode:`404 Not found`:
     No verification exists with the given ``$VERIFICATION_ID``. The ID may
     be invalid or the verification may have been deleted after expiration.
 
   .. ts:def:: KyCHStatusResponse
 
     interface KyCHStatusResponse {
       // Current status of the verification. Possible values:
       //
       // - "pending": Session created but /authorize not yet called.
       //   (Normally not seen via /status since /authorize must be
       //   called first to get the verification_id.)
       //
       // - "authorized": User has been shown the QR code but has not
       //   yet scanned it or completed verification in their wallet.
       //   The client should continue polling.
       //
       // - "verified": The user's credential has been successfully
       //   verified by the Swiyu Verifier. The client can now redirect
       //   the user to /finalize to obtain the authorization code.
       //
       // - "failed": Verification failed. This may occur if the user
       //   declined consent, presented an invalid credential, or the
       //   credential issuer is not trusted.
       //
       // - "expired": The verification session timed out before the
       //   user completed verification. The client should start a
       //   new session via /setup.
       //
       // - "completed": An access token has already been issued for
       //   this verification. The flow is complete.
       status: "pending" | "authorized" | "verified" | "failed" | "expired" | "completed";
     }
 
 
 .. _kych-finalize:
 
 --------
 Finalize
 --------
 
 .. http:get:: /finalize/$VERIFICATION_ID
 
   Completes the authorization flow by redirecting the user back to the client
   with an OAuth 2.0 authorization code. This endpoint should only be called
   after polling ``/status`` returns ``verified``.
 
   When called, KyCH:
 
   1. Validates the session is in ``verified`` status.
   2. Generates a cryptographically random authorization code.
   3. Stores the code with a short expiration time (configurable, default 10 minutes).
   4. Redirects the user's browser to the client's registered ``redirect_uri``
      with the authorization code and state as query parameters.
 
   The authorization code is single-use. The client must exchange it for an
   access token at the ``/token`` endpoint before it expires.
 
   **Request:**
 
   :param VERIFICATION_ID: The verification ID returned by ``/authorize``.
 
   :query state: Required. The state parameter from the original authorization
     request. Must match exactly for CSRF protection.
 
   **Response:**
 
   :http:statuscode:`302 Found`:
     Redirects to the client's ``redirect_uri`` with query parameters:
 
     - ``code``: The authorization code to exchange for an access token.
     - ``state``: The state parameter, echoed back unchanged.
 
     Example redirect: ``https://client.example.com/callback?code=abc123&state=xyz789``
 
   :http:statuscode:`400 Bad Request`:
     The verification is not in ``verified`` status. This occurs if:
 
     - The user has not completed verification yet (status is ``authorized``)
     - Verification failed (status is ``failed``)
     - A token was already issued (status is ``completed``)
 
   :http:statuscode:`403 Forbidden`:
     The ``state`` parameter does not match.
 
   :http:statuscode:`404 Not found`:
     No verification exists with the given ``$VERIFICATION_ID``.
 
 
 .. _kych-token:
 
 -----
 Token
 -----
 
 .. http:post:: /token
 
   Exchanges an authorization code for an access token. This is the standard
   OAuth 2.0 token endpoint implementing the authorization code grant.
 
   The client authenticates by including its ``client_id`` and ``client_secret``
   in the request body (not via HTTP Basic authentication). The ``redirect_uri``
   must exactly match the one used in the original authorization request.
 
   Authorization codes are single-use. Once exchanged for a token, the code
   is invalidated and cannot be used again. Codes also expire after a short
   time (configurable, default 10 minutes).
 
   **Request:**
 
   :reqheader Content-Type: Must be ``application/x-www-form-urlencoded``.
 
   The request body contains the following form parameters:
 
   .. ts:def:: KyCHTokenRequest
 
     interface KyCHTokenRequest {
       // The OAuth 2.0 grant type. Must be "authorization_code".
       grant_type: "authorization_code";
 
       // The authorization code received from the /finalize redirect.
       // This code is single-use and expires after a short time.
       code: string;
 
       // The client identifier. Must match the client that initiated
       // the authorization flow.
       client_id: string;
 
       // The client secret for authentication. KyCH verifies this
       // against the stored bcrypt hash.
       client_secret: string;
 
       // The redirect URI. Must exactly match the redirect_uri used
       // in the original /authorize request. This prevents authorization
       // code injection attacks.
       redirect_uri: string;
     }
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Token issued successfully. Returns a `KyCHTokenResponse` containing
     the access token. The session status is updated to ``completed``.
 
   :http:statuscode:`400 Bad Request`:
     The request is invalid. Possible causes:
 
     - ``grant_type`` is not ``authorization_code``
     - ``code`` is missing, invalid, expired, or already used
     - ``redirect_uri`` does not match the original request
     - Required parameters are missing
 
   :http:statuscode:`401 Unauthorized`:
     Client authentication failed. Either ``client_id`` does not exist or
     ``client_secret`` does not match the registered secret.
 
   .. ts:def:: KyCHTokenResponse
 
     interface KyCHTokenResponse {
       // The access token. Use this as a Bearer token in the
       // Authorization header when calling /info.
       access_token: string;
 
       // The token type. Always "Bearer".
       token_type: "Bearer";
 
       // Token validity period in seconds. The token cannot be used
       // after this time. Typically 3600 (1 hour).
       expires_in: number;
     }
 
 
 .. _kych-info:
 
 ----
 Info
 ----
 
 .. http:get:: /info
 
   Retrieves the verified identity claims using an access token. This endpoint
   is analogous to the OAuth 2.0 UserInfo endpoint but returns verified
   credential claims instead of user profile information.
 
   The response contains only the claims that were:
 
   1. Requested in the ``scope`` parameter during authorization.
   2. Successfully disclosed by the user from their verifiable credential.
 
   The access token is validated on each request. Expired or revoked tokens
   are rejected.
 
   **Request:**
 
   :reqheader Authorization: Required. Must be ``Bearer $ACCESS_TOKEN`` where
     ``$ACCESS_TOKEN`` is the token received from ``/token``.
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Returns a `KyCHInfoResponse` containing the verified claims.
 
   :http:statuscode:`401 Unauthorized`:
     The access token is missing, malformed, expired, or has been revoked.
     The client should obtain a new token by starting a new verification flow.
 
   .. ts:def:: KyCHInfoResponse
 
     interface KyCHInfoResponse {
       // The verified credential claims as key-value pairs. Only claims
       // that were requested and disclosed are included.
       //
       // Example response for scope "family_name given_name age_over_18":
       // {
       //   "family_name": "Muster",
       //   "given_name": "Max",
       //   "age_over_18": true
       // }
       //
       // Claim types vary:
       // - String claims: family_name, given_name, birth_place, nationality, etc.
       // - Boolean claims: age_over_16, age_over_18, age_over_65
       // - Date claims: birth_date, issuance_date, expiry_date (ISO 8601 format)
       // - Binary claims: portrait (base64-encoded image data)
       [claim: string]: string | boolean | number | object;
     }
 
 
 .. _kych-notification:
 
 ------------
 Notification
 ------------
 
 .. http:post:: /notification
 
   Webhook endpoint for receiving asynchronous notifications from the Swiyu
   Verifier. The verifier calls this endpoint when a verification request
   changes state, typically when the user presents their credential.
 
   When a notification is received, KyCH:
 
   1. Looks up the verification session by ``verification_id``.
   2. Queries the Swiyu Verifier's management API for the verification result.
   3. If successful, extracts the disclosed claims and updates the session
      to ``verified`` status.
   4. If failed, updates the session to ``failed`` status.
 
   This endpoint always returns ``200 OK`` to acknowledge receipt, regardless
   of whether processing succeeded. Errors are logged internally. This prevents
   the verifier from retrying notifications that cannot be processed.
 
   **Request:**
 
   :reqheader Content-Type: Should be ``application/json``.
 
   .. ts:def:: KyCHNotificationRequest
 
     interface KyCHNotificationRequest {
       // UUID of the verification request as assigned by the Swiyu
       // Verifier. KyCH uses this to look up the corresponding session.
       verification_id: string;
 
       // ISO 8601 timestamp indicating when the verification state
       // changed. Used for logging and debugging.
       timestamp: string;
     }
 
   **Response:**
 
   :http:statuscode:`200 OK`:
     Notification acknowledged. The response body is empty. This status is
     returned regardless of processing outcome to prevent retries.
 
 
 .. _kych-errors:
 
 ------
 Errors
 ------
 
 All error responses use the following format:
 
 .. ts:def:: KyCHErrorResponse
 
   interface KyCHErrorResponse {
     // Error code identifier
     error: string;
   }
 
 Common error codes:
 
 - ``unauthorized``: Missing or invalid authentication credentials.
 - ``invalid_request``: Malformed request parameters.
 - ``invalid_redirect_uri``: The redirect URI does not match the registered value.
 - ``invalid_scope``: Requested scopes are not allowed.
 - ``invalid_grant``: Authorization code is invalid, expired, or already used.
 - ``invalid_client``: Client authentication failed.
 - ``invalid_token``: Access token is invalid, expired, or revoked.
 - ``invalid_state``: The state parameter does not match.
 - ``session_not_found``: The session or verification was not found.
 - ``session_expired``: The session has expired.
 - ``not_verified``: The session has not been verified yet.
 - ``verifier_unavailable``: Cannot communicate with the Swiyu Verifier.
 - ``verifier_error``: The Swiyu Verifier returned an error.
 - ``internal_error``: An internal server error occurred.