VaultysId API Reference

The VaultysId class is the core identity representation in the @vaultys/id library. It encapsulates cryptographic keys and provides methods for authentication, encryption, and identity management.

Class: VaultysId

class VaultysId {
  type: string
  keyManager: KeyManager
  certificate?: Certificate
}

Constants

Identity Types

const TYPE_MACHINE = "machine"           // Service/server identity
const TYPE_PERSON = "person"             // Human user identity
const TYPE_ORGANIZATION = "organization"  // Organization identity
const TYPE_FIDO2 = "fido2"              // FIDO2 hardware key
const TYPE_FIDO2PRF = "fido2prf"        // FIDO2 with PRF extension

Constructor

`constructor(type, keyManager, certificate?)`

Creates a new VaultysId instance.

Parameters:

type (string): The type of identity (TYPE_MACHINE, TYPE_PERSON, etc.)
keyManager (KeyManager): The cryptographic key manager
certificate (Certificate, optional): Optional certificate data

Example:

const keyManager = new KeyManager("ed25519");
const vaultysId = new VaultysId(TYPE_PERSON, keyManager);

Static Methods

Identity Creation

`static async generatePerson(algorithm?: string): Promise<VaultysId>`

Generates a new person identity with the specified algorithm.

Parameters:

algorithm (string, optional): Cryptographic algorithm ("ed25519", "dilithium_ed25519", "ml_kem768_x25519"). Defaults to "ed25519"

Returns: Promise<VaultysId>

Example:

// Standard Ed25519
const person = await VaultysId.generatePerson("ed25519");

// Post-quantum hybrid
const pqPerson = await VaultysId.generatePerson("dilithium_ed25519");

// ML-KEM (Kyber) hybrid
const mlPerson = await VaultysId.generatePerson("ml_kem768_x25519");

`static async generateMachine(algorithm?: string): Promise<VaultysId>`

Generates a new machine/service identity.

Parameters:

algorithm (string, optional): Cryptographic algorithm. Defaults to "ed25519"

Returns: Promise<VaultysId>

Example:

const service = await VaultysId.generateMachine("ed25519");

`static async generateOrganization(algorithm?: string): Promise<VaultysId>`

Generates a new organization identity.

Parameters:

algorithm (string, optional): Cryptographic algorithm. Defaults to "ed25519"

Returns: Promise<VaultysId>

Example:

const org = await VaultysId.generateOrganization("ed25519");

Identity Import/Export

`static fromId(id: string): VaultysId`

Creates a VaultysId from a serialized identity string.

Parameters:

id (string): Base64-encoded identity string

Returns: VaultysId

Throws: Error if the identity format is invalid

Example:

const serialized = existingId.id;
const imported = VaultysId.fromId(serialized);

`static fromSecret(secret: string): VaultysId`

Creates a VaultysId from a secret/private key.

Parameters:

secret (string): Base64-encoded secret key

Returns: VaultysId

Example:

const secret = "base64_encoded_secret_key";
const vaultysId = VaultysId.fromSecret(secret);

Entropy-based Creation

`static async fromEntropy(entropy: string, type?: string, algorithm?: string): Promise<VaultysId>`

Creates a deterministic identity from entropy.

Parameters:

entropy (string): Entropy string for deterministic generation
type (string, optional): Identity type. Defaults to TYPE_PERSON
algorithm (string, optional): Cryptographic algorithm

Returns: Promise<VaultysId>

Example:

const entropy = "some_random_entropy_string";
const deterministicId = await VaultysId.fromEntropy(entropy, TYPE_PERSON, "ed25519");

`static async personFromEntropy(entropy: string, algorithm?: string): Promise<VaultysId>`

Creates a person identity from entropy.

Parameters:

entropy (string): Entropy string
algorithm (string, optional): Cryptographic algorithm

Returns: Promise<VaultysId>

`static async machineFromEntropy(entropy: string, algorithm?: string): Promise<VaultysId>`

Creates a machine identity from entropy.

Parameters:

