pqforge 0.1.0

A secure, opinionated cryptographic wrapper designed to enforce safe post-quantum and classical composition in Dart/Flutter and Serverpod ecosystems. By bridging pqcrypto and pointycastle, pqforge eli [...]

pqforge

Post-quantum application recipes for Dart, Flutter, Serverpod, and local CLI workflows.

Project Signals

Cryptographic Surface

Automation And Discovery

pqforge turns pqcrypto ML-KEM and ML-DSA primitives into practical, domain-separated application workflows: encrypted files, folders, text, media, email payloads, records, signed documents, signed webhooks, signed tokens, release artifacts, tamper-evident logs, hybrid sessions, wrapped key custody, and a reusable CLI.

It is deliberately more than "call a primitive." It gives users named, auditable operations they can explain in a code review.

First Run

dart pub get

export PQFORGE_PASSPHRASE='load-this-from-a-secret-manager'
dart run pqforge keygen \
  --profile maximum \
  --key-id vault \
  --out-dir keys \
  --passphrase-env PQFORGE_PASSPHRASE

dart run pqforge encrypt-folder \
  --recipient-public keys/vault.kem.public.json \
  --in-dir ./records \
  --out-dir ./records.pqf

dart run pqforge decrypt-folder \
  --recipient-secret keys/vault.kem.secret.wrapped.json \
  --passphrase-env PQFORGE_PASSPHRASE \
  --in-dir ./records.pqf \
  --out-dir ./records.open

keygen --out-dir stores reusable keys in the selected directory. Public keys are raw JSON. Secret keys are Argon2id + AES-256-GCM wrapped JSON when you pass --passphrase-env, --passphrase-file, or --passphrase.

What You Can Build

App idea	Use this surface
Local file vaults and server export jobs	encrypt, decrypt, encryptFileBytes
Folder archives and evidence bundles	encrypt-folder, decrypt-folder, encryptFolderEntry
Notes, prompts, and short secrets	encrypt-text, decrypt-text, sealText, signText
Images, audio, video, PDFs, and media records	encrypt-media, decrypt-media, sealMedia, signMedia
Contracts, approvals, certificates, and reports	sign --kind document, signDocument
Payment callbacks and server events	signWebhook, verifyWebhook
API capability grants and admin actions	issueToken, verifyToken
Secure notification bodies	sealEmail, openEmail
Medical, government, and registry records	encryptRecord, appendSignedLogEntry
Release bundles and firmware	sign --kind artifact, signArtifact
Serverpod/API hybrid sessions	PqForgeHybridKeyAgreement, PqForgeSecureSession

The full app catalog is in doc/cookbook/PROJECT_CATALOG.md.

Library Quickstart

import 'dart:typed_data';
import 'package:pqforge/pqforge.dart';

final forge = PqForge(profile: PqForgeProfile.maximum);
final keys = forge.generateKeys(keyId: 'archive-key');

final envelope = forge.sealMedia(
  keys.kemKeyPair.publicKey,
  mediaBytes,
  mediaId: 'cover-2026-001',
  mimeType: 'image/png',
);

final opened = forge.openMedia(
  keys.kemKeyPair.secretKey,
  envelope,
);

final signature = forge.signArtifact(
  signerSecretKey: keys.signatureKeyPair.secretKey,
  artifactId: 'release.tar.gz',
  version: 7,
  artifactBytes: Uint8List.fromList(opened),
);

CLI Commands

Command	Purpose
keygen	Generate public keys and raw or wrapped secret keys
encrypt / decrypt	Encrypt and decrypt a single file
encrypt-folder / decrypt-folder	Encrypt and decrypt folder trees
encrypt-text / decrypt-text	Encrypt and decrypt UTF-8 text
encrypt-media / decrypt-media	Encrypt and decrypt media or PDFs
sign / verify	Sign and verify documents, text, media, and artifacts

Read the complete command guide at doc/CLI.md.

Profiles

Profile	KEM	Signature	Best for
compact	ML-KEM-512	ML-DSA-44	smaller demos and constrained payloads
balanced	ML-KEM-768	ML-DSA-65	default application and server workflows
maximum	ML-KEM-1024	ML-DSA-87	long-lived records, archives, media, and high-value artifacts

Hybrid Sessions

The optional package:pqforge/pqforge_cryptography.dart entrypoint adds:

• PqForgeHybridKeyAgreement for X25519 + ML-KEM session key agreement;
• PqForgeHybridSigner for ML-DSA + Ed25519 dual signatures;
• PqForgeSecureSession for AES-256-GCM or ChaCha20-Poly1305 packets;
• SecretKey.deriveHybridSecretKey() for package:cryptography users.

ECDSA remains app-supplied through dualSign / dualVerify because cryptography 2.9.0 exposes P-256 but does not implement Dart VM key generation for that path.

Claim Boundary

Allowed:

• "FIPS 203-aligned ML-KEM through pqcrypto."
• "FIPS 204-aligned ML-DSA through pqcrypto."
• "Application-layer composition helpers for KEM-DEM, AEAD sessions, wrapped key custody, signatures, recipes, and CLI workflows."

Do not claim:

• "FIPS validated", "CMVP validated", or "certified";
• hard constant-time Dart behavior;
• hard memory erasure;
• "ML-KEM alone is secure transport";
• AES signs documents;
• RC4 support.

RC4 is not supported. AES is encryption, not signatures.

Documentation

• GitHub Pages use-case site
• Documentation index
• CLI guide
• Project catalog
• Cookbook
• API reference
• Hybrid audit
• Key custody
• Claim boundary
• Visibility generation

Validation

dart run tool/visibility/generate_visibility.dart --check
dart format --output=none --set-exit-if-changed .
dart analyze
dart test
dart run example/pqforge_example.dart
dart run example/catalog_recipes_example.dart
dart run example/hybrid_key_agreement_example.dart
dart pub publish --dry-run