From 475e23fdab074e82b12248bb34ce2fa8772e7867 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 10 Nov 2026 19:05:46 +0000 Subject: [PATCH 1/2] fix: hold Connect until the preview answers, and stop calling every refusal expired - Map the preview the way redeem is mapped: only a 400 is an invalid link. A 401, 403 or 404 (the API key, or an agent it doesn't own or that is gone), a 5xx, a network failure or a malformed answer is "unreachable", so the person isn't sent for a new link that fails the same way - Return why there is nothing to show (`PreviewResult`) instead of null, and have `handlePreviewRequest` answer 400 or 502 to match - Offer no Connect button until the preview has named the account, and none when it fails. Before, the button showed straight away against "Slack, Teams, or Copilot", which is the case `preview` exists to stop - Write Teams and Copilot names without an "@"; only Slack shows people as "@name" - Take the `?platform=` Agenta sends as an optional prop, for naming the app before the preview has answered, as AGENTS.md already describes - Document that only redeem reports a used link: a spent link still previews until it expires Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_013TYQ7D3Pk6WDSYuhCUvtGN --- AGENTS.md | 3 ++ README.md | 25 ++++++++---- src/connect-page.tsx | 80 ++++++++++++++++++++++++++------------ src/connect.ts | 58 +++++++++++++++++++++------ tests/connect-page.test.ts | 42 ++++++++++++++++++++ tests/connect.test.ts | 79 ++++++++++++++++++++++++++++++------- 6 files changed, 230 insertions(+), 57 deletions(-) create mode 100644 tests/connect-page.test.ts diff --git a/AGENTS.md b/AGENTS.md index 62a471d..626a39f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -49,6 +49,9 @@ restyle: - The five states, and the wording that sends people back to the chat app. A person on this page came from Slack or Teams and needs to be told to go back +- No Connect button until the preview has named the chat account, including + when the preview fails. That name is the only check a person can make against + a link somebody else sent them - The `noindex,nofollow` and `no-referrer` meta tags. The URL carries a token - Sign-in starting on arrival rather than behind a second click diff --git a/README.md b/README.md index a6cfdfb..345f4c7 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ makes it run as each of your customers instead. as `?token=`, and the app they came from as `?platform=` 3. Your page signs the visitor in the way your product already does 4. Your backend asks `POST /api/v1/customer-links/preview` who the token names, - and your page shows it next to who they are signed in as + and your page shows it next to who they are signed in as. Only then does it + offer Connect 5. Your backend `POST`s the token and your own identifier for that user to `POST /api/v1/customer-links`, with your Agenta API key 6. Agenta stores the link. It is durable — only the token was short-lived — and @@ -50,11 +51,20 @@ https://app.example.com/connect ## What can go wrong -| Status | What happened | What to tell them | -| --------------------- | -------------------------------------- | ---------------------------- | -| `400 invalid_request` | Expired, tampered with, or not a token | Ask the agent for a new link | -| `409 link_token_used` | The link was already redeemed | Ask for a new one if needed | -| `502` | Agenta could not be reached | Try again | +| Agenta answers | What happened | What to tell them | +| --------------------- | ------------------------------------------------ | ---------------------------- | +| `400 invalid_request` | Expired, tampered with, or not a token | Ask the agent for a new link | +| `409 link_token_used` | The link was already redeemed | Ask for a new one if needed | +| `401` to `404` | Your API key or plan, or an agent it doesn't own | Try again later | +| No answer, or a `5xx` | Agenta could not be reached | Try again | + +Your endpoints answer `502` for the last two rows. Neither is the person's +link, so neither may read as an expired one: they would only ask the agent for +a new link that fails the same way. + +Only redeeming says a link was used. The preview reads the token, not whether +it has been redeemed, so a spent link still names its account until it +expires. ## Two things to keep @@ -69,7 +79,8 @@ which the attacker's messages run as them. Every request in that sequence is first-party, correctly signed, and impossible to tell from the real thing at the server. The only place it can be caught is on the page, by a person reading "Connect your account (you@corp.com) to Slack (@attacker in Some Other Corp)". -That is what `preview` is for. +That is what `preview` is for, and why the page offers no Connect button until +it has answered, or when it could not. **Take a JSON body, not a form post.** An HTML form can only send urlencoded, multipart, or plain text bodies, so a server that requires `application/json` diff --git a/src/connect-page.tsx b/src/connect-page.tsx index 4af538a..a53bfe1 100644 --- a/src/connect-page.tsx +++ b/src/connect-page.tsx @@ -6,8 +6,8 @@ * The page the Connect button opens. * * It reads `?token=`, makes sure the visitor is signed in to your product, asks - * your server who the token names, and posts the token back to your own - * `/connect`. Everything it renders is one of five states, because those + * your server who the token names, and only then offers to post the token back to + * your own `/connect`. Everything it renders is one of five states, because those * are the only five things that can happen and each one needs a person to be * told something different. * @@ -21,8 +21,9 @@ import type { LinkDescription } from "./connect.js"; /** * Where the visitor is. * - * `ready` is the only state with a button. The other four are terminal, and the - * three that are not `failed` all end the same way: go back to the chat app. + * `ready` offers the button once the preview has named the account, and `failed` + * offers it again if Connect itself failed; a preview that failed has nothing to + * retry against. The other three all end the same way: go back to the chat app. */ export type ConnectStatus = "ready" | "connected" | "invalid" | "used" | "failed"; @@ -37,9 +38,18 @@ const APP_NAMES: Record = { copilot: "Copilot", }; -/** What to call the chat app before the description has said which one it is. */ +/** What to call the chat app when nothing has said which one it is. */ const ANY_APP = "Slack, Teams, or Copilot"; +/** + * What to call the chat app the visitor came from. + * @param surface The preview's `surface`, or Agenta's `?platform=` before the preview has answered. + * @returns "Slack", "Teams", or "Copilot", or all three when it is not one of them. + */ +export function appName(surface: string | undefined): string { + return APP_NAMES[surface as LinkDescription["surface"]] ?? ANY_APP; +} + /** * What to say in each terminal state. * @param status Where the visitor ended up. @@ -74,24 +84,29 @@ export function statusContent(status: ConnectStatus, platform: string): StatusCo * Show this next to who the visitor is signed in as. Someone who was sent a * link they did not ask for is reading the only line on the page that can tell * them so. - * @param description What your server got back from Agenta, if anything. - * @returns A phrase such as "Slack (@alice in Acme Corp)". + * @param description What your server got back from Agenta. + * @returns A phrase such as "Slack (@alice in Acme Corp)" or "Teams (Alice Smith)". */ -export function identityLabel(description: LinkDescription | undefined): string { - if (!description) return ANY_APP; - const inside = [ - description.platformUserName && `@${description.platformUserName}`, - description.workspaceName && `in ${description.workspaceName}`, - ] - .filter(Boolean) - .join(" "); - const app = APP_NAMES[description.surface]; +export function identityLabel(description: LinkDescription): string { + const { surface, platformUserName, workspaceName } = description; + // As each app shows a person: Slack as "@" and their display name, Teams and + // Copilot as the name alone. + const who = + platformUserName && (surface === "slack" ? `@${platformUserName}` : platformUserName); + const inside = [who, workspaceName && `in ${workspaceName}`].filter(Boolean).join(" "); + const app = APP_NAMES[surface]; return inside ? `${app} (${inside})` : app; } export interface ConnectPageProps { /** The `?token=` query parameter, however your router hands it over. */ token: string; + /** + * The `?platform=` query parameter Agenta sends alongside the token. Only names + * the app in messages shown before the preview has answered: anyone can edit a + * URL, so who is being connected comes from the preview alone. + */ + platform?: string; /** Whether your own session is loading. */ loading: boolean; /** Whether the visitor is signed in to your product. */ @@ -105,6 +120,7 @@ export interface ConnectPageProps { /** Links the signed-in visitor's account to the chat identity that sent them here. */ export function ConnectPage({ token, + platform, loading, isAuthenticated, signIn, @@ -142,8 +158,8 @@ export function ConnectPage({ ); }, [isAuthenticated, loading, signIn, status, token]); - // Asked for before the button is offered, so nobody clicks Connect without - // having been told what they are connecting. + // The button is not offered until this answers, so nobody clicks Connect + // without having been told what they are connecting. useEffect(() => { if (!token || !isAuthenticated) return; let live = true; @@ -157,9 +173,11 @@ export function ConnectPage({ if (!live) return; if (response.ok) setDescription((await response.json()) as LinkDescription); else if (response.status === 400) setStatus("invalid"); + else setStatus("failed"); } catch { - // Leaves the button offered against the generic noun. A dead - // token is caught again on redeem, where it costs nothing. + // Not a reason to offer the button anyway: without the account's + // name there is nothing for the visitor to check. + if (live) setStatus("failed"); } })(); return () => { @@ -191,8 +209,8 @@ export function ConnectPage({ } }; - const target = identityLabel(description); - const content = statusContent(status, description ? APP_NAMES[description.surface] : ANY_APP); + const app = appName(description?.surface ?? platform); + const content = statusContent(status, app); if (content) { return (
@@ -208,7 +226,7 @@ export function ConnectPage({ return (

This link has expired

-

Return to {ANY_APP} and ask the agent for a new link

+

Return to {app} and ask the agent for a new link

); } @@ -226,11 +244,25 @@ export function ConnectPage({ ); } + if (!description) { + return ( +
+

Connect your account

+ {status === "failed" ? ( +

We could not check this connection. Please try again.

+ ) : ( +

Checking this connection…

+ )} +
+ ); + } + return (

Connect your account

- Connect your account{accountName ? ` (${accountName})` : ""} to {target} + Connect your account{accountName ? ` (${accountName})` : ""} to{" "} + {identityLabel(description)}

{status === "failed" &&

We could not connect the account. Please try again.

}