docs(changeset): allow kid (when not a did) to be combined with x5c/jwk header params in JWT/JWS. This is a pattern commonly used and breaks interop with Credo.

Signed-off-by: Timo Glastra <[email protected]>

Author: TimoGlastra

.changeset/cuddly-deers-relate.md

@@ -0,0 +1,5 @@
+---
+'@credo-ts/core': patch
+---
+
+allow kid (when not a did) to be combined with x5c/jwk header params in JWT/JWS. This is a pattern commonly used and breaks interop with Credo.

packages/core/package.json

@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@animo-id/mdoc": "0.4.0",
-    "@animo-id/pex": "4.1.1-alpha.0",
+    "@animo-id/pex": "4.1.1-alpha.1",
     "@astronautlabs/jsonpath": "^1.1.2",
     "@digitalcredentials/jsonld": "^6.0.0",
     "@digitalcredentials/jsonld-signatures": "^9.4.0",

packages/core/src/crypto/JwsService.ts

@@ -211,8 +211,17 @@ export class JwsService {
   }
 
   private buildProtected(options: JwsProtectedHeaderOptions) {
-    if ([options.jwk, options.kid, options.x5c].filter(Boolean).length != 1) {
-      throw new CredoError('Only one of JWK, kid or x5c can and must be provided.')
+    const x5cJwkCount = [options.jwk, options.x5c].filter(Boolean).length
+
+    // FIXME: checking for kid starting with '#' is not good.
+    // but now we don't really limit that kid (did key reference)
+    // cannot be combined with x5c/jwk
+    if (options.kid?.startsWith('did:')) {
+      if (x5cJwkCount > 0) {
+        throw new CredoError("When 'kid' is a did, 'jwk' and 'x5c' cannot be provided.")
+      }
+    } else if (x5cJwkCount > 1 || (x5cJwkCount === 0 && !options.kid)) {
+      throw new CredoError("Header must contain one of 'kid' with a did value, 'x5c', or 'jwk'.")
     }
 
     return {
@@ -241,16 +250,25 @@ export class JwsService {
       trustedCertificates: trustedCertificatesFromOptions = [],
     } = options
 
-    if ([protectedHeader.jwk, protectedHeader.kid, protectedHeader.x5c].filter(Boolean).length > 1) {
-      throw new CredoError('Only one of jwk, kid and x5c headers can and must be provided.')
+    const x5cJwkCount = [protectedHeader.jwk, protectedHeader.x5c].filter(Boolean)
+
+    // FIXME: checking for kid starting with '#' is not good.
+    // but now we don't really limit that kid (did key reference)
+    // cannot be combined with x5c/jwk
+    if (typeof protectedHeader.kid === 'string' && protectedHeader.kid?.startsWith('did:')) {
+      if (x5cJwkCount.length > 0) {
+        throw new CredoError("When 'kid' is a did, 'jwk' and 'x5c' cannot be provided.")
+      }
+    } else if (x5cJwkCount.length > 1) {
+      throw new CredoError("Header must contain one of 'kid' with a did value, 'x5c', or 'jwk'.")
     }
 
     if (protectedHeader.x5c) {
       if (
         !Array.isArray(protectedHeader.x5c) ||
         protectedHeader.x5c.some((certificate) => typeof certificate !== 'string')
       ) {
-        throw new CredoError('x5c header is not a valid JSON array of string.')
+        throw new CredoError('x5c header is not a valid JSON array of strings.')
       }
 
       const trustedCertificatesFromConfig =
@@ -278,7 +296,9 @@ export class JwsService {
     }
 
     if (!jwkResolver) {
-      throw new CredoError(`jwkResolver is required when the JWS protected header does not contain a 'jwk' property.`)
+      throw new CredoError(
+        `jwkResolver is required when the JWS protected header does not contain a 'jwk' or 'x5c' property.`
+      )
     }
 
     try {

packages/core/src/crypto/__tests__/JwsService.test.ts

@@ -1,5 +1,5 @@
 import type { AgentContext } from '../../agent'
-import type { Key, Wallet } from '@credo-ts/core'
+import { X509Certificate, X509ModuleConfig, X509Service, type Key, type Wallet } from '@credo-ts/core'
 
 import { InMemoryWallet } from '../../../../../tests/InMemoryWallet'
 import { getAgentConfig, getAgentContext } from '../../../tests/helpers'
@@ -19,6 +19,7 @@ describe('JwsService', () => {
   let agentContext: AgentContext
   let jwsService: JwsService
   let didJwsz6MkfKey: Key
+  let didJwsz6MkfCertificate: X509Certificate
   let didJwsz6MkvKey: Key
   let didJwszDnaeyKey: Key
 
@@ -27,14 +28,22 @@ describe('JwsService', () => {
     wallet = new InMemoryWallet()
     agentContext = getAgentContext({
       wallet,
+      registerInstances: [[X509ModuleConfig, new X509ModuleConfig()]],
     })
     await wallet.createAndOpen(config.walletConfig)
 
     jwsService = new JwsService()
+
     didJwsz6MkfKey = await wallet.createKey({
       privateKey: TypedArrayEncoder.fromString(didJwsz6Mkf.SEED),
       keyType: KeyType.Ed25519,
     })
+    didJwsz6MkfCertificate = await X509Service.createCertificate(agentContext, {
+      authorityKey: didJwsz6MkfKey,
+      issuer: {
+        countryName: 'NL',
+      },
+    })
 
     didJwsz6MkvKey = await wallet.createKey({
       privateKey: TypedArrayEncoder.fromString(didJwsz6Mkv.SEED),
@@ -102,6 +111,80 @@ describe('JwsService', () => {
     )
   })
 
+  it('allows both x5c/jwk and kid (no did) to be present', async () => {
+    const payload = JsonEncoder.toBuffer(didJwsz6Mkf.DATA_JSON)
+
+    const signed1 = await jwsService.createJwsCompact(agentContext, {
+      payload,
+      key: didJwsz6MkfKey,
+      protectedHeaderOptions: {
+        alg: JwaSignatureAlgorithm.EdDSA,
+        jwk: getJwkFromKey(didJwsz6MkfKey),
+        kid: 'something',
+      },
+    })
+    const { isValid: isValid1 } = await jwsService.verifyJws(agentContext, {
+      jws: signed1,
+    })
+    expect(isValid1).toEqual(true)
+
+    const signed2 = await jwsService.createJwsCompact(agentContext, {
+      payload,
+      key: didJwsz6MkfKey,
+      protectedHeaderOptions: {
+        alg: JwaSignatureAlgorithm.EdDSA,
+        x5c: [didJwsz6MkfCertificate.toString('base64url')],
+        kid: 'something',
+      },
+    })
+
+    const { isValid: isValid2 } = await jwsService.verifyJws(agentContext, {
+      jws: signed2,
+      trustedCertificates: [didJwsz6MkfCertificate.toString('base64url')],
+    })
+    expect(isValid2).toEqual(true)
+  })
+
+  it('throws error whens signing jws with more than one of x5c, jwk, kid (with did)', async () => {
+    const payload = JsonEncoder.toBuffer(didJwsz6Mkf.DATA_JSON)
+
+    await expect(
+      jwsService.createJwsCompact(agentContext, {
+        payload,
+        key: didJwsz6MkfKey,
+        protectedHeaderOptions: {
+          alg: JwaSignatureAlgorithm.EdDSA,
+          jwk: getJwkFromKey(didJwsz6MkfKey),
+          kid: 'did:example:123',
+        },
+      })
+    ).rejects.toThrow("When 'kid' is a did, 'jwk' and 'x5c' cannot be provided.")
+
+    await expect(
+      jwsService.createJwsCompact(agentContext, {
+        payload,
+        key: didJwsz6MkfKey,
+        protectedHeaderOptions: {
+          alg: JwaSignatureAlgorithm.EdDSA,
+          jwk: getJwkFromKey(didJwsz6MkfKey),
+          x5c: [didJwsz6MkfCertificate.toString('base64url')],
+        },
+      })
+    ).rejects.toThrow("Header must contain one of 'kid' with a did value, 'x5c', or 'jwk'.")
+
+    await expect(
+      jwsService.createJwsCompact(agentContext, {
+        payload,
+        key: didJwsz6MkfKey,
+        protectedHeaderOptions: {
+          alg: JwaSignatureAlgorithm.EdDSA,
+          kid: 'did:example:123',
+          x5c: [didJwsz6MkfCertificate.toString('base64url')],
+        },
+      })
+    ).rejects.toThrow("When 'kid' is a did, 'jwk' and 'x5c' cannot be provided.")
+  })
+
   describe('verifyJws', () => {
     it('returns true if the jws signature matches the payload', async () => {
       const { isValid, signerKeys } = await jwsService.verifyJws(agentContext, {
@@ -149,5 +232,69 @@ describe('JwsService', () => {
         })
       ).rejects.toThrow('Unable to verify JWS, no signatures present in JWS.')
     })
+
+    it('throws error when verifying jws with more than one of x5c, jwk, kid (with did)', async () => {
+      const payload = JsonEncoder.toBuffer(didJwsz6Mkf.DATA_JSON)
+
+      await expect(
+        jwsService.verifyJws(agentContext, {
+          jws: {
+            header: {},
+            protected: JsonEncoder.toBase64URL({
+              alg: JwaSignatureAlgorithm.EdDSA,
+              jwk: getJwkFromKey(didJwsz6MkfKey).toJson(),
+              kid: 'did:example:123',
+            }),
+            payload: '',
+            signature: '',
+          },
+        })
+      ).rejects.toThrow("When 'kid' is a did, 'jwk' and 'x5c' cannot be provided.")
+
+      await expect(
+        jwsService.verifyJws(agentContext, {
+          jws: {
+            header: {},
+            protected: JsonEncoder.toBase64URL({
+              alg: JwaSignatureAlgorithm.EdDSA,
+              jwk: getJwkFromKey(didJwsz6MkfKey).toJson(),
+              kid: 'did:example:123',
+            }),
+            payload: '',
+            signature: '',
+          },
+        })
+      ).rejects.toThrow("When 'kid' is a did, 'jwk' and 'x5c' cannot be provided.")
+
+      await expect(
+        jwsService.verifyJws(agentContext, {
+          jws: {
+            header: {},
+            protected: JsonEncoder.toBase64URL({
+              alg: JwaSignatureAlgorithm.EdDSA,
+              jwk: getJwkFromKey(didJwsz6MkfKey).toJson(),
+              x5c: [didJwsz6MkfCertificate.toString('base64url')],
+            }),
+            payload: '',
+            signature: '',
+          },
+        })
+      ).rejects.toThrow("Header must contain one of 'kid' with a did value, 'x5c', or 'jwk'.")
+
+      await expect(
+        jwsService.verifyJws(agentContext, {
+          jws: {
+            header: {},
+            protected: JsonEncoder.toBase64URL({
+              alg: JwaSignatureAlgorithm.EdDSA,
+              kid: 'did:example:123',
+              x5c: [didJwsz6MkfCertificate.toString('base64url')],
+            }),
+            payload: '',
+            signature: '',
+          },
+        })
+      ).rejects.toThrow("When 'kid' is a did, 'jwk' and 'x5c' cannot be provided.")
+    })
   })
 })

packages/didcomm/package.json

@@ -34,7 +34,7 @@
     "rxjs": "^7.8.0"
   },
   "devDependencies": {
-    "@animo-id/pex": "4.1.1-alpha.0",
+    "@animo-id/pex": "4.1.1-alpha.1",
     "@sphereon/pex-models": "^2.3.1",
     "@types/luxon": "^3.2.0",
     "reflect-metadata": "^0.1.13",