vanara 0.1.0 → 0.2.0

package/catalog/packs/security-pack/references/choosing-the-right-tool.md

@@ -0,0 +1,37 @@
+# Choosing the right item: symptom → tool
+
+When you're mid-feature and not sure what to reach for, match the symptom to the item.
+
+| Symptom / task | Reach for | Why |
+|---|---|---|
+| "New feature touches auth, money, or PII" | `threat-modeler` + `owasp-top10` | Enumerate abuse cases before code exists |
+| "Which OWASP risk applies here?" | `owasp-top10` | The per-risk defense reference |
+| "I'm building login / sessions / MFA" | `secure-auth` | Vetted hashing, tokens, session handling |
+| "I need to reset passwords / issue tokens" | `secure-auth` | Single-use, TTL'd, constant-time compared |
+| "Where does this API key / credential go?" | `secrets-management` | Never in source; loaded from a store |
+| "Diff is ready for review" | `security-auditor` + `owasp-top10` | Security-first code review before merge |
+| "Is a dependency vulnerable?" | `vuln-scanner` | CVEs, including transitive, are invisible to review |
+| "Did a secret get committed?" | `vuln-scanner` | Scans tree *and* git history |
+| "A secret leaked — now what?" | `secrets-management` | Rotate, don't just delete |
+
+## Agent + skill pairings
+
+Each agent has a natural skill partner. Use them together:
+
+- `threat-modeler` + `owasp-top10` — enumerate threats *and* tag each with the risk category that
+  drives its defense.
+- `security-auditor` + `owasp-top10` — the auditor reviews against a concrete Top 10 checklist rather
+  than a vibe.
+- Building auth or handling secrets — apply `secure-auth` / `secrets-management` *while writing*, not
+  as an afterthought the auditor has to catch.
+
+## Escalation boundaries
+
+- Regulatory/compliance evidence (GDPR, SOC 2, audit trails) → `compliance-auditor` and the
+  privacy/audit-logging skills, not this pack.
+- Infrastructure, network, TLS, and cloud IAM hardening → DevOps/network specialists; this pack is
+  application-code security.
+- Smart-contract vulnerabilities → `smart-contract-auditor` + `smart-contract-security`; the threat
+  surface differs from web app security.
+- A CVE with no available patch → this is a risk-acceptance decision (document + mitigate), not
+  something `vuln-scanner` resolves for you.

package/catalog/packs/security-pack/references/threat-model-to-remediation.md

@@ -0,0 +1,69 @@
+# From threat model to remediation: the discipline playbook
+
+A threat model only pays off if its threats become fixes. This playbook is the connective tissue
+between `threat-modeler`'s output and a clean `security-auditor` pass — how a STRIDE finding turns
+into a mitigation, a test, and an audited change.
+
+## Step 1 — Enumerate with STRIDE (`threat-modeler`)
+
+Walk each trust boundary in the feature and ask the six STRIDE questions. For every "yes", write a
+one-line abuse case in the attacker's voice:
+
+```text
+Spoofing        → "I replay another user's session token to act as them."
+Tampering       → "I change the price field in the checkout request."
+Repudiation     → "I perform a refund and there's no log tying it to me."
+Info disclosure → "The error response tells me whether an email is registered."
+DoS             → "I hit the reset endpoint 10k times with no rate limit."
+Elevation       → "I call the admin endpoint with a normal user's token."
+```
+
+## Step 2 — Classify and prioritize (`owasp-top10`)
+
+Tag each abuse case with its OWASP category and a severity driven by *impact × likelihood*:
+
+| Abuse case | OWASP | Severity |
+|---|---|---|
+| Session token replay | A07 Auth failures | HIGH |
+| Price tampering | A04 Insecure design / A08 | CRITICAL |
+| Missing refund audit log | A09 Logging failures | MEDIUM |
+| Email enumeration | A01 Access control | MEDIUM |
+| No rate limit on reset | A04 / A07 | HIGH |
+| Privilege escalation | A01 Broken access control | CRITICAL |
+
+Fix CRITICAL/HIGH before shipping; schedule MEDIUM/LOW with an owner.
+
+## Step 3 — Design the mitigation (skills)
+
+Each category has a known defense — reach for the skill, don't improvise:
+
+- Access control (A01) → deny by default; authorize every request server-side against the *resource
+  owner*, not just "is logged in".
+- Auth failures (A07) → `secure-auth`: strong hashing, single-use tokens, constant-time compare,
+  rotate on privilege change.
+- Insecure design (A04) → re-derive trusted values (price, role) server-side; never trust the client.
+- Sensitive data (A02) → `secrets-management` for keys; encrypt at rest; identical responses to
+  prevent enumeration.
+
+## Step 4 — Test the abuse case, then implement
+
+Turn each abuse case into a failing test *first*, so the fix has a target and a regression guard:
+
+```text
+✗ a request with user B's token cannot mutate user A's resource   (A01)
+✗ POST /checkout ignores a client-supplied price field            (A04)
+✗ /password-reset returns 429 after N attempts per window         (A07)
+```
+
+Implement until green. The test now permanently encodes the threat.
+
+## Step 5 — Audit and scan (`security-auditor` + `vuln-scanner`)
+
+Hand the diff to `security-auditor` with the stage-2 severity table as the agenda — it verifies each
+mitigation is present and correct, citing `file:line`. Then `vuln-scanner` sweeps dependencies and
+history. Ship only when the CRITICAL/HIGH rows are all closed and the scan is clean.
+
+## The through-line
+
+Threat → OWASP class → mitigation skill → failing abuse-case test → audited fix. When a finding
+skips a step — a threat with no test, or a fix with no audit — that's where regressions re-enter.

