anti-slop-engineering 1.3.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/.skills.json +1 -1
  2. package/README.md +33 -1
  3. package/SKILL.md +3 -1
  4. package/bin/cli.js +16 -3
  5. package/dist/bin/anti-slop-rust +0 -0
  6. package/dist/bin/toil-guard +0 -0
  7. package/install.sh +6 -1
  8. package/marketplace.json +1 -1
  9. package/package.json +2 -1
  10. package/scripts/paranoid_guard.py +201 -0
  11. package/services/anti-slop-rust/Cargo.lock +1 -1
  12. package/services/anti-slop-rust/Cargo.toml +1 -1
  13. package/services/toil-guard-go/pkg/model/types.go +1 -1
  14. package/services/toil-guard-go/pkg/server/server.go +1 -1
  15. package/skills/future-scale-gate/references/foundation-method.md +1 -1
  16. package/skills/paranoid-principal-architect/Playbook/paranoid_principal_architect_playbook.md +92 -0
  17. package/skills/paranoid-principal-architect/SKILL.md +140 -0
  18. package/skills/paranoid-principal-architect/evals/scenarios.json +112 -0
  19. package/skills/paranoid-principal-architect/examples/hardened-idempotent-service.ts +177 -0
  20. package/skills/paranoid-principal-architect/examples/paranoid-architecture-record.json +58 -0
  21. package/skills/paranoid-principal-architect/references/modern-web-platform.md +134 -0
  22. package/skills/paranoid-principal-architect/references/scale-concurrency-patterns.md +173 -0
  23. package/skills/paranoid-principal-architect/references/threat-record-contract.md +130 -0
  24. package/skills/paranoid-principal-architect/references/zero-trust-security.md +128 -0
  25. package/skills/paranoid-principal-architect/usecases/architect.md +40 -0
  26. package/skills/paranoid-principal-architect/usecases/implement.md +28 -0
  27. package/skills/paranoid-principal-architect/usecases/review.md +51 -0