entropy (string): Entropy string
algorithm (string, optional): Cryptographic algorithm

Returns: Promise<VaultysId>

`static async organizationFromEntropy(entropy: string, algorithm?: string): Promise<VaultysId>`

Creates an organization identity from entropy.

Parameters:

entropy (string): Entropy string
algorithm (string, optional): Cryptographic algorithm

Returns: Promise<VaultysId>

FIDO2/WebAuthn Methods

`static createPublicKeyCredentialCreationOptions(requireResidentKey: boolean): PublicKeyCredentialCreationOptions`

Creates WebAuthn credential creation options for standard FIDO2.

Parameters:

requireResidentKey (boolean): Whether to require a resident key (for passkeys)

Returns: PublicKeyCredentialCreationOptions

Example:

const options = VaultysId.createPublicKeyCredentialCreationOptions(true);
const credential = await navigator.credentials.create({ publicKey: options });

`static createPublicKeyCredentialOptionsPQC(requireResidentKey: boolean): PublicKeyCredentialCreationOptions`

Creates WebAuthn credential creation options with post-quantum algorithms.

Parameters:

requireResidentKey (boolean): Whether to require a resident key

Returns: PublicKeyCredentialCreationOptions

`static async fido2FromAttestation(attestation: PublicKeyCredential, usePRF?: boolean): Promise<VaultysId>`

Creates a VaultysId from a WebAuthn attestation.

Parameters:

attestation (PublicKeyCredential): The attestation from navigator.credentials.create()
usePRF (boolean, optional): Whether to use PRF extension

Returns: Promise<VaultysId>

Example:

const options = VaultysId.createPublicKeyCredentialCreationOptions(true);
const attestation = await navigator.credentials.create({ publicKey: options });
const fido2Id = await VaultysId.fido2FromAttestation(attestation);

`static async createWebauthn(): Promise<VaultysId>`

Helper method to create a standard WebAuthn identity.

Returns: Promise<VaultysId>

`static async createPQC(): Promise<VaultysId>`

Helper method to create a post-quantum WebAuthn identity.

Returns: Promise<VaultysId>

Cryptographic Operations

`static async diffieHellman(id1: VaultysId, id2: VaultysId): Promise<Buffer>`

Performs Diffie-Hellman key exchange between two identities.

Parameters:

id1 (VaultysId): First identity
id2 (VaultysId): Second identity

Returns: Promise<Buffer> - Shared secret

Example:

const sharedSecret = await VaultysId.diffieHellman(alice, bob);

`static async encrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>`

Encrypts data for a specific recipient.

Parameters:

data (Buffer): Data to encrypt
recipientId (VaultysId): Recipient's VaultysId

Returns: Promise<Buffer> - Encrypted data

Example:

const encrypted = await VaultysId.encrypt(Buffer.from("secret"), recipientId);

Instance Properties

`fingerprint`

Gets the identity's fingerprint for visual verification.

Type: string (readonly)

Example:

const fp = vaultysId.fingerprint;
// "0355 E57E 7D06 A275 C7BD E1E6 49E0 735D 0DAF 1151"

`did`

Gets the Decentralized Identifier (DID) for the identity.

Type: string (readonly)

Example:

const did = vaultysId.did;
// "did:vaultys:0355E57E7D06A275C7BDE1E649E0735D0DAF1151"

`didDocument`

Gets the DID Document containing public keys and authentication methods.

Type: object (readonly)

Structure:

{
  "@context": ["https://www.w3.org/ns/did/v1"],
  "id": "did:vaultys:...",
  "authentication": [{
    "id": "did:vaultys:...#keys-1",
    "type": "Ed25519VerificationKey2020",
    "controller": "did:vaultys:...",
    "publicKeyMultibase": "..."
  }],
  "keyAgreement": [{
    "id": "did:vaultys:...#keys-2",
    "type": "X25519KeyAgreementKey2020",
    "controller": "did:vaultys:...",
    "publicKeyMultibase": "..."
  }]
}

`id`

Gets the serialized identity string.

Type: string (readonly)

