@sphereon/ssi-sdk.linked-vp 0.34.1-feature.SSISDK.82.linkedVP.325

package/plugin.schema.json

@@ -0,0 +1,183 @@
+{
+  "ILinkedVPManager": {
+    "components": {
+      "schemas": {
+        "GeneratePresentationArgs": {
+          "type": "object",
+          "properties": {
+            "linkedVpId": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "linkedVpId"
+          ],
+          "additionalProperties": false
+        },
+        "LinkedVPPresentation": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "$ref": "#/components/schemas/Record<string,any>"
+            }
+          ]
+        },
+        "Record<string,any>": {
+          "type": "object"
+        },
+        "GetServiceEntriesArgs": {
+          "type": "object",
+          "properties": {
+            "tenantId": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
+        "LinkedVPServiceEntry": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "type": {
+              "type": "string",
+              "const": "LinkedVerifiablePresentation"
+            },
+            "serviceEndpoint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "id",
+            "type",
+            "serviceEndpoint"
+          ],
+          "additionalProperties": false
+        },
+        "HasLinkedVPEntryArgs": {
+          "type": "object",
+          "properties": {
+            "linkedVpId": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "linkedVpId"
+          ],
+          "additionalProperties": false
+        },
+        "PublishCredentialArgs": {
+          "type": "object",
+          "properties": {
+            "digitalCredentialId": {
+              "type": "string"
+            },
+            "linkedVpId": {
+              "type": "string"
+            },
+            "tenantId": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "digitalCredentialId"
+          ],
+          "additionalProperties": false
+        },
+        "LinkedVPEntry": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "linkedVpId": {
+              "type": "string"
+            },
+            "tenantId": {
+              "type": "string"
+            },
+            "linkedVpFrom": {
+              "type": "string",
+              "format": "date-time"
+            },
+            "createdAt": {
+              "type": "string",
+              "format": "date-time"
+            }
+          },
+          "required": [
+            "id",
+            "linkedVpId",
+            "createdAt"
+          ],
+          "additionalProperties": false
+        },
+        "UnpublishCredentialArgs": {
+          "type": "object",
+          "properties": {
+            "linkedVpId": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "linkedVpId"
+          ],
+          "additionalProperties": false
+        }
+      },
+      "methods": {
+        "lvpGeneratePresentation": {
+          "description": "Generate and return a Verifiable Presentation for a published LinkedVP This is the main endpoint handler for GET /linked-vp/",
+          "arguments": {
+            "$ref": "#/components/schemas/GeneratePresentationArgs"
+          },
+          "returnType": {
+            "$ref": "#/components/schemas/LinkedVPPresentation"
+          }
+        },
+        "lvpGetServiceEntries": {
+          "description": "Get LinkedVP service entries for a DID to be added to a DID Document This is useful when generating DID Documents with toDidDocument",
+          "arguments": {
+            "$ref": "#/components/schemas/GetServiceEntriesArgs"
+          },
+          "returnType": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/LinkedVPServiceEntry"
+            }
+          }
+        },
+        "lvpHasEntry": {
+          "description": "Check if a LinkedVP entry exists by linkedVpId",
+          "arguments": {
+            "$ref": "#/components/schemas/HasLinkedVPEntryArgs"
+          },
+          "returnType": {
+            "type": "boolean"
+          }
+        },
+        "lvpPublishCredential": {
+          "description": "Publish a credential as a LinkedVP by adding it to the holder's DID Document",
+          "arguments": {
+            "$ref": "#/components/schemas/PublishCredentialArgs"
+          },
+          "returnType": {
+            "$ref": "#/components/schemas/LinkedVPEntry"
+          }
+        },
+        "lvpUnpublishCredential": {
+          "description": "Unpublish a credential by removing its LinkedVP entry from the DID Document",
+          "arguments": {
+            "$ref": "#/components/schemas/UnpublishCredentialArgs"
+          },
+          "returnType": {
+            "type": "boolean"
+          }
+        }
+      }
+    }
+  }
+}

package/src/__tests__/localAgent.test.ts

