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 Bootstrap

The seventh bootstrap step applies early, context-specific HTTP access restrictions before APPNETOS initializes autoloading, class extensions and the core runtime.

Purpose and Execution

Bootstrap\Security\SecurityBootstrap runs after Session Bootstrap and before Autoload Bootstrap. Application Bootstrap has already resolved the active application and exact runtime context. Security Bootstrap reads the optional installed security definition and applies its rules before ordinary application execution.

Security is configured per runtime context, not globally for an application. A context without a security definition receives no early Basic, Bearer or IP restrictions from this bootstrap. Process runtimes and requests without an active application are skipped.

// Simplified execution order in SecurityBootstrap::boot().
if ($runtimeState->getProcess()) {
    return;
}

// After resolving the active application and exact context:
$this->handleIpAccess($contextSecurity);
$this->handleBasicAuth($contextSecurity);
$this->handleBearerAuth($contextSecurity);

The handlers above are invoked sequentially in the current implementation. The recommended configuration activates only one HTTP authentication mechanism per context.

Request Security Flow

The diagram shows the configured IP check followed by a single chosen HTTP authentication method. Denied IPs receive HTTP 403; failed authentication receives HTTP 401. Successful requests continue through the remaining bootstrap sequence.

SecurityBootstrap flow: load exact-context security, evaluate IP deny and allow lists, choose either Basic or Bearer authentication, and continue or return 401 or 403.
The diagram presents the supported configuration practice: one active authentication mechanism per context, optionally combined with IP access rules.

Configuration File Resolution

Security Bootstrap reads the installed runtime configuration from platform/security/. It does not read application installation templates from .files/ and does not resolve custom source files directly.

platform/security/appnetos-api-dev.php
platform/security/appnetos-api-dev.docker.php

When APPNETOS_ENVIRONMENT is docker and the environment-specific file exists, it replaces the standard configuration in full. Files are not merged. If neither file exists, no early security restrictions are configured by this bootstrap.

Complete Application Security Example

APPNETOS API Dev illustrates the typical separation between browser administration and administrative REST access. The admin runtime context uses Basic Authentication; admin-rest uses Bearer Authentication.

<?php

return [
    'application' => 'appnetos-api-dev',
    'contexts' => [
        'admin' => [
            'basic_auth' => [
                'active' => true,
                'realm' => 'APPNETOS API Dev',
                'users' => [
                    'admin' => '<password_hash>',
                ],
            ],
        ],
        'admin-rest' => [
            'bearer_auth' => [
                'active' => true,
                'tokens' => [
                    'admin' => '<token_hash>',
                ],
            ],
        ],
    ],
];

The placeholder values represent hashes created with password_hash(), not plaintext credentials. Never copy published example credentials into a production configuration.

Configuration Reference

Key Type Behavior
application string Required; must match the active application and configuration filename stem.
contexts array Required map of exact runtime-context names.
contexts.<context>.basic_auth.active bool Optional; enabled only when strictly true.
basic_auth.realm string Optional non-empty challenge realm; defaults to APPNETOS.
basic_auth.users array Required non-empty username-to-password-hash map when Basic is active.
contexts.<context>.bearer_auth.active bool Optional; enabled only when strictly true.
bearer_auth.tokens array Required non-empty token-name-to-token-hash map when Bearer is active.
contexts.<context>.ip_access.active bool Optional; enabled only when strictly true.
ip_access.allow array Optional list of allowed IP addresses and CIDR ranges; a non-empty list requires a match.
ip_access.deny array Optional list of denied IP addresses and CIDR ranges; checked before allow rules.

Only the security definition for contexts[<resolved-runtime-context>] is considered. There is no fallback to default_context or the base_context. Invalid active rule definitions can throw bootstrap exceptions.

HTTP Basic Authentication

Basic Authentication reads a username and password from PHP authentication variables or the Authorization: Basic header. The configured password hash is verified using password_verify(). A successful authentication stores the username under the basic key of the runtime security identity.

