> 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-session03-hosted-identity-and-authorization-guardrails/spec.md).

# Session Specification

**Session ID**: `phase07-session03-hosted-identity-and-authorization-guardrails` **Phase**: 07 - Hosted Services and Analytics Guardrails **Status**: Completed **Created**: 2026-05-30 **Package**: Cross-cutting (`apps/server`, `apps/web`, `packages/protocol`; docs) **Package Stack**: TypeScript, Express, React 18, Vite, Vitest, npm workspaces, Markdown docs

***

## 1. Session Overview

This session defines the hosted identity and authorization guardrails that Phase 07 requires before any account-backed claim can be made. It turns the Session 01 baseline, Session 02 hosted-config boundary, and Phase 06 room-authority carryforward into a source-backed identity posture: hosted account lifecycle is planned, explicit, and local-first, while War Room authority remains only room-scoped bearer proof.

The work is cross-package but intentionally does not ship production hosted auth. `packages/protocol` should own shared identity status vocabulary, authorization-surface labels, role/audit requirements, unsupported/planned states, and non-overclaim checks. `apps/server` should expose only compact local diagnostics for the planned identity posture, behind existing local auth. `apps/web` should expose helper copy and state labels that make account-backed identity unavailable or planned without creating hosted account UI.

The session also updates stable docs so future hosted persistence, analytics, public replay, push, remote access, diagnostics, and release work can reference one clear identity baseline. It must preserve core local workflows without Supabase, OAuth providers, hosted accounts, Cloudflare credentials, Worker URL, analytics, hosted storage, public replay hosting, push, remote access, or production-hosted validation.

***

## 2. Objectives

