Skip to content

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.