@app_/crypto
Cryptographic primitives for Atlas Protocol. Built on Falcon-1024 post-quantum signatures, X-Wing hybrid KEM encryption, and Blake3/SHA256 hashing.
Key generation
Generate Falcon-1024 keypairs. Both keys are returned as base64-encoded strings. Public keys are 1793 bytes, private keys are 2305 bytes.
import { generateKeyPair, isMatchingKeyPair } from '@app_/crypto/keygen';
// Generate a Falcon-1024 keypair (base64-encoded)
const { publicKey, privateKey } = await generateKeyPair();
// Verify a keypair matches
const valid = await isMatchingKeyPair(publicKey, privateKey); Signing & verification
Sign payloads with a Falcon private key and verify against the corresponding public key. Verification throws on failure.
import { signBytes, signString, verifyBytesSignature, verifyStringSignature } from '@app_/crypto/signing';
// Sign a string payload
const signature = await signString('hello world', privateKey);
// Verify — throws on failure
await verifyStringSignature('hello world', signature, publicKey);
// Sign raw bytes
const bytes = new Uint8Array([1, 2, 3]);
const sig = await signBytes(bytes, privateKey);
await verifyBytesSignature(bytes, sig, publicKey); Hashing
Hash strings with Blake3, bytes with SHA256 (returning CIDv1), or arbitrary data via deterministic serialization.
import { hashString, hashBytes, hashData, hashEnvelope, hashPrivateKey } from '@app_/crypto/hashing';
// Blake3 hash of a string
const hash = hashString('hello');
// SHA256 hash of bytes → returns CIDv1
const cid = hashBytes(new Uint8Array([1, 2, 3]));
// Hash arbitrary data (serialized with safe-stable-stringify)
const dataHash = hashData({ type: 'Person', name: 'Alice' });
// Hash a Falcon private key
const keyHash = hashPrivateKey(privateKey);
// Hash an envelope's structured fields
const envelopeHash = hashEnvelope({
data: envelopeData,
signature,
expiresAt,
recipientKeyId,
}); Envelopes
Sign and verify envelopes — the primary data container in Atlas. An envelope wraps Schema.org-typed data with a signature, content hash, and optional encryption fields.
import { signEnvelope, verifyEnvelope } from '@app_/crypto/envelope';
// Sign an envelope — returns { signature, contentHash, hash }
const signed = await signEnvelope({
data: { '@type': 'Article', name: 'Hello' },
privateKey,
expiresAt: undefined,
recipientKeyId: undefined,
});
// Verify envelope integrity and signature
await verifyEnvelope(
{ data: signed.data, signature: signed.signature, hash: signed.hash },
publicKey,
proofs, // optional: ProofOfWork or PermitProof array
now, // optional: custom timestamp for validation
); Encryption
HPKE encryption using X-Wing hybrid KEM for end-to-end encrypted envelopes. Also supports passphrase-based key backup with PBKDF2 + AES-256-GCM.
import { encryptHpkeMessage, decryptHpkeMessage } from '@app_/crypto/encryption';
import { encryptPrivateKeyWithPassphrase } from '@app_/crypto/encryption';
// HPKE encryption (X-Wing hybrid KEM)
const { kemCiphertext, encryptedData } = await encryptHpkeMessage(
recipientPublicKeyBase64,
{ secret: 'data' },
);
// HPKE decryption
const decrypted = await decryptHpkeMessage(
recipientPrivateKeyBase64,
kemCiphertext,
encryptedData,
);
// Passphrase-based key backup (PBKDF2 + AES-256-GCM)
const encrypted = await encryptPrivateKeyWithPassphrase(privateKey, 'my-passphrase'); Encoding utilities
import { stringToBytes, bytesToBase64, base64ToBytes, bytesToHex } from '@app_/crypto/encoding';
const bytes = stringToBytes('hello'); // Uint8Array
const b64 = bytesToBase64(bytes); // base64 string
const back = base64ToBytes(b64); // Uint8Array
const hex = bytesToHex(bytes); // hex string Key parsing & validation
import { parseRawPublicKey, parseRawPrivateKey, toHash, isFalconPublicKey, isHash } from '@app_/crypto/keys';
// Parse base64-encoded keys
const pubKeyBytes = parseRawPublicKey(publicKeyBase64);
const privKeyBytes = parseRawPrivateKey(privateKeyBase64);
// Convert public key to its hash identifier
const hash = toHash(publicKeyBase64);
// Validation checks
isFalconPublicKey(value); // true if valid Falcon-1024 public key
isHash(value); // true if 64-char hex string Proofs
Create and verify Proof of Work and Permit (delegated key) proofs. PoW proofs are signed attestations that a nonce was computed, with a validity window.
import {
signProofOfWorkProof,
verifyProofOfWorkSignature,
verifyPermitSignature,
getProofOfWorkValidity,
} from '@app_/crypto/proofs';
// Create a signed Proof of Work
const pow = await signProofOfWorkProof(nonce, validFrom, validUntil, privateKey);
// Verify PoW signature
await verifyProofOfWorkSignature(pow, authorPublicKey);
// Verify a Permit (delegated key) signature
await verifyPermitSignature(permit, authorPublicKey);
// Extract validity window
const { validFrom, validUntil } = getProofOfWorkValidity(pow); Dependencies
| Package | Purpose |
|---|---|
| falcon-crypto | Falcon-1024 post-quantum signatures |
| @hpke/hybridkem-x-wing | X-Wing hybrid KEM for encryption |
| @noble/hashes | Blake3 and SHA256 |
| multiformats | CIDv1 content identifiers |
| safe-stable-stringify | Deterministic JSON serialization |