vanara 0.1.0 → 0.2.0

package/catalog/skills/secrets-management/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: secrets-management
+description: Handle secrets safely across the lifecycle — keep them out of source, load from env or a secret manager, scope to least privilege, encrypt in transit and at rest, rotate on a schedule, and respond fast when one leaks. Deep reference with runbooks, examples, and a runnable leak scanner.
+type: skill
+version: 2.0.0
+updated: 2026-06-29
+---
+# Secrets Management
+
+A secret committed to source control is **already compromised** — assume it is public the moment it lands
+in history, even on a private repo. Git history, CI logs, container layers, backups, and forks all retain
+it. The only safe response is rotation, not deletion. This skill is the deep reference for keeping secrets
+out of code, supplying them safely at runtime, and reacting correctly when one escapes. Heavy detail lives
+in `references/`; copy-paste material in `examples/`; a runnable leak scanner in `scripts/`.
+
+## Mental model
+
+Treat a secret as **runtime configuration**, never as code. Code is committed, reviewed, copied, and
+shipped to laptops; secrets must not ride along. Separate three concerns and never collapse them:
+
+| Concern | Question | Answer |
+|---|---|---|
+| Storage | where does the truth live? | a secret manager (Vault, cloud KMS/Secrets Manager) |
+| Delivery | how does the app get it? | injected env var or a fetch at boot, over TLS |
+| Lifecycle | how does it change? | rotation on a schedule + on suspected leak |
+
+The application code should only ever *read* a secret from its environment — it should never know the
+storage backend, the rotation cadence, or the raw value's origin. That decoupling is what lets you rotate
+a leaked key with **zero code changes**.
+
+## 1. Keep secrets out of source
+
+1. Never hardcode keys, tokens, passwords, connection strings, or private keys in source — not even
+   "temporarily". Temporary hardcodes are how most leaks happen.
+2. Commit a placeholder template (`.env.example`) with **fake** values and key names only; add the real
+   `.env` to `.gitignore` before the first commit.
+3. Add a secret scanner to pre-commit hooks **and** CI so a leak is caught before it reaches the remote.
+   Run `scripts/detect-hardcoded.mjs` over diffs or files as a zero-dependency gate.
+4. Load and validate required secrets at startup; fail fast with a clear message naming the missing var.
+
+```js
+// Read from the environment; never embed the value. Validate at boot.
+const required = ['DATABASE_URL', 'STRIPE_SECRET_KEY', 'JWT_SIGNING_KEY'];
+const missing = required.filter((k) => !process.env[k]);
+if (missing.length) {
+  throw new Error(`Missing required secrets: ${missing.join(', ')}`);
+}
+const stripeKey = process.env.STRIPE_SECRET_KEY; // if this leaks, rotate the value — no code change
+```
+
+## 2. Environment variables vs secret managers
+
+Env vars are the universal **delivery** mechanism, but they are not a secure **store** — they leak via
+`/proc`, crash dumps, child processes, and accidental `console.log(process.env)`. For anything beyond a
+single dev machine, the source of truth belongs in a manager.
+
+| Approach | Good for | Watch out for |
+|---|---|---|
+| `.env` file (gitignored) | local dev only | easy to commit by accident; no rotation, no audit |
+| Platform env vars (CI/PaaS) | small apps, single-tenant | visible to anyone with dashboard access; static |
+| Secret manager (Vault, AWS/GCP/Azure) | production, teams | needs auth bootstrap; adds a runtime dependency |
+| Cloud KMS (envelope encryption) | encrypting data + secrets | key policy mistakes are silent until exploited |
+
+A manager buys you **dynamic, short-lived credentials** (e.g. Vault issues a DB credential that auto-expires
+in 1 hour), centralized **audit logs**, and **rotation without redeploys**. See
+`references/secret-managers.md` for the comparison and bootstrap-auth patterns.
+
+## 3. Least privilege & short-lived credentials
+
+- Scope every credential to the **minimum** resources and actions it needs; a build token does not need
+  prod database write access.
+- Prefer **short-lived** dynamic credentials over long-lived static keys. A credential that lives 15
+  minutes limits the blast radius of a leak to 15 minutes.
+- Use **distinct** credentials per service and per environment so revocation is surgical, not a blackout.
+- Never share one "god" key across services — you lose the ability to attribute and revoke.
+
+## 4. Encryption in transit and at rest
+
+- **In transit:** fetch secrets only over TLS; reject plaintext transports. Never pass secrets as URL
+  query params (they land in logs, proxies, and browser history) — use headers or the request body.
+- **At rest:** the manager encrypts its store; for data you encrypt yourself, use **envelope encryption**
+  (a KMS-held key encrypts per-record data keys) rather than a single static key in config.
+- Keep secrets out of logs, error reports, and APM traces. Redact at the logging boundary — see the
+  scanner's redaction logic and `references/leak-response.md`.
+
+## 5. Rotation
+
+Rotation is the difference between "we had an incident" and "we had a non-event." Two triggers:
+
+1. **Scheduled** — rotate on a fixed cadence (e.g. 90 days for static keys) so no credential is ancient.
+2. **Reactive** — rotate **immediately** on any suspected exposure, no matter how minor it looks.
+
+The safe pattern is **overlap**: provision the new credential, deploy it, verify, then revoke the old —
+so there is no downtime window. The full step-by-step is in
+[`references/rotation.md`](references/rotation.md) and a fill-in incident checklist is in
+`examples/rotation-runbook.md`.
+
+## Common pitfalls (failure modes)
+
+- **"It's a private repo, so it's fine."** Forks, clones, CI caches, and future open-sourcing all expose
+  it. Private is not secret.
+- **Deleting the commit instead of rotating.** `git rm` / force-push does not erase history from clones,
+  caches, and PR mirrors. The credential is burned — rotate it.
+- **Logging the whole environment.** `console.log(process.env)` or dumping config on a crash ships every
+  secret to your log aggregator. Redact at the boundary.
+- **Secrets in URLs.** Query-string tokens leak into access logs, referrer headers, and proxies.
+- **One static key forever.** No rotation means a years-old leak is still valid today.
+- **Over-scoped credentials.** A read-only reporting job holding admin keys turns a small leak into a
+  full compromise.
+- **Checking `.env.example` with real values.** The template must contain only obviously fake placeholders.
+
+## When NOT to use / trade-offs
+
+- **A full secret manager for a solo side project** is overkill — gitignored `.env` plus a pre-commit
+  scanner is proportionate. Adopt a manager when you have a team, multiple environments, or compliance needs.
+- **Short-lived dynamic credentials add operational complexity** (auth bootstrap, renewal, clock skew). If
+  your platform can't renew reliably, a rotated static key with tight scope may be the pragmatic choice.
+- **Client-side secrets don't exist.** Anything shipped to a browser or mobile app is public; never put a
+  secret in front-end code — use a backend proxy or short-lived scoped tokens instead.
+- **Encrypting everything** has key-management cost. Encrypt what's sensitive; don't build a KMS maze for
+  non-secret config.
+
+## Files in this package
+
+- `references/secret-managers.md` — env vars vs Vault/cloud managers, bootstrap auth, dynamic creds
+- `references/rotation.md` — scheduled & reactive rotation, zero-downtime overlap pattern
+- `references/leak-response.md` — what to do in the first hour after a leak; redaction guidance
+- `examples/env-example.md` — a model `.env.example` with safe placeholders and `.gitignore` notes
+- `examples/rotation-runbook.md` — fill-in incident/rotation checklist
+- `scripts/detect-hardcoded.mjs` — zero-dep scanner that flags & redacts hardcoded secrets (`--selftest`)
+
+Pairs with the `secure-auth` skill (where signing keys and session secrets come from), the `owasp-top10`
+skill (A07 identification/auth failures, A02 cryptographic failures), and the `security-auditor` agent for
+a full credential-handling review.

