Cors
in package
Cross-Origin Resource Sharing (CORS) for the REST API.
Opt-in by design: with no CORS_ALLOWED_ORIGINS configured, no CORS headers
are emitted and the API stays same-origin-only — existing installs are
unchanged. When the env var lists one or more origins, the request Origin
is echoed back only if it matches the allow-list exactly (no wildcards).
Built for token (Bearer) auth: credentials/cookies are intentionally NOT
enabled, so Access-Control-Allow-Credentials is never sent. A packaged
client (e.g. the Capacitor/F-Droid app) authenticates with an
Authorization: Bearer header rather than cookies, which sidesteps the
cookie-CORS and CSRF complications entirely.
Tags
Table of Contents
Constants
- ALLOWED_HEADERS = 'Content-Type, Authorization, X-CSRF-TOKEN'
- Request headers a cross-origin client may send. `Authorization` carries the Bearer token; `X-CSRF-TOKEN` is accepted for cookie-auth callers.
- ALLOWED_METHODS = 'GET, POST, PUT, DELETE, OPTIONS'
- Methods advertised to preflight requests. Mirrors the API's accepted verbs plus OPTIONS itself.
- MAX_AGE = '86400'
- How long (seconds) a browser may cache the preflight result.
Methods
- allowedOrigins() : array<int, string>
- Parse the configured allow-list from `CORS_ALLOWED_ORIGINS` (comma-separated). Each entry is trimmed and stripped of a trailing slash so it matches a browser `Origin` header.
- handlePreflight() : bool
- Answer a CORS preflight (OPTIONS) request: emit the headers and a 204.
- resolveOrigin() : string|null
- The request `Origin` if it is allow-listed, otherwise null.
- sendHeaders() : void
- Emit CORS response headers when the request `Origin` is allow-listed.
Constants
ALLOWED_HEADERS
Request headers a cross-origin client may send. `Authorization` carries the Bearer token; `X-CSRF-TOKEN` is accepted for cookie-auth callers.
private
mixed
ALLOWED_HEADERS
= 'Content-Type, Authorization, X-CSRF-TOKEN'
ALLOWED_METHODS
Methods advertised to preflight requests. Mirrors the API's accepted verbs plus OPTIONS itself.
private
mixed
ALLOWED_METHODS
= 'GET, POST, PUT, DELETE, OPTIONS'
MAX_AGE
How long (seconds) a browser may cache the preflight result.
private
mixed
MAX_AGE
= '86400'
Methods
allowedOrigins()
Parse the configured allow-list from `CORS_ALLOWED_ORIGINS` (comma-separated). Each entry is trimmed and stripped of a trailing slash so it matches a browser `Origin` header.
public
static allowedOrigins() : array<int, string>
Return values
array<int, string> —Exact origins, e.g. ['https://app.example', 'capacitor://localhost']
handlePreflight()
Answer a CORS preflight (OPTIONS) request: emit the headers and a 204.
public
static handlePreflight(string $method) : bool
Parameters
- $method : string
-
The request method.
Return values
bool —True if this was a preflight and has been fully answered (the caller should stop processing); false otherwise.
resolveOrigin()
The request `Origin` if it is allow-listed, otherwise null.
public
static resolveOrigin() : string|null
Matching is exact (after trailing-slash normalization); this never reflects an arbitrary origin back, which would defeat the purpose of the allow-list.
Return values
string|nullsendHeaders()
Emit CORS response headers when the request `Origin` is allow-listed.
public
static sendHeaders() : void
No-op for same-origin requests, disallowed origins, or once headers have already been flushed.