Memories

Memories / 文件

本頁目錄

OneDrive 與 Google Drive 授權

CLI 支援瀏覽器登入、加密的本機帳號儲存、狀態查詢、本機登出，以及透過 OneDrive 或 Google Drive 應用程式資料夾，對不可變更的密文物件執行 cloud sync。權杖更新會在後續上傳前持久保存。真實帳號驗證仍待完成。每部裝置每個供應商可連結一個帳號；再次登入時，只有在新授權成功後才會取代該供應商的帳號。

登入前

建置／安裝新版 CLI，並以相同的新版本重新啟動常駐程式：

cargo install --path crates/cli --locked
memories daemon

請在另一個終端機執行常駐程式。在將執行登入的終端機中，視需要解鎖現有資料庫，再執行 memories sudo。每個命令都必須持續使用相同的 --home／MEMORIES_HOME。新的資料庫需要先執行 memories init。請勿將其資料庫檔案移至雲端同步目錄。

程式不隨附 OAuth 應用程式註冊。請使用您自己的註冊；CLI 絕不會要求您的 Microsoft 或 Google 帳號密碼。驗證與同意授權會在瀏覽器中的供應商網站上進行。

OneDrive 註冊

  1. 在 Microsoft Entra ID 中建立應用程式註冊。若同時需要商務與個人 OneDrive，請選擇支援任何組織目錄中的帳號，以及個人 Microsoft 帳號。此用戶端使用 common 租用戶。
  2. 在驗證設定下，新增 Mobile and desktop applications（行動與桌面應用程式）平台，重新導向 URI 為 http://localhost/oauth/callback。這是公開的桌面用戶端，不是 Web 或 SPA 應用程式。請勿為此流程建立用戶端密碼。
  3. 設定委派的 Microsoft Graph 權限 User.Read 與 Files.ReadWrite.AppFolder；登入也會要求 offline_access。組織的同意政策可能需要管理員核准。
  4. 複製應用程式（用戶端）ID，並執行：
memories sudo
memories cloud login onedrive --client-id YOUR_MICROSOFT_CLIENT_ID

回呼使用 http://localhost:PORT/oauth/callback。Microsoft 比對 localhost 重新導向 URI 時會忽略連接埠；路徑必須與註冊相符。接聽器只繫結 IPv4 回送位址。選填的 --port PORT 可選擇固定連接埠；否則由作業系統選擇可用連接埠。

另一種方式是使用 --client-config PATH，其接受含有 client_id 的 JSON 物件。不接受自訂授權／權杖 URL 或機密用戶端密碼。

Google Drive 註冊

  1. 建立／選取 Google Cloud 專案，並啟用 Google Drive API。
  2. 設定 OAuth 同意畫面。若應用程式處於測試模式，請將您的 Google 帳號加入測試使用者。要求 drive.appdata，以及用於帳號識別的 openid、email 與 profile。
  3. 建立類型為 Desktop app（桌面應用程式）的 OAuth 用戶端，然後下載其 JSON 檔案。CLI 預期下載檔案中的 installed 區段，而非 Web 用戶端設定。
  4. 將 JSON 保存在此儲存庫之外，並執行：
memories sudo
memories cloud login google-drive --client-config /path/to/google-desktop-client.json

Windows CMD 範例：

memories cloud login google-drive --client-config "%USERPROFILE%\Downloads\google-desktop-client.json"

回呼使用 http://127.0.0.1:PORT/oauth/callback。桌面應用程式流程支援回送位址回呼；不需要託管回呼伺服器。下載檔案中的端點欄位會被忽略：用戶端使用固定的 Google 官方端點。若提供已安裝應用程式的用戶端密碼，會從 JSON 讀取，絕不透過命令參數傳入。桌面應用程式密碼不能取代 PKCE。

Google 可能讓測試模式應用程式的更新權杖到期（要求非基本範圍時，通常為七天）。請視需要重新授權；發布與供應商驗證要求取決於您的應用程式。

狀態、取消與登出

memories cloud status
memories cloud sync onedrive
memories cloud sync google-drive
memories sudo
memories cloud logout onedrive
memories cloud logout google-drive

狀態會回傳供應商、帳號身分、顯示名稱／電子郵件、存取權杖到期時間，以及是否儲存更新權杖。絕不回傳存取權杖、更新權杖或用戶端密碼。sync_enabled 表示至少已連結一個雲端帳號。object_sync 只報告寄件匣／收件匣數量。cloud sync 會在供應商傳輸前視需要更新權杖；單純存取權杖到期，不代表供應商同意授權已撤銷。 到期時間從權杖交換開始時保守計算；緩慢的網路回應或帳號個人資料查詢不會延長權杖有效期限。

登出會移除本機帳號，並取消該供應商任何待處理登入。不會撤銷 Microsoft 或 Google 伺服器上的同意授權。遠端撤銷請使用供應商的已連結應用程式設定。移除本機記錄也不保證從儲存快照或較舊的本機副本中完成鑑識層級的抹除。

