For full documentation, visit docs.postguard.eu.
TypeScript/JavaScript SDK for PostGuard, published as @e4a/pg-js on npm. Works in both browsers and Node.js.
PostGuard encrypts data for recipients based on their identity attributes (email address, phone number, etc.) rather than traditional public keys. Recipients prove their identity via Yivi to decrypt. This SDK is the main way web applications and email add-ons integrate with PostGuard.
Quick Start
npm install @e4a/pg-js
import { PostGuard } from '@e4a/pg-js';
const pg = new PostGuard({
pkgUrl: 'https://pkg.postguard.eu',
});
// Encrypt
const sealed = pg.encrypt({
sign: pg.sign.apiKey('your-api-key'),
recipients: [pg.recipient.email('[email protected]')],
files: fileList,
});
const { uuid } = await sealed.upload();
// Decrypt
const opened = pg.open({ uuid });
const result = await opened.decrypt({ element: '#yivi-popup' });
result.download();
See the full API reference for encryption options, signing methods, recipient types, and email helpers.
Server-side usage (Node, Bun, Deno)
The SDK works in non-browser runtimes for the encrypt + upload path
when signing via sign.apiKey or a custom sign.session callback. No
polyfills required.
Minimum runtime versions:
| Runtime | Minimum | Notes |
|---|---|---|
| Node | 22+ | Enforced via engines.node. The build tool requires Node 22.18+; runtime is tested on 22 and 24. |
| Bun | 1.0.16+ | First release with AbortSignal.any (the SDK's tightest web-API requirement) |
| Deno | 1.39+ | First release with AbortSignal.any |
Other notes:
sign.yivi(...)requires a DOM and is browser-only. The SDK throws a clearYiviSessionErrorupfront on non-browser runtimes — usesign.apiKeyorsign.sessioninstead.- For decryption,
result.blobandresult.plaintextare universal;result.download(...)triggers a browser download and is browser-only. sealed.upload()refusesdata: ReadableStream— usesealed.toBytes()for streaming, or passdataasUint8Array.
A manual smoke test for any runtime lives at scripts/smoke.mjs. Set
PG_API_KEY to a staging key to exercise the full upload pipeline:
PG_API_KEY=PG-... node scripts/smoke.mjs
PG_API_KEY=PG-... bun scripts/smoke.mjs
PG_API_KEY=PG-... deno run -A scripts/smoke.mjs
Development
This package lives in a pnpm workspace at packages/pg-js. From the repo root:
pnpm install # runs the prebuild generators + a full build via `prepare`
pnpm build
Run the tests:
pnpm test
Watch mode (pnpm dev, pnpm test:watch) runs from this directory.
Releasing
Releases are managed by changesets. A PR that should ship runs pnpm changeset and commits the generated file; merging to main opens (or updates) a "Version Packages" PR, and merging that publishes to npm with provenance.
License
MIT