@mocanetwork/privado-js-sdk 1.0.0

package/src/iden3comm/packers/jws.ts

@@ -0,0 +1,225 @@
+import { BasicMessage, IPacker, JWSPackerParams } from '../types';
+import {
+  AcceptJwsAlgorithms,
+  MediaType,
+  ProtocolVersion,
+  SUPPORTED_PUBLIC_KEY_TYPES
+} from '../constants';
+import { extractPublicKeyBytes, resolveVerificationMethods } from '../utils/did';
+import { keyPath, KMS } from '../../kms/';
+
+import { verifyJWS } from 'did-jwt';
+import { DIDDocument, Resolvable, parse } from 'did-resolver';
+import { bytesToBase64url } from '../../utils/encoding';
+import {
+  byteDecoder,
+  byteEncoder,
+  bytesToHex,
+  decodeBase64url,
+  encodeBase64url
+} from '../../utils';
+import { parseAcceptProfile } from '../utils';
+
+/**
+ * Packer that can pack message to JWZ token,
+ * and unpack and validate JWZ envelope
+ * @public
+ * @class ZKPPacker
+ * @implements implements IPacker interface
+ */
+export class JWSPacker implements IPacker {
+  private readonly supportedAlgorithms = [AcceptJwsAlgorithms.ES256K, AcceptJwsAlgorithms.ES256KR];
+  private readonly supportedProtocolVersions = [ProtocolVersion.V1];
+
+  /**
+   * Creates an instance of JWSPacker.
+   *
+   * @param {KMS} _kms
+   * @param {Resolvable} _documentResolver
+   * @memberof JWSPacker
+   */
+  constructor(private readonly _kms: KMS, private readonly _documentResolver: Resolvable) {}
+
+  /**
+   * Packs the given payload and returns a promise that resolves to the packed data.
+   *
+   * @param {Uint8Array} payload - The payload to be packed.
+   * @param {PackerParams} param - The packing parameters.
+   * @returns `Promise<Uint8Array>`
+   */
+  packMessage(msg: BasicMessage, param: JWSPackerParams): Promise<Uint8Array> {
+    return this.packInternal(msg, param);
+  }
+  /**
+   * creates JSON Web Signature token
+   *
+   * @param {Uint8Array} payload - serialized message
+   * @param {PackerParams} params - sender id and proving alg are required
+   * @returns `Promise<Uint8Array>`
+   */
+  async pack(payload: Uint8Array, params: JWSPackerParams): Promise<Uint8Array> {
+    const message = JSON.parse(byteDecoder.decode(payload));
+    return this.packInternal(message, params);
+  }
+
+  /**
+   * validate envelope which is jwz token
+   *
+   * @param {Uint8Array} envelope
+   * @returns `Promise<BasicMessage>`
+   */
+  async unpack(envelope: Uint8Array): Promise<BasicMessage> {
+    const jws = byteDecoder.decode(envelope);
+
+    const [headerStr, msgStr] = jws.split('.');
+
+    const header = JSON.parse(decodeBase64url(headerStr));
+    const message = JSON.parse(decodeBase64url(msgStr));
+    const explicitSender = parse(header.kid)?.did;
+    if (explicitSender && explicitSender !== message.from) {
+      throw new Error(`Sender does not match DID in message with kid ${header?.kid}`);
+    }
+
+    const didDocument: DIDDocument = await this.resolveDidDoc(message.from);
+
+    let vms = resolveVerificationMethods(didDocument);
+
+    if (!vms?.length) {
+      throw new Error(`No verification methods defined in the DID document of ${didDocument.id}`);
+    }
+    if (header.kid) {
+      const vm = vms.find((v) => {
+        return v.id === header.kid;
+      });
+      if (!vm) {
+        throw new Error(
+          `verification method with specified kid ${header.kid} is not found in the DID Document`
+        );
+      }
+      vms = [vm];
+    }
+
+    const verificationResponse = verifyJWS(jws, vms);
+
+    if (!verificationResponse) {
+      throw new Error('JWS verification failed');
+    }
+    return message as BasicMessage;
+  }
+
+  mediaType(): MediaType {
+    return MediaType.SignedMessage;
+  }
+
+  /** {@inheritDoc IPacker.getSupportedProfiles} */
+  getSupportedProfiles(): string[] {
+    return this.supportedProtocolVersions.map(
+      (v) => `${v};env=${this.mediaType()};alg=${this.supportedAlgorithms.join(',')}`
+    );
+  }
+
+  /** {@inheritDoc IPacker.isProfileSupported} */
+  isProfileSupported(profile: string) {
+    const { protocolVersion, env, circuits, alg } = parseAcceptProfile(profile);
+
+    if (!this.supportedProtocolVersions.includes(protocolVersion)) {
+      return false;
+    }
+    if (env !== this.mediaType()) {
+      return false;
+    }
+
+    if (circuits) {
+      throw new Error(`Circuits are not supported for ${env} media type`);
+    }
+
+    const algSupported =
+      !alg?.length || alg.some((a) => this.supportedAlgorithms.includes(a as AcceptJwsAlgorithms));
+    return algSupported;
+  }
+
+  private async resolveDidDoc(from: string) {
+    let didDocument: DIDDocument;
+    try {
+      const didResolutionResult = await this._documentResolver.resolve(from);
+      if (!didResolutionResult?.didDocument?.id) {
+        throw new Error(`did document for ${from} is not found in resolution result`);
+      }
+      didDocument = didResolutionResult.didDocument;
+    } catch (err: unknown) {
+      throw new Error(`did document for ${from} is not resolved: ${(err as Error).message}`);
+    }
+    return didDocument;
+  }
+
+  private async packInternal(message: BasicMessage, params: JWSPackerParams): Promise<Uint8Array> {
+    if (!params.alg) {
+      throw new Error('Missing algorithm');
+    }
+
+    const from = message.from ?? '';
+    if (!from) {
+      throw new Error('Missing sender DID');
+    }
+
+    const vmTypes: string[] =
+      SUPPORTED_PUBLIC_KEY_TYPES[params.alg as keyof typeof SUPPORTED_PUBLIC_KEY_TYPES];
+    if (!vmTypes?.length) {
+      throw new Error(`No supported verification methods for algorithm ${params.alg}`);
+    }
+
+    const didDocument: DIDDocument = params.didDocument ?? (await this.resolveDidDoc(from));
+
+    const vms = resolveVerificationMethods(didDocument);
+
+    if (!vms.length) {
+      throw new Error(`No verification methods defined in the DID document of ${didDocument.id}`);
+    }
+
+    // try to find a managed signing key that matches keyRef
+    const vm = params.kid ? vms.find((vm) => vm.id === params.kid) : vms[0];
+
+    if (!vm) {
+      throw new Error(`No key found with id ${params.kid} in DID document of ${didDocument.id}`);
+    }
+
+    const { publicKeyBytes, kmsKeyType } = extractPublicKeyBytes(vm);
+
+    if (!publicKeyBytes && !kmsKeyType) {
+      if ((vm.blockchainAccountId || vm.ethereumAddress) && !params.signer) {
+        throw new Error(`No signer provided for ${vm.blockchainAccountId || vm.ethereumAddress}`);
+      }
+    }
+
+    const kid = vm.id;
+
+    const headerObj = { alg: params.alg, kid, typ: MediaType.SignedMessage };
+    const header = encodeBase64url(JSON.stringify(headerObj));
+    const msg = encodeBase64url(JSON.stringify(message));
+    const signingInput = `${header}.${msg}`;
+    const signingInputBytes = byteEncoder.encode(signingInput);
+    let signatureBase64: string;
+    if (params.signer) {
+      const signature = await params.signer(vm, signingInputBytes);
+      signatureBase64 = bytesToBase64url(signature);
+    } else {
+      if (!publicKeyBytes) {
+        throw new Error('No public key found');
+      }
+
+      if (!kmsKeyType) {
+        throw new Error('No KMS key type found');
+      }
+
+      const signatureBytes = await this._kms.sign(
+        { type: kmsKeyType, id: keyPath(kmsKeyType, bytesToHex(publicKeyBytes)) },
+        signingInputBytes,
+        { alg: params.alg }
+      );
+
+      signatureBase64 = bytesToBase64url(signatureBytes);
+    }
+
+    return byteEncoder.encode(`${signingInput}.${signatureBase64}`);
+  }
+}