package/catalog/packs/security-pack/references/workflow.md

@@ -0,0 +1,56 @@
+# The five-stage security workflow
+
+Each stage has an owner (the primary item), the skills it applies, and an explicit **exit criterion**
+— you don't advance until the criterion is met. This is what keeps security from collapsing into a
+single rushed review at the end.
+
+## Stage 1 — Model
+
+- **Owner:** `threat-modeler` · **Applies:** `owasp-top10`
+- Draw the trust boundaries (client, server, third parties, data store). For each boundary, walk
+  STRIDE — Spoofing, Tampering, Repudiation, Information disclosure, Denial of service, Elevation of
+  privilege — and write down the concrete abuse cases for *this* feature.
+- Map each threat to its OWASP Top 10 category so the audit later has a checklist.
+- **Exit criterion:** a written list of threats, each tagged with an OWASP category and a planned
+  mitigation, that the build and audit stages can reference.
+
+## Stage 2 — Build
+
+- **Owners:** `secure-auth`, `secrets-management` (as the feature demands)
+- Implement the risk-bearing parts against a vetted construction, not from memory. Auth: correct
+  hashing, single-use tokens, constant-time comparison, no user enumeration. Secrets: loaded from a
+  store or environment, never committed, never shipped to the client.
+- Write the abuse-case tests from stage 1 alongside the implementation.
+- **Exit criterion:** the risky paths are implemented per the skills' guidance and the abuse-case
+  tests pass.
+
+## Stage 3 — Audit
+
+- **Owner:** `security-auditor` · **Applies:** `owasp-top10`
+- Review the diff security-first, using the stage-1 threat list as the agenda: broken access control
+  (IDOR/authorization), injection, auth failures, unsafe crypto, sensitive-data exposure. Every
+  finding cites `file:line`, a severity, and a concrete fix.
+- **Exit criterion:** no CRITICAL or HIGH finding remains open.
+
+## Stage 4 — Scan
+
+- **Owner:** `vuln-scanner`
+- Scan dependencies (including transitive) for known CVEs, and scan the working tree **and git
+  history** for secrets. A secret found in history is treated as exposed even if HEAD is clean.
+- **Exit criterion:** no unaddressed CVE at High/Critical severity; no secret in tree or history
+  (removal alone is insufficient for a real leak — see below).
+
+## Stage 5 — Ship
+
+- **Gate:** no open CRITICAL/HIGH audit finding, clean dependency scan, no committed secret.
+- If a secret was ever exposed, it is **rotated**, not merely deleted. If a CVE has no patch,
+  document the risk acceptance or apply a mitigating control before shipping.
+- **Exit criterion:** all gates green; any accepted risk is written down with an owner.
+
+## Why order matters
+
+The threat model is the shared dependency of every later stage — it sets what to build carefully in
+stage 2 and what to look for in stage 3. Building before modeling means you protect the wrong things.
+Auditing before scanning means you can pass human review while a vulnerable dependency or a leaked key
+sits in the tree. Skipping or reordering stages is the single biggest source of shipped
+vulnerabilities.

