OpenPGP armor
Base64 in a nice suit
That PGP key you once pasted into a form? Armor. It's base64 with a -----BEGIN PGP MESSAGE----- line on top, an END line below and a few Name: value headers if somebody felt chatty. Nothing is encrypted by the armor itself. It just keeps binary packets alive in an email.
import { armor } from "@agntn/encodings";
const block = armor.encode(new TextEncoder().encode("Hello, armor"), {
label: "MESSAGE",
headers: [["Comment", "not encrypted, just wrapped"]],
});
// -----BEGIN PGP MESSAGE-----
// Comment: not encrypted, just wrapped
//
// SGVsbG8sIGFybW9y
// -----END PGP MESSAGE-----
armor.decode(block);
// { label: "MESSAGE", headers: [["Comment", "not encrypted, just wrapped"]],
// bytes: Uint8Array(12), checksum: "absent" }
The label is whatever follows BEGIN PGP . MESSAGE, PUBLIC KEY BLOCK, SIGNATURE, or your own. Headers are pairs, in order, so a repeated Comment stays repeated. Lines come out at 64 characters, the way GnuPG writes them.
What's that = line above END?
Older blocks carry a CRC24 there, a 24-bit checksum of the bytes. RFC 9580 says to stop writing it, and never to reject a block over it. So encode leaves it out unless you ask.
armor.encode(new TextEncoder().encode("Hello, armor"), { label: "MESSAGE", checksum: true });
// -----BEGIN PGP MESSAGE-----
//
// SGVsbG8sIGFybW9y
// =o0JO
// -----END PGP MESSAGE-----
And decode never throws on it. A wrong one shows up as checksum: "mismatch" next to perfectly good bytes. Want to warn somebody that the text got changed or cut? Go ahead. The bytes are still yours to use.
Armor from the wild
Real armor arrives pasted, forwarded and a bit mangled. decode takes it the way it comes:
- text around the block, like the rest of an email,
- CRLF line ends and indented lines,
- a lost blank line under the headers,
- spaces and blank lines inside the base64.
Two blocks in one text? You get the first one. Pass label: "SIGNATURE" and it skips to the one you want. A cleartext signed message isn't armor at all, only its signature block is. So decode steps over the SIGNED MESSAGE frame and hands you the SIGNATURE. Checking that signature is a job for @agntn/keys.
What it won't take is a block with no END line, a checksum line with data under it, or data that isn't base64. Each one is a DecodeError. A label in lowercase, or one with PGP already in it, is an InvalidOptionError that tells you what to pass instead.
Where it lives
decode hands back a label and headers along with the bytes, and nothing in the registry does that. So armor sits outside it, like RLP and the code pages. The subpath is @agntn/encodings/armor. No CLI command and no agent tool yet, just the two functions.