Skip to main content
The createMdocCredential function is an asynchronous method that generates a Mobile Document (mDoc) credential in compliance with the ISO/IEC 18013-5 and related standards.

​
Installation

yarn add @terminal3/mdoc_vc

​
Function Signature

TypeScript
export type MDocSignerAlgorithm = 'RS256';
export type MDocHashAlgorithm = 'SHA-256' | 'SHA-384' | 'SHA-512';

export interface CreateMdocCredential {
  privateKey: string;
  claims: Record<string, unknown>;
  validityInfo: {
    signed: Date;
    validFrom: Date;
    validUntil: Date;
    expectedUpdate?: Date;
  };
  signAlg?: MDocSignerAlgorithm;
  hashAlg?: MDocHashAlgorithm;
  hasher?: Hasher;
  randomGenerator?: RandomGenerator;
  deviceJwkKey?: JsonWebKey;
  issuerCertificate?: Uint8Array;
  unprotectedHeader?: Record<string, unknown>;
};

​
Parameters

  • privateKey (string): is an RSA PEM key in String format, used to sign the credential.
  • claims (object): is an object that contains user or credential-related data (e.g., { first_name: "Joey" }).
  • validityInfo (object): defines the credential’s validity period and expected updates:
    • signed (Date): The timestamp when the credential was signed.
    • validFrom (Date): The date from which the credential becomes valid.
    • validUntil (Date): The date after which the credential is no longer valid.
    • expectedUpdate (Date, optional): When the credential is expected to be updated or refreshed.
  • signAlg (MDocSignerAlgorithm, optional): The signing algorithm to be used (e.g., RS256).
  • hashAlg (MDocHashAlgorithm, optional): The hashing algorithm used to generate document digests.
  • hasher (Hasher, optional): A custom hashing implementation. If provided, it overrides the default hashing mechanism.
  • randomGenerator (RandomGenerator, optional): A custom random byte generator for cryptographic operations.
  • deviceJwkKey (JsonWebKey, optional): A JWK-formatted key representing the device’s authentication key.
  • issuerCertificate (Uint8Array, optional): The issuer’s X.509 certificate in binary format, used for trust validation.
  • unprotectedHeader (object, optional): Additional metadata to include in the credential’s unprotected JOSE header.

​
Returns

Promise<ArrayBuffer>: A promise that resolves to a data that is a single object, self-contained CBOR array as follows: 
[
  h'A10126',                       // protected headers (byte of string)
  { 4: h'4a6f686e' },              // unprotected headers (raw CBOR map)
  h'A2646E616D65674A6F686E20446F65', // payload (byte of string)
  h'5f8c...'                       // signature (byte of string)
]

​
Exceptions

Throws an error if the signature type is unsupported.

​
Examples

TypeScript
import { generateKeyPairSync } from 'crypto';
import { createMdocCredential } from '@terminal3/mdoc_vc';

const { privateKey } = generateKeyPairSync('rsa', {
  modulusLength: 2048,
});
const privateKeyPem = privateKey.export({ type: 'pkcs8', format: 'pem' }).toString();

const claims = {
  given_name: 'Alice',
  family_name: 'Doe',
};

const validityInfo = {
  signed: new Date(),
  validFrom: new Date(),
  validUntil: new Date(Date.now() + 1000 * 60 * 60),
};

const credential = await createMdocCredential({
  privateKey: privateKeyPem,
  claims,
  validityInfo,
});

console.log(credential);