Memories

Memories / 文件

本頁目錄

遠端常駐程式（HTTP/WebSocket 與中繼 RPC）

Memories 可透過下列方式提供相同的訊框式 service::Request 協定：

  1. 本機 IPC（預設；以作業系統使用者驗證；帶有長度前綴的訊框）
  2. HTTP + WebSocket（選用接聽；權杖驗證；與中繼 RPC 相同的二進位 JSON 訊框）
  3. WSS 中繼 RPC（/v1/rpc/{room}/{slot}）

直接與中繼遠端連線共用同一種傳輸格式：WebSocket 二進位訊框先承載 AuthFrame，再承載版本 1 的 Wire（service::Request）。保險庫同步仍使用 /v1/channel。WebUI 維持僅顯示狀態。

安全規則

  • 接聽權杖：--listen-token / MEMORIES_LISTEN_TOKEN，或在啟用 HTTP/中繼主機時產生並顯示一次。切勿將權杖放入 TOML。
  • 儲存區鎖定時會清除權杖。
  • 遠端呼叫端使用固定的權限提升命名空間 ws:remote / relay:remote（與 cli:{pid} 分開）。透過遠端傳輸解鎖及執行 sudo 會提升該命名空間的權限，讓後續單次連線在閒置期限內保有提升的權限（與本機相同：閒置 5 分鐘／最長 15 分鐘）。
  • 桌面 HTTP/中繼主機在解鎖/sudo 後會提供完整的 handle_client 功能（保險庫、卡片、記憶、檔案、憑證、同步、MCP 授權、備份、主機上的代理綁定、遠端工作階段、Run、CryptoJob 等），並受與本機 IPC 相同的權限提升檢查約束。
  • HTTP 接聽預設使用回送介面；非回送介面需要 --allow-non-loopback。
  • 一般 HTTP/WS 不需要憑證（直接區域網路連線的預設方式）。
  • 選用 TLS：--tls-cert / --tls-key（PEM）會在同一個接聽端啟用 HTTPS/WSS。https:// 接聽 URL 必須使用這些旗標。
  • 信任範圍外的中繼必須使用 wss://，並具備 43 字元的房間 ID 和權杖。
  • 持有接聽權杖的任何人，在該傳輸命名空間中都與已提升權限的本機用戶端同樣受到信任。請像密碼一樣保護權杖；優先使用回送介面或經過驗證的網路路徑。

殘餘風險

  • 權杖遭竊 ⇒ 可完全遠端控制已解鎖／提升權限的桌面常駐程式。
  • 非回送 HTTP 會將訊框式 API 暴露到網路；綁定到回送介面以外時，請使用 --tls-cert / --tls-key、反向代理、VPN 或防火牆。
  • 中繼 RPC（/v1/rpc/{room}/{slot}）經過驗證，但沒有端對端加密：其應用層 JSON 訊框先承載共用接聽權杖，再承載請求與回應。中繼營運者或 TLS 終止端可讀取權杖和 RPC 酬載。WSS 保護通往中繼的每條連線，無法防範中繼本身；遠端常駐程式存取應使用可信任的中繼。
  • 保險庫對等同步（/v1/channel）是獨立通道，承載端對端加密的酬載。該通道的中繼營運者只能看見密文長度與時間資訊，看不到資產明文。
  • 主機端代理接聽端仍綁定在常駐程式所在機器的回送介面；遠端用戶端提升權限後可啟動它們，但也必須能連到該主機的回送介面（通常透過另一條通道）才能使用。

HTTP/WebSocket 主機與用戶端

# Host (prints a token once if --listen-token is omitted)
memories daemon --listen http://127.0.0.1:7900
# or HTTPS URL when TLS is configured:
memories daemon --listen https://127.0.0.1:8443 \
  --tls-cert certs/daemon-tls.crt --tls-key certs/daemon-tls.key --listen-token "$TOKEN"

# Client (another shell / machine that can reach the listener)
export MEMORIES_DAEMON=http://127.0.0.1:7900
export MEMORIES_DAEMON_TOKEN="$TOKEN"
memories status
memories unlock
memories sudo
memories vault list

直接 RPC 路徑是 /v1/rpc（WebSocket 升級）。旗標：--daemon、--daemon-token（與環境變數的意義相同）。

用戶端 TLS 信任

預設啟用憑證與主機名稱驗證。全域 --ca-file PATH 選項會將 PEM CA 憑證包中的所有憑證加入一般信任存放區。若常駐程式使用自簽憑證，請明確信任其憑證（其 DNS/IP 主體替代名稱仍必須與 URL 相符）：

memories --daemon https://localhost:8443 --daemon-token "$TOKEN" \
  --ca-file certs/daemon-tls.crt status

# Equivalent CA setting, also usable with relay and HTTPS clients:
export MEMORIES_CA_FILE=certs/daemon-tls.crt
memories --daemon https://localhost:8443 --daemon-token "$TOKEN" status