package/catalog/skills/secrets-management/examples/env-example.md

@@ -0,0 +1,41 @@
+# Model `.env.example`
+
+Commit this template; never commit the real `.env`. Values here are **obviously fake placeholders** so a
+scanner won't flag them and a human won't mistake them for real. Document every key the app needs.
+
+```dotenv
+# === Database ===
+# Real value lives in the secret manager; this is the shape only.
+DATABASE_URL=postgres://USER:PASSWORD@localhost:5432/appdb
+
+# === Third-party APIs ===
+STRIPE_SECRET_KEY=sk_test_REPLACE_ME_xxxxxxxxxxxxxxxx
+SENDGRID_API_KEY=SG.REPLACE_ME.xxxxxxxxxxxxxxxxxxxxxxxx
+
+# === Auth / signing ===
+# Generate locally with: openssl rand -base64 32
+JWT_SIGNING_KEY=REPLACE_WITH_RANDOM_32_BYTES
+SESSION_SECRET=REPLACE_WITH_RANDOM_32_BYTES
+
+# === Runtime config (not secret) ===
+NODE_ENV=development
+LOG_LEVEL=info
+```
+
+## `.gitignore` (add before the first commit)
+
+```gitignore
+# Real secrets — never commit
+.env
+.env.local
+.env.*.local
+*.pem
+*.key
+```
+
+## Rules
+
+1. Keep `.env.example` in sync with the code — every `process.env.X` the app reads should appear here.
+2. Placeholders must be clearly fake: `REPLACE_ME`, `sk_test_...`, `xxxx`. Never a redacted-but-real value.
+3. The real `.env` is for local dev only. In CI/production, inject values from the secret manager.
+4. Validate presence at startup (see `SKILL.md` §1) so a missing key fails fast with a named error.

