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

CORS Bootstrap

The fifth bootstrap step optionally grants trusted browser origins access to a resolved application context, handles CORS preflight requests, and defines frame-embedding policy before session and security initialization.

Purpose and Execution

Bootstrap\Cors\CorsBootstrap executes after Application Bootstrap and before Session Bootstrap. Application Bootstrap has already resolved the application and its exact runtime context. CORS does not define, replace, or discover routes.

Applications normally work without any CORS configuration. Their existing routes handle same-origin browser requests. A CORS configuration is only needed when another browser origin must be allowed to access a specific context, or when the context should permit embedding by trusted origins.

public function boot(): void
{
    if ($this->runtimeState->getProcess()) {
        return;
    }

    $application = $this->runtimeState->getApplication();
    $context = $this->runtimeState->getContext();

    if ($application === null || $application === '' || $context === null || $context === '') {
        return;
    }

    $configuration = $this->loadCorsFile($application);
    $definition = $configuration['contexts'][$context] ?? null;

    // Only explicitly active contexts proceed to origin validation and header handling.
}

The excerpt illustrates the early guards and exact-context lookup. Process runtimes, missing application or context resolution, missing files, and missing or inactive context definitions do not enable CORS. The bootstrap does not fall back to the default context or base context.

Request Flow

The diagram distinguishes genuine browser preflight requests from ordinary HTTP requests. Only genuine preflights are terminated inside this bootstrap step.

CORS bootstrap request flow: resolved application and context, optional context-specific CORS, preflight response or continued session and security bootstrap.
CORS is evaluated after application resolution. Ordinary requests continue through the remaining bootstrap chain.

Configuration File Resolution

Installed runtime CORS configurations are read from platform/cors/ using the resolved application identifier. They are optional.

platform/cors/appnetos-dns-control.php
platform/cors/appnetos-dns-control.docker.php

If APPNETOS_ENVIRONMENT is docker and the second file exists, it replaces the complete default configuration. There is no array merge or key-level fallback. If the environment file does not exist, the default file is used; if neither exists, no CORS permissions are enabled.

Complete Configuration Example

On appnetos.com, API Dev runs on separate hosts and needs browser access to the DNS Control admin-rest context. This example allows those browser origins without weakening REST authentication.

<?php

declare(strict_types=1);

return [
    'application' => 'appnetos-dns-control',
    'contexts' => [
        'admin-rest' => [
            'active' => true,
            'origins' => [
                'api-dev.appnetos.com',
                'api-dev.appnetos.de',
            ],
        ],
    ],
];

The scheme-free origin definitions above expand to both http:// and https:// variants. For production deployments where only HTTPS is intended, use explicit HTTPS origins instead.

Key Type Rule
application string Required; must equal the resolved application identifier and configuration filename stem.
contexts array Required; maps exact runtime context names to their CORS definitions.
contexts.<context>.active bool Optional; defaults to false. Only true activates a context.
contexts.<context>.origins array Required for an active context; lists trusted browser origins.

Application Identifier

The application key identifies the application whose browser access rules are being configured. It must match the application selected by Application Bootstrap and the CORS configuration filename (excluding the environment suffix).

'application' => 'appnetos-dns-control',

A missing or mismatched application identifier causes bootstrap validation to fail when the configuration file is loaded.

Context-Specific Activation

Each context is configured independently. A rule for admin-rest does not automatically apply to admin, rest, or app. Contexts omitted from the file are not enabled.

'contexts' => [
    'admin-rest' => [
        'active' => true,
        'origins' => [
            'https://api-dev.appnetos.com',
        ],
    ],
    'admin' => [
        'active' => false,
    ],
],

When active is omitted, its effective value is false. An active context must provide an origins array; even an empty array is valid but grants no cross-origin access. It still establishes a frame-ancestors 'self' policy for that active context.

'contexts' => [
    'app' => [
        'active' => true,
        'origins' => [], // No cross-origin access; same-origin framing only.
    ],
],

Origin Definitions and Normalization

An origin consists of a scheme, host, and optional port. The bootstrap accepts explicit http:// or https:// origins and scheme-free host definitions. Scheme-free definitions expand to both protocols; an explicit non-default port is preserved.