@@ -0,0 +1,95 @@
+import { IdentifierResolution } from '@sphereon/ssi-sdk-ext.identifier-resolution'
+import { SphereonKeyManager } from '@sphereon/ssi-sdk-ext.key-manager'
+import { SphereonKeyManagementSystem } from '@sphereon/ssi-sdk-ext.kms-local'
+import { CredentialStore } from '@sphereon/ssi-sdk.credential-store'
+import { VcdmCredentialPlugin } from '@sphereon/ssi-sdk.credential-vcdm'
+import { CredentialProviderJWT } from '@sphereon/ssi-sdk.credential-vcdm1-jwt-provider'
+
+import { DigitalCredentialEntity, DigitalCredentialStore } from '@sphereon/ssi-sdk.data-store'
+
+import { Agent } from '@veramo/core'
+import { DIDManager, MemoryDIDStore } from '@veramo/did-manager'
+import { WebDIDProvider } from '@veramo/did-provider-web'
+import { MemoryKeyStore, MemoryPrivateKeyStore } from '@veramo/key-manager'
+import { DataSource } from 'typeorm'
+import { describe } from 'vitest'
+import { LinkedVPManager } from '../agent/LinkedVPManager'
+import linkedVPManagerAgentLogic from './shared/linkedVPManagerAgentLogic'
+
+let agent: any
+
+const setup = async () => {
+  const db = new DataSource({
+    type: 'sqlite',
+    database: ':memory:',
+    synchronize: true,
+    entities: [DigitalCredentialEntity],
+  })
+  await db.initialize()
+
+  const digitalStore = new DigitalCredentialStore(db)
+  const jwt = new CredentialProviderJWT()
+
+  const plugins = [
+    new CredentialStore({ store: digitalStore }),
+
+    new SphereonKeyManager({
+      store: new MemoryKeyStore(),
+      kms: {
+        local: new SphereonKeyManagementSystem(new MemoryPrivateKeyStore()),
+      },
+    }),
+
+    new DIDManager({
+      store: new MemoryDIDStore(),
+      defaultProvider: 'did:web',
+      providers: {
+        [`did:web`]: new WebDIDProvider({
+          defaultKms: 'local',
+        }),
+      },
+    }),
+
+    new IdentifierResolution(),
+
+    new LinkedVPManager({
+      holderDids: {
+        default: 'did:web:example.com',
+        tenant1: 'did:web:example.com:tenants:tenant1',
+      },
+    }),
+
+    new VcdmCredentialPlugin({ issuers: [jwt] }),
+  ]
+
+  agent = new Agent({
+    plugins,
+  })
+
+  // Create tenant DIDs
+  await agent.didManagerImport({
+    did: 'did:web:example.com:tenants:tenant1',
+    provider: 'did:web',
+    keys: [
+      {
+        kid: 'key-1',
+        type: 'Secp256r1',
+        privateKeyHex:
+          '078c0f0eaa6510fab9f4f2cf8657b32811c53d7d98869fd0d5bd08a7ba34376b8adfdd44784dea407e088ff2437d5e2123e685a26dca91efceb7a9f4dfd81848',
+        publicKeyHex: '8adfdd44784dea407e088ff2437d5e2123e685a26dca91efceb7a9f4dfd81848',
+        kms: 'local',
+      },
+    ],
+  })
+
+  return true
+}
+
+const tearDown = async () => true
+const getAgent = () => agent
+
+const testContext = { getAgent, setup, tearDown, isRestTest: false }
+
+describe('LinkedVP Manager Local integration tests', () => {
+  linkedVPManagerAgentLogic(testContext)
+})

package/src/__tests__/shared/linkedVPManagerAgentLogic.ts

