Drive Sync の構成：URL、スコープ、監査

これは開発者向けの Drive Sync リファレンスです。REST API や MCP server と同期アクセスを統合する場合、TrekMail Drive 上にツールを構築する場合、WebDAV ファサードの権限適用を監査する場合に使用します。

rclone や Finder を接続するだけなら、Drive Sync の概要から始めてください。

Drive Sync とは

Drive Sync は TrekMail Drive の WebDAV インターフェースです。対応同期アプリは専用デバイスパスワードと選択した権限を使い、ダッシュボードや Webmail と同じファイルへアクセスします。

固定プレフィックスで標準 WebDAV メソッドを使用します。クライアントごとに対応が異なるため、本番移行やバックアップ前に使い捨てフォルダで必要な操作を試してください。

URL の構成

Drive URL はデプロイごとに生成され、Sync devices に表示されます。ダッシュボードのドメインから組み立てず、その URL をコピーしてください。パスは /dav/files/ で始まります。

https://YOUR-DRIVE-HOST/dav/files/

ルート以下にはアカウントツリーとメールボックスツリーがあります。パスワードが開ける範囲は、メールボックスへの紐付けと選択権限の両方で決まります。

アカウント全体のツリー

/dav/files/account/
    ├── (top-level account-drive folders the dashboard shows)
    └── (top-level files at the account-drive root)

これはダッシュボードの Account Drive です。一つのメールボックスに限定されないパスワードは、Account Drive 権限があれば表示できます。

メールボックス限定ツリー

/dav/files/mailbox-{N}/
    ├── (the mailbox's personal Drive files and folders)
    └── Shared/
        ├── (account-drive folders flagged "shared with all mailboxes")
        └── ...

一つのメールボックスに限定されたデバイスパスワードは、その個人用ツリーだけを表示します。個人用 Drive アクセスがあり、アカウントに共有フォルダがあれば、Shared/ に全メールボックス共有のアカウントフォルダが表示されます。

限定パスワードは Account Drive や別メールボックスを表示できません。限定なしのパスワードは Drive 空間を一覧できますが、各パスには対応するアカウントまたはメールボックス権限が必要です。

デバイスパスワードの作成

ダッシュボードの Sync devices、または現在のメールボックスの Webmail から作成できます。ダッシュボードはアカウント全体または一つのメールボックス限定で作成でき、Webmail はサインイン中のメールボックス限定です。

明確なラベルを付け、必要な権限だけを選び、一時接続には有効期限を設定します。シークレットは一度だけ表示されるため、確認画面を閉じる前にアプリかパスワードマネージャーへ保存します。

通常の TrekMail パスワードを変えずにいつでも取り消せます。取り消し済み、期限切れのパスワードは直ちに停止します。

デバイスパスワードでサインイン

同期は HTTPS 上の HTTP Basic を使用します。Sync devices に表示されたユーザー名と生成パスワードを入力し、ダッシュボード用パスワードは使わないでください。

取り消しまたは期限切れ後、アプリは通常認証情報を再要求します。アカウント状態、メールボックスアクセス、Drive アクセス、選択権限はリクエストごとに確認されます。

スコープモデル

REST API と同じ drive:{family}:{action} 形式を使います。デバイスパスワードに適用される八つは次のとおりです。

読み取りには対応する :read、作成、変更、移動、コピー、削除には :write が必要です。パスがアカウントかメールボックスかを決めるため、限定パスワードは Account Drive や別メールボックスへ届きません。

Sync devices は同期アプリ向け権限だけを提示します。Billing permissions は含まれません。

Share と purge 権限

利用資格があれば :share と :purge が表示されます。現在の WebDAV route guard はファイル操作を :read と :write だけに対応付けるため、選択しても WebDAV のリンク作成や永久削除コマンドは追加されません。

通常の WebDAV DELETE は :write が必要で、ファイルを Trash へ移します。WebDAV はその場での置換や永久 purge を提供しません。これらには Drive インターフェースを使います。

ファイル名の安全性

名前は各 OS で安全である必要があります。空、パス区切り、制御文字、誤認させる文字、Windows または Unicode 正規化後に衝突する名前は拒否されます。表示文字は最大 255 文字です。

検証エラーならアプリで名前を変えて再試行します。ファイル名にパスを入れて回避しないでください。

チャンクアップロード

小さいファイルは通常の PUT を使えます。Nextcloud chunked-upload v2 対応クライアントは /dav/uploads/{session-uuid}/ にセッションを作り、番号付きチャンクを上げ、MOVE で最終位置へ組み立てます。

制限はデプロイとクライアントで異なります。失敗または期限切れセッションは新規試行として扱います。別クライアントが先に宛先を作った場合、競合応答に従って新しい名前を選ぶかフォルダを更新します。

監査記録

Sync の成功した変更は Drive アクティビティ履歴に表示されます。対象、操作、時刻、使用パスワードを記録し、管理者が調査して該当パスワードを取り消せます。

Drive change feed を使うクライアントは WebDAV の変更も確認できます。完全再同期を求められたら、保存 cursor を続ける前に新しい snapshot からローカルビューを再構築します。

レート制限

Drive Sync リクエストは制限されます。429 を受けたら concurrency を減らし、提供された Retry-After に従い、小さな操作を再試行してからジョブを再開します。

提供状況

Drive Sync は production で利用できます。Drive アクセスが必要で、権限はアカウント、メールボックス、プラン、作成者によって決まります。White Label も同じサービスです。URL は必ず Sync devices からコピーします。

次のステップ

• 利用者向け設定は Drive Sync の概要。
• デバイスパスワード発行 UI は Sync devices。
• REST API と MCP の対応操作は Drive API の概要とDrive API のスコープと権限。
• ストレージとクォータは共有ストレージクォータの説明。