Skip to content

Identity and trust boundaries

Portal user identity, machine publisher identity, Tasks authorization and LAN operator access are different trust boundaries. A client-visible role or a network hostname alone does not grant a Portal permission. Sources: portal · dashboard/api/mobile/v1/lib/runtime.php, portal-api · docs/TASKS.md, infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf.

Staff sign-in (Google)

Portal PHP owns the browser Google sign-in/account policy and creates its PHP session. Mobile authorization starts at the API and redirects to the Portal Google flow. Tokens are issued only after the Portal's account/permission checks; the Worker is not a second user directory. Sources: portal · dashboard/login/google_login.php, portal · dashboard/api/mobile/v1/auth/start.php, portal · dashboard/api/mobile/v1/token.php.

OAuth with PKCE (iOS app and web BFF)

Client ID/callback pairs are allowlisted. The authorization code is one-use, PKCE-bound and stored as a hash; the token exchange locks/consumes it in a SQL transaction. Opaque tokens use 32 random bytes and SHA-256 lookup hashes. Sources: portal · dashboard/api/mobile/v1/lib/core.php, portal · dashboard/api/mobile/v1/token.php.

Defaults are a five-minute code, 15-minute access token, 30-day refresh idle limit, and 90-day family ceiling. These are bounded runtime-configurable values, not immutable protocol constants. Refresh rotation preserves the family ceiling; reusing an inactive refresh token revokes its family. Sources: portal · dashboard/api/mobile/v1/lib/core.php, portal · dashboard/api/mobile/v1/lib/tokens.php, portal · dashboard/api/mobile/v1/token.php.

Each bearer request reloads the user and checks active status; resource handlers apply current permissions. SQL/rate-limit failures return service errors, not a valid anonymous identity. Sources: portal · dashboard/api/mobile/v1/lib/runtime.php, portal · dashboard/api/mobile/v1/bootstrap.php.

The native app validates the OAuth browser callback and stores tokens in AfterFirstUnlockThisDeviceOnly Keychain storage. Refresh error handling distinguishes an explicit invalid grant from transient failures, preserving sessions across temporary network/service failures. Sources: portal-ios · RiverOaksPortal/App/WebAuthenticationService.swift, portal-ios · RiverOaksPortal/App/KeychainTokenVault.swift, portal-ios · Sources/PortalCore/APIClient.swift.

Web Portal behind the API (BFF)

The PHP session holds API tokens server-side. The BFF validates the environment pair, constrains API resource paths, coordinates refresh and clears mismatched credentials; tokens are not handed to browser JavaScript. Sources: portal · dashboard/v2/api/lib/client.php, portal · dashboard/v2/api/callback.php.

Opening a web page from the app (handoff)

web-session issues a short-lived one-use fragment secret for a server-owned allowlist of destinations. web-continue.php consumes it and ties the PHP session to the token family. This is separate from copying native bearer tokens into browser cookies. Sources: portal · dashboard/api/mobile/v1/web-session.php, portal · dashboard/api/mobile/v1/web-continue.php, portal · dashboard/api/mobile/v1/lib/tokens.php.

HMAC publishers

Boundary Signature/replay contract Source
Alert ingest HMAC-SHA256 over timestamp + . + raw body; publisher policy, idempotency and server-selected recipients portal · dashboard/api/mobile/v1/lib/alert-ingest.php
Comms/panic HMAC-SHA256 over timestamp + newline + raw body; 30-second skew check and stream/sequence ordering; key shared by these two feeds within a lane portal · dashboard/api/mobile/v1/lib/comms.php, portal · dashboard/api/mobile/v1/comms-ingest.php, portal · dashboard/api/mobile/v1/panic-ingest.php
Email gateway Timestamp/method/path/idempotency/body-digest canonical string; caller-scoped quotas cloudflare-email · README.md, cloudflare-email · src/index.ts
Short Links admin Access boundary plus signed admin requests and replay controls cloudflare-short-links · src/admin.ts
Timeline producers mTLS plus signed producer/epoch/sequence/body contract; durable duplicate/gap checks infrastructure/service-timeline · src/service_timeline/signing.py, infrastructure/service-timeline · src/service_timeline/storage.py

These formats are not interchangeable. The comms producer holds only the latest bounded snapshot and continues local transcription when API publication fails. Source: infrastructure/lyric-follower · macos/WorshipDataCaptureApp/Sources/WorshipDataCaptureApp/CommsPublisher.swift.

Tasks assertion (dev)

The API validates Portal identity, then creates a short-lived request-bound assertion for the dev Tasks service binding. Tasks owns task/project permissions; the Portal permission list is not a replacement ACL. Sources: portal-api · src/index.ts, portal-api · docs/TASKS.md.

Authentik and Cloudflare Access

Browser Lyrics Control and the interactive songs viewer use nginx Authentik forward auth. Exact iPad control routes deliberately bypass browser auth but retain source ACL/method/body limits; nginx overwrites the local marker header, and the follower validates its local control boundary. Sources: infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf, infra · nginx/hosts/rocc-db/sites-enabled/songs.riveroaks.cc.conf, infrastructure/lyric-follower · src/lyric_follower/rehearsal.py.

Capture scheduling has a separate bearer-protected route and backend. Its nginx location explicitly permits non-LAN sources before delegating to bearer checks; it must not be described as an anonymous LAN-only endpoint. Source: infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf, infrastructure/lyric-follower · server/planning_center_api.py.

The documentation has one content corpus, published to both docs.ro.church (internet-reachable through Cloudflare Access) and docs.riveroaks.cc (private network). IT/portal-system is not a separately private section: MkDocs has no section exclusion and CI builds the same corpus for both destinations. Access is a site boundary, not a folder label. Keep credentials, recovery material, personal records and new private-admin endpoint inventories out of this section. Existing operational hostnames are not proof that adding more would be appropriate. Sources: docs · mkdocs.yml, docs · .gitlab-ci.yml, docs · README.md.

On November 3 ET, anonymous root/source-page requests to the public hostname returned 403; the source register on the authorized private-network path returned 200. That verifies these requests, not every Cloudflare Access policy or bypass route. Publication CI evidence is tracked on T-100498.

Secret and privacy boundaries

Planning Center credentials stay in server-side adapters; dashboard/capture clients receive filtered data or a dedicated API credential. That does not mean only one server component can possess PCO credentials: both the song adapter and capture-feed generator are server-side consumers. Sources: portal · lyrics/songs/api.php, infrastructure/lyric-follower · server/planning-center-feed.php, infrastructure/lyric-follower · server/planning_center_api.py.

Worker secrets are configured through sensitive IaC inputs and secret bindings. Saved plans/state can contain those values; masking a CI variable or declaring it sensitive does not make the artifact safe to publish. Invocation logs are enabled in the reviewed API IaC. Do not capture credential headers, payloads, transcripts, recordings or personal data in documentation/evidence. Sources: portal-api · infra/modules/portal-platform/main.tf, portal-api · infra/modules/portal-platform/variables.tf, portal-api · .gitlab-ci.yml.

Opting into ?comms=1 on the lyric socket selects message types; it is not an authentication check. The reviewed PHP broadcaster does not distinguish LAN from public subscribers. The private nginx ACL is visible in source, but safe filtering at every public WebSocket edge is not established here. Do not claim comms confidentiality without separately verifying that boundary. Sources: portal · lyrics/server.php, portal · lyrics/comms_feed.php, infra · nginx/hosts/rocc-db/sites-enabled/lyrics.riveroaks.cc.conf.