package/src/iden3comm/packers/plain.ts

@@ -0,0 +1,86 @@
+import { BasicMessage, IPacker } from '../types';
+import { MediaType, ProtocolVersion } from '../constants';
+import { byteDecoder, byteEncoder } from '../../utils';
+import { parseAcceptProfile } from '../utils';
+
+/**
+ * Plain packer just serializes bytes to JSON and adds media type
+ *
+ * @public
+ * @class PlainPacker
+ * @implements implements IPacker interface
+ */
+export class PlainPacker implements IPacker {
+  private readonly supportedProtocolVersions = [ProtocolVersion.V1];
+
+  /**
+   * Packs a basic message using the specified parameters.
+   *
+   * @param msg - The basic message to pack.
+   * @param param - The packer parameters.
+   * @returns A promise that resolves to a Uint8Array representing the packed message.
+   * @throws An error if the method is not implemented.
+   */
+  packMessage(msg: BasicMessage): Promise<Uint8Array> {
+    msg.typ = MediaType.PlainMessage;
+    return Promise.resolve(byteEncoder.encode(JSON.stringify(msg)));
+  }
+  /**
+   * Pack returns packed message to transport envelope
+   *
+   * @param {Uint8Array} payload - json message serialized
+   * @param {PlainPackerParams} _params - not used here
+   * @returns `Promise<Uint8Array>`
+   */
+  async pack(payload: Uint8Array): Promise<Uint8Array> {
+    const msg = JSON.parse(byteDecoder.decode(payload));
+    msg.typ = MediaType.PlainMessage;
+    return Promise.resolve(byteEncoder.encode(JSON.stringify(msg)));
+  }
+
+  /**
+   * Unpack returns unpacked message from transport envelope
+   *
+   * @param {Uint8Array} envelope - packed envelope (serialized json with media type)
+   * @returns `Promise<BasicMessage>`
+   */
+  async unpack(envelope: Uint8Array): Promise<BasicMessage> {
+    return JSON.parse(byteDecoder.decode(envelope));
+  }
+
+  /**
+   * returns media type for plain message
+   *
+   * @returns MediaType
+   */
+  mediaType(): MediaType {
+    return MediaType.PlainMessage;
+  }
+
+  /** {@inheritDoc IPacker.getSupportedProfiles} */
+  getSupportedProfiles(): string[] {
+    return this.supportedProtocolVersions.map((v) => `${v};env=${this.mediaType()}`);
+  }
+
+  /** {@inheritDoc IPacker.isProfileSupported} */
+  isProfileSupported(profile: string) {
+    const { protocolVersion, env, circuits, alg } = parseAcceptProfile(profile);
+
+    if (!this.supportedProtocolVersions.includes(protocolVersion)) {
+      return false;
+    }
+    if (env !== this.mediaType()) {
+      return false;
+    }
+
+    if (circuits) {
+      throw new Error(`Circuits are not supported for ${env} media type`);
+    }
+
+    if (alg) {
+      throw new Error(`Algorithms are not supported for ${env} media type`);
+    }
+
+    return true;
+  }
+}

