submit: finfold-growth-mission

submissions/mcp-hackathon/finfold-growth-mission/RIGHTS.md

@@ -0,0 +1,15 @@
+# Submission rights declaration
+
+Project: Finfold Growth Mission API
+Submission slug: finfold-growth-mission
+Submitter: Joey Zhao (Finfold)
+Date: 2026-09-02
+
+The submitter confirms that they own, or have sufficient authorization for, the source code, dependencies, service, data, branding, and other materials submitted in this pull request.
+
+Subject to the official program terms, the submitter authorizes X-Agent to retain, reproduce, audit, test, archive, and publish the submitted program artifact for judging, fraud prevention, dispute handling, ecosystem submission, and post-award accountability. Closing the pull request, deleting a fork, or deleting an external repository does not revoke the official archive rights attached to an accepted and rewarded entry.
+
+Third-party components and their licenses: Runtime dependency Zod is MIT licensed. Development and verification dependencies, including Wrangler, TypeScript, Vitest, Cloudflare Vitest Pool Workers, and Oxlint, retain the licenses recorded in `source/package-lock.json`. Cloudflare Workers, D1, and Workers AI are external hosted services governed by their provider terms and are not redistributed in this submission.
+Exceptions or restrictions: The submitted project source is all rights reserved except for third-party components under their respective licenses. Review, audit, archival, judging, ecosystem submission, and post-award retention are authorized as stated above; no production credentials or customer data are licensed or included.
+
+This declaration must be completed before review. It is not a substitute for event terms reviewed by qualified counsel.

submissions/mcp-hackathon/finfold-growth-mission/SUBMISSION.md

@@ -0,0 +1,45 @@
+# Finfold Growth Mission API
+
+**Submitted via:** `xagt-plugin@0.5.0`
+**Submitted at:** 2026-09-02T08:12:39.464Z
+**Updated at:** 2026-09-03T11:53:00.000Z
+
+## Capability
+
+- **One-line description:** Turn one public business URL and growth objective into one evidence-bound mission, one publishable asset, one tracked CTA, and an outcome-driven next action.
+- **Capability boundary:** Reads one public HTML page, selects one primary growth mission, preserves the model-selected angle and audience, compiles up to three canonical excerpts into a distinct platform-native structure, creates one same-site HTTPS tracked CTA, and accepts attributable outcomes to calculate a verdict and next action. It never renders private pages, bypasses access controls, auto-publishes, modifies external accounts, fabricates missing evidence, or guarantees growth.
+
+## Live API
+
+- **API base URL:** https://api.finfold.app
+- **Health-check URL:** https://api.finfold.app/health
+- **Deployment proof URL:** https://api.finfold.app/.well-known/xagent-verification.json
+- **Authentication:** Bearer review key delivered only through the program's approved private review channel. The raw key is shown once and only its SHA-256 hash is stored.
+- **Rate limits / known limits:** The isolated review key allows 100 authenticated calls per UTC day and expires after 2026-10-05. Source fetches accept public HTML/XHTML only, stream at most 1.5 MB, allow at most three redirects, and time out after 10 seconds. Mission creation is synchronous; the current five-platform production run completed 20/20 calls on the first provider attempt with 16,897 ms p50, 22,548 ms p95, and 24,206 ms p99. JavaScript-only or evidence-thin pages fail with typed errors. Anonymous clicks are raw counts and do not count as credible conversion outcomes by themselves.
+
+## Source and reproducibility
+
+- **Source repository:** https://github.com/joeymilano/finfold-growth-mission-api
+- **Review commit:** `65a4a545ca74b0e357973de433fd108c375531bc`
+- **Source submitted in this PR:** `source/`
+- **Run tests:** `npm ci && npm run check`
+- **Run locally:** `npx wrangler d1 migrations apply finfold-growth-mission --local && npm run dev` (mission generation uses the configured Workers AI binding; the test suite is fully intercepted and does not require paid inference).
+- **Deploy:** Create the D1 database, replace the documented `database_id`, run `npx wrangler d1 migrations apply finfold-growth-mission --remote`, issue a review key with `node scripts/issue-review-key.mjs`, then run `npx wrangler deploy --var "COMMIT_SHA:$(git rev-parse HEAD)"`.
+- **Version binding:** The exact commit is injected at deployment. Public `/health` and same-origin `/.well-known/xagent-verification.json` both return `65a4a545ca74b0e357973de433fd108c375531bc`, which is also the public GitHub review commit.
+
+## Verification
+
+See `verification/README.md` for public version proof, an authenticated mission call, MCP discovery, expected output, safe failure behavior, tracking verification, the credential-free five-platform 20-call report, a redacted real mission, and authenticated live MCP discovery evidence under `source/verification/`.
+
+## Security and data handling
+
+- **Data collected:** Request URL, objective, platform, locale, optional target/landing page, extracted evidence snippets, generated mission/asset, aggregate daily clicks, and reviewer-supplied outcome events. The service does not store raw HTML, API keys, IP addresses, or credentials embedded in URLs.
+- **Purpose and retention:** Evidence and attributable mission data are retained for 30 days so the service can calculate `won`, `lost`, `inconclusive`, or `running`; scheduled cleanup removes expired records. Hashed review-key usage is retained for quota enforcement.
+- **Third parties / outbound network calls:** The Worker fetches only the caller-supplied public source origin and calls Cloudflare Workers AI. Cloudflare Workers, D1, and Workers AI host the service. There are no analytics, ad networks, payment processors, or auto-publishing integrations in the review build.
+- **Known risks / restrictions:** Public pages may change after a mission is generated; the stored source digest and exact evidence snippets bind what was reviewed at generation time. SSRF controls reject local/private/special-use targets, credentials, unsafe ports, suspicious redirects, non-HTML, oversized responses, and HTTPS downgrade. Tracked destinations require HTTPS and the source host, its subdomain, or canonical `www`/apex equivalent. Model output is schema-validated, canonicalized to selected source sections, and given one repair attempt before failing closed. Revenue outcomes use one target currency and all outcomes must fall inside the measurement window. Reviewers should record only real outcomes.
+
+## Support
+
+- **Team / builder:** Joey Zhao (Finfold)
+- **Contact:** support@finfold.app
+- **License / rights:** Joey Zhao owns and authorizes review of the submitted Finfold Growth Mission source under the accompanying all-rights-reserved license and `RIGHTS.md`; third-party packages retain their own licenses.

