> 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/sessions/phase07-session06-push-remote-access-and-operator-diagnostics-guardrails/spec.md).

# Session Specification

**Session ID**: `phase07-session06-push-remote-access-and-operator-diagnostics-guardrails` **Phase**: 07 - Hosted Services and Analytics Guardrails **Status**: Not Started **Created**: 2026-05-30 **Package**: Cross-package (`packages/protocol`, `apps/server`, `apps/cli`, `apps/web`; docs and env examples) **Package Stack**: TypeScript, JavaScript CLI, Express, React 18, Vite, Vitest, npm workspaces, Markdown docs

***

## 1. Session Overview

This session defines and implements the Phase 07 guardrails for push notifications, remote access, tunnels, and operator diagnostics. It closes the last source-backed guardrail gap before the Phase 07 validation closeout by making the current posture explicit: browser notifications remain local-only, Web Push remains reserved, remote access and tunnels remain unavailable or future opt-in, and hosted-service diagnostics report posture without exposing raw secrets or local developer data.

The work is cross-package. `packages/protocol` should own shared hosted operation vocabulary for push, remote access, tunnels, operator diagnostics, blocked payload labels, unsupported claims, and compact summary shapes. `apps/server` should expose a local authenticated diagnostics route that returns only bounded posture. `apps/cli` should fetch and print that posture from loopback servers only. `apps/web` should keep notification and service worker behavior honest by preserving local notification copy, avoiding push subscription behavior, and documenting unavailable push and remote access states.

This session prepares Session 07 by producing concrete source, tests, docs, and environment evidence for routing requirements P07-R017 through P07-R019. It must preserve core local workflows without VAPID keys, Cloudflare accounts, tunnel tokens, hosted auth, hosted storage, analytics, public replay hosting, remote tunnels, provider credentials, or production-hosted validation.

***

## 2. Objectives

