Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(connect-demo): demo Connect end to end on dev (#9269)

Eric Hayes584beb405e10
diff --git a/.github/workspace-dep-closures.json b/.github/workspace-dep-closures.json
index 164bb902f9..5b700b998d 100644
--- a/.github/workspace-dep-closures.json
+++ b/.github/workspace-dep-closures.json
@@ -4223,6 +4223,12 @@
"connect/crates/connect_platform",
"crates/workspace-hack"
],
+ "connect_demo": [
+ "connect/crates/connect_client",
+ "connect/crates/connect_platform",
+ "connect/services/connect_demo",
+ "crates/workspace-hack"
+ ],
"connect_integration": [
"connect/crates/connect_client",
"connect/crates/connect_platform",
diff --git a/Cargo.lock b/Cargo.lock
index 4adcf9e922..3b96ad8240 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -4939,6 +4939,31 @@ dependencies = [
"zeroize",
]
+[[package]]
+name = "connect_demo"
+version = "0.1.0"
+dependencies = [
+ "axum",
+ "connect_client",
+ "connect_platform",
+ "futures",
+ "html-escape",
+ "http-body-util",
+ "reqwest 0.13.4",
+ "rootcause",
+ "serde",
+ "serde_json",
+ "sse-stream",
+ "thiserror 2.0.18",
+ "tokio",
+ "tower 0.5.3",
+ "tracing",
+ "url",
+ "uuid",
+ "wiremock",
+ "workspace-hack",
+]
+
[[package]]
name = "connect_integration"
version = "0.1.0"
diff --git a/Cargo.toml b/Cargo.toml
index b924516bac..1dd832daf4 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -9,6 +9,7 @@ members = [
"connect/crates/connect_client",
"connect/tests/connect_integration",
"connect/services/connect_api",
+ "connect/services/connect_demo",
"crates/access_requests",
"crates/agent_api_keys",
"crates/routines",
diff --git a/connect/.agents/skills/connect-submission/SKILL.md b/connect/.agents/skills/connect-submission/SKILL.md
index c4a2f7b49b..c55640aad9 100644
--- a/connect/.agents/skills/connect-submission/SKILL.md
+++ b/connect/.agents/skills/connect-submission/SKILL.md
@@ -34,9 +34,10 @@ One vendor per run. The record format, states, and human gates are in
messages. Answer the same day; log each exchange in the record. A request
that changes scope or wording beyond `answers.md` goes to the human first.
7. **Update the record**: `state`, `last_contact`, `next_action`,
- `next_action_owner`, `due`. On approval, set the catalog app's `status` to
- `live` (run `connect-add-app` to re-check it) and log where the secrets
- live.
+ `next_action_owner`, `due`. On approval, log where the secrets live and
+ run conformance (`connect-add-app` re-checks the app). Set the catalog
+ app's `status` to `live` only after conformance passes: a real connect,
+ refresh, and tool call.
Done when the record's state moved forward or its blocker is in the human
queue, and `next_action`, owner, and `due` say exactly what happens next.
diff --git a/connect/AGENTS.md b/connect/AGENTS.md
index 692ef1bb07..458e2db193 100644
--- a/connect/AGENTS.md
+++ b/connect/AGENTS.md
@@ -22,11 +22,11 @@ roles are in [`docs/building.md`](docs/building.md).
| `registry/apps/<id>/` | One app per directory: `app.toml` and `icon.svg`. The catalog's source of truth; spec in [`docs/catalog.md`](docs/catalog.md). |
| `submissions/` | One record per vendor OAuth app submission; process in [`docs/submissions.md`](docs/submissions.md). |
| `crates/` | Rust crates, all named `connect_*`. `connect_client` is the public client. |
-| `services/` | Deployable services; `connect_api` first. |
+| `services/` | Deployable services: `connect_api` and the standalone `connect_demo` customer app. |
| `infra/` | Standalone Pulumi project for Connect's ECS, ALB, database, KMS key, and runtime secret. |
-| `docker-compose.yml` | Local Connect API and PostgreSQL 17. |
+| `docker-compose.yml` | Local Connect API, demo, and PostgreSQL 17. |
| `packages/` | TypeScript packages; `@macro-connect/sdk` is the public web SDK. |
-| `docs/` | Plan, decisions, catalog spec, probing, submissions, research, and deployment runbooks. |
+| `docs/` | Plan, decisions, catalog spec, probing, submissions, [test accounts](docs/test-accounts.md), research, and deployment runbooks. |
| `tasks/` | One spec per builder task, with its Result; process in [`docs/building.md`](docs/building.md). |
| `tooling/` | `dispatch.sh` runs a builder on a task spec; `builder-brief.md` is its shared prompt. |
| `.agents/skills/` | Workflows: `connect-pm`, `connect-add-app`, `connect-submission`. `.claude/skills` symlinks here. |
diff --git a/connect/STATUS.md b/connect/STATUS.md
index 6e6724b0da..c0626577e4 100644
--- a/connect/STATUS.md
+++ b/connect/STATUS.md
@@ -1,8 +1,9 @@
# Status
-Last updated 2026-10-30 by Claude (planning session). Slice 1: Connect as an
-independent backend with integration tests. Target: Macro's own
-users off Pipedream for catalog apps by 2026-11-06 ([plan](docs/plan.md#week-one)).
+Last updated 2026-10-31 by Claude. Slice 1 is deployed and proven end to end
+on dev: `https://connect-dev.macro.com`, demo at
+`https://connect-dev.macro.com/demo`. Target: Macro's own users off Pipedream
+for catalog apps by 2026-11-06 ([plan](docs/plan.md#week-one)).
## Human queue
@@ -10,14 +11,8 @@ Eric. Each item is ready for one sitting; agents prepare the rest.
- [ ] **Review PR #9231** (Connect as an independent backend; touches none of
Macro's deployed services).
-- [ ] **First dev deploy** (after T016 and your review): Connect's own Pulumi
- project in `connect/infra`, stack `dev`. You provide Pulumi access
- (`PULUMI_ACCESS_TOKEN`) and approve `pulumi up` after seeing the preview.
- It creates Connect-only AWS resources plus one DNS record,
- `connect-dev.macro.com`.
-- [ ] **Test workspaces** for the first slice (Linear, Notion, PostHog,
- Sentry): accounts an agent may sign in to, or the `[email protected]`
- browser sign-in below so agents create free ones.
+- [ ] **Review the demo PR** (stacked on #9231): the demo app, its optional
+ infra, and the CDP driver.
- [ ] **Company facts every vendor form asks for** (unblocks Zoom, Xero,
Figma, Vercel, Box, Discord): legal company name; contact name, title,
and email; Connect's production host and OAuth callback (proposed:
@@ -34,10 +29,9 @@ Eric. Each item is ready for one sitting; agents prepare the rest.
- [ ] Rotate the `[email protected]` password (it was shared in a chat
transcript on 2026-10-30), then update `CONNECT_ACCOUNT_PASSWORD` in
Doppler `connect/prd`.
-- [ ] Sign in once in Macro Connect's browser: `ssh -L 6081:localhost:6081
- big-pickle`, open http://localhost:6081/vnc.html; the Google sign-in page
- for `[email protected]` is open. While signed in, enroll an
- authenticator-app (TOTP) second factor and save its setup key as
+- [ ] Enroll an authenticator-app (TOTP) second factor on `[email protected]`
+ (the browser is signed in; view it with `ssh -L 6081:localhost:6081
+ big-pickle` and http://localhost:6081/vnc.html) and save its setup key as
`CONNECT_ACCOUNT_TOTP_SECRET` in Doppler `connect/prd`, so agents can
sign in again without you. ([how it works](docs/submissions.md#browser))
- [ ] Give the submission agents read access to the `[email protected]` inbox
@@ -54,17 +48,25 @@ Eric. Each item is ready for one sitting; agents prepare the rest.
## In flight
-Nothing: waiting on your review of PR #9231 and the first dev deploy.
+Nothing.
## Next
-After the deploy: `connect/tooling/integration.sh dev`, then a real consent per
-live app with test accounts and the browser (T018). Later slices: [T010](tasks/T010-macro-adapter.md) Macro integration,
-then reconnect prompts (T011). Submissions wait on the company
-facts above.
+Token refresh against a live vendor (when a Linear or Sentry access token
+expires, the gateway must refresh it; unit-tested, not yet seen live). Then
+[T010](tasks/T010-macro-adapter.md) Macro integration and reconnect prompts
+(T011). Submissions wait on the company facts above.
## Done
+- 2026-10-31: Dev deployed (`pulumi up`, stack `macro-inc/macro-connect/dev`).
+ `integration.sh dev` passes 11/11, including each vendor accepting Connect's
+ client. Real consents completed for Linear, Notion, PostHog, and Sentry in
+ [test workspaces](docs/test-accounts.md); through the gateway each listed
+ its tools (70, 68, 1, 12) and answered a read tool call.
+ [T019](tasks/T019-demo-app.md) demo deployed at `/demo`: connect, list
+ tools, and call a tool from the browser. `cdp.ts` drives the browser.
+
- 2026-10-30: [T014](tasks/T014-deny-wrappers.md), [T015](tasks/T015-test-databases.md)
CI fixes; [T016](tasks/T016-independent-hosting.md) Connect hosted
independently in `connect/infra` with a local Compose run;
diff --git a/connect/crates/connect_client/AGENTS.md b/connect/crates/connect_client/AGENTS.md
index 2e76046dfa..c849189f81 100644
--- a/connect/crates/connect_client/AGENTS.md
+++ b/connect/crates/connect_client/AGENTS.md
@@ -7,6 +7,7 @@ The public Rust surface for Macro Connect customers. API changes here are breaki
## Start here
- `src/lib.rs`: authenticated async client, error mapping, and MCP gateway address.
+- `catalog_icon` fetches public SVG icons so customer apps do not call the Connect API directly from the browser.
- `src/wire.rs`: shared request and response types used by the client and `connect_api`.
## Scope
diff --git a/connect/crates/connect_client/src/lib.rs b/connect/crates/connect_client/src/lib.rs
index 6850722869..293d5a0f68 100644
--- a/connect/crates/connect_client/src/lib.rs
+++ b/connect/crates/connect_client/src/lib.rs
@@ -129,6 +129,30 @@ impl ConnectClient {
self.request(Method::GET, &["v1", "catalog"], None).await
}
+ /// Fetch an official SVG icon from Connect's public catalog.
+ pub async fn catalog_icon(&self, app_id: &str) -> Result<Vec<u8>, Error> {
+ let mut headers = HeaderMap::new();
+ inject_trace_headers(&mut headers);
+ let response = self
+ .http
+ .get(self.route(&["v1", "catalog", app_id, "icon.svg"]))
+ .headers(headers)
+ .send()
+ .await
+ .map_err(|_| Error::Unavailable)?;
+ if !response.status().is_success() {
+ return Err(Error::Api {
+ status: response.status(),
+ message: "catalog icon unavailable".to_owned(),
+ });
+ }
+ response
+ .bytes()
+ .await
+ .map(|bytes| bytes.to_vec())
+ .map_err(|_| Error::Unavailable)
+ }
+
/// Create a browser session for connecting a user's app.
#[tracing::instrument(name = "connect.client.create_connect_session", skip_all, fields(app_id = %app_id, outcome), err)]
pub async fn create_connect_session(
diff --git a/connect/crates/connect_client/src/test.rs b/connect/crates/connect_client/src/test.rs
index 8ce0a1c18a..cc031d0bed 100644
--- a/connect/crates/connect_client/src/test.rs
+++ b/connect/crates/connect_client/src/test.rs
@@ -22,6 +22,13 @@ async fn calls_every_customer_route_with_the_shared_wire_contract() {
.await;
assert_eq!(client.catalog().await.unwrap()[0].id, "notion");
+ Mock::given(method("GET"))
+ .and(path("/connect/v1/catalog/notion/icon.svg"))
+ .respond_with(ResponseTemplate::new(200).set_body_raw("<svg/>", "image/svg+xml"))
+ .mount(&server)
+ .await;
+ assert_eq!(client.catalog_icon("notion").await.unwrap(), b"<svg/>");
+
Mock::given(method("POST"))
.and(path("/connect/v1/connect-sessions"))
.and(body_json(serde_json::json!({
@@ -91,7 +98,7 @@ async fn calls_every_customer_route_with_the_shared_wire_contract() {
);
assert_eq!(upstream.bearer_token, "ck_test_secret");
assert!(!format!("{client:?} {upstream:?}").contains("ck_test_secret"));
- assert_eq!(server.received_requests().await.unwrap().len(), 5);
+ assert_eq!(server.received_requests().await.unwrap().len(), 6);
}
#[tokio::test]
diff --git a/connect/docker-compose.yml b/connect/docker-compose.yml
index 9f36e49900..ad6259dc70 100644
--- a/connect/docker-compose.yml
+++ b/connect/docker-compose.yml
@@ -24,6 +24,18 @@ services:
depends_on:
db:
condition: service_healthy
+ demo:
+ build:
+ context: ..
+ dockerfile: connect/services/connect_demo/Dockerfile
+ ports:
+ - "${CONNECT_DEMO_PORT:-3000}:3000"
+ environment:
+ CONNECT_BASE_URL: http://api:8080
+ CONNECT_DEMO_CUSTOMER_KEY: ${CONNECT_DEMO_CUSTOMER_KEY:-}
+ CONNECT_DEMO_PUBLIC_URL: http://localhost:${CONNECT_DEMO_PORT:-3000}/demo
+ depends_on:
+ - api
volumes:
connect_db:
diff --git a/connect/docs/decisions.md b/connect/docs/decisions.md
index 6f1d3fc55f..8e1df328ab 100644
--- a/connect/docs/decisions.md
+++ b/connect/docs/decisions.md
@@ -2,6 +2,17 @@
Newest first. Each entry: date, decision, reason, who decided.
+## 2026-10-31
+
+- **Test consents use separate free workspaces, never Macro's.** Vendors offer
+ to join Macro's workspaces because the test account is on `macro.com`;
+ joining adds seats and exposes company data
+ ([test accounts](test-accounts.md)). (Claude)
+- **The demo is a separate Connect customer at `/demo` on the dev host.** It
+ uses only `connect_client` and its own customer key, as Macro will, and is
+ optional in the stack (`demoCustomerKey`). (Eric asked for a working demo;
+ Claude chose the shape)
+
## 2026-10-30
- **First pass: an entirely independent backend, not wired to Macro.** Connect
diff --git a/connect/docs/runbooks/bootstrap.md b/connect/docs/runbooks/bootstrap.md
index b82894d1e1..186e9769af 100644
--- a/connect/docs/runbooks/bootstrap.md
+++ b/connect/docs/runbooks/bootstrap.md
@@ -11,7 +11,7 @@ From the repository root, start PostgreSQL 17 and the API, then create a
customer with a localhost redirect origin:
```sh
-docker compose -f connect/docker-compose.yml up -d --build && docker compose -f connect/docker-compose.yml run --rm api create-customer local --redirect-origin http://localhost:3000
+docker compose -f connect/docker-compose.yml up -d --build db api && docker compose -f connect/docker-compose.yml run --rm api create-customer local --redirect-origin http://localhost:3000
```
The CLI prints the customer key once. Store it locally; do not put it in a
@@ -59,7 +59,8 @@ pulumi up --stack dev
```
Pulumi builds the API image from the repository root, creates the database
-with an RDS-managed password, and writes `APP_SECRETS_JSON` to its own Secrets
+with a Pulumi-generated password (kept in stack state; RDS does not rotate it,
+so the stored `DATABASE_URL` stays valid), and writes `APP_SECRETS_JSON` to its own Secrets
Manager secret for ECS injection. Connect reads no runtime Doppler project.
After the deploy succeeds, check:
@@ -73,6 +74,28 @@ deletion protection, and Pulumi protection. Its public hostname is deliberately
unset until the product owner chooses it; set `publicHost` before previewing
production.
+## Demo
+
+For a local demo, create a separate customer with a localhost redirect origin.
+The CLI prints its key once; pass it to Compose from the process environment:
+
+```sh
+docker compose -f connect/docker-compose.yml run --rm api create-customer demo --redirect-origin http://localhost:3000
+CONNECT_DEMO_CUSTOMER_KEY=<local-demo-key> docker compose -f connect/docker-compose.yml up -d --build demo
+curl --fail http://localhost:3000/demo/health
+```
+
+For dev, create another demo customer with redirect origin
+`https://connect-dev.macro.com` (the origin, without `/demo`). Run
+`connect_api create-customer demo --redirect-origin
+https://connect-dev.macro.com` against the dev database using the approved
+operations path. Store its key with `pulumi config set --secret demoCustomerKey
+<dev-demo-key>` in `connect/infra`, then review the Pulumi preview and deploy
+with human approval. Setting the encrypted key creates the demo image, service,
+secret, and `/demo` listener rule; leaving it unset creates none of them.
+After deployment, open `https://connect-dev.macro.com/demo`. The demo uses its
+own customer key and keeps browser identities in secure cookies.
+
## Verify
Run the live integration checks against dev with a customer key whose redirect
diff --git a/connect/docs/submissions.md b/connect/docs/submissions.md
index 71c29358ff..96a940e997 100644
--- a/connect/docs/submissions.md
+++ b/connect/docs/submissions.md
@@ -88,8 +88,9 @@ Submission agents use Macro Connect's own Chromium, never the shared agent
browser: `connect/tooling/browser/run.sh` starts it (Docker, loopback only)
with a profile volume that holds only `[email protected]` sessions.
-- Agents drive it over CDP at `http://localhost:9333` (raw CDP over a
- WebSocket; Playwright's `connectOverCDP` hangs against this image).
+- Agents drive it over CDP at `http://localhost:9333` with
+ `bun connect/tooling/browser/cdp.ts` (raw CDP; Playwright's
+ `connectOverCDP` hangs against this image). Pipe secrets to `type -`.
- The human watches and takes over at `http://localhost:6081/vnc.html`,
through `ssh -L 6081:localhost:6081 <host>` from their machine.
- Sessions persist across restarts. When a sign-in is needed, the agent fills
diff --git a/connect/docs/test-accounts.md b/connect/docs/test-accounts.md
new file mode 100644
index 0000000000..13d45d22fe
--- /dev/null
+++ b/connect/docs/test-accounts.md
@@ -0,0 +1,22 @@
+# Test accounts
+
+Real consents run in Connect's browser as `[email protected]`, signing in to
+each vendor with Google. Each vendor gets its own free test workspace or
+organization created by that account.
+
+- Never join Macro's own workspaces: vendors offer them because the account
+ is on `macro.com`, and joining adds a member (often a paid seat) and grants
+ Connect access to company data. Choose "create new workspace" and turn off
+ domain auto-join.
+- Grant the narrowest access the consent screen offers (read-only where it
+ is a choice), and call only read tools in checks.
+
+| App | Test workspace | Created |
+| --- | --- | --- |
+| Linear | workspace "Macro Connect Test" (`linear.app/macro-connect-test`, EU region, domain access off) | 2026-10-31 |
+| Notion | personal space "connect macro's Space" (Free) | 2026-10-31 |
+| PostHog | organization "Macro Connect Test", US Cloud | 2026-10-31 |
+| Sentry | organization `macro-connect-test`, US | 2026-10-31 |
+
+The dev integration customer's key is `CONNECT_IT_CUSTOMER_KEY` and the demo
+customer's is `CONNECT_DEMO_CUSTOMER_KEY`, both in Doppler `connect/dev`.
diff --git a/connect/infra/AGENTS.md b/connect/infra/AGENTS.md
index 10581541f0..73df6fa642 100644
--- a/connect/infra/AGENTS.md
+++ b/connect/infra/AGENTS.md
@@ -7,6 +7,9 @@ load balancer, Postgres database, grant KMS key, and runtime secret. It may
read the existing VPC and use the `macro.com` Route 53 zone, but must not
mutate shared security groups or import Macro's `infra/` packages.
+The optional demo service has its own image, task, target group, and runtime
+secret. It is created only when encrypted `demoCustomerKey` config is set.
+
## Configuration
`dev` has the public host `connect-dev.macro.com`. Each stack requires
diff --git a/connect/infra/Pulumi.dev.yaml b/connect/infra/Pulumi.dev.yaml
index daccda1d42..0329a6d095 100644
--- a/connect/infra/Pulumi.dev.yaml
+++ b/connect/infra/Pulumi.dev.yaml
@@ -11,3 +11,5 @@ config:
macro-connect:privateSubnetIds:
- subnet-03c3753c5342f434e
- subnet-0e2530cd19536fe10
+ macro-connect:demoCustomerKey:
+ secure: AAABALBK6BiFbzTtjRY9L4Hjy1tjFfTmYGgezhb/AJAknj4vqt58xC5RBktaok8LUnybmskygZw4FpLcVK653aBucho5Kj5YT1uod0HeZ5xmnitPqgkcV6mQ5yF6LENxlt94i6uLaf87BV62afKJS/Xomw==
diff --git a/connect/infra/bun.lock b/connect/infra/bun.lock
index 96628ff8e6..d027aeedc7 100644
--- a/connect/infra/bun.lock
+++ b/connect/infra/bun.lock
@@ -8,6 +8,7 @@
"@pulumi/aws": "^7.34.0",
"@pulumi/awsx": "^3.1.0",
"@pulumi/pulumi": "^3.209.0",
+ "@pulumi/random": "^4.21.6",
"smol-toml": "^1.5.2",
},
"devDependencies": {
@@ -174,6 +175,8 @@
"@pulumi/pulumi": ["@pulumi/[email protected]", "", { "dependencies": { "@grpc/grpc-js": "^1.10.1", "@logdna/tail-file": "^2.0.6", "@npmcli/arborist": "^9.0.0", "@opentelemetry/api": "^1.9", "@opentelemetry/core": "^2.9", "@opentelemetry/exporter-trace-otlp-grpc": "^0.220", "@opentelemetry/exporter-zipkin": "^2.9", "@opentelemetry/instrumentation": "^0.220", "@opentelemetry/instrumentation-grpc": "^0.220", "@opentelemetry/resources": "^2.9", "@opentelemetry/sdk-trace-base": "^2.9", "@opentelemetry/sdk-trace-node": "^2.9", "@opentelemetry/semantic-conventions": "^1.42", "@types/google-protobuf": "^3.15.5", "@types/semver": "^7.5.6", "execa": "^5.1.0", "google-protobuf": "^3.21.4", "ini": "^2.0.0", "js-yaml": "^4.3.2", "minimist": "^1.2.6", "normalize-package-data": "^6.0.0", "require-from-string": "^2.0.1", "semver": "^7.5.2", "source-map-support": "^0.5.6", "upath": "^1.1.0" }, "peerDependencies": { "ts-node": ">= 7.0.1 < 12", "typescript": ">= 3.8.3 < 7" }, "optionalPeers": ["ts-node", "typescript"] }, "sha512-Yh2k0Kry4u5LM730KUO5HZFnqHdlW9ypoQ8zgO0Tqam1G6urFXjIUTUaLxvWrdsm6gKCoyVS6CPdeOGcV+Msvg=="],
+ "@pulumi/random": ["@pulumi/[email protected]", "", { "dependencies": { "@pulumi/pulumi": "^3.142.0" } }, "sha512-HsWUATAcKxceBcvNzPIdkC7sXyWWiGZmd/y4eZKF5nSAwCgpOPReZ+LLFbkl2bvKGHc3nNX5vIM84YU2dpSD1Q=="],
+
"@sigstore/bundle": ["@sigstore/[email protected]", "", { "dependencies": { "@sigstore/protobuf-specs": "^0.5.0" } }, "sha512-NwCl5Y0V6Di0NexvkTqdoVfmjTaQwoLM236r89KEojGmq/jMls8S+zb7yOwAPdXvbwfKDlP+lmXgAL4vKSQT+A=="],
"@sigstore/core": ["@sigstore/[email protected]", "", {}, "sha512-qRsxPnCrbC/puegGxKuynfnxgLiHqWStrSjxkoB4YKqq3Z3s4cyZyj42ZdWFAEblNP65C+rBH8EuREHIXoi83g=="],
diff --git a/connect/infra/index.ts b/connect/infra/index.ts
index 9ac6dbc327..3a2a0df5a0 100644
--- a/connect/infra/index.ts
+++ b/connect/infra/index.ts
@@ -3,6 +3,7 @@ import { join, resolve } from 'node:path';
import * as aws from '@pulumi/aws';
import * as awsx from '@pulumi/awsx';
import * as pulumi from '@pulumi/pulumi';
+import * as random from '@pulumi/random';
import { parse } from 'smol-toml';
const stack = pulumi.getStack();
@@ -35,6 +36,7 @@ type OwnAppCredentials = Record<
>;
const ownAppCredentials =
config.getSecretObject<OwnAppCredentials>('ownAppCredentials');
+const demoCustomerKey = config.getSecret('demoCustomerKey');
if (liveOwnApps.length > 0 && !ownAppCredentials) {
throw new Error(
'Live own-app entries require encrypted ownAppCredentials config',
@@ -222,6 +224,12 @@ const dbSubnets = new aws.rds.SubnetGroup(`${name}-db-subnets`, {
subnetIds: privateSubnetIds,
tags,
});
+// Pulumi owns the password: an RDS-managed one rotates weekly behind the
+// DATABASE_URL baked into the runtime secret.
+const dbPassword = new random.RandomPassword(`${name}-db-password`, {
+ length: 40,
+ special: false,
+});
const database = new aws.rds.Instance(
`${name}-db`,
{
@@ -234,7 +242,7 @@ const database = new aws.rds.Instance(
storageEncrypted: true,
dbName: 'macro_connect',
username: 'connect_api',
- manageMasterUserPassword: true,
+ password: dbPassword.result,
dbSubnetGroupName: dbSubnets.name,
vpcSecurityGroupIds: [dbSg.id],
publiclyAccessible: false,
@@ -246,20 +254,13 @@ const database = new aws.rds.Instance(
},
{ protect: stack === 'prod' },
);
-const dbSecretArn = database.masterUserSecrets.apply((secrets) => {
- if (secrets.length !== 1) throw new Error('RDS master secret is missing');
- return secrets[0].secretArn;
-});
-const dbSecret = aws.secretsmanager.getSecretVersionOutput({
- secretId: dbSecretArn,
-});
const databaseUrl = pulumi.secret(
pulumi
- .all([database.address, dbSecret.secretString])
- .apply(([address, secret]) => {
- const credentials = JSON.parse(secret) as { password: string };
- return `postgresql://connect_api:${encodeURIComponent(credentials.password)}@${address}:5432/macro_connect`;
- }),
+ .all([database.address, dbPassword.result])
+ .apply(
+ ([address, password]) =>
+ `postgresql://connect_api:${encodeURIComponent(password)}@${address}:5432/macro_connect`,
+ ),
);
const runtimeSecret = new aws.secretsmanager.Secret(`${name}-runtime`, {
name: `${name}-runtime`,
@@ -428,6 +429,158 @@ const service = new aws.ecs.Service(
{ dependsOn: [https, runtimeSecretVersion] },
);
+if (demoCustomerKey) {
+ const demoName = `${name}-demo`;
+ const demoRepository = new aws.ecr.Repository(`${demoName}-repo`, {
+ name: demoName,
+ imageScanningConfiguration: { scanOnPush: true },
+ tags,
+ });
+ const demoImage = new awsx.ecr.Image(`${demoName}-image`, {
+ repositoryUrl: demoRepository.repositoryUrl,
+ context: '../..',
+ dockerfile: '../../connect/services/connect_demo/Dockerfile',
+ platform: 'linux/amd64',
+ });
+ const demoLogs = new aws.cloudwatch.LogGroup(`${demoName}-logs`, {
+ name: `/ecs/${demoName}`,
+ retentionInDays: stack === 'prod' ? 30 : 7,
+ tags,
+ });
+ const demoSg = new aws.ec2.SecurityGroup(`${demoName}-sg`, {
+ vpcId: vpc.id,
+ egress: [],
+ tags,
+ });
+ new aws.vpc.SecurityGroupEgressRule(`${name}-alb-to-demo`, {
+ securityGroupId: albSg.id,
+ ipProtocol: 'tcp',
+ fromPort: 3000,
+ toPort: 3000,
+ referencedSecurityGroupId: demoSg.id,
+ tags,
+ });
+ new aws.vpc.SecurityGroupIngressRule(`${demoName}-from-alb`, {
+ securityGroupId: demoSg.id,
+ ipProtocol: 'tcp',
+ fromPort: 3000,
+ toPort: 3000,
+ referencedSecurityGroupId: albSg.id,
+ tags,
+ });
+ new aws.vpc.SecurityGroupEgressRule(`${demoName}-out`, {
+ securityGroupId: demoSg.id,
+ ipProtocol: '-1',
+ cidrIpv4: '0.0.0.0/0',
+ tags,
+ });
+ const demoSecret = new aws.secretsmanager.Secret(`${demoName}-runtime`, {
+ name: `${demoName}-runtime`,
+ tags,
+ });
+ const demoSecretVersion = new aws.secretsmanager.SecretVersion(
+ `${demoName}-runtime-version`,
+ {
+ secretId: demoSecret.id,
+ secretString: pulumi.secret(
+ demoCustomerKey.apply((key) =>
+ JSON.stringify({
+ CONNECT_BASE_URL: publicUrl,
+ CONNECT_DEMO_PUBLIC_URL: `${publicUrl}/demo`,
+ CONNECT_DEMO_CUSTOMER_KEY: key,
+ }),
+ ),
+ ),
+ },
+ );
+ new aws.iam.RolePolicy(`${demoName}-execution-secret`, {
+ role: executionRole.name,
+ policy: pulumi.jsonStringify({
+ Version: '2012-10-17',
+ Statement: [
+ {
+ Effect: 'Allow',
+ Action: 'secretsmanager:GetSecretValue',
+ Resource: demoSecret.arn,
+ },
+ ],
+ }),
+ });
+ const demoTarget = new aws.lb.TargetGroup(`${demoName}-target`, {
+ // Target group names are limited to 32 characters.
+ namePrefix: 'demo-',
+ port: 3000,
+ protocol: 'HTTP',
+ targetType: 'ip',
+ vpcId: vpc.id,
+ healthCheck: { path: '/demo/health', protocol: 'HTTP', matcher: '200' },
+ tags,
+ });
+ const demoRule = new aws.lb.ListenerRule(`${demoName}-rule`, {
+ listenerArn: https.arn,
+ priority: 100,
+ conditions: [{ pathPattern: { values: ['/demo', '/demo/*'] } }],
+ actions: [{ type: 'forward', targetGroupArn: demoTarget.arn }],
+ tags,
+ });
+ const demoTask = new aws.ecs.TaskDefinition(`${demoName}-task`, {
+ family: demoName,
+ cpu: '256',
+ memory: '512',
+ networkMode: 'awsvpc',
+ requiresCompatibilities: ['FARGATE'],
+ taskRoleArn: taskRole.arn,
+ executionRoleArn: executionRole.arn,
+ containerDefinitions: pulumi.jsonStringify([
+ {
+ name: 'connect_demo',
+ image: demoImage.imageUri,
+ essential: true,
+ portMappings: [{ containerPort: 3000, protocol: 'tcp' }],
+ secrets: [
+ {
+ name: 'APP_SECRETS_JSON',
+ valueFrom: pulumi.interpolate`${demoSecret.arn}:::${demoSecretVersion.versionId}`,
+ },
+ ],
+ logConfiguration: {
+ logDriver: 'awslogs',
+ options: {
+ 'awslogs-group': demoLogs.name,
+ 'awslogs-region': aws.config.region ?? 'us-east-1',
+ 'awslogs-stream-prefix': 'connect_demo',
+ },
+ },
+ },
+ ]),
+ tags,
+ });
+ new aws.ecs.Service(
+ `${demoName}-service`,
+ {
+ cluster: cluster.arn,
+ taskDefinition: demoTask.arn,
+ desiredCount: 1,
+ launchType: 'FARGATE',
+ deploymentCircuitBreaker: { enable: true, rollback: true },
+ networkConfiguration: {
+ subnets: privateSubnetIds,
+ securityGroups: [demoSg.id],
+ assignPublicIp: false,
+ },
+ loadBalancers: [
+ {
+ targetGroupArn: demoTarget.arn,
+ containerName: 'connect_demo',
+ containerPort: 3000,
+ },
+ ],
+ tags,
+ },
+ { dependsOn: [demoRule, demoSecretVersion] },
+ );
+}
+
export const connectUrl = publicUrl;
export const clusterArn = cluster.arn;
export const serviceArn = service.id;
diff --git a/connect/infra/package.json b/connect/infra/package.json
index 6b596013da..c3d4a16224 100644
--- a/connect/infra/package.json
+++ b/connect/infra/package.json
@@ -8,6 +8,7 @@
"@pulumi/aws": "^7.34.0",
"@pulumi/awsx": "^3.1.0",
"@pulumi/pulumi": "^3.209.0",
+ "@pulumi/random": "^4.21.6",
"smol-toml": "^1.5.2"
},
"devDependencies": {
diff --git a/connect/services/connect_api/src/domain/oauth.rs b/connect/services/connect_api/src/domain/oauth.rs
index 904a9c8453..43ad330204 100644
--- a/connect/services/connect_api/src/domain/oauth.rs
+++ b/connect/services/connect_api/src/domain/oauth.rs
@@ -109,6 +109,12 @@ pub trait OAuthRepository: Send + Sync {
async fn get_session(&self, token: &str) -> Result<Option<Session>, Error>;
async fn save_state(&self, state: &OAuthState) -> Result<(), Error>;
async fn take_state(&self, state: &str) -> Result<Option<TakenState>, Error>;
+ /// Reads a registered client without taking the register-once lock.
+ async fn get_client(
+ &self,
+ issuer: &str,
+ redirect_uri: &str,
+ ) -> Result<Option<OAuthClientRecord>, Error>;
async fn lock_client(
&self,
issuer: &str,
@@ -534,12 +540,13 @@ impl OAuthService {
.get(app_id)
.and_then(|client| client.secret.clone()),
ClientRegistration::Dcr => {
- let mut locked = self
+ // A plain read: a refresh already holds the grant's lock on
+ // one pool connection, so it must not open a second one here.
+ let record = self
.repository
- .lock_client(issuer, &self.callback_url())
- .await?;
- let record = locked.get().await?.ok_or(Error::OAuth)?;
- locked.commit().await?;
+ .get_client(issuer, &self.callback_url())
+ .await?
+ .ok_or(Error::OAuth)?;
match record.secret {
Some(envelope) => {
let mut secret = self
diff --git a/connect/services/connect_api/src/outbound/oauth.rs b/connect/services/connect_api/src/outbound/oauth.rs
index 090ba707d1..8286059ed1 100644
--- a/connect/services/connect_api/src/outbound/oauth.rs
+++ b/connect/services/connect_api/src/outbound/oauth.rs
@@ -45,8 +45,8 @@ impl TokenBody {
let expires_at = self
.expires_in
.map(|seconds| {
- Utc::now()
- .checked_add_signed(Duration::seconds(seconds))
+ Duration::try_seconds(seconds)
+ .and_then(|ttl| Utc::now().checked_add_signed(ttl))
.ok_or(Error::OAuth)
})
.transpose()?;
diff --git a/connect/services/connect_api/src/outbound/oauth_store.rs b/connect/services/connect_api/src/outbound/oauth_store.rs
index 8813afbe75..3d9194736f 100644
--- a/connect/services/connect_api/src/outbound/oauth_store.rs
+++ b/connect/services/connect_api/src/outbound/oauth_store.rs
@@ -110,46 +110,54 @@ struct ClientLock {
redirect_uri: String,
}
+#[expect(
+ clippy::disallowed_methods,
+ reason = "Connect's own database uses runtime-checked queries per connect/docs/decisions.md"
+)]
+async fn fetch_client<'e>(
+ executor: impl sqlx::PgExecutor<'e>,
+ issuer: &str,
+ redirect_uri: &str,
+) -> Result<Option<OAuthClientRecord>, Error> {
+ let row = sqlx::query_as::<_, ClientRow>("SELECT client_id, secret_ciphertext, secret_nonce, secret_encrypted_data_key, secret_kms_key_id, secret_encryption_version FROM oauth_clients WHERE issuer = $1 AND redirect_uri = $2")
+ .bind(issuer).bind(redirect_uri).fetch_optional(executor).await.map_err(storage)?;
+ row.map(|row| {
+ let secret = match (
+ row.secret_ciphertext,
+ row.secret_nonce,
+ row.secret_encrypted_data_key,
+ row.secret_kms_key_id,
+ row.secret_encryption_version,
+ ) {
+ (
+ Some(ciphertext),
+ Some(nonce),
+ Some(encrypted_data_key),
+ Some(kms_key_id),
+ Some(encryption_version),
+ ) => Some(Envelope {
+ ciphertext,
+ nonce,
+ encrypted_data_key,
+ kms_key_id,
+ encryption_version,
+ access_token_expires_at: None,
+ }),
+ (None, None, None, None, None) => None,
+ _ => return Err(Error::Cipher),
+ };
+ Ok(OAuthClientRecord {
+ id: row.client_id,
+ secret,
+ })
+ })
+ .transpose()
+}
+
#[async_trait::async_trait]
impl LockedClient for ClientLock {
- #[expect(
- clippy::disallowed_methods,
- reason = "Connect's own database uses runtime-checked queries per connect/docs/decisions.md"
- )]
async fn get(&mut self) -> Result<Option<OAuthClientRecord>, Error> {
- let row = sqlx::query_as::<_, ClientRow>("SELECT client_id, secret_ciphertext, secret_nonce, secret_encrypted_data_key, secret_kms_key_id, secret_encryption_version FROM oauth_clients WHERE issuer = $1 AND redirect_uri = $2")
- .bind(&self.issuer).bind(&self.redirect_uri).fetch_optional(&mut *self.transaction).await.map_err(storage)?;
- row.map(|row| {
- let secret = match (
- row.secret_ciphertext,
- row.secret_nonce,
- row.secret_encrypted_data_key,
- row.secret_kms_key_id,
- row.secret_encryption_version,
- ) {
- (
- Some(ciphertext),
- Some(nonce),
- Some(encrypted_data_key),
- Some(kms_key_id),
- Some(encryption_version),
- ) => Some(Envelope {
- ciphertext,
- nonce,
- encrypted_data_key,
- kms_key_id,
- encryption_version,
- access_token_expires_at: None,
- }),
- (None, None, None, None, None) => None,
- _ => return Err(Error::Cipher),
- };
- Ok(OAuthClientRecord {
- id: row.client_id,
- secret,
- })
- })
- .transpose()
+ fetch_client(&mut *self.transaction, &self.issuer, &self.redirect_uri).await
}
#[expect(
@@ -343,6 +351,14 @@ impl OAuthRepository for PostgresRepository {
.transpose()
}
+ async fn get_client(
+ &self,
+ issuer: &str,
+ redirect_uri: &str,
+ ) -> Result<Option<OAuthClientRecord>, Error> {
+ fetch_client(&self.pool, issuer, redirect_uri).await
+ }
+
async fn lock_client(
&self,
issuer: &str,
diff --git a/connect/services/connect_demo/AGENTS.md b/connect/services/connect_demo/AGENTS.md
new file mode 100644
index 0000000000..e47ce29337
--- /dev/null
+++ b/connect/services/connect_demo/AGENTS.md
@@ -0,0 +1,28 @@
+# Connect demo
+
+## What it is
+
+A standalone customer app for exercising Connect's catalog, OAuth flow, and MCP gateway from one page.
+
+## Start here
+
+- `src/main.rs`: browser routes, cookie identity, rendering, and startup.
+- `src/mcp.rs`: MCP initialization, session handling, JSON/SSE parsing, and tool calls.
+- `src/app.js`: loads tool forms and results into the catalog page.
+- `src/test.rs` and `src/mcp/test.rs`: fake Connect and held-open SSE tests.
+
+## Scope
+
+- Owns: demo browser experience and its opaque browser identity.
+- Not here: OAuth grants or vendor credentials → `connect_api`.
+
+## Boundaries
+
+- Connect access goes through `connect_client`; the demo never exports vendor tokens.
+- The configured public URL ends in `/demo` and is the OAuth redirect target base.
+
+## Checks
+
+- `cargo nextest run --all-features -p connect_demo`
+- `cargo clippy -p connect_demo --all-features --all-targets -- -D warnings`
+- `cargo x deps --check` after `just hakari` when dependencies change.
diff --git a/connect/services/connect_demo/CLAUDE.md b/connect/services/connect_demo/CLAUDE.md
new file mode 120000
index 0000000000..47dc3e3d86
--- /dev/null
+++ b/connect/services/connect_demo/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/connect/services/connect_demo/Cargo.toml b/connect/services/connect_demo/Cargo.toml
new file mode 100644
index 0000000000..6fe521df05
--- /dev/null
+++ b/connect/services/connect_demo/Cargo.toml
@@ -0,0 +1,28 @@
+[package]
+name = "connect_demo"
+version = "0.1.0"
+edition = "2024"
+publish = false
+
+[dependencies]
+axum = { workspace = true }
+connect_client = { path = "../../crates/connect_client" }
+connect_platform = { path = "../../crates/connect_platform" }
+futures = { workspace = true }
+html-escape = { workspace = true }
+reqwest = { workspace = true, features = ["stream"] }
+rootcause = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+sse-stream = { workspace = true }
+thiserror = { workspace = true }
+tokio = { workspace = true, features = ["net", "signal"] }
+tracing = { workspace = true }
+uuid = { workspace = true }
+url = { workspace = true }
+workspace-hack = { version = "0.1", path = "../../../crates/workspace-hack" }
+
+[dev-dependencies]
+http-body-util = { workspace = true }
+tower = { workspace = true }
+wiremock = { workspace = true }
diff --git a/connect/services/connect_demo/Dockerfile b/connect/services/connect_demo/Dockerfile
new file mode 100644
index 0000000000..3829f65228
--- /dev/null
+++ b/connect/services/connect_demo/Dockerfile
@@ -0,0 +1,18 @@
+# syntax=docker/dockerfile:1
+FROM rust:1.94-bookworm AS builder
+WORKDIR /app
+ENV SQLX_OFFLINE=true
+RUN apt-get update && apt-get install -y --no-install-recommends cmake clang libclang-dev && rm -rf /var/lib/apt/lists/*
+COPY . .
+RUN --mount=type=cache,target=/usr/local/cargo/registry,sharing=shared \
+ --mount=type=cache,target=/usr/local/cargo/git/db,sharing=shared \
+ cargo build --release --locked -p connect_demo --bin connect_demo && \
+ strip target/release/connect_demo
+
+FROM debian:bookworm-slim
+RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates && rm -rf /var/lib/apt/lists/* \
+ && useradd --system --uid 10001 connect
+COPY --from=builder /app/target/release/connect_demo /usr/local/bin/connect_demo
+USER connect
+EXPOSE 3000
+ENTRYPOINT ["connect_demo"]
diff --git a/connect/services/connect_demo/src/app.js b/connect/services/connect_demo/src/app.js
new file mode 100644
index 0000000000..addb92de7d
--- /dev/null
+++ b/connect/services/connect_demo/src/app.js
@@ -0,0 +1,25 @@
+let latestRequest = 0;
+
+document.addEventListener('submit', async (event) => {
+ const form = event.target;
+ if (!(form instanceof HTMLFormElement) || !form.classList.contains('ajax')) return;
+ event.preventDefault();
+ const workspace = document.getElementById('workspace');
+ if (!workspace) return;
+ const requestId = ++latestRequest;
+ workspace.textContent = 'Loading tools…';
+ try {
+ const response = await fetch(form.action, {
+ method: 'POST',
+ body: new URLSearchParams(new FormData(form)),
+ credentials: 'same-origin',
+ });
+ const html = await response.text();
+ if (requestId !== latestRequest) return;
+ workspace.innerHTML = html;
+ } catch {
+ if (requestId !== latestRequest) return;
+ workspace.textContent = 'The demo could not reach the service.';
+ }
+ workspace.scrollIntoView({ behavior: 'smooth', block: 'start' });
+});
diff --git a/connect/services/connect_demo/src/main.rs b/connect/services/connect_demo/src/main.rs
new file mode 100644
index 0000000000..01cc329452
--- /dev/null
+++ b/connect/services/connect_demo/src/main.rs
@@ -0,0 +1,381 @@
+//! Standalone browser customer for exercising Macro Connect.
+
+mod mcp;
+#[cfg(test)]
+mod test;
+
+use std::{collections::HashSet, sync::Arc, time::Duration};
+
+use axum::{
+ Extension, Form, Router,
+ extract::{Path, Query, Request, State},
+ http::{HeaderValue, StatusCode, header},
+ middleware::{self, Next},
+ response::{Html, IntoResponse, Redirect, Response},
+ routing::{get, post},
+};
+use connect_client::{ConnectClient, wire::ConnectionStatus};
+use connect_platform::{ConfigLoader, Telemetry, http_trace_layer};
+use serde::Deserialize;
+use serde_json::Value;
+use tokio::net::TcpListener;
+use tracing::Span;
+use url::Url;
+use uuid::Uuid;
+
+#[derive(Clone)]
+struct AppState {
+ client: Arc<ConnectClient>,
+ http: reqwest::Client,
+ public_url: Url,
+}
+
+#[derive(Clone)]
+struct DemoUser(String);
+
+fn page(title: &str, content: &str) -> Html<String> {
+ Html(format!(
+ "<!doctype html><html lang=\"en\"><head><meta charset=\"utf-8\"><meta name=\"viewport\" content=\"width=device-width,initial-scale=1\"><title>{}</title><style>{}</style></head><body><h1>Macro Connect demo</h1>{content}<script>{}</script></body></html>",
+ escape(title),
+ include_str!("style.css"),
+ include_str!("app.js")
+ ))
+}
+
+fn escape(text: &str) -> String {
+ html_escape::encode_safe(text).into_owned()
+}
+
+fn path_id(id: &str) -> String {
+ url::form_urlencoded::byte_serialize(id.as_bytes()).collect()
+}
+
+fn error_page(error: impl std::fmt::Display) -> Response {
+ (
+ StatusCode::BAD_GATEWAY,
+ page(
+ "Demo error",
+ &format!(
+ "<p class=\"error\">{}</p><a href=\"/demo\">Back to catalog</a>",
+ escape(&error.to_string())
+ ),
+ ),
+ )
+ .into_response()
+}
+
+fn error_fragment(error: impl std::fmt::Display) -> Response {
+ (
+ StatusCode::BAD_GATEWAY,
+ Html(format!(
+ "<p class=\"error\">{}</p>",
+ escape(&error.to_string())
+ )),
+ )
+ .into_response()
+}
+
+async fn cookie(mut request: Request, next: Next) -> Response {
+ let existing = request
+ .headers()
+ .get(header::COOKIE)
+ .and_then(|header| header.to_str().ok())
+ .and_then(|value| {
+ value
+ .split(';')
+ .find_map(|part| part.trim().strip_prefix("connect_demo_user="))
+ .and_then(|value| Uuid::parse_str(value).ok())
+ });
+ let id = existing.unwrap_or_else(Uuid::new_v4);
+ request.extensions_mut().insert(DemoUser(id.to_string()));
+ let mut response = next.run(request).await;
+ if existing.is_none()
+ && let Ok(value) = HeaderValue::from_str(&format!(
+ "connect_demo_user={id}; Path=/demo; Max-Age=2592000; Secure; HttpOnly; SameSite=Lax"
+ ))
+ {
+ response.headers_mut().insert(header::SET_COOKIE, value);
+ }
+ response
+}
+
+async fn health() -> &'static str {
+ "ok"
+}
+
+async fn catalog(State(state): State<AppState>, Extension(user): Extension<DemoUser>) -> Response {
+ let (apps, connections) =
+ match tokio::try_join!(state.client.catalog(), state.client.connections(&user.0)) {
+ Ok(value) => value,
+ Err(error) => return error_page(error),
+ };
+ let connected: HashSet<&str> = connections
+ .iter()
+ .filter(|connection| matches!(connection.status, ConnectionStatus::Active))
+ .map(|connection| connection.app_id.as_str())
+ .collect();
+ let mut content =
+ String::from("<p>Connect an app, then try its MCP tools.</p><div class=\"grid\">");
+ for app in apps {
+ let id = path_id(&app.id);
+ content.push_str("<section class=\"card\">");
+ if app.icon_url.is_some() {
+ content.push_str(&format!("<img alt=\"\" src=\"/demo/icons/{id}\">"));
+ }
+ content.push_str(&format!(
+ "<h2>{}</h2><p>{}</p><span class=\"badge\">{}</span><div class=\"actions\">",
+ escape(&app.name),
+ escape(&app.description),
+ if app.access.iter().any(|access| access == "api") {
+ "MCP + API"
+ } else {
+ "MCP"
+ }
+ ));
+ if connected.contains(app.id.as_str()) {
+ content.push_str(&format!("<strong>Connected</strong><form method=\"post\" action=\"/demo/disconnect/{id}\"><button>Disconnect</button></form><form class=\"ajax\" method=\"post\" action=\"/demo/apps/{id}/tools\"><button>Try it</button></form><small>Disconnect removes this demo connection without revoking vendor access.</small>"));
+ } else {
+ content.push_str(&format!("<form method=\"post\" action=\"/demo/connect/{id}\"><button>Connect</button></form>"));
+ }
+ content.push_str("</div></section>");
+ }
+ content.push_str("</div><div id=\"workspace\" aria-live=\"polite\"></div>");
+ page("Catalog", &content).into_response()
+}
+
+async fn icon(State(state): State<AppState>, Path(app_id): Path<String>) -> Response {
+ match state.client.catalog_icon(&app_id).await {
+ Ok(bytes) => (
+ [
+ (header::CONTENT_TYPE, "image/svg+xml"),
+ (header::CACHE_CONTROL, "public, max-age=3600"),
+ ],
+ bytes,
+ )
+ .into_response(),
+ Err(_) => StatusCode::NOT_FOUND.into_response(),
+ }
+}
+
+async fn connect(
+ State(state): State<AppState>,
+ Extension(user): Extension<DemoUser>,
+ Path(app_id): Path<String>,
+) -> Response {
+ let mut redirect_url = state.public_url.clone();
+ redirect_url.set_path("/demo/connected");
+ redirect_url.query_pairs_mut().append_pair("app", &app_id);
+ match state
+ .client
+ .create_connect_session(&user.0, &app_id, redirect_url.as_str())
+ .await
+ {
+ Ok(session) => (
+ StatusCode::SEE_OTHER,
+ [(header::LOCATION, session.connect_url)],
+ )
+ .into_response(),
+ Err(error) => error_page(error),
+ }
+}
+
+#[derive(Default, Deserialize)]
+struct ConnectedQuery {
+ app: Option<String>,
+ app_id: Option<String>,
+ status: Option<String>,
+ reason: Option<String>,
+}
+
+async fn connected(Query(query): Query<ConnectedQuery>) -> Html<String> {
+ let app = query
+ .app_id
+ .or(query.app)
+ .unwrap_or_else(|| "app".to_owned());
+ let content = if query.status.as_deref() == Some("error") {
+ format!(
+ "<p class=\"error\">Could not connect {}: {}</p>",
+ escape(&app),
+ escape(query.reason.as_deref().unwrap_or("unknown error"))
+ )
+ } else if query.status.as_deref() == Some("connected") {
+ format!("<p>Connected {}.</p>", escape(&app))
+ } else {
+ "<p>Connection result is unavailable.</p>".to_owned()
+ };
+ page(
+ "Connection result",
+ &format!("{content}<a href=\"/demo\">Back to catalog</a>"),
+ )
+}
+
+async fn disconnect(
+ State(state): State<AppState>,
+ Extension(user): Extension<DemoUser>,
+ Path(app_id): Path<String>,
+) -> Response {
+ match state.client.delete_connection(&user.0, &app_id).await {
+ Ok(_) => Redirect::to("/demo").into_response(),
+ Err(error) => error_page(error),
+ }
+}
+
+#[tracing::instrument(name = "demo.mcp_list_tools", skip_all, fields(app_id = %app_id, outcome))]
+async fn tools(
+ State(state): State<AppState>,
+ Extension(user): Extension<DemoUser>,
+ Path(app_id): Path<String>,
+) -> Response {
+ let result = mcp::list_tools(&state.client, &state.http, &user.0, &app_id).await;
+ Span::current().record("outcome", if result.is_ok() { "ok" } else { "error" });
+ match result {
+ Ok(value) => {
+ let id = path_id(&app_id);
+ let mut content = format!("<p>Tools for {}.</p>", escape(&app_id));
+ if let Some(list) = value.get("tools").and_then(Value::as_array) {
+ for tool in list {
+ let name = tool.get("name").and_then(Value::as_str).unwrap_or("");
+ if name.is_empty() {
+ continue;
+ }
+ let schema = serde_json::to_string_pretty(
+ tool.get("inputSchema").unwrap_or(&Value::Null),
+ )
+ .unwrap_or_else(|_| "null".to_owned());
+ content.push_str(&format!("<section class=\"panel\"><h2>{}</h2><p>{}</p><details><summary>Input schema</summary><pre>{}</pre></details><form class=\"ajax\" method=\"post\" action=\"/demo/apps/{id}/call\"><input type=\"hidden\" name=\"name\" value=\"{}\"><label>JSON arguments<textarea name=\"arguments\">{{}}</textarea></label><button>Run tool</button></form></section>", escape(name), escape(tool.get("description").and_then(Value::as_str).unwrap_or("")), escape(&schema), escape(name)));
+ }
+ }
+ content.push_str("<a href=\"/demo\">Back to catalog</a>");
+ Html(content).into_response()
+ }
+ Err(error) => error_fragment(error),
+ }
+}
+
+#[derive(Deserialize)]
+struct CallForm {
+ name: String,
+ arguments: String,
+}
+
+#[tracing::instrument(name = "demo.mcp_call_tool", skip_all, fields(app_id = %app_id, outcome))]
+async fn call(
+ State(state): State<AppState>,
+ Extension(user): Extension<DemoUser>,
+ Path(app_id): Path<String>,
+ Form(form): Form<CallForm>,
+) -> Response {
+ let arguments: Value = match serde_json::from_str(&form.arguments) {
+ Ok(value @ Value::Object(_)) => value,
+ _ => {
+ Span::current().record("outcome", "invalid_arguments");
+ return (
+ StatusCode::BAD_REQUEST,
+ Html("<p class=\"error\">Arguments must be a JSON object.</p>".to_owned()),
+ )
+ .into_response();
+ }
+ };
+ let result = mcp::call_tool(
+ &state.client,
+ &state.http,
+ &user.0,
+ &app_id,
+ &form.name,
+ arguments,
+ )
+ .await;
+ Span::current().record("outcome", if result.is_ok() { "ok" } else { "error" });
+ match result {
+ Ok(value) => {
+ let text = serde_json::to_string_pretty(&expand_text_json(value))
+ .unwrap_or_else(|_| "null".to_owned());
+ let id = path_id(&app_id);
+ Html(format!("<section class=\"panel\"><h2>{}</h2><pre>{}</pre><form class=\"ajax\" method=\"post\" action=\"/demo/apps/{id}/tools\"><button>Back to tools</button></form></section>", escape(&form.name), escape(&text))).into_response()
+ }
+ Err(error) => error_fragment(error),
+ }
+}
+
+/// Parses JSON carried in MCP text content so results read as nested JSON.
+fn expand_text_json(mut value: Value) -> Value {
+ if let Some(content) = value.get_mut("content").and_then(Value::as_array_mut) {
+ for item in content {
+ let parsed = item
+ .get("text")
+ .and_then(Value::as_str)
+ .and_then(|text| serde_json::from_str::<Value>(text).ok())
+ .filter(|parsed| parsed.is_object() || parsed.is_array());
+ if let Some(parsed) = parsed {
+ item["text"] = parsed;
+ }
+ }
+ }
+ value
+}
+
+fn router(state: AppState) -> Router {
+ let browser = Router::new()
+ .route("/demo", get(catalog))
+ .route("/demo/icons/{app_id}", get(icon))
+ .route("/demo/connect/{app_id}", post(connect))
+ .route("/demo/connected", get(connected))
+ .route("/demo/disconnect/{app_id}", post(disconnect))
+ .route("/demo/apps/{app_id}/tools", post(tools))
+ .route("/demo/apps/{app_id}/call", post(call))
+ .layer(middleware::from_fn(cookie));
+ Router::new()
+ .route("/demo/health", get(health))
+ .merge(browser)
+ .with_state(state)
+ .layer(http_trace_layer())
+}
+
+#[tokio::main]
+async fn main() -> Result<(), rootcause::Report> {
+ let source = ConfigLoader::load(&[
+ "CONNECT_BASE_URL",
+ "CONNECT_DEMO_CUSTOMER_KEY",
+ "CONNECT_DEMO_PUBLIC_URL",
+ "PORT",
+ "OTEL_EXPORTER_OTLP_TRACES_ENDPOINT",
+ "OTEL_EXPORTER_OTLP_ENDPOINT",
+ "OTEL_SERVICE_NAME",
+ "RUST_LOG",
+ ])?;
+ let base_url: String = source.required("CONNECT_BASE_URL")?;
+ let customer_key: String = source.required("CONNECT_DEMO_CUSTOMER_KEY")?;
+ let public_url_text: String = source.required("CONNECT_DEMO_PUBLIC_URL")?;
+ let public_url = Url::parse(&public_url_text)?;
+ if !matches!(public_url.scheme(), "http" | "https")
+ || public_url.path() != "/demo"
+ || public_url.query().is_some()
+ || public_url.fragment().is_some()
+ || !public_url.username().is_empty()
+ || public_url.password().is_some()
+ {
+ return Err(rootcause::Report::new(std::io::Error::new(
+ std::io::ErrorKind::InvalidInput,
+ "CONNECT_DEMO_PUBLIC_URL must be an HTTP(S) URL ending in /demo",
+ ))
+ .into_dynamic());
+ }
+ let port: u16 = source.with_default("PORT", 3000)?;
+ let telemetry = Telemetry::init("connect_demo", &source)?;
+ let http = reqwest::Client::builder()
+ .timeout(Duration::from_secs(30))
+ .build()?;
+ let state = AppState {
+ client: Arc::new(ConnectClient::new(&base_url, customer_key)?),
+ http,
+ public_url,
+ };
+ let listener = TcpListener::bind(("0.0.0.0", port)).await?;
+ axum::serve(listener, router(state))
+ .with_graceful_shutdown(async {
+ let _ = tokio::signal::ctrl_c().await;
+ })
+ .await?;
+ telemetry.shutdown()?;
+ Ok(())
+}
diff --git a/connect/services/connect_demo/src/mcp.rs b/connect/services/connect_demo/src/mcp.rs
new file mode 100644
index 0000000000..3daeeca216
--- /dev/null
+++ b/connect/services/connect_demo/src/mcp.rs
@@ -0,0 +1,207 @@
+use connect_client::ConnectClient;
+use connect_platform::inject_trace_headers;
+use futures::StreamExt as _;
+use reqwest::header::{ACCEPT, CONTENT_TYPE, HeaderMap, HeaderValue};
+use serde_json::{Value, json};
+use sse_stream::SseStream;
+use std::collections::HashSet;
+use tracing::Span;
+
+#[derive(Debug, thiserror::Error)]
+pub enum McpError {
+ #[error("gateway request failed: {0}")]
+ Request(#[from] reqwest::Error),
+ #[error("gateway returned HTTP {0}")]
+ Status(reqwest::StatusCode),
+ #[error("gateway response was not valid MCP JSON")]
+ InvalidResponse,
+ #[error("gateway returned an MCP error: {0}")]
+ Protocol(Value),
+}
+
+struct McpSession {
+ id: Option<String>,
+ protocol_version: String,
+}
+
+pub async fn list_tools(
+ client: &ConnectClient,
+ http: &reqwest::Client,
+ user_id: &str,
+ app_id: &str,
+) -> Result<Value, McpError> {
+ let session = initialize(client, http, user_id, app_id).await?;
+ let upstream = client.mcp_upstream(user_id, app_id);
+ send(
+ http,
+ &upstream,
+ Some(&session),
+ json!({"jsonrpc":"2.0","method":"notifications/initialized"}),
+ )
+ .await?;
+ let mut tools = Vec::new();
+ let mut cursor: Option<String> = None;
+ let mut seen = HashSet::new();
+ loop {
+ let params = cursor
+ .as_ref()
+ .map_or_else(|| json!({}), |cursor| json!({"cursor":cursor}));
+ let result = request(
+ http,
+ &upstream,
+ Some(&session),
+ json!({"jsonrpc":"2.0","id":2,"method":"tools/list","params":params}),
+ )
+ .await?;
+ tools.extend(
+ result
+ .get("tools")
+ .and_then(Value::as_array)
+ .ok_or(McpError::InvalidResponse)?
+ .iter()
+ .cloned(),
+ );
+ cursor = result
+ .get("nextCursor")
+ .and_then(Value::as_str)
+ .map(str::to_owned);
+ match &cursor {
+ Some(next) if !seen.insert(next.clone()) => return Err(McpError::InvalidResponse),
+ Some(_) => {}
+ None => return Ok(json!({"tools":tools})),
+ }
+ }
+}
+
+pub async fn call_tool(
+ client: &ConnectClient,
+ http: &reqwest::Client,
+ user_id: &str,
+ app_id: &str,
+ name: &str,
+ arguments: Value,
+) -> Result<Value, McpError> {
+ let session = initialize(client, http, user_id, app_id).await?;
+ let upstream = client.mcp_upstream(user_id, app_id);
+ send(
+ http,
+ &upstream,
+ Some(&session),
+ json!({"jsonrpc":"2.0","method":"notifications/initialized"}),
+ )
+ .await?;
+ request(http, &upstream, Some(&session), json!({"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":name,"arguments":arguments}})).await
+}
+
+async fn initialize(
+ client: &ConnectClient,
+ http: &reqwest::Client,
+ user_id: &str,
+ app_id: &str,
+) -> Result<McpSession, McpError> {
+ let upstream = client.mcp_upstream(user_id, app_id);
+ let (result, session) = send(http, &upstream, None, json!({
+ "jsonrpc":"2.0", "id":1, "method":"initialize",
+ "params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"connect-demo","version":"0.1.0"}}
+ })).await?;
+ let protocol_version = result
+ .as_ref()
+ .and_then(|value| value.get("protocolVersion"))
+ .and_then(Value::as_str)
+ .ok_or(McpError::InvalidResponse)?;
+ Ok(McpSession {
+ id: session,
+ protocol_version: protocol_version.to_owned(),
+ })
+}
+
+async fn request(
+ http: &reqwest::Client,
+ upstream: &connect_client::McpUpstream,
+ session: Option<&McpSession>,
+ payload: Value,
+) -> Result<Value, McpError> {
+ let (response, _) = send(http, upstream, session, payload).await?;
+ response.ok_or(McpError::InvalidResponse)
+}
+
+async fn send(
+ http: &reqwest::Client,
+ upstream: &connect_client::McpUpstream,
+ session: Option<&McpSession>,
+ payload: Value,
+) -> Result<(Option<Value>, Option<String>), McpError> {
+ let mut headers = HeaderMap::new();
+ inject_trace_headers(&mut headers);
+ headers.insert(
+ ACCEPT,
+ HeaderValue::from_static("application/json, text/event-stream"),
+ );
+ headers.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
+ if let Some(session) = session {
+ if let Some(id) = &session.id {
+ headers.insert(
+ "mcp-session-id",
+ HeaderValue::from_str(id).map_err(|_| McpError::InvalidResponse)?,
+ );
+ }
+ headers.insert(
+ "mcp-protocol-version",
+ HeaderValue::from_str(&session.protocol_version)
+ .map_err(|_| McpError::InvalidResponse)?,
+ );
+ }
+ let response = http
+ .post(upstream.url.clone())
+ .headers(headers)
+ .bearer_auth(&upstream.bearer_token)
+ .json(&payload)
+ .send()
+ .await?;
+ if !response.status().is_success() {
+ return Err(McpError::Status(response.status()));
+ }
+ let session = response
+ .headers()
+ .get("mcp-session-id")
+ .and_then(|value| value.to_str().ok())
+ .map(str::to_owned);
+ if response.status() == reqwest::StatusCode::ACCEPTED && payload.get("id").is_none() {
+ return Ok((None, session));
+ }
+ let is_sse = response
+ .headers()
+ .get(CONTENT_TYPE)
+ .and_then(|value| value.to_str().ok())
+ .is_some_and(|value| value.starts_with("text/event-stream"));
+ let value = if is_sse {
+ let mut events = SseStream::from_byte_stream(response.bytes_stream());
+ let mut result = None;
+ while let Some(event) = events.next().await {
+ let event = event.map_err(|_| McpError::InvalidResponse)?;
+ if let Some(data) = event.data
+ && let Ok(value) = serde_json::from_str::<Value>(&data)
+ && value.get("id") == payload.get("id")
+ && (value.get("result").is_some() || value.get("error").is_some())
+ {
+ result = Some(value);
+ break;
+ }
+ }
+ result.ok_or(McpError::InvalidResponse)?
+ } else {
+ let body = response.bytes().await?;
+ if body.is_empty() {
+ return Ok((None, session));
+ }
+ serde_json::from_slice::<Value>(&body).map_err(|_| McpError::InvalidResponse)?
+ };
+ if let Some(error) = value.get("error") {
+ Span::current().record("outcome", "protocol_error");
+ return Err(McpError::Protocol(error.clone()));
+ }
+ Ok((value.get("result").cloned(), session))
+}
+
+#[cfg(test)]
+mod test;
diff --git a/connect/services/connect_demo/src/mcp/test.rs b/connect/services/connect_demo/src/mcp/test.rs
new file mode 100644
index 0000000000..757f79d84b
--- /dev/null
+++ b/connect/services/connect_demo/src/mcp/test.rs
@@ -0,0 +1,37 @@
+use super::*;
+use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
+
+#[tokio::test]
+async fn reads_sse_result_before_stream_closes() {
+ let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
+ let address = listener.local_addr().unwrap();
+ let (release, wait_for_release) = tokio::sync::oneshot::channel::<()>();
+ let server = tokio::spawn(async move {
+ let (mut socket, _) = listener.accept().await.unwrap();
+ let mut request = [0_u8; 1024];
+ socket.read_exact(&mut request[..1]).await.unwrap();
+ let event =
+ "event: message\ndata: {\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[]}}\n\n";
+ socket.write_all(format!("HTTP/1.1 200 OK\r\nContent-Type: text/event-stream\r\nTransfer-Encoding: chunked\r\n\r\n{:x}\r\n{event}\r\n", event.len()).as_bytes()).await.unwrap();
+ wait_for_release.await.unwrap();
+ socket.write_all(b"0\r\n\r\n").await.unwrap();
+ });
+ let client = ConnectClient::new(&format!("http://{address}"), "test-key").unwrap();
+ let upstream = client.mcp_upstream("user", "app");
+ let http = reqwest::Client::new();
+ let result = tokio::time::timeout(
+ std::time::Duration::from_secs(5),
+ request(
+ &http,
+ &upstream,
+ None,
+ json!({"jsonrpc":"2.0","id":2,"method":"tools/list"}),
+ ),
+ )
+ .await
+ .unwrap()
+ .unwrap();
+ assert_eq!(result, json!({"tools":[]}));
+ release.send(()).unwrap();
+ server.await.unwrap();
+}
diff --git a/connect/services/connect_demo/src/style.css b/connect/services/connect_demo/src/style.css
new file mode 100644
index 0000000000..0b9d3c090e
--- /dev/null
+++ b/connect/services/connect_demo/src/style.css
@@ -0,0 +1,16 @@
+:root { color-scheme: light; font-family: system-ui, sans-serif; background: #f7f7f6; color: #242424; }
+body { max-width: 980px; margin: 2rem auto; padding: 0 1rem; }
+h1 { font-size: 2rem; margin-bottom: .3rem; }
+p { line-height: 1.45; }
+.grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); gap: 1rem; }
+.card, .panel { background: white; border: 1px solid #dededb; border-radius: 12px; padding: 1rem; }
+.card h2 { font-size: 1.1rem; margin: 0; }
+.card img { width: 32px; height: 32px; float: right; }
+.badge { font-size: .75rem; color: #555; }
+.actions { display: flex; flex-wrap: wrap; align-items: center; gap: .4rem; margin-top: 1rem; }
+button, a.button { padding: .45rem .7rem; border-radius: 6px; border: 1px solid #777; background: white; color: #242424; font: inherit; cursor: pointer; text-decoration: none; }
+textarea { width: 100%; min-height: 8rem; box-sizing: border-box; font: 14px monospace; }
+pre { overflow: auto; white-space: pre-wrap; overflow-wrap: anywhere; padding: 1rem; background: #f4f4f2; border-radius: 6px; }
+.error { color: #a22; }
+#workspace { margin-top: 1.5rem; }
+#workspace .panel { margin: .75rem 0; }
diff --git a/connect/services/connect_demo/src/test.rs b/connect/services/connect_demo/src/test.rs
new file mode 100644
index 0000000000..82e6924e97
--- /dev/null
+++ b/connect/services/connect_demo/src/test.rs
@@ -0,0 +1,221 @@
+use super::*;
+use axum::{body::Body, http::Request};
+use http_body_util::BodyExt as _;
+use serde_json::json;
+use tower::ServiceExt as _;
+use wiremock::{
+ Mock, MockServer, ResponseTemplate,
+ matchers::{method, path, path_regex},
+};
+
+fn state(server: &MockServer) -> AppState {
+ AppState {
+ client: Arc::new(ConnectClient::new(&server.uri(), "demo-test-key").unwrap()),
+ http: reqwest::Client::new(),
+ public_url: Url::parse("https://demo.test/demo").unwrap(),
+ }
+}
+
+async fn body(response: Response) -> String {
+ let bytes = response.into_body().collect().await.unwrap().to_bytes();
+ String::from_utf8(bytes.to_vec()).unwrap()
+}
+
+#[tokio::test]
+async fn catalog_escapes_vendor_text_and_tracks_cookie_identity() {
+ let server = MockServer::start().await;
+ Mock::given(method("GET")).and(path("/v1/catalog"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!([
+ {"id":"linear","name":"<Linear>","description":"<script>alert(1)</script>","access":["mcp"],"mcp_url":"https://vendor.test/mcp","icon_url":"/v1/catalog/linear/icon.svg"},
+ {"id":"api-app","name":"API app","description":"API access","access":["mcp","api"],"mcp_url":"https://vendor.test/mcp","icon_url":null}
+ ]))).mount(&server).await;
+ Mock::given(method("GET")).and(path("/v1/users/123e4567-e89b-42d3-a456-426614174000/connections"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!([{"appId":"linear","status":"active","scopes":[],"createdAt":"2026-10-30T09:00:00Z"}])))
+ .with_priority(1).mount(&server).await;
+ Mock::given(method("GET"))
+ .and(path_regex("^/v1/users/.*/connections$"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!([])))
+ .mount(&server)
+ .await;
+ let app = router(state(&server));
+ let response = app
+ .clone()
+ .oneshot(Request::builder().uri("/demo").body(Body::empty()).unwrap())
+ .await
+ .unwrap();
+ let cookie = response
+ .headers()
+ .get(header::SET_COOKIE)
+ .unwrap()
+ .to_str()
+ .unwrap();
+ assert!(cookie.contains("Secure; HttpOnly; SameSite=Lax"));
+ assert!(Uuid::parse_str(cookie.split('=').nth(1).unwrap().split(';').next().unwrap()).is_ok());
+ let html = body(response).await;
+ assert!(html.contains("&lt;Linear&gt;"));
+ assert!(html.contains("&lt;script&gt;alert(1)&lt;&#x2F;script&gt;"));
+ assert!(!html.contains("<script>alert(1)</script>"));
+ assert!(html.contains("MCP + API"));
+ assert!(html.contains("/demo/icons/linear"));
+ assert!(html.contains("id=\"workspace\""));
+ assert!(html.contains("fetch(form.action"));
+ let response = app
+ .clone()
+ .oneshot(
+ Request::builder()
+ .uri("/demo")
+ .header(
+ header::COOKIE,
+ "connect_demo_user=123e4567-e89b-42d3-a456-426614174000",
+ )
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert!(response.headers().get(header::SET_COOKIE).is_none());
+ let html = body(response).await;
+ assert!(html.contains("Connected"));
+ assert!(html.contains("Disconnect"));
+ assert!(html.contains("Try it"));
+ assert!(html.contains("class=\"ajax\""));
+ assert!(html.contains("/demo/connect/api-app"));
+}
+
+#[tokio::test]
+async fn connect_redirect_uses_same_demo_user_and_callback() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST")).and(path("/v1/connect-sessions"))
+ .respond_with(ResponseTemplate::new(200).set_body_json(json!({"connect_url":"https://connect.test/authorize","expires_at":"2026-10-30T10:00:00Z"})))
+ .mount(&server).await;
+ let response = router(state(&server))
+ .oneshot(
+ Request::builder()
+ .method("POST")
+ .uri("/demo/connect/linear")
+ .header(
+ header::COOKIE,
+ "connect_demo_user=123e4567-e89b-42d3-a456-426614174000",
+ )
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(response.status(), StatusCode::SEE_OTHER);
+ assert_eq!(
+ response.headers().get(header::LOCATION).unwrap(),
+ "https://connect.test/authorize"
+ );
+ let requests = server.received_requests().await.unwrap();
+ let payload: Value = serde_json::from_slice(&requests[0].body).unwrap();
+ assert_eq!(
+ payload["external_user_id"],
+ "123e4567-e89b-42d3-a456-426614174000"
+ );
+ assert_eq!(
+ payload["redirect_url"],
+ "https://demo.test/demo/connected?app=linear"
+ );
+}
+
+#[tokio::test]
+async fn callback_page_escapes_vendor_error() {
+ let server = MockServer::start().await;
+ let response = router(state(&server))
+ .oneshot(
+ Request::builder()
+ .uri("/demo/connected?app=linear&status=error&reason=%3Cscript%3E")
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ let html = body(response).await;
+ assert!(html.contains("Could not connect linear"));
+ assert!(html.contains("Could not connect linear: &lt;script&gt;</p>"));
+}
+
+#[tokio::test]
+async fn mcp_handlers_initialize_and_forward_session_for_sse_list_and_call() {
+ let server = MockServer::start().await;
+ Mock::given(method("POST")).and(path("/v1/users/123e4567-e89b-42d3-a456-426614174000/mcp/linear"))
+ .respond_with(|request: &wiremock::Request| {
+ let body: Value = serde_json::from_slice(&request.body).unwrap();
+ match body["method"].as_str().unwrap() {
+ "initialize" => ResponseTemplate::new(200).insert_header("content-type", "text/event-stream").insert_header("mcp-session-id", "session-123").set_body_raw("event: message\ndata: {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"protocolVersion\":\"2025-06-18\"}}\n\n", "text/event-stream"),
+ "notifications/initialized" => ResponseTemplate::new(202),
+ "tools/list" => ResponseTemplate::new(200).set_body_json(json!({"jsonrpc":"2.0","id":2,"result":{"tools":[{"name":"find","description":"Find <items>"}]}})),
+ "tools/call" => ResponseTemplate::new(200).set_body_json(json!({"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"<secret>"}]}})),
+ _ => ResponseTemplate::new(400),
+ }
+ }).mount(&server).await;
+ let app = router(state(&server));
+ let cookie = "connect_demo_user=123e4567-e89b-42d3-a456-426614174000";
+ let response = app
+ .clone()
+ .oneshot(
+ Request::builder()
+ .method("POST")
+ .uri("/demo/apps/linear/tools")
+ .header(header::COOKIE, cookie)
+ .body(Body::empty())
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(response.status(), StatusCode::OK);
+ let html = body(response).await;
+ assert!(html.contains("Find &lt;items&gt;"));
+ assert!(html.contains("name=\"arguments\""));
+ let response = app
+ .oneshot(
+ Request::builder()
+ .method("POST")
+ .uri("/demo/apps/linear/call")
+ .header(header::COOKIE, cookie)
+ .header(header::CONTENT_TYPE, "application/x-www-form-urlencoded")
+ .body(Body::from(
+ "name=find&arguments=%7B%22query%22%3A%22hello%22%7D",
+ ))
+ .unwrap(),
+ )
+ .await
+ .unwrap();
+ assert_eq!(response.status(), StatusCode::OK);
+ let html = body(response).await;
+ assert!(html.contains("&lt;secret&gt;"));
+ assert!(!html.contains("<secret>"));
+ let requests = server.received_requests().await.unwrap();
+ assert_eq!(requests.len(), 6);
+ for request in requests.iter().filter(|request| {
+ !request
+ .body
+ .windows(10)
+ .any(|window| window == b"initialize")
+ }) {
+ assert_eq!(
+ request.headers.get("mcp-session-id").unwrap(),
+ "session-123"
+ );
+ assert_eq!(
+ request.headers.get("mcp-protocol-version").unwrap(),
+ "2025-06-18"
+ );
+ }
+ let call: Value = serde_json::from_slice(&requests[5].body).unwrap();
+ assert_eq!(call["params"]["arguments"]["query"], "hello");
+}
+
+#[test]
+fn tool_results_expand_json_text_only() {
+ let value = json!({"content": [
+ {"type": "text", "text": "{\"teams\":[{\"key\":\"MAC\"}]}"},
+ {"type": "text", "text": "plain words"},
+ {"type": "text", "text": "42"}
+ ]});
+ let expanded = expand_text_json(value);
+ assert_eq!(expanded["content"][0]["text"]["teams"][0]["key"], "MAC");
+ assert_eq!(expanded["content"][1]["text"], "plain words");
+ assert_eq!(expanded["content"][2]["text"], "42");
+}
diff --git a/connect/submissions/asana.md b/connect/submissions/asana.md
index 40476a32a4..0e587f10e0 100644
--- a/connect/submissions/asana.md
+++ b/connect/submissions/asana.md
@@ -8,7 +8,7 @@ submitted:
last_contact:
next_action: Human confirms whether Macro already has an MCP app
next_action_owner: human
-due:
+due: 2026-11-09
---
## Requirements
diff --git a/connect/submissions/hubspot.md b/connect/submissions/hubspot.md
index 5f0cc9e99a..8a12998a6b 100644
--- a/connect/submissions/hubspot.md
+++ b/connect/submissions/hubspot.md
@@ -8,7 +8,7 @@ submitted:
last_contact:
next_action: Human confirms whether Macro already has an MCP auth app
next_action_owner: human
-due:
+due: 2026-11-09
---
## Requirements
diff --git a/connect/tasks/T019-demo-app.md b/connect/tasks/T019-demo-app.md
new file mode 100644
index 0000000000..579379c809
--- /dev/null
+++ b/connect/tasks/T019-demo-app.md
@@ -0,0 +1,142 @@
+# T019: Demo customer app at `connect-dev.macro.com/demo`
+
+Base: `eric/macro-connect` (PR #9231). Branch for review: `eric/macro-connect-demo`.
+
+## Goal
+
+A person opens `https://connect-dev.macro.com/demo`, sees Connect's catalog,
+connects an app through a real vendor consent, and runs that vendor's MCP
+tools through Connect's gateway, all from one page. The demo is a separate
+customer of Connect: it talks to Connect only through `connect_client` with
+its own customer key, exactly as Macro will.
+
+## Context
+
+- `connect/crates/connect_client` (public client, `mcp_upstream`),
+ `connect/services/connect_api` (routes, `create-customer` CLI),
+ `connect/infra/index.ts` (ALB, listeners, ECS service, Secrets Manager
+ runtime JSON), `connect/docs/runbooks/bootstrap.md`.
+- The dev stack is deployed by the planner; do not run `pulumi` against AWS.
+
+## Do
+
+1. **Service** `connect/services/connect_demo` (package `connect_demo`, axum,
+ depends only on `connect_client`, `connect_platform`, and ordinary crates;
+ the boundary rules apply). Config through `connect_platform`:
+ `CONNECT_BASE_URL`, `CONNECT_DEMO_CUSTOMER_KEY`, `CONNECT_DEMO_PUBLIC_URL`
+ (e.g. `https://connect-dev.macro.com/demo`). Everything under `/demo`;
+ `/demo/health` for the target group.
+ - Each browser gets an opaque random demo user id in a `Secure`,
+ `HttpOnly`, `SameSite=Lax` cookie; it is the `external_user_id`.
+ - `GET /demo`: one server-rendered HTML page (no frontend build; small
+ inline CSS and vanilla JS are fine). Shows every catalog entry with icon,
+ name, description, `MCP` / `MCP + API` label, and per app either
+ **Connect** or **Connected** with **Disconnect** and **Try it**.
+ - `POST /demo/connect/{app_id}`: creates a connect session with redirect
+ `<public>/demo/connected?app=<id>` and 303s to `connect_url`.
+ `GET /demo/connected` shows success or the error Connect returned, then
+ links back.
+ - `POST /demo/apps/{app_id}/tools` lists the app's MCP tools through
+ Connect's gateway (MCP `initialize`, `notifications/initialized`,
+ `tools/list`, honoring `Mcp-Session-Id`, JSON or SSE responses).
+ `POST /demo/apps/{app_id}/call` runs one tool with JSON arguments typed
+ by the user and shows the result. Render results as escaped,
+ pretty-printed JSON.
+ - Never expose the customer key or vendor tokens to the browser; never
+ call `access_token`.
+ - Span the MCP calls (`demo.mcp_list_tools`, `demo.mcp_call_tool`) with
+ `app_id` and outcome; no tool arguments or results in spans.
+ - Dockerfile like `connect_api`'s.
+2. **Infra** in `connect/infra/index.ts`: an ECR image for `connect_demo`, its
+ own task definition and ECS service (1 task) on the existing cluster, its
+ own security group reachable only from the ALB, a target group with health
+ check `/demo/health`, and an HTTPS listener rule sending `/demo` and
+ `/demo/*` to it. Its runtime JSON (`CONNECT_BASE_URL`,
+ `CONNECT_DEMO_PUBLIC_URL`, `CONNECT_DEMO_CUSTOMER_KEY`) lives in its own
+ Secrets Manager secret. The key comes from encrypted Pulumi config
+ `demoCustomerKey`; when it is unset, create none of the demo resources so
+ the stack still deploys.
+3. **Local**: add `connect_demo` to `connect/docker-compose.yml` (port
+ `CONNECT_DEMO_PORT`, default 3000, public URL `http://localhost:3000/demo`),
+ reading the key from `CONNECT_DEMO_CUSTOMER_KEY` in the environment.
+4. **Tests**: handler tests against a fake Connect (wiremock or an in-process
+ axum stub) covering the page rendering (labels, connected state, HTML
+ escaping of vendor-supplied text), the connect redirect, the cookie, and
+ the MCP list/call flow including an SSE response and a session id.
+5. **Docs**: `connect/services/connect_demo/AGENTS.md` (+ `CLAUDE.md`
+ symlink); a "Demo" section in `bootstrap.md` (create the demo customer
+ with redirect origin `https://connect-dev.macro.com`, set
+ `demoCustomerKey`, deploy); `connect/AGENTS.md` map.
+
+## Done when
+
+- Compose runs Connect and the demo; `http://localhost:3000/demo` lists the
+ live apps and **Connect** for Linear 303s to Connect and then to
+ `mcp.linear.app`'s authorize endpoint (paste the `Location` hosts).
+- `cargo nextest run --all-features -p connect_demo -p connect_client -p connect_api`,
+ clippy (`-D warnings`) for those, `cargo x deps --check`, `just check`, and
+ in `connect/infra`: `bunx tsc --noEmit`, `bunx biome check .` pass.
+- Nothing outside `connect/` changes except workspace membership and
+ generated Cargo artifacts.
+
+## Out of scope
+
+Real vendor consent (the planner does it in the browser); deploying; a
+frontend build; user accounts beyond the cookie.
+
+## Result
+
+### Changed
+
+- `connect/services/connect_demo/{Cargo.toml,Dockerfile,AGENTS.md,CLAUDE.md,src/main.rs,src/mcp.rs,src/mcp/test.rs,src/test.rs,src/style.css,src/app.js}`: standalone server-rendered demo with a browser identity cookie, catalog and connection controls, JSON and SSE MCP tool flows, escaped results, tracing spans, and handler tests. The JavaScript ignores stale asynchronous responses.
+- `connect/crates/connect_client/{AGENTS.md,src/lib.rs,src/test.rs}`: expose catalog icons through the public client and cover the route.
+- `connect/infra/{index.ts,AGENTS.md}`: optional demo image, secret, task, service, security group, target group, and HTTPS listener rule, all gated on encrypted `demoCustomerKey` config.
+- `connect/{docker-compose.yml,AGENTS.md}` and `connect/docs/runbooks/bootstrap.md`: local demo service and documented local and dev bootstrap. The agent maps now include the demo.
+- `Cargo.toml`, `Cargo.lock`, and `.github/workspace-dep-closures.json`: workspace membership and generated dependency artifacts.
+- `connect/tasks/T019-demo-app.md`: this handoff result. `connect/STATUS.md` was not changed.
+
+### Checks
+
+All Rust and repository tooling ran inside `nix develop --command` with `CARGO_TARGET_DIR="$CONNECT_CARGO_TARGET_DIR"` and `DATABASE_URL="$CONNECT_DATABASE_URL"` exported. No AWS Pulumi command, deployment, production access, or vendor consent was run.
+
+| Check | Exact outcome |
+| --- | --- |
+| `just hakari` | Passed; regenerated workspace dependency closure. |
+| `cargo nextest run --all-features -p connect_demo -p connect_client -p connect_api` | Passed; 31 tests, 0 skipped. |
+| `cargo clippy -p connect_demo -p connect_client -p connect_api --all-features --all-targets -- -D warnings` | Passed, exit 0. |
+| `cargo x deps --check` | Passed, exit 0. |
+| `just check` | Passed; format, ast-grep, PII scan, and 12 PII scanner tests. |
+| `bun install --frozen-lockfile` in `connect/infra` | Passed; lockfile unchanged. |
+| `bunx tsc --noEmit` in `connect/infra` | Passed, exit 0. |
+| `bunx biome check .` in `connect/infra` | Passed; 4 files checked, no fixes. |
+| `docker compose -f connect/docker-compose.yml config --quiet` | Passed, exit 0. |
+| Compose build and run | Passed; API and demo images built and both services started. Host port 8080 was occupied, so the API used `CONNECT_PORT=18673`; demo used port 3000. |
+| Live HTTP and redirect chain | API `/health` 200; demo `/demo/health` 200; `/demo` 200 with Linear and Connect; `POST /demo/connect/linear` 303 with `Location` host `localhost`; Connect authorization 303 with `Location` host `mcp.linear.app`. |
+| Browser rendering | Passed in headless Chromium at desktop and 390 px mobile widths; catalog, icons, controls, and one-column mobile layout were visually checked. |
+| Audit skill | Passed; no remaining concrete code regression or out-of-scope change found. |
+| `git diff --check` | Passed, exit 0. |
+| Runtime trace export | Not verified; no local trace exporter was configured. Span names and attributes were reviewed in code. |
+
+### Open questions
+
+None.
+
+### Proposed commits
+
+1. `feat(connect-demo): add catalog and MCP customer app`
+
+ Why: A standalone customer app is needed to exercise the public catalog, connection flow, and MCP gateway.
+
+ What: Add the demo service, client icon method, tests, workspace membership, and generated Cargo artifacts.
+
+2. `feat(connect-infra): route optional demo service`
+
+ Why: The demo needs isolated runtime configuration and a route on the existing HTTPS listener.
+
+ What: Add optional infrastructure resources and the local Compose service.
+
+3. `docs(connect): document demo bootstrap`
+
+ Why: The setup steps and repository map must describe the new service.
+
+ What: Update the bootstrap runbook and agent guides, and record the task result.
diff --git a/connect/tooling/browser/cdp.ts b/connect/tooling/browser/cdp.ts
new file mode 100644
index 0000000000..86c7851b4a
--- /dev/null
+++ b/connect/tooling/browser/cdp.ts
@@ -0,0 +1,195 @@
+// Drive Connect's dedicated browser (tooling/browser/run.sh) over raw CDP.
+// Usage (bun, inside `nix develop`):
+// bun connect/tooling/browser/cdp.ts <command> [args]
+// Commands act on the first page tab unless CDP_TARGET names a URL substring:
+// tabs list page tabs
+// open <url> navigate and wait for load
+// url print the current URL
+// eval <js> evaluate an expression, print the JSON result
+// text [selector] print visible text (default: body)
+// click <selector|text=...> click an element's centre
+// type <text> insert text into the focused element
+// key <Enter|Tab|...> press one key
+// shot <path.png> save a screenshot
+// wait <js> [seconds] poll until the expression is truthy
+// Never pass secrets as arguments; pipe them: `printf %s "$X" | cdp.ts type -`.
+
+const endpoint = process.env.CDP_URL ?? 'http://localhost:9333';
+
+type Tab = {
+ id: string;
+ type: string;
+ url: string;
+ webSocketDebuggerUrl: string;
+};
+
+async function pageTab(): Promise<Tab> {
+ const tabs = (await (await fetch(`${endpoint}/json/list`)).json()) as Tab[];
+ const pages = tabs.filter((t) => t.type === 'page');
+ const want = process.env.CDP_TARGET;
+ const tab = want ? pages.find((t) => t.url.includes(want)) : pages[0];
+ if (!tab) throw new Error('no matching page tab');
+ return tab;
+}
+
+function connect(tab: Tab) {
+ const ws = new WebSocket(tab.webSocketDebuggerUrl);
+ let next = 0;
+ const pending = new Map<
+ number,
+ (m: { result?: unknown; error?: unknown }) => void
+ >();
+ const events: ((m: { method: string }) => void)[] = [];
+ ws.onmessage = (e) => {
+ const m = JSON.parse(String(e.data));
+ if (m.id !== undefined) pending.get(m.id)?.(m);
+ else for (const f of events) f(m);
+ };
+ const ready = new Promise<void>((r) => {
+ ws.onopen = () => r();
+ });
+ // biome-ignore lint/suspicious/noExplicitAny: CDP results are untyped JSON.
+ const send = async (method: string, params: object = {}): Promise<any> => {
+ await ready;
+ const id = ++next;
+ ws.send(JSON.stringify({ id, method, params }));
+ const m = await new Promise<{ result?: unknown; error?: unknown }>((r) =>
+ pending.set(id, r),
+ );
+ if (m.error) throw new Error(`${method}: ${JSON.stringify(m.error)}`);
+ return m.result;
+ };
+ return { send, events, close: () => ws.close() };
+}
+
+async function evaluate(
+ // biome-ignore lint/suspicious/noExplicitAny: CDP results are untyped JSON.
+ send: (m: string, p?: object) => Promise<any>,
+ expression: string,
+) {
+ const r = await send('Runtime.evaluate', {
+ expression,
+ returnByValue: true,
+ awaitPromise: true,
+ });
+ if (r.exceptionDetails)
+ throw new Error(r.exceptionDetails.exception?.description ?? 'eval failed');
+ return r.result.value;
+}
+
+const locate = (sel: string) => `(() => {
+ const s = ${JSON.stringify(sel)};
+ let el;
+ if (s.startsWith('text=')) {
+ // Prefer an exactly matching control, then the control around matching text.
+ const want = s.slice(5).trim().toLowerCase();
+ const visible = (e) => e.offsetParent !== null;
+ const label = (e) => e.innerText.trim().toLowerCase();
+ const controls = [...document.querySelectorAll('button,a,[role=button],[role=link],[role=option],input[type=submit],label')].filter(visible);
+ el = controls.find((e) => label(e) === want) ?? controls.find((e) => label(e).includes(want));
+ if (!el) {
+ const leaf = [...document.querySelectorAll('body *')].filter(visible).filter((e) => label(e) === want).pop();
+ el = leaf?.closest('button,a,[role=button],[role=link],li') ?? leaf;
+ }
+ } else el = document.querySelector(s);
+ if (!el) return null;
+ el.scrollIntoView({ block: 'center' });
+ const r = el.getBoundingClientRect();
+ return { x: r.x + r.width / 2, y: r.y + r.height / 2 };
+})()`;
+
+async function readArg(arg: string | undefined) {
+ if (arg === '-') return (await Bun.stdin.text()).replace(/\n$/, '');
+ return arg ?? '';
+}
+
+const [cmd, ...args] = process.argv.slice(2);
+const tab = await pageTab();
+if (cmd === 'tabs') {
+ const tabs = (await (await fetch(`${endpoint}/json/list`)).json()) as Tab[];
+ for (const t of tabs.filter((t) => t.type === 'page')) console.log(t.url);
+ process.exit(0);
+}
+const { send, events, close } = connect(tab);
+try {
+ switch (cmd) {
+ case 'open': {
+ await send('Page.enable');
+ const loaded = new Promise<void>((r) =>
+ events.push((m) => m.method === 'Page.loadEventFired' && r()),
+ );
+ await send('Page.navigate', { url: args[0] });
+ await Promise.race([loaded, Bun.sleep(30_000)]);
+ console.log(await evaluate(send, 'location.href'));
+ break;
+ }
+ case 'url':
+ console.log(await evaluate(send, 'location.href'));
+ break;
+ case 'eval':
+ console.log(
+ JSON.stringify(await evaluate(send, await readArg(args[0])), null, 2),
+ );
+ break;
+ case 'text':
+ console.log(
+ await evaluate(
+ send,
+ `document.querySelector(${JSON.stringify(args[0] ?? 'body')})?.innerText ?? ''`,
+ ),
+ );
+ break;
+ case 'click': {
+ const p = await evaluate(send, locate(args.join(' ')));
+ if (!p) throw new Error(`not found: ${args.join(' ')}`);
+ for (const type of ['mousePressed', 'mouseReleased'])
+ await send('Input.dispatchMouseEvent', {
+ type,
+ x: p.x,
+ y: p.y,
+ button: 'left',
+ clickCount: 1,
+ });
+ break;
+ }
+ case 'type':
+ await send('Input.insertText', { text: await readArg(args[0]) });
+ break;
+ case 'key': {
+ const key = args[0];
+ const codes: Record<string, number> = {
+ Enter: 13,
+ Tab: 9,
+ Escape: 27,
+ Backspace: 8,
+ };
+ const base = { key, code: key, windowsVirtualKeyCode: codes[key] ?? 0 };
+ await send('Input.dispatchKeyEvent', {
+ type: 'keyDown',
+ ...base,
+ ...(key === 'Enter' ? { text: '\r' } : {}),
+ });
+ await send('Input.dispatchKeyEvent', { type: 'keyUp', ...base });
+ break;
+ }
+ case 'shot': {
+ const r = await send('Page.captureScreenshot', { format: 'png' });
+ await Bun.write(args[0], Buffer.from(r.data, 'base64'));
+ console.log(args[0]);
+ break;
+ }
+ case 'wait': {
+ const deadline = Date.now() + Number(args[1] ?? 30) * 1000;
+ while (!(await evaluate(send, args[0]).catch(() => false))) {
+ if (Date.now() > deadline)
+ throw new Error(`timed out waiting for ${args[0]}`);
+ await Bun.sleep(500);
+ }
+ break;
+ }
+ default:
+ throw new Error(`unknown command ${cmd}`);
+ }
+} finally {
+ close();
+}
diff --git a/connect/tooling/browser/entrypoint.sh b/connect/tooling/browser/entrypoint.sh
index 5b5a04630a..07922f516a 100755
--- a/connect/tooling/browser/entrypoint.sh
+++ b/connect/tooling/browser/entrypoint.sh
@@ -44,6 +44,5 @@ exec chromium \
--window-size="${WIDTH},${HEIGHT}" \
--window-position=0,0 \
--remote-debugging-port=9333 \
- --remote-allow-origins='*' \
--user-data-dir=/data/chrome-profile \
about:blank
diff --git a/rules/ast-grep/ts-connect-public-sdk.yml b/rules/ast-grep/ts-connect-public-sdk.yml
index c2e388932b..497514e6cb 100644
--- a/rules/ast-grep/ts-connect-public-sdk.yml
+++ b/rules/ast-grep/ts-connect-public-sdk.yml
@@ -9,6 +9,7 @@ note: |-
files:
- apps/**
- packages/**
+ - services/**
rule:
kind: string
all:
diff --git a/rules/ast-grep/tsx-connect-public-sdk.yml b/rules/ast-grep/tsx-connect-public-sdk.yml
index 71b09859ad..1a8aaf992a 100644
--- a/rules/ast-grep/tsx-connect-public-sdk.yml
+++ b/rules/ast-grep/tsx-connect-public-sdk.yml
@@ -9,6 +9,7 @@ note: |-
files:
- apps/**
- packages/**
+ - services/**
rule:
kind: string
all: