APPNETOS is under active development This website and its documentation are being prepared for public launch. Content and features may change.
Select Theme
Loading

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.

APPNETOS CORS bootstrap, security authentication, REST authorization and rate limiting flow
Cross-origin policy is evaluated before authentication; resource authorization and rate limiting are enforced by the REST resolver.

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

Next Steps

Previous

Request & Response

Explore Request & Response

Next

OpenAPI Generator

Explore OpenAPI Generator