Initial curated CertScope source from fe2bbe3ca5c98bf64be26a09c6c58ee805a7f87e

README.md

@@ -0,0 +1,99 @@
+# CertScope-Public
+
+CertScope is a compact, self-hosted domain posture inspector. Enter one public hostname and get an explainable report across DNS, TLS and HTTP(S), with deterministic findings, evidence pointers and portable exports.
+
+## The problem it solves
+
+Configuration risk is spread across DNS records, certificates and HTTP response policy. CertScope puts those signals in one small report and explains each score deduction with the observed evidence and a practical remediation.
+
+![CertScope overview](docs/assets/certscope-overview.png)
+
+## What it checks
+
+- DNS A, AAAA, MX, NS, TXT/SPF and DMARC records, including partial family/query states.
+- TLS protocol, endpoint address, certificate identity, SAN/hostname coverage, trust state, validity dates and fingerprint.
+- HTTP-to-HTTPS behavior, validated redirect chains, terminal status semantics and security headers.
+- Evidence-backed edge-case checks for malformed certificate windows, MX/SPF/DMARC posture and partial record-family failures.
+- HSTS value quality, directive-aware CSP quality, `nosniff`, browser-style Referrer-Policy fallback evaluation and clickjacking protection.
+- Stable diagnostics, evidence pointers, remediation and JSON/Markdown export.
+
+The built-in `portfolio-demo.invalid` fixture is deterministic and does not use the network, so the product can be reviewed in under 30 seconds. Before a scan, the landing explains the product boundary. After a scan, it becomes an inspection workspace: provenance, completeness, timestamp, actions and evidence are kept together without fictional dashboard features. If a re-inspection fails, the previous validated report stays visible with its original demo/live label and an explicit error banner.
+
+## Scoring
+
+Each category starts at 100 and applies only the negative impacts of findings in that category, clamped to 0–100. The overall score is the rounded equal-weighted average:
+
+```text
+overall = round((DNS + TLS + HTTP) / 3)
+```
+
+`deductions` is `100 - overall`; it is not the sum of category losses. Missing evidence caused by a partial collector is not silently converted into a finding or score penalty. The report shows completeness separately.
+
+![HTTP evidence](docs/assets/certscope-http-evidence.png)
+
+## Security boundary
+
+CertScope accepts one normalized DNS hostname, not a URL or IP literal. It resolves A and AAAA answers before connecting and rejects every non-public-unicast address, including private, loopback, link-local, multicast, CGNAT and ULA space. HTTP/TLS connect directly to a validated address while retaining the normalized hostname for Host/SNI. Every redirect is checked again, limited to three hops, restricted to HTTP(S) and default ports; blocked redirect targets and HTTPS-to-HTTP downgrades are retained as findings. DNS, TLS and HTTP have hard aggregate deadlines; candidate address attempts are bounded.
+
+The unauthenticated API has a process-local four-slot concurrency guard and a 30-request/60-second fair-use window. Forwarded client headers are only used when `CERTSCOPE_TRUST_PROXY=true`; otherwise requests share a conservative direct-client bucket. Authentication, accounts, persistence, queues, workers, AI and multi-host scanning are deliberately out of scope. See [SECURITY.md](SECURITY.md) and [the threat model](docs/THREAT_MODEL.md).
+
+## Run locally
+
+```bash
+npm ci
+npm run dev
+```
+
+Open `http://localhost:3000`, inspect a public hostname, or choose **Load demo** for the offline fixture.
+
+The release checks are:
+
+```bash
+npm ci
+npm audit --omit=dev --audit-level=high
+npm audit --audit-level=moderate
+npm run lint
+npm run typecheck
+npm test
+npm run build
+npx playwright install chromium
+npm run test:e2e
+npm run sbom
+```
+
+`npm run sbom` writes an ignored production CycloneDX file named `certscope-sbom.cdx.json`.
+
+## Docker deployment
+
+```bash
+docker compose up -d --build
+```
+
+Open `http://localhost:1251`. The image uses Next.js standalone output, a pinned Node Alpine base and a non-root runtime. Compose drops capabilities, enables no-new-privileges, uses a read-only filesystem and bounds temporary storage and resources. `/api/health` reports the application version and build revision.
+
+Compose publishes port 1251 on all host interfaces. Bind the mapping to loopback (`127.0.0.1:1251:3000`) or place the service behind an authenticated HTTPS reverse proxy before exposing it beyond a trusted network. Set `CERTSCOPE_TRUST_PROXY=true` only when trusted proxy headers cannot be supplied directly by clients.
+
+## Portfolio walkthrough
+
+1. Start on the landing to see the exact DNS, TLS and HTTP scope and public-target safeguards.
+2. Click **Load demo** to open the offline, deterministic fixture.
+3. Compare the dominant overall score with the DNS, TLS and HTTP category cards and report context.
+4. Read the completeness indicator and severity-first findings list; open a finding for remediation, then use **View evidence** to jump to its structured DNS, TLS, HTTP or Raw evidence. Close the drawer with Escape.
+5. Use the structured DNS, TLS and HTTP tabs; evidence is explicitly `Yes`, `No` or `Unavailable` when a collector is partial. Raw remains the complete normalized JSON with copy, download and line-wrap controls.
+6. Re-inspect the current host or export JSON/Markdown. On mobile, these actions live behind **Actions**.
+
+## Project shape
+
+`app/` contains the Next.js presentation, health route and inspect API. The report workspace is composed from focused report action, utility and DNS/TLS/HTTP evidence components; `lib/inspect/` contains normalization/policy, deadlines, collectors, header posture parsing, diagnostics, scoring, demo data and exports. Collectors return evidence plus `_meta` status even when a probe fails; presentation code does not perform network probes.
+
+## Demo screenshots
+
+The images above show the bundled `portfolio-demo.invalid` fixture. They do not contain production targets or confidential inspection results; the captured UI version may precede the current package version.
+
+## License
+
+No project-wide license file is included in this repository. Publishing the source does not grant an open-source license. Normal copyright restrictions and the applicable terms for individual third-party components remain in effect.
+
+## Public source distribution
+
+The private canonical repository remains the development source. Reviewed snapshots are synchronized automatically to `CertScope-Public` after changes reach its default branch. The public export contains application source, dependency locks, generic deployment examples and selected demo visuals; private Git history, infrastructure workflows and operational records are excluded. `PUBLIC_SOURCE_MANIFEST.json` identifies the exact source revision and file hashes.