'origins' => [
    'api-dev.appnetos.com',          // HTTP and HTTPS
    'https://api-dev.appnetos.de',  // HTTPS only
    'http://localhost:20000',       // Local development origin
    'localhost:20001',              // HTTP and HTTPS, port 20001
],
Definition Effective origin(s)
api-dev.appnetos.com http://api-dev.appnetos.com and https://api-dev.appnetos.com
https://api-dev.appnetos.com HTTPS only
localhost:20001 http://localhost:20001 and https://localhost:20001
https://localhost:443 Normalized to https://localhost

Normalization lowercases schemes and hosts, removes default ports (80 for HTTP and 443 for HTTPS), and eliminates equivalent duplicates.

'origins' => [
    'https://api-dev.appnetos.com',   // Valid
    // 'https://api-dev.appnetos.com/', // Invalid: trailing slash / path
    // 'https://*.appnetos.com',       // Invalid: wildcard
    // 'https://user@api-dev.appnetos.com', // Invalid: credentials
],

Preflight Requests and Responses

A request is recognized as a CORS preflight only when its HTTP method is OPTIONS and both Origin and Access-Control-Request-Method are present. An ordinary OPTIONS request is not intercepted and proceeds to the remaining bootstrap steps.

OPTIONS /rest/... HTTP/1.1
Host: dns.appnetos.com
Origin: https://api-dev.appnetos.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: Authorization, Content-Type

For a valid preflight from an allowed origin, the bootstrap responds immediately, before session or authentication handling:

HTTP/1.1 204 No Content
Access-Control-Allow-Origin: https://api-dev.appnetos.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Authorization, Content-Type
Access-Control-Max-Age: 600
Preflight condition Status Behavior
Allowed origin, valid method and headers 204 Preflight accepted; request processing ends early.
Origin not allowlisted or malformed 403 Preflight rejected.
Invalid method token, forbidden method, or invalid requested header names 400 Preflight rejected.
Ordinary OPTIONS without required preflight metadata Not handled here Normal bootstrap continues.

The forbidden preflight methods are CONNECT, TRACE, and TRACK. Otherwise, the bootstrap accepts syntactically valid requested method and header tokens; it does not consult application route definitions to establish whether that method is implemented.

Preflight is not authorization

The browser may send the subsequent request, but the actual request must still pass Session Bootstrap, Security Bootstrap, route handling, authentication, and application permissions. An allowed origin does not grant access to a protected endpoint.

Response Headers and Credentials

For an active context, an allowlisted browser Origin receives its original origin value in Access-Control-Allow-Origin and Access-Control-Allow-Credentials: true. An unlisted origin receives no allow-origin permission on ordinary responses. The bootstrap appends Vary: Origin to preserve origin-dependent cache behavior.

The bootstrap exposes PHP response headers through Access-Control-Expose-Headers, excluding Set-Cookie and Set-Cookie2. It installs a PHP header callback so the CORS and frame headers are finalized again just before PHP sends the response, including headers added by later layers.

Credentials support does not override browser cookie policies, SameSite restrictions, or authentication requirements. A configured origin must be trusted.

Frame Embedding and Content Security Policy

For active contexts, the same allowlist also defines permitted frame ancestors. The bootstrap adds 'self' and every normalized configured origin to the CSP frame-ancestors directive, even when a navigation request has no Origin header.

Content-Security-Policy: frame-ancestors 'self' http://api-dev.appnetos.com https://api-dev.appnetos.com

Existing PHP-managed CSP directives other than frame-ancestors are retained. Existing PHP frame-ancestors directives are replaced, and PHP X-Frame-Options headers are removed. Separately added web-server or reverse-proxy policies remain outside this bootstrap's control and must not introduce conflicting restrictions.

Validation and Runtime Boundaries

A selected configuration file must return an array, contain an application identifier matching the resolved application, and contain a contexts array. The selected context definition must be an array, and its active value, if present, must be boolean. Only an active context requires valid origins.

Invalid configuration structures throw an exception during bootstrap. CORS does not change the resolved application, its route definitions, its runtime context, or its security identity. Process executions skip CORS entirely.

Application Customization and Update Safety

At runtime, CorsBootstrap reads the installed configuration from platform/cors/, not directly from the application's original .files directory or the customization source tree.

Next Steps

Previous

Application

Explore Application

Next

Session

Explore Session