todo(profile): redesign profile management with ClawPal as SSOT and no secret reads from remote OpenClaw

[Akane-CN]

TODO: Refactor profile management to ClawPal-first SSOT (no secret pull from remote OpenClaw)

Context

Current profile/auth flows still have mixed authority between ClawPal and remote OpenClaw instances in some paths. This creates ambiguity and security risk, especially around secret resolution and sync behavior.

Goal

Refactor profile management so that ClawPal is the single source of truth (SSOT) for profile definitions and credential intent, then distribute to OpenClaw targets as needed.

Hard rule:

• ClawPal must never read/pull secrets from OpenClaw running on VPS/remote hosts.

Requirements

1. SSOT ownership model

   • Profiles are authored and stored in ClawPal domain.
   • Remote OpenClaw receives derived/configured outputs only.
   • No reverse-sync of secrets from remote OpenClaw back to ClawPal.

2. Secret handling boundary

   • Secret ingestion happens only on trusted ClawPal side.
   • Remote sync can push needed secret material (or references), but must not fetch remote secret stores.
   • Remove/disable any code paths that attempt remote secret discovery for profile resolution.

3. Deterministic distribution

   • Define a clear projection model from ClawPal profile -> remote OpenClaw config/auth store.
   • Include idempotency guarantees and conflict behavior.

4. Migration/backward compatibility

   • Provide migration path for existing installs using remote-derived auth/profile behavior.
   • Add explicit behavior flags if staged rollout is needed.

5. Observability and auditability

   • Record profile distribution events and outcomes.
   • Expose clear diagnostics for “what was pushed”, “when”, and “why”.

Deliverable requested in this issue

Please produce a complete design before implementation, including:

• Problem statement + threat model
• Source-of-truth architecture
• Data model / schema changes
• API contracts (create/update/list/distribute)
• Secret boundary and trust assumptions
• Sync protocol (idempotency, retries, partial failure handling)
• Migration plan and rollback strategy
• Test plan (unit/integration/e2e)
• Operational runbook and success metrics

Acceptance criteria (for design phase)

• Design doc is complete and implementation-ready
• Explicitly proves “no secret read from remote OpenClaw VPS”
• Defines transition strategy for existing users
• Defines verification strategy and CI coverage expectations

[Akane-CN]

Design decisions confirmed (from discussion), plus v1 architecture draft.

Confirmed decisions

1. Remote plaintext secrets are allowed when needed.
2. If remote OpenClaw CLI supports non-plaintext secret mode, prefer non-plaintext mode.
3. Distribution strategy: incremental apply.
4. Drift handling: warn-only by default; overwrite only after explicit user confirmation.
5. A single profile can be distributed to multiple OpenClaw targets.

---

v1 Design (implementation-oriented)

1) Ownership and trust boundary

• ClawPal remains the single source of truth for profile specs and credential intent.
• Remote OpenClaw instances are execution targets receiving projected config.
• No reverse authority: remote state never becomes SSOT.
• Hard rule preserved: do not read secrets from remote OpenClaw for back-sync.

2) Data model

• ProfileSpec (SSOT)
  • id, name, provider, model, enabled, options
  • credential mode (manual, oauth, env/ref, etc.)
  • revision metadata
• SecretMaterial (ClawPal side)
  • key id/ref + metadata
  • encryption-at-rest managed by ClawPal side
• ProfileProjection (per target)
  • targetId
  • profileId
  • lastAppliedRevision
  • applyMode (plaintext | ref)
  • status (ok, degraded, failed, drifted)
  • lastError / updatedAt

3) Capability-aware distribution

Before apply, probe target capability:

• supportsSecretRef (or equivalent non-plaintext path)
• supportsAuthProviderConfig fields
• fallback behavior support

Apply mode selection:

• If capability supports non-plaintext secret reference => use non-plaintext mode.
• Else fallback to plaintext write (explicitly audited).

4) Incremental apply protocol

Per target, per profile:

1. Compute delta from lastAppliedRevision to new revision.
2. Build minimal patch payload (profile fields + credential projection for that profile only).
3. Apply patch idempotently.
4. Update projection status and revision checkpoint.

Properties:

• idempotent retries
• partial-failure isolation (one profile/target fail does not block all)
• resumable apply queue

5) Drift policy

• Scheduled/on-demand drift check compares non-sensitive structure between SSOT projection and target runtime config.
• Default action: mark drifted + warning.
• User can trigger confirmed overwrite (force re-apply from SSOT).

6) Multi-target profile fanout

• Same profile may fan out to N targets.
• Projection status tracked independently per target.
• UI should show matrix view: profile x target state.

7) Security and audit

• Never ingest secret values from remote targets.
• Log distribution events with:
  • actor
  • profileId / targetId
  • mode chosen (plaintext vs ref)
  • success/failure + reason
• Do not log secret payload values.

8) Migration plan

Phase A (compat mode):

• Introduce SSOT model + projection tracking.
• Keep legacy behavior behind feature flag.

Phase B (enforcement):

• Disable/remove any remote secret read path.
• Route all profile changes through SSOT pipeline.

9) Validation plan

• Unit: revision diff, mode selection, drift detection, overwrite gate.
• Integration: capability probe + apply fallback.
• E2E:
  • target supports non-plaintext -> ref mode used
  • target lacks support -> plaintext mode with audit trace
  • drift warning then explicit overwrite path
  • one profile to multiple targets fanout

If this direction is accepted, next step is to split into implementation tasks (data model, capability probe, apply engine, drift checker, UI matrix) and execute in sequence.

[Akane-CN]

已将 #94 拆分为 7 个 implementation 子任务（按依赖顺序）：

