@sphereon/ssi-sdk-ext.jwt-service 0.24.1-next.93

package/src/agent/JwtService.ts

@@ -0,0 +1,47 @@
+import { IAgentPlugin } from '@veramo/core'
+import {
+  createJwsCompact,
+  CreateJwsCompactArgs,
+  CreateJwsFlattenedArgs,
+  CreateJwsJsonArgs,
+  createJwsJsonFlattened,
+  createJwsJsonGeneral,
+  IJwtService,
+  IRequiredContext,
+  JwsCompactResult,
+  JwsJsonFlattened,
+  JwsJsonGeneral,
+  PreparedJwsObject,
+  prepareJwsObject,
+  schema,
+} from '..'
+
+/**
+ * @public
+ */
+export class JwtService implements IAgentPlugin {
+  readonly schema = schema.IMnemonicInfoGenerator
+  readonly methods: IJwtService = {
+    jwtPrepareJws: this.jwtPrepareJws.bind(this),
+    jwtCreateJwsJsonGeneralSignature: this.jwtCreateJwsJsonGeneralSignature.bind(this),
+    jwtCreateJwsJsonFlattenedSignature: this.jwtCreateJwsJsonFlattenedSignature.bind(this),
+    jwtCreateJwsCompactSignature: this.jwtCreateJwsCompactSignature.bind(this),
+  }
+
+  private async jwtPrepareJws(args: CreateJwsJsonArgs, context: IRequiredContext): Promise<PreparedJwsObject> {
+    return await prepareJwsObject(args, context)
+  }
+
+  private async jwtCreateJwsJsonGeneralSignature(args: CreateJwsJsonArgs, context: IRequiredContext): Promise<JwsJsonGeneral> {
+    return await createJwsJsonGeneral(args, context)
+  }
+
+  private async jwtCreateJwsJsonFlattenedSignature(args: CreateJwsFlattenedArgs, context: IRequiredContext): Promise<JwsJsonFlattened> {
+    return await createJwsJsonFlattened(args, context)
+  }
+
+  private async jwtCreateJwsCompactSignature(args: CreateJwsCompactArgs, context: IRequiredContext): Promise<JwsCompactResult> {
+    // We wrap it in a json object for remote REST calls
+    return { jwt: await createJwsCompact(args, context) }
+  }
+}

package/src/functions/index.ts

