# Ecosystem Approvals And Trust Model

> **Status:** Hardened baseline
> **Owner:** `learning_ai_common_plat`
> **Reference inputs:** `learning_ai_auth_app` (SmartAuth), `learning_ai_trails`, `learning_ai_mac_tooling`, `claw-cowork`
> **Purpose:** Define when the ecosystem should ask for approval, when it should not, and how trust posture affects automation.

---

## 1. Problem

The ecosystem wants fewer user steps, but it also includes:

- sensitive auth flows
- high-autonomy agent execution
- browser and desktop capture
- file manipulation
- scheduled automation
- device-risk signals

Without a shared trust model:

- users get too many prompts
- approvals are inconsistent
- products duplicate policy logic
- high-risk actions may bypass the wrong controls

---

## 2. Design Principle

Ask for approval only when risk or ambiguity justifies it.

That means:

- trusted identity + trusted device + low-risk action = no redundant prompt
- degraded device trust or destructive action = step-up approval
- every approval should create enough context to avoid repeated re-approval for the same safe run

---

## 3. Approval Inputs

The trust model should evaluate at least:

1. actor identity trust
2. device posture
3. action risk level
4. data sensitivity
5. execution mode
6. recent approvals
7. org policy

Signal sources:

- SmartAuth identity state
- Auth App approval device
- mac-tooling risk posture
- ActionTrail policy and replay history
- Cowork unattended/destructive-action policy

---

## 4. Suggested Trust Levels

### Identity trust

- `anonymous`
- `authenticated`
- `strong-auth`
- `step-up-verified`

### Device trust

- `unknown`
- `trusted`
- `degraded`
- `high-risk`

### Action risk

- `low`
- `moderate`
- `high`
- `destructive`

---

## 5. Example Policy Matrix

| Identity      | Device    | Action           | Outcome                              |
| ------------- | --------- | ---------------- | ------------------------------------ |
| strong-auth   | trusted   | low              | auto-allow                           |
| strong-auth   | trusted   | moderate         | allow with audit                     |
| strong-auth   | degraded  | moderate         | require step-up approval             |
| authenticated | trusted   | high             | require approval                     |
| any           | high-risk | high/destructive | block or require explicit escalation |

---

## 6. Approval Reuse Rules

Reuse should reduce redundant prompts without weakening safety.

### Reuse windows

- `single-action`
  - approval applies only to one action invocation
- `run-scoped`
  - approval applies to the current agent run while risk posture remains unchanged
- `session-scoped`
  - approval applies to the current session for the same action class and trust state
- `time-bounded`
  - approval applies for a short explicit window such as 10 to 30 minutes

### Reuse invalidation triggers

An existing approval must be treated as invalid when:

1. device trust degrades
2. identity trust drops
3. action class becomes materially more destructive
4. target resource changes to a higher-sensitivity surface
5. the explicit expiry window is reached

### Fresh-approval-required classes

These actions should always require fresh approval:

- destructive file deletion outside product-owned sandboxes
- unattended desktop or browser execution on a degraded or high-risk device
- credential rotation or auth-factor reset
- irreversible billing or entitlement change
- external sharing or publication of sensitive artifacts

---

## 7. Degraded Device Behavior

When device posture becomes `degraded` or `high-risk` during an active session:

- existing run-scoped approvals should be invalidated
- unattended execution should pause or downgrade to review-only mode
- destructive actions should require step-up or explicit re-approval
- the runtime surface should record why an action is paused or blocked

This behavior should be driven by shared trust inputs rather than product-local heuristics.

---

## 8. Shared Approval Record

```ts
type ApprovalRecord = {
  approvalId: string;
  userId: string;
  productId: string;
  sessionId?: string | null;
  runId?: string | null;
  actionType: string;
  actionRisk: 'low' | 'moderate' | 'high' | 'destructive';
  decision: 'approved' | 'denied' | 'expired';
  approvedAt?: string | null;
  deviceTrustAtDecision: string;
  identityTrustAtDecision: string;
  expiresAt?: string | null;
  reuseScope?: 'single-action' | 'run-scoped' | 'session-scoped' | 'time-bounded';
  reasonCode?: string | null;
};
```

---

## 9. Canonical Approval Payload Expectations

Auth App and other approval surfaces should receive one canonical payload with:

- actor summary
- action summary
- risk class
- trust posture at request time
- scope of the requested approval
- target artifact, run, or resource references
- expiry and reuse details
- human-readable explanation of why approval is required

The payload should be sufficient to render approval UX without product-specific branching for common cases.

---

## 10. First Use Cases

1. Cowork destructive file action approval
2. Cowork unattended scheduled run policy
3. JarvisJr delegated action approval
4. FlowMonk high-autonomy execution approval
5. ecosystem auth step-up via Auth App

---

## 11. ActionTrail Rendering Requirements

ActionTrail should be able to render:

- what action required approval
- what trust state triggered it
- whether approval was reused or freshly granted
- who approved or denied it
- whether device posture changed before completion

This requires preserving approval IDs, trust posture at decision time, and the explanation metadata.

---

## 12. Key Open Decisions

1. How should org admins override consumer defaults?
2. Which mac-tooling risk signals are strong enough to block execution outright?
3. Should the ecosystem require dual confirmation for certain billing or auth changes?

---

## 13. Acceptance Criteria

1. Low-risk repeated actions do not spam the user with prompts when trust is already high.
2. High-risk or destructive actions consistently require approval across products.
3. Auth App can approve an agent action using one canonical approval payload.
4. ActionTrail can render why an approval was required and what trust state triggered it.
5. Device-risk changes can alter approval behavior without changing product-local policy code.

---

## 14. Implementation Checklist

- [x] finalize trust input model
- [x] finalize risk taxonomy
- [x] define approval reuse rules
- [x] define fresh-approval-required action classes
- [x] define degraded-device behavior
- [x] define Auth App approval payload
- [x] define ActionTrail approval rendering requirements
- [ ] define org-policy override model
- [ ] define high-assurance billing/auth dual-confirmation rules

Commits:

- `eae3409` drafted the initial stub
- `617d970` tracked approvals hardening as remaining work