1. todo(profile): [94-1] 设计冻结：SSOT + 威胁模型 + 同步协议 #98
2. todo(profile): [94-2] 数据模型重构：ClawPal 侧 SSOT schema #99
3. todo(profile): [94-3] Secret Boundary 实装：禁用 remote secret 读取 #100
4. todo(profile): [94-4] 分发引擎：Deterministic Projection + Idempotent Apply #101
5. todo(profile): [94-5] 应用层 API 与前端流程改造（CRUD + distribute） #102
6. todo(profile): [94-6] 迁移与灰度：兼容旧安装 + 回滚策略 #103
7. todo(profile): [94-7] 可观测性 + 测试闭环 + 运行手册 #104

建议执行顺序：94-1 -> 94-2 -> 94-3 -> 94-4 -> 94-5 -> 94-6 -> 94-7

[dev01lay2]

Code-grounded Design Review

After reading the actual implementation (primarily src-tauri/src/commands/profiles.rs and clawpal-core/src/profile.rs), the direction here is correct, but the design doc needs a few concrete decisions filled in before implementation can begin without ambiguity.

---

1. The Specific Violating Paths

The issue describes the problem in principle. Here are the three concrete paths that need explicit handling in the design:

Path 1 — remote_sync_profiles_to_local_auth (the main offender)
This function reads the remote ~/.clawpal/model-profiles.json via SFTP, calls resolve_remote_profile_api_key for each profile to pull secrets from the remote auth store / shell env, and then writes those resolved keys into local ClawPal storage. This is the most direct secret-pull-from-remote path.

Path 2 — remote_resolve_api_keys
Reads remote profiles and returns masked key representations — still an outbound read of remote credential state.

Path 3 — Dual-authority on ~/.clawpal/model-profiles.json
remote_upsert_model_profile writes ClawPal profile files to the remote host. remote_list_model_profiles reads them back. The remote file has become a second authority source — this is the structural root of the ambiguity the issue is trying to resolve.

The design doc should explicitly list these three paths and state their disposition: delete / refactor / keep-with-constraints.

---

2. Missing Decision: Role of ~/.clawpal/model-profiles.json on Remote Hosts

The issue says ClawPal is SSOT but doesn't define what happens to the remote copy of this file. Two options:

• Option A: Remote hosts no longer store ClawPal-format profiles. ClawPal only pushes derived OpenClaw config (auth store entries + model bindings into openclaw.json). Remote ClawPal file is deprecated.
• Option B: Remote keeps model-profiles.json as a write-only cache, populated exclusively by ClawPal pushes, never read back for secret resolution.

This decision determines whether remote_upsert/list/delete_model_profile are deleted, refactored, or kept as push-only primitives. Without this, the implementer has to decide on the fly.

---

3. Missing Decision: What Gets Pushed to Remote OpenClaw?

The issue says "distribute to OpenClaw targets" but doesn't define the target format. The existing resolve_auth_ref_for_provider function reads from openclaw.json's auth store. Depending on what ClawPal pushes, you could still end up with secrets landing on the remote disk:

• Push plaintext key → key lands in remote openclaw.json or auth store (still a secret on remote disk, higher risk)
• Push authRef pointer + SecretRef → remote OpenClaw resolves its own secret locally (preferred, no secret crosses the wire)
• Push derived short-lived token → acceptable for OAuth flows, needs explicit handling

The design doc should select one of these and justify it. The SecretRef path (option 2) aligns best with the work already done in PR #75 and PR #80.

---

4. remote_test_model_profile Needs a Replacement Model

This command currently resolves the API key from the remote host and then runs a provider probe locally. Under the new model, ClawPal won't hold the remote secret. Two alternatives:

• Push-and-probe: Push the profile config to remote, invoke openclaw models list over SSH to let the remote OpenClaw run the probe using its own credentials.
• Local-key-only: Only test profiles whose keys are stored in local ClawPal; skip or surface a clear error for remote-auth-ref-only profiles.

The design should specify which approach and what the UI surfaces when a profile can't be tested locally.

---

5. Migration Is More Disruptive Than the Issue Implies

The current user flow is:

1. User has API keys on a remote machine (in shell env or auth.json)
2. remote_sync_profiles_to_local_auth pulls them into ClawPal
3. User manages from ClawPal

Removing step 2 is a breaking change for existing users. A feature flag alone isn't sufficient — users will silently lose their profiles if they upgrade without an active migration step.

Suggested addition to migration plan:

• A one-time active import tool: scan remote auth stores, surface keys to the user for manual confirmation in ClawPal (user explicitly copies the key into ClawPal — no silent pull)
• Or a CLI command clawpal profile import --from-remote <host> that is explicitly user-triggered, deprecated in the next minor, and removed after one release cycle
• Upgrade path must handle the case where remote_sync_profiles_to_local_auth has already been called — those locally-cached keys should be detected and users prompted to "confirm ownership" of them in the new model

---

Summary

The issue's direction is correct and necessary. To make the design doc implementation-ready, it needs:

1. Explicit disposition of the three violating code paths (delete / refactor)
2. Decision on remote ~/.clawpal/model-profiles.json (deprecate vs. write-only cache)
3. Selection of push format (SecretRef pointer recommended, aligned with PR fix: support OpenClaw SecretRef in profile sync credential resolution #75/feat: push only related secrets to remote openclaw #80 work)
4. Replacement design for remote_test_model_profile
5. Active migration tool for users who have been using remote_sync_profiles_to_local_auth

Without these decisions documented upfront, the implementer will hit the same kind of path-divergence issues seen in PR #75's SecretRef resolution inconsistency.