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..56038f6 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,22 @@ 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 { + // Compared one by one rather than looked up, so "?platform=constructor" + // names all three apps, not a function from the object's prototype. + return surface === "slack" || surface === "teams" || surface === "copilot" + ? APP_NAMES[surface] + : ANY_APP; +} + /** * What to say in each terminal state. * @param status Where the visitor ended up. @@ -74,24 +88,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 +124,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, @@ -137,13 +157,15 @@ export function ConnectPage({ if (status !== "ready" || !token || loading || isAuthenticated) return; if (signInStarted.current) return; signInStarted.current = true; - signIn(`/connect?${new URLSearchParams({ token }).toString()}`).catch(() => - setStatus("failed"), - ); - }, [isAuthenticated, loading, signIn, status, token]); + // Back to this same link, `platform` included, so the messages that come + // before the preview still name the app. + const returnTo = new URLSearchParams({ token }); + if (platform) returnTo.set("platform", platform); + signIn(`/connect?${returnTo.toString()}`).catch(() => setStatus("failed")); + }, [isAuthenticated, loading, platform, 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 +179,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 +215,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 +232,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 +250,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.

}