@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.

keygen.ts
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.

signing.ts
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.

hashing.ts
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.

envelope.ts
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.

encryption.ts
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

encoding.ts
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

keys.ts
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.

proofs.ts
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-cryptoFalcon-1024 post-quantum signatures
@hpke/hybridkem-x-wingX-Wing hybrid KEM for encryption
@noble/hashesBlake3 and SHA256
multiformatsCIDv1 content identifiers
safe-stable-stringifyDeterministic JSON serialization