@@ -0,0 +1,170 @@
+import { CredentialRole } from '@sphereon/ssi-types'
+import { TAgent } from '@veramo/core'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { ILinkedVPManager } from '../../index'
+
+type ConfiguredAgent = TAgent<ILinkedVPManager>
+
+const holderDid = 'did:web:example.com'
+const tenantId = 'tenant1'
+const holderDidWithTenant = 'did:web:example.com:tenants:tenant1'
+
+function createMockVC(typeSuffix: string) {
+  return {
+    '@context': ['https://www.w3.org/2018/credentials/v1'],
+    type: ['VerifiableCredential', typeSuffix],
+    issuer: 'did:web:issuer.com',
+    issuanceDate: new Date().toISOString(),
+    credentialSubject: {
+      id: holderDid,
+      value: `value-${Math.random().toString(36).slice(2)}`,
+    },
+  }
+}
+
+async function createTestCredential(agent: ConfiguredAgent, tenantId: string) {
+  const mockVC = createMockVC('TestCredential')
+
+  const created = await agent.crsAddCredential({
+    credential: {
+      credentialRole: CredentialRole.HOLDER,
+      rawDocument: JSON.stringify(mockVC),
+      issuerCorrelationType: 'DID' as any,
+      issuerCorrelationId: 'did:web:issuer.com',
+      kmsKeyRef: 'mock-key-ref',
+      identifierMethod: 'did:web',
+      tenantId,
+    },
+  })
+
+  return created.id
+}
+
+export default (testContext: {
+  getAgent: () => ConfiguredAgent
+  setup: () => Promise<boolean>
+  tearDown: () => Promise<boolean>
+  isRestTest: boolean
+}): void => {
+  describe('LinkedVP Manager Agent Plugin', (): void => {
+    let agent: ConfiguredAgent
+
+    beforeAll(async (): Promise<void> => {
+      await testContext.setup()
+      agent = testContext.getAgent()
+    })
+
+    afterAll(testContext.tearDown)
+
+    it('should publish credential with auto-generated linkedVpId INCLUDING tenant suffix', async () => {
+      const credentialId = await createTestCredential(agent, tenantId)
+
+      const result = await agent.lvpPublishCredential({
+        digitalCredentialId: credentialId,
+      })
+
+      expect(result.linkedVpId).toMatch(/^lvp-\d+-[a-z0-9]+@tenant1$/)
+    })
+
+    it('should publish credential with custom linkedVpId AND append tenantId', async () => {
+      const credentialId = await createTestCredential(agent, tenantId)
+      const customLinkedVpId = 'my-custom-lvp-id'
+
+      const result = await agent.lvpPublishCredential({
+        digitalCredentialId: credentialId,
+        linkedVpId: customLinkedVpId,
+      })
+
+      expect(result.linkedVpId).toBe('my-custom-lvp-id@tenant1')
+    })
+
+    it('should fail to publish already published credential', async () => {
+      const credentialId = await createTestCredential(agent, tenantId)
+      const linkedVpId = 'already-published'
+
+      await agent.lvpPublishCredential({
+        digitalCredentialId: credentialId,
+        linkedVpId,
+      })
+
+      await expect(
+        agent.lvpPublishCredential({
+          digitalCredentialId: credentialId,
+          linkedVpId: 'different-id',
+        }),
+      ).rejects.toThrow(/already published/)
+    })
+
+    it('should fail to publish duplicate linkedVpId (after tenant appending)', async () => {
+      const cred1 = await createTestCredential(agent, tenantId)
+      const cred2 = await createTestCredential(agent, tenantId)
+      const duplicateId = 'duplicate-lvp-id'
+
+      await agent.lvpPublishCredential({ digitalCredentialId: cred1, linkedVpId: duplicateId })
+
+      await expect(
+        agent.lvpPublishCredential({
+          digitalCredentialId: cred2,
+          linkedVpId: duplicateId,
+        }),
+      ).rejects.toThrow(/already exists/)
+    })
+
+    it('should unpublish a credential', async () => {
+      const credentialId = await createTestCredential(agent, tenantId)
+      const linkedVpId = 'to-be-unpublished'
+
+      await agent.lvpPublishCredential({
+        digitalCredentialId: credentialId,
+        linkedVpId,
+      })
+
+      const result = await agent.lvpUnpublishCredential({
+        linkedVpId: `${linkedVpId}@tenant1`,
+      })
+
+      expect(result).toBe(true)
+    })
+
+    it('should get service entries for default tenant (no tenantId param)', async () => {
+      const id1 = await createTestCredential(agent, tenantId)
+      const id2 = await createTestCredential(agent, tenantId)
+
+      await agent.lvpPublishCredential({ digitalCredentialId: id1, linkedVpId: 'service1' })
+      await agent.lvpPublishCredential({ digitalCredentialId: id2, linkedVpId: 'service2' })
+
+      const entries = await agent.lvpGetServiceEntries({})
+
+      expect(entries).toEqual(
+        expect.arrayContaining([
+          {
+            id: `${holderDidWithTenant}#service1@tenant1`,
+            type: 'LinkedVerifiablePresentation',
+            serviceEndpoint: `https://example.com/tenants/tenant1/linked-vp/service1@tenant1`,
+          },
+          {
+            id: `${holderDidWithTenant}#service2@tenant1`,
+            type: 'LinkedVerifiablePresentation',
+            serviceEndpoint: `https://example.com/tenants/tenant1/linked-vp/service2@tenant1`,
+          },
+        ]),
+      )
+    })
+
+    /* TODO, did:web may be complicated in a test
+    it('should generate presentation for published credentials', async () => {
+      const credentialId = await createTestCredential(agent, tenantId)
+      const baseId = 'presentation-test'
+
+      await agent.lvpPublishCredential({
+        digitalCredentialId: credentialId,
+        linkedVpId: baseId,
+      })
+
+      const fullLinkedVpId = `${baseId}@tenant1`
+
+      const vp = await agent.lvpGeneratePresentation({ linkedVpId: fullLinkedVpId })
+      expect(vp).toBeDefined()
+    })*/
+  })
+}

