Skip to content

Progressive Secure Package Format (PSPF) 2025 Specification

The Progressive Secure Package Format (PSPF) 2025 is a modern, secure packaging format for distributing applications and their dependencies.

Overview

PSPF/2025 provides: - Security: Cryptographic verification and signing - Efficiency: Progressive loading and caching - Portability: Cross-platform compatibility - Modularity: Slot-based architecture for different content types

Binary Package Structure

Canonical Binary Layout

This is the authoritative specification for PSPF/2025 package structure. All other documentation should reference this diagram.

┌─────────────────────────────────┐  Offset: 0
│                                 │
│      Native Launcher Binary     │  Platform-specific executable
│      (Variable size: ~1-5 MB)   │  - Go or Rust compiled binary
│                                 │  - Handles extraction and execution
│                                 │  - Contains signature verification code
│                                 │
├─────────────────────────────────┤  Offset: launcher_size
│                                 │
│       Metadata (Compressed)     │  GZIP-compressed JSON manifest
│       (Variable size: ~10 KB)   │  - Package name, version, description
│                                 │  - Execution configuration
│                                 │  - Build metadata
│                                 │
├─────────────────────────────────┤  Offset: metadata_offset + metadata_size
│                                 │
│         Slot Table              │  Array of 64-byte slot descriptors
│    (slot_count × 64 bytes)      │  - One descriptor per slot
│                                 │  - Fixed 64-byte binary structure
│                                 │  - Contains offsets, sizes, checksums
│                                 │
├─────────────────────────────────┤  Offset: slot_table_offset + slot_table_size
│                                 │
│         Slot 0 Data             │  First slot (typically Python runtime)
│    (Compressed with tar.gz)     │  - Size: slot[0].size bytes
│                                 │  - Operations: slot[0].operations
│                                 │
├─────────────────────────────────┤  Offset: slot[0].offset + slot[0].size
│                                 │
│         Slot 1 Data             │  Second slot (typically application code)
│    (Compressed with tar.gz)     │  - Size: slot[1].size bytes
│                                 │  - Operations: slot[1].operations
│                                 │
├─────────────────────────────────┤
│            ...                  │  Additional slots as defined
├─────────────────────────────────┤
│                                 │
│         Slot N Data             │  Last slot
│    (Compressed with tar.gz)     │
│                                 │
├─────────────────────────────────┤  Offset: EOF - 8200
│  📦 (Start Magic, 4 bytes)      │  UTF-8: 0xF0 0x9F 0x93 0xA6
├─────────────────────────────────┤  Offset: EOF - 8196
│                                 │
│        Index Block              │  Fixed 8192-byte metadata block
│        (8192 bytes)             │  - Format version: 0x20250001
│                                 │  - Package size, launcher size
│                                 │  - Metadata offset and size
│                                 │  - Slot table offset and size
│                                 │  - Slot count
│                                 │  - Ed25519 public key (32 bytes)
│                                 │  - Ed25519 signature (64 bytes)
│                                 │  - SHA-256 metadata checksum
│                                 │  - Adler-32 index checksum
│                                 │
├─────────────────────────────────┤  Offset: EOF - 4
│  🪄 (End Magic, 4 bytes)        │  UTF-8: 0xF0 0x9F 0xAA 0x84
└─────────────────────────────────┘  Offset: EOF (End of File)

Size Breakdown

Total size: Magic Trailer (8200 bytes) = Start Magic (4) + Index Block (8192) + End Magic (4)

The magic trailer is always located at the end of the file: - Start Magic: 4 bytes at EOF - 8200 - Index Block: 8192 bytes at EOF - 8196 - End Magic: 4 bytes at EOF - 4

Key Components

  1. Launcher Binary (Variable)
  2. Platform-specific compiled executable
  3. Finds and reads the index block
  4. Verifies cryptographic signature
  5. Extracts slots to work environment

  6. Executes the packaged application

  7. Metadata (Variable, ~10 KB)

  8. GZIP-compressed JSON manifest
  9. Package name, version, description
  10. Slot definitions with extraction rules
  11. Execution configuration

  12. Build provenance information

  13. Slot Table (slot_count × 64 bytes)

  14. Array of fixed-size slot descriptors
  15. Each slot: id, name_hash, offset, size, original_size, operations, checksum, purpose, lifecycle, priority, platform, permissions

  16. See SLOT_DESCRIPTOR_SPECIFICATION.md for binary layout

  17. Slot Data (Variable per slot)

  18. Actual content compressed with operation chains
  19. Common: tar.gz for directories, gzip for single files

  20. Operations defined in slot descriptor

  21. Index Block (8192 bytes)

  22. Fixed-size metadata and cryptographic data
  23. Located at EOF - 8196
  24. Contains all offsets needed to parse package

  25. Ed25519 signature covers entire package except signature field

  26. Magic Trailer (8 bytes around index)

  27. Start magic: 📦 (4 bytes) at EOF - 8200
  28. End magic: 🪄 (4 bytes) at EOF - 4
  29. Used for rapid format identification

Reading Algorithm

To read a PSPF package:

  1. Seek to EOF - 4 and verify end magic (🪄)
  2. Seek to EOF - 8200 and verify start magic (📦)
  3. Read index block from EOF - 8196 (8192 bytes)
  4. Verify index checksum (Adler-32)
  5. Verify package signature (Ed25519)
  6. Read metadata from metadata_offset (size: metadata_size)
  7. Read slot table from slot_table_offset (size: slot_count × 64)
  8. Extract slots as needed based on lifecycle rules

All Other Documentation

All other binary layout diagrams in the FlavorPack documentation should link to this canonical specification rather than duplicating the structure. This ensures consistency and prevents documentation drift.

Specification Documents

Core Format Specifications

Format Enhancement Proposals (FEPs)

Future Enhancement Proposals

API Reference

For Python implementation details, see: - API Documentation - Packaging API - Builder API - Reader API - Crypto API

Concepts

Implementation