1. Define push subscription, VAPID exposure, backend routing, unsubscribe, retention, payload minimization, and visible local fallback requirements.
2. Define Cloudflare Tunnel or future remote access requirements for explicit opt-in, token handling, expiration, revocation, local auth, rate limits, Origin/CORS, audit, unsupported states, and abuse controls.
3. Add protocol, server, CLI, and web source behavior that reports compact hosted operation posture without enabling push delivery, remote tunnels, or hosted diagnostic agents.
4. Update stable docs, package READMEs, environment comments, and tests so operator diagnostics expose posture only and never raw credentials, account ids, zone ids, tunnel tokens, local paths, prompts, commands, room payloads, logs, backups, or replay/export data.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase07-session01-hosted-services-requirements-and-privacy-baseline` - provides hosted-service routing, local-first fallback rules, variable inventory, and hosted payload blocklist.
* [x] `phase07-session02-hosted-configuration-and-client-exposure-boundaries` - provides hosted config categories, reserved VAPID and Cloudflare variables, diagnostics vocabulary, and browser exposure rules.
* [x] `phase07-session03-hosted-identity-and-authorization-guardrails` - provides authorization, consent, revocation, audit, and hosted identity non-overclaim requirements.
* [x] `phase07-session04-hosted-persistence-and-public-replay-boundaries` - provides retention, deletion, public replay, export, and blocked payload boundaries relevant to push and diagnostics.
* [x] `phase07-session05-analytics-consent-and-payload-controls` - provides analytics consent, opt-out, payload minimization, and blocked diagnostic payload labels.
* [x] `phase02-session06-settings-replay-notifications-and-scan-ux` - provides the current local browser notification and service worker UX baseline.
* [x] `phase06-session05-isolation-boundary-and-sandbox-diagnostics` - provides non-executing local diagnostics and unsupported remote executor posture.

### Required Tools/Knowledge

* Node 20+, npm workspaces, TypeScript 5.9, JavaScript CLI modules, React 18, Vite, Express diagnostics routes, Vitest, Testing Library, and Biome.
* Existing hosted config, identity, persistence, analytics, and isolation patterns in `packages/protocol`, `apps/server`, `apps/cli`, and `apps/web`.
* Current local notification and service worker behavior in `apps/web/src/lib/notifications.ts` and `apps/web/public/sw.js`.
* Current status and doctor diagnostic output in `apps/cli/src/commands/status.js`, `apps/cli/src/commands/doctor.js`, and `apps/cli/src/lib/orchestrationDiagnostics.js`.

### Environment Requirements

* No VAPID keys, push provider account, Cloudflare account, tunnel token, hosted auth, hosted storage, analytics service, or remote endpoint is required.
* Do not read, copy, print, or commit raw values from `.env.local`, hosted consoles, Cloudflare dashboards, push subscriptions, tunnel credentials, room payloads, prompts, command output, local paths, exports, replay buffers, archives, logs, backups, or ignored historical artifacts.
* Use synthetic test records for secret, account, zone, tunnel, path, prompt, command, room, log, backup, and replay leak checks.

***

## 4. Scope

### In Scope (MVP)

* Maintainers can reference a push, remote access, tunnel, and operator diagnostic guardrail spec - add consent, VAPID exposure, routing, unsubscribe, retention, payload minimization, remote opt-in, token handling, revocation, rate-limit, CORS/Origin, audit, unsupported-state, and Phase 08 handoff requirements.
* Protocol consumers can share one hosted operation contract - add planned, disabled, unavailable, surface, requirement, blocked payload, unsupported claim, docs path, summary, and bounded count vocabulary in `packages/protocol`.
* Server diagnostics expose compact posture only - add a local diagnostics builder and route for hosted operations with local auth, existing CORS and rate limiting, compact unavailable errors, and no request-body echo.
* CLI operators can inspect hosted operation posture safely - add loopback-only fetch, compact validation, sanitized failure handling, and status or doctor output for push and remote access guardrails.
* Browser notification behavior stays honest - refine local notification copy, service worker push comments or sanitization, and web helper tests so current source does not imply push backend, push subscription, VAPID key use, or remote access is active.
* Stable docs, package README files, and `.env.local.example` align with the current disabled or unavailable posture for push, remote access, tunnels, and hosted diagnostics.

### Out of Scope (Deferred)

* Shipping a push backend, push subscription endpoint, Web Push delivery service, VAPID private key usage, push subscription persistence, or remote notification worker - *Reason: this session defines guardrails and disabled readiness only.*
* Making Cloudflare Tunnel, remote access, public gateway, remote executor, remote CLI relay, or hosted diagnostic agent active - *Reason: remote access requires a later threat model, authorization, audit, rollback, redaction, rate-limit, and validation scope.*
* Making Cloudflare, VAPID, tunnel, hosted auth, hosted storage, analytics, or provider credentials required for core local server, web, CLI, hooks, adapters, Worker fallback, public demo, replay, export, backup, or diagnostics workflows - *Reason: Phase 07 local-first fallback is mandatory.*
* Uploading prompts, files, command bodies, terminal output, transcripts, tokens, account ids, zone ids, tunnel tokens, broad paths, exports, replay buffers, scan payloads, room payloads, diagnostics, logs, backups, media drafts, or historical intake - *Reason: blocked by the Phase 07 hosted payload privacy blocklist.*
* Closing trusted unified erasure, production-hosted validation, release hardening, mobile certification, WCAG certification, or legacy decommission
  * *Reason: Phase 08 owns those release gates.*

***

## 5. Technical Approach

### Architecture

Use `packages/protocol` as the shared contract owner for hosted operation guardrails. Add a focused `hostedOperations` module with status, surface, requirement, blocked payload, unsupported claim, docs path, summary, and count helpers. The contract should classify push, remote access, tunnel, and operator diagnostic surfaces as planned, disabled, or unavailable without creating runtime activation paths.

In `apps/server`, add a hosted operation diagnostics builder that consumes the protocol summary and optional status input, then wire `GET /diagnostics/hosted-operations` through the existing diagnostics router. The route should inherit local bearer auth, CORS, and rate limiting from the server stack. Unsupported methods should remain compact 501 responses. The response must contain only labels, counts, docs paths, and booleans; it must not include environment values, request bodies, push subscriptions, tunnel tokens, Cloudflare ids, local paths, room payloads, logs, backups, exports, or replay buffers.

In `apps/cli`, extend the existing diagnostics helper instead of creating a new network stack. Fetch hosted operation diagnostics from loopback servers only, validate and compact the response, sanitize all failure text, and surface short status or doctor output. CLI output should help operators understand that push and remote access are not active while avoiding raw values and avoiding remote server probes.

In `apps/web`, preserve local notification behavior and make unavailable states explicit. Notification copy should say browser notifications are local OS notifications, not push delivery. The service worker push handler may stay as a future-compatible handler only if comments and tests make clear that no subscription, backend, VAPID use, or server routing exists. Any push payload handling should be bounded and sanitize navigation targets so future push payloads cannot imply arbitrary remote control.

### Design Patterns

* Protocol-first contracts: shared hosted operation vocabulary starts in `packages/protocol` before server, CLI, or web consumers display it.
* Planned-state scaffolding: source can report unavailable or disabled posture without creating half-wired hosted features.
* Local-only diagnostics: status and doctor probes use loopback diagnostics and sanitized compact response shapes only.
* Negative claim tests: tests assert push delivery, push subscriptions, remote tunnels, remote executors, hosted diagnostic agents, production validation, and trusted erasure are not active.
* Boundary-local redaction: every diagnostics boundary uses bounded labels and counts instead of raw secrets, ids, local paths, room payloads, logs, backups, exports, or replay data.
* Accessible unavailable states: web copy describes unsupported, denied, default, granted-local, disabled, or unavailable states without implying hosted push or remote access.

### Technology Stack

* TypeScript contracts and Vitest tests in `packages/protocol`.
* Express diagnostics route and Vitest route tests in `apps/server`.
* JavaScript CLI diagnostics, status and doctor output, and Node-based tests in `apps/cli`.
* React/Vite browser helpers, local notification tests, service worker static tests, and Testing Library/Vitest tests in `apps/web`.
* Markdown docs under `.spec_system/PRD/phase_07/`, `docs/`, package README files, and `.env.local.example`.

***

## 6. Deliverables

### Files to Create

| File                                                                              | Purpose                                                                                                                             | Est. Lines |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/PRD/phase_07/push_remote_access_operator_diagnostics_guardrails.md` | Source-backed push, VAPID, remote access, tunnel, operator diagnostic, redaction, local fallback, and Phase 08 handoff baseline     | \~260      |
| `packages/protocol/src/hostedOperations.ts`                                       | Shared hosted operation status, surface, requirement, blocked payload, unsupported claim, docs path, summary, and count helpers     | \~260      |
| `packages/protocol/tests/hostedOperations.test.ts`                                | Protocol tests for push, remote access, tunnel, diagnostics vocabulary, summary helpers, blocked labels, and negative claims        | \~180      |
| `apps/server/src/lib/hostedOperations.ts`                                         | Local hosted operation diagnostics builder with planned or unavailable posture and no raw value exposure                            | \~80       |
| `apps/server/tests/hostedOperationsDiagnostics.test.ts`                           | Server diagnostics route tests for auth, CORS, planned/unavailable state, unsupported methods, and synthetic leak prevention        | \~170      |
| `apps/web/src/lib/hostedOperations.ts`                                            | Browser helper copy for local notification posture, push unavailable state, remote access unavailable state, and safe status labels | \~120      |
| `apps/web/tests/hostedOperations.test.ts`                                         | Web helper tests for local-only notification copy, disabled push, unavailable remote access, and no hosted capability implication   | \~130      |

