Skip to content

Commit b1007fa

Browse files
committed
Record credential offers and let their makers list what they issued
The credential offer API answered only an offer URI, so an integration could not learn which credentials its offer produced, and any token with the status scope could revoke, suspend or reinstate every credential of its configurations, another integration's included. Every offer is now recorded (oidc_vci_credential_offer: owner, offered configurations, grant, and when it is redeemable, redeemed and kept until), with no personal data. The owner is the API principal which made it, none for an administrator's offer. The offer id travels on the issuer state or pre-authorized code, the access token and each issued credential's Status List entry, and the offer API answers it as offer_id. At the token endpoint, a token minted for an offer raises the record's retention to the token's own expiry, confirmed on the primary; a code or issuer state naming no offer is refused before anything is spent. The Credential Endpoint links what a request signed to the token's offer through a linker which can change no status, every credential or none, then checks with a fresh clock that the token still lives and on the primary that the offer is still recorded, before anything is handed out. GET api/vci/credential-offer/{offer_id} lists an offer and its credentials to the principal which made it, by bearer token only, in pages of 500 with a strictly validated keyset cursor; every refusal is the same 404. A credential from an offer an API token made can have its status changed by that offer's owner only, compared byte for byte. The cron removes a record once it is past its retention and no Status List entry names it; linkage cleanup clears the entries' offer_id with the rest. Migration version20261111000001, re-runnable. Assisted-by: Claude Code (claude-opus-5-5, design, implementation & tests) Assisted-by: Claude Code (claude-sonnet-5-5, test adaptation & tests) Assisted-by: OpenAI Codex (gpt-6.1-sol, xhigh review) Assisted-by: Google Antigravity (gemini-3.8-flash-high, review)
1 parent 8d07d49 commit b1007fa

67 files changed

Lines changed: 5688 additions & 132 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/8-api.md‎

Lines changed: 144 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,13 @@ token itself is never written anywhere, since that would put a bearer secret in
6969
Both shapes work. A token configured as a plain list of scopes can not be given credential configurations,
7070
though, so it can not be used at the credential offer and credential status endpoints (see below).
7171