package/src/iden3comm/packers/zkp.ts

@@ -0,0 +1,243 @@
+import {
+  StateVerificationOpts,
+  AuthDataPrepareFunc,
+  BasicMessage,
+  IPacker,
+  ProvingParams,
+  StateVerificationFunc,
+  VerificationParams,
+  ZKPPackerParams
+} from '../types';
+import { Token, Header, ProvingMethodAlg, proving } from '@iden3/js-jwz';
+import { AuthV2PubSignals, CircuitId } from '../../circuits/index';
+import { BytesHelper, DID } from '@mocanetwork/moca-iden3';
+import { bytesToProtocolMessage } from '../utils/envelope';
+import {
+  ErrNoProvingMethodAlg,
+  ErrPackedWithUnsupportedCircuit,
+  ErrProofIsInvalid,
+  ErrSenderNotUsedTokenCreation,
+  ErrStateVerificationFailed,
+  ErrUnknownCircuitID
+} from '../errors';
+import { AcceptAuthCircuits, AcceptJwzAlgorithms, MediaType, ProtocolVersion } from '../constants';
+import { byteDecoder, byteEncoder } from '../../utils';
+import { DEFAULT_AUTH_VERIFY_DELAY } from '../constants';
+import { parseAcceptProfile } from '../utils';
+
+const { getProvingMethod } = proving;
+
+/**
+ * Handler to
+ *
+ * @public
+ * @class DataPrepareHandlerFunc
+ */
+export class DataPrepareHandlerFunc {
+  /**
+   * Creates an instance of DataPrepareHandlerFunc.
+   * @param {AuthDataPrepareFunc} dataPrepareFunc - function that produces marshaled inputs for auth circuits
+   */
+  constructor(public readonly dataPrepareFunc: AuthDataPrepareFunc) {}
+
+  /**
+   *
+   *
+   * @param {Uint8Array} hash - challenge that will be signed
+   * @param {DID} did - did of identity that will prepare inputs
+   * @param {CircuitId} circuitId - circuit id
+   * @returns `Promise<Uint8Array>`
+   */
+  prepare(hash: Uint8Array, did: DID, circuitId: CircuitId): Promise<Uint8Array> {
+    return this.dataPrepareFunc(hash, did, circuitId);
+  }
+}
+
+/**
+ * Handler to verify public signals of authorization circuits
+ *
+ * @public
+ * @class VerificationHandlerFunc
+ */
+export class VerificationHandlerFunc {
+  /**
+   * Creates an instance of VerificationHandlerFunc.
+   * @param {StateVerificationFunc} stateVerificationFunc - state verification function
+   */
+  constructor(public readonly stateVerificationFunc: StateVerificationFunc) {}
+
+  /**
+   *
+   *
+   * @param {string} id  - id of circuit
+   * @param {Array<string>} pubSignals - signals that must contain user id and state
+   * @returns `Promise<boolean>`
+   */
+  verify(id: string, pubSignals: Array<string>, opts?: StateVerificationOpts): Promise<boolean> {
+    return this.stateVerificationFunc(id, pubSignals, opts);
+  }
+}
+
+/**
+ * Packer that can pack message to JWZ token,
+ * and unpack and validate JWZ envelope
+ * @public
+ * @class ZKPPacker
+ * @implements implements IPacker interface
+ */
+export class ZKPPacker implements IPacker {
+  private readonly supportedProtocolVersions = [ProtocolVersion.V1];
+  private readonly supportedAlgorithms = [AcceptJwzAlgorithms.Groth16];
+  private readonly supportedCircuitIds = [AcceptAuthCircuits.AuthV2];
+
+  /**
+   * Creates an instance of ZKPPacker.
+   * @param {Map<string, ProvingParams>} provingParamsMap - string is derived by JSON.parse(ProvingMethodAlg)
+   * @param {Map<string, VerificationParams>} verificationParamsMap - string is derived by JSON.parse(ProvingMethodAlg)
+   */
+  constructor(
+    public readonly provingParamsMap: Map<string, ProvingParams>,
+    public readonly verificationParamsMap: Map<string, VerificationParams>,
+    private readonly _opts: StateVerificationOpts = {
+      acceptedStateTransitionDelay: DEFAULT_AUTH_VERIFY_DELAY
+    }
+  ) {}
+
+  /**
+   * Packs a basic message using the specified parameters.
+   * @param msg - The basic message to pack.
+   * @param param - The parameters for the ZKPPacker.
+   * @returns A promise that resolves to a Uint8Array representing the packed message.
+   */
+  packMessage(msg: BasicMessage, param: ZKPPackerParams): Promise<Uint8Array> {
+    return this.pack(byteEncoder.encode(JSON.stringify(msg)), param as ZKPPackerParams);
+  }
+
+  /**
+   * creates JSON Web Zeroknowledge token
+   *
+   * @param {Uint8Array} payload - serialized message
+   * @param {ZKPPackerParams} params - sender id and proving alg are required
+   * @returns `Promise<Uint8Array>`
+   */
+  async pack(payload: Uint8Array, params: ZKPPackerParams): Promise<Uint8Array> {
+    const provingMethod = await getProvingMethod(params.provingMethodAlg);
+    const provingParams = this.provingParamsMap.get(params.provingMethodAlg.toString());
+
+    if (!provingParams) {
+      throw new Error(ErrNoProvingMethodAlg);
+    }
+
+    const token = new Token(
+      provingMethod,
+      byteDecoder.decode(payload),
+      (hash: Uint8Array, circuitId: string) => {
+        return provingParams?.dataPreparer?.prepare(hash, params.senderDID, circuitId as CircuitId);
+      }
+    );
+    token.setHeader(Header.Type, MediaType.ZKPMessage);
+    const tokenStr = await token.prove(provingParams.provingKey, provingParams.wasm);
+    return byteEncoder.encode(tokenStr);
+  }
+
+  /**
+   * validate envelope which is jwz token
+   *
+   * @param {Uint8Array} envelope
+   * @returns `Promise<BasicMessage>`
+   */
+  async unpack(envelope: Uint8Array): Promise<BasicMessage> {
+    const token = await Token.parse(byteDecoder.decode(envelope));
+    const provingMethodAlg = new ProvingMethodAlg(token.alg, token.circuitId);
+    const verificationParams = this.verificationParamsMap.get(provingMethodAlg.toString());
+    if (!verificationParams?.key) {
+      throw new Error(ErrPackedWithUnsupportedCircuit);
+    }
+    const isValid = await token.verify(verificationParams?.key);
+    if (!isValid) {
+      throw new Error(ErrProofIsInvalid);
+    }
+
+    const verificationResult = await verificationParams?.verificationFn?.verify(
+      token.circuitId,
+      token.zkProof.pub_signals,
+      this._opts
+    );
+
+    if (!verificationResult) {
+      throw new Error(ErrStateVerificationFailed);
+    }
+
+    const message = bytesToProtocolMessage(byteEncoder.encode(token.getPayload()));
+
+    // should throw if error
+    verifySender(token, message);
+
+    return message;
+  }
+
+  mediaType(): MediaType {
+    return MediaType.ZKPMessage;
+  }
+
+  /** {@inheritDoc IPacker.getSupportedProfiles} */
+  getSupportedProfiles(): string[] {
+    return this.supportedProtocolVersions.map(
+      (v) =>
+        `${v};env=${this.mediaType()};alg=${this.supportedAlgorithms.join(
+          ','
+        )};circuitIds=${this.supportedCircuitIds.join(',')}`
+    );
+  }
+
+  /** {@inheritDoc IPacker.isProfileSupported} */
+  isProfileSupported(profile: string) {
+    const { protocolVersion, env, circuits, alg } = parseAcceptProfile(profile);
+
+    if (!this.supportedProtocolVersions.includes(protocolVersion)) {
+      return false;
+    }
+
+    if (env !== this.mediaType()) {
+      return false;
+    }
+
+    const supportedCircuitIds = this.supportedCircuitIds;
+    const circuitIdSupported =
+      !circuits?.length || circuits.some((c) => supportedCircuitIds.includes(c));
+
+    const supportedAlgArr = this.supportedAlgorithms;
+    const algSupported =
+      !alg?.length || alg.some((a) => supportedAlgArr.includes(a as AcceptJwzAlgorithms));
+    return algSupported && circuitIdSupported;
+  }
+}
+
+const verifySender = async (token: Token, msg: BasicMessage): Promise<void> => {
+  switch (token.circuitId) {
+    case CircuitId.AuthV2:
+      {
+        if (!msg.from) {
+          throw new Error(ErrSenderNotUsedTokenCreation);
+        }
+        const authSignals = new AuthV2PubSignals().pubSignalsUnmarshal(
+          byteEncoder.encode(JSON.stringify(token.zkProof.pub_signals))
+        );
+        const did = DID.parseFromId(authSignals.userID);
+
+        const msgHash = await token.getMessageHash();
+        const challenge = BytesHelper.bytesToInt(msgHash.reverse());
+
+        if (challenge !== authSignals.challenge) {
+          throw new Error(ErrSenderNotUsedTokenCreation);
+        }
+
+        if (msg.from !== did.string()) {
+          throw new Error(ErrSenderNotUsedTokenCreation);
+        }
+      }
+      break;
+    default:
+      throw new Error(ErrUnknownCircuitID);
+  }
+};

