Hybrid Security Gates¶

Open Cowork can now run as Desktop, Cloud Web, Standalone Gateway, Cloud Channel Gateway, Desktop pairing, or a full hybrid of those surfaces. This page defines the production security gates for those modes. It complements Deployment Topologies: topologies say what you are deploying; security gates say which auth, policy, audit, quota, redaction, and restore behavior must be true before that topology is exposed to users.

The machine-readable contract lives at deploy/security/hybrid-security-gates.json. pnpm deploy:validate and pnpm ops:validate verify that the contract, docs, and code evidence stay in sync.

Non-Negotiable Rules¶

• Open Cowork is a product layer on top of OpenCode, not a second runtime.
• Every thread has one execution authority at a time: desktop_local, cloud_worker, or gateway_standalone.
• The Gateway is either a standalone execution owner or a Cloud channel adapter; it must not silently switch roles.
• Remote approvals for Desktop-owned execution default to local_confirmation.
• remote_allowed is an explicit, scoped policy decision. Missing policy falls back to requires_local_confirmation or blocked_by_policy, never remote approval.
• A Gateway service token authenticates the Gateway process only. It does not grant the channel actor approval authority.
• Public provider callbacks require provider signing, HMAC, or equivalent shared-secret verification.
• Production modes fail closed without TLS, admin token, durable stores, backup/restore posture, and redaction posture.

Gate Matrix¶

Approval And Question Policy¶

Approval and question behavior follows the execution authority that owns the thread.

For desktop-local, there is no remote approval path. The local Desktop user answers OpenCode approvals and questions.

For desktop-pairing, Desktop remains the authority. The default remote approval and question policy is local_confirmation. A remote client may send a prompt or response request, but Desktop returns requires_local_confirmation until a local user confirms it. remote_allowed may be used only when all of these are true:

• the pairing policy explicitly enables it;
• the actor, workspace, session, and action risk are in scope;
• revocation and lease fencing are active;
• the action is written to the local audit log;
• redaction still blocks raw provider keys, local paths, local MCP details, and artifact bodies unless policy explicitly allows them.

For cloud-worker, Cloud membership, role, profile policy, subscription/quota state, and runtime policy decide approval and question authority. Remote approval and question responses require allowRemoteApprovalResponses: true in the effective cloud runtime policy. Pending permissions and questions must be present in durable projection state so late-join clients can recover after restart.

For standalone-gateway, the channel actor must resolve to Gateway RBAC before approvals or questions can be answered. Approval tokens are single-use and replay protected.

For cloud-channel-gateway, the Gateway service token proves the process is allowed to call Cloud APIs. It does not prove that the human or channel actor is allowed to approve a permission. Cloud must resolve provider identity and check membership/RBAC before accepting approval or question replies.

Auth And Revocation¶

Every connector has an explicit auth and revocation contract:

• Desktop local: preload whitelist plus main-process project grants.
• Desktop pairing: bearer pairing token, pairing id, device id, command leases, and pairing revocation.
• Standalone Gateway: admin token for operator endpoints, private OpenCode endpoint, provider signing or HMAC for public ingress, and provider credential rotation.
• Cloud worker: OIDC, signed trusted header auth, cookie auth, or scoped API token; membership and API-token revocation block new mutations.
• Cloud Channel Gateway: scoped gateway service token plus separate inbound actor identity resolution; channel binding and token revocation stop routing.
• Cloud Gateway Edge: registration tokens, heartbeat, lease fencing, and explicit customer_hosted_managed_saas_deferred review before managed SaaS claims are made.

Audit Taxonomy¶

Security-sensitive actions must be auditable in the authority that owns them. The gate contract lists the minimum audit events for each mode. The taxonomy includes:

• pairing lifecycle: pairing.created, pairing.updated, pairing.enabled, pairing.disabled, pairing.connected, pairing.offline, pairing.revoked;
• remote commands: command.accepted, command.completed, command.failed, command.blocked, remote.event.published;
• provider ingress: provider.ingress.accepted, provider.ingress.rejected;
• approvals and questions: permission.requested, permission.responded, question.asked, question.replied;
• Cloud control plane: org.created, membership.created, api_token.created, api_token.revoked, byok.secret.updated, quota.rejected;
• channel operations: gateway.registered, gateway.revoked, channel.binding.created, channel.binding.revoked, delivery.sent, delivery.dead_lettered;
• edge operations: gateway.registration.heartbeat, gateway.edge.write_fenced_output.

Audit rows must not contain raw provider keys, OAuth tokens, MCP secrets, channel secrets, local file contents, or sensitive local paths.

Quotas And Rate Limits¶

Production deployments must apply rate limits at every public or remotely reachable boundary:

• Cloud: IP, token, user, org, workspace, worker-spawn, prompt, and workflow limits.
• Gateway: provider ingress, channel actor, delivery retry, dead-letter, and operator endpoint limits.
• Desktop pairing: pairing command, broker command lease, and remote event publish limits.
• Edge registration: heartbeat, command, and fenced write limits.

Where the protocol supports it, throttles return Retry-After. Quota denials should be clear: 402 for billing/entitlement failures and 429 for rate limits.

Durability, Backup, And Restore¶

Production security posture includes recovery posture:

• Cloud requires Postgres, provider-backed object storage, secret-manager/KMS references, worker checkpoints, event logs, and session projections.
• Standalone Gateway requires Gateway Postgres, artifact storage where file ingress is enabled, channel credential secret storage, delivery cursors, and dead-letter retention.
• Desktop pairing requires Desktop pairing records, broker command log, broker event cursor, and local audit records.
• Full hybrid restore drills prove that authority boundaries survive restore and that no local data is uploaded implicitly.

Restore evidence must include redaction review. Use Backup and Restore and Restore Drill Report as the operator templates.

Redaction Requirements¶

Diagnostics, logs, caches, dashboards, audit rows, and channel messages must redact:

• raw provider keys and BYOK plaintext;
• OAuth access and refresh tokens;
• MCP secrets;
• channel provider secrets and signing tokens;
• private artifact URLs unless the actor is authorized;
• local host paths and local file bodies unless explicitly uploaded through a Cloud-safe artifact flow;
• raw Gateway database state, raw OpenCode runtime homes, and gateway private files in Cloud registration payloads.

The default posture is metadata over contents. If a deployment chooses to expose richer fields, that exposure must be explicit in policy and covered by audit.

Fail-Closed Validation¶

pnpm deploy:validate checks the gate contract and cross-references code evidence for the following fail-closed behavior:

• Desktop pairing defaults to local_confirmation.
• Desktop pairing can return requires_local_confirmation and blocked_by_policy.
• Public Cloud does not trust unsigned header auth.
• Public Cloud fails closed without Postgres, provider-backed object storage, production secrets, auth, and worker checkpoints.
• Gateway operator endpoints require an admin token.
• Gateway webhook ingress requires provider signing, HMAC, or a shared secret.
• Gateway fake provider is local/demo-only.
• Gateway rejects public OpenCode endpoints.
• Cloud and Gateway throttles expose Retry-After.
• Full hybrid requires one execution authority per thread.

pnpm ops:validate checks that the operations artifacts include the gate contract, backup/restore posture, topology docs, observability assets, and mode-aware runbook references.