OID4VC: Batch Issuance Implementation Plan

Batch Issuance Implementation Plan

This is a result of conversations between myself, @dbluhm, and @TheTechmage.

What, When, and Why Batch Issuance

Batch Issuance is the process of issuing multiple single-use copies to a holder. Each copy is used once, and then discarded by the holder. Once all, or a sufficient number, of these disposable credentials are used, the holder can request a new batch from the issuer.

Batch issuance solves the issue of verifier-verifier linkability. Since each credential of a batch is only used once, verifiers can't keep track of the identifiers contained in the credential to collude with other verifiers about holder information without the holder's knowledge.

Batch issuance might not be necessary when the credential is expected to always disclose strongly correlating attributes. In that case, batch issuance would be additional overhead without the benefit of unlinkability.

Implementing Batch Issuance

A Batch Issuance endpoint would essentially be a standard /issue endpoint wrapped in a for-loop, so the added complexity there will be minimal.

Definitions: Refreshing Credentials vs. Reissuing Credentials

Obtaining a new batch of credentials, once you've exhausted your original set, is a key component of batch issuance. To that end, we'd like to note a difference between refreshing and reissuing a credential or batch of credentials.

• Refreshing a Credential: using a refresh token, supplied with the original batch, to obtain a new credential or batch of credentials
• Reissuing a Credential: starting the OID4VCI protocol flow over again, to obtain a replacement credential or batch of credentials

Refreshing occurs when the holder has a valid, non-expired refresh token and can present said token to the issuer.

Reissuing occurs if no refresh token was given, or if the refresh token has expired.

Refresh Tokens

We'll need to add the option to include a refresh token when issuing a credential or batch of credentials.

• Refresh tokens should be rotated on each use
• Refresh tokens must be stateful to enable "revocation"
• exp of refresh tokens are defined by the issuer
• If refresh token does not have an exp, the token must be sender-constrained using DPoP

Code Specifics

Models

Refresh Record: New

We'll need to add a new model, RefreshRecord, that holds the refresh token, credential values, a count of how many credentials have been issued, and as the maximum batch size.
We can match based on the refresh token and pull out the corresponding credential values to quickly refresh a holder's credentials.

Exchange Record: Updates

We'll need to keep track of whether an issuer intends for a credential to be batch issue-able and, optionally, the maximum batch size.

Public Routes

POST /batch-credential

• New route
• Does the same stuff as the credential endpoint just on a loop

GET /token

• Add support for the refresh_token grant type
• Should generate a new exchange record, derived from refresh record holding the credential values, advancing the record to the appropriate point in the state machine
• Generates a new refresh token, stores in the refresh record, and updates the expiration timestamp

Admin Routes

POST /oid4vci/exchange/create

Update the existing route.

• refresh (object):
  • ttl (interval | None | Absent): Integer representing the number of seconds until the refresh token expires after it's last use. If omitted, defaults to 1 week from now. If explicitly None/null, the refresh token will not have an expiration time and can be used indefinitely.

POST /oid4vci/refresh/expire

• Delete all expired refresh tokens and their associated credential records

DELETE /oid4vci/refresh/{token_id}

• Delete a refresh token early or if an expiration time was omitted

PUT /oid4vci/refresh/{token_id}

• Update the credential record values
• Update the interval
• Update the timestamp

Start by locating the existing OID4VCI exchange and token routes and their models; the plan names RefreshRecord and Exchange Record as the main model work. Review the proposed /batch-credential, /token, and admin refresh routes. Done means the planned batch issuance, refresh-token lifecycle, and refresh-record management behavior are implemented and tested.