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

package/src/functions/managedIdentifierFunctions.ts

@@ -0,0 +1,178 @@
+import { getFirstKeyWithRelation } from '@sphereon/ssi-sdk-ext.did-utils'
+import { calculateJwkThumbprint, JWK, toJwk } from '@sphereon/ssi-sdk-ext.key-utils'
+import { pemOrDerToX509Certificate } from '@sphereon/ssi-sdk-ext.x509-utils'
+import { contextHasDidManager, contextHasKeyManager } from '@sphereon/ssi-sdk.agent-config'
+import { IAgentContext, IIdentifier, IKeyManager } from '@veramo/core'
+import { CryptoEngine, setEngine } from 'pkijs'
+import {
+  isManagedIdentifierDidOpts,
+  isManagedIdentifierDidResult,
+  isManagedIdentifierJwkOpts,
+  isManagedIdentifierKidOpts,
+  isManagedIdentifierX5cOpts,
+  ManagedIdentifierDidOpts,
+  ManagedIdentifierDidResult,
+  ManagedIdentifierJwkOpts,
+  ManagedIdentifierJwkResult,
+  ManagedIdentifierKidOpts,
+  ManagedIdentifierKidResult,
+  ManagedIdentifierOpts,
+  ManagedIdentifierResult,
+  ManagedIdentifierX5cOpts,
+  ManagedIdentifierX5cResult,
+} from '../types'
+
+export async function getManagedKidIdentifier(
+  opts: ManagedIdentifierKidOpts,
+  context: IAgentContext<IKeyManager>
+): Promise<ManagedIdentifierKidResult> {
+  const method = 'kid'
+  if (!contextHasKeyManager(context)) {
+    return Promise.reject(Error(`Cannot get Key/JWK identifier if KeyManager plugin is not enabled!`))
+  }
+  const key = await context.agent.keyManagerGet({ kid: opts.kmsKeyRef ?? opts.identifier })
+  const jwk = toJwk(key.publicKeyHex, key.type, { key })
+  const jwkThumbprint = (key.meta?.jwkThumbprint as string) ?? calculateJwkThumbprint({ jwk })
+  const kid = opts.kid ?? (key.meta?.verificationMethod?.id as string) ?? jwkThumbprint
+  const issuer = opts.issuer ?? kid // The different identifiers should set the value. Defaults to the kid
+  return {
+    method,
+    key,
+    jwk,
+    jwkThumbprint,
+    kid,
+    issuer,
+    kmsKeyRef: key.kid,
+  } satisfies ManagedIdentifierKidResult
+}
+
+export async function getManagedDidIdentifier(opts: ManagedIdentifierDidOpts, context: IAgentContext<any>): Promise<ManagedIdentifierDidResult> {
+  const method = 'did'
+  if (!contextHasDidManager(context)) {
+    return Promise.reject(Error(`Cannot get DID identifier if DID Manager plugin is not enabled!`))
+  }
+
+  let identifier: IIdentifier
+  if (typeof opts.identifier === 'string') {
+    identifier = await context.agent.didManagerGet({ did: opts.identifier.split('#')[0] })
+  } else {
+    identifier = opts.identifier
+  }
+
+  const did = identifier.did
+  const keys = identifier?.keys // fixme: We really want to return the vmRelationship keys here actually
+  const extendedKey = await getFirstKeyWithRelation(
+    {
+      ...opts,
+      identifier,
+      vmRelationship: opts.vmRelationship ?? 'verificationMethod',
+    },
+    context
+  )
+  const key = extendedKey
+  const controllerKeyId = identifier.controllerKeyId
+  const jwk = toJwk(key.publicKeyHex, key.type, { key })
+  const jwkThumbprint = key.meta?.jwkThumbprint ?? calculateJwkThumbprint({ jwk })
+  const kid = opts.kid ?? extendedKey.meta?.verificationMethod?.id
+  const issuer = opts.issuer ?? did
+  return {
+    method,
+    key,
+    did,
+    kmsKeyRef: key.kid,
+    jwk,
+    jwkThumbprint,
+    controllerKeyId,
+    kid,
+    keys,
+    issuer,
+    identifier,
+  }
+}
+
+export async function getManagedJwkIdentifier(
+  opts: ManagedIdentifierJwkOpts,
+  context: IAgentContext<IKeyManager>
+): Promise<ManagedIdentifierJwkResult> {
+  const method = 'jwk'
+  const { kid, issuer } = opts
+  if (!contextHasKeyManager(context)) {
+    return Promise.reject(Error(`Cannot get Key/JWK identifier if KeyManager plugin is not enabled!`))
+  }
+  const key = await context.agent.keyManagerGet({ kid: opts.kmsKeyRef ?? calculateJwkThumbprint({ jwk: opts.identifier }) })
+  const jwk = opts.identifier ?? toJwk(key.publicKeyHex, key.type, { key })
+  const jwkThumbprint = (key.meta?.jwkThumbprint as string) ?? calculateJwkThumbprint({ jwk })
+  // we explicitly do not set the kid and issuer, meaning it can remain null. Normally you do not provide a kid and issuer with Jwks.
+  return {
+    method,
+    key,
+    kmsKeyRef: key.kid,
+    jwk,
+    jwkThumbprint,
+    kid,
+    issuer,
+  } satisfies ManagedIdentifierJwkResult
+}
+
+export async function getManagedX5cIdentifier(
+  opts: ManagedIdentifierX5cOpts & {
+    crypto?: Crypto
+  },
+  context: IAgentContext<IKeyManager>
+): Promise<ManagedIdentifierX5cResult> {
+  const { kid, issuer } = opts
+  const method = 'x5c'
+  const 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!`))
+  }
+  const cryptoImpl = opts.crypto ?? crypto
+  const 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)
+  const jwk = (await cryptoEngine.subtle.exportKey('jwk', pk)) as JWK
+  const jwkThumbprint = calculateJwkThumbprint({ jwk })
+  const key = await context.agent.keyManagerGet({ kid: opts.kmsKeyRef ?? jwkThumbprint })
+  // we explicitly do not set the kid and issuer, meaning it can remain null. Normally you do not provide a kid and issuer with x5c.
+
+  return {
+    method,
+    x5c,
+    certificate,
+    jwk,
+    jwkThumbprint,
+    key,
+    kmsKeyRef: key.kid,
+    kid,
+    issuer,
+  } satisfies ManagedIdentifierX5cResult
+}
+
+export async function getManagedIdentifier(
+  opts: ManagedIdentifierOpts & {
+    crypto?: Crypto
+  },
+  context: IAgentContext<IKeyManager>
+): Promise<ManagedIdentifierResult> {
+  let resolutionResult: ManagedIdentifierResult
+  if (isManagedIdentifierKidOpts(opts)) {
+    resolutionResult = await getManagedKidIdentifier(opts, context)
+  } else if (isManagedIdentifierDidOpts(opts)) {
+    resolutionResult = await getManagedDidIdentifier(opts, context)
+  } else if (isManagedIdentifierJwkOpts(opts)) {
+    resolutionResult = await getManagedJwkIdentifier(opts, context)
+  } else if (isManagedIdentifierX5cOpts(opts)) {
+    resolutionResult = await getManagedX5cIdentifier(opts, context)
+  } else {
+    return Promise.reject(Error(`Could not determine identifier method. Please provide explicitly`))
+  }
+  const { key } = resolutionResult
+  if (!key || (isManagedIdentifierDidOpts(opts) && isManagedIdentifierDidResult(resolutionResult) && !resolutionResult.identifier)) {
+    console.log(`Cannot find identifier`, opts.identifier)
+    return Promise.reject(`Cannot find identifier ${opts.identifier}`)
+  }
+  return resolutionResult
+}

package/src/types/IIdentifierResolution.ts

@@ -1,24 +1,35 @@
-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 { IAgentContext, IDIDManager, IKeyManager, IPluginMethodMap } from '@veramo/core'
 import {
-  DIDDocument,
-  DIDDocumentSection,
-  DIDResolutionResult,
-  IAgentContext,
-  IDIDManager,
-  IIdentifier,
-  IKey,
-  IKeyManager,
-  IPluginMethodMap,
-  TKeyType,
-} from '@veramo/core'
+  ExternalIdentifierDidOpts,
+  ExternalIdentifierDidResult,
+  ExternalIdentifierOpts,
+  ExternalIdentifierResult,
+  ExternalIdentifierX5cOpts,
+  ExternalIdentifierX5cResult,
+} from './externalIdentifierTypes'
+import {
+  ManagedIdentifierDidOpts,
+  ManagedIdentifierDidResult,
+  ManagedIdentifierJwkOpts,
+  ManagedIdentifierJwkResult,
+  ManagedIdentifierKidOpts,
+  ManagedIdentifierKidResult,
+  ManagedIdentifierOpts,
+  ManagedIdentifierResult,
+  ManagedIdentifierX5cOpts,
+  ManagedIdentifierX5cResult,
+} from './managedIdentifierTypes'
 
 /**
  * @public
  */
 export interface IIdentifierResolution extends IPluginMethodMap {
+  /**
+   * Main method for managed identifiers. We always go through this method (also the others) as we want to integrate a plugin for anomaly detection. Having a single method helps
+   * @param args
+   * @param context
+   * @public
+   */
   identifierManagedGet(args: ManagedIdentifierOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierResult>
 
   identifierManagedGetByDid(args: ManagedIdentifierDidOpts, context: IAgentContext<IKeyManager & IDIDManager>): Promise<ManagedIdentifierDidResult>
@@ -29,269 +40,15 @@ export interface IIdentifierResolution extends IPluginMethodMap {
 
   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
-}
+  /**
+   * Main method for external identifiers. We always go through this method (also the others) as we want to integrate a plugin for anomaly detection. Having a single method helps
+   * @param args
+   * @param context
+   * @public
+   */
+  identifierExternalResolve(args: ExternalIdentifierOpts, context: IAgentContext<any>): Promise<ExternalIdentifierResult>
 
-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
-}
+  identifierExternalResolveByDid(args: ExternalIdentifierDidOpts, context: IAgentContext<any>): Promise<ExternalIdentifierDidResult>
 
-export interface ManagedIdentifierX5cResult extends IManagedIdentifierResultBase {
-  method: 'x5c'
-  x5c: string[]
-  certificate: any // Certificate(JSON_, but trips schema generator. Probably want to create our own DTO
+  identifierExternalResolveByX5c(args: ExternalIdentifierX5cOpts, context: IAgentContext<any>): Promise<ExternalIdentifierX5cResult>
 }

package/src/types/common.ts

@@ -0,0 +1,37 @@
+import { JWK } from '@sphereon/ssi-sdk-ext.key-utils'
+import { IIdentifier } from '@veramo/core'
+import { ExternalIdentifierType } from './externalIdentifierTypes'
+import { ManagedIdentifierType } from './managedIdentifierTypes'
+
+export interface JwkInfo {
+  jwk: JWK
+  jwkThumbprint: string
+}
+
+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
+}

package/src/types/externalIdentifierTypes.ts

@@ -0,0 +1,119 @@
+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 } from '@veramo/core'
+import { isDidIdentifier, isJwkIdentifier, isJwksUrlIdentifier, isKidIdentifier, isOidcDiscoveryIdentifier, isX5cIdentifier, JwkInfo } from './common'
+
+/**
+ * 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 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 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 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 ExternalIdentifierX5cOpts = Omit<ExternalIdentifierOptsBase, 'method'> & {
+  method?: 'x5c'
+  identifier: string[]
+  verify?: boolean // defaults to true
+  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 ExternalIdentifierMethod = 'did' | 'jwk' | 'x5c' | 'kid' | 'oidc-discovery' | 'jwks-url' | 'oid4vci-issuer'
+
+export type ExternalIdentifierResult = ExternalIdentifierDidResult | ExternalIdentifierX5cResult
+
+export interface IExternalIdentifierResultBase {
+  method: ExternalIdentifierMethod
+  jwks: Array<ExternalJwkInfo>
+}
+
+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 ExternalJwkInfo extends JwkInfo {
+  kid?: string
+}
+
+export interface ExternalIdentifierDidResult extends IExternalIdentifierResultBase {
+  method: 'did'
+  did: string
+  didDocument?: DIDDocument
+  didJwks?: DidDocumentJwks
+  didResolutionResult: Omit<DIDResolutionResult, 'didDocument'> // we already provide that directly
+  didParsed: IParsedDID
+}

package/src/types/index.ts

@@ -0,0 +1,4 @@
+export * from './common'
+export * from './externalIdentifierTypes'
+export * from './managedIdentifierTypes'
+export * from './IIdentifierResolution'