概要と共通事項

Typle 本体（Web版と iPad・Mac・Android・Windows 版）が使う、アプリ自身のバックエンドです。Go の server/internal/web で、本番では Vercel の Go の関数（リポジトリ直下の api/index.go → server/vercel）として動きます。手元では server/cmd/typle-web（既定 127.0.0.1:8081）で起動し、npm run dev と E2E が使います。

スクリプトや別のアプリから読み書きする手元専用の /api/v1 は API（Go） を見てください。2つは internal/store・internal/workspace・internal/auth を共有します。

エンドポイント

共通事項

• 本文はJSON（Content-Type: application/json; charset=utf-8）で、Cache-Control: private, no-store・Vary: Cookie を付けます。/api/shared だけは Cache-Control: no-store です。
• エラーは { "error": "<キー>" } です。キーはアプリの errors のメッセージのキーで、画面が利用者の言語で表示します。
• すべての応答に Content-Security-Policy: frame-ancestors 'none'; base-uri 'self'; object-src 'none'・X-Frame-Options: DENY・X-Content-Type-Options: nosniff・Referrer-Policy: strict-origin-when-cross-origin を付けます（Vercel では next.config.mjs のヘッダーが Go の関数に届かないため）。
• HEAD は GET と同じに答えます（本文なし）。

エラー

503 で答えた失敗は、操作名（workspace.read など）を付けて Sentry に送ります（docs/sentry.md）。

認証

アカウントは github:<GitHubのユーザーID>、または FFPF ID でログインしたときのアカウントです。ログインの流れは ログイン を見てください。

• Authorization ヘッダーがあるリクエストは、アプリ（iPad・Mac・Android・Windows）のものとして Authorization: Bearer <トークン> だけで判断し、Cookie は見ません。トークンは POST /api/auth/token で受け取ります。
• ないリクエストはセッションの Cookie で判断します。名前は HTTPS では __Host- 付きで、HttpOnly・SameSite=Lax・Path=/ です。セッションはログインから30日で切れ、使っても延びません。
• データを読み書きするリクエストは、そのたびにセッションが無効にされていないか（POST /api/auth/signout?everywhere=1 の後のログインか）をDBで確かめます。無効なら 401 loginRequired で、Cookie を消します。確かめられなければ 503 databaseUnavailable です。

書き込みの制限（CSRF 対策）

Cookie で書き込むリクエストは、Origin がアプリの origin（AUTH_URL。小文字、既定のポートなし）と同じで、Content-Type の ; より前が application/json のときだけ受け付けます。違えば 403 forbiddenRequest です。

コードの構成