登入有五分鐘的限制。--no-browser 會印出授權 URL 而不開啟瀏覽器，但仍會等待這部電腦上的回呼。這不是帶外／手動代碼流程，也不是遠端／無介面登入機制。 逾時或一般錯誤時，CLI 會取消其待處理票證。強制終止 CLI 後，請等待到期，或在重試前使用 cloud logout PROVIDER。

安全與生命週期

  • OAuth 使用授權碼、S256 PKCE 與不可預測的 state 值。會檢查回呼方法、Host、來源、路徑、重複欄位、state、到期與重放。供應商錯誤與回呼頁面不會回顯代碼或權杖。
  • 瀏覽器等待、權杖交換與身分查詢都在 CLI 程序中執行，位於常駐程式的互斥鎖與資料庫交易之外。HTTPS 請求具有受限的逾時／回應大小、停用自動重新導向，且不繼承環境代理伺服器設定。此初始傳輸設定不支援需要代理伺服器的網路環境。
  • 常駐程式核發綁定至供應商、用戶端 ID 與本機呼叫者的短效票證。儲存時需要再次 sudo；鎖定、重新啟動或登出會使待處理票證失效。延遲到達的 HTTP 結果不能恢復已取消的登入。
  • 本機 CLI 受信任，可執行供應商交換。服務的權杖寫入操作需要有效票證與提權；它不是遠端端點，MCP 也無法使用。沒有權杖讀取命令。
  • 帳號與權杖位於加密的本機狀態中。匯出備份、裝置核准、保管庫同步、稽核輸出與 MCP 皆不包含它們。每部裝置都必須分別登入。雲端登入不會授予保管庫成員資格。
  • 程式擁有的機密緩衝區會清零；如 SECURITY.md 所述，HTTP／URL／JSON 函式庫與作業系統記憶體可能保留暫時副本。

缺少此狀態欄位時仍向下相容。請勿以舊版常駐程式重新開啟並重寫已授權的儲存區：舊版不了解雲端帳號，可能捨棄新欄位，導致需要再次進行雲端登入。

驗證範圍

測試使用本機 HTTP 測試資料驗證兩個供應商的交換、真實回送位址回呼、加密持久保存、呼叫者綁定、重放、鎖定後取消、缺少範圍／更新權杖、錯誤遮蔽、備份排除與 MCP 拒絕。測試傳輸僅供模組內部使用；正式環境端點是固定的 HTTPS。

真實帳號授權需要已註冊的用戶端 ID／設定與使用者同意。未執行該測試前，不會宣稱已驗證任何真實供應商帳號。行動裝置使用下述原生授權流程；真實同意授權仍未驗證。

於 2026-09-09 查核的參考資料：

行動用戶端

雲端按鈕會開啟連線狀態、連結／重新連結、立即同步與中斷連結。同步僅在前景執行。AppAuth 會開啟系統瀏覽器、驗證 state 並產生 PKCE。瀏覽器切至背景會鎖定資料庫。返回後，請先解鎖並再次進行本機授權，再由 Rust 交換代碼。存取與更新權杖由 Rust 驗證／儲存，絕不回傳至 Dart。

請使用各平台專屬的公開用戶端註冊進行建置：

  • --dart-define=MEMORIES_ONEDRIVE_CLIENT_ID=...
  • --dart-define=MEMORIES_ONEDRIVE_REDIRECT_URI=app.memories.memories:/oauth/callback
  • --dart-define=MEMORIES_GOOGLE_CLIENT_ID=...
  • --dart-define=MEMORIES_GOOGLE_REDIRECT_URI=...

未設定用戶端 ID 時，會停用登入並顯示說明訊息。請勿嵌入 Web 用戶端密碼或重複使用桌面回送位址設定。請使用供應商對您的平台、bundle／套件與簽署身分支援的確切原生重新導向。Google iOS 註冊通常使用反向用戶端 ID 配置；Google Android 註冊與重新導向限制有所不同，發布 Android 建置前必須以該供應商支援的原生流程驗證。僅設定 URI 不足以證明支援供應商同意授權。

預設註冊的應用程式配置為 app.memories.memories。若使用其他自訂配置，Android 接受 Gradle 屬性 memoriesOAuthScheme（例如透過 ORG_GRADLE_PROJECT_memoriesOAuthScheme）；iOS 使用 mobile/ios/Flutter/Memories.xcconfig 中的 MEMORIES_OAUTH_SCHEME。配置必須與原生回呼註冊及 Dart 重新導向 URI 相符。同時啟用兩個供應商時，請註冊相容的回呼，或將第二個配置加入原生資訊清單／URL 類型。HTTPS 應用程式／通用連結需要各平台的關聯檔案與原生設定；預設自訂配置建置不會啟用它們。

完成瀏覽器登入不能恢復舊的提權工作階段。取消本機密碼提示會讓雲端授權維持原狀。鎖定／切至背景會取消套用延遲到達的同步結果。網路失敗會保留排程資料，供稍後立即同步；UI 會區分已完成操作，以及仍有待處理工作的限時執行。登出會移除本機權杖，不會移除供應商同意授權或雲端檔案。真實供應商驗證請參閱發布關卡。