submissions/mcp-hackathon/finfold-growth-mission/source/.dev.vars.example

@@ -0,0 +1,2 @@
+# Only required when MODEL_PROVIDER=http.
+LLM_API_KEY=replace-with-provider-key

submissions/mcp-hackathon/finfold-growth-mission/source/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci
+      - run: npm run check

submissions/mcp-hackathon/finfold-growth-mission/source/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+.wrangler/
+.dev.vars
+.env
+coverage/
+benchmark-results/
+*.log
+*.cpuprofile
+.DS_Store

submissions/mcp-hackathon/finfold-growth-mission/source/LICENSE

@@ -0,0 +1,9 @@
+Copyright (c) 2026 Finfold. All rights reserved.
+
+This source is publicly viewable for evaluation, security review, and the X-Agent
+hackathon submission described in RIGHTS.md. No permission is granted to copy,
+modify, distribute, sublicense, sell, or use the source commercially except as
+expressly stated in RIGHTS.md or in a separate written agreement with Finfold.
+
+Third-party dependencies are not covered by this notice and remain subject to
+their respective licenses.

submissions/mcp-hackathon/finfold-growth-mission/source/README.md

@@ -0,0 +1,120 @@
+# Finfold Growth Mission API
+
+**One URL. One evidence-bound growth move. One measurable outcome loop.**
+
+Finfold Growth Mission turns a public business page and a growth objective into exactly one primary mission, one platform-native content asset, and one tracked CTA. Real clicks, leads, signups, purchases, and revenue feed back into a `won`, `lost`, `running`, or `inconclusive` verdict with a concrete next action.
+
+This is a standalone Cloudflare Worker built for the X-Agent MCP Hackathon. It is not a wrapper around the private Finfold application and contains no Finfold customer data or proprietary application source.
+
+## Why this exists
+
+Most growth agents stop at copy generation. This capability completes a measurable operating loop:
+
+```mermaid
+flowchart LR
+  A[Public business URL] --> B[Bounded HTML evidence]
+  B --> C[One validated mission]
+  C --> D[One content asset]
+  D --> E[Tracked CTA]
+  E --> F[Real outcomes]
+  F --> G[Verdict + next action]
+```
+
+The model selects the mission, audience, hypothesis, and evidence by stable semantic section ID. A deterministic evidence compiler preserves the selected angle, combines up to three canonical source excerpts, and gives each platform its own publishing structure. Every factual claim remains the exact textual intersection of the deliverable and its cited quote; connective language must be framed as a test or hypothesis. Invalid structure, unknown evidence IDs, unsupported numbers, missing CTA, platform overflow, or guaranteed-result language triggers one repair attempt and then a clear error—never a fabricated fallback.
+
+## Live interfaces
+
+- `GET /health` — status and exact deployed commit
+- `GET /.well-known/xagent-verification.json` — schema version, X-Agent slug, and the same commit
+- `GET /v1/capability` — product boundary, retention, side effects, and fixed per-mission price interface
+- `POST /v1/missions` — create one mission (`mission:create`)
+- `GET /v1/missions/{id}` — read mission, attribution, verdict, and next action (`mission:read`)
+- `POST /v1/missions/{id}/outcomes` — record one idempotent outcome (`outcome:write`)
+- `GET /v1/usage` — key expiry and daily usage (`mission:read`)
+- `GET /r/{trackingCode}` — count an anonymous click and redirect with UTM parameters
+- `POST /mcp` — stateless Streamable HTTP MCP
+- `GET /openapi.json` — OpenAPI 3.1 contract
+
+Mutation endpoints require both `Authorization: Bearer <review-key>` and `Idempotency-Key`. The review key is SHA-256 hashed at rest, scope-limited, capped at 100 authenticated calls per UTC day, and expires on 2026-10-05.
+
+## Quick start
+
+Requirements: Node.js 22+, a Cloudflare account, and Wrangler authentication. Production uses Cloudflare Workers AI with Llama 3.3 70B Instruct Fast for structured generation; an OpenAI-compatible HTTP adapter remains available for alternative deployments and deterministic tests.
+
+```bash
+npm ci
+npx wrangler d1 create finfold-growth-mission
+# Put the returned database_id in wrangler.jsonc.
+npm run types
+npx wrangler d1 migrations apply finfold-growth-mission --local
+npm run dev
+```
+
+Production setup:
+
+```bash
+npx wrangler d1 migrations apply finfold-growth-mission --remote
+node scripts/issue-review-key.mjs --remote
+npx wrangler deploy --var COMMIT_SHA:$(git rev-parse HEAD)
+node scripts/verify-deployment.mjs $(git rev-parse HEAD)
+```
+
+The review key command prints the raw key once after D1 accepts only its hash. Store it in an approved password manager; it cannot be recovered from D1.
+
+## Create a real mission
+
+```bash
+curl https://api.finfold.app/v1/missions \
+  -H "Authorization: Bearer $REVIEW_KEY" \
+  -H "Idempotency-Key: reviewer-demo-001" \
+  -H "Content-Type: application/json" \
+  --data '{
+    "sourceUrl": "https://www.finfold.app/",
+    "objective": "leads",
+    "platform": "linkedin",
+    "locale": "en"
+  }'
+```
+
+Then publish the returned asset manually, use its `/r/...` CTA, and record a real outcome:
+
+```bash
+curl https://api.finfold.app/v1/missions/$MISSION_ID/outcomes \
+  -H "Authorization: Bearer $REVIEW_KEY" \
+  -H "Idempotency-Key: crm-event-001" \
+  -H "Content-Type: application/json" \
+  --data '{"eventId":"crm-lead-001","type":"lead","quantity":1}'
+```
+
+For revenue missions, `targetCurrency` defaults to `USD`; every revenue outcome must use that currency. Custom landing pages must use HTTPS and the source host, its subdomain, or its canonical `www`/apex equivalent.
+
+## Supported decisions
+
+| Objective | Default target | Measurement window | Winning metric |
+|---|---:|---:|---|
+| Leads | 1 | 14 days | Recorded leads |
+| Signups | 1 | 7 days | Recorded signups |
+| Purchases | 1 | 30 days | Recorded purchases |
+| Revenue | 1 | 30 days | Recorded revenue value |
+
+Platforms: `auto`, `linkedin`, `x`, `reddit`, `xiaohongshu`, and `wechat`.
+
+## Quality gates
+
+```bash
+npm run check
+```
+
+This runs lint, strict TypeScript, Worker-runtime unit/integration tests, Wrangler dry-run bundling, and a high-confidence secret scan. See [verification/README.md](verification/README.md) for the complete reproducibility procedure, the five-platform production benchmark, a redacted live mission, and authenticated MCP discovery evidence.
+
+## Safety boundary
+
+- Reads public HTML, metadata, and JSON-LD only; does not execute page JavaScript.
+- Blocks local/private/metadata URLs, credentials, non-standard ports, unsafe redirects, oversized responses, and non-HTML MIME types. Tracked destinations must use HTTPS and stay on the source host hierarchy.
+- Does not auto-publish, log into external accounts, mutate third-party accounts, or guarantee growth.
+- Does not store raw HTML or raw API keys.
+- Stores source evidence snippets and attributable outcome totals for 30 days. Anonymous raw clicks are reported separately and never count as credible conversion evidence on their own.
+
+Details: [Security](docs/SECURITY.md), [Data handling](docs/DATA-HANDLING.md), [Architecture](docs/ARCHITECTURE.md), [API and MCP](docs/API.md), and [Scorecard evidence](docs/SCORECARD.md).
+
+Support: `support@finfold.app`

