# pages-cliの接続と保存契約 pages-cliはPagesWikiのHTTPクライアントであり、DBやDocument Storeを直接開かない。実行名は `pages`、独立配布版はv0.1.0から始まる。配布・OS条件は[配布ガイド](../DISTRIBUTION.md)、初期設定とコマンドは[README](../README.md)、メール・タスク・連絡先は[NeoMutt連携](neomutt.md)に記載する。 ## 接続と認証 接続先のoriginでDomainを決め、サーバーの既存認証・権限評価を使う。遠隔接続はHTTPS必須で、既定では証明書とホスト名を検証する。v0.2.0以降の `--insecure` / `-k` はその呼出しだけ検証をスキップし、設定やセッションへ保存しない。期限切れ・ホスト名不一致も許容するため、信頼できる検証環境でのみ使用する。CLIのSSLContextだけを変更し、プロセス全体のTLS既定値やOIDCブラウザの検証は変更しない。警告は標準エラーへ出力する。詳細は[利用手順とリスク](../README.md#自己署名証明書の環境に接続する)を参照。 `-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作成、競合の対話的復旧、巨大ファイル転送は後続タスク。