Three seams, and openpgp.js does the rest

$ npm install openpgp        # ^6, provided by the host
$ npm install encedo-pgp-js  # hem-sdk-js sits alongside it

# bundles, if you want them built rather than imported from source
$ npm run build
  → dist/encedo-pgp.browser.js   # ~64 KB, openpgp external
  → dist/encedo-pgp.node.js      # same, node:crypto backend

The runtime split is only SHA-1, SHA-256 and AES key unwrap: node:crypto in Node, crypto.subtle in the browser. Everything else is the same code on both.

import { HEM } from 'hem-sdk-js'
import { buildCertificate, armorCertificate, DESCR, encodeDescr } from 'encedo-pgp-js'

const hem = new HEM('https://hsm.example.com')
await hem.hemCheckin()                              // connection + clock, once

const gen = await hem.authorizePassword(pw, 'keymgmt:gen')
const iat = Math.floor(Date.now() / 1000)           // baked into the fingerprint

const { kid: kidSign } = await hem.createKeyPair(gen, `pgp-sign-${email}`,
    'ED25519',   encodeDescr(DESCR.selfSign(email, iat)))
const { kid: kidEcdh } = await hem.createKeyPair(gen, `pgp-ecdh-${email}`,
    'CURVE25519', encodeDescr(DESCR.selfEcdh(email, iat)))

// one token per key — the scope names the KID it may be used on
const signTok = await hem.authorizePassword(pw, `keymgmt:use:${kidSign}`)
const ecdhTok = await hem.authorizePassword(pw, `keymgmt:use:${kidEcdh}`)

const { cert, fingerprint, keyId } = await buildCertificate(
    hem, signTok, kidSign, kidEcdh, email, { ecdhToken: ecdhTok, timestamp: iat })

const armored = armorCertificate(cert)   // -----BEGIN PGP PUBLIC KEY BLOCK-----

iat is passed rather than taken from the clock inside the builder, so the same keys always produce the same fingerprint. Rebuilding a certificate is then a pure function of what the module holds — there is no certificate to store, and nothing to lose.

const message = await openpgp.readMessage({ armoredMessage })
const pkesks  = message.packets.filterByTag(
    openpgp.enums.packet.publicKeyEncryptedSessionKey)

for (const p of pkesks) {                       // several, if several recipients
  let ephemeral, wrapped
  if ('V' in p.encrypted) {                     // algo 18, legacy ECDH
    ephemeral = p.encrypted.V                     //   0x40 || 32 bytes
    wrapped   = p.encrypted.C.data
  } else {                                      // algo 25, v6 X25519
    ephemeral = p.encrypted.ephemeralPublicKey
    wrapped   = p.encrypted.C.wrappedKey
  }
  const algoId = p.sessionKeyAlgorithm ?? openpgp.enums.symmetric.aes256

  // ECDH inside the module, KDF and AES-KW locally on the result
  const { data } = await hsmDecryptPkesk(
      ephemeral, wrapped, ourEcdhFingerprint, algoId, hem, ecdhTok, kidEcdh)

  const sessionKey = { data, algorithm: openpgp.enums.read(
      openpgp.enums.symmetric, algoId) }

  const { data: plaintext, signatures } = await openpgp.decrypt({
      message, sessionKeys: [sessionKey], verificationKeys })
  return plaintext
}

Signature verification stays entirely native: it needs only the sender’s public key, so it is passed to decrypt() as verificationKeys and never involves the module. hsmDecryptPkesk returns the numeric algoId rather than the enum name, so a host that bundles its own openpgp.js resolves the enum in its own instance.

// detached signature over the exact MIME bytes that will be sent
const { sigPkt } = await buildHsmSignaturePkt(
    hem, signTok, kidSign, keyId8, signedContent)

const armoredSig = (await openpgp.readSignature(
    { binarySignature: sigPkt })).armor()    // LF endings — see below

// multipart/signed; protocol="application/pgp-signature"; micalg=pgp-sha256
//   part 1: signedContent          (verbatim, byte for byte)
//   part 2: armoredSig             (application/pgp-signature)

// or, for the cleartext form:
const armoredMsg = await signCleartextMessage(
    hem, signTok, kidSign, keyId8, text)     // BEGIN PGP SIGNED MESSAGE