package/catalog/skills/secrets-management/examples/rotation-runbook.md

@@ -0,0 +1,50 @@
+# Rotation / Leak Runbook (fill-in)
+
+Copy this into your incident tracker and fill the blanks. The goal of the first hour is to make the leaked
+credential useless — rotate first, investigate second.
+
+## Incident header
+
+- **Date / time detected (UTC):** ________
+- **Detected by:** (scanner / human / third-party report) ________
+- **Credential type:** (API key / DB password / signing key / deploy token / other) ________
+- **Where it leaked:** (commit SHA / log / screenshot / paste / laptop) ________
+- **Likely exposure window start:** ________
+
+## Step 1 — Rotate / revoke (do this FIRST)
+
+- [ ] Provision replacement credential
+- [ ] Deploy / inject new value via secret manager
+- [ ] Verify new credential works in production
+- [ ] Revoke the leaked credential
+- [ ] New credential id / version: ________
+
+## Step 2 — Assess blast radius
+
+- [ ] What can this credential do? ________
+- [ ] Which environments / data are reachable? ________
+- [ ] Could it have unlocked other secrets? (list) ________
+
+## Step 3 — Check for abuse
+
+- [ ] Pulled audit logs since exposure window: yes / no
+- [ ] Unfamiliar IPs / regions / patterns found? ________
+- [ ] Derived sessions/tokens revoked if needed: yes / n/a
+
+## Step 4 — Notify
+
+- [ ] Owning team notified
+- [ ] Security / compliance notified (if required by policy)
+
+## Step 5 — Cleanup (after rotation)
+
+- [ ] Scrubbed value from git history (`git filter-repo`)
+- [ ] Invalidated CI caches / mirrors
+- [ ] Did NOT paste the raw secret into this ticket
+
+## Step 6 — Prevent recurrence
+
+- [ ] Added/tightened scanner rule that missed it
+- [ ] Pre-commit + CI secret gate in place
+- [ ] Post-incident timeline written
+- [ ] Owner: ________  Due: ________

package/catalog/skills/secrets-management/references/leak-response.md