package/catalog/skills/api-pagination/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: api-pagination
+description: Implement correct, fast API pagination — cursor vs offset trade-offs, opaque cursor encoding, stable sort keys, page-size limits, total-count costs, and consumer-side iteration that survives inserts, deletes, and retries. With runnable cursor checks.
+type: skill
+version: 1.0.0
+updated: 2026-07-10
+---
+# API Pagination
+
+Pagination looks trivial until data changes underneath the reader. Offset pagination silently
+**skips or duplicates rows** when inserts land mid-iteration; cursor pagination survives churn but
+demands a stable sort key and an opaque token contract. This skill covers both sides: designing the
+API and consuming one correctly. Deep detail lives in `references/`; copy-paste material in
+`examples/`; a runnable cursor round-trip check in `scripts/`.
+
+## Decision: offset vs cursor
+
+| Situation | Use |
+|---|---|
+| Admin tables, small datasets, "jump to page 7" required | Offset (`LIMIT/OFFSET`) |
+| Feeds, sync endpoints, anything users scroll | Cursor (keyset) |
+| Data changes while clients iterate | Cursor — offset will skip/duplicate |
+| Deep pages (offset > ~10k rows) | Cursor — `OFFSET n` scans and discards n rows |
+
+Offset's failure mode is correctness, not just speed: a row inserted before your current position
+shifts everything, so page 3 re-shows an item from page 2 (duplicate) or swallows one (skip).
+
+## Keyset mechanics (the part people get wrong)
+
+The sort key must be **unique and immutable**. `created_at` alone is not unique — two rows with the
+same timestamp make the cursor ambiguous and rows vanish. Always add a tiebreaker:
+
+```sql
+-- WHERE clause for "next page after (2026-07-01T12:00:00Z, id 4711)" descending
+SELECT * FROM items
+WHERE (created_at, id) < ('2026-07-01T12:00:00Z', 4711)
+ORDER BY created_at DESC, id DESC
+LIMIT 51;  -- page_size + 1 to detect has_more without COUNT(*)
+```
+
+Fetch `page_size + 1` rows: if you get 51, there is a next page and the 51st row's key becomes the
+next cursor. This avoids `COUNT(*)`, which on large tables costs more than the page itself
+(see `references/counting-and-totals.md`).
+
+## Cursor token contract
+
+Cursors are **opaque to clients** — never let them parse or build one. Encode the keyset values plus
+the sort direction, base64url it, and (for public APIs) HMAC it so tampering is detectable. Include a
+version byte so you can change the encoding later. Full recipe: `references/cursor-encoding.md`;
+runnable round-trip: `scripts/check-cursor.mjs`.
+
+## Response envelope
+
+```json
+{
+  "data": [ ... ],
+  "page_info": { "has_more": true, "next_cursor": "djEuMj..." }
+}
+```
+
+Rules: `next_cursor` is absent (not empty-string) on the last page; page size is capped server-side
+(a `limit=10000` request gets the cap, documented, not an error); the default page size appears in
+the docs and never changes silently. Consumer-side iteration rules — retries, cursor expiry,
+resumption — live in `references/consuming-pages.md`.
+
+## Pitfalls
+
+- **Mutable sort keys** (`updated_at`) — rows teleport across pages as they update. Sort on immutable
+  columns or accept re-delivery and dedupe client-side.
+- **Cursor built from row position** instead of row values — it is offset with extra steps and
+  inherits every offset bug.
+- **`COUNT(*)` on every page** — the count is stale by the time the client renders it; provide totals
+  on a separate, cacheable endpoint if the product truly needs them.
+- **Breaking cursor encoding on deploy** — clients hold cursors across releases; version the token.
+- **Missing composite index** — keyset needs an index on exactly `(created_at, id)` in sort order, or
+  every page is a scan.
+
+## Verification
+
+Run `node scripts/check-cursor.mjs` — encodes, decodes, tampers, and versions a cursor and asserts
+every property above. For the SQL side, `examples/keyset-queries.sql` includes an `EXPLAIN` you can
+run to confirm the index is used. Pairs with `rest-api-design` (envelopes, limits) and
+`sql-index-tuning` (composite indexes).

