Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 4 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,8 +129,10 @@ errors and cannot recover previously discarded validation details.

Provisioning accepts optional `subtext_api_url`, stored on the account that owns the
single connected QA project. Authentication, session callbacks, and dashboard
reviews use that endpoint. Only the US, EU, and staging Fullstory MCP endpoints
are accepted, preventing the public provisioning route from fetching arbitrary URLs.
reviews use that endpoint. HTTPS endpoints on `*.fullstory.com` with the exact `/mcp/subtext` path
are accepted. Credentials, custom ports, query strings, and fragments are rejected.
Session ingestion likewise accepts HTTPS session URLs on `*.fullstory.com`, so new
Fullstory environments do not need per-host allowlist updates in either service.
There is no global override or automatic endpoint probing. The `na1.` key prefix
does not establish whether a key is for production or staging.

Expand Down
2 changes: 1 addition & 1 deletion public/api/v1/skills/setup-self-healing/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ POST `/api/v1/accounts` (`provisionAccount`) with `Content-Type: application/jso
{"subtext_api_key":"<Subtext key>"}
```

For a project using EU or staging, include `subtext_api_url` in that body with the matching full MCP endpoint: `https://api.eu1.fullstory.com/mcp/subtext` or `https://api.staging.fullstory.com/mcp/subtext`. For example, staging provisioning uses:
Subtext endpoints accept HTTPS URLs on `*.fullstory.com` with the exact `/mcp/subtext` path; new Fullstory regions and environments do not require an allowlist update. For a project using EU or staging, include `subtext_api_url` in that body with the matching full MCP endpoint: `https://api.eu1.fullstory.com/mcp/subtext` or `https://api.staging.fullstory.com/mcp/subtext`. For example, staging provisioning uses:

