Security Considerations

The Verifier's security model covers transport, authentication, request binding, and credential integrity:

1. Transport Security: All communication occurs over HTTPS, safeguarding data in transit. OpenID4VP requires HTTPS in production; plain HTTP is only permitted in development when explicitly enabled.

2. Authentication & Authorization: Verifier endpoints require a valid OIDC bearer token, sent as Authorization: Bearer <token> and validated against your identity provider's JWKS endpoint (OIDC_JWKS_URL). Authenticated principals are derived from the token's claims, and administrative routes additionally enforce the admin role from realm_access.roles (client roles in resource_access.<client>.roles are also accepted). Store and transmit tokens securely; never expose them client-side. A small set of endpoints is public by design: the health and version routes (GET /, GET /version), hosted did:web documents (GET /:uuid/did.json, also served at /:uuid/.well-known/did.json), the Swagger docs (GET /api-docs, GET /api-docs-json), and the wallet-facing OpenID4VP protocol endpoints mounted by the underlying Credo agent (public by protocol design).

3. Nonce and State Binding: Authorization requests and presentation responses are bound together by unique, time-bound values defined by the OpenID4VP protocol. This binding prevents replay attacks and ensures a presentation can only be accepted for the request it was issued against.

4. Signed Authorization Requests: Each authorization request is signed with the verifier's DID, so wallets can authenticate the relying party before disclosing any data. The signing DID is taken from the verifierId when it is itself a DID, or from the optional signingDid field in the request body.

5. Credential Integrity: The Verifier validates credential signatures and resolves the issuer's DID document to confirm authenticity, rejecting credentials that fail authenticity or integrity checks. SD-JWT selective disclosure is honored so only the claims the holder chooses to reveal are processed.

6. Minimal Data Exposure: The Verifier only processes the claims required by your authorization request (expressed via DCQL or a Presentation Exchange definition). It does not request or retain unnecessary information, preserving holder privacy.

7. Rate Limiting: The service applies a global request rate limit (60 requests per 60 seconds) to mitigate abuse and brute-force attempts. Account for this limit when designing high-volume verification flows and retry logic.

8. Monitoring and Logging: Maintain logs and monitor for suspicious activity, such as repeated failed verifications or token validation errors.

9. Error Handling: Avoid exposing sensitive details in error responses. The service returns a consistent error shape (statusCode, message, path, timestamp); surface generic user-facing messages and keep technical details in your internal logs.

For local development without tokens, see the development bypass in Authentication.