The central API (portal-api)
riveroaks/portal-api is a TypeScript Cloudflare Worker. Its catalog maps
canonical /api/v1 resources to PHP adapters, native ticket-live handlers, or
the development Tasks service binding. assistant remains a planned resource
that returns 501. Sources: portal-api · src/contract.ts, portal-api · src/index.ts.
Request lifecycle
The Worker validates the configured hostname/lane, path encoding, route, method,
body bounds, and authentication header shape. Ordinary calls reject cookies
and upgrades; ticket-live has a dedicated upgrade path. Separate auth/API rate
limit bindings provide an edge abuse layer. PHP also enforces its own limits.
Source: portal-api · src/index.ts,
portal · dashboard/api/mobile/v1/lib/runtime.php.
For a Portal resource it constructs an allowlisted origin path, strips
spoofable forwarding/cookie headers, sets trusted forwarding metadata and a
request ID, and calls PRIVATE_PORTAL_API.fetch. Returned headers are sanitized
and responses include X-Request-ID and X-Portal-API-Release. Browser calls use
the Portal BFF; this is not a general CORS proxy. Source: portal-api · src/index.ts.
Private connectivity
OpenTofu binds a Workers VPC HTTP service to the existing Goshen tunnel and
10.200.24.42:80. The Worker selects the matching Portal hostname from its
configuration, so nginx's Host selection separates the checkouts. The declared
last hop is HTTP; do not describe it as end-to-end origin TLS. Sources:
portal-api · infra/modules/portal-platform/main.tf, portal-api · src/index.ts,
infra · nginx/hosts/rocc-db/sites-enabled/ro.church.conf.
Dev owns the VPC Service resource; production references that existing service
ID instead of owning a duplicate. Workers, custom domains, rate-limit
namespaces, and Terraform states are lane-specific. The shared connector,
origin host and port remain common dependencies. Sources:
portal-api · infra/modules/portal-platform/main.tf,
portal-api · infra/environments/alpha/main.tf,
portal-api · infra/environments/production/main.tf.
Resource catalog
The following groups summarize the dev source catalog; each exact method,
permission label, implementation state, auth style and devOnly flag lives in
portal-api · src/contract.ts. Compare with portal-api · src/contract.ts before
assuming production supports one of these routes. Labels do not replace the
adapter's runtime permission checks.
| Group | Canonical resources | Backend |
|---|---|---|
| Identity | me, bootstrap, web-session |
Portal PHP |
| Tickets | tickets, ticket-attachments, ticket-email-reply |
Portal PHP |
| Ticket invalidation | tickets-live-token, tickets-live, ticket-live-ingest |
Worker + Durable Object |
| Budget | budget, budget-expenses, budget-inbox, budget-admin, budget-export |
Portal PHP |
| Staff tools | links, sermon-slides, services, files, network, physical-access, device-updates, automation |
Portal PHP |
| Expenses | expense-requests, receipt-link |
Portal PHP |
| Alerts | alerts, alerts-wait, alert-ingest, alert-preferences, push-installations, task-alert-ingest |
Portal PHP |
| Comms | comms, comms-ingest, panic-ingest |
Portal PHP and RAM snapshots |
| Access | doors, access-cards |
Portal PHP, dev-only catalog entries |
| Tasks | tasks, task-detail, task-comments, task-comment, task-projects, task-project-assignees, task-alert-preferences |
Tasks Worker, dev only |
| Assistant reservation | assistant |
Planned (501) |
Authentication styles
| Style | Use | Evidence |
|---|---|---|
| Bearer | Native staff calls and PHP BFF | portal · dashboard/api/mobile/v1/lib/runtime.php |
alert-hmac |
Signed machine events, including alert and ticket ingest paths | portal-api · src/contract.ts, portal · dashboard/api/mobile/v1/lib/alert-ingest.php |
comms-hmac |
Comms and panic snapshots | portal · dashboard/api/mobile/v1/lib/comms.php |
connect-token |
Ticket-live WebSocket | portal-api · src/ticket-live.ts |
GET /oauth/authorize redirects to Portal auth/start.php. POST /oauth/token
and /oauth/revoke proxy to the token service and family revocation adapters.
The edge is not an independent OAuth user database. Sources:
portal-api · src/index.ts, portal · dashboard/api/mobile/v1/auth/start.php,
portal · dashboard/api/mobile/v1/token.php,
portal · dashboard/api/mobile/v1/revoke.php.
Ticket live updates (WebSocket)
The CSRF-protected browser BFF obtains a connect token with its server-held
bearer. The Worker checks the Portal identity/permission and issues a 60-second
signed token. The upgrade accepts exact subprotocol credentials and the matching
Portal Origin, with no query token. Sources:
portal · dashboard/v2/tickets/api/live-token.php,
portal-api · src/index.ts, portal-api · src/ticket-live.ts.
An environment-scoped TicketLiveHub stores a monotonically increasing revision
in SQLite and broadcasts generic tickets.changed notices. Ticket content and
user records are not stored in that hub. Clients refetch authorized data; the
Portal queue retains polling fallback. Sources:
portal-api · src/ticket-live-hub.ts, portal-api · docs/TICKETS_LIVE.md,
portal · docs/ticket-portal-live-updates.md.
Tasks gateway (development only)
For a Tasks route the API first asks the private Portal bootstrap adapter for a
current active staff identity, then signs a 30-second assertion covering the
method, path/query, body digest and request ID. It calls TASKS_API through a
service binding, not a public-hostname fetch. The gateway's role is identity and
transport; Tasks owns its authorization. Sources:
portal-api · src/index.ts, portal-api · docs/TASKS.md,
portal-api · infra/modules/portal-platform/main.tf.
Mutation paths require explicit idempotency/version headers where defined.
Assertion rejection becomes 502, avoiding a misleading user-token refresh.
The configuration checks prohibit enabling this gateway in production.
Source: portal-api · src/index.ts,
portal-api · infra/modules/portal-platform/main.tf.
Alert delivery
The Portal determines recipients, dedupe, preferences and read state. Native
foreground transport uses alerts and bounded alerts-wait; APNs delivery is
performed by the Portal background sender. Dev can also use the narrow LAN
alert proxy, with public API fallback. Sources:
portal · docs/mobile-alerts.md, portal · scripts/mobile-apns-worker.php,
portal-ios · Sources/PortalCore/APIClient.swift,
infra · nginx/hosts/rocc-db/sites-enabled/dev-alerts.riveroaks.cc.conf.
Health, deployment and logs
/healthz is a direct Worker liveness response. Dev adds /health/live and
/health/ready (also /api/v1/_origin/health): readiness expects the private
bootstrap adapter to reject an unauthenticated call with 401. It does not
prove every resource or background worker is healthy. Sources:
portal-api · src/index.ts, portal-api · src/index.ts.
CI stages are validate, test, plan, deploy, verify; dev applies and
smokes automatically after its gates, while production apply/smoke require
ENABLE_PRODUCTION_API=true. alpha is the historical name of the dev IaC
root/state, not a third runtime lane. Sources: portal-api · .gitlab-ci.yml,
portal-api · infra/environments/alpha/backend.tf.
The IaC enables Worker invocation logs; the application emits bounded outcome
logs. Never include tokens, snapshots or personal records in debugging output.
Saved plans/state may contain secret bindings even when variables are marked
sensitive. Sources: portal-api · infra/modules/portal-platform/main.tf,
portal-api · infra/modules/portal-platform/variables.tf,
portal-api · .gitlab-ci.yml, portal-api · src/index.ts.
Operations and rollback: portal-api · docs/OPERATIONS.md. Add a resource in the
catalog, implement/deploy its origin adapter first, update contract tests, then
follow release order.
Source: portal-api · CONTRIBUTING.md, portal-api · docs/MIGRATION.md.