The module receives a SHA-256 digest and returns a standard Ed25519 signature — not Ed25519ph — which is what GnuPG, RNP and openpgp.js all verify. Two details decide whether a verifier agrees: the signed part must be transmitted byte for byte, and armor() emits LF while MIME wants CRLF, so convert the armoured signature before placing it in the message. Encryption needs no seam of its own: it uses the recipient’s public key, so openpgp.encrypt() runs natively and the module is not involved.

Tokens are short-lived and issued per scope. A page that only lists keys never holds a token that can sign, and a token that can sign with one key cannot decrypt with another.

import { lookupKey, publishKey } from 'encedo-pgp-js'

const keyBytes = await lookupKey('someone@example.com')
//   https://openpgpkey.example.com/.well-known/openpgpkey/example.com/hu/<z-base-32>
//   falls back to https://example.com/.well-known/openpgpkey/hu/<z-base-32>

await publishKey(wkdBase, email, cert, authToken)   // POST the binary certificate

The server side is encedo-wkd, also MIT: a small service that stores and serves certificates at those paths. Any other WKD host works just as well — the format is the standard one.

Import the pure-byte functions

buildHsmSignaturePkt, hsmDecryptPkesk, signCleartextMessage and buildCertificate make no openpgp.js calls, so they are safe to take from the bundle in any host.

Call the high-level API on your own instance

openpgp.readMessage, decrypt, encrypt and readKey should be called on the openpgp.js the host already bundles, with the session key or signature packet handed across.

Webpack wants the Node build

Given the choice, webpack resolves openpgp’s Node entry point, and EdDSA verification then fails in the browser with Unknown curve while decryption still appears to work. Alias openpgp$ to dist/openpgp.min.mjs and the symptom goes away.

Own keys are Ed25519 and X25519

The certificate builder emits an Ed25519 primary key with an X25519 subkey and nothing else. Correspondents on NIST P-256, P-384, P-521 or secp256k1 are handled natively by openpgp.js when encrypting to them and verifying them; the restriction is on what the module holds for you, not on who you can write to.

No key import, by design

A private key that can be loaded into the module is a private key that existed outside one. Identities are generated in the device, which means adopting this is a new certificate rather than a migration.

Signature verification is not done in the module

It needs only a public key, so it runs in openpgp.js. An earlier attempt to verify through the device was removed: openpgp.js v6 discards the trailing signature packet once the encrypted container is decrypted, so it could never see the signature it was meant to check. Trusting a sender because their key sits in the module is two separate questions — verify the signature natively, then confirm the certificate is the one the module holds for that address.

Hidden recipients are not universally readable

Encrypting with a wildcard key ID conceals who a message is for, but Thunderbird and RNP do not attempt trial decryption of anonymous recipients and will not open it. GnuPG and Proton Mail do. Treat it as a deliberate trade rather than a default.

Post-quantum is in the hardware, not in the mail

The module performs ML-KEM and ML-DSA today. OpenPGP is not there yet, and the library does not pretend otherwise.

Pre-1.0

0.1.0, MIT, no external security audit. The API may still move; the message formats it produces will not, because they are the standard’s.

On send

The composer hands over the MIME tree it was about to submit. The module signs it with buildHsmSignaturePkt, encrypts to the recipients’ certificates — fetched over WKD, or from a key server, and validated against the address — and returns a PGP/MIME body. Attachments and inline images go inside the encrypted part, not beside it.

On read

The reader detects multipart/encrypted and multipart/signed, obtains the session key through the module, decrypts, verifies against the sender’s certificate and renders a banner. The decrypted HTML is sanitised before it reaches the DOM.

What the server holds

Ciphertext. The mail server is not part of the trust decision at any point: the module is reached from the browser, and the certificates come from WKD.

$ node test/test-keygen.js  --hsm https://hsm.example.com --email you@example.com
$ node test/test-sign.js    --email you@example.com --message "Hello"
$ node test/test-encrypt.js --to someone@example.com --message "Secret"
$ node test/test-decrypt.js --email you@example.com --file /tmp/message.asc

# and the signature any OpenPGP implementation should accept:
$ gpg --verify <(node test/test-sign.js --email you@example.com --message "Hello")

The overview, including the threat model and what this costs you, is on the front page.