@sphereon/ssi-sdk-ext.identifier-resolution 0.24.1-next.100

package/src/types/IIdentifierResolution.ts

@@ -0,0 +1,79 @@
+import { IAgentContext, IDIDManager, IKeyManager, IPluginMethodMap } from '@veramo/core'
+import {
+  ExternalIdentifierDidOpts,
+  ExternalIdentifierDidResult,
+  ExternalIdentifierOpts,
+  ExternalIdentifierResult,
+  ExternalIdentifierX5cOpts,
+  ExternalIdentifierX5cResult,
+} from './externalIdentifierTypes'
+import {
+  ManagedIdentifierDidOpts,
+  ManagedIdentifierDidResult,
+  ManagedIdentifierJwkOpts,
+  ManagedIdentifierJwkResult,
+  ManagedIdentifierKeyOpts,
+  ManagedIdentifierKeyResult,
+  ManagedIdentifierKidOpts,
+  ManagedIdentifierKidResult,
+  ManagedIdentifierOptsOrResult,
+  ManagedIdentifierResult,
+  ManagedIdentifierX5cOpts,
+  ManagedIdentifierX5cResult,
+} from './managedIdentifierTypes'
+
+// Exposing the methods here for any REST implementation
+export const identifierResolutionContextMethods: Array<string> = [
+  'identifierManagedGet',
+  'identifierManagedGetByDid',
+  'identifierManagedGetByKid',
+  'identifierManagedGetByJwk',
+  'identifierManagedGetByX5c',
+  'identifierManagedGetByKey',
+  'identifierExternalResolve',
+  'identifierExternalResolveByDid',
+  'identifierExternalResolveByX5c',
+]
+
+/**
+ * @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
+   *
+   * The end result of all these methods is a common baseline response that allows to use a key from the registered KMS systems. It also provides kid and iss(uer) values that can be used in a JWT/JWS for instance
+   * Allows to get a managed identifier result in case identifier options are passed in, but returns the identifier directly in case results are passed in. This means resolution can have happened before, or happens in this method
+   *
+   * We use the opts or result type almost everywhere, as it allows for just in time resolution whenever this method is called and afterwards we have the result, so resolution doesn't have to hit the DB, or external endpoints.
+   * Also use this method in the local agent, not using REST. If case the identifier needs to be resolved, you can always have the above methods using REST
+   * @param args
+   * @param context
+   * @public
+   */
+  identifierManagedGet(args: ManagedIdentifierOptsOrResult, 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>
+
+  identifierManagedGetByKey(args: ManagedIdentifierKeyOpts, context: IAgentContext<IKeyManager>): Promise<ManagedIdentifierKeyResult>
+
+  // TODO: We can create a custom managed identifier method allowing developers to register a callback function to get their implementation hooked up. Needs more investigation as it would also impact the KMS
+
+  /**
+   * 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>
+
+  identifierExternalResolveByDid(args: ExternalIdentifierDidOpts, context: IAgentContext<any>): Promise<ExternalIdentifierDidResult>
+
+  identifierExternalResolveByX5c(args: ExternalIdentifierX5cOpts, context: IAgentContext<any>): Promise<ExternalIdentifierX5cResult>
+}

package/src/types/common.ts

@@ -0,0 +1,47 @@
+import { JWK } from '@sphereon/ssi-sdk-ext.key-utils'
+import { IIdentifier, IKey } 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 isKeyIdentifier(identifier: ManagedIdentifierType): identifier is IKey {
+  return (
+    typeof identifier === 'string' &&
+    !Array.isArray(identifier) &&
+    typeof identifier === 'object' &&
+    `kid` in identifier &&
+    'publicKeyHex' in identifier
+  )
+}
+
+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'

package/src/types/managedIdentifierTypes.ts

@@ -0,0 +1,157 @@
+import { JWK } from '@sphereon/ssi-sdk-ext.key-utils'
+import { DIDDocumentSection, IIdentifier, IKey, TKeyType } from '@veramo/core'
+import { isDidIdentifier, isJwkIdentifier, isKeyIdentifier, isKidIdentifier, isX5cIdentifier, JwkInfo } from './common'
+
+/**
+ * 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 | IKey
+
+export type ManagedIdentifierOpts = (
+  | ManagedIdentifierJwkOpts
+  | ManagedIdentifierX5cOpts
+  | ManagedIdentifierDidOpts
+  | ManagedIdentifierKidOpts
+  | ManagedIdentifierKeyOpts
+) &
+  ManagedIdentifierOptsBase
+
+export type ManagedIdentifierOptsBase = {
+  method?: ManagedIdentifierMethod // If provided always takes precedences otherwise it will be inferred from the identifier
+  identifier: ManagedIdentifierType
+  kmsKeyRef?: string // The key reference for the KMS system. If provided this value will be used to determine the appropriate key. Otherwise it will be inferred
+  issuer?: string // can be used when a specific issuer needs to end up, for instance when signing JWTs. Will be returned or inferred if not provided
+  kid?: string // can be used when a specific kid value needs to be used. For instance when signing JWTs. Will be returned or inferred if not provided
+}
+
+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 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 ManagedIdentifierKeyOpts = Omit<ManagedIdentifierOptsBase, 'method'> & {
+  method?: 'key'
+  identifier: IKey
+}
+
+export function isManagedIdentifierKeyOpts(opts: ManagedIdentifierOptsBase): opts is ManagedIdentifierKidOpts {
+  const { identifier } = opts
+  return ('method' in opts && opts.method === 'key') || isKeyIdentifier(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 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 interface ManagedJwkInfo extends JwkInfo {
+  kmsKeyRef: string
+}
+
+export interface IManagedIdentifierResultBase extends ManagedJwkInfo {
+  method: ManagedIdentifierMethod
+  opts: ManagedIdentifierOpts
+  key: IKey
+  kid?: string
+  issuer?: string
+  identifier: ManagedIdentifierType
+}
+
+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 ManagedIdentifierX5cResult {
+  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 function isManagedIdentifierKeyResult(object: IManagedIdentifierResultBase): object is ManagedIdentifierKeyResult {
+  return object!! && typeof object === 'object' && 'method' in object && object.method === 'key'
+}
+
+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
+  issuer: string
+  kid: string
+}
+
+export interface ManagedIdentifierJwkResult extends IManagedIdentifierResultBase {
+  identifier: JWK
+  method: 'jwk'
+}
+
+export interface ManagedIdentifierKidResult extends IManagedIdentifierResultBase {
+  method: 'kid'
+  identifier: string
+  kid: string
+}
+
+export interface ManagedIdentifierKeyResult extends IManagedIdentifierResultBase {
+  method: 'key'
+  identifier: IKey
+}
+
+export interface ManagedIdentifierX5cResult extends IManagedIdentifierResultBase {
+  method: 'x5c'
+  identifier: string[]
+  x5c: string[]
+  certificate: any // Certificate(JSON_, but trips schema generator. Probably want to create our own DTO
+}
+
+export type ManagedIdentifierMethod = 'did' | 'jwk' | 'x5c' | 'kid' | 'key'
+
+export type ManagedIdentifierResult = IManagedIdentifierResultBase &
+  (ManagedIdentifierX5cResult | ManagedIdentifierDidResult | ManagedIdentifierJwkResult | ManagedIdentifierKidResult | ManagedIdentifierKeyResult)
+
+export type ManagedIdentifierOptsOrResult = (ManagedIdentifierResult | ManagedIdentifierOpts) & { lazyDisabled?: boolean }