eggserve-core 0.1.1

Security policy, path confinement, and static-serving primitives for eggserve
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

# Toolchain and Language Support Policy

This document defines the supported language versions, Rust toolchain requirements, and platform targets for eggserve. It is the normative reference for toolchain compatibility; the capability matrix ([library-capability-matrix.md](library-capability-matrix.md)) and release contract ([release-contract.md](release-contract.md)) should be consulted for feature-level details.

## Rust

### Edition and Resolver

All workspace crates use Rust edition **2021** with workspace resolver **v2**.

### MSRV Policy

There is no formal minimum supported Rust version. eggserve tracks the current stable Rust toolchain. Newer stable releases may be required at any time without advance notice. There is no backward-compatibility guarantee for older compilers.

### Supported Targets

| Target | Status |
|--------|--------|
| `x86_64-unknown-linux-gnu` | Supported |
| `aarch64-unknown-linux-gnu` | Supported |
| `x86_64-apple-darwin` | Supported |
| `aarch64-apple-darwin` | Supported |
| `x86_64-pc-windows-msvc` | Supported |

Other targets may compile but are not tested in CI and are not supported.

### Feature Flags

| Feature | Crate | Default | Description |
|---------|-------|---------|-------------|
| (none) | `eggserve-core` | Yes | Core server and primitives |
| `python-bindings-internal` | `eggserve-core` | No | `ResolvedFile` extraction methods for Python bindings |
| `tls` | `eggserve-bin` | No | TLS server via rustls |

## Python

### Supported Versions

| Implementation | Status |
|----------------|--------|
| CPython 3.11+ (`>=3.11`) | Supported (abi3 stable ABI) |
| CPython < 3.11 | Unsupported |
| PyPy | Unsupported |
| Free-threaded CPython (3.13t, 3.14t) | Unsupported |

### ABI

eggserve uses the Python stable ABI (`abi3`). One abi3 wheel per OS/architecture
serves all supported CPython minor versions (3.11+). The minimum supported
version is CPython 3.11.

### Build System

Wheels are built with **maturin** (latest stable, `>=1.0, <2.0`). The build backend is declared in `pyproject.toml`.

### PyO3 Version

The Python bindings use PyO3 **0.24** with the `extension-module` and `abi3-py311` features.

### Wheel Matrix

| Platform | Wheel Target |
|----------|-------------|
| Linux x86_64 | `x86_64-unknown-linux-gnu` |
| macOS arm64 | `aarch64-apple-darwin` |
| Windows x86_64 | `x86_64-pc-windows-msvc` |

The wheel packages the platform-native extension, which includes the CLI entry
point. Users do not need a separate Rust installation to use the CLI from a
wheel, and no standalone executable is placed in the package's `bin/`
directory.

## Platform Security Classification

| Platform | Classification | Hardening |
|----------|---------------|-----------|
| Linux x86_64 | supported-hardened | Descriptor-relative traversal via `statat` + `openat`. Full symlink/dotfile/reparse hardening. Pinned root identity. |
| Linux aarch64 | supported-hardened | Same as Linux x86_64. |
| macOS arm64 | supported-hardened | Descriptor-relative traversal via `statat` + `openat`. Full symlink/dotfile hardening. Pinned root identity. |
| macOS x86_64 | supported-hardened | Same as macOS arm64. |
| Windows x86_64 | supported-functional | Handle-relative confinement and manual qualification are complete for the executed classes. Two open-descendant root-rename cases remain explicitly skipped because NTFS rejects that external path operation; Windows remains trusted/local-content only. |

### Classification Definitions

- **supported-hardened**: Full security hardening is active. Descriptor-relative traversal on Unix provides TOCTOU-resistant symlink denial. The serving root is pinned at startup (`PinnedRoot`), so renaming or replacing the configured pathname does not redirect the running server. These platforms are suitable for serving untrusted content with safe defaults.
- **supported-functional**: The server is functional and manually qualified for the executed platform classes, but the platform is not promoted to hardened public-content status. Windows has handle-relative confinement, with two skipped open-descendant root-rename cases caused by NTFS path-rename semantics. These platforms are suitable only for trusted local content.

See [security-policy.md](security-policy.md) and [non-goals.md](non-goals.md) for the full Windows hardening statement and deferred scope.

## Toolchain Requirements for Development

| Tool | Required Version | Purpose |
|------|-----------------|---------|
| Rust stable | Current stable | Building all crates, running tests |
| Python | 3.11+ (abi3 wheel) | Wheel builds, Python tests |
| maturin | `>=1.0, <2.0` | Python wheel builds |
| bash | Any POSIX-compatible | CI and local scripts (`scripts/`) |