@@ -0,0 +1,47 @@
+# Leak Response — The First Hour
+
+When a secret leaks, speed beats blame. The credential is burned; your job is to make it useless before it
+is abused. Deleting the commit is **not** a fix — history persists in clones, forks, CI caches, and mirrors.
+
+## Immediate steps (in order)
+
+1. **Rotate / revoke the credential first.** Generate a replacement and invalidate the leaked value. This
+   is the only action that actually closes the hole. Everything else is cleanup.
+2. **Assess blast radius.** What could this credential do? Which environments, data, and actions? Use that
+   to set urgency and notification scope.
+3. **Check for abuse.** Pull audit logs for the credential since the likely exposure time. Look for
+   unfamiliar IPs, regions, or access patterns.
+4. **Contain.** If abuse is suspected, also revoke sessions/tokens derived from it and rotate any secrets
+   it could have unlocked (a leaked deploy key may have read other secrets).
+5. **Notify** the owning team and, if required, security/compliance — per your incident policy.
+6. **Purge history** only after rotation: scrub the value from git history (e.g. `git filter-repo`),
+   invalidate CI caches, and force-update. Treat this as hygiene, not remediation.
+7. **Post-incident:** add or tighten the scanner rule that missed it; add a pre-commit/CI gate if one was
+   absent; write up the timeline.
+
+## Redaction (prevent the next leak in logs)
+
+Most leaks after the first are in logs. Redact at the logging boundary so secrets never reach the
+aggregator:
+
+```js
+const SECRET_KEYS = /(pass(word)?|secret|token|api[-_]?key|authorization)/i;
+function redact(obj) {
+  if (typeof obj !== 'object' || obj === null) return obj;
+  const out = Array.isArray(obj) ? [] : {};
+  for (const [k, v] of Object.entries(obj)) {
+    out[k] = SECRET_KEYS.test(k) ? '[REDACTED]' : redact(v);
+  }
+  return out;
+}
+logger.info('request', redact(context)); // never log raw process.env or auth headers
+```
+
+The package scanner (`scripts/detect-hardcoded.mjs`) redacts matched values in its output for the same
+reason — never echo the secret you just found.
+
+## Don'ts
+
+- Don't quietly delete the commit and move on — the credential is still valid until rotated.
+- Don't paste the leaked value into a ticket, chat, or email to "show" the leak.
+- Don't wait for confirmation of abuse before rotating; rotation is cheap, a breach is not.

package/catalog/skills/secrets-management/references/rotation.md

@@ -0,0 +1,46 @@
+# Secret Rotation
+
+Rotation is the control that turns a leak into a non-event. A credential that is rotated regularly and can
+be rotated *fast* limits how long any exposure is useful.
+
+## Two triggers
+
+1. **Scheduled rotation** — replace credentials on a fixed cadence so none becomes ancient.
+   - Long-lived static keys: every 30–90 days.
+   - Signing keys (JWT, sessions): rotate with overlap; keep the previous key valid for verification until
+     all issued tokens expire.
+   - Prefer **short-lived dynamic credentials** so "rotation" is automatic and continuous.
+2. **Reactive rotation** — rotate **immediately** on any suspected exposure: a key in a commit, a leaked
+   log, a laptop loss, a departing employee, or a third-party breach. Do not wait to "confirm" — rotate first.
+
+## Zero-downtime overlap pattern
+
+Never rotate by deleting the old credential first — that causes an outage. Overlap instead:
+
+1. **Provision** a new credential alongside the old one (both valid).
+2. **Deploy / inject** the new value (update the secret manager; let instances pick it up).
+3. **Verify** the new credential works in production (health check, canary).
+4. **Revoke** the old credential.
+5. **Confirm** nothing broke; check error rates and audit logs for use of the revoked key.
+
+```
+old key: valid ============================x (revoked at step 4)
+new key:           valid =========================================>
+                   ^deploy   ^verify        ^safe to revoke old
+```
+
+For **signing keys**, the overlap must outlast the longest token lifetime: publish both keys (by key id),
+sign with the new one, accept either for verification, and drop the old key only after every token signed
+with it has expired.
+
+## KMS / envelope-encryption key rotation
+
+When you encrypt data yourself, rotate the **key-encryption key** (KEK) in KMS without re-encrypting every
+record: data is encrypted with per-record data keys, which are themselves encrypted by the KEK. Rotating the
+KEK re-wraps data keys lazily. Keep old KEK versions enabled for decryption until re-wrap completes.
+
+## Automate it
+
+Manual rotation is rotation that doesn't happen. Use the manager's native rotation (AWS rotation Lambdas,
+Vault leases, GCP versions) so the cadence is enforced by infrastructure, not a calendar reminder. See
+`leak-response.md` for the reactive path and `examples/rotation-runbook.md` for a fill-in checklist.