@@ -0,0 +1,279 @@
+import {
+  isManagedIdentifierDidResult,
+  isManagedIdentifierX5cResult,
+  ManagedIdentifierMethod,
+  ManagedIdentifierResult,
+  ensureManagedIdentifierResult,
+} from '@sphereon/ssi-sdk-ext.identifier-resolution'
+import { bytesToBase64url, encodeJoseBlob } from '@veramo/utils'
+import * as u8a from 'uint8arrays'
+import {
+  CreateJwsCompactArgs,
+  CreateJwsFlattenedArgs,
+  CreateJwsJsonArgs,
+  CreateJwsMode,
+  IRequiredContext,
+  JwsCompact,
+  JwsJsonFlattened,
+  JwsJsonGeneral,
+  JwsJsonSignature,
+  JwtHeader,
+  PreparedJwsObject,
+} from '../types/IJwtService'
+
+export const prepareJwsObject = async (args: CreateJwsJsonArgs, context: IRequiredContext): Promise<PreparedJwsObject> => {
+  const { existingSignatures, protectedHeader, unprotectedHeader, issuer, payload, mode = 'auto' } = args
+
+  const { noIdentifierInHeader = false } = issuer
+  const combinedHeader = { ...unprotectedHeader, ...protectedHeader }
+  if (!combinedHeader.alg) {
+    return Promise.reject(`No 'alg' key present in the JWS header`)
+  }
+  const identifier = await ensureManagedIdentifierResult(issuer, context)
+  await checkAndUpdateJwtHeader({ mode, identifier, noIdentifierInHeader, header: protectedHeader }, context)
+
+  const isBytes = payload instanceof Uint8Array
+  const isString = typeof payload === 'string'
+  if (!isBytes && !isString) {
+    if (issuer.noIssPayloadUpdate !== true && !payload.iss && identifier.issuer) {
+      payload.iss = identifier.issuer
+    }
+  }
+  const payloadBytes = isBytes ? payload : isString ? u8a.fromString(payload, 'base64url') : u8a.fromString(JSON.stringify(payload), 'utf-8')
+  const base64urlHeader = encodeJoseBlob(protectedHeader)
+  const base64urlPayload = bytesToBase64url(payloadBytes)
+
+  return {
+    jws: {
+      unprotectedHeader,
+      protectedHeader,
+      payload: payloadBytes,
+      existingSignatures,
+    },
+    b64: {
+      protectedHeader: base64urlHeader,
+      payload: base64urlPayload,
+    },
+    identifier,
+  }
+}
+
+export const createJwsCompact = async (args: CreateJwsCompactArgs, context: IRequiredContext): Promise<JwsCompact> => {
+  const { protected: protectedHeader, payload, signature } = await createJwsJsonFlattened(args, context)
+  return `${protectedHeader}.${payload}.${signature}`
+}
+
+export const createJwsJsonFlattened = async (args: CreateJwsFlattenedArgs, context: IRequiredContext): Promise<JwsJsonFlattened> => {
+  const jws = await createJwsJsonGeneral(args, context)
+  if (jws.signatures.length !== 1) {
+    return Promise.reject(Error(`JWS flattened signature can only contain 1 signature. Found ${jws.signatures.length}`))
+  }
+  return {
+    ...jws.signatures[0],
+    payload: jws.payload,
+  } satisfies JwsJsonFlattened
+}
+
+export const createJwsJsonGeneral = async (args: CreateJwsJsonArgs, context: IRequiredContext): Promise<JwsJsonGeneral> => {
+  const { payload, protectedHeader, unprotectedHeader, existingSignatures, mode, issuer } = args
+  const { b64, identifier } = await prepareJwsObject(
+    {
+      protectedHeader,
+      unprotectedHeader,
+      payload,
+      existingSignatures,
+      issuer,
+      mode,
+    },
+    context
+  )
+  // const algorithm = await signatureAlgorithmFromKey({ key: identifier.key })
+  const signature = await context.agent.keyManagerSign({
+    keyRef: identifier.kmsKeyRef,
+    data: `${b64.protectedHeader}.${b64.payload}`,
+    encoding: undefined,
+  })
+  const jsonSignature = {
+    protected: b64.protectedHeader,
+    header: unprotectedHeader,
+    signature,
+  } satisfies JwsJsonSignature
+  return {
+    payload: b64.payload,
+    signatures: [...(existingSignatures ?? []), jsonSignature],
+  } satisfies JwsJsonGeneral
+}
+
+/**
+ * Updates the JWT header to include x5c, kid, jwk objects using the supplied issuer identifier that will be used to sign. If not present will automatically make the header objects available
+ * @param mode The type of header to check or include
+ * @param identifier The identifier of the signer. This identifier will be used later to sign
+ * @param header The JWT header
+ * @param noIdentifierInHeader
+ * @param context
+ */
+
+export const checkAndUpdateJwtHeader = async (
+  {
+    mode = 'auto',
+    identifier,
+    header,
+    noIdentifierInHeader = false,
+  }: {
+    mode?: CreateJwsMode
+    identifier: ManagedIdentifierResult
+    noIdentifierInHeader?: boolean
+    header: JwtHeader
+  },
+  context: IRequiredContext
+) => {
+  if (isMode(mode, identifier.method, 'did')) {
+    // kid is VM of the DID
+    // @see https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.4
+    await checkAndUpdateDidHeader({ header, identifier, noIdentifierInHeader }, context)
+  } else if (isMode(mode, identifier.method, 'x5c')) {
+    // Include the x5c in the header. No kid
+    // @see https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.6
+    await checkAndUpdateX5cHeader({ header, identifier, noIdentifierInHeader }, context)
+  } else if (isMode(mode, identifier.method, 'kid', false)) {
+    await checkAndUpdateKidHeader({ header, identifier, noIdentifierInHeader }, context)
+  } else if (isMode(mode, identifier.method, 'jwk', false)) {
+    // Include the JWK in the header as well as its kid if present
+    // @see https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.3
+    // @see https://datatracker.ietf.org/doc/html/rfc7515#section-4.1.4
+    await checkAndUpdateJwkHeader({ header, identifier, noIdentifierInHeader }, context)
+  } else {
+    // Better safe than sorry. We could let it pass, but we want to force implementers to make a conscious choice
+    return Promise.reject(`Invalid combination of JWS creation mode ${mode} and identifier method ${identifier.method} chosen`)
+  }
+}
+
+const checkAndUpdateX5cHeader = async (
+  {
+    header,
+    identifier,
+    noIdentifierInHeader = false,
+  }: {
+    header: JwtHeader
+    identifier: ManagedIdentifierResult
+    noIdentifierInHeader?: boolean
+  },
+  context: IRequiredContext
+) => {
+  const { x5c } = header
+  if (x5c) {
+    // let's resolve the provided x5c to be sure
+    const x5cIdentifier = await context.agent.identifierManagedGetByX5c({ identifier: x5c })
+    if (x5cIdentifier.kmsKeyRef !== identifier.kmsKeyRef) {
+      return Promise.reject(Error(`An x5c header was present, but its issuer public key did not match the provided signing public key!`))
+    }
+  } else if (!noIdentifierInHeader) {
+    if (!isManagedIdentifierX5cResult(identifier)) {
+      return Promise.reject(Error('No x5c header in the JWT, but mode was x5c and also no x5x identifier was provided!'))
+    } else if (header.jwk || header.kid) {
+      return Promise.reject(Error('x5c mode was choosen, but jwk or kid headers were provided. These cannot be used together!'))
+    }
+    header.x5c = identifier.x5c
+  }
+}
+
+const checkAndUpdateDidHeader = async (
+  {
+    header,
+    identifier,
+    noIdentifierInHeader = false,
+  }: {
+    header: JwtHeader
+    identifier: ManagedIdentifierResult
+    noIdentifierInHeader?: boolean
+  },
+  context: IRequiredContext
+) => {
+  const { kid } = header
+  if (kid) {
+    // let's resolve the provided x5c to be sure
+    const vmIdentifier = await context.agent.identifierManagedGetByDid({ identifier: kid })
+    if (vmIdentifier.kmsKeyRef !== identifier.kmsKeyRef) {
+      return Promise.reject(Error(`A kid header was present, but its value did not match the provided signing kid!`))
+    }
+  } else if (!noIdentifierInHeader) {
+    if (!isManagedIdentifierDidResult(identifier)) {
+      return Promise.reject(Error('No kid header in the JWT, but mode was did and also no DID identifier was provided!'))
+    } else if (header.jwk || header.x5c) {
+      return Promise.reject(Error('did mode was chosen, but jwk or x5c headers were provided. These cannot be used together!'))
+    }
+    header.kid = identifier.kid
+  }
+}
+
+const checkAndUpdateJwkHeader = async (
+  {
+    header,
+    identifier,
+    noIdentifierInHeader = false,
+  }: {
+    header: JwtHeader
+    identifier: ManagedIdentifierResult
+    noIdentifierInHeader?: boolean
+  },
+  context: IRequiredContext
+) => {
+  const { jwk } = header
+  if (jwk) {
+    // let's resolve the provided x5c to be sure
+    const jwkIdentifier = await context.agent.identifierManagedGetByJwk({ identifier: jwk })
+    if (jwkIdentifier.kmsKeyRef !== identifier.kmsKeyRef) {
+      return Promise.reject(Error(`A jwk header was present, but its value did not match the provided signing jwk or kid!`))
+    }
+  } else if (!noIdentifierInHeader) {
+    // We basically accept everything for this mode, as we can always create JWKs from any key
+    if (header.x5c) {
+      return Promise.reject(Error('jwk mode was chosen, but x5c headers were provided. These cannot be used together!'))
+    }
+    header.jwk = identifier.jwk
+  }
+}
+
+const checkAndUpdateKidHeader = async (
+  {
+    header,
+    identifier,
+    noIdentifierInHeader = false,
+  }: {
+    header: JwtHeader
+    identifier: ManagedIdentifierResult
+    noIdentifierInHeader?: boolean
+  },
+  context: IRequiredContext
+) => {
+  const { kid } = header
+  if (kid) {
+    // let's resolve the provided x5c to be sure
+    const kidIdentifier = await context.agent.identifierManagedGetByKid({ identifier: kid })
+    if (kidIdentifier.kmsKeyRef !== identifier.kmsKeyRef) {
+      return Promise.reject(Error(`A kid header was present, but its value did not match the provided signing kid!`))
+    }
+  } else if (!noIdentifierInHeader) {
+    // We basically accept everything for this mode, as we can always create JWKs from any key
+    if (header.x5c) {
+      return Promise.reject(Error('kid mode was chosen, but x5c headers were provided. These cannot be used together!'))
+    }
+    header.kid = identifier.kid
+  }
+}
+
+const isMode = (mode: CreateJwsMode, identifierMethod: ManagedIdentifierMethod, checkMode: CreateJwsMode, loose = true) => {
+  if (loose && (checkMode === 'jwk' || checkMode === 'kid')) {
+    // we always have the kid and jwk at hand no matter the identifier method, so we are okay with that
+    // todo: check the impact on the above expressions, as this will now always return true for the both of them
+    return true
+  }
+  if (mode === checkMode) {
+    if (checkMode !== 'auto' && mode !== identifierMethod) {
+      throw Error(`Provided mode ${mode} conflicts with identifier method ${identifierMethod}`)
+    }
+    return true
+  }
+  // we always have the kid and jwk at hand no matter the identifier method, so we are okay with that
+  return mode === 'auto' && identifierMethod === checkMode
+}