### Files to Modify

| File                                              | Changes                                                                                                                                              | Est. Lines |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `packages/protocol/src/index.ts`                  | Export hosted operation contracts from the package barrel                                                                                            | \~2        |
| `packages/protocol/src/hostedConfig.ts`           | Refine reserved VAPID and Cloudflare/tunnel metadata to point at Session 06 ownership and blocked browser mirrors                                    | \~25       |
| `packages/protocol/tests/hostedConfig.test.ts`    | Assert VAPID private keys, Cloudflare ids, API tokens, and tunnel tokens remain server-only, deploy-only, reserved, or blocked from browser exposure | \~45       |
| `apps/server/src/routes/diagnostics.ts`           | Wire `GET /diagnostics/hosted-operations` through existing local auth, CORS, rate-limit, compact errors, and no request-body echo                    | \~25       |
| `apps/server/src/server.ts`                       | Pass optional hosted operation diagnostics status into the diagnostics router for tests and future local posture overrides                           | \~10       |
| `apps/cli/src/lib/orchestrationDiagnostics.js`    | Add loopback-only hosted operation diagnostics fetch, compact response validation, redaction, and status description helpers                         | \~120      |
| `apps/cli/src/commands/status.js`                 | Print compact hosted operation posture without raw credentials, ids, tokens, paths, payloads, logs, backups, or remote probes                        | \~25       |
| `apps/cli/src/commands/doctor.js`                 | Add hosted operation diagnostics availability checks and unavailable-state messaging without treating push or remote access as active                | \~35       |
| `apps/cli/tests/orchestrationDiagnostics.test.js` | Cover hosted operation diagnostics fetch, compaction, non-loopback rejection, sanitization, and malformed response handling                          | \~100      |
| `apps/cli/tests/cliRuntime.test.js`               | Cover status or doctor output for hosted operation posture without leaking synthetic sensitive values                                                | \~80       |
| `apps/web/src/lib/notifications.ts`               | Refine local notification copy and payload handling so current behavior does not imply push subscription or backend delivery                         | \~30       |
| `apps/web/public/sw.js`                           | Clarify future push handler posture and bound/sanitize push payload fields and click targets                                                         | \~35       |
| `apps/web/tests/notifications.test.ts`            | Add regression coverage that notification copy remains local-only and push-adjacent payload fields are bounded                                       | \~45       |
| `.env.local.example`                              | Align VAPID and Cloudflare tunnel comments with Session 06 optional, reserved, server-only, deploy-only, and no-raw-value posture                    | \~30       |
| `docs/api/README_api.md`                          | Document `GET /diagnostics/hosted-operations` as local planned-state diagnostics, not push, tunnel, or hosted agent runtime                          | \~25       |
| `docs/hosted-services.md`                         | Add push, remote access, tunnel, and operator diagnostic guardrails with local-first fallback and unsupported states                                 | \~60       |
| `docs/privacy-and-security.md`                    | Add push/diagnostics blocked payload categories, credential boundaries, retention, local fallback, and no raw-value guarantees                       | \~45       |
| `docs/ARCHITECTURE.md`                            | Document hosted operation diagnostics as protocol-first planned-state contracts with no remote executor or tunnel runtime                            | \~35       |
| `docs/environments.md`                            | Clarify VAPID, Cloudflare, tunnel, and diagnostics variables remain optional, reserved, deploy-only, or server-only                                  | \~45       |
| `docs/deployment.md`                              | Clarify Cloudflare Worker, Pages, custom domains, and tunnel placeholders do not prove active remote access or push delivery                         | \~35       |
| `docs/release.md`                                 | Add push/remote/diagnostic release guardrails, negative-claim checks, and Phase 08 validation and erasure deferrals                                  | \~40       |
| `packages/protocol/README_protocol.md`            | Document hosted operation contract ownership and future consumer rules                                                                               | \~30       |
| `apps/server/README_server.md`                    | Document hosted operation diagnostics route, local auth inheritance, redaction, and unavailable state                                                | \~30       |
| `apps/cli/README_cli.md`                          | Document CLI hosted operation diagnostics output, loopback-only probes, and no remote tunnel or hosted agent behavior                                | \~35       |
| `apps/web/README_web.md`                          | Document local notification posture, push unavailable state, and no remote access UI behavior                                                        | \~35       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Push requirements define subscription consent, VAPID public/private key exposure boundaries, backend routing, unsubscribe, retention, payload minimization, disabled default, and visible local fallback.
* [ ] Remote access requirements define explicit opt-in, token handling, expiration, revocation, local auth, rate limits, Origin/CORS, audit, unsupported states, abuse controls, and no remote executor.
* [ ] Protocol hosted operation contracts expose status, surface, requirement, blocked payload, unsupported claim, docs path, bounded counts, and summary helpers.
* [ ] Server hosted operation diagnostics expose compact planned or unavailable posture through a local authenticated diagnostics route.
* [ ] CLI status or doctor output reports hosted operation posture from loopback diagnostics only and never prints raw credentials, account ids, zone ids, tunnel tokens, paths, prompts, commands, room payloads, logs, backups, exports, or replay buffers.
* [ ] Web notification copy and service worker handling keep browser notifications local-only and do not imply push subscription, backend delivery, VAPID usage, remote access, hosted diagnostics, or trusted erasure.

