stacks-security

name	stacks-security
description	Use when implementing security in Stacks — password hashing (bcrypt/argon2), app key generation, AES encryption/decryption, hash verification, rehashing detection, or security configuration (firewall, rate limiting, IP allowlists). Covers @stacksjs/security and config/security.ts.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

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

import { generateAppKey } from '@stacksjs/security'

const key = generateAppKey()  // 32-character random string
// Run via CLI: buddy key:generate

Encryption / Decryption

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

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

bcryptEncode(value, rounds?)     // bcrypt hash
bcryptVerify(value, hash)        // bcrypt verify
argon2Encode(value, options?)    // argon2 hash
argon2Verify(value, hash)        // argon2 verify
md5Encode(value)                  // MD5 (legacy only)
base64Encode(value)               // base64
base64Verify(value, encoded)      // base64 compare

HashMakeOptions

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

{
  driver: 'bcrypt',
  bcrypt: { rounds: 12 },
  argon2: { memory: 65536, time: 3 }
}

config/security.ts

{
  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
• md5Encode() exists for legacy compatibility only — never use for passwords
• The firewall config is used by cloud deployment for WAF rules
• Rate limiting is per-minute per-IP (500 default)