> 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/hosted_identity_authorization_guardrails.md). # Hosted Identity and Authorization Guardrails **Session ID**: `phase07-session03-hosted-identity-and-authorization-guardrails` **Status**: Source-backed guardrail baseline **Created**: 2026-05-30 **Scope**: Hosted account lifecycle, authorization, consent, roles, audit, non-overclaim, and Phase 08 handoff requirements *** ## Purpose This artifact defines the hosted identity posture for Phase 07. It is a guardrail baseline, not an implementation of hosted accounts. FactionOS remains local-first and usable without hosted accounts, Supabase, OAuth, SSO, organization management, billing, hosted storage, analytics, public replay, push, remote access, Cloudflare credentials, or a deployed Worker URL. Room-local War Room authority is a bearer proof for one Worker room. It is not hosted account identity, SSO, organization membership, public collaboration safety, analytics consent, production audit proof, or trusted erasure. ## Source Ownership | Surface | Owner | Current state | | ------------------- | ----------------------------------------- | -------------------------------------------------- | | Shared vocabulary | `packages/protocol/src/hostedIdentity.ts` | Planned-state contracts and non-overclaim labels | | Local diagnostics | `apps/server/src/lib/hostedIdentity.ts` | Status-only local posture | | Browser helper copy | `apps/web/src/lib/hostedIdentity.ts` | Planned/unavailable helper copy with no account UI | | Stable docs | `docs/`, package README files | Current limitations and Phase 08 handoffs | ## Status Vocabulary | Status | Meaning | | ------------- | ---------------------------------------------------------------------------------- | | `unavailable` | No hosted identity runtime is configured or active. Core local workflows continue. | | `planned` | Requirements are defined, but production hosted identity is not shipped. | | `local_only` | The current operation uses local state or room-local Worker proof only. | | `unsupported` | A requested account-backed claim is explicitly not available in this build. | No status in this artifact proves account identity, account consent, account revocation, account export, account deletion, SSO, organization membership, public collaboration safety, production-hosted validation, or trusted erasure. ## Account Lifecycle Requirements Before hosted account identity can become active, a later session must define and validate all of the following controls: | Requirement | Minimum bar before activation | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sign-in | OAuth or SSO flow uses PKCE or an equivalent reviewed browser-safe flow. | | Session expiry | Access and refresh lifetimes are bounded, documented, and locally visible. | | Logout | Logout clears browser account state and invalidates server-side sessions where applicable. | | Revocation | Account sessions, provider grants, push subscriptions, and hosted storage access can be revoked. | | Consent | Analytics, public replay, push, remote access, and hosted storage require explicit consent per surface. | | Export | Hosted account data has a documented export path before claims are made. | | Deletion handoff | Trusted unified erasure remains Phase 08 until all local, Worker, browser, archive, backup, log, replay, and future hosted surfaces are covered. | | Local fallback | Missing hosted identity config keeps server, web, hooks, CLI, adapters, Worker tests, public demo, replay, export, archive, backup, and diagnostics usable. | ## Authorization Boundaries Future authorization-sensitive operations should be server-mediated by default unless a later accepted design proves a narrower browser-only boundary. | Surface | Required boundary | | ---------------------- | ---------------------------------------------------------------------------------------------------------------- | | Account data | Validate authenticated account session at the server boundary nearest the protected data. | | War Room participation | Continue to use room-scoped Worker authority; do not treat it as account identity. | | Hosted storage | Require account authorization, storage eligibility, retention, export, deletion, and policy tests before writes. | | Analytics preferences | Require consent and opt-out enforcement before capture. | | Public replay | Require explicit user consent, payload redaction, expiration, takedown, and no-index posture. | | Push | Require browser permission, subscription consent, unsubscribe, retention, and payload minimization. | | Remote access | Require explicit opt-in, local auth, rate limits, CORS/Origin review, expiry, revocation, and audit. | | Operator diagnostics | Return posture, docs paths, booleans, counts, and reason codes only. | ## Role and Organization Requirements FactionOS does not currently ship hosted roles or organization membership. Before any account-backed role claim is made, a later session must define: * Account role vocabulary and mapping source. * Organization membership source and revocation behavior. * Permission checks closest to each protected resource. * Role downgrade and session refresh behavior. * Admin, operator, member, observer, and service-account audit semantics. * Tests proving stale roles cannot authorize protected operations. Worker roles such as leader, member, observer, and pending remain room-local role hints only. They do not prove hosted account role or organization membership. ## Audit Requirements Before hosted identity becomes active, audit evidence must cover: * Authentication decision reason codes without raw tokens. * Authorization allow and deny outcomes without request bodies. * Session expiry, refresh, logout, and revocation events. * Consent grant, denial, and withdrawal events. * Hosted storage access, export, deletion request, and deletion completion. * Public replay publish, expiration, and takedown actions. * Push subscription create and unsubscribe actions. * Remote access enable, disable, expiry, and abuse-control outcomes. * Diagnostics access without raw account ids, local paths, prompts, commands, replay buffers, exports, archives, logs, backups, or env values. ## Sensitive Value Rules The following values must never appear in browser storage, replay buffers, exports, archives, diagnostics, logs, stable docs examples, public demo output, or test snapshots: * Raw account tokens, refresh tokens, OAuth codes, ID tokens, JWKS keys, client secrets, provider secrets, and service-role keys. * Raw Worker authority tokens and raw authority hashes. * Account ids, organization ids, email addresses, or profile identifiers unless a later privacy review defines a redacted display shape. * Request bodies, local paths, prompts, commands, terminal output, file contents, replay buffers, exports, archives, backups, logs, or scan payloads. ## Local-Only Fallback If hosted identity config is absent, blank, reserved, or invalid: * The local server still starts. * The web cockpit still renders local state. * Hooks, CLI, adapters, backup, export, replay, archive, and public demo workflows remain credential-free. * War Room can remain local-only or use optional Worker room authority when a Worker URL is configured. * Diagnostics return compact planned or unavailable posture instead of raw values or blank failure states. ## Non-Overclaim Labels Tests and docs should use these labels when guarding against overclaim: | Label | Meaning | | --------------------------------- | ------------------------------------------------------------------------- | | `not_hosted_identity` | Room authority or local auth does not identify a hosted account. | | `not_sso` | No SSO provider or organization SSO proof is active. | | `not_organization_membership` | No account-backed organization membership is proven. | | `not_public_collaboration_safety` | Local or room-scoped proof does not validate public collaboration safety. | | `not_production_audit_proof` | Local diagnostics and Worker room events are not production audit proof. | | `not_analytics_consent` | Room authority or local auth does not grant analytics consent. | | `not_trusted_erasure` | Local clear/reset does not prove trusted unified erasure. | ## Diagnostics Rules Hosted identity diagnostics may expose only: * Version, generated timestamp, status labels, and reason codes. * Docs paths and requirement labels. * Booleans such as local-only fallback and hosted identity required status. * Counts of lifecycle, authorization, role, audit, and non-overclaim requirements. Hosted identity diagnostics must not expose: * Raw env values, tokens, account ids, authority tokens, request bodies, local paths, prompts, commands, terminal output, replay buffers, exports, archives, logs, backups, or file contents. * Any claim that hosted accounts, OAuth, SSO, organization management, billing, Supabase auth, hosted storage, analytics consent, public replay hosting, push, remote access, or trusted erasure is active. ## Abuse-Control Requirements Before hosted identity becomes active, future source must define and test: * Duplicate action prevention for sign-in, logout, revocation, consent, export, deletion request, public replay publish, push subscribe, and remote-access enablement. * Rate limits and lockout behavior for account-backed sensitive endpoints. * Timeout and retry rules for provider calls. * Explicit user-visible failure paths for identity provider outage, revoked session, expired session, missing consent, role downgrade, and unavailable hosted storage. * Error boundaries that return stable reason codes without leaking stack traces, provider details, tokens, ids, or local paths. ## Phase 08 Handoff Phase 08 remains responsible for: * Trusted unified erasure across local state, browser hints, Worker state, archives, exports, replay buffers, logs, backups, valid spool state, and future hosted data. * Production-hosted validation for deployed app, deployed Worker, Cloudflare dashboard state, hosted account providers, release-candidate smoke, and account-backed data flows. * Release hardening, security review, mobile certification, WCAG certification, and legacy decommission gates. This Session 03 artifact is sufficient to prevent hosted identity overclaim. It is not sufficient to ship hosted identity. --- # 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/hosted_identity_authorization_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.