'admin' => [
    'basic_auth' => [
        'active' => true,
        'realm' => 'APPNETOS DNS Control',
        'users' => [
            'admin' => '<password_hash>',
        ],
    ],
],

A missing or invalid credential produces 401 Unauthorized and a WWW-Authenticate: Basic challenge with the configured realm. A realm is a browser authentication label, not a username.

HTTP Bearer Authentication

Bearer Authentication reads the token from the Authorization: Bearer header and verifies it against the configured token hashes with password_verify(). The token name is an internal identifier; the submitted secret token is not stored in RuntimeState.

'admin-rest' => [
    'bearer_auth' => [
        'active' => true,
        'tokens' => [
            'admin' => '<token_hash>',
        ],
    ],
],

A missing or invalid token produces 401 Unauthorized with WWW-Authenticate: Bearer. A successful request records the configured token name as the bearer runtime security identity.

One Authentication Method per Context

Context setup Recommended use
Basic active, Bearer inactive Supported pattern
Bearer active, Basic inactive Supported pattern
Both inactive No HTTP authentication from these two mechanisms
Both active Do not configure; ordinary Authorization-header authentication cannot satisfy both

Implementation detail: The current SecurityBootstrap does not explicitly reject this combination during configuration validation. It invokes both handlers sequentially. This is a configuration rule, not a claimed built-in exclusivity exception.

IP Access Control

IP rules can be used independently or alongside the chosen authentication method. The bootstrap reads the client address from $_SERVER['REMOTE_ADDR'], evaluates deny entries first, and then applies an optional allow list. IPv4 and IPv6 addresses and CIDR notation are supported.

'admin' => [
    'ip_access' => [
        'active' => true,
        'allow' => [
            '192.0.2.0/24',
            '2001:db8::/32',
        ],
        'deny' => [
            '192.0.2.55',
        ],
    ],
    'basic_auth' => [
        'active' => true,
        'realm' => 'APPNETOS Administration',
        'users' => ['admin' => '<password_hash>'],
    ],
],

The addresses above are documentation-only ranges. Replace them with the actual trusted network ranges.

A denied client or a client that fails a non-empty allow list receives 403 Forbidden before HTTP authentication is evaluated.

Generate and Replace Credentials

APPNETOS application packages include administrative security defaults. The initial Basic credentials are admin:admin, and the initial Bearer token is admin. Replace both before exposing an installation to untrusted networks.

php -r "echo password_hash('replace-with-a-strong-password', PASSWORD_DEFAULT) . PHP_EOL;"
php -r "echo password_hash('replace-with-a-long-random-token', PASSWORD_DEFAULT) . PHP_EOL;"

Insert the resulting hashes into basic_auth.users and bearer_auth.tokens, respectively. The token-name key can remain a descriptive identifier, but the actual token secret must be independently generated and securely distributed.

Request Outcomes and Runtime Effects

Condition Outcome
Process runtime or no active application Security Bootstrap skips early HTTP checks.
No security file or no exact-context entry No early restrictions from this bootstrap.
IP denied / not on non-empty allow list 403 Forbidden.
Basic credentials missing or invalid 401 Unauthorized with Basic challenge.
Bearer token missing or invalid 401 Unauthorized with Bearer challenge.
All configured checks pass Security identity is stored in RuntimeState; bootstrap continues.
Malformed active configuration Bootstrap exception (where explicitly validated).

These are early HTTP restrictions. Passing them does not bypass application authorization, permissions, or later security checks. CORS preflight handling occurs earlier in the bootstrap sequence; a permitted preflight is not a successful authenticated REST request.

Customization and Update Safety

Security Bootstrap only reads the installed files in platform/security/; it does not load customization sources. For the custom installation workflow, see the separate Application Customization and Custom Installation documentation.

Next Steps

Previous

Session

Explore Session

Next

Autoload

Explore Autoload