Use vertical, acyclic flows with shorter labels and split notification pairing from delivery so diagrams render with larger text.
- commit
- 12e659b8eabbd9eac87afaf397636b0f223668f7
- parent
- 8dfdb697e7f8eb3afbcef44b415602547e52d0f3
- author
- Dami <dami.etoile@gmail.com>
| M | ARCHITECTURE.md | 75 | +++++++++++++++--------------- |
| M | SECURITY.md | 20 | ++++---- |
@@ -7,14 +7,14 @@ identically.
77 ## Components88 99 ```mermaid10-flowchart LR11- CLI["nzip Deno CLI"] -- "bearer-authenticated API" --> W["nzip Worker"]10+flowchart TB11+ CLI["Deno CLI"] -- "bearer API" --> W["Worker"]1212 V(["visitor"]) -- "GET /2a3f" --> C{"Workers Cache"}13- C -- "hit" --> V14- C -- "miss or bypass" --> W15- W -- "tagged public response" --> C16- W --> R2[("R2 blobs and manifests")]17- W --> D1[("D1 state and history")]13+ C -- "hit" --> RESP["public response"]14+ C -- "miss" --> W15+ W -- "tagged response" --> RESP16+ W --> R2[("R2 blobs")]17+ W --> D1[("D1 state")]1818 ```1919 2020 - `shared/` defines manifests, hashing, target parsing, limits, media types, and API contracts.@@ -80,29 +80,28 @@ also asynchronous: the owner request persists an event and per-device attempts b
8080 work contacts a Web Push provider.8181 8282 ```mermaid83-flowchart LR84- subgraph Pairing85- OWNER["owner CLI"] -- "notify pair" --> WINDOW[("10-minute pairing window")]86- PHONE["phone browser"] -- "begin enrollment" --> PENDING[("pending device and code hash")]87- WINDOW --> PENDING88- PENDING -- "display code" --> PHONE89- OWNER -- "approve code" --> APPROVED[("approved device claim")]90- PENDING --> APPROVED91- APPROVED -- "activate claim" --> PWA["installed PWA"]92- PWA -- "attach PushSubscription" --> ACTIVE[("active device")]93- end94-95- subgraph Delivery96- OWNER -- "notify send" --> API["owner notification API"]97- API --> EVENT[("event and per-device deliveries")]98- EVENT --> DRAIN["scheduled delivery drain"]99- ACTIVE --> DRAIN100- DRAIN --> PUSH["allowed Web Push provider"]101- PUSH --> SW["service worker"]102- SW --> NOTICE["system notification"]103- NOTICE -- "tap" --> TARGET["claim-authenticated click target"]104- TARGET --> SITE["root or manifest-pinned site"]105- end83+flowchart TB84+ OWNER["owner: notify pair"] --> WINDOW[("10-minute window")]85+ PHONE["phone browser"] -- "enroll" --> PENDING[("pending device")]86+ WINDOW --> PENDING87+ PENDING --> CODE["display pairing code"]88+ CODE --> APPROVE["owner approves code"]89+ APPROVE --> APPROVED[("approved claim")]90+ APPROVED -- "activate" --> PWA["installed PWA"]91+ PWA -- "attach subscription" --> ACTIVE[("active device")]92+```93+94+```mermaid95+flowchart TB96+ OWNER["owner CLI"] -- "notify send" --> API["notification API"]97+ API --> EVENT[("event + deliveries")]98+ ACTIVE[("active devices")] --> DRAIN["scheduled drain"]99+ EVENT --> DRAIN100+ DRAIN --> PUSH["Web Push provider"]101+ PUSH --> SW["service worker"]102+ SW --> NOTICE["system notification"]103+ NOTICE -- "tap" --> TARGET["validated click target"]104+ TARGET --> SITE["root or pinned site"]106105 ```107106 108107 Pairing codes cannot approve themselves; the approval path always requires the owner bearer token.@@ -122,15 +121,15 @@ leases, bounded retry schedules, and terminal outcomes so overlapping cron execu
122121 ## Observability123122 124123 ```mermaid125-flowchart LR126- RESP["Worker response"] --> CLASSIFY["classify security-relevant request"]127- CLASSIFY --> SAMPLE{"deterministic scanner sample"}124+flowchart TB125+ RESP["Worker response"] --> CLASSIFY["classify request"]126+ CLASSIFY --> SAMPLE{"scanner sample"}128127 SAMPLE -- "selected" --> LOGS["Workers Logs"]129- SAMPLE -- "not selected" --> DROP["no log event"]130- PROBES[("bounded D1 probe windows")] --> CRON["five-minute evaluator"]131- CRON --> WINDOW["security.enumeration_window"]132- CRON --> OUTBOX[("durable alert outbox")]133- LOGS --> DASH["Cloudflare Observability"]128+ SAMPLE -- "not selected" --> DROP["no event"]129+ PROBES[("D1 probe windows")] --> CRON["5-minute evaluator"]130+ CRON --> WINDOW["incident event"]131+ CRON --> OUTBOX[("alert outbox")]132+ LOGS --> DASH["Observability"]134133 WINDOW --> DASH135134 PROBES --> METRICS["D1 row metrics"]136135 ```@@ -43,21 +43,21 @@ The address space is intentionally small, so nzip observes and limits enumeratio
4343 claiming addresses are unguessable.4444 4545 ```mermaid46-flowchart LR46+flowchart TB4747 REQ(["request"]) --> SURFACE{"request surface"}48- SURFACE -- "/api/*" --> TOKEN["bearer-token check"]49- SURFACE -- "GET /xxxx" --> ENUM["enumeration limiter"]50- SURFACE -- "POST /xxxx/__unlock" --> UNLOCK["password limiter"]48+ SURFACE -- "/api/*" --> TOKEN["bearer check"]49+ SURFACE -- "GET /xxxx" --> ENUM["enum limiter"]50+ SURFACE -- "POST unlock" --> UNLOCK["password limiter"]5151 TOKEN --> API["owner API"]52- ENUM --> SERVE["site lookup and serve"]52+ ENUM --> SERVE["site lookup"]5353 UNLOCK --> SERVE5454 SERVE --> GATE{"password protected?"}55- GATE -- "yes" --> COOKIE["PBKDF2 and signed cookie"]55+ GATE -- "yes" --> COOKIE["PBKDF2 + cookie"]5656 GATE -- "no" --> PUBLIC["public response"]57- ENUM -. "HMAC scanner identity" .-> PROBES[("bounded D1 probe windows")]58- PROBES --> EVAL["five-minute incident evaluator"]59- EVAL --> OUTBOX[("durable email outbox")]60- OUTBOX --> EMAIL["verified-destination email"]57+ ENUM -. "HMAC identity" .-> PROBES[("D1 probe windows")]58+ PROBES --> EVAL["incident evaluator"]59+ EVAL --> OUTBOX[("email outbox")]60+ OUTBOX --> EMAIL["verified email"]6161 EMAIL --> INBOX(["operator inbox"])6262 ```6363