Getting Started

Getting Started

This page describes how to run Secure Package V14 locally and use the server package engine.

Requirements

The main server workspace requires:

• PHP 8.2 or newer
• PHP Sodium extension
• PHP Zip extension
• random_bytes() support (provided by supported PHP runtimes)
• Apache/XAMPP or another PHP-capable web server for the web interface

MySQL through PDO is optional in the current codebase. The default package/account/catalog workflow is filesystem-backed.

Composer is used for development dependencies and validation, but the application runtime itself declares only PHP as a required Composer dependency.

Local web setup

Point the web server's document root at the repository's public/ directory, not the repository root.

The intended layout is:

project-root/
├── app/
├── bin/
├── config/
├── public/      <-- web root
├── storage/     <-- private runtime data
├── tests/
├── bootstrap.php
├── composer.json
└── VERSION

Do not expose the repository root directly. The project intentionally keeps configuration, storage, release signing material, and source code outside the public web surface.

First runtime check

Run:

php bin/self-check.php

The self-check verifies:

• PHP >= 8.2
• Sodium availability
• random_bytes() availability
• Argon2id support in Sodium
• PHP Zip extension availability

For the main server workspace, the Zip extension is not optional because ZIP archives are both accepted as source input and used as the portable .spkg14 transport.

Creating a package through the web UI

The normal workflow is:

1. Open the V14 web interface.
2. Sign in or create an account.
3. Select a ZIP containing the project directory.
4. Upload it through the resumable upload flow.
5. If the source ZIP is encrypted, provide the archive password when requested.
6. Wait for protected archive extraction and validation to complete.
7. Supply a project name, password, and pattern.
8. Decide whether to create a recovery key.
9. Build the V14 package.
10. Store the displayed recovery key outside the package if one was generated.
11. Download or manage the resulting package.

The recovery key is intentionally shown once by the creation workflow. It is a credential, not metadata, and is not recoverable from the package.

Server package format

Portable V14 packages use:

<package-id>.spkg14

Internally, the archive contains:

header.json
manifest.enc
complete.json
blobs/
  <48-hex>.bin

The header.json file describes the format and cryptographic profile. The manifest is encrypted. File names are encrypted inside the manifest. File contents live in authenticated ciphertext blobs.

Restoring a package

The server can open a V14 package using either:

• the original password + pattern, or
• the independent recovery key, when a recovery slot exists.

Before any restored file is written, V14 verifies package structure, header binding, manifest authentication, completion metadata, blob inventory, per-blob SHA-256 hashes, and the Merkle root. It then performs a full path preflight and rejects existing destinations.

A successful restore is written into a temporary restore directory and exposed through a short-lived restore token for download.

Local CLI example

Encrypt a directory:

php bin/encrypt-directory.php <source-dir> <output-dir> <password>

Decrypt a package directory or .spkg14 package:

php bin/decrypt-package.php <package-dir-or-spkg14> <output-dir> <password> [recovery-key]

The CLI arguments are intentionally simple, but production automation should treat passwords and recovery keys as secrets rather than placing them in shell history or process listings.

Production baseline

At minimum configure:

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

Keep storage/, environment secrets, and release signing keys outside the public web root.

First verification commands

A useful local development baseline is:

php bin/self-check.php
php bin/source-audit.php
php bin/security-test.php --full
find public/client -type f -name '*.js' -print0 | xargs -0 -n1 node --check
composer validate --strict --no-check-publish
composer install --no-interaction --prefer-dist --no-progress
composer audit --no-interaction

For a production-quality release, these gates should be run from a clean working tree and complemented by the release signing procedure described in Release and Supply Chain.

Important operational rule

Do not put passwords, patterns, or recovery keys into logs, issues, analytics, commit messages, or the release repository.