Example:

const serialized = vaultysId.id;
// Can be used with VaultysId.fromId(serialized)

`version`

Gets the identity version.

Type: number (readonly)

`relationshipCertificate`

Gets the relationship certificate if present.

Type: Certificate | undefined (readonly)

Instance Methods

Identity Operations

`toVersion(version: number): VaultysId`

Converts the identity to a specific version.

Parameters:

version (number): Target version number

Returns: VaultysId

Example:

const v1Identity = vaultysId.toVersion(1);

`getSecret(): string`

Gets the secret/private key as a base64 string.

Returns: string

Security Note: Handle with care - this exposes the private key!

Example:

const secret = vaultysId.getSecret();
// Store securely or use for backup

Type Checking

`isHardware(): boolean`

Checks if the identity is hardware-based (FIDO2).

Returns: boolean

Example:

if (vaultysId.isHardware()) {
  console.log("This is a hardware key");
}

`isMachine(): boolean`

Checks if the identity is a machine/service type.

Returns: boolean

`isPerson(): boolean`

Checks if the identity is a person type.

Returns: boolean

Authentication

`async signChallenge(challenge: Challenge): Promise<SignedChallenge>`

Signs an authentication challenge.

Parameters:

challenge (Challenge): The challenge to sign

Returns: Promise<SignedChallenge>

Example:

const challenge = { nonce: crypto.randomBytes(32), timestamp: Date.now() };
const signed = await vaultysId.signChallenge(challenge);

`verifyChallenge(signedChallenge: SignedChallenge, publicKey: Buffer): boolean`

Verifies a signed challenge.

Parameters:

signedChallenge (SignedChallenge): The signed challenge to verify
publicKey (Buffer): Public key of the signer

Returns: boolean

Example:

const isValid = vaultysId.verifyChallenge(signedChallenge, senderPublicKey);

`async signChallenge_v0(challenge: Challenge): Promise<SignedChallenge>`

Legacy version of challenge signing (v0 protocol).

Parameters:

challenge (Challenge): The challenge to sign

Returns: Promise<SignedChallenge>

`verifyChallenge_v0(signedChallenge: SignedChallenge, publicKey: Buffer): boolean`

Legacy version of challenge verification (v0 protocol).

Parameters:

signedChallenge (SignedChallenge): The signed challenge
publicKey (Buffer): Public key of the signer

Returns: boolean

Encryption/Decryption

`async encrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>`

Encrypts data for a recipient (instance method).

Parameters:

data (Buffer): Data to encrypt
recipientId (VaultysId): Recipient's identity

Returns: Promise<Buffer>

Example:

const encrypted = await alice.encrypt(Buffer.from("secret"), bob);

`async decrypt(encryptedData: Buffer): Promise<Buffer>`

Decrypts data encrypted for this identity.

Parameters:

encryptedData (Buffer): Encrypted data

Returns: Promise<Buffer>

Example:

const decrypted = await bob.decrypt(encrypted);

`async signcrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>`

Signs and encrypts data in one operation.

Parameters:

data (Buffer): Data to sign and encrypt
recipientId (VaultysId): Recipient's identity

Returns: Promise<Buffer>

Example:

const signcrypted = await alice.signcrypt(Buffer.from("authenticated secret"), bob);

DHIES (Diffie-Hellman Integrated Encryption Scheme)

`async dhiesEncrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>`

Encrypts using DHIES.

Parameters:

data (Buffer): Data to encrypt
recipientId (VaultysId): Recipient's identity

Returns: Promise<Buffer>

`async dhiesDecrypt(encryptedData: Buffer, senderId: VaultysId): Promise<Buffer>`

Decrypts DHIES encrypted data.

Parameters:

encryptedData (Buffer): Encrypted data
senderId (VaultysId): Sender's identity

Returns: Promise<Buffer>

Key Exchange

`async performDiffieHellman(otherId: VaultysId): Promise<Buffer>`

Performs Diffie-Hellman key exchange with another identity.

Parameters:

otherId (VaultysId): The other party's identity