package/src/iden3comm/types/index.ts

@@ -0,0 +1,17 @@
+export * from './protocol/auth';
+export * from './protocol/credentials';
+export * from './protocol/messages';
+export * from './protocol/proof';
+export * from './protocol/revocation';
+export * from './protocol/contract-request';
+export * from './protocol/proposal-request';
+export * from './protocol/payment';
+export * from './protocol/accept-profile';
+export * from './protocol/discovery-protocol';
+export * from './protocol/problem-report';
+
+export * from './protocol/attachment';
+export * from './protocol/common';
+export * from './packer';
+export * from './models';
+export * from './packageManager';

package/src/iden3comm/types/models.ts

@@ -0,0 +1,7 @@
+/**
+ * State verification options
+ */
+export type StateVerificationOpts = {
+  // acceptedStateTransitionDelay is the period of time in milliseconds that a revoked state remains valid.
+  acceptedStateTransitionDelay?: number;
+};

package/src/iden3comm/types/packageManager.ts

@@ -0,0 +1,112 @@
+import { BasicMessage, IPacker, PackerParams } from './packer';
+import { MediaType } from '../constants';
+
+/**
+ * Interface for defining the registry of packers
+ *
+ * @public
+ * @interface   IPackageManager
+ */
+export interface IPackageManager {
+  /**
+   * Map of packers key is media type, value is packer implementation
+   *
+   * @type {Map<MediaType, IPacker>}
+   */
+  packers: Map<MediaType, IPacker>;
+
+  /**
+   * registers new packer in the manager
+   *
+   * @param {Array<IPacker>} packers
+   */
+  registerPackers(packers: Array<IPacker>): void;
+
+  /**
+   * packs payload with a packer that is assigned to media type
+   * forwards packer params to implementation
+   *
+   * @param {MediaType} mediaType
+   * @param {Uint8Array} payload
+   * @param {PackerParams} params
+   * @returns `Promise<Uint8Array>`
+   */
+  pack(mediaType: MediaType, payload: Uint8Array, params: PackerParams): Promise<Uint8Array>;
+
+  /**
+   * packs payload with a packer that is assigned to media type
+   * forwards packer params to implementation
+   *
+   * @param {MediaType} mediaType
+   * @param {BasicMessage} protocolMessage
+   * @param {PackerParams} params
+   * @returns `Promise<Uint8Array>`
+   */
+  packMessage(
+    mediaType: MediaType,
+    protocolMessage: BasicMessage,
+    params: PackerParams
+  ): Promise<Uint8Array>;
+
+  /**
+   * unpacks packed envelope to basic protocol message and returns media type of the envelope
+   *
+   * @param {Uint8Array} envelope - bytes envelope
+   * @returns `Promise<{ unpackedMessage: BasicMessage; unpackedMediaType: MediaType }`
+   */
+  unpack(
+    envelope: Uint8Array
+  ): Promise<{ unpackedMessage: BasicMessage; unpackedMediaType: MediaType }>;
+
+  /**
+   * unpacks an envelope with a known media type
+   *
+   * @param {MediaType} mediaType
+   * @param {Uint8Array} envelope
+   * @returns `Promise<BasicMessage>`
+   */
+  unpackWithType(mediaType: MediaType, envelope: Uint8Array): Promise<BasicMessage>;
+
+  /**
+   * gets media type from an envelope
+   *
+   * @param {string} envelope
+   * @returns MediaType
+   */
+  getMediaType(envelope: string): MediaType;
+
+  /**
+   * gets supported media types by packer manager
+   *
+   * @returns MediaType[]
+   */
+  getSupportedMediaTypes(): MediaType[];
+
+  /**
+   * gets supported accept profiles by packer manager
+   *
+   * @returns string[]
+   */
+  getSupportedProfiles(): string[];
+
+  /**
+   * returns true if media type and algorithms supported by packer manager
+   *
+   * @param {MediaType} mediaType
+   * @param {string} profile
+   * @returns {boolean}
+   */
+  isProfileSupported(mediaType: MediaType, profile: string): boolean;
+}
+/**
+ * EnvelopeStub is used to stub the jwt based envelops
+ */
+export type EnvelopeStub = {
+  protected: string;
+};
+/**
+ * HeaderStub is used to stub the jwt based envelops
+ */
+export type HeaderStub = {
+  typ: MediaType;
+};