Security & CORS
Authenticate at the application boundary. Authorize each REST resource. Allow only trusted browser origins.
APPNETOS separates bootstrap authentication, REST Collection authorization, Redis-backed rate limiting and browser cross-origin permissions. These controls solve different problems and should be configured independently.
Security architecture
The application and runtime context are resolved before CORS and Security Bootstrap. Security
Bootstrap
authenticates configured Basic or Bearer credentials and records a resolved identity. The REST
resolver
checks that identity against the #[Security] annotation of the selected Collection. An
allowed CORS origin never bypasses authentication.
Application and context security configuration
Runtime security definitions live under platform/security/<application>.php. An
environment-specific file such as platform/security/<application>.docker.php
replaces
the default configuration in full when present; files are not merged. Each context has its own
rules.
<?php
declare(strict_types=1);
return [
'application' => 'example-app',
'contexts' => [
'admin-rest' => [
'basic_auth' => [
'active' => true,
'realm' => 'APPNETOS',
'users' => [
'api-admin' => '<password_hash output>',
],
],
'bearer_auth' => [
'active' => true,
'tokens' => [
'integration-key' => '<password_hash output>',
],
],
],
],
];
Illustrative configuration: replace the placeholders with hashes
produced using password_hash(). Never commit raw passwords or bearer tokens.
See Security Bootstrap for configuration resolution and credential verification.
Basic and Bearer authentication
Basic authentication verifies a submitted password against the configured password hash and records a
runtime identity such as ['basic' => 'api-admin']. Bearer authentication verifies
the
submitted token against a configured token hash and records its identifier, for example ['bearer'
=> 'integration-key']. REST authorization compares these resolved identifiers, not
plaintext secrets.
Authentication failures are handled by the bootstrap layer, including the appropriate HTTP 401 challenge. Do not confuse authentication with the later resource-level authorization check.
REST Collection authorization
The optional Core\Rest\Annotation\Security attribute restricts an annotated REST
Collection
to named Basic users or Bearer key identifiers. When both lists are configured, a match in either
applicable identity list grants access. If the annotation is absent, the REST resolver adds no
resource-specific restriction, although bootstrap security may still apply.
use Core\Rest\Annotation\Rest;
use Core\Rest\Annotation\Security;
#[Rest(slug: 'inventory', methods: ['GET'])]
#[Security(users: ['api-admin'], keys: ['integration-key'])]
class InventoryCollection extends \Core\Collection\Base
{
// Collection mapping and implementation omitted.
}
If a protected resource has no resolved identity, the resolver returns an unauthorized error. If an identity is present but does not match the allowed users or keys, it returns a forbidden error.
CORS: trusted browser origins
CORS is configured separately under platform/cors/<application>.php, with optional
environment-specific replacement. Only explicitly active contexts apply an origin allowlist. The
CORS
bootstrap runs after application resolution and before session/security initialization.
<?php
declare(strict_types=1);
return [
'application' => 'example-app',
'contexts' => [
'admin-rest' => [
'active' => true,
'origins' => [
'https://api-client.example.com',
'http://localhost:20000',
],
],
],
];
Explicit scheme and host are recommended for production. A scheme-free hostname permits both HTTP and HTTPS variants. Origins are exact; wildcard hosts, paths and trailing slashes are not accepted.
See CORS Bootstrap for normalization rules, frame-embedding policy and response headers.
Preflight requests
An OPTIONS request is treated as a CORS preflight only when it also includes
Origin and Access-Control-Request-Method. Allowed, valid preflights are
answered immediately with HTTP 204, before authentication. Rejected preflights return
400 or 403, depending on the validation failure. Ordinary requests
continue
through the remaining bootstrap and REST layers.
Preflight approval is not permission to execute a REST operation. The subsequent request must still pass authentication, REST authorization and HTTP-method checks.
REST rate limiting
Core\Rest\Annotation\RateLimit sets a per-resource request limit and time window. The
REST
resolver tracks counters using Redis and identifies callers using Bearer credentials, Basic users or
client IP information. Credentials are hashed before being incorporated into Redis keys.
use Core\Rest\Annotation\RateLimit;
#[RateLimit(limit: 100, seconds: 60)]
The resolver exposes rate-limit response headers such as X-RateLimit-Limit and X-RateLimit-Remaining.
Rate limiting is deliberately fail-open when Redis is unavailable or an operation
fails; it is not a substitute for authentication or infrastructure-level abuse protection.
Troubleshooting
| Symptom | Check |
|---|---|
401 Unauthorized |
Missing or invalid Basic/Bearer credentials; or no resolved identity for a protected REST resource. |
403 Forbidden |
Resolved identity not listed in #[Security], or rejected CORS preflight
origin.
|
| Browser blocks cross-origin request | Exact origin, active application context, environment-specific CORS file and preflight response. |
| Rate limiting not enforced | Redis availability and fail-open behavior; check the resource annotation and runtime configuration. |
| Works in curl, fails in browser | Browser CORS restrictions do not apply to curl; verify preflight and response headers. |
Public API Methods
Public methods declared by the two REST security-related annotation classes. REST resolver security and rate-limit checks are protected implementation methods, not public API methods.
| Class | Method |
|---|---|
Core\Rest\Annotation\Security |
__construct(...) |
Core\Rest\Annotation\Security |
getUsers(): array |
Core\Rest\Annotation\Security |
hasUsers(): bool |
Core\Rest\Annotation\Security |
getKeys(): array |
Core\Rest\Annotation\Security |
hasKeys(): bool |
Core\Rest\Annotation\RateLimit |
__construct(...) |
Core\Rest\Annotation\RateLimit |
getLimit(): int |
Core\Rest\Annotation\RateLimit |
getSeconds(): int |