EarnmoreClient
Source: index.ts:170
A stateful client that derives the PBKDF2 HMAC key once at construction and caches it for fast repeated operations.
Implements:
- Key versioning (NIST SP 800-57 / ISO 11568-1):
keyIdin constructor - Key Check Value (ISO 11568-2):
getKCV() - Cryptoperiod enforcement (NIST SP 800-57 §5.3.6):
isKeyExpired() - Audit event hooks (CSF 2.0 DE.AE-02 / ISO 27001:2022 A.8.15):
onEvent - Secure key zeroing on decommission:
destroy()
Constructors
new EarnmoreClient(
passkey: string,
config: ComplianceConfig,
): EarnmoreClient
Parameters
passkey(string) — Secret passkey string (≥16 chars)config(ComplianceConfig) — Optional compliance config:
Returns
EarnmoreClient
Methods
decryptPAN(
encrypted: EncryptedPAN,
encryptionKey: Buffer,
): string
Decrypts an EncryptedPAN.
Parameters
encrypted(EncryptedPAN) — Result from encryptPAN()encryptionKey(Buffer) — The same 32-byte key used for encryption
Returns
string
destroy(): void
Zeros the cached derived key and marks this client as destroyed. Call this when the client will no longer be used to clear key material from process memory.
Returns
void
encryptPAN(pan: string, encryptionKey: Buffer): EncryptedPAN
Encrypts a PAN for at-rest storage (AES-256-GCM).
Parameters
pan(string) — 16-digit PANencryptionKey(Buffer) — 32-byte key — MUST be different from the CVV passkey (PCI-DSS Req 3.7.5)
Returns
generate(customer: CustomerInfo): CardResult
Generates a unique card from customer identity data. CVV is derived using the cached HMAC key and this client's keyId.
⚠️ Store card.keyId alongside the card record — required for validation after key rotation (NIST SP 800-57 / ISO 11568-1).
Parameters
customer(CustomerInfo)
Returns
generateDynamicCvv(
pan: string,
expiry: string,
atc: number,
): string
Generates a dynamic CVV (dCVV) using this client's cached HMAC key. EMVCo cryptograms bind an Application Transaction Counter (ATC) to the message.
Parameters
pan(string)expiry(string)atc(number)
Returns
string
getKCV(): string
Returns the Key Check Value (KCV) for this client's derived key.
The KCV is a non-secret 6-character hex fingerprint (ISO 11568-2). Store it alongside your key configuration and verify on startup to confirm the correct passkey was loaded.
Returns
string— 6-character hex KCV (e.g. "a3f2c1")
getKeyId(): string
Returns the key identifier this client was initialized with. Store alongside card records for key rotation support.
Returns
string
isKeyExpired(maxAgeYears: number): boolean
Checks whether this key has exceeded its recommended cryptoperiod.
Per NIST SP 800-57 Part 1 Rev.5 §5.3.6, HMAC authentication keys should not be used beyond 2 years (NIST_HMAC_KEY_MAX_YEARS).
Parameters
maxAgeYears(number, default: "NIST_HMAC_KEY_MAX_YEARS") — Maximum key age in years. Default: NIST_HMAC_KEY_MAX_YEARS (2)
Returns
boolean— true if the key age exceeds maxAgeYears
maskPAN(pan: string): string
Masks a PAN per PCI-DSS Req 3.5. Returns first 6 + 6 masked chars + last 4.
Parameters
pan(string)
Returns
string
redactCardResult(result: CardResult): StorableCardData
Strips CVV (SAD) from a CardResult, returning a StorableCardData object safe to persist per PCI-DSS Req 3.3.1. The keyId is preserved in StorableCardData for future validation.
Parameters
result(CardResult)
Returns
validateCvv(pan: string, expiry: string, cvv: string): boolean
Validates a CVV using this client's cached HMAC key and keyId. Uses constant-time comparison — no PBKDF2 per call.
For cards issued under a different keyId, use the corresponding EarnmoreClient instance (with the matching passkey and keyId).
Parameters
pan(string)expiry(string)cvv(string)
Returns
boolean
validateDynamicCvv(
pan: string,
expiry: string,
atc: number,
dcvv: string,
): boolean
Validates a dynamic CVV (dCVV) using this client's cached HMAC key.
Parameters
pan(string)expiry(string)atc(number)dcvv(string)
Returns
boolean