52 lines
5.7 KiB
Markdown
52 lines
5.7 KiB
Markdown
# 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必須。証明書検証を無効にするオプションはない。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作成、競合の対話的復旧、巨大ファイル転送は後続タスク。
|