Files
pages-cli/docs/client-contract.md
T
Anya Tokugawa 59ab4c5b26
Test and release pages-cli / linux (push) Successful in 7s
Test and release pages-cli / macos (push) Skipped
Add invocation-scoped TLS verification bypass for self-signed servers
2026-11-06 07:45:33 +09:00

6.2 KiB

pages-cliの接続と保存契約

pages-cliはPagesWikiのHTTPクライアントであり、DBやDocument Storeを直接開かない。実行名は pages、独立配布版はv0.1.0から始まる。配布・OS条件は配布ガイド、初期設定とコマンドはREADME、メール・タスク・連絡先はNeoMutt連携に記載する。

接続と認証

接続先のoriginでDomainを決め、サーバーの既存認証・権限評価を使う。遠隔接続はHTTPS必須で、既定では証明書とホスト名を検証する。v0.2.0以降の --insecure / -k はその呼出しだけ検証をスキップし、設定やセッションへ保存しない。期限切れ・ホスト名不一致も許容するため、信頼できる検証環境でのみ使用する。CLIのSSLContextだけを変更し、プロセス全体のTLS既定値やOIDCブラウザの検証は変更しない。警告は標準エラーへ出力する。詳細は利用手順とリスクを参照。

-k 使用時も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作成、競合の対話的復旧、巨大ファイル転送は後続タスク。