Deployment

Deployment

Secure Package V14 should be deployed as a PHP application whose public web root is only the public/ directory.

Recommended layout

server/
├── app/              private
├── bin/              private
├── config/           private
├── public/           web root
├── storage/          private
├── tests/            private
├── bootstrap.php     private
├── composer.json     private
└── VERSION           private

Do not expose the repository root through Apache/Nginx.

Environment configuration

Recommended production baseline:

SPK_REQUIRE_HTTPS=1
SPK_PUBLIC_ORIGIN=https://your-host.example
SPK_NAME_PEPPER=<long-random-secret>

SPK_REQUIRE_HTTPS

Set to 1 to force HTTPS for the application session layer.

SPK_PUBLIC_ORIGIN

Set this explicitly in production so same-origin validation does not depend on dynamic host reconstruction.

SPK_NAME_PEPPER

Use a long random secret managed by the deployment environment.

If it is absent, V14 can generate a persistent local fallback at storage/secrets/name-pepper.bin, but controlled production secret management is preferable.

PHP extensions

The main server workspace requires:

• PHP >= 8.2
• Sodium
• Zip
• random_bytes() support

pdo_mysql is optional for the current application core.

The health endpoint reports Zip as a required component and returns degraded status when it is unavailable.

Composer

The project disables Composer plugins by configuration.

For a release, generate a real lockfile in a normal development environment:

composer update
composer validate --strict --no-check-publish
composer audit --no-interaction

Commit the real composer.lock.

CI should then use:

composer install --no-interaction --prefer-dist --no-progress
composer audit --no-interaction

Do not fabricate a lockfile in CI.

Filesystem permissions

Use restrictive permissions for:

• storage/
• package archives
• upload staging
• job state
• account storage
• rate-limit state
• audit logs
• release private keys
• deployment environment files

The web server should not have permission to execute files from package storage.

HTTPS and headers

The application emits security headers at the PHP layer, but infrastructure should still be configured correctly.

Use TLS termination that preserves the correct HTTPS signal to PHP.

Do not weaken the application's CSP or cross-origin policy merely to make a nonessential third-party asset load.

Release signing

Keep the Ed25519 private release key:

• outside the repository;
• outside the public web root;
• outside application storage;
• out of CI logs.

Sign the active source tree and distribute the exact release archive checksum with the independently trusted public key.

External trust root

For high-assurance deployment, configure:

SECURE_PACKAGE_TRUSTED_RELEASE_KEY_HEX=<64 lowercase hex chars>

The verifier then checks that the embedded release key matches this external pinned trust root.

Without an external key, embedded-key verification establishes self-consistency, not independent trust.

Recovery key handling

A V14 recovery key grants package restore without the password/pattern. Treat it as an independent credential.

Recommended handling:

• display once;
• copy to a secure offline location;
• use a password manager or secret manager with appropriate controls;
• never store it in the package itself;
• never place it in Git, issues, logs, screenshots, or analytics.

Production health check

The service exposes:

/health.php

It checks:

• PHP version
• Sodium
• Zip
• PDO MySQL as optional
• randomness API
• storage availability

The endpoint returns HTTP 200 only when all required checks pass.

Before public exposure

Run:

php bin/self-check.php
php bin/source-audit.php
php bin/security-test.php --full
composer validate --strict --no-check-publish
composer audit --no-interaction

Then run the release signing and verification procedure.

Operational caveat

No deployment guide can compensate for a compromised operating system, leaked environment secret, compromised release key, malicious PHP runtime, or compromised administrator account. Infrastructure security remains part of the overall trust model.