stacks-security

# Stacks Security ## Key Paths - Core package: `storage/framework/core/security/src/` - Security config: `config/security.ts` - Hashing config: `config/hashing.ts` ## Source Files ``` security/src/ ├── index.ts # all exports ├── key.ts # generateAppKey() ├── crypt.ts # encrypt/decrypt (AES via APP_KEY) └── hash.ts # password hashing (bcrypt/argon2) ``` ## App Key Generation ```typescript import { generateAppKey } from '@stacksjs/security' const key = generateAppKey() // 32-character random string // Run via CLI: buddy key:generate ``` ## Encryption / Decryption ```typescript import { encrypt, decrypt } from '@stacksjs/security' const encrypted = await encrypt('sensitive data') // uses APP_KEY const encrypted = await encrypt('data', 'custom-passphrase') const decrypted = await decrypt(encrypted) const decrypted = await decrypt(encrypted, 'custom-passphrase') ``` ## Password Hashing ```typescript import { make, check, needsRehash, info, detectAlgorithm } from '@stacksjs/security' // Hash a password const hash = await make('password123') // bcrypt (default) const hash = await make('password123', { algorithm: 'argon2' }) const hash = await make('password123', { rounds: 14 }) // bcrypt rounds // Verify const valid = await check('password123', hash) // true/false // Check if rehash needed (e.g., after changing rounds) const needs = needsRehash(hash, { rounds: 14 }) // Inspect hash const hashInfo = info(hash) // { algorithm, options } const algo = detectAlgorithm(hash) // 'bcrypt' | 'argon2' | 'argon2id' | ... ``` ### Aliases - `hashMake` = `make` - `hashCheck` = `check` - `hashNeedsRehash` = `needsRehash` - `hashInfo` = `info` - `makeHash` = `make` - `verifyHash` = `check` ### Algorithm-Specific Functions ```typescript bcryptEncode(value, rounds?) // bcrypt hash bcryptVerify(value, hash) // bcrypt verify argon2Encode(value, options?) // argon2 hash argon2Verify(value, hash) // argon2 verify base64Encode(value) // base64 ``` ## HashMakeOptions ```typescript interface HashMakeOptions { algorithm?: 'bcrypt' | 'argon2' | 'argon2id' | 'argon2i' | 'argon2d' rounds?: number // bcrypt (default: 12) memory?: number // argon2 (default: 65536) time?: number // argon2 (default: 3) } ``` ## config/hashing.ts ```typescript { driver: 'bcrypt', bcrypt: { rounds: 12 }, argon2: { memory: 65536, time: 3 } } ``` ## config/security.ts ```typescript { firewall: { enabled: true, countryCodes: [], // block by country ipAddresses: { allowlist: [], blocklist: [] }, rateLimitPerMinute: 500, useIpReputationLists: true, useKnownBadInputsRuleSet: true } } ``` ## Gotchas - Default hashing is bcrypt with 12 rounds — sufficient for most applications - `needsRehash()` compares current hash options against provided options — useful after config changes - APP_KEY is used for `encrypt()`/`decrypt()` — generate via `buddy key:generate` - APP_KEY format is colon-separated (validated during deployment) - Argon2 requires more memory/time but is more resistant to GPU attacks - Base64 is encoding, not hashing. Never use `base64Encode()` for credentials. - MD5 and base64 password verification are intentionally absent from the main security API. - The firewall config is used by cloud deployment for WAF rules - Rate limiting is per-minute per-IP (500 default)