Mac Access: freeze architecture, identities, and connector-core boundary

[100yenadmin]

Parent epic: #698

Context

PR #697 moves the connector source into evaOS-GUI, but it intentionally preserves the existing Workbench packaging shape. Before two products consume that source, freeze the process, identity, transport, state-ownership, and migration contracts so implementation cannot create a second connector or break macOS permission continuity.

Required change

Create the executable architecture contract for evaOS Mac Access v0.1 and the shared mac-connector-core boundary.

Decisions this issue must lock

1. Exact package layout under packages/mac-access and packages/mac-connector-core, following the repository's 10-child directory limit and pure-logic/IO separation rules.
2. Stable app, helper/XPC, and LaunchAgent identities:
   • com.evaos.mac-access
   • com.evaos.mac-access.helper
   • com.evaos.mac-access.connector if a LaunchAgent remains necessary.
3. Which process owns Keychain material, pairing state, broker-selected binding, local audit writes, TCC status, helper lifecycle, and updates.
4. The authenticated local client protocol used by Workbench.
5. The outbound broker/ws-proxy protocol, message envelope, replay/expiry rules, reconnect behavior, and selected-binding invariants.
6. How the current Python bridge becomes an embedded implementation detail without requiring system Python.
7. Migration from Workbench-owned connector lifecycle to Mac Access ownership without dual listeners, duplicate grants, or TCC prompts.
8. Uninstall, downgrade, rollback, and orphan-process cleanup.

Deliverables

• docs/evaos/mac-access/architecture.md
• docs/evaos/mac-access/threat-model.md
• versioned JSON schemas or TypeScript/Python contract fixtures for local status/action messages and broker control envelopes
• a source-to-target migration table for the PR fix(workbench): own Mac bridge source #697 bridge modules and the Workbench TypeScript call sites
• an Architecture Decision Record explaining why code stays in this repo but ships as an independent product

Verified source references

• package.json — packages/* workspace
• resources/evaos-beta/bridge/src/evaos_desktop_bridge/ — owned connector source after PR fix(workbench): own Mac bridge source #697
• packages/desktop/src/process/services/evaosNativeCompanionStatus.ts — current lifecycle/readiness/pairing owner
• packages/desktop/src/process/bridge/evaosNativeCompanionBridge.ts — safe IPC boundary
• packages/desktop/src/common/evaos/nativeCompanionBoundary.ts — trust-owner contract and canaries
• docs/evaos/native-companion-boundary.md — shell/native authority boundary

Acceptance criteria

1. Every connector module and Workbench call site has exactly one target owner and migration phase.
2. The architecture identifies one and only one TCC/helper/connector owner when Mac Access and Workbench run together.
3. Remote transport is outbound-only and every action is bound to selected customer/device/grant/session scope, nonce, expiry, and audit ID.
4. Normal onboarding has no Workbench, system Python, Homebrew, Tailscale, public listener, port-forward, or terminal dependency.
5. Local IPC authentication, Keychain custody, log redaction, update ownership, rollback, and uninstall behavior are specified with pass/fail invariants.
6. The document defines Off, Ask Every Time, and Full Access, including the default transition from unpaired Off to paired Ask Every Time only after explicit user consent.
7. A threat table covers replay, stale binding, wrong customer, duplicate process, local untrusted client, stolen pairing code, revoked grant, offline broker, helper replacement, downgrade, and crash recovery.
8. The design has a focused contract test plan and names the exact evidence needed before implementation issues can claim completion.

Validation

• architecture review against current PR fix(workbench): own Mac bridge source #697 head or its merged/superseding head;
• schema fixtures parse in every intended consumer language;
• negative fixture table covers every threat listed above;
• git diff --check and documentation checks;
• current-head adversarial architecture review before downstream implementation begins.

Scope and sequencing

Architecture inspection may begin while PR #697 is open. Do not land implementation against a pre-#697 bridge copy. This issue blocks the core, transport, policy, Workbench integration, packaging, and live-proof issues.

Non-goals

• no connector rewrite;
• no public artifact;
• no Workbench v2.1.36 changes;
• no backend mutation before the existing broker/ws-proxy contract is mapped;
• no customer or live runtime mutation.

Proof boundary

This issue proves an executable design only. It does not prove a working app, security, release readiness, pristine-Mac onboarding, or VM-to-Mac control.