feat: relay the caller's own keyless signup link from the API

[rakshith48]

Keyless recovery messages now relay the caller's own https://firecrawl.dev/k/<token> signup link from the API, in place of the fixed utm_medium=mcp link. The token is a 12-character encrypted value (keyless IPv4, surface, prompt reason) that the site decrypts to keyless attribution; the API stores nothing per identity.

• A keyless 429 uses its signup_url. An eligibility refusal uses signupUrl.
• When a hosted keyless session calls an account-only tool, the server asks /v2/keyless/eligibility?signup_link=1 for the caller's link. The API tags that token with the account_only_tool reason, and issuing it is free (no rows), so this call stays.
• Relays only the API's own links: firecrawl.dev/k/<12-char token>, or the regular keyless signin link the API sends when it has no token (signin?utm_source=keyless&utm_medium=<surface>), on www. or the bare host. Anything else (another host, the old 8-character ids, or no link) falls back to the regular MCP signin link (signin?utm_source=keyless&utm_medium=mcp&redirect=%2Fapp%2Fapi-keys), so MCP attribution is kept.
• Recovery payloads carry the link as signup_url.
• Tests cover the 429, eligibility and account-only paths, including an account-only case that relays the regular link and drops an untrusted or legacy one.

Safe to deploy before the API change, since it falls back to the regular MCP signin link.

---

Summary by cubic

Keyless recovery messages now relay the caller's own https://firecrawl.dev/k/<token> signup link from the API instead of the fixed utm_medium=mcp link, keeping attribution on the identity that was rate-limited.

• The API issues stateless 12-character encrypted tokens; legacy 8-character ids and non-firecrawl.dev links are rejected.
• A keyless 429 uses its signup_url; an eligibility refusal uses signupUrl; an account-only tool on a hosted keyless session asks /v2/keyless/eligibility?signup_link=1 for the caller's link.
• Links are checked field by field: https on firecrawl.dev/www.firecrawl.dev, either /k/<12-char token> with no query, or /signin with utm_source=keyless, utm_medium=api|mcp|cli, and an optional redirect=/app/api-keys. Anything else falls back to the regular MCP signup link and unrecognized Firecrawl-hosted links are logged once for drift visibility.
• Recovery payloads carry the link as signup_url, and the server ships as 3.27.0.

Safe to deploy before the API change, since it falls back to the regular MCP signup link.

Migration
Ship in order: web /k route and signup decrypt, API issuing links, MCP relay, then CLI. Set KEYLESS_SIGNUP_LINK_KEYS in the web env before the API ships.

^{Written for commit 583a554. Summary will update on new commits.}

Rollout order (ship in this order)

1. firecrawl/firecrawl-db#310: migrations
2. firecrawl/firecrawl-web#3849: /k/<token> route and signup decrypt (must be live before the API ships, or new links 404)
3. feat(api): link keyless prompts to opaque per-identity /k links firecrawl#4856: API issues the links
4. feat: relay the caller's own keyless signup link from the API #467: MCP relays them
5. feat: print the API's keyless signup link as-is and send X-Origin: cli cli#291: CLI release

Web and API must share KEYLESS_SIGNUP_LINK_KEYS before the API ships. Set the same value in the web env first, then in the API env. If the API encrypts with a key the web doesn't have, signups keep the raw token in keyless_ref but get no decoded columns.

🤖 Generated with Claude Code

[cubic-dev-ai]

All reported issues were addressed across 5 files

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Auto-approved: Per-caller keyless signup links are now relayed from the API into recovery messages, with strict URL validation and a fallback to the bare /k link; the change is bounded to message/payload formatting and covered by new tests.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 4 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

Dismissed because Cubic found issues in a newer review.

[cubic-dev-ai]

All reported issues were addressed across 3 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Auto-approved: Per-caller keyless signup links from the API are relayed in recovery messages only after strict URL validation, with fallback to the standard MCP signin link; the change is confined to recovery formatting and covered by tests.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Auto-approved: Keyless recovery messages now relay a caller-specific, API-issued signup link only after strict field-by-field URL validation, falling back to the standard MCP signin link otherwise; the behavior is confined to recovery messaging and covered by focused tests.

Re-trigger cubic</sub>