reference/link-handler-spec.md

/link Handler Spec

Status: implemented in apps/web.

Goal

Support zero-manual onboarding from setup links generated by the server.

Examples:

  • relay mode: https://mino.ink/link?relayCode=...&relayUrl=...
  • direct mode: https://mino.ink/link?serverUrl=...&apiKey=...
  • local built-in UI: http://localhost:3000/link?...
  • local web dev: http://localhost:5173/link?...

Required Params

  • direct mode: serverUrl, apiKey
  • relay mode: relayCode, optional relayUrl

Required Flow

  1. Parse query params
  2. If relay mode, exchange code at relay (POST /api/v1/pair/exchange)
  3. Validate resolved serverUrl and apiKey
  4. Normalize serverUrl
  5. Verify key (POST {serverUrl}/api/v1/auth/verify)
  6. Mark setup complete (POST {serverUrl}/api/v1/auth/link)
  7. Persist linked profile locally
  8. Redirect to workspace

Security Requirements

  • never log raw apiKey
  • redact sensitive values in diagnostics
  • strip apiKey, relayCode, and relayUrl from browser URL

Acceptance Criteria

  • valid relay/direct links complete onboarding without manual input
  • POST /api/v1/auth/link runs exactly once on successful first link
  • invalid links fail safely with manual fallback