72+
The name, or the fingerprint of an unnamed token, is also who owns the credential offers the token makes (see
73+
[Credential Offer Details](#credential-offer-details)). Two tokens configured under one name are therefore one
74+
owner, by design: a token can be rotated without losing its offers, and an offering system and a support system can
75+
share their offers by sharing a name. Two integrations an operator gives the same name share them too, so give each
76+
integration a name of its own. An unnamed token owns its offers by its fingerprint, so rotating it loses them: the
77+
new token can neither list them nor change the status of what they issued (the administration screens still can).
78+
7279
### Limiting a token to credential configurations
7380

7481
A token's scopes say which endpoints it may call. At the credential offer and credential status endpoints, a
@@ -166,7 +173,18 @@ naming the same user each issue their own attributes.
166173

167174
#### Response
168175

169-
The response is a JSON object with the `credential_offer_uri` field containing the credential offer URI string value.
176+
The response is a JSON object with two fields:
177+
178+
* __credential_offer_uri__ (string): the credential offer URI, which the wallet is sent to.
179+
* __offer_id__ (string): the identifier of the offer, 64 lower-case hexadecimal characters. Keep it: it is how the
180+
caller later asks which credentials the offer produced, and changes their status (see
181+
[Credential Offer Details](#credential-offer-details)). It is neither the pre-authorized code nor the issuer state,
182+
which redeem the offer and are for the wallet only, so it can go into the caller's own records and logs.
183+
184+
Every offer is recorded, with the principal of the token which made it as its owner (its name, or a fingerprint;
185+
see [Naming a token](#naming-a-token)). An offer made from an administrator's session, or from the administration
186+
screens, has no owner, and no API caller can list it. The record holds no personal data: the user attributes of a
187+
pre-authorized offer stay with its code and its access token.
170188

171189
An offer for the authorization code grant is redeemed once: when the wallet exchanges the code it obtained with the
172190
offer for an access token. That has to happen within the issuer state lifetime (`vci_issuer_state_ttl`); the access
@@ -189,9 +207,9 @@ hold no email address to send the transaction code to.
189207
`credential_configuration_ids`, or the token has none (see
190208
[Limiting a token to credential configurations](#limiting-a-token-to-credential-configurations)). A configuration
191209
which does not exist is answered with `400` `invalid_request` whatever the list says.
192-
* `500` `server_error`: the offer could not be built, for example because the transaction code could not be mailed,
193-
or a credential configuration is malformed; or the token's `credential_configuration_ids` are malformed. The cause
194-
is in the log.
210+
* `500` `server_error`: the offer could not be built or recorded, for example because the transaction code could not
211+
be mailed, or a credential configuration is malformed; or the token's name or `credential_configuration_ids` could
212+
not be read from the configuration. The cause is in the log.
195213

196214
When the wallet redeems a pre-authorized code at the token endpoint, a wrong transaction code is answered with
197215
`invalid_grant`, and one sent for an offer which has none with `invalid_request`, as OpenID4VCI 1.0 section 6.3 has
@@ -225,7 +243,8 @@ Response:
225243

226244
```json
227245
{
228-
"credential_offer_uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fidp.mivanci.incubator.hexaa.eu%22%2C%22credential_configuration_ids%22%3A%5B%22ResearchAndScholarshipCredentialDcSdJwt%22%5D%2C%22grants%22%3A%7B%22authorization_code%22%3A%7B%22issuer_state%22%3A%2230616b68fa26b00c5a6391faffc02e4e4fd9b0023fd6a3aa29ec754e2f5e2871%22%7D%7D%7D"
246+
"credential_offer_uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fidp.mivanci.incubator.hexaa.eu%22%2C%22credential_configuration_ids%22%3A%5B%22ResearchAndScholarshipCredentialDcSdJwt%22%5D%2C%22grants%22%3A%7B%22authorization_code%22%3A%7B%22issuer_state%22%3A%2230616b68fa26b00c5a6391faffc02e4e4fd9b0023fd6a3aa29ec754e2f5e2871%22%7D%7D%7D",
247+
"offer_id": "8f4c2a1e9d7b6053c4e1f2a8b9d0c7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0"
229248
}
230249

231250
```
@@ -259,7 +278,115 @@ Response:
259278

260279
```json
261280
{
262-
"credential_offer_uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fidp.mivanci.incubator.hexaa.eu%22%2C%22credential_configuration_ids%22%3A%5B%22ResearchAndScholarshipCredentialDcSdJwt%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%22_ffcdf6d86cd564c300346351dce0b4ccb2fde304e2%22%2C%22tx_code%22%3A%7B%22input_mode%22%3A%22numeric%22%2C%22length%22%3A4%2C%22description%22%3A%22Please%20provide%20the%20one-time%20code%20that%20was%20sent%20to%20your%20e-mail%20address.%22%7D%7D%7D%7D"
281+
"credential_offer_uri": "openid-credential-offer://?credential_offer=%7B%22credential_issuer%22%3A%22https%3A%2F%2Fidp.mivanci.incubator.hexaa.eu%22%2C%22credential_configuration_ids%22%3A%5B%22ResearchAndScholarshipCredentialDcSdJwt%22%5D%2C%22grants%22%3A%7B%22urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Apre-authorized_code%22%3A%7B%22pre-authorized_code%22%3A%22_ffcdf6d86cd564c300346351dce0b4ccb2fde304e2%22%2C%22tx_code%22%3A%7B%22input_mode%22%3A%22numeric%22%2C%22length%22%3A4%2C%22description%22%3A%22Please%20provide%20the%20one-time%20code%20that%20was%20sent%20to%20your%20e-mail%20address.%22%7D%7D%7D%7D",
282+
"offer_id": "3b9e7d1c5a2f4086e9c3b7a1d5f2e8c4b6a0d9e3f7c1b5a8e2d6f0c4b9a7e3d1"
283+
}
284+
```
285+
286+
### Credential Offer Details
287+
288+
Tells the caller which made a credential offer what the offer produced: the offer as it is recorded, and the
289+
credentials issued from it, each with the identifier the [Credential Status](#credential-status) endpoint takes.
290+
Withdrawing a credential issued from an offer is then: list the offer's credentials, and change the status of each.
291+
292+
It is served under the same settings as the [Credential Offer](#credential-offer) endpoint: the API, the VCI
293+
feature and `ModuleConfig::OPTION_API_VCI_CREDENTIAL_OFFER_ENDPOINT_ENABLED`. With the VCI feature switched off
294+
it is not served, unlike the credential status endpoint; the administration screens still reach the credentials.
295+
296+
#### Path
297+
298+
`/api/vci/credential-offer/{offer_id}`, with the `offer_id` the credential offer endpoint answered.
299+
300+
#### Method
301+
302+
`GET`
303+
304+
#### Authorization
305+
306+
`Bearer Token`, and only from the `Authorization` header, for the reasons given at the
307+
[Credential Status](#credential-status) endpoint. The token needs one of the scopes of the credential offer
308+
endpoint (`VciCredentialOffer`, `VciAll`, `All`), has to stand for the principal which made the offer (see
309+
[Naming a token](#naming-a-token)), and every credential configuration the offer offered has to be in its
310+
`credential_configuration_ids` still: an offer whose configuration has since been taken off the token's list is no
311+
longer the token's to see.
312+
313+
#### Request
314+
315+
* __cursor__ (query parameter, optional): the `next_cursor` of the previous page, to ask for the page after it.
316+
317+
#### Response
318+
319+
A JSON object with the following fields. Moments are numbers of seconds since the epoch (UTC), as in a JWT.
320+
321+
* __offer_id__ (string): the offer's identifier.
322+
* __credential_configuration_ids__ (array of strings): the credential configurations offered.
323+
* __grant_type__ (string): the grant the offer is redeemed with.
324+
* __created_at__ (number): when the offer was made.
325+
* __redeemable_until__ (number): when its pre-authorized code or issuer state expires.
326+
* __redeemed_at__ (number or `null`): when an access token was first issued for the offer, `null` until then. It says
327+
that a token was issued, not that a credential reached a wallet.
328+
* __withdrawn_at__ (number or `null`): reserved for withdrawing an offer; always `null` for now.
329+
* __credentials__ (array): the credentials issued from the offer, in the order they were issued, at most 500 per
330+
page. Each is an object with:
331+
* __credential_id__ (string): the credential's `jti`, which the credential status endpoint takes.
332+
* __credential_configuration_id__ (string): the credential configuration it was issued from.
333+
* __status__ (string): `valid`, `invalid` or `suspended`, as the credential status endpoint names them.
334+
* __issued_at__ (number): when it was issued, to the second. The times the credential itself states are rounded
335+
(`vci_time_claim_granularity`), so its `iat` may be earlier and its `exp` later.
336+
* __expires_at__ (number or `null`): when it expires; `null` for a credential which never does.
337+
* __next_cursor__ (string, only when there are more): pass it as `cursor` to get the next page. A cursor names the
338+
last credential of a page rather than a position, so credentials which expire while the caller pages do not shift
339+
the pages.
340+
341+
An access token issued for an offer buys credentials as often as its lifetime allows, so the list can grow until
342+
the token expires. A credential appears once it has been signed and before it is handed to the wallet, so a list
343+
taken after the wallet received a credential holds it. A credential issued with no Token Status List entry (its
344+
configuration is in no Status List pool) is not listed, since the entry is where the link to the offer is kept; nor
345+
is a credential once it has expired and the cron has removed what linked it to its offer. An offer is kept as long as
346+
it can still be redeemed, as long as an access token issued for it lives, and as long as a credential issued from
347+
it has not expired; then the cron removes it.
348+
349+
Errors:
350+
351+
* `400 invalid_request`: the cursor is malformed.
352+
* `401 unauthorized`: no bearer token, or one which is not configured.
353+
* `403 insufficient_scope`: the token is configured but has none of the scopes this endpoint accepts.
354+
* `404 not_found`: no offer with that identifier can be shown. An identifier which is malformed, one which is
355+
unknown or whose offer has been removed, an offer made from an administrator's session, an offer made by another
356+
principal, and an offer whose credential configuration is no longer in the token's list are all answered the same
357+
way, so that the endpoint can not be used to find out which offers exist. The log says which it was.
358+
* `500 server_error`: the offer or its credentials could not be read, or the token's name or
359+
`credential_configuration_ids` could not be read from the configuration. The cause is in the log.
360+
361+
#### Sample
362+
363+
Request:
364+
365+
```shell
366+
curl --location 'https://idp.example.org/ssp/module.php/oidc/api/vci/credential-offer/8f4c2a1e9d7b6053c4e1f2a8b9d0c7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0' \
367+
--header 'Authorization: Bearer ***'
368+
```
369+
370+
Response:
371+
372+
```json
373+
{
374+
"offer_id": "8f4c2a1e9d7b6053c4e1f2a8b9d0c7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0",
375+
"credential_configuration_ids": ["ResearchAndScholarshipCredentialDcSdJwt"],
376+
"grant_type": "authorization_code",
377+
"created_at": 1794391200,
378+
"redeemable_until": 1794391800,
379+
"redeemed_at": 1794391320,
380+
"withdrawn_at": null,
381+
"credentials": [
382+
{
383+
"credential_id": "https://idp.example.org/vc/mBS4Zt9wDRe-8sYcJUEBiZ4bGDsYY3rMHOB2Xdw4t1c",
384+
"credential_configuration_id": "ResearchAndScholarshipCredentialDcSdJwt",
385+
"status": "valid",
386+
"issued_at": 1794391320,
387+
"expires_at": 1825927320
388+
}
389+
]
263390
}
264391
```
265392

@@ -324,12 +451,19 @@ status was not one of the three.
324451
* `401 unauthorized`: no bearer token, or one which is not configured.
325452
* `403 insufficient_scope`: the token is configured but has none of the scopes this endpoint accepts.
326453
* `404 not_found`: no credential with that identifier can have its status changed. A credential which
327-
was never issued here, one issued without a `status` claim, one which has expired, and one issued from a
454+
was never issued here, one issued without a `status` claim, one which has expired, one issued from a
328455
credential configuration which is not in the token's `credential_configuration_ids` (see
329456
[Limiting a token to credential configurations](#limiting-a-token-to-credential-configurations)), or whose
330-
configuration is not recorded, are all answered the same way, so that the endpoint can not be used to find out
331-
which identifiers exist. A token with `['*']` included: only the administration screens can change a credential
332-
whose configuration is not recorded.
457+
configuration is not recorded, and one issued from a credential offer another principal made, are all answered
458+
the same way, so that the endpoint can not be used to find out which identifiers exist. A token with `['*']`
459+
included: only the administration screens can change a credential whose configuration is not recorded.
460+
461+
A credential issued from an offer an API token made can have its status changed by that token's principal only
462+
(see [Naming a token](#naming-a-token)), whatever the other tokens' configurations: otherwise an integration sharing
463+
a credential configuration with another could revoke, suspend or reinstate the other's credentials, whose
464+
identifiers travel inside them to every verifier they are shown to. Any other credential, one a wallet obtained
465+
without an offer or from an offer made from the administration screens, is changed under the token's credential
466+
configurations alone.
333467
* `409 conflict`: another change landed at the same moment and the credential ended up holding
334468
something other than what was asked for. Read the current status and decide again.
335469
* `422 unsupported_status`: the Status List this credential belongs to was created without room for

‎routing/routes/routes.php‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -208,6 +208,12 @@
208208
)->controller([VciCredentialOfferApiController::class, 'credentialOffer'])
209209
->methods([HttpMethodsEnum::POST->value]);
210210

211+
$routes->add(
212+
RoutesEnum::ApiVciCredentialOfferDetails->name,
213+
RoutesEnum::ApiVciCredentialOfferDetails->value,
214+
)->controller([VciCredentialOfferApiController::class, 'credentialOfferDetails'])
215+
->methods([HttpMethodsEnum::GET->value]);
216+
211217
$routes->add(
212218
RoutesEnum::ApiVciCredentialStatus->name,
213219
RoutesEnum::ApiVciCredentialStatus->value,

‎src/Codebooks/RoutesEnum.php‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,9 @@ enum RoutesEnum: string
108108
****************************************************************************************************************/
109109

110110
case ApiVciCredentialOffer = 'api/vci/credential-offer';
111+
// What one offer produced, asked by the API caller which made it. The offer id is validated by the controller,
112+
// after authorization, so that a malformed one is answered as an unknown one is.
113+
case ApiVciCredentialOfferDetails = 'api/vci/credential-offer/{offerId}';
111114
case ApiVciCredentialStatus = 'api/vci/credential-status';
112115
case ApiOAuth2TokenIntrospection = 'api/oauth2/token-introspection';
113116
}

‎src/Controllers/Admin/VerifiableCredentailsTestController.php‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -161,16 +161,17 @@ public function verifiableCredentialIssuance(Request $request): Response
161161
is_string($authSourceId) ? $authSourceId : '',
162162
);
163163

164+
// An administrator's offer is recorded with no owner, so no API caller can list it.
164165
$credentialOfferUri = $this->credentialOfferUriFactory->buildPreAuthorized(
165166
[$credentialConfigurationId],
166167
$authSource->getAttributes(),
167168
$useTxCode,
168169
$usersEmailAttributeName,
169-
);
170+
)->getUri();
170171
} elseif ($grantType === GrantTypesEnum::AuthorizationCode->value) {
171172
$credentialOfferUri = $this->credentialOfferUriFactory->buildForAuthorization(
172173
[$credentialConfigurationId],
173-
);
174+
)->getUri();
174175
}
175176
}
176177

0 commit comments

Comments
 (0)