Returns: Promise<Buffer> - Shared secret

Example:

const sharedSecret = await alice.performDiffieHellman(bob);

OTP (One-Time Password)

`getOTP(length?: number): string`

Generates a one-time password.

Parameters:

length (number, optional): Length of the OTP. Defaults to 6

Returns: string

Example:

const otp = vaultysId.getOTP(6);
// "342819"

`getOTPHmac(secret: string, counter?: number): string`

Generates an HMAC-based OTP.

Parameters:

secret (string): Secret for HMAC
counter (number, optional): Counter value

Returns: string

Example:

const hotp = vaultysId.getOTPHmac("shared_secret", 1);

HMAC

`async hmac(data: Buffer): Promise<Buffer>`

Computes HMAC of data using the identity's key.

Parameters:

data (Buffer): Data to compute HMAC for

Returns: Promise<Buffer>

Example:

const mac = await vaultysId.hmac(Buffer.from("message"));

Error Handling

Most methods can throw errors for:

Invalid key formats
Unsupported algorithms
Hardware key unavailability
Cryptographic operation failures

Always wrap operations in try-catch blocks:

try {
  const vaultysId = await VaultysId.generatePerson("ed25519");
  const encrypted = await vaultysId.encrypt(data, recipient);
} catch (error) {
  console.error("Operation failed:", error.message);
}

Algorithm Support

The library supports multiple cryptographic algorithms:

Classical: Ed25519, X25519
Post-Quantum: Dilithium (signatures), ML-KEM/Kyber (key encapsulation)
Hybrid: Combinations like dilithium_ed25519, ml_kem768_x25519
Hardware: FIDO2/WebAuthn with various curves

Security Considerations

Private Keys: Never expose private keys (from getSecret()) in logs or insecure storage
Entropy: Use cryptographically secure random sources for entropy-based generation
Verification: Always verify signatures and certificates in authentication flows
Hardware Keys: Prefer hardware-based identities for high-security scenarios
Post-Quantum: Consider using post-quantum algorithms for future-proofing

Class: VaultysId​

Constants​

Identity Types​

Constructor​

constructor(type, keyManager, certificate?)​

Static Methods​

Identity Creation​

static async generatePerson(algorithm?: string): Promise<VaultysId>​

static async generateMachine(algorithm?: string): Promise<VaultysId>​

static async generateOrganization(algorithm?: string): Promise<VaultysId>​

Identity Import/Export​

static fromId(id: string): VaultysId​

static fromSecret(secret: string): VaultysId​

Entropy-based Creation​

static async fromEntropy(entropy: string, type?: string, algorithm?: string): Promise<VaultysId>​

static async personFromEntropy(entropy: string, algorithm?: string): Promise<VaultysId>​

static async machineFromEntropy(entropy: string, algorithm?: string): Promise<VaultysId>​

static async organizationFromEntropy(entropy: string, algorithm?: string): Promise<VaultysId>​

FIDO2/WebAuthn Methods​

static createPublicKeyCredentialCreationOptions(requireResidentKey: boolean): PublicKeyCredentialCreationOptions​

static createPublicKeyCredentialOptionsPQC(requireResidentKey: boolean): PublicKeyCredentialCreationOptions​

static async fido2FromAttestation(attestation: PublicKeyCredential, usePRF?: boolean): Promise<VaultysId>​

static async createWebauthn(): Promise<VaultysId>​

static async createPQC(): Promise<VaultysId>​

Cryptographic Operations​

static async diffieHellman(id1: VaultysId, id2: VaultysId): Promise<Buffer>​

static async encrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>​

Instance Properties​

fingerprint​

did​

didDocument​

id​

version​

relationshipCertificate​

Instance Methods​

Identity Operations​

toVersion(version: number): VaultysId​

getSecret(): string​

Type Checking​

isHardware(): boolean​

isMachine(): boolean​

isPerson(): boolean​

Authentication​

async signChallenge(challenge: Challenge): Promise<SignedChallenge>​

