概要
ログイン中の利用者は、自分のプロフィール、パーソナルアクセストークン、認証方法、承認した Koyori Desktop の端末を管理できる。同じテナントに関わる人のプロフィールも見られる。編集対象は users の列のうち本人が持ち主である 3 つに限り、メールアドレス・管理者フラグ・凍結フラグ・2FA の有効状態はこの API では変更できない。users の内容を変更する API には、ほかに管理者専用の PATCH /v1/admin/users/{id} がある。アバターの保存はドライブのストレージバックエンドに依存する。
振る舞い
編集できる項目
編集できる項目は次のとおりである。
| 項目 | 列 | 備考 |
|---|---|---|
| ユーザー名 | users.username |
一意制約は無く、同名を許す |
| 自己紹介 | users.bio |
|
| アバター | users.avatar_url |
画面では画像のアップロード(POST /v1/auth/me/avatar)で設定する。API では PATCH /v1/auth/me の avatar_url で画像の URL も指定できる。アップロードした画像のキーは users.avatar_storage_key |
同名の利用者
users.username に一意制約は無く、PATCH /v1/auth/me も重複を確認しない。既存の利用者と同じ username に変更でき、登録 API(POST /v1/auth/register)も同様に重複を許す。本人によるプロフィール更新は監査ログに記録し、ユーザー名の変更前後を追跡できる。
メンションの宛先は username の一致では決めない。コメント・タスクの説明文のメンションはメンションのマーカー(<@利用者ID>)で利用者の ID を指す(コメント・アクティビティの @メンション処理)。同名の利用者が同じプロジェクトにいても補完で選んだ一人にだけ届き、改名してもマーカーは切れない。画面上では、コメント・担当者・AvatarGroup の表示名が同じになる。
省略と消去
送らなかったフィールドは変更しない。フィールドが 1 つも無い {} を送った場合も 200 OK を返し、値は変わらない。指定の有無ではなく現在値との差を見るので、同じ値を送っても UPDATE と監査ログは発行しない。
avatar_url を消すときは { "clear_avatar_url": true } を送る。空文字("")では消せず、入力チェックで弾かれる。bio の消去は {"bio": ""} で行う。bio は空文字がそのまま有効な値で、新規登録時も空文字が入り、NULL と "" をアプリ側で区別していない。
アバターの URL
avatar_url はフロントエンドで <img src> に流し込むので、https:// 以外を保存段階で弾く(payload::users::validate_avatar_url)。javascript:、data:、HTTP、相対パスは受け付けない。画面(ProfileForm.vue)は URL を入力させないので、この判定は API 側にだけある。
avatar_url は本人以外の画面でも <img src> に載る(担当者一覧の AvatarGroup など)。指定された外部 URL は閲覧者のブラウザが直接取りに行くので、その URL を用意した側はアバターを見た人の IP アドレスと User-Agent を知り得る。アップロードしたアバターは自サーバーから配信するので、この問題は無い。そのため画面からは URL を指定できなくした。この問題は、既に外部 URL を保存している利用者と API からの指定には残る。
アップロードで入る avatar_url({APP_BASE_URL}/v1/avatars/...)は、APP_BASE_URL が http の開発環境では https:// で始まらない。サーバーが書き込む値なのでこの制限は掛からず、画面は保存済みの値をそのまま表示する。
アバターのアップロード
POST /v1/auth/me/avatar は画像をアップロードし、avatar_url を自サーバーの配信 URL に差し替える。規則は次のとおりである。
- リクエストは
multipart/form-dataで、フィールドfileを 1 つ送る - 画像は 2 MiB(
service::avatar::AVATAR_MAX_BYTES)までで、超えたら413を返す。本文全体の上限(RequestBodyLimitLayer)はこのルートだけに掛け、multipart の境界とヘッダーの分だけ 64 KiB 広げる。本文はメモリに読む - 形式はクライアントの content-type を信用せず、先頭バイトで判定する(
service::avatar::detect_image_format)。それ以外・空は400(unsupported-avatar-format)、fileが無ければ400を返す - ドライブと同じストレージバックエンドに
avatar-{uuid v4}.{拡張子}のキーで置く。drive_filesの行は作らず、リサイズ・寸法の検査・EXIF の除去はしない - トランザクションで
avatar_url = {APP_BASE_URL}/v1/avatars/{key}、avatar_storage_key = keyにし、監査ログuser.profile.update(changed_fields: ["avatar_url"]、PATCH /v1/auth/meと同じ形)を残す - DB の更新に失敗したら、置いた画像を消してからエラーを返す
- 応答は
200 OK/UserResponseである
avatar_url の生成に使う APP_BASE_URL は OAuth のコールバック URL と同じ設定値で、ブラウザから届くバックエンドの公開 URL にする。
判定する形式は次のとおりである。
| 形式 | 先頭バイト | 拡張子 |
|---|---|---|
| PNG | 89 50 4E 47 |
png |
| JPEG | FF D8 FF |
jpg |
| GIF | GIF8 |
gif |
| WebP | RIFF????WEBP |
webp |
アバターの配信
GET /v1/avatars/{key} はアップロードした画像を認証なしで配信する。<img src> から取れる必要があり、Koyori Desktop も同じ URL を使う。キーは UUID v4 で推測できない。
keyが^avatar-[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\.(png|jpg|gif|webp)$に一致しなければ404を返す- DB は引かず、
Content-Typeは拡張子から決める。画像が無ければ404を返す - ヘッダは
Content-Type、Cache-Control: public, max-age=31536000, immutable、Content-Disposition: inlineである。X-Content-Type-Options: nosniffは全経路共通の層で付く - 差し替えるとキーごと変わるので、同じ URL の中身は変わらない
画像の片付け
使われなくなった画像は、DB の更新をコミットした後に消す。消すのに失敗しても応答は成功のままにし、tracing::warn! で記録する。孤児の画像が残るだけで、利用者から見える状態は正しい。
| 契機 | 消す画像 |
|---|---|
| 再アップロード | 直前の avatar_storage_key |
PATCH /v1/auth/me で clear_avatar_url: true、または avatar_url を別の URL に変更 |
直前の avatar_storage_key。列は NULL に戻す |
管理者による利用者の削除(DELETE /v1/admin/users/{id}) |
対象の利用者の avatar_storage_key |
アバター以外の項目だけを変える PATCH では消さない。
アクセストークン
PAT 自体の認可設計の定義元は個人アクセストークンの認可である。GET /v1/personal_tokens は自分(user_id)のトークンのうち revoked = false で、結び付いたテナントが 1 件以上あるものを、名前の昇順(同名は id 順)で PersonalTokenResponse の配列として返す。テナントが尽きたトークン(結び付け先のテナントがすべて削除されたもの)は、認証にも通らないので出さない。GET /v1/personal_tokens/{id} も同じ条件で、尽きたトークンは 404 を返す。平文トークン・ハッシュは含まず、1 件も持たない場合は空配列を返す。
POST /v1/personal_tokens の tenant_ids は、重複を含めて 20 件までである。件数の検査は重複をまとめる前に行うので、同じ id を並べて 21 件にすると、まとめれば 20 件以下でも 400 になる。
平文トークンは発行直後の応答でしか取得できない。DELETE /v1/personal_tokens/{id} は行を消さず revoked フラグを立て、冪等である。取り消したトークンは一覧に出なくなる。
MCP の OAuth の許可は PAT と同じ表の行だが、この 3 つの API には出ない。単体取得と取り消しは 404 を返す。
連携中のアプリ
連携中のアプリは、利用者が MCP の OAuth の同意画面で接続を許可したクライアントである。規則の定義元は MCP サーバーの OAuth での接続である。
GET /v1/oauth_grants は、自分の許可のうち使えるものを、クライアントの名前の昇順(同名は id 順)で返す。次のものは出さない。
- 取り消した許可
- 期限の切れた許可
- 結び付いたテナントが尽きた許可
- サーバーが許可するクライアントの一覧に無いクライアントの許可
DELETE /v1/oauth_grants/{id} は許可を取り消し、そのアクセストークンとリフレッシュトークンを使えなくする。取り消した許可にも 204 を返す。他人の許可と PAT の id は 404 を返す。
解除したクライアントをもう一度使うには、クライアントから接続し直して同意する。
Koyori Desktop の端末
Device Token の規則の定義元は Bearer 認証・認可の「Desktop 認証」である。
GET /v1/users/me/devicesは、失効済み・期限切れと、パスワードの変更などで無効になった(sessions_revoked_at以前に発行した)端末を除いて新しい順に返すDELETE /v1/users/me/devices/{id}はrevoked_atを立てるだけで行は残り、一覧からは消える。その端末は次の要求から401になる
他の利用者のプロフィール
テナントのメンバーは、同じテナントに関わる人のプロフィールを見られる(TASK-257)。ユーザー名・自己紹介・アバターは本人がプロフィール設定で編集し、部署・役職・チームはテナント Admin / オーナーがメンバー設定(PUT /v1/tenants/{id}/members/{user_id})で編集する(TASK-334)。
返すのは id / username / account_kind / bio / avatar_url / department / position / team / membership の 9 項目だけである。部署・役職・チームはこのテナントでの値で、未設定・ゲストでは null になる。membership は対象の利用者とこのテナントとの関わり方(Owner / Member / Guest)で、TASK-515 で足した。閲覧者はテナントに入れる人に限られるので、誰がゲストかを見られるのはテナントのオーナー・メンバーだけである。メールアドレス・管理者フラグ・凍結フラグ・2FA の有効状態・has_password は返さない。自分自身を指定しても同じ形で返す。
このプロフィールは、プロフィールのページのほか、コメント・説明文のメンションのチップのカード(プロフィールのカード)にも出る。カードは名前とアバターを先に出し、所属・自己紹介・membership から作る「ゲスト」の表示を、このプロフィールが返ってから足す。
データ
このページで扱う users の列は次のとおりである。
| 列 | 説明 |
|---|---|
username |
ユーザー名。一意制約は無い |
bio |
自己紹介。空文字が有効な値である |
avatar_url |
アバターの URL |
avatar_storage_key |
アップロードした画像のキー。URL を指定しているときは NULL |
username / bio / avatar_url の定義は m20260520000000_initial_schema.rs、avatar_storage_key は m20261016020000_user_avatar_storage_key.rs にある。部署・役職・チームの列は m20261021000000_tenant_members_org_profile.rs、Device Token は m20260924010000_device_tokens.rs にある。
API
| メソッド | パス | 説明 |
|---|---|---|
| PATCH | /v1/auth/me |
自分のプロフィールを更新し、UserResponse を返す |
| POST | /v1/auth/me/avatar |
アバター画像をアップロードする |
| GET | /v1/avatars/{key} |
アップロードしたアバター画像を配信する |
| GET | /v1/personal_tokens |
自分のトークンの一覧 |
| POST | /v1/personal_tokens |
トークンを発行する |
| DELETE | /v1/personal_tokens/{id} |
トークンを取り消す |
| GET | /v1/oauth_grants |
連携中のアプリ(自分の MCP の OAuth の許可)の一覧 |
| DELETE | /v1/oauth_grants/{id} |
連携中のアプリの接続を解除する |
| GET | /v1/users/me/devices |
承認した端末の一覧 |
| DELETE | /v1/users/me/devices/{id} |
端末を失効させる |
| POST | /v1/desktop/auth/codes |
Koyori Desktop の承認コードを発行する |
| GET | /v1/tenants/{tenant_id}/users/{user_id} |
他の利用者のプロフィール(UserProfileResponse)を返す |
PATCH /v1/auth/me の本文(UpdateProfileRequest)は次のとおりである。文字数は UTF-16 コードユニットではなく Unicode コードポイント単位で数える。avatar_url と clear_avatar_url: true は同時に指定できず、400 Bad Request を返す。
| フィールド | 型 | 制約 | 省略時 |
|---|---|---|---|
username |
string? |
3〜255 文字 | 変更しない |
bio |
string? |
1000 文字以内 | 変更しない |
avatar_url |
string? |
2048 文字以内、https:// で始まる |
変更しない |
clear_avatar_url |
bool |
false |
GET /v1/auth/me(UserResponse)は has_password: bool を返す。ハッシュそのものは返さない。
認可
| 操作 | 誰が | スコープ |
|---|---|---|
| プロフィールの更新・アバターのアップロード | ログイン中の本人(CurrentUser) |
セッション専用。下の表のとおり拒否する |
| アバターの配信 | 誰でも | 認証不要 |
| トークンの一覧・発行・取り消し | ログイン中の本人。発行は選んだすべてのテナントに所属していること(プロジェクトだけに参加する利用者を除く) | セッション専用。PAT は 403 |
| 連携中のアプリの一覧・解除 | ログイン中の本人 | セッション専用。PAT は 403 |
| 端末の一覧・失効 | ログイン中の本人 | セッションと Device Token。PAT は 403。Device Token で失効できるのはその端末自身だけで、別の端末を指定すると 403 |
| 他の利用者のプロフィール | テナントのオーナー・テナントメンバー | PAT は read:tenant を要求する(メンバー一覧と同じ) |
GET /v1/auth/me は Desktop の Device Token も通すが、更新は通さない。CurrentUser の拒否は次のとおりである。PAT で自分のプロフィールを書き換えられないことは、個人アクセストークンの認可の「アカウント API は PAT 非対応」に沿う。
| 状態 | 応答 |
|---|---|
| 未ログイン | 401 |
Authorization: Bearer 付き(有効な PAT・Device Token) |
403。アカウント API は Bearer 非対応 |
| 無効な Bearer(存在しない・失効・期限切れ) | 401 |
| 2FA の途中(half-authed) | 403 |
| 凍結済みの利用者 | 403 |
| 入力チェック違反 | 400 |
他の利用者のプロフィールの結果は次のとおりである。閲覧者の判定はテナントの所属判定(ensure_tenant_access)を通し、対象者の判定は tenant_members の行とテナント / プロジェクト認可の既存関数(is_tenant_owner / explicit_member_project_ids)で行う。
| 状況 | 結果 |
|---|---|
| 閲覧者がテナントのオーナー・テナントメンバーで、対象がそのテナントのオーナー・メンバー・ゲスト | 200 |
| 閲覧者がテナントに入れない。ゲストと、テナントの 2FA 強制を満たさない場合を含む | 403 |
| 対象がそのテナントに関わっていない / 存在しない | 404 |
画面
プロフィール
| 項目 | 値 |
|---|---|
| URL | /settings/profile |
| ページファイル | apps/frontend/src/pages/settings/profile/+Page.vue |
| 入口 | ヘッダー右上の歯車、利用者メニューの「Account」 |
テナントに紐づかない個人の設定なので、テナントスコープ(/{tenant}/...)の外に置く。左のサイドバーには、ヘッダーのテナント切り替えで選んでいるテナントのナビ(ホーム・My Tasks・カレンダー・プロジェクト一覧)を出す。左にアカウント設定のナビ、右にプロフィールのフォームを並べる。
ナビは 8 項目を表示する。
- リンクとして機能するのは「プロフィール」「環境設定」「テーマ」「セキュリティ」「アクセストークン」「連携中のアプリ」の 6 項目である
- 「通知」「セッション」は
aria-disabledの押せない項目として並べる - 環境設定で「実験的機能を表示する」を有効にしたときだけ、区切り線の下に「実験的機能」(
/settings/experiments)が加わる。この設定はナビの項目を出すだけで、機能ごとの有効・無効はそのページのフラグで切り替える(現在のフラグは「ガントチャート」(koyoriArcIntegration)だけ) - 項目は
apps/frontend/src/components/settings/AccountSettingsNav.vueのitemsに定義する。hrefを足すとその項目が有効になる
環境設定(/settings/preferences)と実験的機能の値はブラウザの localStorage に保存する。アカウントには保存しないので、ほかの端末や別のブラウザには引き継がれない。環境設定の項目は「実験的機能を表示する」「絵文字の字」「タスク一覧でサブタスクを最初から展開する」の 3 つで、定義は apps/frontend/src/lib/preferences.ts の PREFERENCE_TABLE に置く。
テーマ(/settings/theme)は、画面の配色(ライト/ダーク)を ThemeSwitch で切り替える。選んだ値は localStorage の koyori-theme に残し、アカウントには保存しない。まだ選んでいなければ OS の配色に合わせる。head の themeScript(apps/frontend/src/pages/+Head.vue)が、描画の前に html の data-theme を light か dark に決める。
画面上部のパンくずは実データから組む(パンくず)。設定系の画面は プロフィール のように一段で出し、Account settings に当たる中間の段は置かない。
フォームの挙動は次のとおりである。
- 初期値は
GET /v1/auth/meの結果である - アバターはプレビューと「画像を選ぶ」「削除」のボタンである。URL の入力欄は無い。「画像を選ぶ」ボタンで PNG / JPEG / GIF / WebP を選ぶと、その場で
POST /v1/auth/me/avatarに送る。「変更を保存」は要らない - 2 MiB を超える画像は送る前に止める
- アップロードに成功したら応答の
UserResponseで/v1/auth/meのクエリと認証ストアを更新し、プレビューを新しい画像にする。失敗は413(サイズ)/400(形式)/ それ以外で文言を分けて出す - 「削除」ボタンはプレビューを頭文字に戻す。この時点では保存せず、保存すると
clear_avatar_urlを送る。削除の後に画像を選ぶと削除は取り消される - アップロード中は「削除」と「変更を保存」を、保存中は「画像を選ぶ」と「削除」を押せなくする。どちらの通信もアバターを書き換えるので、重なると応答の届く順によって画面とサーバーの状態が食い違う
- 保存済みの値はスキームを問わずプレビューする。
APP_BASE_URLが http の開発環境で、アップロードした画像を表示するためである - 保存すると
PATCH /v1/auth/meを送り、成功したら/v1/auth/meのクエリを無効化してサイドバーの表示名・アバターにも反映する - ユーザー名と自己紹介の入力チェックは送信前(
onSubmit)と項目からフォーカスが外れたとき(onBlur)の両方で走り、条件は API 側と同じものを持たせる
アクセストークン
| 項目 | 値 |
|---|---|
| URL | /settings/tokens |
| ページファイル | apps/frontend/src/pages/settings/tokens/+Page.vue |
| 本体 | apps/frontend/src/components/settings/AccessTokensSection.vue |
- 一覧の各行に、トークン名、末尾 4 文字だけの伏せ字(
pat_••••••7f3a)、結び付いたテナントの名前、スコープ数、有効期限、最終使用日時を表示する。テナントは 2 件まで全部、3 件以上は「A、B ほか n 件」とする。スコープの内訳は「スコープを表示」のドロップダウンで開く - 発行は「トークンを発行」でフォームを開き、
POST /v1/personal_tokensを送る - 平文トークンは発行後にコピー付きで 1 度だけ表示し、再表示できないことを明記する
- 取り消しは確認ダイアログを経て
DELETE /v1/personal_tokens/{id}を送る - 所属するテナントが無い利用者には発行ボタンを無効にし、その旨を表示する。
403が返った場合は、本文のmessageが2fa-setup-requiredなら、選んだテナントのどれかが 2 段階認証を必須にしていることを伝えて設定を促し(API は該当のテナントを返さない)、tenant-membership-missingなら選んだテナントに所属していないことを伝える。それ以外の403は原因を言わず、発行できなかったことだけを伝える - 取り消しの確認ダイアログには、結び付いたテナントの名前をすべて出す
発行フォームの項目は次のとおりである。
| 項目 | 内容 |
|---|---|
| トークン名 | 1〜100 文字 |
| テナント | 自分が所属するテナント(プロジェクトだけに参加するテナントを除く)。複数選べ、1 件以上必須(API は 1〜20 件)。候補が 1 件なら選択済みで、2 件以上なら未選択から始める。選ばずに送るとエラーを出して送らない。1 件でもフォームに出す |
| 有効期限プリセット | 30日 / 90日(既定)/ 1年 / 無期限 |
| スコープ | backend の全 16 種。1 つ以上必須で、説明付きのチェックボックスである |
プロジェクトの絞り込み(project_ids) |
常に null(テナント内の全プロジェクト)で送る |
連携中のアプリ
| 項目 | 値 |
|---|---|
| URL | /settings/apps |
| ページファイル | apps/frontend/src/pages/settings/apps/+Page.vue |
| 本体 | apps/frontend/src/components/settings/ConnectedAppsSection.vue |
| 入口 | アカウント設定のナビの「連携中のアプリ」 |
- 一覧の各行に、クライアントの名前、
client_idの host、結び付いたテナントの名前、スコープ数、期限、最終使用日時を表示する。名前はクライアントの自己申告なので、host を並べて出す。スコープの内訳は「スコープを表示」のドロップダウンで開く - 1 件も無ければ「連携中のアプリはありません。」を表示する
- 「接続を解除」は確認ダイアログを経て
DELETE /v1/oauth_grants/{id}を送り、一覧を取り直す。ダイアログには、クライアントの名前と host、結び付いたテナントの名前をすべて出す - 接続の許可はこの画面では行わない。MCP クライアントが開く同意画面で行う
セキュリティ
パスワードと OAuth 連携を「サインインできる方法」としてまとめて管理し、2 段階認証(TOTP)と Koyori Desktop の端末も扱う画面である。OAuth の認可フローと解除規則の定義元は OAuth ログイン、2 段階認証の規則の定義元は 2 段階認証である。
| 項目 | 値 |
|---|---|
| URL | /settings/security |
| ページファイル | apps/frontend/src/pages/settings/security/+Page.vue |
| 本体 | apps/frontend/src/components/settings/AuthMethodsSection.vue |
| パスワード行 | apps/frontend/src/components/settings/PasswordMethodRow.vue |
| 2 段階認証 | apps/frontend/src/components/settings/TwoFactorSection.vue |
1 枚のカードに「パスワード」「連携済み」「追加できる連携」を上から並べる。
パスワードの行は GET /v1/auth/me の has_password で出し分ける。
| 状態 | ボタン | 送信先 | 入力 |
|---|---|---|---|
| 設定済み | パスワードを変更 | POST /v1/auth/password/change |
現在 + 新しい + 確認 |
| 未設定(OAuth のみ) | パスワードを設定 | POST /v1/auth/password |
新しい + 確認 |
変更はすべてのセッションと PAT を失効させるので、フォームを開いた時点でその旨を出す。成功したら /signin へフルページ遷移し、サインイン画面はなぜサインアウトされたのかを表示する。
入力チェックは lib/auth-methods.ts の validatePasswordForm である。8 文字以上、確認との一致に加え、変更のときだけ「現在のパスワードが空でない」「現在と同じ値でない」を見る。強度表示はサインアップと同じ PasswordStrengthBar を使う。
OAuth 連携は次のとおりである。
- 連携済みは
GET /v1/auth/oauth/connectionsで取り、プロバイダー名、provider_email、接続日時、self-hosted のinstance_urlを出す - 解除は確認を挟んで
DELETE /v1/auth/oauth/connections/{provider}を送る。self-hosted はinstance_urlをクエリに添える - 追加できる連携は
GET /v1/auth/oauth/providersのうち未連携のものである。連携済みかどうかは開始用 slug ではなくconnection_provider(連携一覧が返す識別子)で突き合わせる requires_instance_urlのプロバイダー(GitLab セルフホスト)は、インスタンスが違えば別の連携として足せるので、1 件連携済みでも候補に残す。連携済みと同じインスタンス URL を入れた場合は開始しない。backend も同じインスタンスの別アカウントの接続を409で弾き、同じアカウントの接続し直しはトークンの更新になる- 「連携する」で既存の OAuth 開始 URL へフルページ遷移する。
redirect_afterにはこの画面のパスだけを渡す。プロバイダー側のエラーは backend が?oauth_error=を付けて同じ画面に戻す - 開始 URL の組み立てとプロバイダー表示名は、サインイン画面の
OAuthButtonsと共通のlib/oauth-providers.tsに置く
「連携しました」「パスワードを変更しました」は、URL のクエリではなく lib/one-time-notice.ts のマーカー(sessionStorage)を根拠に出す。マーカーは操作を始める側が置き、戻ってきた画面が 1 回だけ消費する。連携についてはさらに、GET /v1/auth/oauth/connections にその接続が実際に入っていることまで確かめてから出す。マーカーにはプロバイダー名だけでなく connection_provider とインスタンス URL も入れて、開始したその接続が入ったことを確かめる。
backend は「その連携がログイン用の最後の 1 件 かつ パスワード無し かつ パスキー無し」のとき解除を 403 oauth-last-auth-method で拒む。PR 承認用の連携(sign_in: false)は数えない。画面はこの判定を先取りして注意書きを出すだけで、可否はサーバーの応答に従う。先取りの数え方(countAuthMethods)は backend と揃えてパスキーも数えるので、この画面は件数を見る目的で GET /v1/auth/passkeys も呼ぶ。
認証方法の下に 2 段階認証の欄を置く。GET /v1/auth/me の totp_enabled で出す操作を変える。
| 状態 | 操作 | 送信先 | 入力 |
|---|---|---|---|
| 無効 | 有効にする | POST /v1/auth/2fa/totp/setup → POST /v1/auth/2fa/totp/verify-setup |
QR コードを読み取った後の初回コード |
| 有効 | 無効にする | DELETE /v1/auth/2fa/totp |
TOTP のコードかリカバリーコード |
| 有効 | リカバリーコードを再生成 | POST /v1/auth/2fa/recovery-codes/regenerate |
TOTP のコードだけ |
- QR コードと手入力用の URI、リカバリーコードの表示は、ログイン時のセットアップ(
/auth/2fa)と同じ部品(TwoFactorSetupForm・TwoFactorVerifyForm・RecoveryCodesPanel)をembeddedで埋め込む - リカバリーコードは画面の状態にだけ置き、保存の確認を押すか閉じると消す。コードを返す 2 つの mutation は
gcTime: 0にし、成功後にreset()して TanStack Query のキャッシュにも残さない - 操作が成功したら
/v1/auth/meを取り直す。失敗したときは状態の表示を切り替えない - 無効化が
403のときは、所属するテナントが 2 段階認証を必須にしているので無効化できないことを表示する(テナントの強制) 429のときは 30 秒のあいだ送信を止める。上限そのものは backend が守る- 有効化の開始が
409のときは、別の画面で設定済みとして/v1/auth/meを取り直す - 応答待ちのあいだはキャンセルを押せなくする。初回コードの検証中は「有効にする」も止める。検証中に新しいセットアップを始めると、backend が秘密を入れ替え、古い秘密で通った検証が新しい秘密を検証済みにしてしまう。別のタブから同じ順で操作した場合は画面では防げない
2 段階認証の欄の下に、承認した Koyori Desktop(Device Token)の一覧と失効を出す(apps/frontend/src/components/settings/DevicesSection.vue)。各行に端末名、末尾 4 文字だけの伏せ字、有効期限、最終使用を出し、失効は確認ダイアログを経る。
Koyori Desktop の承認
承認は /desktop/authorize(apps/frontend/src/pages/desktop/authorize/+Page.vue)で行う。
- Desktop が開いたクエリ(
port/code_challenge/state/name)をlib/desktop-authorize.tsで検証する。portは 1024〜65535 の整数のみである - 承認で
POST /v1/desktop/auth/codesを呼んでhttp://127.0.0.1:{port}/callback?code=&state=へ遷移する - 未ログインなら戻り先を
lib/one-time-notice.tsのマーカーに置いてサインインへ送り、パスワードでのサインイン後にこの画面へ戻す - OAuth でのサインインは戻らないので、Desktop からやり直す
他の利用者のプロフィール
| 項目 | 値 |
|---|---|
| URL | /{tenant}/users/{user_id} |
| ページ | apps/frontend/src/pages/@tenant/users/@userId/+Page.vue |
| 入口 | タスク詳細の担当者名・コメントの投稿者・テナント設定のメンバー一覧の名前 |
部署・役職・チームは値のあるものだけを username の下に出す。自分のときだけ「プロフィールを編集」を出す。
未実装と既知の制限
モックアップにあるが、実装していない項目は次のとおりである。
| 項目 | 理由 | 必要な作業 |
|---|---|---|
| 表示名(Display name) | users に列が無い |
マイグレーションで列を追加し、UserResponse と UpdateProfileRequest に載せる |
| タイムゾーン | users に列が無い |
同上。加えて日時表示側の適用箇所を決める必要がある |
| 言語 | users に列が無い |
同上。i18n の仕組み自体がまだ無い |
| メールアドレスの変更 | 変更後の再確認の流れが無い(email_verification は新規登録用) |
変更要求、新アドレスへの確認メール、確認後の反映の経路を新設する |
| 通知 / セッションの各画面 | 画面が無い | 通知は /v1/users/me/notification-settings/{project_id} が既にある |
| パスキーの管理 | 認証方法とは別タスク(TASK-189)。パスキーの未実装 | セキュリティ画面にセクションを足す。API は既にある |
| トークンのプロジェクト絞り込み | アクセストークン画面の対象外 | API(project_ids)は既にある。フォームに選択 UI を足す |
ほかの制限は次のとおりである。
users.usernameの一意制約は入れていない- アップロード画像の片付けに失敗すると、孤児の画像がストレージに残る
決定の記録
| 日付 | 決定 | 理由 |
|---|---|---|
| 2026-08-19 | /settings/profile をテナントスコープの外に置く |
テナントに紐づかない個人の設定である |
| 2026-08-19 | users.username に一意制約を入れず、同名を許す |
記録なし |
| 2026-08-19 | bio に clear_bio を用意しない |
bio は空文字がそのまま有効な値で、新規登録時も空文字が入るので、消去は {"bio": ""} で足りる |
| 2026-08-19 | avatar_url の消去は clear_avatar_url のフラグで行う |
avatar_url は https:// で始まることを要求するので空文字は入力チェックで弾かれる。既存の PATCH .../tasks/{id}(UpdateTaskRequest)が nullable な項目に clear_* を持たせているのと同じ形にする |
| 2026-08-24 | avatar_url は https:// だけを受け付ける |
javascript: や data: を保存できるとそのまま描画経路に載る。HTTP は mixed content で表示できない |
| 2026-09-05 | パスワードの変更後は /signin へフルページ遷移する |
クライアントルーティングにすると、失効済みのセッションで取ったキャッシュを持ち越す |
| 2026-09-05 | 最後の認証方法の注意書きは先取りに留め、可否はサーバーの応答に従う | 画面が数えた後に別のタブで増減されうる |
| 2026-09-05 | 開始 URL とプロバイダー表示名を lib/oauth-providers.ts で共有する |
片方だけ直すと画面ごとに名前や戻り先が食い違う |
| 2026-09-07 | 成功通知はクエリではなく sessionStorage のマーカーを根拠にする | クエリだけで判定すると、その URL を開かせるだけで、連携していない人に「連携しました」を、変更していない人に「失効しました」を読ませられる |
| 2026-09-07 | 連携の成功通知は連携一覧に接続が入っていることまで確かめる | 承認の途中で失敗してこの画面に戻らなかったとき、マーカーだけが残って次の来訪で誤って出るのを防ぐ |
| 2026-09-07 | マーカーに connection_provider とインスタンス URL も入れる |
プロバイダー名だけで比べると、GitLab セルフホストのインスタンス A を連携済みのまま B の承認を中断した人に、A を見て「連携しました」が出る |
| 2026-09-07 | 連携済みの判定は connection_provider で突き合わせる |
汎用 OIDC は開始用 slug が oidc、連携一覧の識別子が oidc:{issuer} で形が違い、slug で比べると連携済みでも候補に残り続ける |
| 2026-09-10 | パンくずに Account settings の中間の段を置かない |
その名で開ける画面が無い |
| 2026-09-24 | Desktop の承認の戻り先は認証ガードに任せず、マーカーに置く | 認証ガードに任せるとクエリが落ちる |
| 2026-10-15 | 対象がテナントに関わらない場合を 403 にせず 404 にする |
users はテナント横断の表で、403 と 404 を分けると任意の UUID について利用者が実在するかを調べられる |
| 2026-10-16 | アバターの画像を消す専用の API を設けない | clear_avatar_url で足りる |
| 2026-10-16 | 本文全体の上限を multipart の分だけ 64 KiB 広げる | 上限ちょうどの画像を multipart の境界とヘッダーのせいで落とさない |
| 2026-10-16 | 古い画像はコミットの後に消し、失敗しても応答は成功のままにする | 孤児の画像が残るだけで、利用者から見える状態は正しい |
| 2026-10-17 | メンションの宛先は username でなく利用者 ID で決める | 同名の利用者が同じプロジェクトにいても補完で選んだ一人にだけ届き、改名してもマーカーが切れない |
| 2026-11-07 | ヘッダーの歯車はテナント設定ではなくアカウント設定(/settings/profile)を開く |
歯車からは自分の設定が開くと期待される。テナント設定はヘッダーのテナント切り替えのメニューからも開ける |
| 2026-11-07 | リカバリーコードを返す mutation は gcTime: 0 にし、成功後に reset() する |
閉じた後も QueryClient に残ると、同じタブの別の画面や開発ツールから読み出せる。コードは応答を受けた直後の表示にしか使わない |
| 2026-11-09 | タスク一覧のサブタスクの初期展開は環境設定(localStorage)に置き、URL やプロジェクト設定にしない | 共有した相手の見え方を変える値ではなく、読む人の好みなので端末ごとでよい |
| 2026-11-14 | 配色の切り替えはヘッダーではなくアカウント設定の「テーマ」ページに置く | 頻繁に替える設定ではない |
| 2026-11-14 | task 側の暗い配色の条件は html の data-theme が light でないこと |
ui の既定が暗い配色で、属性が無いときも ui と同じ配色になる |
| 2026-11-17 | プロフィール画面からアバターの URL 入力欄を外し、画像のアップロードだけにする。PATCH /v1/auth/me の avatar_url は残す(TASK-551) |
URL 欄はアップロードが無かった頃の代わりで、外部 URL は閲覧者の IP アドレスと User-Agent を URL の持ち主に渡す。API は既存の値と利用者を壊さないよう変えない |
| 2026-11-19 | MCP の OAuth で許可した接続を、アクセストークンのページではなく新しいページ「連携中のアプリ」(/settings/apps)に出す(TASK-563) |
PAT は利用者が発行するもので、許可はクライアントが求めて利用者が与えるものである。一覧を分けると、解除する対象を探しやすい |