### Testing Requirements

* [ ] Protocol tests written and passing for hosted operation vocabulary, summary helpers, blocked payload labels, unsupported claims, and uniqueness.
* [ ] Server diagnostics route tests written and passing for auth inheritance, CORS, planned/unavailable posture, unsupported methods, and synthetic leak prevention.
* [ ] CLI tests written and passing for loopback-only fetches, compact output, malformed response handling, and redaction.
* [ ] Web tests written and passing for local-only notification copy, push unavailable states, bounded push payload handling, and remote access unavailable copy.
* [ ] Focused typechecks or equivalent package checks run for changed TypeScript packages, with skipped-check rationale recorded if needed.

### Non-Functional Requirements

* [ ] Core local workflows start, hydrate, export, replay, scan, run hooks, run CLI diagnostics, and use War Room fallback without VAPID, Cloudflare, tunnel, hosted auth, hosted storage, analytics, public replay, remote access, or provider credentials.
* [ ] Diagnostics responses and CLI output remain bounded, deterministic, and redacted at every boundary.
* [ ] Push and remote access surfaces remain disabled, unavailable, or explicitly future opt-in until a later scoped implementation ships.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] `git diff --check` passes for changed files.

***

## 8. Implementation Notes

### Key Considerations

* The current web service worker includes a future-compatible `push` event handler. This session should make that posture explicit and bounded without introducing push subscription, VAPID use, or backend delivery.
* `CLOUDFLARE_TUNNEL_TOKEN`, account ids, zone ids, and API tokens are deploy-only or secret-bearing values. They must never appear in browser config, diagnostics, CLI output, docs examples with real values, logs, exports, archives, replay buffers, or tests except as synthetic leak probes.
* CLI diagnostics should stay local and loopback-only. Non-loopback URLs must fail closed with sanitized messages.
* Remote access is not remote execution. Do not soften the existing non-executing guarded-action and isolation posture.