package/catalog/skills/secrets-management/references/secret-managers.md

@@ -0,0 +1,52 @@
+# Secret Managers — Env Vars vs Vault vs Cloud KMS
+
+Where the *truth* of a secret lives. Environment variables deliver secrets to a process; they do not
+securely store them. For anything past a single laptop, the source of truth belongs in a manager.
+
+## Why env vars are not a store
+
+Env vars are convenient and universal, but:
+- They are inherited by **child processes** — a shelled-out command sees every secret.
+- They appear in `/proc/<pid>/environ`, crash dumps, and many APM/observability agents.
+- They are trivially leaked by `console.log(process.env)` or an error reporter that captures context.
+- They are **static** — no rotation, no expiry, no audit trail of who read what.
+
+Use them as the *delivery* channel (the app reads `process.env.X`), but populate them from a manager.
+
+## Options compared
+
+| Manager | Model | Strengths | Costs / caveats |
+|---|---|---|---|
+| HashiCorp Vault | central server, dynamic secrets | short-lived DB/cloud creds, leasing, rich audit | run/operate a server; auth bootstrap |
+| AWS Secrets Manager / SSM | managed, IAM-scoped | native rotation Lambdas, IAM policies | AWS-only; per-secret cost |
+| GCP Secret Manager | managed, IAM-scoped | versioning, IAM, CMEK | GCP-only |
+| Azure Key Vault | managed, RBAC + keys | HSM-backed keys, certs + secrets | Azure-only |
+| Cloud KMS | key custody, not blob store | envelope encryption of your own data | you still store the ciphertext somewhere |
+
+## The bootstrap-auth problem
+
+A manager removes secrets from your repo, but the app still needs **one** credential to authenticate to the
+manager. Solve it with platform identity, not another static secret:
+- **Workload identity / IAM roles** — the cloud assigns the running instance an identity; no key to store.
+- **Vault auth methods** — Kubernetes service-account JWT, AWS IAM, or AppRole with a short-lived secret-id.
+- **OIDC federation** in CI — the pipeline exchanges a signed OIDC token for short-lived cloud creds; no
+  long-lived keys in CI settings.
+
+The goal: the only thing on disk is an *identity*, and the actual secrets are fetched at runtime over TLS.
+
+## Dynamic, short-lived credentials
+
+The biggest win of a real manager is **generated-on-demand** credentials:
+```
+# Conceptual: Vault issues a DB credential that auto-expires
+GET vault/database/creds/app-readonly
+-> { username: "v-app-ro-7f3a", password: "<generated>", lease_duration: 3600 }
+```
+The credential lives one hour, is unique to this request, and is revoked automatically. A leak is bounded
+by the lease, and every issuance is in the audit log.
+
+## Choosing
+
+- Solo / hobby: gitignored `.env` + a pre-commit scanner. A manager is overkill.
+- Team / multi-env / compliance: a managed secret manager with IAM-scoped access and rotation.
+- Encrypting your own data at rest: KMS envelope encryption (see `rotation.md` for key rotation).