package/catalog/skills/api-pagination/examples/keyset-queries.sql

@@ -0,0 +1,38 @@
+-- Keyset pagination: canonical queries (Postgres syntax).
+
+-- The supporting index. Column order and direction must match the ORDER BY exactly.
+CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_items_created_id
+  ON items (created_at DESC, id DESC);
+
+-- Page 1 (no cursor): newest first, page_size 50, +1 row to detect has_more.
+SELECT id, created_at, title
+FROM items
+WHERE tenant_id = $1
+ORDER BY created_at DESC, id DESC
+LIMIT 51;
+
+-- Page N (cursor decoded to ($2 = created_at, $3 = id) of the last row seen).
+-- Row-value comparison keeps the composite ordering correct in one clause.
+SELECT id, created_at, title
+FROM items
+WHERE tenant_id = $1
+  AND (created_at, id) < ($2, $3)
+ORDER BY created_at DESC, id DESC
+LIMIT 51;
+
+-- Verify the index is used (look for "Index Scan ... idx_items_created_id",
+-- no Sort node, and rows examined ≈ LIMIT):
+EXPLAIN (ANALYZE, BUFFERS)
+SELECT id, created_at, title
+FROM items
+WHERE tenant_id = $1 AND (created_at, id) < (now(), 2147483647)
+ORDER BY created_at DESC, id DESC
+LIMIT 51;
+
+-- Ascending variant (jump-to-oldest without deep offsets): flip both the
+-- comparison and the sort, same index scanned backwards.
+SELECT id, created_at, title
+FROM items
+WHERE tenant_id = $1 AND (created_at, id) > ($2, $3)
+ORDER BY created_at ASC, id ASC
+LIMIT 51;

package/catalog/skills/api-pagination/examples/response-shapes.md

@@ -0,0 +1,51 @@
+# Response Shapes
+
+## Cursor-paginated list (recommended default)
+
+```json
+{
+  "data": [
+    { "id": "itm_9x2", "created_at": "2026-07-01T12:00:00.412Z", "title": "..." }
+  ],
+  "page_info": {
+    "has_more": true,
+    "next_cursor": "v1.eyJrIjpbIjIwMjYt...IsNDcxMV0sImQiOiJkZXNjIn0.3f9a1c22b0"
+  }
+}
+```
+
+Last page: `has_more: false` and **no** `next_cursor` key. Clients must treat absence — not
+empty string, not null — as the terminal signal (document exactly one convention and test it).
+
+## Offset-paginated list (admin/small data only)
+
+```json
+{
+  "data": [ ... ],
+  "page_info": { "page": 3, "per_page": 50, "total": 1204, "total_pages": 25 }
+}
+```
+
+Only ship `total`/`total_pages` when the dataset is small enough that COUNT is cheap and the
+product genuinely offers page jumping.
+
+## Request parameters
+
+```
+GET /v1/items?limit=50&cursor=v1.eyJr...          # cursor flow
+GET /v1/admin/items?page=3&per_page=50            # offset flow
+```
+
+- `limit` capped server-side (e.g., max 200); over-cap requests get the cap, not an error.
+- Filters/sort are request parameters, never encoded inside the cursor — but changing them
+  mid-iteration invalidates the cursor (return `CURSOR_INVALID`, client restarts).
+
+## Error shapes
+
+```json
+{ "error": { "code": "CURSOR_EXPIRED", "message": "Restart iteration from the beginning." } }
+{ "error": { "code": "CURSOR_INVALID", "message": "Cursor is malformed or filters changed." } }
+```
+
+Both are 400s. Clients restart from their last durable checkpoint; idempotent processing absorbs
+the overlap.

package/catalog/skills/api-pagination/references/consuming-pages.md