1. Define hosted account lifecycle requirements for sign-in, session expiry, revocation, logout, consent, local-only fallback, export, and deletion handoff.
2. Define authorization boundaries for account data, War Room participation, hosted storage, analytics preferences, public replay, push, remote access, and operator diagnostics.
3. Add protocol, server, and web scaffolding that reports hosted identity as planned or unavailable without enabling OAuth, SSO, organization management, billing, or hosted account UI.
4. Update API, architecture, privacy, hosted-service, environment, deployment, release, War Room, and package README docs so room-local Worker authority is never described as hosted identity or production audit proof.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase07-session01-hosted-services-requirements-and-privacy-baseline` - provides hosted identity routing, payload blocklist, local-first fallback checks, and Phase 08 deferrals.
* [x] `phase07-session02-hosted-configuration-and-client-exposure-boundaries` - provides hosted config categories, browser/server exposure boundaries, diagnostics patterns, and tests.
* [x] `phase06-session02-room-authority-and-participant-identity-contracts` - provides room-local authority, role, revision, idempotency, and authority error semantics.
* [x] `phase06-session07-collaboration-isolation-and-mobile-validation-closeout` - provides current security posture, local browser evidence, hosted identity residual risk, and trusted erasure deferral.
* [x] `phase05-session07-war-room-validation-and-documentation-closeout` - provides optional Worker boundary, room lifecycle evidence, and deployment diagnostics.

### Required Tools/Knowledge

* Node 20+, npm workspaces, TypeScript 5.9, Vitest, Express routing, Vite browser helpers, Zustand-backed War Room state, and Biome formatting/linting.
* Existing hosted config pattern in `packages/protocol/src/hostedConfig.ts`, `apps/server/src/lib/hostedConfig.ts`, `apps/server/src/routes/diagnostics.ts`, and `apps/web/src/lib/hostedConfig.ts`.
* Current War Room authority contracts in `packages/protocol/src/warroom.ts`, `apps/web/src/lib/warRoomIdentity.ts`, `apps/web/src/lib/warRoomUi.ts`, and `apps/warroom`.

### Environment Requirements

* Local checkout of the FactionOS monorepo with dependencies available through existing npm workspace scripts.
* No hosted account, OAuth provider, Supabase project, SSO provider, production app host, or real credential is required.
* Do not read, copy, print, or commit raw values from `.env.local` or hosted service consoles. Use synthetic test records and documented examples only.

***

## 4. Scope

### In Scope (MVP)

* Maintainers can reference a hosted identity guardrail artifact - add lifecycle, consent, revocation, authorization, role, audit, abuse-control, local-only fallback, and Phase 08 erasure handoff requirements.
* Protocol consumers can share one identity posture contract - add planned, unavailable, local-only, account-lifecycle, authorization-surface, role-mapping, audit, and non-overclaim vocabulary in `packages/protocol`.
* Operators can inspect local hosted identity posture safely - add server diagnostics that expose compact status, docs paths, and unsupported/planned reason codes without raw tokens, account ids, request bodies, or local paths.
* Browser code can render honest planned-state copy - add web helpers for hosted identity availability, local-only fallback, and War Room authority non-overclaim without adding sign-in UI.
* Tests or docs checks prevent Worker authority overclaim - prove room-local authority is not hosted account identity, SSO, organization membership, public collaboration safety, production audit proof, analytics consent, or trusted erasure.
* Stable docs and package README files align with source behavior and current open finding `P06-S07-HOSTED-IDENTITY`.

### Out of Scope (Deferred)

* Shipping production hosted auth, OAuth provider integration, PKCE runtime flow, JWKS fetching, SSO, organization management, account UI, billing, or account-backed onboarding - *Reason: this session defines guardrails and planned states only.*
* Storing raw account tokens, refresh tokens, OAuth codes, ID tokens, or raw Worker authority tokens in localStorage, replay buffers, exports, archives, diagnostics, logs, Worker payloads, or public docs - *Reason: blocked by the Phase 07 payload privacy blocklist.*
* Adding Supabase tables, RLS policies, storage buckets, public replay uploads, analytics capture, push subscriptions, tunnels, remote access, or hosted diagnostics upload - *Reason: Sessions 04, 05, and 06 own those surfaces.*
* 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 identity posture. Add a focused `hostedIdentity` module that exports identity status values, lifecycle requirement values, authorization surface values, role requirement values, audit requirement values, docs paths, diagnostic shapes, and pure helpers for building a compact guardrail summary. Keep these helpers deterministic and side-effect free so server and web packages can consume them without duplicating strings.

In `apps/server`, add a local hosted identity diagnostics builder and route. The route should be read-only, inherit the same local auth, CORS, rate-limit, and body-size boundary as other diagnostics, and return status-only JSON: planned or unavailable states, docs paths, required controls, and explicit non-overclaim labels. It must never return raw env values, bearer values, OAuth tokens, account ids, authority tokens, request bodies, local paths, logs, archives, replay buffers, exports, prompts, commands, or file contents.

In `apps/web`, add pure helper functions that describe hosted identity as planned or unavailable and distinguish it from War Room participant hints and room-local authority. Use this helper in tests and only light UI copy if needed to prevent existing War Room copy from implying hosted identity. Do not add sign-in buttons, account pages, OAuth redirects, Supabase clients, or account state persistence.

### Design Patterns

* Protocol-first contracts: shared identity status, lifecycle, role, audit, and non-overclaim vocabulary starts in `packages/protocol`.
* Planned-state scaffolding: source can expose unsupported or planned states without creating half-wired hosted auth behavior.
* Redacted diagnostics: diagnostics report status labels, docs paths, booleans, counts, and requirement names only.
* Local-first fallback: absent hosted identity config keeps core server, web, hooks, CLI, adapters, Worker fallback, public demo, replay, export, archive, and diagnostics workflows usable.
* Boundary-nearest authorization: future authorization-sensitive operations should be server-mediated by default and must not rely on UI copy alone.
* Negative claim tests: tests should assert that Worker authority is not described as hosted identity, SSO, organization membership, public collaboration safety, production audit proof, analytics consent, or trusted erasure.

### Technology Stack

* TypeScript contracts and Vitest tests in `packages/protocol`.
* Express diagnostics routing and Vitest route tests in `apps/server`.
* Vite/browser helper logic and Vitest tests in `apps/web`.
* Markdown docs under `.spec_system/PRD/phase_07/`, `docs/`, and package README files.

***

## 6. Deliverables

### Files to Create

| File                                                                    | Purpose                                                                                                                 | Est. Lines |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------- |
| `.spec_system/PRD/phase_07/hosted_identity_authorization_guardrails.md` | Source-backed hosted identity, authorization, consent, role, audit, non-overclaim, and Phase 08 handoff baseline        | \~240      |
| `packages/protocol/src/hostedIdentity.ts`                               | Shared hosted identity posture contracts, requirement vocabulary, docs paths, diagnostics shapes, and pure helpers      | \~240      |
| `packages/protocol/tests/hostedIdentity.test.ts`                        | Protocol tests for lifecycle requirements, authorization surfaces, non-overclaim vocabulary, and bounded summary shapes | \~170      |
| `apps/server/src/lib/hostedIdentity.ts`                                 | Local hosted identity diagnostics builder with redacted planned-state output                                            | \~150      |
| `apps/server/tests/hostedIdentityDiagnostics.test.ts`                   | Server route tests for auth inheritance, planned status, local-only fallback, and no raw token leakage                  | \~150      |
| `apps/web/src/lib/hostedIdentity.ts`                                    | Browser helper for hosted identity unavailable/planned state and Worker authority distinction                           | \~130      |
| `apps/web/tests/hostedIdentity.test.ts`                                 | Web helper tests for local-only fallback, planned copy, and War Room authority non-overclaim                            | \~130      |

### Files to Modify

| File                                    | Changes                                                                                                | Est. Lines |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------- |
| `packages/protocol/src/index.ts`        | Export hosted identity contracts from the package barrel                                               | \~2        |
| `apps/server/src/routes/diagnostics.ts` | Add `GET /diagnostics/hosted-identity` using the local diagnostics pattern                             | \~20       |
| `docs/api/README_api.md`                | Document hosted identity diagnostics as local planned-state posture, not hosted runtime behavior       | \~25       |
| `docs/hosted-services.md`               | Add Session 03 hosted identity guardrails and non-overclaim wording                                    | \~35       |
| `docs/privacy-and-security.md`          | Add account-token, authority-token, consent, revocation, audit, and Worker non-overclaim privacy rules | \~35       |
| `docs/ARCHITECTURE.md`                  | Add hosted identity planned-state architecture and local/Worker separation                             | \~25       |
| `docs/environments.md`                  | Clarify that reserved Supabase/OAuth variables do not enable hosted identity                           | \~25       |
| `docs/deployment.md`                    | Clarify deployed Worker and Cloudflare operations are not hosted identity proof                        | \~20       |
| `docs/release.md`                       | Add hosted identity release guardrails and Phase 08 deferrals                                          | \~25       |
| `packages/protocol/README_protocol.md`  | Document protocol ownership of hosted identity guardrail contracts                                     | \~25       |
| `apps/server/README_server.md`          | Document server hosted identity diagnostics and unavailable state                                      | \~25       |
| `apps/web/README_web.md`                | Document browser planned-state helper, local-only fallback, and no account UI                          | \~25       |
| `apps/warroom/README_warroom.md`        | Reaffirm room-local authority is not hosted account identity or audit proof                            | \~20       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Hosted identity requirements cover consent, sign-in, session expiry, logout, revocation, account export/deletion handoff, authorization, roles, audit, abuse controls, and local-only fallback.
* [ ] Protocol hosted identity contracts expose planned/unavailable states, authorization-surface labels, lifecycle requirements, role requirements, audit requirements, docs paths, and non-overclaim vocabulary.
* [ ] Server hosted identity diagnostics return status-only planned posture and inherit local bearer auth when `FACTIONOS_AUTH_TOKEN` is configured.
* [ ] Server diagnostics never include raw account tokens, OAuth values, authority tokens, account ids, request bodies, local paths, prompts, command output, replay buffers, exports, archives, logs, backups, or env values.
* [ ] Browser helpers keep hosted identity unavailable or planned without adding account UI, OAuth redirects, Supabase clients, or persisted account state.
* [ ] Room-local Worker authority remains documented and tested as one room-scoped bearer proof only.
* [ ] No source, UI, docs, diagnostics, or tests imply hosted identity is shipped before end-to-end validation exists.

### Testing Requirements

* [ ] Protocol hosted identity tests written and passing.
* [ ] Server hosted identity diagnostics route tests written and passing.
* [ ] Web hosted identity helper tests written and passing.
* [ ] Focused package typechecks run for changed TypeScript packages where feasible.
* [ ] Manual docs review completed for hosted identity, War Room authority, and release-deferral wording.

### Non-Functional Requirements

* [ ] Core local workflows remain usable without hosted accounts, Supabase, OAuth providers, SSO, Cloudflare credentials, Worker URL, analytics, hosted storage, public replay hosting, push, remote access, or production hosts.
* [ ] Public/browser surfaces never store or display raw account tokens, OAuth codes, refresh tokens, ID tokens, or raw Worker authority tokens.
* [ ] Future hosted identity authorization-sensitive operations are documented as server-mediated by default unless a later session proves otherwise.
* [ ] Phase 08 trusted erasure and production-hosted validation remain explicitly deferred.

### Quality Gates

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

***

## 8. Implementation Notes

### Key Considerations

* Do not add a real auth provider, sign-in surface, OAuth redirect route, Supabase client, account storage, or hosted session cookie.
* Do not read or copy `.env.local`; tests should use synthetic token-like strings and assert they are absent from serialized diagnostics.
* Keep Worker authority language narrow: possession of a Worker-issued token for one participant in one room.
* Participant names, colors, roles, and local browser hints are display metadata, not account-backed identity.
* Current Cloudflare Worker deployment proves optional room relay health, not hosted account identity or production auditability.
* Account deletion and export can be specified as future lifecycle requirements, but trusted unified erasure remains Phase 08.

### Potential Challenges

* Hosted identity overclaim: mitigate with negative-claim tests and docs checks that reject account, SSO, organization, public collaboration safety, production audit, analytics consent, and trusted erasure wording around Worker authority.
* Diagnostic leakage: mitigate by returning requirement names, status labels, docs paths, and booleans only, with tests against synthetic raw token values.
* Scope bleed into real auth: mitigate by keeping new code pure and diagnostics-only, with explicit unavailable/planned state.
* Browser copy drift: mitigate by centralizing hosted identity helper copy and testing that War Room authority copy stays non-hosted.
* Future authorization ambiguity: mitigate by documenting closest-boundary enforcement and server mediation before hosted persistence, analytics, public replay, push, diagnostics, or remote access can become active.

### Relevant Considerations

* \[P06-S07-HOSTED-IDENTITY] **Hosted identity remains open**: Phase 07 must define hosted account lifecycle, consent, authorization, revocation, audit, and end-to-end validation before any hosted identity claim.
* \[P06-apps/warroom+apps/web] **War Room federation is optional and redacted**: Worker rooms are optional transfer, not hosted identity or broad hosted collaboration proof.
* \[P00] **Hosted services are optional**: Supabase, Umami analytics, hosted storage, public replay hosting, and hosted validation remain optional or planned; core local workflows must work without hosted accounts or public client tokens.
* \[P05] **Redaction is boundary-specific**: diagnostics, browser helpers, Worker payloads, analytics, hosted storage, public replay, push, logs, exports, archives, and backups need explicit minimization at each boundary.
* \[P03-packages/protocol] **Protocol leads cross-package work**: shared identity, authorization, unsupported-state, and diagnostic vocabulary should start in `packages/protocol`.
* \[P03] **Local-first boundary is architectural**: server, web, hooks, CLI, adapters, LLM, analytics, backups, logs, and Worker integrations should degrade cleanly when remote services are absent.
* \[P06] **Unified erasure still missing**: do not claim trusted deletion for Worker storage, browser hints, archives, memory, settings, replay, exports, diagnostics, logs, backups, or future hosted data.
* \[P06] **Phase complete is not release complete**: this session does not close production-hosted validation, trusted erasure, mobile certification, WCAG certification, or release decommission gates.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Hosted identity state could be mistaken for shipped auth if planned, unavailable, and local-only states are not explicit.
* Diagnostics could accidentally expose synthetic or real token-like values, account ids, authority tokens, request bodies, or local paths.
* War Room authority copy could drift into account, SSO, organization, production audit, public sharing safety, analytics consent, or erasure claims.

***

## 9. Testing Strategy

### Unit Tests

* Test protocol lifecycle, authorization surface, role, audit, local-only, and non-overclaim vocabulary for uniqueness and expected values.
* Test protocol summary builders return bounded status-only output and never require hosted services for local workflows.
* Test web helpers return planned/unavailable hosted identity state, local-only fallback copy, and War Room authority distinction.

### Integration Tests

* Test `GET /diagnostics/hosted-identity` returns planned/unavailable posture, docs paths, requirement names, local-only status, and no raw token fields.
* Test the diagnostics route inherits local bearer auth when configured.
* Test synthetic OAuth, account, authority, and Cloudflare token-like strings do not appear in serialized server diagnostics.

### Manual Testing

* Review `docs/hosted-services.md`, `docs/privacy-and-security.md`, `docs/ARCHITECTURE.md`, `docs/api/README_api.md`, `docs/environments.md`, `docs/deployment.md`, `docs/release.md`, `apps/warroom/README_warroom.md`, and package README files for consistent shipped/planned/deferred wording.
* Confirm no doc describes room-local Worker authority as hosted account identity, SSO, organization membership, public collaboration safety, production audit proof, analytics consent, or trusted erasure.

### Edge Cases

* Hosted auth config values present in env examples must not enable account state or diagnostics beyond planned/unavailable posture.
* Browser refresh, Worker URL changes, participant changes, leave/reset, expired authority, invalid authority, missing authority, and authority mismatch must remain local War Room authority behavior, not account logout.
* Future account deletion/export wording must be lifecycle handoff only and must not close Phase 08 trusted unified erasure.
* Docs and tests must avoid raw OAuth values, public tokens, account ids, authority tokens, request bodies, local paths, and probe dumps.

***

## 10. Dependencies

### External Libraries

* No new external runtime libraries are planned.
* Existing Express, TypeScript, Vite, and Vitest dependencies are sufficient.

### Other Sessions

* **Depends on**: `phase07-session01-hosted-services-requirements-and-privacy-baseline`, `phase07-session02-hosted-configuration-and-client-exposure-boundaries`
* **Enables**: `phase07-session04-hosted-persistence-and-public-replay-boundaries`, `phase07-session05-analytics-consent-and-payload-controls`, `phase07-session06-push-remote-access-and-operator-diagnostics-guardrails`, `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-session03-hosted-identity-and-authorization-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.