package/catalog/skills/secrets-management/scripts/detect-hardcoded.mjs

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// Zero-dependency scanner: flags likely hardcoded secrets in a code string and
+// redacts the matched value so the finding can be logged safely.
+//
+// Usage:
+//   node detect-hardcoded.mjs '<code string>'        # scan a literal string
+//   echo '<code>' | node detect-hardcoded.mjs        # scan from stdin
+//   node detect-hardcoded.mjs --selftest             # built-in leaky + clean cases
+//
+// Exit codes: 0 = no secrets found (clean) ; 1 = secret(s) found OR selftest failed.
+
+// Each rule: a name and a regex with the sensitive value in capture group 1 (or 0).
+const RULES = [
+  ['AWS access key id', /\b(AKIA[0-9A-Z]{16})\b/],
+  ['Stripe secret key', /\b(sk_(?:live|test)_[A-Za-z0-9]{16,})\b/],
+  ['Google API key', /\b(AIza[0-9A-Za-z_\-]{35})\b/],
+  ['Slack token', /\b(xox[baprs]-[0-9A-Za-z-]{10,})\b/],
+  ['GitHub token', /\b(gh[pousr]_[0-9A-Za-z]{20,})\b/],
+  ['JWT', /\b(eyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,})\b/],
+  ['Private key block', /(-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----)/],
+  // Generic: an assignment to a secret-ish name with a non-trivial inline string literal.
+  ['Hardcoded password/secret assignment',
+    /\b(?:password|passwd|secret|api[_-]?key|token|access[_-]?key)\b\s*[:=]\s*["'`]([^"'`\s]{6,})["'`]/i],
+];
+
+// Mask all but a short prefix so output never echoes a real secret.
+function redactValue(v) {
+  if (v.length <= 6) return '*'.repeat(v.length);
+  return v.slice(0, 4) + '*'.repeat(Math.max(4, v.length - 4));
+}
+
+export function scan(code) {
+  const findings = [];
+  for (const [name, re] of RULES) {
+    const g = new RegExp(re.source, re.flags.includes('g') ? re.flags : re.flags + 'g');
+    let m;
+    while ((m = g.exec(code)) !== null) {
+      const value = m[1] ?? m[0];
+      findings.push({ rule: name, redacted: redactValue(value) });
+      if (m.index === g.lastIndex) g.lastIndex++; // avoid zero-width loop
+    }
+  }
+  return findings;
+}
+
+function report(label, code) {
+  const findings = scan(code);
+  if (findings.length === 0) {
+    console.log(`OK ${label}: no hardcoded secrets detected`);
+    return true;
+  }
+  console.error(`FAIL ${label}: ${findings.length} potential secret(s):`);
+  for (const f of findings) console.error(`    - ${f.rule}: ${f.redacted}`);
+  return false;
+}
+
+function selftest() {
+  // All sample values are OBVIOUSLY FAKE — fixed filler, not real credentials.
+  const leaky = [
+    "const k = 'AKIAIOSFODNN7EXAMPLE';",
+    "stripe = 'sk_test_0000000000000000FAKE';",
+    "googleKey = 'AIzaBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB';",
+    "const password = 'hunter2hunter2';",
+    "apiKey: 'tok_FAKEFAKEFAKE'",
+  ];
+  const clean = [
+    "const k = process.env.AWS_ACCESS_KEY_ID;",
+    "const password = process.env.DB_PASSWORD; // loaded from env",
+    "// example: set STRIPE_SECRET_KEY in your secret manager",
+    "const limit = 20; const name = 'orders';",
+  ];
+  let pass = true;
+  leaky.forEach((c, i) => {
+    const found = scan(c).length > 0;
+    const ok = found === true;
+    pass &&= ok;
+    console.log(`${ok ? 'OK' : 'XX'} leaky[${i}]: ${found ? 'flagged' : 'missed'} (expected flagged)`);
+  });
+  clean.forEach((c, i) => {
+    const found = scan(c).length > 0;
+    const ok = found === false;
+    pass &&= ok;
+    console.log(`${ok ? 'OK' : 'XX'} clean[${i}]: ${found ? 'flagged' : 'clean'} (expected clean)`);
+  });
+  console.log(pass ? 'selftest: PASS' : 'selftest: FAIL');
+  process.exit(pass ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) process.exit(report('input', arg) ? 0 : 1);
+else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(report('stdin', buf) ? 0 : 1));
+}

package/catalog/skills/secure-auth/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: secure-auth
+description: Implement authentication securely — authentication vs authorization, password hashing (argon2id/bcrypt), sessions vs JWT (storage, expiry, refresh, revocation), MFA, OAuth2/OIDC flows, and defenses against credential stuffing, session fixation, and CSRF. Worked examples + a runnable password-policy check.
+type: skill
+version: 2.0.0
+updated: 2026-06-29
+---
+# Secure Authentication
+
+Authentication is the front door to your system, and it is the single control attackers probe hardest.
+The goal of this skill is **not** to teach you to invent a clever scheme — it is to help you assemble
+well-understood primitives correctly, because almost every real-world breach in this area comes from a
+broken assembly of good parts, not from cracked cryptography. Heavy detail lives in `references/`;
+copy-paste material in `examples/`; a runnable policy check in `scripts/`.
+
+## Mental model
+
+Three distinct questions get muddled constantly. Keep them separate:
+
+| Question | Concern | Wrong answer looks like |
+|---|---|---|
+| Who are you? | **Authentication** (login, password, MFA) | trusting a client-supplied `user_id` |
+| What may you do? | **Authorization** (roles, ownership, scopes) | checking auth but not ownership (IDOR) |
+| How do we remember you? | **Session management** (cookies/tokens) | long-lived tokens you can't revoke |
+
+A request can be perfectly *authenticated* and still be an attack if you skip *authorization*. The most
+common API vulnerability — Broken Object Level Authorization — is exactly this: a logged-in user reads
+`/accounts/124` when they only own `124`'s neighbor. Always check ownership server-side, never trust an
+identifier the client could change.
+
+## 1. Password storage: slow hash, never plaintext
+
+The non-negotiable rule: **never store a recoverable password.** Store a one-way hash produced by a
+*deliberately slow* algorithm so that a stolen database is expensive to crack offline.
+
+```ts
+import argon2 from 'argon2';
+
+// Registration / password change — argon2id is the current default recommendation.
+const hash = await argon2.hash(password, { type: argon2.argon2id });
+// Store `hash` (it embeds the salt + cost params). NEVER store `password`.
+
+// Login — constant-time verify; argon2 reads cost params from the stored hash.
+const ok = await argon2.verify(hash, attempt);
+```
+
+Use **argon2id** (preferred) or **bcrypt** (battle-tested, fine if argon2 isn't available). Never use
+fast general-purpose hashes (`MD5`, `SHA-256`) — a GPU computes billions of those per second, so a leak
+becomes a mass account takeover within hours. Always salt (argon2/bcrypt do this for you), and validate
+the password against a policy and a breached-password list *before* hashing — run
+`scripts/check-password-policy.mjs --selftest` to see the kind of check that belongs at this boundary.
+The full parameter-tuning guidance is in [references/password-hashing.md](references/password-hashing.md).
+
+## 2. Sessions vs JWT: how you remember a logged-in user
+
+Two dominant models, with a real trade-off around **revocation**:
+
+- **Server-side sessions** — a random opaque session ID in an `HttpOnly; Secure; SameSite` cookie; state
+  lives server-side (DB/Redis). Revocation is trivial: delete the row. This is the safe default for
+  classic web apps.
+- **Stateless JWTs** — a signed token the client carries. Scales without shared session storage, but you
+  **cannot un-issue a signed token** before it expires. Mitigate with short-lived access tokens
+  (5–15 min) plus a revocable, rotating refresh token kept server-side.
+
+```http
+Set-Cookie: session=9f2c...; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=3600
+```
+
+Storage matters enormously: a token in `localStorage` is readable by any XSS payload, so prefer
+`HttpOnly` cookies (which JavaScript cannot read) over web storage for anything that authenticates a
+request. The complete comparison — expiry, refresh rotation, reuse detection, and revocation strategies —
+is in [references/sessions-vs-jwt.md](references/sessions-vs-jwt.md).
+
+## 3. MFA and step-up
+
+A password alone is a single point of failure against phishing and credential stuffing. Offer a second
+factor and require it for sensitive actions (password change, payouts):
+
+- **TOTP** (authenticator app) — good baseline, phishable but cheap.
+- **WebAuthn / passkeys** — phishing-resistant, hardware-backed; prefer where you can.
+- **SMS** — weakest (SIM-swap), use only as a fallback.
+
+Treat MFA as *step-up*: don't force it on every request, escalate it when risk rises.
+
+## 4. OAuth2 / OIDC: delegated auth done right
+
+When you offload login to a provider (Google, an identity platform), use **OAuth2 Authorization Code
+flow with PKCE** for web and mobile/SPA clients. Do not use the implicit flow (deprecated) and never the
+resource-owner password flow for third-party login. OIDC layers an identity `id_token` on top of OAuth2's
+access token. Validate the `id_token` signature, `iss`, `aud`, and `exp`, and use the `state` parameter to
+defend against CSRF on the callback. See [references/oauth2-oidc.md](references/oauth2-oidc.md) for the
+full flow diagrams and validation checklist, and `examples/auth-flow.md` for an annotated walk-through.
+
+## 5. Account recovery
+
+Recovery flows are a favorite bypass — they are authentication's back door. Make reset tokens
+**single-use, time-limited (e.g. 15–30 min), and high-entropy**, store only their hash, and invalidate
+all active sessions on a successful reset. Critically, return the **same response** whether or not the
+email exists, and keep timing uniform, so the endpoint can't be used to enumerate accounts.
+
+## Common pitfalls (failure modes)
+
+- **Fast/unsalted hashes** (`SHA-256`, `MD5`) — instantly crackable at scale after a DB leak.
+- **JWT you can't revoke** — a long-lived access token stays valid after logout/compromise; keep them short.
+- **Tokens in `localStorage`** — any XSS exfiltrates them; use `HttpOnly` cookies.
+- **Session fixation** — not rotating the session ID on login lets an attacker pre-seed a known ID; always
+  regenerate the session identifier at the moment privilege changes.
+- **Missing CSRF protection** on cookie-authenticated state-changing requests — use `SameSite` cookies
+  plus anti-CSRF tokens. See [references/auth-attacks.md](references/auth-attacks.md).
+- **Account enumeration** — different responses/timing for "wrong password" vs "no such user."
+- **No rate limiting / lockout** — credential stuffing walks straight in; throttle and add MFA.
+- **Authn without authz** — checking *who* but not *whether they own this object* (IDOR/BOLA).
+
+## When NOT to roll your own / trade-offs
+
+Prefer a vetted identity provider or library over hand-built auth whenever you can. Building it yourself
+means owning password reset, MFA enrollment, session revocation, breach monitoring, and audit trails
+*forever*. Reach for a managed IdP (OIDC provider, an auth platform) when you want SSO, social login, or
+compliance offload; the cost is vendor lock-in and per-MAU pricing. Build in-house only when you have
+hard data-residency constraints or genuinely unusual requirements — and even then, wrap proven libraries
+(argon2, a maintained OAuth2 client) rather than primitives. Stateless JWT trades easy revocation for
+horizontal scale; if you rarely need to scale auth across regions, server-side sessions are simpler and
+safer.
+
+## Files in this package
+
+- `references/password-hashing.md` — argon2id vs bcrypt, cost tuning, pepper, rehash-on-login
+- `references/sessions-vs-jwt.md` — cookies vs tokens, expiry, refresh rotation, revocation
+- `references/oauth2-oidc.md` — Authorization Code + PKCE, token validation, OIDC claims
+- `references/auth-attacks.md` — credential stuffing, session fixation, CSRF, enumeration + defenses
+- `examples/jwt-verify.ts` — dependency-light JWT verification with the right checks
+- `examples/auth-flow.md` — annotated login + refresh + OAuth2 callback walk-through
+- `scripts/check-password-policy.mjs` — runnable policy check (length, classes, breached list); `--selftest`
+
+Pairs with `owasp-top10`, `secrets-management`, `rest-api-design`, `audit-logging`, and `gdpr-compliance`.