package/src/index.ts

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

package/src/types/IJwtService.ts

@@ -0,0 +1,113 @@
+import { IIdentifierResolution, ManagedIdentifierOptsOrResult, ManagedIdentifierResult } from '@sphereon/ssi-sdk-ext.identifier-resolution'
+import { ISphereonKeyManager } from '@sphereon/ssi-sdk-ext.key-manager'
+import { JWK, SignatureAlgorithmJwa } from '@sphereon/ssi-sdk-ext.key-utils'
+import { IAgentContext, IPluginMethodMap } from '@veramo/core'
+
+export type IRequiredContext = IAgentContext<IIdentifierResolution & ISphereonKeyManager> // could we still interop with Veramo?
+export interface IJwtService extends IPluginMethodMap {
+  jwtPrepareJws(args: CreateJwsJsonArgs, context: IRequiredContext): Promise<PreparedJwsObject>
+
+  jwtCreateJwsJsonGeneralSignature(args: CreateJwsJsonArgs, context: IRequiredContext): Promise<JwsJsonGeneral>
+
+  jwtCreateJwsJsonFlattenedSignature(args: CreateJwsFlattenedArgs, context: IRequiredContext): Promise<JwsJsonFlattened>
+
+  jwtCreateJwsCompactSignature(args: CreateJwsCompactArgs, context: IRequiredContext): Promise<JwsCompactResult>
+
+  // jwtVerifyJwsCompactSignature(args: {jwt: string}): Promise<any>
+
+  // TODO: JWE/encryption
+}
+
+export interface PreparedJws {
+  protectedHeader: JwtHeader
+  payload: Uint8Array
+  unprotectedHeader?: JwtHeader // only for jws json and also then optional
+  existingSignatures?: Array<JwsJsonSignature> // only for jws json and also then optional
+}
+
+export interface JwsJsonSignature {
+  protected: string
+  header?: JwtHeader
+  signature: string
+}
+
+export type JwsCompact = string
+
+export interface JwsJsonFlattened {
+  payload: string
+  protected: string
+  header?: JwtHeader
+  signature: string
+}
+
+export interface JwsJsonGeneral {
+  payload: string
+  signatures: Array<JwsJsonSignature>
+}
+
+export interface PreparedJwsObject {
+  jws: PreparedJws
+  b64: { payload: string; protectedHeader: string } // header is always json, as it can only be used in JwsJson
+  identifier: ManagedIdentifierResult
+}
+
+export interface BaseJwtHeader {
+  typ?: string
+  alg?: string
+  kid?: string
+}
+export interface BaseJwtPayload {
+  iss?: string
+  sub?: string
+  aud?: string[] | string
+  exp?: number
+  nbf?: number
+  iat?: number
+  jti?: string
+}
+
+export interface JwtHeader extends BaseJwtHeader {
+  kid?: string
+  jwk?: JWK
+  x5c?: string[]
+
+  [key: string]: unknown
+}
+
+export interface JwtPayload extends BaseJwtPayload {
+  [key: string]: unknown
+}
+
+export interface JwsHeaderOpts {
+  als: SignatureAlgorithmJwa
+}
+
+export type CreateJwsMode = 'x5c' | 'kid' | 'jwk' | 'did' | 'auto'
+
+export type CreateJwsArgs = {
+  mode?: CreateJwsMode
+  issuer: ManagedIdentifierOptsOrResult & { noIssPayloadUpdate?: boolean; noIdentifierInHeader?: boolean }
+  protectedHeader: JwtHeader
+  payload: JwtPayload | Uint8Array | string
+}
+
+export type CreateJwsCompactArgs = CreateJwsArgs
+
+export type CreateJwsFlattenedArgs = Exclude<CreateJwsJsonArgs, 'existingSignatures'>
+
+/**
+ * @public
+ */
+export type CreateJwsJsonArgs = CreateJwsArgs & {
+  unprotectedHeader?: JwtHeader // only for jws json
+  existingSignatures?: Array<JwsJsonSignature> // Only for jws json
+}
+
+/**
+ * @public
+ */
+export interface JwsCompactResult {
+  jwt: JwsCompact
+}
+
+// export const COMPACT_JWS_REGEX = /^([a-zA-Z0-9_=-]+)\.([a-zA-Z0-9_=-]+)?\.([a-zA-Z0-9_=-]+)$/