Signing & Encryption
HMAC-SHA256 signing and AES-256-GCM encryption — tamper-proof and confidential data using the Web Crypto API.
Katman provides sign/unsign for tamper-proof data and encrypt/decrypt for confidential data. Both use the Web Crypto API — works in Node.js, Bun, Deno, and Cloudflare Workers.
Signing (HMAC-SHA256)
Signing proves that a value hasn't been tampered with. The value is still readable — it's not encrypted.
import { , } from "katman/plugins"
// Sign a value
const = await ("user:123", "my-secret-key")
// "user:123.a1b2c3d4..."
// Verify and extract
const = await (, "my-secret-key")
// "user:123" — or null if tamperedCommon use cases: session tokens in cookies, CSRF tokens, signed URLs.
Signed cookies
import { , } from "katman/plugins"
import { , } from "katman/cookies"
// Set a signed session cookie
const = await (, SECRET)
const = ("session", , { : true })
// Read and verify
const = (ctx.headers, "session")
const = ? await (, SECRET) : null
if (!) throw new KatmanError("UNAUTHORIZED")Encryption (AES-256-GCM)
Encryption makes data unreadable without the secret. Uses PBKDF2 key derivation with a random salt and IV per encryption.
import { , } from "katman/plugins"
const = await ("sensitive-data", "my-secret-key")
// "base64url-encoded-blob"
const = await (, "my-secret-key")
// "sensitive-data"Each call to encrypt() produces a different output (random salt + IV), so the same plaintext encrypted twice gives different ciphertexts. This is by design — it prevents pattern analysis.
When to use which
| Need | Use |
|---|---|
| Prove a value wasn't tampered with | sign / unsign |
| Hide a value from the client | encrypt / decrypt |
| Session tokens in cookies | sign (no need to hide the user ID) |
| Storing secrets in cookies | encrypt (the value must be confidential) |