package/src/agent/LinkedVPManager.ts

@@ -0,0 +1,221 @@
+import { DigitalCredential } from '@sphereon/ssi-sdk.data-store-types'
+import { IAgentPlugin } from '@veramo/core'
+import { IsNull, Not } from 'typeorm'
+import { schema } from '../index'
+import { createLinkedVPPresentation } from '../services/LinkedVPService'
+import {
+  GeneratePresentationArgs,
+  GetServiceEntriesArgs,
+  HasLinkedVPEntryArgs,
+  ILinkedVPManager,
+  LinkedVPEntry,
+  LinkedVPPresentation,
+  LinkedVPServiceEntry,
+  PublishCredentialArgs,
+  RequiredContext,
+  UnpublishCredentialArgs,
+} from '../types'
+
+// Exposing the methods here for any REST implementation
+export const linkedVPManagerMethods: Array<string> = [
+  'lvpPublishCredential',
+  'lvpUnpublishCredential',
+  'lvpHasEntry',
+  'lvpGetServiceEntries',
+  'lvpGeneratePresentation',
+]
+
+/**
+ * {@inheritDoc ILinkedVPManager}
+ */
+export class LinkedVPManager implements IAgentPlugin {
+  readonly schema = schema.ILinkedVPManager
+  readonly methods: ILinkedVPManager = {
+    lvpPublishCredential: this.lvpPublishCredential.bind(this),
+    lvpUnpublishCredential: this.lvpUnpublishCredential.bind(this),
+    lvpHasEntry: this.lvpHasEntry.bind(this),
+    lvpGetServiceEntries: this.lvpGetServiceEntries.bind(this),
+    lvpGeneratePresentation: this.lvpGeneratePresentation.bind(this),
+  }
+
+  private readonly holderDids: Record<string, string>
+
+  constructor(options: { holderDids: Record<string, string> }) {
+    this.holderDids = options.holderDids
+  }
+
+  private async lvpPublishCredential(args: PublishCredentialArgs, context: RequiredContext): Promise<LinkedVPEntry> {
+    const { digitalCredentialId } = args
+
+    const credential: DigitalCredential = await context.agent.crsGetCredential({ id: digitalCredentialId })
+
+    if (credential.linkedVpId) {
+      return Promise.reject(new Error(`Credential ${digitalCredentialId} is already published with linkedVpId ${credential.linkedVpId}`))
+    }
+
+    const linkedVpId = this.buildLinkedVpId(args.linkedVpId, credential.tenantId)
+
+    await this.ensureLinkedVpIdUnique(linkedVpId, context, credential.tenantId)
+
+    const publishedAt = new Date()
+    await context.agent.crsUpdateCredential({
+      id: digitalCredentialId,
+      linkedVpId,
+      linkedVpFrom: publishedAt,
+    })
+
+    return {
+      id: credential.id,
+      linkedVpId,
+      tenantId: credential.tenantId,
+      linkedVpFrom: publishedAt,
+      createdAt: credential.createdAt,
+    }
+  }
+
+  private async lvpUnpublishCredential(args: UnpublishCredentialArgs, context: RequiredContext): Promise<boolean> {
+    const { linkedVpId } = args
+
+    // Find credential by linkedVpId and tenantId
+    const credentials = await context.agent.crsGetCredentials({
+      filter: [{ linkedVpId }],
+    })
+    if (credentials.length === 0) {
+      return Promise.reject(Error(`No credential found with linkedVpId ${linkedVpId}`))
+    }
+
+    const credential = credentials[0]
+    await context.agent.crsUpdateCredential({
+      id: credential.id,
+      linkedVpId: undefined,
+      linkedVpFrom: undefined,
+    })
+
+    return true
+  }
+
+  private async lvpHasEntry(args: HasLinkedVPEntryArgs, context: RequiredContext): Promise<boolean> {
+    const { linkedVpId } = args
+
+    try {
+      const credentials = await context.agent.crsGetCredentials({
+        filter: [{ linkedVpId }],
+      })
+      return credentials.length > 0
+    } catch (error) {
+      return false
+    }
+  }
+
+  private async lvpGetServiceEntries(args: GetServiceEntriesArgs, context: RequiredContext): Promise<Array<LinkedVPServiceEntry>> {
+    const { tenantId } = args
+
+    // Get all published credentials (credentials with linkedVpId set)
+    const filter: any = { linkedVpId: Not(IsNull()) }
+    if (tenantId) {
+      filter.tenantId = tenantId
+    }
+
+    const credentials = await context.agent.crsGetCredentials({
+      filter: [filter],
+    })
+
+    return credentials
+      .filter((cred) => cred.linkedVpId !== undefined && cred.linkedVpId !== null)
+      .map((cred) => {
+        const holderDidForEntry = this.getHolderDid(cred.tenantId)
+        return this.credentialToServiceEntry(cred, holderDidForEntry)
+      })
+  }
+
+  private async lvpGeneratePresentation(args: GeneratePresentationArgs, context: RequiredContext): Promise<LinkedVPPresentation> {
+    const { linkedVpId } = args
+    const tenantId = this.parseTenantFromLinkedVpId(linkedVpId)
+    const holderDid = this.getHolderDid(tenantId)
+
+    const uniqueCredentials = await context.agent.crsGetUniqueCredentials({
+      filter: [
+        {
+          linkedVpId: args.linkedVpId,
+          ...(tenantId && { tenantId }),
+        },
+      ],
+    })
+    if (uniqueCredentials.length === 0) {
+      return Promise.reject(Error(`No published credentials found for linkedVpId ${linkedVpId}`))
+    }
+
+    // Generate the Verifiable Presentation with all published credentials
+    return createLinkedVPPresentation(holderDid, uniqueCredentials, context.agent)
+  }
+
+  private getHolderDid(tenantId: string | undefined) {
+    const holderDid = this.holderDids[tenantId ?? 'default']
+    if (!holderDid) {
+      throw Error(`No holder did supplied for tenant ${tenantId ?? 'default'}`)
+    }
+    return holderDid
+  }
+
+  private parseTenantFromLinkedVpId(linkedVpId: string): string | undefined {
+    const idx = linkedVpId.lastIndexOf('@')
+    return idx === -1 ? undefined : linkedVpId.substring(idx + 1)
+  }
+
+  private generateLinkedVpId(): string {
+    return `lvp-${Date.now()}-${Math.random().toString(36).substring(2, 15)}`
+  }
+
+  private async ensureLinkedVpIdUnique(linkedVpId: string, context: RequiredContext, tenantId?: string): Promise<void> {
+    const credentials = await context.agent.crsGetCredentials({
+      filter: [{ linkedVpId, ...(tenantId && { tenantId }) }],
+    })
+
+    if (credentials.length > 0) {
+      throw new Error(`LinkedVP ID ${linkedVpId} already exists${tenantId ? ` for tenant ${tenantId}` : ''}`)
+    }
+  }
+
+  private buildLinkedVpId(linkedVpId: string | undefined, tenantId: string | undefined) {
+    let finalLinkedVpId = linkedVpId || this.generateLinkedVpId()
+
+    // Append tenantId if provided and not already present
+    if (tenantId && tenantId !== '' && !finalLinkedVpId.includes('@')) {
+      finalLinkedVpId = `${finalLinkedVpId}@${tenantId}`
+    }
+    return finalLinkedVpId
+  }
+
+  private getBaseUrlFromDid(holderDid: string): string {
+    if (!holderDid.startsWith('did:web:')) {
+      throw new Error(`Invalid DID: ${holderDid}, must be did:web`)
+    }
+
+    const withoutPrefix = holderDid.replace('did:web:', '') // example.com:tenants:tenant1
+    const parts = withoutPrefix.split(':')
+    const domain = parts.shift()! // example.com
+    const path = parts.join('/') // tenants/tenant1
+
+    return path
+      ? `https://${domain}/${path}` // https://example.com/tenants/tenant1
+      : `https://${domain}` // https://example.com
+  }
+
+  private buildServiceEndpoint(holderDid: string, linkedVpId: string): string {
+    const baseUrl = this.getBaseUrlFromDid(holderDid)
+    const cleanBaseUrl = baseUrl.endsWith('/') ? baseUrl.slice(0, -1) : baseUrl
+    return `${cleanBaseUrl}/linked-vp/${linkedVpId}`
+  }
+
+  private credentialToServiceEntry(credential: DigitalCredential, holderDid: string): LinkedVPServiceEntry {
+    if (!credential.linkedVpId) {
+      throw new Error(`Credential ${credential.id} does not have a linkedVpId`)
+    }
+
+    return {
+      id: `${holderDid}#${credential.linkedVpId}`,
+      type: 'LinkedVerifiablePresentation',
+      serviceEndpoint: this.buildServiceEndpoint(holderDid, credential.linkedVpId),
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @public
+ */
+import schema from '../plugin.schema.json'
+export { schema }
+export { LinkedVPManager, linkedVPManagerMethods } from './agent/LinkedVPManager'
+export * from './types/ILinkedVPManager'