### Potential Challenges

* Service worker test coverage: `apps/web/public/sw.js` is a plain public asset, so implementation may need a lightweight static test or helper extraction to validate bounded push payload behavior.
* CLI output drift: status and doctor tests should assert posture labels, not brittle full command output.
* Diagnostics shape growth: summaries should expose counts and labels only, avoiding nested raw objects that future features might fill with unsafe values.
* Docs overclaim: deployment and environment docs must distinguish optional Cloudflare Worker settings from remote access, tunnels, hosted diagnostics, hosted identity, production validation, and trusted erasure.

### Relevant Considerations

* \[P06] **Unified erasure still missing**: Do not call unsubscribe, local reset, diagnostics cleanup, Worker leave, or tunnel revocation trusted erasure.
* \[P03] **Real executors remain unimplemented by design**: Remote access must not imply file, git, terminal, Docker, Worker, hosted, or tunnel execution.
* \[P03-apps/cli+apps/hooks] **Lifecycle state is local and file-based**: CLI diagnostics must keep crash recovery and stale-state output local and compact.
* \[P00] **Hosted services are optional**: Core local workflows must work without VAPID, Cloudflare, tunnel, hosted auth, hosted storage, analytics, public replay, or provider credentials.
* \[P05] **Redaction is boundary-specific**: Push payloads, diagnostics, tunnel metadata, Worker payloads, exports, archives, logs, backups, and replay buffers need explicit minimization at their own boundaries.
* \[P03] **Local-first boundary is architectural**: Server, web, CLI, hooks, adapters, analytics, backups, logs, and Worker integrations must degrade cleanly when remote services are absent.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Diagnostics accidentally expose raw secrets, account ids, zone ids, tunnel tokens, local paths, prompts, commands, room payloads, logs, backups, exports, or replay buffers.
* Browser notification or service worker copy implies push delivery, push subscription, VAPID use, remote access, hosted diagnostics, or trusted erasure is active.
* CLI diagnostics probe non-loopback URLs, print raw failure details, or treat unavailable push and remote access posture as a failure of local operation.

