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.
- package/.skills.json +1 -1
- package/README.md +33 -1
- package/SKILL.md +3 -1
- package/bin/cli.js +16 -3
- package/dist/bin/anti-slop-rust +0 -0
- package/dist/bin/toil-guard +0 -0
- package/install.sh +6 -1
- package/marketplace.json +1 -1
- package/package.json +2 -1
- package/scripts/paranoid_guard.py +201 -0
- package/services/anti-slop-rust/Cargo.lock +1 -1
- package/services/anti-slop-rust/Cargo.toml +1 -1
- package/services/toil-guard-go/pkg/model/types.go +1 -1
- package/services/toil-guard-go/pkg/server/server.go +1 -1
- package/skills/future-scale-gate/references/foundation-method.md +1 -1
- package/skills/paranoid-principal-architect/Playbook/paranoid_principal_architect_playbook.md +92 -0
- package/skills/paranoid-principal-architect/SKILL.md +140 -0
- package/skills/paranoid-principal-architect/evals/scenarios.json +112 -0
- package/skills/paranoid-principal-architect/examples/hardened-idempotent-service.ts +177 -0
- package/skills/paranoid-principal-architect/examples/paranoid-architecture-record.json +58 -0
- package/skills/paranoid-principal-architect/references/modern-web-platform.md +134 -0
- package/skills/paranoid-principal-architect/references/scale-concurrency-patterns.md +173 -0
- package/skills/paranoid-principal-architect/references/threat-record-contract.md +130 -0
- package/skills/paranoid-principal-architect/references/zero-trust-security.md +128 -0
- package/skills/paranoid-principal-architect/usecases/architect.md +40 -0
- package/skills/paranoid-principal-architect/usecases/implement.md +28 -0
- 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
|
+
```
|