submissions/mcp-hackathon/finfold-growth-mission/source/RIGHTS.md

@@ -0,0 +1,7 @@
+# Rights and submission authorization
+
+The repository owner represents that they own or are authorized to submit the original Finfold Growth Mission API source in this repository for review and archival in the X-Agent hackathon submission repository.
+
+No customer data, production credentials, third-party proprietary source, or private Finfold application source is included. Third-party packages remain governed by their respective licenses and are referenced through `package-lock.json`.
+
+The X-Agent maintainers are granted permission to review, test, reproduce, and retain the submitted source snapshot for the hackathon program. No broader license to use the Finfold name, trademarks, or source commercially is granted.

submissions/mcp-hackathon/finfold-growth-mission/source/docs/API.md

@@ -0,0 +1,41 @@
+# API and MCP contract
+
+## Authentication and idempotency
+
+All mission and usage endpoints require `Authorization: Bearer <key>`. Required scopes are documented per route. `POST` routes also require an `Idempotency-Key` of 8–128 safe characters.
+
+All routes answer browser preflight requests and expose the request/idempotency headers needed by reviewer consoles. Public documentation endpoints also support `HEAD`. Authentication remains explicit Bearer-token based; the service uses no ambient browser cookie.
+
+Reusing a key with the same normalized request returns the original status and body with `Idempotent-Replayed: true`. Reusing it with a different request returns `409 IDEMPOTENCY_CONFLICT`. A concurrent duplicate returns `409 REQUEST_IN_PROGRESS` and is safe to retry later with the same key.
+
+## Typed source errors
+
+| Code | Meaning | Retry? |
+|---|---|---|
+| `SOURCE_URL_BLOCKED` | URL, network target, port, or redirect violates policy | No |
+| `LANDING_PAGE_BLOCKED` | Tracked destination is not HTTPS or leaves the source host hierarchy | No |
+| `SOURCE_FETCH_FAILED` | Timeout, upstream failure, redirect problem, or non-2xx source | Sometimes |
+| `SOURCE_TOO_LARGE` | Response exceeds the streaming byte limit | No |
+| `SOURCE_INVALID_MIME` | Source is not public HTML/XHTML | No |
+| `SOURCE_NEEDS_RENDERING` | Page is a thin JavaScript shell | No; provide a server-rendered page |
+| `INSUFFICIENT_EVIDENCE` | Static page lacks enough semantic evidence | No; provide a richer page |
+| `EVIDENCE_VALIDATION_FAILED` | Generated quote is not an exact section substring | No content is delivered |
+| `QUALITY_VALIDATION_FAILED` | Objective/platform/CTA/length/number/guarantee gate failed | No content is delivered |
+| `OUTCOME_OUTSIDE_WINDOW` | Event time is before mission start or after its measurement deadline | No |
+| `CURRENCY_MISMATCH` | Revenue event currency differs from the mission target currency | No |
+
+Every error includes `code`, `message`, `retryable`, and `requestId`.
+
+## MCP tools
+
+| Tool | Scope | Mutation | External side effects | Retry rule |
+|---|---|---|---|---|
+| `finfold_create_growth_mission` | `mission:create` | Persists one mission | Fetches public source and calls configured model; never publishes | Same `idempotencyKey` |
+| `finfold_get_growth_mission` | `mission:read` | None | None | Freely repeatable |
+| `finfold_record_growth_outcome` | `outcome:write` | Persists one event | None | Same `eventId` and `idempotencyKey` |
+
+MCP client transport URL: `https://api.finfold.app/mcp`. Send the review key as a Bearer Authorization header. The transport is stateless; no session cookie or server-held client session is required.
+
+Revenue missions accept `targetCurrency` and default to `USD`. Every revenue event must use the same currency. `occurredAt` must fall inside the mission's measurement window.
+
+The complete machine-readable HTTP contract, including public proof, capability, usage, tracking, errors, and MCP authentication, is available at `/openapi.json`.