Architecture

Architecture

Secure Package V14 is organized as a layered security-oriented PHP application. The cryptographic engine is not the only security boundary; archive handling, storage, authentication, authorization, and release tooling are deliberately part of the same design.

High-level layers

Browser / CLI
     |
     v
public/*.php
     |
     v
API controller / web security
     |
     +------------------------------+
     |                              |
     v                              v
Archive workflow                Package service
     |                              |
     v                              v
Resumable upload              V14 Package Builder
     |                              |
     v                              +--> Crypto layer
Temporary job state                 |       - KDF
                                    |       - AEAD
                                    |       - stream encryption
                                    |       - Merkle
                                    |
                                    +--> Manifest / package format
                                    |
                                    +--> Package archive

Restore path:
portable package -> safe extraction -> V14 verifier -> V14 reader -> preflight -> atomic restore

Source tree responsibilities

app/Crypto/

This directory contains the cryptographic composition:

• V14KeyDerivation.php — credential wrapping, HKDF subkeys, file keys, header binding.
• V14Aead.php — XChaCha20-Poly1305 encryption/decryption and key-slot wrapping.
• V14Stream.php — secretstream-based file encryption and decryption.
• V14Merkle.php — package-wide Merkle tree construction.

The cryptographic classes are intentionally small and purpose-specific. Higher-level package code composes them rather than reimplementing primitives inline.

app/Project/

This is the V14 package domain:

• V14Descriptor.php — canonical package identity, schema, crypto profile, and format limits.
• V14PackageBuilder.php — turns a source directory into an authenticated V14 package directory.
• V14PackageReader.php — authenticates and restores a package.
• V14PackageVerifier.php — performs structural package checks before decryption.
• V14PackageService.php — integrates package building with storage and project-name management.
• PackageArchive.php — creates and safely extracts portable .spkg14 ZIP archives.
• PackageCatalog.php — records package ownership and lifecycle metadata.
• PackageId.php — validates and generates 48-hex package identifiers.
• RestoreArchive.php — prepares a restored directory for download.

app/Archive/

The archive layer deals with incoming ZIP source material. It is intentionally separate from the V14 package format because an input ZIP is untrusted external data and may be password-protected or contain nested archives.

The workflow validates paths, counts, sizes, depth, symbolic links, and nested archive limits before accepting extracted content.

app/Security/

This layer protects the web/application boundary:

• sessions and CSRF
• same-origin enforcement
• account creation and password verification
• authorization and ownership checks
• rate limiting
• access tokens
• restore tokens
• replay protection
• server-side secrets
• canonical JSON
• security diagnostics
• signed state
• project-name protection

app/Storage/

The storage layer provides atomic file writes, audit logs, temporary jobs, uploads, chunk storage, and inventory management.

app/Api/

PackageController maps API actions to application services. Request bounds JSON request sizes. JsonResponse emits non-cacheable JSON responses.

public/

The public web surface contains the user interface, API entry points, health endpoints, download handlers, and the isolated browser V13 client.

bin/

CLI helpers support encryption/decryption, cleanup, source auditing, self-checks, security tests, benchmarking, package compaction, and release signing/verification.

Build flow

The V14 build pipeline is roughly:

ZIP upload
  -> resumable upload state
  -> checksum verification (when declared)
  -> archive job
  -> safe ZIP inspection/extraction
  -> optional nested archive processing
  -> V14 builder
  -> random package root key
  -> credential/recovery slots
  -> encrypted filenames
  -> authenticated file streams
  -> ciphertext hashes
  -> Merkle root
  -> encrypted manifest
  -> completion record
  -> portable .spkg14 archive
  -> package catalog registration
  -> short-lived download token

The server removes the temporary unpacked V14 package directory after successful portable packaging so encrypted bytes are not unnecessarily duplicated.

Restore flow

package catalog lookup
  -> locate .spkg14
  -> safe ZIP extraction when necessary
  -> V14 structural verification
  -> credential/recovery unlock
  -> derive V14 subkeys
  -> authenticate manifest
  -> validate completion record
  -> inventory blobs
  -> verify every referenced ciphertext hash
  -> reject unreachable blobs
  -> recompute Merkle root
  -> full path preflight
  -> create restore directory
  -> directories first
  -> files through atomic temporary restores
  -> issue short-lived restore token

The most important architectural property is the ordering: integrity verification occurs before plaintext restore output begins.

Security boundaries

There are four major boundaries:

Cryptographic boundary

Credentials unlock a wrapping key. The wrapping key unlocks a random package root key. The root key derives dedicated subkeys.

Integrity boundary

Header binding, AEAD authentication, SHA-256 blob hashes, completion metadata, and the Merkle root jointly protect package consistency.

Filesystem boundary

Input archive paths and output restore names are independently validated. Existing output paths are rejected. Writes use temporary files before final rename.

Release trust boundary

The signed release manifest covers the active source tree and can be verified against an externally supplied Ed25519 trust root.

Design philosophy

The project intentionally prefers explicit failure and conservative behavior over permissive parsing. Unsupported formats are rejected rather than guessed. Unsafe names are rejected rather than normalized into potentially ambiguous alternatives. A partially validated package is not treated as safe plaintext input.