Proca SDK: encryption helpers

Proca server pushes actions to AMQP service in format defined in @proca/queue package. The action or event data can contain Personal Identifiable Information (PII) in encrypted form. This package provides helpers to decrypt the NaCL encrypted payload.

TypeScript types

• KeyStore - Contains NaCL key pairs used to decrypt PII.

Functions

• loadKeyStoreFromFile(filename : string) - load KeyStore from a file.

• loadKeyStoreFromString(content : string) - load KeyStore from a string

• storeKeyStoreToFile(keystore : KeyStore, filename? : string) - store KeyStore into file

• decryptPersonalInfo(pii : PersonalInfo | undefined, keyStore : KeyStore) : any - decrypt PersonalInfo record (see @proca/queue definitions) using a provided KeyStore

Development

npm install       # also builds dist/ via the "prepare" script
npm run build     # compile src/ -> dist/ (one-shot)
npm run watch     # recompile on change
npm test          # build, then run the test suite
npm run check     # run the test suite without rebuilding

dist/ is committed. A tracked pre-commit hook (.githooks/pre-commit, wired by npm install) rebuilds and stages dist/ whenever src/, tsconfig.json, or package.json is part of a commit, and blocks the commit if the build fails.

Testing

The suite exercises the real crypto against a static fixture — no network or Proca server required. test/fixtures/personalInfo.json is a real NaCl-encrypted queue record and test/fixtures/keystore.json holds the matching private key (a throwaway keypair generated for the tests). Because the ciphertext is frozen on disk rather than re-encrypted each run, the tests cover the whole decode -> decrypt -> parse path, not just a self-consistent round-trip.

| Test | Verifies | | --- | --- | | decrypt with matching key (from file and from string) | loadKeyStoreFromFile / loadKeyStoreFromString + decryptPersonalInfo -> { firstName, lastName, email, phone } | | keystore missing the key | returns null | | undefined pii | returns {} | | pii missing nonce / keys | throws | | wrong signing key | Poly1305 authentication fails -> throws | | decodeBase64url | 24-byte nonce, 32-byte key | | addKeysToKeyStore | merges and de-dupes by public key; rejects malformed input | | keystore file store -> load round-trip | survives, file mode is 0600, still decrypts | | storeKeyStoreToString | emits the { public: { private } } shape |