feat: Pass in issuer_state to regular state in auth code flow, so we get a better integration with any external OIDC solution

Author: nklomp

packages/client/lib/CredentialRequestClient.ts

@@ -18,7 +18,7 @@ import {
   UniformCredentialRequest,
   URL_NOT_VALID,
 } from '@sphereon/oid4vci-common';
-import { CredentialFormat, DIDDocument } from '@sphereon/ssi-types';
+import { CredentialFormat } from '@sphereon/ssi-types';
 import Debug from 'debug';
 
 import { CredentialRequestClientBuilderV1_0_11 } from './CredentialRequestClientBuilderV1_0_11';
@@ -41,9 +41,10 @@ export interface CredentialRequestOpts {
   token: string;
   version: OpenId4VCIVersion;
   subjectIssuance?: ExperimentalSubjectIssuance;
+  issuerState?: string;
 }
 
-export type CreateCredentialRequestOpts<DIDDoc = DIDDocument> = {
+export type CreateCredentialRequestOpts = {
   credentialIdentifier?: string;
   credentialTypes?: string | string[];
   context?: string[];
@@ -52,7 +53,7 @@ export type CreateCredentialRequestOpts<DIDDoc = DIDDocument> = {
   version: OpenId4VCIVersion;
 };
 
-export async function buildProof<DIDDoc = DIDDocument>(
+export async function buildProof(
   proofInput: ProofOfPossessionBuilder | ProofOfPossession,
   opts: {
     version: OpenId4VCIVersion;
@@ -101,7 +102,7 @@ export class CredentialRequestClient {
    * like using DPoP together with an authorization code flow. These are however rare, so you should be using the acquireCredentialsUsingProof normally
    * @param opts
    */
-  public async acquireCredentialsWithoutProof<DIDDoc = DIDDocument>(opts: {
+  public async acquireCredentialsWithoutProof(opts: {
     credentialIdentifier?: string;
     credentialTypes?: string | string[];
     context?: string[];
@@ -122,7 +123,7 @@ export class CredentialRequestClient {
     return await this.acquireCredentialsUsingRequestWithoutProof(request, opts.createDPoPOpts);
   }
 
-  public async acquireCredentialsUsingProof<DIDDoc = DIDDocument>(opts: {
+  public async acquireCredentialsUsingProof(opts: {
     proofInput: ProofOfPossessionBuilder | ProofOfPossession;
     credentialIdentifier?: string;
     credentialTypes?: string | string[];
@@ -245,21 +246,19 @@ export class CredentialRequestClient {
     });
   }
 
-  public async createCredentialRequestWithoutProof<DIDDoc = DIDDocument>(
-    opts: CreateCredentialRequestOpts,
-  ): Promise<CredentialRequestWithoutProofV1_0_13> {
+  public async createCredentialRequestWithoutProof(opts: CreateCredentialRequestOpts): Promise<CredentialRequestWithoutProofV1_0_13> {
     return await this.createCredentialRequestImpl(opts);
   }
 
-  public async createCredentialRequest<DIDDoc = DIDDocument>(
+  public async createCredentialRequest(
     opts: CreateCredentialRequestOpts & {
       proofInput: ProofOfPossessionBuilder | ProofOfPossession;
     },
   ): Promise<CredentialRequestV1_0_13> {
     return await this.createCredentialRequestImpl(opts);
   }
 
-  private async createCredentialRequestImpl<DIDDoc = DIDDocument>(
+  private async createCredentialRequestImpl(
     opts: CreateCredentialRequestOpts & {
       proofInput?: ProofOfPossessionBuilder | ProofOfPossession;
     },
@@ -295,6 +294,7 @@ export class CredentialRequestClient {
     if (types.length === 0) {
       throw Error(`Credential type(s) need to be provided`);
     }
+    const issuer_state = this.credentialRequestOpts.issuerState;
 
     // TODO: we should move format specific logic
     if (format === 'jwt_vc_json' || format === 'jwt_vc') {
@@ -303,6 +303,7 @@ export class CredentialRequestClient {
           type: types,
         },
         format,
+        ...(issuer_state && { issuer_state }),
         ...(proof && { proof }),
         ...opts.subjectIssuance,
       };
@@ -313,6 +314,7 @@ export class CredentialRequestClient {
 
       return {
         format,
+        ...(issuer_state && { issuer_state }),
         ...(proof && { proof }),
         ...opts.subjectIssuance,
 
@@ -327,6 +329,7 @@ export class CredentialRequestClient {
       }
       return {
         format,
+        ...(issuer_state && { issuer_state }),
         ...(proof && { proof }),
         vct: types[0],
         ...opts.subjectIssuance,
@@ -337,6 +340,7 @@ export class CredentialRequestClient {
       }
       return {
         format,
+        ...(issuer_state && { issuer_state }),
         ...(proof && { proof }),
         doctype: types[0],
         ...opts.subjectIssuance,

packages/client/lib/CredentialRequestClientBuilder.ts

@@ -168,6 +168,10 @@ export class CredentialRequestClientBuilder {
     return this;
   }
 
+  public withIssuerState(issuerState?: string): this {
+    this._builder.withIssuerState(issuerState);
+    return this;
+  }
   public withCredentialType(credentialTypes: string | string[]): this {
     this._builder.withCredentialType(credentialTypes);
     return this;

packages/client/lib/CredentialRequestClientBuilderV1_0_11.ts

@@ -28,6 +28,7 @@ export class CredentialRequestClientBuilderV1_0_11 {
   token?: string;
   version?: OpenId4VCIVersion;
   subjectIssuance?: ExperimentalSubjectIssuance;
+  issuerState?: string;
 
   public static fromCredentialIssuer({
     credentialIssuer,
@@ -98,6 +99,11 @@ export class CredentialRequestClientBuilderV1_0_11 {
     });
   }
 
+  public withIssuerState(issuerState?: string): this {
+    this.issuerState = issuerState;
+    return this;
+  }
+
   public withCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadata): this {
     this.credentialEndpoint = metadata.credential_endpoint;
     return this;

packages/client/lib/CredentialRequestClientBuilderV1_0_13.ts

@@ -27,6 +27,7 @@ export class CredentialRequestClientBuilderV1_0_13 {
   token?: string;
   version?: OpenId4VCIVersion;
   subjectIssuance?: ExperimentalSubjectIssuance;
+  issuerState?: string;
 
   public static fromCredentialIssuer({
     credentialIssuer,
@@ -86,6 +87,7 @@ export class CredentialRequestClientBuilderV1_0_13 {
     if (ids.length && ids.length === 1) {
       builder.withCredentialIdentifier(ids[0]);
     }
+
     return builder;
   }
 
@@ -96,11 +98,13 @@ export class CredentialRequestClientBuilderV1_0_13 {
     credentialOffer: CredentialOfferRequestWithBaseUrl;
     metadata?: EndpointMetadata;
   }): CredentialRequestClientBuilderV1_0_13 {
-    return CredentialRequestClientBuilderV1_0_13.fromCredentialOfferRequest({
+    const builder = CredentialRequestClientBuilderV1_0_13.fromCredentialOfferRequest({
       request: credentialOffer,
       metadata,
       version: credentialOffer.version,
     });
+
+    return builder;
   }
 
   public withCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadataV1_0_13): this {
@@ -113,6 +117,11 @@ export class CredentialRequestClientBuilderV1_0_13 {
     return this;
   }
 
+  public withIssuerState(issuerState?: string): this {
+    this.issuerState = issuerState;
+    return this;
+  }
+
   public withDeferredCredentialEndpointFromMetadata(metadata: CredentialIssuerMetadataV1_0_13): this {
     this.deferredCredentialEndpoint = metadata.deferred_credential_endpoint;
     return this;

packages/client/lib/OpenID4VCIClient.ts

@@ -455,6 +455,15 @@ export class OpenID4VCIClient {
             version: this.version(),
           });
     }
+    // If we are in an auth code flow, without a c nonce, we return the issuerState back to the issuer in case it is present
+    const issuerState =
+      this.issuerSupportedFlowTypes().includes(AuthzFlowType.AUTHORIZATION_CODE_FLOW) &&
+      this._state.authorizationCodeResponse &&
+      !this.accessTokenResponse?.c_nonce &&
+      this._state.credentialOffer?.issuerState
+        ? this._state.credentialOffer.issuerState
+        : undefined;
+    requestBuilder.withIssuerState(issuerState);
 
     requestBuilder.withTokenFromResponse(this.accessTokenResponse);
     requestBuilder.withDeferredCredentialAwait(deferredCredentialAwait ?? false, deferredCredentialIntervalInMS);

packages/client/lib/OpenID4VCIClientV1_0_13.ts

@@ -61,6 +61,7 @@ export interface OpenID4VCIClientStateV1_0_13 {
   pkce: PKCEOpts;
   accessToken?: string;
   authorizationURL?: string;
+  sendIssuerStateIfNoNonce?: boolean;
 }
 
 export class OpenID4VCIClientV1_0_13 {
@@ -459,7 +460,15 @@ export class OpenID4VCIClientV1_0_13 {
           metadata: this.endpointMetadata,
           version: this.version(),
         });
-
+    // If we are in an auth code flow, without a c nonce, we return the issuerState back to the issuer in case it is present
+    const issuerState =
+      this.issuerSupportedFlowTypes().includes(AuthzFlowType.AUTHORIZATION_CODE_FLOW) &&
+      this._state.authorizationCodeResponse &&
+      !this.accessTokenResponse?.c_nonce &&
+      this._state.credentialOffer?.issuerState
+        ? this._state.credentialOffer.issuerState
+        : undefined;
+    requestBuilder.withIssuerState(issuerState);
     requestBuilder.withTokenFromResponse(this.accessTokenResponse);
     requestBuilder.withDeferredCredentialAwait(deferredCredentialAwait ?? false, deferredCredentialIntervalInMS);
     let subjectIssuance: ExperimentalSubjectIssuance | undefined;

packages/issuer/lib/VcIssuer.ts

@@ -405,7 +405,7 @@ export class VcIssuer {
         const credentialDataSupplierInput = opts.credentialDataSupplierInput ?? session.credentialDataSupplierInput
 
         const result = await credentialDataSupplier({
-          ...cNonceState,
+          ...(cNonceState ? { ...cNonceState } : { ...authSession }),
           credentialRequest: opts.credentialRequest,
           credentialSupplierConfig: this._issuerMetadata.credential_supplier_config,
           credentialOffer /*todo: clientId: */,
@@ -477,8 +477,10 @@ export class VcIssuer {
         // credential: OPTIONAL. Contains issued Credential. MUST be present when acceptance_token is not returned. MAY be a JSON string or a JSON object, depending on the Credential format. See Appendix E for the Credential format specific encoding requirements
         throw new Error(CREDENTIAL_MISSING_ERROR)
       }
-      // remove the previous nonce
-      await this.cNonces.delete(cNonceState.cNonce)
+      if (cNonceState) {
+        // remove the previous nonce
+        await this.cNonces.delete(cNonceState.cNonce)
+      }
 
       let notification_id: string | undefined
 
@@ -624,14 +626,24 @@ export class VcIssuer {
 
       const { didDocument, did, jwt } = jwtVerifyResult
       const { header, payload } = jwt
-      const { iss, aud, iat, nonce } = payload
-      if (!nonce) {
+      const { iss, aud, iat, nonce, issuer_state } = payload
+      if (!nonce && !issuer_state) {
         throw Error('No nonce was found in the Proof of Possession')
       }
-      const cNonceState = await this.cNonces.getAsserted(nonce)
-      preAuthorizedCode = cNonceState.preAuthorizedCode
-      issuerState = cNonceState.issuerState
-      const createdAt = cNonceState.createdAt
+      let createdAt: number
+      let cNonceState: CNonceState | undefined
+      if (nonce) {
+        cNonceState = await this.cNonces.getAsserted(nonce)
+        preAuthorizedCode = cNonceState.preAuthorizedCode
+        issuerState = cNonceState.issuerState
+        createdAt = cNonceState.createdAt
+      } else if (issuer_state) {
+        const session = await this._credentialOfferSessions.getAsserted(issuer_state as string)
+        issuerState = issuer_state as string | undefined
+        createdAt = session.createdAt
+      } else {
+        throw Error('No nonce or issuer_state was found in the Proof of Possession')
+      }
       // The verify callback should set the correct values, but let's look at the JWT ourselves to to be sure
       const alg = jwtVerifyResult.alg ?? header.alg
       const kid = jwtVerifyResult.kid ?? header.kid

packages/oid4vci-common/lib/types/Authorization.types.ts

@@ -177,6 +177,7 @@ export interface AuthorizationChallengeCodeResponse {
    * The authorization code issued by the authorization server.
    */
   authorization_code: string;
+  state?: string;
 }
 
 // https://www.ietf.org/archive/id/draft-parecki-oauth-first-party-apps-02.html#name-error-response

packages/oid4vci-common/lib/types/v1_0_13.types.ts

@@ -108,6 +108,9 @@ export type CredentialRequestV1_0_13ResponseEncryption = {
 export interface CredentialRequestV1_0_13Common extends ExperimentalSubjectIssuance {
   credential_response_encryption?: CredentialRequestV1_0_13ResponseEncryption;
   proof?: ProofOfPossession;
+
+  // We allow sending a issuer state back to the credential offer in case an auth code flow is used with an external AS and no nonces are used (not recommended), but does allow to integrate any OIDC server
+  state?: string;
 }
 
 export type CredentialRequestV1_0_13 = CredentialRequestV1_0_13Common &