# DANGEROUS: development only; prefer --ca-file instead.
memories --daemon https://localhost:8443 --daemon-token "$TOKEN" --insecure status

--insecure 會停用憑證鏈與主機名稱驗證。 TLS 加密仍然啟用，但攻擊者可以冒充伺服器並讀取常駐程式權杖、憑證或請求／回應資料。切勿在正式環境或不可信任的網路上使用。此選項僅適用於 CLI（沒有 MEMORIES_INSECURE 環境變數）。即使使用 --insecure，明確指定的 CA 檔案也必須可讀取且含有有效的 PEM 憑證；無效檔案會在連線前失敗。檔案只會在啟動時載入一次；變更憑證包後請重新啟動程序。

這兩個選項適用於目前程序建立的對外連線：直接連線常駐程式的 HTTPS/WSS、中繼 RPC 主機／用戶端、保險庫同步中繼用戶端、雲端 OAuth 與 Drive HTTP、RAG API／模型下載 HTTP、使用憑證驗證的 HTTPS、自動化 webhook，以及資料庫 TLS 工作階段／代理。對於由常駐程式執行的操作，請在啟動該常駐程式時傳入選項；用戶端旗標不會經由 RPC 傳送，也無法變更常駐程式的上游 TLS 政策：

memories --ca-file /path/internal-ca.pem daemon
# Development only: affects every outbound TLS connection in this daemon.
memories --insecure daemon

伺服器的 --tls-cert / --tls-key 與共用權杖驗證保持不變。資料庫的 --tls-ca CA_ID 仍會解析保險庫中的 PEM 憑證；其信任會與常駐程式的 --ca-file 憑證包合併。這兩個選項都不會停用 TLS 或 SSH 主機金鑰釘選。這些旗標不是 TOML 設定，不會作為保險庫機密持久保存，也不會設定行動版／FFI 呼叫端、外部程式／瀏覽器的 TLS 用戶端，或這些 HTTP 建構器之外由相依套件管理的下載。

中繼 RPC 主機與用戶端

# Generate a room id (43 URL-safe characters)
memories sync room

# Host joins slot a
memories daemon \
  --relay-host wss://relay.example.com \
  --room "$ROOM" \
  --listen-token "$TOKEN"

# Client joins slot b
export MEMORIES_DAEMON_RELAY=wss://relay.example.com
export MEMORIES_DAEMON_ROOM="$ROOM"
export MEMORIES_DAEMON_TOKEN="$TOKEN"
memories status

本機開發可搭配 memories-relay 使用 ws://127.0.0.1:8787。

若中繼使用私有 CA，主機與用戶端皆可使用全域旗標：

memories --ca-file /path/relay-ca.pem daemon \
  --relay-host wss://relay.example.com --room "$ROOM" --listen-token "$TOKEN"
memories --ca-file /path/relay-ca.pem --daemon-relay wss://relay.example.com \
  --daemon-room "$ROOM" --daemon-token "$TOKEN" status

行動版 Share（前景主機）

Flutter 應用程式可啟動 Share 工作階段，在已解鎖且位於前景時，以主機身分（插槽 a）加入中繼 RPC。進入背景或鎖定會終止工作階段。行動版保留 FFI 拒絕清單（不允許 Run/CryptoJob/MCP 授權／遠端工作階段／代理，Share 也拒絕複製憑證明文與匯出備份）。手機不會開啟 HTTP 接聽端。請參閱 mobile/README.md。

僅限本機／平台例外

功能 桌面遠端（HTTP/WS / 中繼） 行動版 FFI / Share
保險庫／記憶／卡片／檔案／同步／狀態／解鎖／sudo 完整（必要時需提升權限） FFI 允許的範圍內完整提供
MCP 授權／撤銷、Backup、CredentialCopy 提升權限後完整提供 Share 拒絕；FFI 允許本機複製／備份
Run, CryptoJob, Remote, Proxy 提升權限後完整提供（在主機執行） 拒絕（沒有桌面執行環境）
HTTP/WS 接聽 選用（--listen） 不提供

Persona 自動化 webhook

啟用 HTTP 接聽時，下列端點接受傳入的自動化觸發：

POST /v1/persona/{vault}/{persona}/automation/trigger
Authorization: Bearer <persona world.automation.webhook_token>
Content-Type: application/json

{"hook":"HOOK_ID"}

常駐程式必須已解鎖（與其他寫入 RPC 相同）。接聽權杖啟用 HTTP 功能；自動化 webhook_token（透過 persona automation put --webhook-token 設定）授權該 hook。中繼主機會在中繼上的 POST /v1/persona/{room}/{vault}/{persona}/automation/trigger 收到相同呼叫（相同的主體與 webhook bearer）；房間區段是唯一路徑差異，中繼會將一個既有的 persona_automation_trigger 傳輸訊框轉送到已連線的主機，而不是在本機處理或向外發送 POST。 等效 CLI：

memories persona automation trigger VAULT PERSONA --id HOOK_ID \
  --source webhook --token "$WEBHOOK_TOKEN"