```json
{"subtext_api_key":"<Subtext key>","subtext_api_url":"https://api.staging.fullstory.com/mcp/subtext"}
Expand Down
2 changes: 1 addition & 1 deletion src/api/contracts.ts
Original file line number Diff line number Diff line change
Expand Up @@ -949,7 +949,7 @@ export const operations: Operation[] = [
implemented: true,
summary: "Provision an account with a dedicated QA identity",
description:
"Validate a Subtext key and return a Self Healing API key. Optionally select a US, EU, or staging Subtext MCP endpoint for this account and its connected project. Defaults to US production. Repeat with the same Subtext key and endpoint to recover the same account and API key. All subsequent requests use the returned API key.",
"Validate a Subtext key and return a Self Healing API key. Optionally select an HTTPS Subtext MCP endpoint on *.fullstory.com with path /mcp/subtext for this account and its connected project. Defaults to US production. Repeat with the same Subtext key and endpoint to recover the same account and API key. All subsequent requests use the returned API key.",
body: z
.object({
subtext_api_key: z.string().min(1).max(4096).regex(/^\S+$/),
Expand Down
2 changes: 1 addition & 1 deletion src/api/sessions.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ export function normalizeSessionUrl(raw: string) {
const url = new URL(raw);
if (
url.protocol !== "https:" ||
!["app.fullstory.com", "app.eu1.fullstory.com"].includes(url.hostname) ||
!url.hostname.endsWith(".fullstory.com") ||
url.username ||
url.password ||
!/(?:client-session|session|trace)\//.test(url.pathname)
Expand Down
12 changes: 7 additions & 5 deletions src/api/subtext-endpoint.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,13 @@ import { z } from "zod";

export const defaultSubtextEndpoint = "https://api.fullstory.com/mcp/subtext";
// Provisioning is public: restrict credential-bearing requests to provider endpoints.
export const SubtextApiUrl = z.enum([
defaultSubtextEndpoint,
"https://api.eu1.fullstory.com/mcp/subtext",
"https://api.staging.fullstory.com/mcp/subtext",
]);
export const SubtextApiUrl = z
.string()
.url()
.regex(
/^https:\/\/(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+fullstory\.com\/mcp\/subtext$/i,
"Use an HTTPS Fullstory subdomain with the /mcp/subtext path.",
);
export function subtextEndpoint(endpoint = defaultSubtextEndpoint): string {
return SubtextApiUrl.parse(endpoint);
}
59 changes: 57 additions & 2 deletions tests/connections.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -288,7 +288,10 @@ test("previously sealed sessions accept new captures without installer intervent
await f.db.close();
}
});
async function checkCallbackEndpoint(endpoint?: string) {
async function checkCallbackEndpoint(
endpoint?: string,
sessionUrl = "https://app.fullstory.com/ui/org/session/1",
) {
const f = await fixture(endpoint);
try {
await f.service.connect(f.account, "customer-key", settings);
Expand Down Expand Up @@ -483,7 +486,10 @@ async function checkCallbackEndpoint(endpoint?: string) {
test("callback enforces session and MCP-client scope at the default endpoint", () =>
checkCallbackEndpoint());
test("callback uses the saved staging endpoint with the same session isolation", () =>
checkCallbackEndpoint("https://api.staging.fullstory.com/mcp/subtext"));
checkCallbackEndpoint(
"https://api.staging.fullstory.com/mcp/subtext",
"https://app.staging.fullstory.com/ui/org/session/123:456",
));
test("connection responses hide internal credentials and QA transport uses existing API paths", async () => {
const f = await fixture();
try {
Expand Down Expand Up @@ -943,3 +949,52 @@ test("callback failures return JSON with upstream status and bounded, redacted d
await f.db.close();
}
});

test("Fullstory wildcard hosts are forwarded and retries deduplicated", async () => {
const f = await fixture("https://api.staging.fullstory.com/mcp/subtext");
try {
await f.service.connect(f.account, "customer-key", settings);
for (const [host, kind] of [
["app.staging.fullstory.com", "session"],
["app.future-region.fullstory.com", "client-session"],
["replay.internal.preview.fullstory.com", "trace"],
]) {
const url = `https://${host}/ui/org/${kind}/123:456`;
const input = { session_url: url + "#at=1000" };
const first = await f.service.action(f.account, "session", input);
assert.equal(first.status, "stored");
assert.deepEqual(
await f.service.action(f.account, "session", input),
first,
);
const upload = f.calls
.filter((c) => c.path === "/api/project-session/register")
.at(-1)!.body as { session_url: string; auxiliary_data: unknown[] };
assert.equal(upload.session_url, url);
assert.deepEqual(upload.auxiliary_data, []);
}
assert.equal(
f.calls.filter((c) => c.path === "/api/project-session/register").length,
3,
);
for (const url of [
"https://notfullstory.com/ui/org/session/1",
"https://fullstory.com/ui/org/session/1",
"http://app.staging.fullstory.com/ui/org/session/1",
"https://app.staging.fullstory.com.evil.example/ui/org/session/1",
"https://user:password@app.staging.fullstory.com/ui/org/session/1",
"https://app.staging.fullstory.com/ui/org/settings",
]) {
await assert.rejects(
f.service.action(f.account, "session", { session_url: url }),
{ status: 400, code: "invalid_session" },
);
}
assert.equal(
f.calls.filter((c) => c.path === "/api/project-session/register").length,
3,
);
} finally {
await f.db.close();
}
});
15 changes: 13 additions & 2 deletions tests/subtext-endpoint.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,14 @@ import test from "node:test";
import assert from "node:assert/strict";
import { subtextEndpoint } from "../src/api/subtext-endpoint.ts";

test("Subtext defaults to production and accepts explicit EU and staging endpoints", () => {
test("Subtext defaults to production and accepts Fullstory subdomains without an environment allowlist", () => {
assert.equal(subtextEndpoint(), "https://api.fullstory.com/mcp/subtext");
for (const host of ["api.eu1.fullstory.com", "api.staging.fullstory.com"])
for (const host of [
"api.eu1.fullstory.com",
"api.staging.fullstory.com",
"api.future-region.fullstory.com",
"subtext.internal.preview.fullstory.com",
])
assert.equal(
subtextEndpoint(`https://${host}/mcp/subtext`),
`https://${host}/mcp/subtext`,
Expand All @@ -16,6 +21,12 @@ test("public provisioning cannot direct credentials to arbitrary URLs", () => {
"https://127.0.0.1/mcp/subtext",
"https://api.fullstory.com.attacker.example/mcp/subtext",
"https://api.fullstory.com/me",
"https://fullstory.com/mcp/subtext",
"https://notfullstory.com/mcp/subtext",
"https://user:password@api.fullstory.com/mcp/subtext",
"https://api.fullstory.com:8443/mcp/subtext",
"https://api.fullstory.com/mcp/subtext?redirect=elsewhere",
"https://api.fullstory.com/mcp/subtext#fragment",
])
assert.throws(() => subtextEndpoint(url));
});
Loading