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.