> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_07/push_remote_access_operator_diagnostics_guardrails.md). # Push, Remote Access, Tunnel, and Operator Diagnostics Guardrails **Session ID**: `phase07-session06-push-remote-access-and-operator-diagnostics-guardrails` **Status**: Source-backed guardrail baseline **Created**: 2026-05-30 **Scope**: Web Push/VAPID, remote access, Cloudflare Tunnel, and hosted operation diagnostics *** ## Purpose This artifact defines the Phase 07 requirements for push notifications, remote access, tunnels, and operator diagnostics. It records the current posture: browser notifications are local OS notifications only, Web Push is reserved, remote access and tunnels are unavailable or future explicit opt-in, and hosted operation diagnostics expose compact posture only. The artifact routes requirements P07-R017 through P07-R019 to source, tests, docs, and validation evidence. It does not enable push delivery, VAPID private key use, push subscription storage, Cloudflare Tunnel, remote execution, hosted diagnostic agents, production-hosted validation, or trusted erasure. ## Current Source Posture | Surface | Current state | Runtime claim | | --------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------- | | Browser notifications | Local OS notifications behind browser permission and app setting | Local-only notification fallback, not Web Push | | Service worker push handler | Future-compatible bounded handler | No subscription, VAPID key use, or backend route is shipped | | VAPID keys | Reserved environment placeholders | Public key may become browser-visible later; private key stays server-only | | Remote access | Unsupported local route family and unavailable executor posture | No remote executor, relay, or tunnel runtime | | Cloudflare Tunnel | Reserved deploy/tunnel token placeholder | No tunnel is started by source code | | Operator diagnostics | Local server and CLI posture snapshots | Counts, labels, docs paths, and booleans only | ## Push Requirements ### Consent * Push subscription must require explicit user or operator consent before creating, storing, refreshing, or sending a subscription. * Browser notification permission is not push subscription consent. * Local app notification opt-in is not hosted push consent. * Consent must be revocable without disabling core local cockpit workflows. * Denied, default, unsupported, disabled, and granted-local states must remain visible in UI copy. ### VAPID Exposure * `VAPID_PUBLIC_KEY` is reserved future push metadata and may become browser-visible only after Web Push is scoped. * `VAPID_PRIVATE_KEY` is server-only and must never appear in `VITE_` variables, browser bundles, diagnostics, logs, docs examples, exports, archives, replay buffers, or tests except as synthetic leak probes. * `VAPID_SUBJECT` is metadata for a future sender identity and must not be treated as proof that push delivery is active. * Browser-blocked mirrors include `VITE_VAPID_PRIVATE_KEY`; future mirrors for secret-bearing push values must remain blocked. ### Backend Routing * No push subscription endpoint, push send endpoint, push storage table, push queue, push worker, or provider adapter is active in Phase 07. * A future route must be server-mediated, locally authenticated or hosted-auth protected, rate limited, origin checked, and covered by payload tests before it is documented as active. * Route failures must use compact public errors and must not echo request bodies, subscriptions, endpoint URLs, auth headers, keys, prompts, local paths, commands, or replay/export data. ### Unsubscribe and Revocation * Future unsubscribe must revoke the server-side subscription record and stop queued delivery before returning success. * Duplicate unsubscribe or retry calls must be idempotent. * Browser permission revocation, local notification disable, and unsubscribe must be separate states in copy and diagnostics. * Unsubscribe is not trusted unified erasure until Phase 08 defines a complete delete/reset workflow. ### Retention * No push subscriptions are currently stored. * Future subscription retention must have an explicit maximum age and cleanup path. * Delivery attempts, failures, and audit events must avoid raw endpoint URLs, keys, payloads, prompts, local paths, commands, logs, backups, replay buffers, exports, and room payloads. ### Payload Minimization * Push payloads must be minimal labels and safe navigation hints only. * Push payloads must not contain prompts, transcripts, file contents, code, diffs, command bodies, terminal output, secrets, credentials, local paths, raw env dumps, replay buffers, exports, archives, backups, diagnostics, logs, scan payloads, media drafts, War Room payloads, Cloudflare ids, zone ids, tunnel tokens, account identifiers, or historical intake. * Future click targets must be same-origin relative paths or allowed hash/query hints, never external URLs or credential-bearing URLs. ### Visible Local Fallback * Current notifications must describe local OS notifications and in-app toasts. * Missing VAPID keys, absent push backend, denied permission, and unsupported Notification API states must not break local cockpit use. * Docs and UI copy must not imply push delivery, push subscription, or backend routing is active. ## Remote Access and Tunnel Requirements ### Explicit Opt-in * Remote access and tunnels are unavailable unless a future scoped session adds explicit operator opt-in, threat model, authorization, audit, rollback, redaction, and validation. * Core local workflows must remain usable without Cloudflare credentials, tunnel tokens, hosted auth, hosted storage, analytics, push, public replay, or provider credentials. * Any future non-loopback bind, tunnel, or gateway must be distinguished from remote execution. ### Token Handling * `CLOUDFLARE_TUNNEL_TOKEN` is a deploy/tunnel secret and must not be exposed in browser config, diagnostics, health responses, logs, docs examples, exports, replay buffers, archives, or tests except synthetic leak probes. * `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_ZONE_ID`, and `CLOUDFLARE_API_TOKEN` are deploy-only or secret-bearing operational values. * Future tunnel setup must load tokens only at the server or deployment boundary that needs them and must never forward them to the web client. ### Expiration and Revocation * A future remote access grant must have an explicit expiration. * Revocation must stop new sessions and invalidate existing sessions where the provider supports it. * Expired, revoked, unavailable, disabled, and not-configured states must have separate diagnostics labels. * Revocation is not trusted erasure until Phase 08 covers all local and future hosted state. ### Local Auth, Rate Limits, and Origin/CORS * Future remote access must preserve local bearer auth or a stronger hosted identity boundary before sensitive operations are exposed. * Origin/CORS allowlists must be explicit, narrow, and tested. * WebSocket upgrade and HTTP routes must reject unauthorized or untrusted origins at the closest boundary. * Rate limits and abuse controls must apply before any expensive work or sensitive state access. ### Audit and Abuse Controls * Future remote access audit may record reason codes, labels, timestamps, and bounded counts only. * Audit must not record tokens, prompts, commands, terminal output, file contents, local paths, exports, replay buffers, backups, logs, room payloads, or raw request bodies. * Abuse controls must include duplicate action prevention, retry limits, timeout handling, and visible failure states. ### Unsupported States * No file, git, terminal, Docker, Worker, hosted, remote, or tunnel executor is active in Phase 07. * Unsupported route families must return compact deterministic errors. * UI, CLI, docs, and diagnostics must use unavailable, disabled, planned, unsupported, or local-only language instead of shipped-capability language. ## Operator Diagnostics Requirements ### Compact Shape * Hosted operation diagnostics may expose version, status, generated time, local-only booleans, disabled/unavailable runtime booleans, surface labels, requirement labels, blocked payload labels, unsupported claim labels, docs paths, and bounded counts. * Diagnostics must not expose raw values, request bodies, environment values, account ids, zone ids, tunnel tokens, VAPID private keys, subscriptions, local paths, prompts, commands, terminal output, room payloads, logs, backups, exports, archives, replay buffers, scan payloads, or media drafts. ### Local Auth and Loopback * Server diagnostics inherit local bearer auth, CORS, body size, and rate-limit middleware from the local server. * CLI diagnostics must fetch hosted operation posture only from loopback server URLs. * Non-loopback CLI URLs must fail closed with sanitized failure text. * Timeouts, malformed JSON, missing routes, unauthorized responses, and rate limits must be visible but bounded. ### Status Labels Diagnostics use these status labels: | Label | Meaning | | ------------- | ----------------------------------------------- | | `planned` | Requirements exist, runtime is not shipped | | `disabled` | Surface is intentionally off | | `unavailable` | Surface cannot run in this build or environment | | `unsupported` | Surface is not accepted by current API/runtime | | `local_only` | Current fallback stays on the local machine | ### Blocked Payload Labels Hosted operation diagnostics and tests must cover the blocked labels from the Phase 07 hosted payload blocklist, including prompt content, transcripts, file or code content, command bodies, terminal output, secrets, credentials, URL credentials, local paths, raw env dumps, replay buffers, exports, archives, backup payloads, diagnostic payloads, log payloads, scan payloads, media drafts, War Room payloads, Cloudflare account ids, zone ids, tunnel tokens, push subscriptions, and quarantined historical content. ## Environment Requirements * Blank VAPID and Cloudflare placeholders must not change local startup. * `.env.local.example` must contain no real credentials, raw account ids, raw zone ids, raw tunnel tokens, or values copied from private consoles. * Browser-exposed config must stay limited to documented public-client values. * Deploy-only values must remain deploy-only and not browser-visible. * Reserved future values must not be described as active runtime behavior. ## Documentation Requirements * API docs must document `GET /diagnostics/hosted-operations` as local posture diagnostics only. * Hosted services docs must distinguish local notifications from Web Push and optional Worker deployment from remote access or tunnels. * Privacy docs must include push payloads, diagnostic payloads, subscriptions, tunnel tokens, Cloudflare ids, and local operational data in blocked categories. * Environment and deployment docs must say Cloudflare placeholders do not prove active tunnel, public gateway, remote executor, or push delivery. * Release docs must keep production-hosted validation, trusted erasure, mobile certification, WCAG certification, and legacy decommission deferred to Phase 08. ## Phase 08 Handoff Phase 08 owns: * Trusted unified erasure across Worker state, browser hints, archives, memory, settings, replay buffers, exports, diagnostics, logs, backups, valid spool state, workspace files, and future hosted data. * Production-hosted validation for deployed app, deployed Worker, domains, tunnel posture, push provider posture, and release-candidate smoke. * Release hardening, security review, mobile certification, WCAG certification, and legacy decommission. * Any real remote access, tunnel, hosted diagnostic agent, or executor threat model. ## Acceptance Evidence * Protocol contracts expose hosted operation surfaces, requirements, blocked labels, unsupported claims, docs paths, and bounded counts. * Server route returns local authenticated diagnostics with compact planned or unavailable posture. * CLI status and doctor output fetch loopback-only diagnostics and print sanitized status labels. * Web helpers and notification/service worker tests preserve local-only copy and bounded push-adjacent payload handling. * Docs and environment examples align with optional, reserved, server-only, deploy-only, local-first, and no-raw-value posture. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/phases/phase_07/push_remote_access_operator_diagnostics_guardrails.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.