5.7 KiB
pages-cliの接続と保存契約
pages-cliはPagesWikiのHTTPクライアントであり、DBやDocument Storeを直接開かない。実行名は pages、独立配布版はv0.1.0から始まる。配布・OS条件は配布ガイド、初期設定とコマンドはREADME、メール・タスク・連絡先はNeoMutt連携に記載する。
接続と認証
接続先のoriginでDomainを決め、サーバーの既存認証・権限評価を使う。遠隔接続はHTTPS必須。証明書検証を無効にするオプションはない。HTTPはloopbackでの開発専用。originにuserinfo、Path、query、fragmentを含めず、リダイレクトには追従しない。ログイン画面のHTMLや302/303をAPIの成功として扱わない。
パスワードログインでは必要に応じてTOTPを入力する。login --oidc [--no-browser] ではブラウザのOIDCログイン後に、ターミナルの確認コードを入力して承認する。S256でCLIのverifierに束縛し、短期リクエストを一度だけBearerセッションへ交換する。SSH先から開始し、別端末で承認できる。ブラウザCookie、外部OIDC token、Campus用PSKをCLIのBearerとして流用しない。
OIDC入口はサーバーv0.3.0以降。OIDCで認証した利用者への追加ローカルTOTP省略と新規言語版の編集はサーバーv0.4.0以降。タスク・連絡先を含む独立CLIの利用基準はサーバーv0.6.0以降。独立CLIとサーバーのバージョン番号は連動しない。
ローカル状態と秘密情報
設定は $XDG_CONFIG_HOME/pages-cli/config.json、セッションは同じルートの sessions/PROFILE.json に置く。XDG_CONFIG_HOME未指定時は ~/.config/pages-cli/。ディレクトリ0700、ファイル0600と所有者を検査し、シンボリックリンクは拒否する。設定とセッションは分離し、atomic replaceとプロファイルロックで保存する。同じプロファイルの同時利用は拒否する。
設定のorigin・usernameと保存セッションの対応を検査する。ログイン中の接続先変更はlogoutを先に行う。logoutはサーバーの失効に失敗した場合、成功と報告せず資格情報を残す。パスワード・TOTP・Bearerを引数、URL、履歴、設定表示へ含めない。セッションファイルは平文なので、同じOSユーザーやrootからは保護できない。OS keyringは未対応。
アドレスと編集
Pathは到達経路、UUIDはPageの識別子、Revisionは履歴。正本は /v/raw/path:/...、uuid:、rev: で取得する。Wiki正本はHTMLで、編集用Markdownはauthoring射影。children等の展開結果を保存せず、HTMLの保護フェンスを既存変換APIで往復する。
編集開始時にObject UUIDと保存先言語、基点Revisionを確定する。auto は表示されたRevisionの言語を採用する。明示した言語のheadがなければ既存言語の内容を下書きとして開き、空の基点で新規言語版をCAS保存する。自動翻訳はしない。無変更なら作成しない。編集途中でPathが変わっても別Pageへ保存しない。
$EDITOR はshellを介さず起動する。作業ファイルは0700の一時ディレクトリ内へ0600で保存し、成功・無変更時は削除する。通信断や競合時は原稿と復旧メタデータを保持して場所を表示する。復旧メタデータにBearerを入れない。競合時は差分を示して停止し、自動マージ・強制上書き・保存要求の自動再送は行わない。
put は既存言語の基点を --base で指定する。新規Path/Page、バイナリ編集、Asset更新は未対応。Revisionアドレスは取得専用。ブラウザで open する際はブラウザ自身のログインを使い、共有リンクを自動発行しない。
HTTP API
| 操作 | エンドポイント |
|---|---|
| パスワード・MFA | POST /_/auth/login、/_/auth/totp |
| OIDC引き継ぎ | POST /_/auth/cli/start、ブラウザ /_/auth/cli/verify、POST /_/auth/cli/token |
| 失効 | POST /_/auth/logout |
| 一覧・補完 | GET /_/api/v1/path-picker |
| 検索候補 | GET /_/api/v1/search/suggest |
| 正本・識別子 | GET/HEAD /v/raw/{explicit-address} |
| 編集状態 | GET /_/api/v1/editor/state |
| HTMLへの復帰 | POST /_/api/v1/render/markdown、authoring=true、projection=false |
| CAS保存 | POST /_/api/v1/revisions/save |
| タスク | /_/api/v1/extension/organizer.tasks/配下のcapture・items・preferences・work・report |
| 個人アドレス帳 | /_/api/v1/extension/organizer.contacts/配下のitems・import |
上限と検証
ネットワークには20秒のsocket timeoutと応答サイズ上限がある。総転送時間の厳密なdeadlineや巨大転送のstreamingは未対応。get は最大64 MiB、SHA-256を照合し、新規0600ファイルへ出力する。既存ファイルは上書きしない。編集テキストは1 MiB、JSON送信は2 MiBまで。
メール取り込みは1通2 MiB、本文は明示指定時のみ、保持するメモは16 KiBまで。再送用要求は最大20件。連絡先importは1枚のUTF-8 vCard、64 KiBまで。NeoMutt検索は本人・Domain内の個人アドレス帳を対象とし、最大100件を返す。
CLIの単体・実バイナリ試験は合成データのみを使用する。サーバー側の権限・CAS・OIDC署名検証とGoのHTTP結合テストはPagesWikiリポジトリで管理する。Windowsの資格情報保護とロック移植、新規Page作成、競合の対話的復旧、巨大ファイル転送は後続タスク。