@@ -0,0 +1,39 @@
+# Consuming Paginated APIs Correctly
+
+The consumer side has its own failure modes: partial iteration on crash, duplicate processing on
+retry, and silent stalls when a provider changes page semantics.
+
+## The iteration loop
+
+```js
+let cursor = savedCheckpoint ?? null;
+do {
+  const page = await get('/items', { cursor, limit: 100 });
+  for (const item of page.data) await processIdempotently(item);
+  cursor = page.page_info.next_cursor ?? null;
+  await saveCheckpoint(cursor);          // AFTER processing the page
+} while (cursor);
+```
+
+Rules encoded above:
+
+- **Checkpoint the cursor, not the item index.** Persist `next_cursor` after each fully processed
+  page; on restart, resume from the checkpoint instead of page one.
+- **Process idempotently.** At-least-once is the reality: a crash between processing and
+  checkpointing replays the page. Dedupe on item ID exactly like a webhook consumer.
+- **Loop on `next_cursor` presence, not on `data.length > 0`.** Some providers return short or
+  empty pages mid-stream (filtered rows); an empty page with a cursor is NOT the end.
+- **Bound the loop.** A provider bug that returns the same cursor forever becomes your infinite
+  loop; track `pages_fetched` against a sane ceiling and alert past it.
+
+## Retry semantics
+
+Page fetches are GETs — safe to retry with backoff. But a `CURSOR_EXPIRED` or `CURSOR_INVALID`
+response is not retryable: restart the iteration from your last durable checkpoint (or from
+scratch) and rely on idempotent processing to absorb the overlap.
+
+## Rate limits and burst shape
+
+Full-table syncs hammer providers. Respect `Retry-After` on 429s, spread scheduled syncs with
+jitter, and prefer provider-side incremental endpoints (`updated_since=`) over re-walking
+everything — pagination is for the backfill, deltas are for steady state.

package/catalog/skills/api-pagination/references/counting-and-totals.md

@@ -0,0 +1,41 @@
+# Counting and Totals
+
+`COUNT(*)` is the hidden cost center of pagination. On a large Postgres table it is a full index
+or heap scan — routinely slower than fetching the page itself — and the number is stale the moment
+it is computed.
+
+## Decision table
+
+| Product need | Implementation |
+|---|---|
+| "Load more" / infinite scroll | No count at all — `has_more` from the +1-row trick |
+| "~12,300 results" | Estimated count (below), clearly rounded in the UI |
+| Exact count on small filtered sets (<10k rows) | Real `COUNT(*)`, acceptable |
+| Exact count on big tables, hard requirement | Maintained counter (trigger or async rollup) |
+
+## Estimated counts (Postgres)
+
+```sql
+-- Table-wide estimate: instant, from the planner's statistics
+SELECT reltuples::bigint FROM pg_class WHERE relname = 'items';
+
+-- Filtered estimate: run the query through EXPLAIN and parse rows=
+EXPLAIN (FORMAT JSON) SELECT 1 FROM items WHERE status = 'active';
+-- -> Plan.["Plan Rows"]
+```
+
+Estimates drift after bulk writes until autovacuum/analyze runs — fine for "~N results", wrong for
+billing or quotas.
+
+## Maintained counters
+
+A trigger-updated counter table gives exact totals at O(1) read cost, but serializes writes on hot
+rows (every insert contends on the same counter row). For high write rates, shard the counter
+(N rows, sum on read) or roll up asynchronously and accept seconds of lag. Never compute quotas
+or invoices from pagination counts — those need their own transactional bookkeeping.
+
+## The `total_pages` trap
+
+Exposing `total_pages` invites clients to build page links (`?page=812`), which drags you back to
+deep offsets. If the UI needs a jump-to-end affordance, offer a reversed sort (`?order=asc`)
+instead — last page becomes first page, at first-page cost.

package/catalog/skills/api-pagination/references/cursor-encoding.md

