@sphereon/ssi-sdk-ext.identifier-resolution 0.24.1-unstable.75

package/src/agent/IdentifierResolution.ts

@@ -0,0 +1,69 @@
+import { IAgentContext, IAgentPlugin, IDIDManager, IKeyManager } from '@veramo/core'
+import { getManagedIdentifier } from '../functions'
+
+import {
+  ManagedIdentifierResult,
+  ManagedIdentifierDidOpts,
+  ManagedIdentifierDidResult,
+  ManagedIdentifierJwkOpts,
+  ManagedIdentifierJwkResult,
+  ManagedIdentifierKidOpts,
+  ManagedIdentifierKidResult,
+  ManagedIdentifierOpts,
+  ManagedIdentifierX5cOpts,
+  ManagedIdentifierX5cResult,
+  schema,
+} from '../index'
+import { ExternalIdentifierOpts, IIdentifierResolution } from '../types/IIdentifierResolution'
+
+/**
+ * @public
+ */
+export class IdentifierResolution implements IAgentPlugin {
+  private readonly _crypto: Crypto
+
+  readonly schema = schema.IMnemonicInfoGenerator
+  readonly methods: IIdentifierResolution = {
+    identifierManagedGet: this.identifierGetManaged.bind(this),
+    identifierManagedGetByDid: this.identifierGetManagedByDid.bind(this),
+    identifierManagedGetByKid: this.identifierGetManagedByKid.bind(this),
+    identifierManagedGetByJwk: this.identifierGetManagedByJwk.bind(this),
+    identifierManagedGetByX5c: this.identifierGetManagedByX5c.bind(this),
+
+    identifierExternalResolve: this.identifierResolveExternal.bind(this),
+  }
+
+  /**
+   * TODO: Add a cache, as we are retrieving the same keys/info quite often
+   */
+  constructor({ crypto: cryptoArg }: { crypto: Crypto }) {
+    this._crypto = cryptoArg ?? global.crypto
+  }
+
+  private async identifierGetManaged(args: ManagedIdentifierOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierResult> {
+    return await getManagedIdentifier({ ...args, crypto: this._crypto }, context)
+  }
+
+  private async identifierGetManagedByDid(
+    args: ManagedIdentifierDidOpts,
+    context: IAgentContext<IKeyManager & IDIDManager>
+  ): Promise<ManagedIdentifierDidResult> {
+    return (await this.identifierGetManaged({ ...args, method: 'did' }, context)) as ManagedIdentifierDidResult
+  }
+
+  private async identifierGetManagedByKid(args: ManagedIdentifierKidOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierKidResult> {
+    return (await this.identifierGetManaged({ ...args, method: 'kid' }, context)) as ManagedIdentifierKidResult
+  }
+
+  private async identifierGetManagedByJwk(args: ManagedIdentifierJwkOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierJwkResult> {
+    return (await this.identifierGetManaged({ ...args, method: 'jwk' }, context)) as ManagedIdentifierJwkResult
+  }
+
+  private async identifierGetManagedByX5c(args: ManagedIdentifierX5cOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierX5cResult> {
+    return (await this.identifierGetManaged({ ...args, method: 'x5c' }, context)) as ManagedIdentifierX5cResult
+  }
+
+  private async identifierResolveExternal(args: ExternalIdentifierOpts, context: IAgentContext<IKeyManager>): Promise<any> {
+    return await getManagedIdentifier({ ...args, crypto: this._crypto }, context)
+  }
+}

package/src/functions/index.ts

@@ -0,0 +1,267 @@
+import { didDocumentToJwks, getAgentResolver, getFirstKeyWithRelation } from '@sphereon/ssi-sdk-ext.did-utils'
+import { calculateJwkThumbprint, JWK, toJwk } from '@sphereon/ssi-sdk-ext.key-utils'
+import { getSubjectDN, pemOrDerToX509Certificate, validateX509CertificateChain, X509ValidationResult } from '@sphereon/ssi-sdk-ext.x509-utils'
+import { contextHasDidManager, contextHasKeyManager, contextHasPlugin } from '@sphereon/ssi-sdk.agent-config'
+import { IParsedDID, parseDid } from '@sphereon/ssi-types'
+import { IAgentContext, IDIDManager, IIdentifier, IKey, IKeyManager, IResolver } from '@veramo/core'
+import { Certificate, CryptoEngine, setEngine } from 'pkijs'
+import {
+  ExternalIdentifierDidOpts,
+  ExternalIdentifierDidResult,
+  ExternalIdentifierMethod,
+  ExternalIdentifierOpts,
+  ExternalIdentifierResult,
+  ExternalIdentifierX5cOpts,
+  ExternalIdentifierX5cResult,
+  ExternalJwkInfo,
+  isExternalIdentifierDidOpts,
+  isExternalIdentifierJwksUrlOpts,
+  isExternalIdentifierKidOpts,
+  isExternalIdentifierOidcDiscoveryOpts,
+  isExternalIdentifierX5cOpts,
+  isManagedIdentifierDidOpts,
+  isManagedIdentifierJwkOpts,
+  isManagedIdentifierKidOpts,
+  isManagedIdentifierX5cOpts,
+  ManagedIdentifierOpts,
+  ManagedIdentifierResult,
+} from '../types/IIdentifierResolution'
+
+export async function resolveExternalIdentifier(
+  opts: ExternalIdentifierOpts & {
+    crypto?: Crypto
+  },
+  context: IAgentContext<any>
+): Promise<ExternalIdentifierResult> {
+  let method: ExternalIdentifierMethod | undefined
+  if (isExternalIdentifierDidOpts(opts)) {
+    return resolveExternalDidIdentifier(opts, context)
+  } else if (isExternalIdentifierX5cOpts(opts)) {
+    return resolveExternalX5cIdentifier(opts, context)
+  } else if (isExternalIdentifierKidOpts(opts)) {
+    method = 'kid'
+  } else if (isExternalIdentifierJwksUrlOpts(opts)) {
+    method = 'jwks-url'
+  } else if (isExternalIdentifierOidcDiscoveryOpts(opts)) {
+    method = 'oidc-discovery'
+  }
+  throw Error(`External resolution method ${method} is not yet implemented`)
+}
+
+export async function resolveExternalX5cIdentifier(
+  opts: ExternalIdentifierX5cOpts & {
+    crypto?: Crypto
+  },
+  context: IAgentContext<IResolver & IDIDManager>
+): Promise<ExternalIdentifierX5cResult> {
+  if (!isExternalIdentifierX5cOpts(opts)) {
+    return Promise.reject('External x5c Identifier args need to be provided')
+  }
+  const verify = opts.verify ?? true
+  const x5c = opts.identifier
+  if (x5c.length === 0) {
+    return Promise.reject('Empty certification chain is now allowed')
+  }
+  const certificates = x5c.map(pemOrDerToX509Certificate)
+
+  let verificationResult: X509ValidationResult | undefined
+  let issuerJWK: JWK | undefined
+  let jwks: ExternalJwkInfo[] = []
+
+  if (verify) {
+    // We use the agent plugin if it is available as that is more powerful, but revert to the function otherwise
+    if (contextHasPlugin(context, 'verifyCertificateChain')) {
+      verificationResult = (await context.agent.verifyCertificateChain({
+        chain: opts.identifier,
+        trustAnchors: opts.trustAnchors ?? [],
+        verificationTime: opts.verificationTime,
+      })) as X509ValidationResult // We need to cast, as we know this is the value and we do not want to rely on the x509 plugin perse
+    } else {
+      verificationResult = await validateX509CertificateChain({
+        chain: opts.identifier,
+        trustAnchors: opts.trustAnchors ?? [],
+        verificationTime: opts.verificationTime,
+      })
+    }
+    if (verificationResult.certificateChain) {
+      jwks = verificationResult.certificateChain.map((cert) => {
+        return {
+          jwk: cert.publicKeyJWK,
+          kid: cert.subject.dn.DN,
+          jwkThumbprint: calculateJwkThumbprint(cert.publicKeyJWK),
+        } satisfies ExternalJwkInfo
+      })
+    }
+  }
+  if (!jwks) {
+    const cryptoEngine = new CryptoEngine({
+      name: 'identifier_resolver_external',
+      crypto: opts.crypto ?? global.crypto,
+    })
+    setEngine(cryptoEngine.name, cryptoEngine)
+    jwks = await Promise.all(
+      certificates.map(async (cert) => {
+        const pk = await cert.getPublicKey(undefined, cryptoEngine)
+        const jwk = (await cryptoEngine.exportKey('jwk', pk)) as JWK
+        return {
+          jwk,
+          kid: getSubjectDN(cert).DN,
+          jwkThumbprint: calculateJwkThumbprint({ jwk }),
+        } satisfies ExternalJwkInfo
+      })
+    )
+  }
+  if (jwks.length === 0) {
+    return Promise.reject('Empty certification chain is now allowed')
+  }
+  if (!issuerJWK) {
+    issuerJWK = jwks[0].jwk
+  }
+
+  return {
+    method: 'x5c',
+    verificationResult,
+    issuerJWK,
+    jwks,
+    certificates,
+    x5c,
+  }
+}
+
+export async function resolveExternalDidIdentifier(
+  opts: ExternalIdentifierDidOpts,
+  context: IAgentContext<IResolver & IDIDManager>
+): Promise<ExternalIdentifierDidResult> {
+  if (!isExternalIdentifierDidOpts(opts)) {
+    return Promise.reject('External DID Identifier args need to be provided')
+  } else if (!contextHasPlugin<IResolver & IDIDManager>(context, 'resolveDid')) {
+    return Promise.reject(Error(`Cannot get external DID identifier if DID resolver plugin is not enabled!`))
+  }
+  const { uniresolverResolution = false, localResolution = true, resolverResolution = true } = opts
+  const did = opts.identifier
+  let parsed: IParsedDID
+  try {
+    parsed = parseDid(did)
+  } catch (error: unknown) {
+    // Error from did resolution spec
+    return Promise.reject(error)
+  }
+  const didParsed = parsed
+  const didResolutionResult = await getAgentResolver(context, {
+    uniresolverResolution,
+    localResolution,
+    resolverResolution,
+  }).resolve(did)
+  const didDocument = didResolutionResult.didDocument ?? undefined
+  const didJwks = didDocument ? didDocumentToJwks(didDocument) : undefined
+  const jwks = didJwks
+    ? Array.from(new Set(Object.values(didJwks).flatMap((jwks) => jwks))).map((jwk) => {
+        return { jwk, jwkThumbprint: calculateJwkThumbprint({ jwk }), kid: jwk.kid }
+      })
+    : []
+
+  if (didResolutionResult?.didDocument) {
+    // @ts-ignore // Mandatory on the original object, but we already provide it directly
+    delete didResolutionResult['didDocument']
+  }
+  return {
+    method: 'did',
+    did,
+    jwks,
+    didJwks,
+    didDocument,
+    didResolutionResult,
+    didParsed,
+  }
+}
+
+export async function getManagedIdentifier(
+  opts: ManagedIdentifierOpts & {
+    crypto?: Crypto
+  },
+  context: IAgentContext<IKeyManager>
+): Promise<ManagedIdentifierResult> {
+  let { method } = opts
+  let identifier: IIdentifier | undefined = undefined
+  let keys: IKey[] | undefined = undefined
+  let key: IKey | undefined = undefined
+  let certificate: Certificate | undefined = undefined
+  let jwk: JWK | undefined = undefined
+  let jwkThumbprint: string | undefined = undefined
+  let x5c: string[] | undefined
+  let controllerKeyId: string | undefined = undefined
+  let did: string | undefined = undefined
+  const cryptoImpl = opts.crypto ?? crypto
+  if (isManagedIdentifierKidOpts(opts)) {
+    method = 'kid'
+    if (!contextHasKeyManager(context)) {
+      return Promise.reject(Error(`Cannot get Key/JWK identifier if KeyManager plugin is not enabled!`))
+    }
+    key = await context.agent.keyManagerGet({ kid: opts.kmsKeyRef ?? opts.identifier })
+  } else if (isManagedIdentifierDidOpts(opts)) {
+    method = 'did'
+    if (!contextHasDidManager(context)) {
+      return Promise.reject(Error(`Cannot get DID identifier if DID Manager plugin is not enabled!`))
+    }
+
+    if (typeof opts.identifier === 'string') {
+      identifier = await context.agent.didManagerGet({ did: opts.identifier.split('#')[0] })
+    } else {
+      identifier = opts.identifier
+    }
+    if (identifier) {
+      did = identifier.did
+      keys = identifier?.keys // fixme: We really want to return the vmRelationship keys here actually
+      key = await getFirstKeyWithRelation(
+        {
+          ...opts,
+          identifier,
+          vmRelationship: opts.vmRelationship ?? 'verificationMethod',
+        },
+        context
+      )
+      controllerKeyId = identifier.controllerKeyId
+    }
+  } else if (isManagedIdentifierJwkOpts(opts)) {
+    method = 'jwk'
+    if (!contextHasKeyManager(context)) {
+      return Promise.reject(Error(`Cannot get Key/JWK identifier if KeyManager plugin is not enabled!`))
+    }
+    key = await context.agent.keyManagerGet({ kid: opts.kmsKeyRef ?? calculateJwkThumbprint({ jwk: opts.identifier }) })
+  } else if (isManagedIdentifierX5cOpts(opts)) {
+    method = 'x5c'
+    x5c = opts.identifier
+    if (x5c.length === 0) {
+      return Promise.reject(`Cannot resolve x5c when an empty x5c is passed in`)
+    } else if (!contextHasKeyManager(context)) {
+      return Promise.reject(Error(`Cannot get X5c identifier if KeyManager plugin is not enabled!`))
+    }
+    certificate = pemOrDerToX509Certificate(x5c[0])
+    const cryptoEngine = new CryptoEngine({ name: 'identifier_resolver_managed', crypto: cryptoImpl })
+    setEngine(cryptoEngine.name, cryptoEngine)
+    const pk = await certificate.getPublicKey(undefined, cryptoEngine)
+    jwk = (await cryptoEngine.subtle.exportKey('jwk', pk)) as JWK
+    jwkThumbprint = calculateJwkThumbprint({ jwk })
+    key = await context.agent.keyManagerGet({ kid: opts.kmsKeyRef ?? jwkThumbprint })
+  } else {
+    return Promise.reject(Error(`Could not determine identifier method. Please provide explicitly`))
+  }
+  if (!key || (isManagedIdentifierDidOpts(opts) && !identifier)) {
+    console.log(`Cannot find identifier`, opts.identifier)
+    return Promise.reject(`Cannot find identifier ${opts.identifier}`)
+  }
+  jwk = jwk ?? toJwk(key.publicKeyHex, key.type, { key })
+  const thumbprint = jwkThumbprint ?? key.meta?.jwkThumbprint ?? calculateJwkThumbprint({ jwk })
+  return {
+    method,
+    jwk,
+    jwkThumbprint: thumbprint,
+    ...(identifier && { identifier }),
+    ...(did && { did }),
+    ...(controllerKeyId && { controllerKeyId }),
+    ...(keys && { keys }),
+    ...(certificate && { certificate: certificate.toJSON() }),
+    key,
+    kmsKeyRef: key.kid,
+  } as ManagedIdentifierResult
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @internal
+ */
+const schema = require('../plugin.schema.json')
+export { schema }
+/**
+ * @public
+ */
+export { IdentifierResolution } from './agent/IdentifierResolution'
+export * from './types/IIdentifierResolution'
+export * from './functions'

package/src/types/IIdentifierResolution.ts

@@ -0,0 +1,297 @@
+import { DidDocumentJwks } from '@sphereon/ssi-sdk-ext.did-utils'
+import { JWK } from '@sphereon/ssi-sdk-ext.key-utils'
+import { X509ValidationResult } from '@sphereon/ssi-sdk-ext.x509-utils'
+import { IParsedDID } from '@sphereon/ssi-types'
+import {
+  DIDDocument,
+  DIDDocumentSection,
+  DIDResolutionResult,
+  IAgentContext,
+  IDIDManager,
+  IIdentifier,
+  IKey,
+  IKeyManager,
+  IPluginMethodMap,
+  TKeyType,
+} from '@veramo/core'
+
+/**
+ * @public
+ */
+export interface IIdentifierResolution extends IPluginMethodMap {
+  identifierManagedGet(args: ManagedIdentifierOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierResult>
+
+  identifierManagedGetByDid(args: ManagedIdentifierDidOpts, context: IAgentContext<IKeyManager & IDIDManager>): Promise<ManagedIdentifierDidResult>
+
+  identifierManagedGetByKid(args: ManagedIdentifierKidOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierKidResult>
+
+  identifierManagedGetByJwk(args: ManagedIdentifierJwkOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierJwkResult>
+
+  identifierManagedGetByX5c(args: ManagedIdentifierX5cOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierX5cResult>
+
+  identifierExternalResolve(args: ExternalIdentifierOpts, context: IAgentContext<any>): Promise<any>
+}
+
+/**
+ * Use whenever we need to pass in an identifier. We can pass in kids, DIDs, IIdentifier objects and x5chains
+ *
+ * The functions below can be used to check the type, and they also provide the proper runtime types
+ */
+export type ManagedIdentifierType = IIdentifier /*did*/ | string /*did or kid*/ | string[] /*x5c*/ | JWK
+
+/**
+ * Use whenever we need to resolve an external identifier. We can pass in kids, DIDs, and x5chains
+ *
+ * The functions below can be used to check the type, and they also provide the proper runtime types
+ */
+export type ExternalIdentifierType = string | string[] | JWK
+
+export function isDidIdentifier(identifier: ManagedIdentifierType | ExternalIdentifierType): identifier is IIdentifier | string {
+  return isIIdentifier(identifier) || (typeof identifier === 'string' && identifier.startsWith('did:'))
+}
+
+export function isIIdentifier(identifier: ManagedIdentifierType | ExternalIdentifierType): identifier is IIdentifier {
+  return typeof identifier === 'object' && !Array.isArray(identifier) && 'did' in identifier && 'keys' in identifier
+}
+
+export function isJwkIdentifier(identifier: ManagedIdentifierType | ExternalIdentifierType): identifier is JWK {
+  return typeof identifier === 'object' && !Array.isArray(identifier) && 'kty' in identifier
+}
+
+export function isOidcDiscoveryIdentifier(identifier: ManagedIdentifierType | ExternalIdentifierType): identifier is string {
+  return typeof identifier === 'string' && identifier.startsWith('http') && identifier.endsWith('/.well-known/openid-configuration')
+}
+
+export function isJwksUrlIdentifier(identifier: ManagedIdentifierType | ExternalIdentifierType): identifier is string {
+  return typeof identifier === 'string' && identifier.startsWith('http') && identifier.endsWith('jwks.json')
+}
+
+export function isKidIdentifier(identifier: ManagedIdentifierType | ExternalIdentifierType): identifier is string {
+  return typeof identifier === 'string' && !identifier.startsWith('did:')
+}
+
+export function isX5cIdentifier(identifier: ManagedIdentifierType | ExternalIdentifierType): identifier is string[] {
+  return Array.isArray(identifier) && identifier.length > 0 // todo: Do we want to do additional validation? We know it must be DER and thus hex for instance
+}
+
+export type ExternalIdentifierOptsBase = {
+  method?: ExternalIdentifierMethod // If provided always takes precedences otherwise it will be inferred from the identifier
+  identifier: ExternalIdentifierType
+}
+
+export type ExternalIdentifierDidOpts = Omit<ExternalIdentifierOptsBase, 'method'> & {
+  method?: 'did'
+  identifier: string
+  noVerificationMethodFallback?: boolean
+  vmRelationship?: DIDDocumentSection
+  localResolution?: boolean // Resolve identifiers hosted by the agent
+  uniresolverResolution?: boolean // Resolve identifiers using universal resolver
+  resolverResolution?: boolean // Use registered drivers
+}
+
+export function isExternalIdentifierDidOpts(opts: ExternalIdentifierOptsBase): opts is ExternalIdentifierDidOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'did') || isDidIdentifier(identifier)
+}
+
+export type ExternalIdentifierOpts = (ExternalIdentifierJwkOpts | ExternalIdentifierX5cOpts | ExternalIdentifierDidOpts | ExternalIdentifierKidOpts) &
+  ExternalIdentifierOptsBase
+
+export type ManagedIdentifierOpts = (ManagedIdentifierJwkOpts | ManagedIdentifierX5cOpts | ManagedIdentifierDidOpts | ManagedIdentifierKidOpts) &
+  ManagedIdentifierOptsBase
+
+export type ManagedIdentifierOptsBase = {
+  method?: ManagedIdentifierMethod // If provided always takes precedences otherwise it will be inferred from the identifier
+  identifier: ManagedIdentifierType
+  kmsKeyRef?: string
+}
+
+export type ManagedIdentifierDidOpts = Omit<ManagedIdentifierOptsBase, 'method'> & {
+  method?: 'did'
+  identifier: IIdentifier | string
+  keyType?: TKeyType
+  offlineWhenNoDIDRegistered?: boolean
+  noVerificationMethodFallback?: boolean
+  controllerKey?: boolean
+  vmRelationship?: DIDDocumentSection
+}
+
+export function isManagedIdentifierDidOpts(opts: ManagedIdentifierOptsBase): opts is ManagedIdentifierDidOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'did') || isDidIdentifier(identifier)
+}
+
+export type ExternalIdentifierKidOpts = Omit<ExternalIdentifierOptsBase, 'method'> & {
+  method?: 'kid'
+  identifier: string
+}
+
+export function isExternalIdentifierKidOpts(opts: ExternalIdentifierOptsBase): opts is ExternalIdentifierKidOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'kid') || isKidIdentifier(identifier)
+}
+
+export type ManagedIdentifierKidOpts = Omit<ManagedIdentifierOptsBase, 'method'> & {
+  method?: 'kid'
+  identifier: string
+}
+
+export function isManagedIdentifierKidOpts(opts: ManagedIdentifierOptsBase): opts is ManagedIdentifierKidOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'kid') || isKidIdentifier(identifier)
+}
+
+export type ExternalIdentifierJwkOpts = Omit<ExternalIdentifierOptsBase, 'method'> & {
+  method?: 'jwk'
+  identifier: JWK
+}
+
+export function isExternalIdentifierJwkOpts(opts: ExternalIdentifierOptsBase): opts is ExternalIdentifierJwkOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'jwk') || isJwkIdentifier(identifier)
+}
+
+export type ExternalIdentifierOidcDiscoveryOpts = Omit<ExternalIdentifierOptsBase, 'method'> & {
+  method?: 'oidc-discovery'
+  identifier: string
+}
+
+export function isExternalIdentifierOidcDiscoveryOpts(opts: ExternalIdentifierOptsBase): opts is ExternalIdentifierJwkOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'oidc-discovery') || isOidcDiscoveryIdentifier(identifier)
+}
+
+export type ExternalIdentifierJwksUrlOpts = Omit<ExternalIdentifierOptsBase, 'method'> & {
+  method?: 'jwks-url'
+  identifier: string
+}
+
+export function isExternalIdentifierJwksUrlOpts(opts: ExternalIdentifierOptsBase): opts is ExternalIdentifierJwksUrlOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'oidc-discovery') || isJwksUrlIdentifier(identifier)
+}
+
+export type ManagedIdentifierJwkOpts = Omit<ManagedIdentifierOptsBase, 'method'> & {
+  method?: 'jwk'
+  identifier: JWK
+}
+
+export function isManagedIdentifierJwkOpts(opts: ManagedIdentifierOptsBase): opts is ManagedIdentifierJwkOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'jwk') || isJwkIdentifier(identifier)
+}
+
+export type ExternalIdentifierX5cOpts = Omit<ExternalIdentifierOptsBase, 'method'> & {
+  method?: 'x5c'
+  identifier: string[]
+  verify: boolean
+  verificationTime?: Date
+  trustAnchors?: string[]
+}
+
+export function isExternalIdentifierX5cOpts(opts: ExternalIdentifierOptsBase): opts is ExternalIdentifierX5cOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'x5c') || isX5cIdentifier(identifier)
+}
+
+export type ManagedIdentifierX5cOpts = Omit<ManagedIdentifierOptsBase, 'method'> & {
+  method?: 'x5c'
+  identifier: string[]
+}
+
+export function isManagedIdentifierX5cOpts(opts: ManagedIdentifierOptsBase): opts is ManagedIdentifierX5cOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'x5c') || isX5cIdentifier(identifier)
+}
+
+export type ExternalIdentifierMethod = 'did' | 'jwk' | 'x5c' | 'kid' | 'oidc-discovery' | 'jwks-url' | 'oid4vci-issuer'
+
+export type ExternalIdentifierResult = ExternalIdentifierDidResult | ExternalIdentifierX5cResult
+
+export type ManagedIdentifierMethod = 'did' | 'jwk' | 'x5c' | 'kid'
+
+export type ManagedIdentifierResult =
+  | ManagedIdentifierX5cResult
+  | ManagedIdentifierDidResult
+  | ManagedIdentifierJwkResult
+  | ManagedIdentifierKidResult
+
+export interface IExternalIdentifierResultBase {
+  method: ExternalIdentifierMethod
+  jwks: Array<ExternalJwkInfo>
+}
+
+export interface JwkInfo {
+  jwk: JWK
+  jwkThumbprint: string
+}
+
+export interface ExternalJwkInfo extends JwkInfo {
+  kid?: string
+}
+
+export interface ManagedJwkInfo extends JwkInfo {
+  kmsKeyRef: string
+}
+
+export interface IManagedIdentifierResultBase extends ManagedJwkInfo {
+  method: ManagedIdentifierMethod
+  key: IKey
+}
+
+export function isManagedIdentifierDidResult(object: IManagedIdentifierResultBase): object is ManagedIdentifierDidResult {
+  return object!! && typeof object === 'object' && 'method' in object && object.method === 'did'
+}
+
+export function isManagedIdentifierX5cResult(object: IManagedIdentifierResultBase): object is ManagedIdentifierDidResult {
+  return object!! && typeof object === 'object' && 'method' in object && object.method === 'x5c'
+}
+
+export function isManagedIdentifierJwkResult(object: IManagedIdentifierResultBase): object is ManagedIdentifierJwkResult {
+  return object!! && typeof object === 'object' && 'method' in object && object.method === 'jwk'
+}
+
+export function isManagedIdentifierKidResult(object: IManagedIdentifierResultBase): object is ManagedIdentifierKidResult {
+  return object!! && typeof object === 'object' && 'method' in object && object.method === 'kid'
+}
+
+export interface ExternalIdentifierDidResult extends IExternalIdentifierResultBase {
+  method: 'did'
+  did: string
+  didDocument?: DIDDocument
+  didJwks?: DidDocumentJwks
+  didResolutionResult: Omit<DIDResolutionResult, 'didDocument'> // we already provide that directly
+  didParsed: IParsedDID
+}
+
+export interface ManagedIdentifierDidResult extends IManagedIdentifierResultBase {
+  method: 'did'
+  identifier: IIdentifier
+  did: string
+  // key: IKey // The key associated with the requested did method sections. Controller key in case of no DID method section requested
+  keys: Array<IKey> // If there is more than one key for the VM relationship.
+  verificationMethodSection?: DIDDocumentSection
+  controllerKeyId: string
+}
+
+export interface ManagedIdentifierJwkResult extends IManagedIdentifierResultBase {
+  method: 'jwk'
+}
+
+export interface ManagedIdentifierKidResult extends IManagedIdentifierResultBase {
+  method: 'kid'
+}
+
+export interface ExternalIdentifierX5cResult extends IExternalIdentifierResultBase {
+  method: 'x5c'
+  x5c: string[]
+  issuerJWK: JWK
+  verificationResult?: X509ValidationResult
+  certificates: any[] // for now since our schema generator trips on pkijs Certificate(Json) object //fixme
+}
+
+export interface ManagedIdentifierX5cResult extends IManagedIdentifierResultBase {
+  method: 'x5c'
+  x5c: string[]
+  certificate: any // Certificate(JSON_, but trips schema generator. Probably want to create our own DTO
+}