@@ -0,0 +1,173 @@
1
+ # Scale & Concurrency Patterns (Day-One 10M Concurrent Users)
2
+
3
+ ## 1. Mathematical Modeling & Little's Law
4
+
5
+ Under the 10,000,000 Concurrent Users Axiom, capacity and latency cannot be left to intuition. System concurrency is governed by Little's Law:
6
+
7
+ $$L = \lambda \times W$$
8
+
9
+ Where:
10
+ - $L$ = Number of concurrent requests in-flight across the system
11
+ - $\lambda$ = Arrival rate (throughput in requests per second)
12
+ - $W$ = Average response time (latency in seconds)
13
+
14
+ ### Concrete Scale Horizon
15
+ - Assume 10,000,000 active concurrent user sessions.
16
+ - If 1% make an API request in any given second, arrival rate $\lambda = 100,000\text{ req/sec}$.
17
+ - **Scenario A (Healthy Latency):** Average latency $W = 50\text{ ms } (0.05\text{ s})$.
18
+ $$L = 100,000 \times 0.05 = 5,000\text{ concurrent in-flight requests}$$
19
+ - **Scenario B (Degraded Latency / Hot Key Lock):** A single unindexed query or row lock slips average latency to $W = 500\text{ ms } (0.5\text{ s})$.
20
+ $$L = 100,000 \times 0.5 = 50,000\text{ concurrent in-flight requests}$$
21
+ - **Result:** A 10x latency regression triggers a 10x surge in in-flight requests. Thread pools, database connection pools, file descriptors, and socket buffers saturate immediately, triggering cascading system brownout.
22
+
23
+ ---
24
+
25
+ ## 2. Hot-Key Defense & Contention Elimination
26
+
27
+ In high-concurrency systems, synchronous row updates on a single entity (e.g. `UPDATE products SET inventory = inventory - 1`, or `UPDATE metrics SET views = views + 1`) introduce devastating lock contention.
28
+
29
+ ### Strategy A: Sharded Counters
30
+ Divide a monolithic counter row into $N$ distinct shards (e.g., 16 or 64 shards):
31
+ - **Write Path:** The writer randomly selects shard index $i \in [0, N-1]$ and increments shard $i$. Contention drops by a factor of $N$.
32
+ - **Read Path:** Compute the sum across all $N$ shards using a single query:
33
+ ```sql
34
+ SELECT COALESCE(SUM(count), 0) FROM metric_shards WHERE metric_id = :id;
35
+ ```
36
+
37
+ ### Strategy B: Append-Only Event Ledgers
38
+ Never update an account balance or inventory count in place synchronously:
39
+ 1. Append an immutable transaction record into an append-only ledger (`ledger_entries`).
40
+ 2. Materialize balances periodically or asynchronously via event streaming / stream processors.
41
+ 3. For immediate balance checks, query `SELECT COALESCE(SUM(delta), 0) FROM ledger_entries WHERE account_id = :id`.
42
+
43
+ ### Strategy C: Asynchronous Batch Rollups
44
+ For high-frequency, non-transactional metrics (views, likes, heartbeats):
45
+ 1. Buffer mutations in high-throughput in-memory or Redis hyperloglogs / queues.
46
+ 2. Flush to persistent storage in micro-batches (e.g., every 500ms or 1,000 items) using bulk operations (`INSERT ... ON CONFLICT DO UPDATE`).
47
+
48
+ ---
49
+
50
+ ## 3. Keyset (Cursor) Pagination vs Offset Degradation
51
+
52
+ Offset pagination (`LIMIT 100 OFFSET 1000000`) forces the database engine to perform a full scan over 1,000,100 index entries or rows, discarding the first million. Under high concurrency, this locks buffer pools and consumes gigabytes of I/O.
53
+
54
+ ### Mandatory Cursor Keyset Invariant
55
+ Use deterministic composite cursor ordering:
56
+ ```sql
57
+ SELECT id, title, created_at
58
+ FROM articles
59
+ WHERE (created_at, id) < (:last_created_at, :last_id)
60
+ ORDER BY created_at DESC, id DESC
61
+ LIMIT 100;
62
+ ```
63
+ Required composite index:
64
+ ```sql
65
+ CREATE INDEX idx_articles_created_at_id ON articles (created_at DESC, id DESC);
66
+ ```
67
+ - Seek time remains $O(\log N)$ regardless of how deep the user paginates.
68
+ - Hard bound: Every read query must specify a maximum limit (default: 50, max: 100).
69
+
70
+ ---
71
+
72
+ ## 4. Bounded Concurrency & Pool Management
73
+
74
+ Unbounded parallel operations will rapidly exhaust Node.js/Go/Rust file descriptors, thread pools, and downstream database connections.
75
+
76
+ ### Prohibited
77
+ ```typescript
78
+ // FATAL DEFECT: If items has 10,000 elements, creates 10,000 simultaneous sockets/queries
79
+ await Promise.all(items.map(item => processItem(item)));
80
+ ```
81
+
82
+ ### Mandatory Bounded Concurrency
83
+ Use a semaphore or bounded concurrency queue (e.g. limit concurrency to 10-25 workers):
84
+ ```typescript
85
+ async function mapConcurrent<T, R>(
86
+ items: readonly T[],
87
+ limit: number,
88
+ fn: (item: T, signal: AbortSignal) => Promise<R>,
89
+ signal: AbortSignal
90
+ ): Promise<R[]> {
91
+ const results: R[] = new Array(items.length);
92
+ let nextIndex = 0;
93
+
94
+ async function worker(): Promise<void> {
95
+ while (nextIndex < items.length) {
96
+ if (signal.aborted) throw signal.reason;
97
+ const index = nextIndex++;
98
+ results[index] = await fn(items[index]!, signal);
99
+ }
100
+ }
101
+
102
+ const pool = Array.from({ length: Math.min(limit, items.length) }, () => worker());
103
+ await Promise.all(pool);
104
+ return results;
105
+ }
106
+ ```
107
+
108
+ ---
109
+
110
+ ## 5. Exponential Backoff with Full Jitter
111
+
112
+ When a downstream service degrades or drops connections, naive retries or flat sleep intervals create a **thundering herd** that ensures the downstream service can never recover.
113
+
114
+ ### The Full Jitter Algorithm
115
+ For retry attempt $i \ge 0$, calculate delay $T_i$:
116
+ $$T_{\text{temp}} = \min(T_{\max}, T_{\text{base}} \times 2^i)$$
117
+ $$T_i = \text{random}(0, T_{\text{temp}})$$
118
+
119
+ ```typescript
120
+ function calculateJitteredBackoff(
121
+ attempt: number,
122
+ baseMs = 100,
123
+ maxMs = 5000
124
+ ): number {
125
+ const expCap = Math.min(maxMs, baseMs * (2 ** attempt));
126
+ return Math.floor(Math.random() * expCap);
127
+ }
128
+ ```
129
+
130
+ ---
131
+
132
+ ## 6. Timeouts & Cancellation
133
+
134
+ Every external interaction (HTTP request, database query, cache call, inter-process call) must be bounded by a non-negotiable timeout.
135
+
136
+ ```typescript
137
+ // Modern native timeout using AbortSignal.timeout
138
+ async function safeFetch(url: string, init?: RequestInit, timeoutMs = 3000): Promise<Response> {
139
+ const timeoutSignal = AbortSignal.timeout(timeoutMs);
140
+ const combinedSignal = init?.signal
141
+ ? AbortSignal.any([init.signal, timeoutSignal])
142
+ : timeoutSignal;
143
+
144
+ return fetch(url, { ...init, signal: combinedSignal });
145
+ }
146
+ ```
147
+
148
+ ---
149
+
150
+ ## 7. Idempotency & Transaction Discipline
151
+
152
+ ### The Idempotency Key Pattern
153
+ 1. Client generates a deterministic or UUID `Idempotency-Key` header on state mutations.
154
+ 2. Server stores the request key in an atomic fast-path cache (e.g. Redis `SET key ... NX EX 86400`) with status `IN_PROGRESS`.
155
+ 3. If duplicate key arrives while `IN_PROGRESS`, return `409 Conflict` or poll/await completion.
156
+ 4. When mutation completes, update cache with the serialized response. Re-deliver cached response on subsequent retries.
157
+
158
+ ### Transaction Seam Discipline
159
+ **Never hold a database transaction open across network calls.**
160
+ ```
161
+ BAD:
162
+ BEGIN TRANSACTION
163
+ UPDATE accounts SET balance = balance - 100
164
+ await fetch("https://payment-gateway/charge") // NETWORK CALL INSIDE TRANSACTION!
165
+ UPDATE payments SET status = 'COMPLETED'
166
+ COMMIT
167
+
168
+ GOOD:
169
+ 1. Reserve funds via Optimistic Concurrency or state = 'PENDING' in short local transaction.
170
+ 2. COMMIT local transaction.
171
+ 3. Perform external HTTP call with explicit timeout and idempotency key.
172
+ 4. Update state to 'CONFIRMED' in a second short local transaction.
173
+ ```
@@ -0,0 +1,130 @@
1
+ # Paranoid Threat & Scale Record Contract
2
+
3
+ When evaluating high-concurrency systems, critical endpoints, or architectural designs, save the evaluation as a persistent JSON record (`paranoid-record.json`) to establish verifiable compliance before implementation.
4
+
5
+ ## Schema Specification (`schema_version: "1.0"`)
6
+
7
+ ```json
8
+ {
9
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
10
+ "title": "ParanoidArchitectureRecord",
11
+ "type": "object",
12
+ "required": [
13
+ "schema_version",
14
+ "goal",
15
+ "scale_profile",
16
+ "threat_pre_mortem",
17
+ "trust_boundaries",
18
+ "concurrency_controls",
19
+ "bounded_limits",
20
+ "verdict"
21
+ ],
22
+ "properties": {
23
+ "schema_version": { "type": "string", "const": "1.0" },
24
+ "goal": { "type": "string", "minLength": 10 },
25
+ "scale_profile": {
26
+ "type": "object",
27
+ "required": ["target_concurrency", "throughput_rps", "latency_budget_ms"],
28
+ "properties": {
29
+ "target_concurrency": { "type": "integer", "minimum": 10000000 },
30
+ "throughput_rps": { "type": "integer", "minimum": 1000 },
31
+ "latency_budget_ms": { "type": "integer", "maximum": 500 }
32
+ }
33
+ },
34
+ "threat_pre_mortem": {
35
+ "type": "array",
36
+ "minItems": 3,
37
+ "items": {
38
+ "type": "object",
39
+ "required": ["id", "threat_class", "description", "mitigation"],
40
+ "properties": {
41
+ "id": { "type": "string" },
42
+ "threat_class": {
43
+ "type": "string",
44
+ "enum": [
45
+ "race_condition",
46
+ "hot_key_contention",
47
+ "unbounded_concurrency",
48
+ "injection",
49
+ "timing_attack",
50
+ "edos",
51
+ "toctou",
52
+ "memory_leak",
53
+ "network_stall"
54
+ ]
55
+ },
56
+ "description": { "type": "string", "minLength": 15 },
57
+ "mitigation": { "type": "string", "minLength": 15 }
58
+ }
59
+ }
60
+ },
61
+ "trust_boundaries": {
62
+ "type": "array",
63
+ "minItems": 1,
64
+ "items": {
65
+ "type": "object",
66
+ "required": ["name", "schema_validation", "data_layer_ownership"],
67
+ "properties": {
68
+ "name": { "type": "string" },
69
+ "schema_validation": { "type": "string" },
70
+ "data_layer_ownership": { "type": "string" }
71
+ }
72
+ }
73
+ },
74
+ "concurrency_controls": {
75
+ "type": "object",
76
+ "required": ["idempotency", "locking_strategy"],
77
+ "properties": {
78
+ "idempotency": {
79
+ "type": "object",
80
+ "required": ["enabled", "key_header", "storage"],
81
+ "properties": {
82
+ "enabled": { "type": "boolean" },
83
+ "key_header": { "type": "string" },
84
+ "storage": { "type": "string" }
85
+ }
86
+ },
87
+ "locking_strategy": {
88
+ "type": "string",
89
+ "enum": ["optimistic_occ", "sharded_counters", "event_ledger", "partitioned_lock"]
90
+ }
91
+ }
92
+ },
93
+ "bounded_limits": {
94
+ "type": "object",
95
+ "required": ["max_read_limit", "max_payload_bytes", "network_timeout_ms", "backoff_algorithm"],
96
+ "properties": {
97
+ "max_read_limit": { "type": "integer", "maximum": 100 },
98
+ "max_payload_bytes": { "type": "integer", "maximum": 10485760 },
99
+ "network_timeout_ms": { "type": "integer", "maximum": 10000 },
100
+ "backoff_algorithm": { "type": "string", "const": "exponential_full_jitter" }
101
+ }
102
+ },
103
+ "verdict": {
104
+ "type": "object",
105
+ "required": ["action", "rationale", "revisit_triggers"],
106
+ "properties": {
107
+ "action": { "type": "string", "enum": ["proceed", "pause", "refuse"] },
108
+ "rationale": { "type": "string", "minLength": 20 },
109
+ "revisit_triggers": {
110
+ "type": "array",
111
+ "minItems": 1,
112
+ "items": { "type": "string" }
113
+ }
114
+ }
115
+ }
116
+ }
117
+ }
118
+ ```
119
+
120
+ ## Audit Tooling
121
+
122
+ Validate records against this contract using:
123
+ ```bash
124
+ python3 scripts/paranoid_guard.py audit <record.json> --json
125
+ ```
126
+
127
+ Exit codes:
128
+ - `0`: Structurally compliant record.
129
+ - `1`: JSON parsing or file access failure.
130
+ - `2`: Validation findings (missing threats, unbounded limits, or unmitigated risks).
@@ -0,0 +1,128 @@
1
+ # Zero-Trust Security & Threat Defense
2
+
3
+ ## 1. Zero-Trust Philosophy: The Battlefield Axiom
4
+
5
+ Every system connected to a network is under continuous hostile reconnaissance. Zero-Trust mandates that no entity—whether inside or outside the network boundary—is trusted by default:
6
+ - **Clients are Hostile:** The browser, mobile app, and API caller are completely controlled by potential adversaries. Never trust client-supplied user IDs, roles, balances, prices, or timestamps.
7
+ - **Networks are Hostile:** Packets can be intercepted, delayed, replayed, or spoofed. All transport must be encrypted (TLS 1.3), authenticated, and verified.
8
+ - **Inputs are Exploit Vectors:** Every byte received must be subjected to runtime schema validation and sanitization.
9
+
10
+ ---
11
+
12
+ ## 2. Boundary Validation: Parse, Don't Validate
13
+
14
+ Validation functions that return booleans (`isValid(input)`) leave untyped, unsanitized objects in circulation. The Paranoid Architect enforces **Parse, Don't Validate**: transform untrusted input at the perimeter into strictly typed, sanitized domain representations.
15
+
16
+ ### Zod / Valibot Schema Invariants
17
+ 1. **Strip Unknown Fields:** Reject or strip undeclared fields to defeat mass-assignment and prototype-pollution attacks:
18
+ ```typescript
19
+ import { z } from "zod";
20
+
21
+ export const CreatePaymentSchema = z.object({
22
+ idempotencyKey: z.string().uuid(),
23
+ amountInCents: z.number().int().positive().max(10_000_000), // Max $100k
24
+ currency: z.enum(["USD", "EUR", "GBP"]),
25
+ recipientId: z.string().regex(/^usr_[a-zA-Z0-9]{24}$/)
26
+ }).strict(); // Strip or reject extraneous attributes
27
+ ```
28
+ 2. **Bounds on All Strings and Arrays:** Every string must have a `.max(N)` length limit. Every array must have a `.max(N)` item count limit to prevent memory exhaustion.
29
+ 3. **Parse Early:** Execute schema parsing at the earliest entry point (e.g., HTTP handler, queue worker, WebSocket frame processor). If parsing fails, terminate immediately with a deterministic `400 Bad Request` and sanitized error structure.
30
+
31
+ ---
32
+
33
+ ## 3. Data-Layer Authorization & Tenancy Enforcement
34
+
35
+ Relying on frontend checks or top-level route middleware (`isAdmin = true`) is an invitation to Broken Object-Level Authorization (BOLA / IDOR).
36
+
37
+ ### The Invariant
38
+ Every database query, mutation, and cache lookup must scope access to the authenticated user and tenant within the SQL/ORM statement itself:
39
+
40
+ ```sql
41
+ -- CORRECT: Ownership enforced at query layer
42
+ UPDATE documents
43
+ SET content = :content, updated_at = :now
44
+ WHERE id = :document_id
45
+ AND tenant_id = :auth_tenant_id
46
+ AND owner_id = :auth_user_id;
47
+
48
+ -- FATAL DEFECT (BOLA Vulnerability):
49
+ -- Finding the document first, then checking doc.ownerId in memory
50
+ SELECT * FROM documents WHERE id = :document_id;
51
+ -- If race condition or logic flaw occurs, unauthorized write executes!
52
+ ```
53
+
54
+ ---
55
+
56
+ ## 4. Cryptographic Hygiene & Timing Defense
57
+
58
+ ### Constant-Time Equality Comparisons
59
+ Never compare passwords, API keys, HMAC signatures, or session tokens using standard equality (`===` or `==`). Standard string equality short-circuits on the first mismatched byte, leaking secret length and content through sub-microsecond timing discrepancies.
60
+
61
+ ```typescript
62
+ import { timingSafeEqual } from "node:crypto";
63
+
64
+ export function constantTimeStringCompare(a: string, b: string): boolean {
65
+ const bufA = Buffer.from(a, "utf-8");
66
+ const bufB = Buffer.from(b, "utf-8");
67
+
68
+ if (bufA.length !== bufB.length) {
69
+ // Perform dummy comparison to equalize time profile
70
+ timingSafeEqual(bufA, bufA);
71
+ return false;
72
+ }
73
+ return timingSafeEqual(bufA, bufB);
74
+ }
75
+ ```
76
+
77
+ ### Cryptographically Secure Randomness
78
+ `Math.random()` uses pseudo-random number generators (like Xoroshiro128+) that are trivially predictable given a few generated values.
79
+ - **Allowed:** `crypto.randomUUID()`, `crypto.getRandomValues(new Uint8Array(N))`.
80
+ - **Prohibited:** `Math.random()`, predictable incrementing IDs for public resources.
81
+
82
+ ### Fail-Fast Secret Hydration
83
+ All required environment variables (encryption keys, database URLs, signing secrets) must be validated on process initialization before opening network listeners:
84
+ ```typescript
85
+ const EnvSchema = z.object({
86
+ DATABASE_URL: z.string().url(),
87
+ SESSION_SECRET: z.string().min(32),
88
+ NODE_ENV: z.enum(["development", "test", "production"])
89
+ });
90
+
91
+ export const env = EnvSchema.parse(process.env);
92
+ ```
93
+
94
+ ---
95
+
96
+ ## 5. Web Security Headers & DOM Safety
97
+
98
+ ### DOM Injection Defense
99
+ Never use unsanitized HTML sinks:
100
+ - **Prohibited:** `element.innerHTML`, `element.outerHTML`, `document.write()`, `eval()`, `setTimeout(string)`, `dangerouslySetInnerHTML`.
101
+ - **Mandatory:** `element.textContent`, DOM node creation (`document.createElement()`), or sanitized output via Trusted Types.
102
+
103
+ ### Modern Security Headers
104
+ Every HTTP response serving web content must include:
105
+ ```http
106
+ Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self';
107
+ X-Content-Type-Options: nosniff
108
+ X-Frame-Options: DENY
109
+ Referrer-Policy: strict-origin-when-cross-origin
110
+ Cross-Origin-Opener-Policy: same-origin
111
+ Cross-Origin-Resource-Policy: same-origin
112
+ Permissions-Policy: camera=(), microphone=(), geolocation=()
113
+ ```
114
+
115
+ ### Cookie Hardening
116
+ Session tokens must be delivered exclusively in hardened cookies:
117
+ - `HttpOnly`: Prevents client-side script access (mitigating XSS theft).
118
+ - `Secure`: Enforces transmission exclusively over TLS.
119
+ - `SameSite=Strict` (or `Lax` for OAuth redirect targets): Mitigates Cross-Site Request Forgery (CSRF).
120
+
121
+ ---
122
+
123
+ ## 6. Economic Denial of Service (EDoS) & Resource Caps
124
+
125
+ Malicious actors or runaway bots can bankrupt infrastructure or exhaust memory by sending massive payloads or pathological requests:
126
+ 1. **Body Size Limits:** Impose strict byte limits before parsing (e.g., max 100KB for JSON, max 5MB for multi-part file uploads).
127
+ 2. **ReDoS Defense:** Never evaluate unbounded regular expressions with nested quantifiers (e.g. `/(a+)+$/`) against user input. Use Google RE2 or linear-time DFA regex engines.
128
+ 3. **Expensive Compute Gating:** Hash computations (Argon2, bcrypt), image transformations, and LLM calls must be gated behind rate limiters (e.g., sliding window token buckets) and user authorization quotas.
@@ -0,0 +1,40 @@
1
+ # Architect System: Day-One 10M Scale & Zero-Trust Design
2
+
3
+ Use this workflow when creating new services, designing distributed backends, drafting schemas, or defining critical system architecture.
4
+
5
+ ## Step-by-Step Architecture Procedure
6
+
7
+ ### 1. Freeze Scale Profile & Concurrency Model
8
+ 1. Explicitly baseline the system for **10,000,000 concurrent user sessions**.
9
+ 2. Apply Little's Law ($L = \lambda \times W$) to calculate in-flight load at 50ms versus 500ms latency.
10
+ 3. Establish hard SLA targets: P99 latency <= 100ms, zero synchronous global lock points.
11
+
12
+ ### 2. Conduct Threat & Scale Pre-Mortem
13
+ Before drawing component boundaries, identify the top 3 fatal failure modes:
14
+ - **Hot-key contention:** Which counter, row, or key will saturate under 100k writes/sec?
15
+ - **Unbounded resource exhaustion:** Where can an adversary send a 50MB payload or trigger an $O(N)$ query?
16
+ - **Race conditions & replay:** How can double-submits or out-of-order retries corrupt financial or domain state?
17
+
18
+ ### 3. Establish Zero-Trust Boundaries
19
+ 1. Declare explicit schema parsers (Zod / Valibot) at every external entrance (HTTP routes, webhooks, message queues).
20
+ 2. Enforce field stripping (`strict()` / allowlists) to prevent mass assignment.
21
+ 3. Scope all data queries to tenant and owner IDs at the query level (`WHERE tenant_id = :tenant_id AND user_id = :user_id`).
22
+
23
+ ### 4. Concurrency & State Architecture
24
+ 1. **Counters:** Eliminate single-row counters. Use 16-64 sharded counters or an append-only event ledger.
25
+ 2. **Mutations:** Enforce an `Idempotency-Key` on every mutating POST/PUT/RPC call.
26
+ 3. **Locks:** Use Optimistic Concurrency Control (OCC) with version stamps or ETags. Prohibit long-lived table locks.
27
+ 4. **Transaction Seams:** Prohibit network I/O inside database transactions. Complete DB mutations in minimal atomic transactions, commit, and execute network calls asynchronously.
28
+
29
+ ### 5. Bound All Execution
30
+ 1. **Reads:** Mandate cursor-based keyset pagination backed by composite indexes. Hard-cap reads to 100 records per page.
31
+ 2. **Workers:** Limit async concurrency via bounded worker pools or semaphores. Ban unbounded `Promise.all(items.map(...))`.
32
+ 3. **Timeouts:** Attach `AbortSignal.timeout(ms)` to every outbound HTTP call and query.
33
+ 4. **Retries:** Apply exponential backoff with full jitter to all transient error recovery paths.
34
+
35
+ ### 6. Generate Assessment Record & Audit
36
+ Save the architectural design decisions to `paranoid-record.json` and verify with:
37
+ ```bash
38
+ python3 scripts/paranoid_guard.py audit <record.json> --json
39
+ ```
40
+ Only proceed to implementation once structural verification passes with `action: "proceed"`.
@@ -0,0 +1,28 @@
1
+ # Hardened Implementation: Defensive Coding Discipline
2
+
3
+ Use this workflow when generating code, implementing endpoints, writing background workers, or refactoring critical execution paths.
4
+
5
+ ## Implementation Procedure
6
+
7
+ ### 1. Execute Threat & Scale Pre-Mortem
8
+ Before writing any implementation code, state:
9
+ 1. **Threat 1:** How concurrent callers (e.g. 10,000 requests in 10ms) could cause duplicate mutations, negative balances, or race conditions.
10
+ 2. **Threat 2:** How an adversarial payload (e.g. 50MB body, prototype pollution, script tag, or SQL fragment) could exhaust memory or compromise boundaries.
11
+ 3. **Threat 3:** How downstream service degradation (e.g. 30s latency or network partition) could lock connection pools or stall the caller.
12
+
13
+ ### 2. Implement the Hardened Code
14
+ Follow this structural order:
15
+ 1. **Perimeter Schema:** Define strict runtime schemas with `.strict()` and bounded field sizes.
16
+ 2. **Authoritative Context:** Extract caller ID and tenant ID exclusively from authenticated session state; never trust the request body.
17
+ 3. **Idempotency Gate:** Check for an `Idempotency-Key`; return cached results or acquire a deduplication lock before side effects.
18
+ 4. **Data Isolation:** Scope database queries to tenant and owner IDs directly within SQL/ORM queries.
19
+ 5. **Bounded Execution:** Limit queries with cursor-based pagination and apply `AbortSignal.timeout(ms)` to all outbound calls.
20
+ 6. **Safe Crypto:** Use `crypto.timingSafeEqual` for all secret comparisons and `crypto.randomUUID()` for nonces.
21
+ 7. **Clean Error Envelope:** Catch exceptions, log internally with trace IDs, and return sanitized error envelopes without leaking infrastructure details.
22
+
23
+ ### 3. Write Adversarial Verification Tests
24
+ Deliver tests verifying resilience under hostile conditions:
25
+ - **Concurrent Collision Test:** Fire 50 concurrent requests with the same `Idempotency-Key` or resource ID. Verify exactly one mutation succeeds while others receive idempotent replays or conflicts.
26
+ - **Oversized / Malformed Payload Test:** Send negative numbers, prototype pollution keys (`__proto__`), strings exceeding max length, and verify early 400 rejection.
27
+ - **Downstream Timeout Test:** Mock a hanging downstream service and verify `AbortSignal.timeout` aborts cleanly without leaking resources.
28
+ - **Unauthorized Tenant Traversal Test:** Attempt to access or mutate a resource belonging to another tenant/user and verify zero data leakage.
@@ -0,0 +1,51 @@
1
+ # Adversarial Review: Zero-Trust & Scale Audit
2
+
3
+ Use this workflow when auditing pull requests, reviewing existing codebases, or performing deep security and performance assessments.
4
+
5
+ ## Review Audit Checklist
6
+
7
+ ### 1. Scan for the Six Instant Rejections
8
+ 1. **Unbounded `Promise.all`:** Search for `.map(` followed by `Promise.all`. Require bounded worker pools.
9
+ 2. **Client-supplied authority:** Check if prices, timestamps, roles, or tenant IDs originate from user input. Require server-authoritative resolution.
10
+ 3. **Unprotected Polling:** Check `setInterval` for missing `document.visibilityState` pauses, error backoff, or cleanup handles.
11
+ 4. **Floating Promises:** Ensure every asynchronous call has explicit `await`, `.catch()`, or `void` with internal logging.
12
+ 5. **TOCTOU Flaws:** Check for read-then-write patterns outside atomic transactions or optimistic locking.
13
+ 6. **Sensitive Leaks:** Check if raw database entities or passwords/tokens are returned directly without an allowlisted DTO.
14
+
15
+ ### 2. Boundary Verification
16
+ - Are all route inputs parsed with strict runtime schemas (Zod/Valibot)?
17
+ - Are unknown fields stripped to prevent mass-assignment attacks?
18
+ - Are string lengths, array counts, and payload byte-sizes strictly capped?
19
+
20
+ ### 3. Concurrency & Contention Inspection
21
+ - Are database mutations idempotent via `Idempotency-Key`?
22
+ - Is there any single-row global counter that will lock under 100k writes/sec?
23
+ - Are database transactions held open across external HTTP requests? (Must reject immediately if found).
24
+
25
+ ### 4. Network & Failure Hardening
26
+ - Does every external `fetch` use `AbortSignal.timeout()`?
27
+ - Do retry mechanisms implement exponential backoff with full jitter?
28
+ - Are errors sanitized so internal infrastructure details and stack traces never reach the client?
29
+
30
+ ## Review Output Format
31
+
32
+ Provide audit findings structured as follows:
33
+
34
+ ```markdown
35
+ ### 1. Adversarial Findings
36
+ - **[CRITICAL / HIGH / MEDIUM]** <Concise title>
37
+ - **Vector:** How an attacker or 10M-user load exploits this flaw.
38
+ - **Location:** File path and line numbers.
39
+ - **Remediation:** Concrete code patch eliminating the defect.
40
+
41
+ ### 2. Invariant Compliance Matrix
42
+ | Invariant | Status | Evidence |
43
+ | --- | --- | --- |
44
+ | Zero-Trust Boundary Validation | PASS / FAIL | Zod schema parses all route params |
45
+ | Data-Layer Authorization | PASS / FAIL | WHERE user_id enforced in query |
46
+ | Bounded Limits & Pagination | PASS / FAIL | Keyset cursor pagination with LIMIT 50 |
47
+ | Network Timeouts & Cancellation | PASS / FAIL | AbortSignal.timeout(3000) applied |
48
+
49
+ ### 3. Verdict
50
+ `PROCEED`, `PAUSE`, or `REFUSE`
51
+ ```