@@ -0,0 +1,34 @@
+# Cursor Encoding
+
+A cursor must carry enough to rebuild the keyset `WHERE` clause and nothing more: the sort-key
+values, the direction, and a version byte. It must be opaque, tamper-evident (public APIs), and
+survive encoding changes across deploys.
+
+## Layout
+
+```
+v1 . base64url( json({ k: ["2026-07-01T12:00:00.000Z", 4711], d: "desc" }) ) . hmac10
+```
+
+- **`v1` prefix** — bump when the payload shape changes; reject unknown versions with 400
+  `CURSOR_INVALID`, which clients treat as "restart iteration".
+- **base64url**, not base64 — cursors travel in query strings; `+/=` break naive clients.
+- **HMAC (first 10 bytes, hex)** over `version + payload` with a server-side key. Not secrecy —
+  integrity. Without it, clients will reverse-engineer the payload and build their own cursors,
+  and your encoding becomes an accidental public API you can never change.
+
+## Rules
+
+- Timestamps in the payload must be **full precision** (milliseconds or better). Truncated seconds
+  re-introduce the duplicate-key ambiguity the tiebreaker was meant to solve.
+- Never embed user IDs, filters, or auth state in the cursor — re-derive those from the request.
+  A cursor pasted into another user's session must not leak or authorize anything.
+- Cursors may expire (e.g., if the underlying snapshot is gone). Expired cursor → 400 with a
+  distinct `CURSOR_EXPIRED` code so clients restart rather than retry.
+- Treat decode failures as client errors (400), never 500 — fuzzers will send garbage.
+
+## Anti-pattern: the "readable" cursor
+
+`?after_id=4711&after_ts=...` looks friendlier but freezes your sort semantics forever: adding a
+tiebreaker, changing direction defaults, or switching the sort column becomes a breaking change.
+Opaque tokens keep the contract at "pass back what we gave you".

package/catalog/skills/api-pagination/scripts/check-cursor.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// Runnable check for the opaque-cursor contract (encode -> decode -> tamper -> version).
+// Usage: node scripts/check-cursor.mjs   (exits 0 on pass, 1 on first failure)
+import { createHmac } from 'node:crypto';
+
+const KEY = 'demo-key-rotate-me';
+const VERSION = 'v1';
+
+const b64u = (buf) => Buffer.from(buf).toString('base64url');
+const sign = (s) => createHmac('sha256', KEY).update(s).digest('hex').slice(0, 20);
+
+export function encodeCursor(keyValues, direction = 'desc') {
+  const payload = b64u(JSON.stringify({ k: keyValues, d: direction }));
+  return `${VERSION}.${payload}.${sign(VERSION + payload)}`;
+}
+
+export function decodeCursor(token) {
+  const [version, payload, mac] = String(token).split('.');
+  if (version !== VERSION) return { error: 'CURSOR_INVALID' }; // unknown version
+  if (!payload || sign(version + payload) !== mac) return { error: 'CURSOR_INVALID' };
+  try {
+    const { k, d } = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+    if (!Array.isArray(k) || !['asc', 'desc'].includes(d)) return { error: 'CURSOR_INVALID' };
+    return { keyValues: k, direction: d };
+  } catch {
+    return { error: 'CURSOR_INVALID' };
+  }
+}
+
+let failed = 0;
+const check = (name, ok) => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}`);
+  if (!ok) failed = 1;
+};
+
+// Round trip preserves full timestamp precision and the tiebreaker.
+const token = encodeCursor(['2026-07-01T12:00:00.412Z', 4711]);
+const out = decodeCursor(token);
+check('round-trip', out.keyValues?.[1] === 4711 && out.keyValues?.[0].endsWith('.412Z'));
+check('url-safe (no + / =)', !/[+/=]/.test(token));
+
+// Tampered payload must be rejected, not half-parsed.
+const [v, p, m] = token.split('.');
+check('tamper detected', decodeCursor(`${v}.${p.slice(0, -2)}xx.${m}`).error === 'CURSOR_INVALID');
+
+// Unknown version and garbage are client errors, never crashes.
+check('unknown version rejected', decodeCursor(`v9.${p}.${m}`).error === 'CURSOR_INVALID');
+check('garbage rejected', decodeCursor('not-a-cursor').error === 'CURSOR_INVALID');
+check('empty rejected', decodeCursor('').error === 'CURSOR_INVALID');
+
+process.exit(failed);