Initial curated CertScope source from fe2bbe3ca5c98bf64be26a09c6c58ee805a7f87e

docs/ARCHITECTURE.md

@@ -0,0 +1,45 @@
+# Architecture
+
+```text
+Browser -> /api/inspect -> hostname normalization and policy
+                         -> DNS A/AAAA + mail-record collectors
+                         -> validate every resolved public address
+                         -> TLS and HTTP(S) collectors
+                              -> direct IP connection with hostname SNI/Host
+                              -> bounded, revalidated redirect hops
+                         -> normalized evidence + collector metadata
+                         -> deterministic diagnostics
+                         -> category scores + equal-weighted overall score
+                         -> dashboard, JSON and Markdown exports
+```
+
+## Boundaries
+
+All probing is server-side. The API accepts a hostname rather than an arbitrary URL. `policy.ts` normalizes lower-case DNS/IDN names and rejects URL/IP input; it validates every A/AAAA answer as public unicast before a connection. Collectors receive validated candidate addresses and connect directly to those addresses while retaining the normalized hostname for TLS SNI and the HTTP Host header.
+
+DNS runs the six required record queries under one four-second aggregate deadline. A or AAAA can be absent or fail independently; one working family is retained as partial evidence. No usable safe address is a hard resolution error. HTTP and TLS try multiple validated candidates with bounded attempts and total budgets. HTTP has a 15-second budget, TLS an eight-second budget, and DNS a four-second budget. HTTP response bodies are destroyed after headers, and TLS sockets are destroyed after each result or failure.
+
+Each redirect is parsed as a URL, restricted to HTTP(S) and default ports, normalized into a visited set, checked for loops, and re-resolved before its direct connection. Policy-rejected targets become `http.redirect_blocked` evidence without a request being made. HTTPS-to-HTTP redirects are stopped before the downgraded request and become `http.https_downgrade` evidence. Redirect depth is capped at three.
+
+Redirect `Location` values are retained in raw form only while the next target is validated; returned evidence removes URL userinfo so credentials cannot appear in reports. Certificate validity dates are checked for parseability and chronological order, and MX answer shape is checked before mail posture findings are derived.
+
+## Evidence and scoring
+
+Collectors return normalized evidence and `_meta` status (`ok`, `partial` or `failed`) with safe probe errors. Diagnostics only score observations that exist; collector incompleteness is shown separately. Category scores are clamped after their own negative findings, then the overall score is:
+
+```text
+DNS = clamp(100 + DNS finding impacts, 0, 100)
+TLS = clamp(100 + TLS finding impacts, 0, 100)
+HTTP = clamp(100 + HTTP finding impacts, 0, 100)
+overall = round((DNS + TLS + HTTP) / 3)
+```
+
+Thus an HTTP deduction is not subtracted a second time from the global score. Stable finding IDs, deterministic severity/impact ordering and evidence pointers keep reports reproducible.
+
+## Presentation and runtime
+
+`app/page.tsx` owns the landing, request state, validated active report, demo and re-inspection states. It promotes a demo/live report only after a structurally valid successful response; an error preserves the prior report and provenance. Its capability, public-boundary and demo-preview content is static product explanation or derived from the deterministic fixture; it does not imply scan history or hidden services. `app/report-view.tsx` orchestrates report-local state, contextual navigation and the accessible diagnostic drawer. `app/components/report/` contains focused actions, shared display utilities and structured DNS/TLS/HTTP evidence views; none performs probes or reimplements header policy. `app/api/health` is a side-effect-free runtime check exposing status, package version and the build revision.
+
+Header parsing produces typed control posture for HSTS, CSP, `nosniff`, Referrer-Policy and frame protection. Diagnostics and the HTTP evidence view consume that same model, so the aggregate is derived from evaluated controls rather than display text. Missing evidence from a partial collector is represented as unavailable rather than a negative observation.
+
+The production image uses Next.js standalone output. The local start helper stages generated static assets into `.next/standalone`; Docker copies those assets directly into the final non-root runtime image. `package.json` is the version source for the application and health response; deployment supplies the same release version and exact commit as image build metadata.

docs/THREAT_MODEL.md

@@ -0,0 +1,40 @@
+# Threat model
+
+## Assets
+
+CertScope protects the host running the inspector from becoming a generic network pivot while preserving enough evidence to troubleshoot public DNS/TLS/HTTP posture. It also protects report consumers from misleading scores and unescaped exported content.
+
+## Primary threats
+
+1. **SSRF into private infrastructure.** A user-controlled hostname or redirect could resolve to loopback, link-local, RFC1918, CGNAT, ULA, multicast or other non-public space.
+2. **DNS rebinding / TOCTOU.** A safe first lookup could be followed by a different answer before a socket is opened, or a redirect target could resolve privately.
+3. **Port and scheme escalation.** A redirect could attempt `file:`, credentials, protocol confusion or an arbitrary port.
+4. **Unbounded work.** Redirect loops, many addresses or stalled DNS/sockets could consume server resources or create concurrent connection pressure.
+5. **Misleading partial evidence or stale provenance.** A failed record family or hop could be mistaken for an absent control, or a failed new request could make a prior demo report appear live.
+6. **Report/content injection.** Hostnames, headers and diagnostic text could break the UI or Markdown exports if rendered without escaping.
+
+## Controls
+
+- hostname-only input validation, lower-case normalization and safe IDN-to-ASCII conversion;
+- public-unicast validation for every resolved A/AAAA answer before any candidate is attempted;
+- direct IP connection after validation, retaining the normalized hostname only for Host/SNI, so the connect path does not ask the OS to resolve the hostname again;
+- bounded multi-address fallback with a hard total deadline and recorded candidate failures;
+- re-resolution and target validation for every redirect hop;
+- HTTP(S)-only, default ports only, maximum three redirect hops, normalized visited-URL loop detection and explicit HTTPS downgrade blocking;
+- four-second DNS, eight-second TLS and 15-second HTTP aggregate budgets, plus per-operation timers and socket/response teardown;
+- explicit collector `_meta.status` and error evidence, with score deductions applied only to observed evidence;
+- client-side structural validation before a successful API payload can replace a valid report, plus retained and explicitly labelled prior evidence on request failure;
+- typed header posture shared by diagnostics and UI, including CSP first-directive-wins behavior, browser-style Referrer-Policy fallback lists and `Unavailable` rather than inferred negative controls;
+- deterministic, non-AI diagnostic rules with stable IDs and an equal-weighted category score;
+- React escaping for UI values and length-safe Markdown escaping/fenced JSON exports;
+- process-local four-slot admission and 30-per-minute fair-use limiting. Forwarded headers are ignored unless an operator explicitly trusts the reverse proxy;
+- no persistence, credential handling, arbitrary shell execution or background jobs in the MVP;
+- container non-root, read-only root filesystem, dropped capabilities, no-new-privileges and bounded temporary storage.
+
+## Residual risk and assumptions
+
+The deployment is intentionally unauthenticated and should be kept behind the intended network boundary or an operator-controlled access layer. The process-local limiter is not shared across replicas. DNS and public routing can change after an individual validated connection; CertScope makes no claim about future state. It also does not inspect response bodies or prove application-level authorization.
+
+## Out of scope
+
+CertScope does not perform port scanning, subdomain enumeration, vulnerability exploitation, authenticated crawling, private-network inspection, history persistence, monitoring daemon work or multi-host inventory.