Files
pages/docs/design/ja/remote-cli.md
T
Anya Tokugawa 93f4ecb8f4
Build and publish container images / images (push) Successful in 14m31s
Release container images / release (push) Successful in 27s
Enable CLI language-aware editing and reuse OIDC authentication
2026-11-01 21:31:04 +09:00

186 lines
20 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# pages-cli:`pages` HTTPクライアント
2026-11-01。合成データで検証済み。同日、本番サーバのCity更新と合わせてクライアントをホストの `/home/anya/.local/bin/pages` に配置した。実ユーザの資格情報取得・ログイン・本番Page編集は未実施。接続設定とログインは利用者が行う。[反映記録](../../operations/deployments/2026-11-01-city-pages-cli.md)。
v0.3.0のOIDCログインは利用者の動作確認済み。後続変更として、OIDC承認時の追加ローカルTOTPを廃止し、CLIの `auto` 言語選択と既存Pageの新規言語版編集を実装した。この後続変更はソース段階であり、本番サーバー/PATH上のCLIには未反映。
## 原設計との整合
原設計の [Address Model](../address-model.md)、[URI](../uri.md)、[認証バックエンド](../auth-backend.md)、[エディタの保存契約](editor-resilience.md)を使用する。
- Pathは到達経路、UUIDはPageの識別子、Revisionは履歴。取得は `/v/raw/path:/...`、`uuid:`、`rev:` で行い、`/raw/...` を増設しない。
- 編集開始時にObject UUIDを確定し、指定言語のheadを取得。保存はUUID+言語+`base_revision_uuid`+`editor_principal_uuid`。Path変更に追従するため保存先を再解決して別Pageに書き込まない。
- Wiki正本はHTML。編集用Markdownはauthoring射影であり、children等の表示展開結果を保存しない。保護HTMLフェンスを既存authoring APIで往復する。
- Domainは接続originで決まり、HTTPで既存の認証・権限制御を受ける。Campus連携用トークン/PSKをユーザー認証に流用しない。
- 旧認証設計にはCookie中心の記載が残るが、実装済みのJSONログインはBearerセッションを発行する。CLIはこのフローを使用し、Web Cookieを抽出しない。
- `data/pageswiki-cli` は信頼されたローカル運用ツールとして維持。遠隔版はサブプロジェクト `pages-cli`、実行名 `pages`(`pages-cli/pages`)とし、DB・Document Storeを直接開かない。
初期のパスワード版にはサーバAPI/DBスキーマの追加・変更はない。後続のOIDC引き継ぎでは下記のauthエンドポイントとmanaged component `cli-auth` v1を追加する。Python 3.9以降の標準ライブラリで動作するUnix系クライアント(fcntl、readline使用)。Windowsネイティブ版は未対応。
## 利用方法
```sh
# 初回設定。パスワードはlogin時の非表示プロンプト、必要ならTOTPを続けて入力。
pages configure --origin https://pages.example.test --username anya
pages login
pages status
pages
# ワンショット。editでは --lang をコマンドの後にも指定可能。
pages ls /manual
pages edit /manual/start
pages get /manual/start ./start.html
pages put ./start.html /manual/start --base REVISION_UUID
pages logout
```
配置方法と詳しい設定例は [pages-cli README](../../../pages-cli/README.md)。既定プロファイル名は `default`、新規プロファイルの編集言語は `auto`。既存の明示設定は保持する。`pages configure --lang auto` で表示対象の言語に追従し、`--lang ja` なら日本語版を指定する。`configure set --profile work --origin ... --username ... --lang en` で接続先を追加し、`configure use work` で既定を切り替える。一時的な `--profile`/`--lang` 上書きも残す。
設定は `config.json` の version/default_profile/profiles と、各接続のorigin/username/langに限定。パスワード・Bearerは設定表示へ含めない。configureはネットワーク通信をせず、ログイン中のorigin/username変更を拒否する。mainは設定ロック→セッションロックの順で取得し、起動時の接続先すり替えを防ぐ。手編集時も保存したセッションの接続先・アカウントとの一致を確認してから使用する。logoutは設定を手編集した場合でも、保存済みの元接続先に対して失効する。
対話シェルは `ls`、`cd`、`pwd`、`status`、`cat`、`view`、`get`、`put`、`edit`、`search`、`open`、`logout`、`exit` を扱う。`--help` で一覧、`edit --help` 等で引数を確認する。`cd` は仮想Pathにも移動でき、存在や閲覧可能な子の存在を保証しない。
TabはPath候補を取得し、上下キーは当該プロセス内の履歴をたどる。Pathに空白等があればシェルと同様に引用する。履歴はディスクへ保存しない。現在Pathは接続プロファイルへ保存する。同じプロファイルの同時実行はロックで拒否し、別プロファイルは独立して使える。
`search QUERY` は権限付きサジェストを表示する初期コマンド。Ctrl+Pのインクリメンタルfuzzy選択は未実装であり、通常のreadlineキー割当のまま。
### 閲覧・編集
- `get ADDRESS LOCAL` は最大64 MiBの正本を取得し、SHA-256を照合する。ローカル出力は0600で新規作成し、既存ファイルを上書きしない。Revision UUIDを表示する。
- `cat` はpipe時に正本バイト列を出力。TTY時には制御文字を除去する。`view` はテキストを `$PAGER`(既定less)に渡し、HTMLを端末上で実行しない。
- `edit` は `$EDITOR`(既定vi)をshellを介さず起動。HTMLはauthoring Markdownが既定、その他の対応テキストは原文。`--format raw` でHTMLを直接編集できる。`--format markdown` はHTML文書専用。
- `auto` はRaw HEADのRevision UUIDから言語を確認し、その言語の現在headを再取得する。以降の保存・競合比較はその言語に固定し、途中で通常表示の言語が変わっても追従しない。
- 明示言語のheadがなければ表示対象のRevisionを下書きとして読み込む。保存先言語と空の `base_revision_uuid` を保持し、保存時点でもheadがないことをCASで確認する。元の言語版は変更しない。これは内容の分岐であり自動翻訳ではない。無変更で閉じれば新規Revisionは作らない。
- ローカル作業ファイルは0700の一時ディレクトリ内に0600で保存。成功・無変更時は削除、失敗/409/通信断時は原稿とrecovery.jsonを保持して場所を表示する。recovery.jsonにはorigin、UUID、基点Revision、言語、形式を記録し、Bearerは含めない。
- 409では最新内容とローカル原稿の差分を表示し、保存は停止する。自動マージ、強制上書き、自動再送はしない。応答喪失時は取得してサーバの状態を確認してから再試行する。
- `put` は既存Pageの既存言語のみ。`--base` が必須で、現在headと不一致なら送信しない。サーバ保存も同じbaseでCASを行う。編集を保持したい場合は最新を取得して差分を確認し、調整済み原稿とその最新Revisionを明示して保存する。
- `put --format markdown` はauthoring変換を使用。rawは正本形式を保持する。ローカル拡張子で保存MIMEを勝手に変更しない。テキスト編集は1 MiB、JSON送信は2 MiBまで。
- `rev:` は取得専用。新規Path/Page、バイナリ編集、Asset更新は拒否する。新規作成のためにエディタGETの副作用を利用しない。新規言語版も保存APIで既存Pageの書込権限を検査する。
- `open` は同一originのPath/UUID/Revisionビューアをブラウザで開く。BearerはURLに含めず、ブラウザ側のログインが必要。共有リンクは自動発行しない。
## HTTP契約
| 操作 | 既存エンドポイント |
| --- | --- |
| ログイン/MFA | POST `/_/auth/login`、`/_/auth/totp`、フォーム本文+Accept application/json |
| 失効 | POST `/_/auth/logout`、Bearer |
| 一覧・補完 | GET `/_/api/v1/path-picker?mode=children&path=...&prefix=...` |
| 検索候補 | GET `/_/api/v1/search/suggest?q=...` |
| 正本・識別子 | GET/HEAD `/v/raw/{explicit-address}?lang=...` |
| 言語別編集状態 | GET `/_/api/v1/editor/state?uuid=...&lang=...` |
| HTMLへの復帰 | POST `/_/api/v1/render/markdown`、authoring=true、projection=false |
| CAS保存 | POST `/_/api/v1/revisions/save` |
一覧は既存の件数制限を維持し、truncatedを表示する。巨大な全階層を再帰取得しない。読み取りのRaw言語選択は既存サーバの候補選択に従う。`auto` はRawのlang指定を省略し、実際に選択されたRevisionの言語をeditor/stateのmetadataで確認する。明示言語のheadがない場合だけ、同APIのrevision指定で元の内容を読み込む。元のRevision UUIDを保存の基点に流用せず、空の基点で新規言語版を作る。
## OIDCブラウザ引き継ぎ
`pages login --oidc` はブラウザを開き、`--no-browser` はURLだけを表示する。
CLI側に受信ポートは不要で、SSH先から開始して別のPC/スマホで承認できる。
接続先のOIDC設定・既存アカウントとの対応を再利用し、新たなprovider登録は不要。
ユーザー名未指定なら認証結果をセッションに保存する。指定済みなら一致を検査し、
不一致時は新セッションを失効させるリクエストを送って保存を止める。
設定上のusernameと認証結果のusernameは別々に保持し、接続先・アカウントの手編集対策を維持する。
### プロトコル
[RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)の別端末承認・ポーリングの考え方と、
[RFC 7636](https://www.rfc-editor.org/rfc/rfc7636)のS256照合を参照する。
これはPagesWiki専用のsession handoffであり、汎用OAuth Device Authorization Serverの
discovery/grant_type/client registrationへの完全準拠を標榜しない。
| 入口 | 用途 |
| --- | --- |
| POST `/_/auth/cli/start` | formの`code_challenge`、`code_challenge_method=S256`で開始 |
| GET `/_/auth/cli/verify?request=...` | OIDCへの入口と、認証後の本人・接続先確認/承認フォーム |
| GET `/_/auth/oidc?cli=...` | 既存のnonce・state・PKCE・署名検証を使うOIDCフロー |
| POST `/_/auth/cli/verify` | browser session、CSRF、request、確認コードで承認/拒否 |
| POST `/_/auth/cli/token` | formの`device_code`、`code_verifier`を照合して単回交換 |
1. CLIは暗号学的乱数のverifierを生成し、そのSHA-256を送る。サーバは独立した256bitの
public request ID/device codeと32bit確認コードを生成する。
返却するverification URIは同一origin内の固定Path。CLIもPath形式を厳密に検査する。
2. ブラウザは既存CookieがあってもOIDCフローを通る。新しいOIDC callbackで作られた
browser sessionにリクエストを一度だけ束縛する。他ブラウザによる再束縛を拒否。
3. callbackだけではCLIへ認証情報を渡さない。承認画面はterminalの確認コード入力を要求し、
フォーム内にコードを埋め込まない。本人が開始した操作だけ承認するよう警告する。
同一origin検査+browser tokenとrequestに束縛したCSRFを使用する。
4. OIDC認証後の承認で追加のローカルTOTPは要求しない。プロバイダーの認証ポリシーを使用する。
OIDC成功だけをMFA成功とは扱わず、未検証のMFA levelを加算しない。
ローカルパスワードログイン時のTOTP要件は変更しない。
5. CLIは5秒間隔でpoll。pendingのみ継続し、slow_downで間隔を5秒ずつ最大30秒へ増やす。
拒否・失効・ネットワーク障害・交換応答の喪失では自動再送しない。
6. grantの消費と専用`pw_api_`セッション発行を同じtransactionで確定する。
Principal/Domain membership/承認元browser sessionの失効・期限を再検査する。
セッションは既存の権限評価に従い、期限はDomain設定と承認元session期限の短い方。
MFA levelを保持する。ブラウザCookieや外部provider tokenをCLIへ流用しない。
### 永続化・上限
- managed component `cli-auth` v1に短期状態を保存。既存authテーブルやURIは改名しない。
- grantは5分で失効。確認失敗は最大5回、OIDC開始は1grantあたり3回まで。
- 同一Domainで5分間に64件まで、全体の保持件数は4096件まで。発行前に作成10分超の行を削除する。
上限判定は単一INSERT内で行い、並行発行で超過しない。長期履歴にはしない。
- device code/確認コード/browser tokenはハッシュだけを保存。verifierはCLIのメモリだけ。
新しいAPI Bearerの平文は既存0600セッションファイルだけに保存する。
- 外向け応答はno-store、承認ページはno-referrer・frame禁止。Bearer・verifier・確認コードを
URLに含めない。リクエスト本文をアクセスログへ記録しない運用を前提とする。
- read-onlyインスタンスは発行・承認・交換しない。初期化は通常のmanaged schema手順に従う。
v0.2.0へ戻す前には追加componentを含む互換性を確認し、schema履歴を削除して回避しない。
HTTP応答が失われた場合にセッションが発行済みの可能性は残る。平文BearerをDBへ保持して
再配布する方式は採らず、利用者が設定画面で不要なセッションを失効する。
Ctrl+C時は未交換grantを即時サーバ削除せず、5分の期限で失効させる。
この上限は入口全体のDDoS対策ではない。reverse proxyでの一般的なリクエスト制限は別途必要。
## セキュリティと運用上の制限
- 遠隔はHTTPS必須、証明書検証を無効化するオプションなし。HTTPはlocalhost/127.0.0.1/::1の開発専用。
- 接続先はoriginのみ。userinfo、Path、query、fragmentを含むURLは拒否。リダイレクトは同一originも含め追従しない。認証画面HTMLや302/303を成功と扱わない。
- 設定は `$XDG_CONFIG_HOME/pages-cli/config.json`、セッションは同じルートの `sessions/PROFILE.json`(既定 `~/.config/pages-cli/`)。ディレクトリ0700/ファイル0600、所有者を検査し、シンボリックリンクは拒否。atomic replaceとプロファイルロックを使用。旧試作の `~/.config/pageswiki-remote/` は自動読込・移行・削除しない。再configure/loginし、不要な旧セッションはサーバ側で失効する。
- 資格情報は平文のため、同一OSユーザーやrootからは保護できない。OS keyring/暗号化保存は後続。共有端末ではlogoutし、残した作業原稿は利用者が整理する。
- パスワード/TOTP/Bearerを引数や履歴へ入力させない。保存したexpiryを超えたセッションでは操作を開始せず、実際の失効・権限はサーバで毎回判定する。logout失敗時は失効済みと報告せず資格情報を残す。
- ネットワーク要求には20秒のsocket timeoutと応答サイズ上限。総転送時間の厳密deadline/ストリーミング巨大ファイル対応は後続。
## 検証と次段階
Python unittest:origin制限、端末制御文字、別origin redirect遮断、非JSON/403/サイズ上限、TOTP、資格情報権限・symlink・並行実行拒否、authoring/CAS payload、ダウンロード上書き拒否、409時の原稿保全。
Python単体試験22件:既定値/複数接続切替/言語保存、一時上書き、設定表示からのトークン除外、接続先変更拒否、PKCE、poll間隔、URL検査、アカウント不一致、取消、通信断、username未指定でのsession保持、開始API未対応/OIDC無効時の診断、autoの言語とhead固定、新規言語版の空CAS、無変更終了、競合時の言語固定を検査する。
Goの `TestRemoteCLIHTTPIntegration`:一時DBと本物のHTTPハンドラでログイン、一覧、編集状態、authoring変換、保存、古いRevision拒否、Rawハッシュ、immutable拒否、新規言語版作成と並行作成の409、元言語の保持、日本語版のみ存在するPageのauto編集、put、ログアウト後の拒否を検査。Pythonがないビルド環境ではこの統合試験をskipする。外部カレンダーや本番資格情報は使わない。
OIDCは署名付き模擬providerによるcallback→承認→交換のHTTP試験、12並行交換で1sessionのみ、
越境・別origin・期限・失効・MFA・不正コード・発行上限・途中失敗rollbackを検査する。
`TestRemoteCLIOIDCIntegration`ではPython CLIから実際のHTTP経由でconfigure→OIDC待機/交換→一覧→authoring保存→logoutを実行する。
この試験のブラウザ操作だけはfixtureの承認ブリッジを使い、実OIDC callbackは別のHTTP試験で検証する。
承認画面のChromium試験は1440px/390pxで実フォームとCookieによる承認を確認する。
v0.3.0の本番OIDCログインは利用者確認済み。追加TOTP省略はローカルTOTP有効の合成アカウントでも検証し、MFA levelを不当に上げないことと既存の検証済みlevelの継承を確認する。
2026-11-01のv0.3.0公開時の実行結果:全Goテスト(キャッシュなし)、全Go vet、関連store/serverのrace検査、
Python 18件、OIDCとパスワードのCLI HTTP統合試験、承認画面と既存CookieログインのChromium試験が成功。
CLI承認画面のモバイルスクリーンショットも確認した。実機Safariは未確認。
前段のイベントログ修正を保持し、OIDCは機能追加としてv0.3.0で公開した。
同日20:52 JSTに本番サーバーとユーザーPATH上のCLIへ反映済み。
[本番反映記録](../../operations/deployments/2026-11-01-v0.3.0.md)にCI再実行、schema移行、公開API確認と復旧条件を記載した。
サーバーとCLIの両方が必要。開始APIの404/405/501は未対応または接続先の誤りとして明示し、
OIDC無効の403と区別する。エラー時のログイン要求は自動再送せず、資格情報も保存しない。
同日の後続変更でも全Goテスト(キャッシュなし)、全Go vet、CLI関連store/serverのrace検査、
Python 22件、承認画面と既存CookieログインのChromium試験が成功した。
`TestRemoteCLILanguageForkRequiresWritePermission`で、有効なreadonlyセッションからの言語版作成が403になり、Revisionが残らないことも確認した。
この後続変更は未リリース・未デプロイであり、上記v0.3.0の反映記録とは区別する。
ソースのチェックポイント:`.deployment-backups/dev-cli-oidc-20261101/source-after.tar.gz`
(SHA-256 `3e4228cd53b4220dffe43a80b4ed02c0bd757a8b3845829b7d3a77a64b0e9c4b`)。
OIDC関連18ファイルのみで、本番DB・鍵・セッション・前段のログ保存修正は含まない。
変更前はGitの`0f686aa`と比較し、対象ファイル単位で復元する。作業ツリー全体をresetしない。
次段階の順序:
1. Ctrl+Pによる検索選択、補完の引用文字/途中カーソル対応、永続履歴の明示opt-in。
2. 新規Page+Path+初回Revisionの原子的な作成API、create/upload-only権限、並行作成の衝突。既存Pageの言語分岐は実装済み。
3. 競合の対話選択・復旧コマンド、巨大転送のstreamingとキャンセル、mget/mput(globのlocal/remoteを明示)。
4. OIDC引き継ぎの本番schema適用・サーバ/CLI配布と利用者確認はv0.3.0で完了。追加TOTP省略と言語編集改善の配布は未実施。schema v1の定義は変更しない。
5. OS keyring、Windows対応、非公開の短縮リンク引き継ぎ。自動的な公開shareは行わない。