***

## 9. Testing Strategy

### Unit Tests

* Protocol tests for hosted operation statuses, surfaces, requirements, blocked payload labels, unsupported claims, docs paths, summary counts, and uniqueness.
* Web helper and notification tests for local-only copy, push unavailable posture, bounded payload fields, safe click targets, and no hosted capability implication.
* CLI diagnostics tests for compact parsing, non-loopback rejection, sanitization, malformed responses, and output labels.

### Integration Tests

* Server route tests for `GET /diagnostics/hosted-operations` with local auth, CORS, rate limiting inherited from app setup, planned/unavailable states, synthetic sensitive environment records, and unsupported method handling.
* CLI status or doctor runtime tests against a local test server fixture that returns hosted operation diagnostics.

### Manual Testing

* Run focused CLI status or doctor command against a local server and confirm the output says push and remote access are unavailable or disabled while local workflows remain usable.
* Open Settings notification states, if touched, and confirm the copy still distinguishes unsupported, default, denied, granted-local, and disabled browser notification states without hosted push claims.

### Edge Cases

* Missing, blank, malformed, or secret-like VAPID and Cloudflare variables.
* Non-loopback diagnostics URLs, timeouts, invalid JSON, unauthorized routes, missing routes, and malformed hosted operation snapshots.
* Push payloads with long strings, URL credentials, external URLs, unknown fields, local paths, token-like values, and missing payload data.
* Docs examples that could be mistaken for real Cloudflare, VAPID, tunnel, or hosted diagnostic activation.

***

## 10. Dependencies

### External Libraries

* No new runtime libraries are required.
* Existing workspace dependencies: TypeScript, Vitest, Testing Library, Express, React 18, Vite, Biome, and npm workspace scripts.

### Other Sessions

* **Depends on**: `phase07-session01-hosted-services-requirements-and-privacy-baseline`, `phase07-session02-hosted-configuration-and-client-exposure-boundaries`, `phase07-session03-hosted-identity-and-authorization-guardrails`, `phase07-session04-hosted-persistence-and-public-replay-boundaries`, `phase07-session05-analytics-consent-and-payload-controls`.
* **Depended by**: `phase07-session07-hosted-guardrails-validation-and-documentation-closeout`.

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# 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/sessions/phase07-session06-push-remote-access-and-operator-diagnostics-guardrails/spec.md?ask=<question>&goal=<endgoal>
```

`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.