feat: Pass issuer to verifyJWS

src/__tests__/__snapshots__/jws-verification-behavior.test.ts.snap

@@ -3,3 +3,7 @@
 exports[`atTime before DID available for v0 1`] = `"did:3:kjzl6cwe1jw14ah8wjy8grgzl52sl18sbyirgi9bqy9yzu28kbxvjmhip99r14k?version-id=0#7wYNHm3nGoNA3Kv"`;
 
 exports[`atTime ok before rotation 1`] = `"did:3:kjzl6cwe1jw14ah8wjy8grgzl52sl18sbyirgi9bqy9yzu28kbxvjmhip99r14k?version-id=0#7wYNHm3nGoNA3Kv"`;
+
+exports[`issuer includes signer as controller 1`] = `"did:3:kjzl6cwe1jw14ah8wjy8grgzl52sl18sbyirgi9bqy9yzu28kbxvjmhip99r14k?version-id=0#7wYNHm3nGoNA3Kv"`;
+
+exports[`issuer same as signer 1`] = `"did:3:kjzl6cwe1jw14ah8wjy8grgzl52sl18sbyirgi9bqy9yzu28kbxvjmhip99r14k?version-id=0#7wYNHm3nGoNA3Kv"`;

src/__tests__/jws-verification-behavior.test.ts

@@ -129,6 +129,17 @@ const VERSION_NEXT = {
   },
 }
 
+const COMPOSITE_ISSUER_EMPTY = {
+  didResolutionMetadata: {
+    contentType: 'application/did+json',
+  },
+  didDocument: {
+    id: 'did:composite:foo',
+    controller: [],
+  },
+  didDocumentMetadata: {},
+}
+
 // v0: did:3:kjzl6cwe1jw14ah8wjy8grgzl52sl18sbyirgi9bqy9yzu28kbxvjmhip99r14k?version-id=0#7wYNHm3nGoNA3Kv
 const jwsV0 =
   'eyJraWQiOiJkaWQ6MzpranpsNmN3ZTFqdzE0YWg4d2p5OGdyZ3psNTJzbDE4c2J5aXJnaTlicXk5eXp1MjhrYnh2am1oaXA5OXIxNGs_dmVyc2lvbi1pZD0wIzd3WU5IbTNuR29OQTNLdiIsImFsZyI6IkVTMjU2SyJ9.eyJoZWxsbyI6IndvcmxkIn0.cHVXU7QW2pvBJpVIBCLhnkCQ0k4Up3cNRqiyeryRbPOSrZdAoQmWy1OfzNFzgY90nol26KJxHWnknSyu5sY__Q'
@@ -217,3 +228,48 @@ describe('atTime', () => {
     expect(kid).toMatchSnapshot()
   })
 })
+
+describe('issuer', () => {
+  const SIGNER_DID = VERSION_0_VANILLA.didDocument.id
+  const did = new DID()
+
+  beforeEach(() => {
+    did.resolve = jest.fn((didUrl: string) => {
+      if (didUrl === COMPOSITE_ISSUER_EMPTY.didDocument.id) {
+        return Promise.resolve(COMPOSITE_ISSUER_EMPTY)
+      }
+      return Promise.resolve(VERSION_0_VANILLA)
+    })
+  })
+
+  test('same as signer', async () => {
+    const { kid } = await did.verifyJWS(jwsV0, { issuer: SIGNER_DID })
+    expect(kid).toMatchSnapshot()
+  })
+  test('includes signer as controller', async () => {
+    const fauxResolve = jest.fn((didUrl: string) => {
+      if (didUrl === COMPOSITE_ISSUER_EMPTY.didDocument.id) {
+        const included = {
+          ...COMPOSITE_ISSUER_EMPTY,
+          didDocument: {
+            ...COMPOSITE_ISSUER_EMPTY.didDocument,
+            controller: [SIGNER_DID],
+          },
+        }
+        return Promise.resolve(included)
+      }
+      return Promise.resolve(VERSION_0_VANILLA)
+    })
+    did.resolve = fauxResolve
+    const issuer = COMPOSITE_ISSUER_EMPTY.didDocument.id
+    const { kid } = await did.verifyJWS(jwsV0, { issuer: issuer })
+    expect(kid).toMatchSnapshot()
+    expect(fauxResolve).toBeCalledWith(issuer)
+  })
+  test('does not include signer as controller', async () => {
+    const issuer = COMPOSITE_ISSUER_EMPTY.didDocument.id
+    await expect(did.verifyJWS(jwsV0, { issuer: issuer })).rejects.toThrow(
+      /invalid_jws: not a valid verificationMethod for issuer/
+    )
+  })
+})

src/did.ts

@@ -11,6 +11,8 @@ import {
   decodeBase64,
   encodeBase64Url,
   randomString,
+  didWithTime,
+  extractControllers,
 } from './utils'
 
 export interface AuthenticateOptions {
@@ -46,6 +48,11 @@ export interface VerifyJWSOptions {
    * If true, timestamp checking is disabled.
    */
   disableTimecheck?: boolean
+
+  /**
+   * DID that issued the signature.
+   */
+  issuer?: string
 }
 
 export interface VerifyJWSResult {
@@ -236,6 +243,18 @@ export class DID {
       }
     }
 
+    const signerDid = didResolutionResult.didDocument?.id
+    if (options.issuer && options.issuer !== signerDid) {
+      const issuerUrl = didWithTime(options.issuer, options.atTime)
+      const issuerResolution = await this.resolve(issuerUrl)
+      const controllerProperty = issuerResolution.didDocument?.controller
+      const controllers = extractControllers(controllerProperty)
+      const signerIsController = signerDid ? controllers.includes(signerDid) : false
+      if (!signerIsController) {
+        throw new Error(`invalid_jws: not a valid verificationMethod for issuer: ${kid}`)
+      }
+    }
+
     const publicKeys = didResolutionResult.didDocument?.verificationMethod || []
     // verifyJWS will throw an error if the signature is invalid
     verifyJWS(jws, publicKeys)

src/utils.ts

@@ -30,3 +30,34 @@ export function fromDagJWS(jws: DagJWS): string {
   if (jws.signatures.length > 1) throw new Error('Cant convert to compact jws')
   return `${jws.signatures[0].protected}.${jws.payload}.${jws.signatures[0].signature}`
 }
+
+/**
+ * Make DID URL from DID and timestamp (= versionTime query)
+ */
+export function didWithTime(did: string, atTime?: number): string {
+  if (atTime) {
+    const versionTime = new Date(atTime).toISOString().split('.')[0] + 'Z'
+    return `${did}?versionTime=${versionTime}`
+  } else {
+    return did
+  }
+}
+
+/**
+ * `controller` field of DID Document can be one or multiple strings, if defined.
+ * Here we transform it into array of strings.
+ * Potentially it can be an empty array.
+ */
+export function extractControllers(
+  controllerProperty: string | Array<string> | undefined
+): Array<string> {
+  if (controllerProperty) {
+    if (Array.isArray(controllerProperty)) {
+      return controllerProperty
+    } else {
+      return [controllerProperty]
+    }
+  } else {
+    return []
+  }
+}