verifyChallenge(signedChallenge: SignedChallenge, publicKey: Buffer): boolean​

async signChallenge_v0(challenge: Challenge): Promise<SignedChallenge>​

verifyChallenge_v0(signedChallenge: SignedChallenge, publicKey: Buffer): boolean​

Encryption/Decryption​

async encrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>​

async decrypt(encryptedData: Buffer): Promise<Buffer>​

async signcrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>​

DHIES (Diffie-Hellman Integrated Encryption Scheme)​

async dhiesEncrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>​

async dhiesDecrypt(encryptedData: Buffer, senderId: VaultysId): Promise<Buffer>​

Key Exchange​

async performDiffieHellman(otherId: VaultysId): Promise<Buffer>​

OTP (One-Time Password)​

getOTP(length?: number): string​

getOTPHmac(secret: string, counter?: number): string​

HMAC​

async hmac(data: Buffer): Promise<Buffer>​

Error Handling​

Algorithm Support​

Security Considerations​

Class: VaultysId

Constants

Identity Types

Constructor

`constructor(type, keyManager, certificate?)`

Static Methods

Identity Creation

`static async generatePerson(algorithm?: string): Promise<VaultysId>`

`static async generateMachine(algorithm?: string): Promise<VaultysId>`

`static async generateOrganization(algorithm?: string): Promise<VaultysId>`

Identity Import/Export

`static fromId(id: string): VaultysId`

`static fromSecret(secret: string): VaultysId`

Entropy-based Creation

`static async fromEntropy(entropy: string, type?: string, algorithm?: string): Promise<VaultysId>`

`static async personFromEntropy(entropy: string, algorithm?: string): Promise<VaultysId>`

`static async machineFromEntropy(entropy: string, algorithm?: string): Promise<VaultysId>`

`static async organizationFromEntropy(entropy: string, algorithm?: string): Promise<VaultysId>`

FIDO2/WebAuthn Methods

`static createPublicKeyCredentialCreationOptions(requireResidentKey: boolean): PublicKeyCredentialCreationOptions`

`static createPublicKeyCredentialOptionsPQC(requireResidentKey: boolean): PublicKeyCredentialCreationOptions`

`static async fido2FromAttestation(attestation: PublicKeyCredential, usePRF?: boolean): Promise<VaultysId>`

`static async createWebauthn(): Promise<VaultysId>`

`static async createPQC(): Promise<VaultysId>`

Cryptographic Operations

`static async diffieHellman(id1: VaultysId, id2: VaultysId): Promise<Buffer>`

`static async encrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>`

Instance Properties

`fingerprint`

`did`

`didDocument`

`id`

`version`

`relationshipCertificate`

Instance Methods

Identity Operations

`toVersion(version: number): VaultysId`

`getSecret(): string`

Type Checking

`isHardware(): boolean`

`isMachine(): boolean`

`isPerson(): boolean`

Authentication

`async signChallenge(challenge: Challenge): Promise<SignedChallenge>`

`verifyChallenge(signedChallenge: SignedChallenge, publicKey: Buffer): boolean`

`async signChallenge_v0(challenge: Challenge): Promise<SignedChallenge>`

`verifyChallenge_v0(signedChallenge: SignedChallenge, publicKey: Buffer): boolean`

Encryption/Decryption

`async encrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>`

`async decrypt(encryptedData: Buffer): Promise<Buffer>`

`async signcrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>`

DHIES (Diffie-Hellman Integrated Encryption Scheme)

`async dhiesEncrypt(data: Buffer, recipientId: VaultysId): Promise<Buffer>`

`async dhiesDecrypt(encryptedData: Buffer, senderId: VaultysId): Promise<Buffer>`

Key Exchange

`async performDiffieHellman(otherId: VaultysId): Promise<Buffer>`

OTP (One-Time Password)

`getOTP(length?: number): string`

`getOTPHmac(secret: string, counter?: number): string`

HMAC

`async hmac(data: Buffer): Promise<Buffer>`

Error Handling

Algorithm Support

Security Considerations