# Conduit

**Real SEC filings as first-class agent tools. One URL, zero install.**

Conduit is a free, open-source, remote (streamable-HTTP) [MCP](https://modelcontextprotocol.io) server over [SEC EDGAR](https://www.sec.gov/search-filings/edgar-application-programming-interfaces), built to run entirely on Cloudflare's free tier. It absorbs EDGAR's sharp edges once — CIK zero-padding, accession formats, XBRL taxonomy tags, and the strict fair-access policy — so every agent client gets clean, cited, token-lean filing data without installing anything.

> Not affiliated with, endorsed by, or sponsored by the SEC. Provides public EDGAR data; not investment advice.

## Status — scaffold only (2026-07-08)

This repository is at **Phase 0 scaffold**. What exists today:

- Worker skeleton (Hono) exposing only `/healthz`.
- TypeScript (strict), ESLint, Vitest on `@cloudflare/vitest-pool-workers` (real workerd) with a passing smoke test.
- D1 migration pipeline (drizzle-kit → `wrangler d1 migrations apply`) with a bootstrap migration.
- Typed analytics tracking plan (`analytics/events.ts`) with the activation event `edgar_first_tool_success` as instrument zero.
- The single EDGAR config module (`src/edgar/config.ts`) holding the declared User-Agent.
- CI on push/PR: typecheck, lint, migration check, unit tests, gitleaks. **No deploy job.**

- The single EDGAR client choke point (`src/edgar/`) + the first tool (`get_filing_section`) behind a dev-only, flag-gated route.
- **The [SECURITY/Opus] v0.5 security posture** (see `docs/security-posture.md`): global ≤10 req/s SEC fair-access budget (coordinator Durable Object), per-IP inbound abuse control (429 + `Retry-After` + `RateLimit-*`), body-size cap, site-wide security headers, CORS baseline, keyed-HMAC client identification (zero PII), outbound host allow-list + charset gates, and RFC 9457 problem+json errors.

**What does NOT exist yet:** the `/mcp` surface, the playground, and the Phase 2 controls (playground denial-of-wallet, prompt-injection posture, full CORS/hygiene sweep, keyed tiers). The charter (`PRD.md`, `ARCHITECTURE.md`, `DESIGN-BRIEF.md`, `BUILD-PLAN.md`, `docs/`) is the contract.

**Phase 0 is NOT signed off.** The stateless-connector spike (a real claude.ai connector against a public URL) is still unrun because it requires public exposure, which is gated on the security posture below.

## ⚠️ Flagged for Sam (unratified)

1. **License — Apache-2.0 (proposed).** Applied now so the public repo is licensed from day one (`LICENSE`, `NOTICE`). Ratify or change before accepting external contributions.
2. **EDGAR User-Agent contact — RATIFIED (Sam, 2026-07-09).** SEC fair access requires a declared User-Agent with real contact info. The contact lives in **one** module (`src/edgar/config.ts`, env-overridable via `EDGAR_UA_CONTACT`) and was ratified as proposed:
   `Conduit/0.1 (+https://conduit.samlatino.dev) latinosammy22@gmail.com`
   This ratifies only the contact string; deploy remains blocked pending posture ratification (below).

## ✅ Deploy unblocked — posture ratified (2026-07-09)

Sam ratified the v0.5 security posture on 2026-07-09 (`docs/POSTURE-RATIFICATION.md` §5). The three deploy guards that previously blocked publish were then lifted by the Opus security session in later commits (so guard removal lands in git history *after* the posture, never before):

1. **CI deploy job** added (`.github/workflows/ci.yml` gains a `deploy` job on `main`).
2. **Publish target** set: `wrangler.toml` declares the `conduit.samlatino.dev` custom domain and real D1 / KV / Durable Object binding IDs.
3. **Guard script removed:** `npm run deploy` now runs `wrangler deploy` (the `scripts/deploy-guard.mjs` non-zero gate is gone).

A full `security-review` pass over `/mcp` + the EDGAR client + the playground remains a pre-launch gate (Phase 2/3). The deep-paging exposure gate on `get_filing_section` for large filers is still capped pending its own ratification + deployed-Worker measurement (ARCHITECTURE #11).

## Develop

```bash
npm install
cp .dev.vars.example .dev.vars   # local-only vars; never committed
npm run migrate                  # apply D1 migrations to the local database
npm run dev                      # wrangler dev (local D1/KV), http://localhost:8787
curl http://localhost:8787/healthz
```

| Command | What it does |
| --- | --- |
| `npm run dev` | `wrangler dev` — local Worker with local D1/KV. |
| `npm test` | Vitest in the real workerd runtime (`@cloudflare/vitest-pool-workers`). |
| `npm run typecheck` | `tsc --noEmit` (strict). |
| `npm run lint` | ESLint. |
| `npm run migrate:generate` | drizzle-kit generates a new versioned migration from `src/db/schema.ts`. |
| `npm run migrate` | Apply migrations to local D1 (`wrangler d1 migrations apply`). Never `db push`. |
| `npm run deploy` | `wrangler deploy` to `conduit.samlatino.dev` (posture ratified 2026-07-09). |

## License

[Apache-2.0](LICENSE) (proposed — see flags above). © 2026 Sam Latino.