cephios-core 0.1.0__tar.gz

cephios_core-0.1.0/.gitattributes

@@ -0,0 +1,6 @@
+# Hash-pinned conformance vectors (see tests/vectors/UPSTREAM.json): the SHA-256 pin enforced by
+# tests/test_vector_pin.py requires a byte-identical checkout on every OS. Mark the vector tree as
+# binary (-text) so git performs NO end-of-line conversion at checkout/check-in — in particular,
+# git-for-Windows autocrlf never rewrites LF->CRLF. -text is the unambiguous "never touch these
+# bytes" intent for SHA-pinned data; this is scoped to the vector tree only (no *.py / pyproject).
+tests/vectors/** -text

cephios_core-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,65 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: test (py${{ matrix.python-version }} / ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.10', '3.11', '3.12', '3.13']
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - name: checkout
+        uses: actions/checkout@v5
+
+      - name: install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: false
+
+      - name: sync (install package + dev deps)
+        run: uv sync
+
+      - name: lint (ruff)
+        run: uv run ruff check .
+
+      - name: type (mypy)
+        run: uv run mypy
+
+      - name: test (pytest)
+        run: uv run pytest
+
+      - name: conformance (§17.3 gate)
+        # Runs the full v1.0 vector suite and enforces the §17.3 per-category thresholds; exits
+        # non-zero if any gated category misses. OS-agnostic invocation (python -m, no shell-ism).
+        run: uv run python -m cephios_core.conformance
+
+  build:
+    name: build (sdist + wheel)
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/checkout@v5
+
+      - name: install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: '3.12'
+          enable-cache: false
+
+      - name: build
+        run: uv build
+
+      - name: list artifacts
+        run: ls -l dist

cephios_core-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+
+# Build artifacts
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+
+# uv (lock resolved fresh in CI for this scaffold; not committed)
+uv.lock
+
+# Tool caches
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# OS
+.DS_Store

cephios_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cephios
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cephios_core-0.1.0/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: cephios-core
+Version: 0.1.0
+Summary: The Python reference implementation of The Cephios Protocol v1.0
+Project-URL: Homepage, https://github.com/cephios/cephios-core
+Project-URL: Repository, https://github.com/cephios/cephios-core
+Project-URL: Conformance suite, https://github.com/cephios/protocol-tests
+Author: Cephios
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cephios,conformance,encryption,neural-data,protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Requires-Dist: apsw>=3.47
+Requires-Dist: argon2-cffi>=23.1
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Provides-Extra: conformance
+Description-Content-Type: text/markdown
+
+# cephios-core
+
+The Python reference implementation of **The Cephios Protocol, version 1.0** — the
+language-independent wire protocol for end-to-end-encrypted neural-data capture and ingestion.
+
+`cephios-core` implements the **client side** of the protocol (the device/SDK side that runs on
+the tenant's own machine). It is verified against the published [conformance test-vector
+suite](https://github.com/cephios/protocol-tests): it passes every §17.3 gated category — the six
+100%-threshold categories (`envelope_encryption`, `wrapped_dek`, `key_derivation`,
+`error_taxonomy`, `envelope_versioning`, `control_plane_erasure`) and `ingestion_idempotency`
+(threshold ≥ 90%). `session_lifecycle` is executed and reported but is not a §17.3 gating criterion.
+
+## Install
+
+```bash
+pip install cephios-core
+```
+
+Requires **Python 3.10+**. Runtime dependencies: `cryptography`, `httpx`, `argon2-cffi`, `apsw`.
+
+## What it implements
+
+Each surface is exposed from its own submodule (the top-level package deliberately exports only
+`__version__`):
+
+- **Argon2id member-key derivation** (`cephios_core.keyderiv`) — §5.2/§5.3 derivation of the
+  X25519 private-key seed + auth-verification token from a master password, client-side only.
+- **AES-256-GCM envelope** (`cephios_core.envelope`) — §6.1/§6.4/§6.5 `construct` (fresh random
+  nonce) / `deconstruct`, with the 16-byte header bound as AEAD associated data.
+- **X25519-ECIES wrapped DEK** (`cephios_core.wrapped_dek`) — §6.3 `wrap_dek` / `unwrap_dek` of
+  the 76-byte wrapped-DEK envelope.
+- **Durable ingestion buffer + uploader** (`cephios_core.buffer`, `cephios_core.ingest`,
+  `cephios_core.uploader`) — the §7 HTTP ingestion path (`POST /v1/ingest`, raw octet-stream body)
+  with a **persist-before-ack, never-silent** local buffer (four typed events —
+  `BufferPressure` / `BufferDrop` / `BufferRejected` / `BufferLost`) and the §7.7.4 disposition
+  uploader (200 → purge; 429 → retain + honor `Retry-After`; 5xx → retain + retry;
+  non-retryable 4xx → emit-then-purge). The `capture()` path encrypts **before** the record
+  reaches the buffer, so the buffer only ever holds ciphertext.
+- **Control-plane + key-management client** (`cephios_core.control`) — §9 sessions
+  (open / close / read), the §8 wrapped-DEK HTTP shapes (public-key upload, wrapped-DEK
+  upload / fetch / revoke), and §10.5 subject erasure.
+- **Typed error taxonomy** (`cephios_core.errors`) — the full §14 twelve-category `CephiosError`
+  hierarchy and the §14.1 wire-error decoder.
+
+The network client is async-first (`httpx.AsyncClient`) with a synchronous facade; the crypto and
+the buffer are synchronous.
+
+## Example
+
+```python
+import os
+from cephios_core.envelope import construct, deconstruct
+
+dek = os.urandom(32)                      # 32-byte AES-256 data-encryption key
+plaintext = b"neural-sample-bytes"
+envelope = construct(dek, plaintext)      # §6.4 — fresh random nonce per call
+assert deconstruct(envelope, dek) == plaintext
+```
+
+## Conformance
+
+The package ships a runner that executes the published v1.0 vectors and enforces the §17.3
+thresholds, exiting non-zero if any gated category misses. The vectors are **not** bundled in the
+wheel (they are the separate [cephios/protocol-tests](https://github.com/cephios/protocol-tests)
+suite), so pass the vector directory explicitly:
+
+```bash
+cephios-conformance path/to/protocol-tests/v1.0
+# equivalently: python -m cephios_core.conformance path/to/protocol-tests/v1.0
+```
+
+## Status & limits
+
+This is an early (**0.1.0**) release. The client-side v1.0 surface above is implemented and passes
+the published §17.3 conformance suite, but the public API may still evolve and the package is not
+yet production-hardened. The buffer's durability is proven against a **process kill** (a real
+SIGKILL of a subprocess mid-write, after which acked records survive on reopen); power-loss /
+kernel-crash durability is not yet independently proven. The Cephios cloud/server is a separate
+system and is **not** part of this package, and the realtime protocol (§11) is not implemented here.
+
+## References
+
+- Protocol specification: *The Cephios Protocol, version 1.0* (`CONTRACT_SPEC.md`).
+- Conformance test-vector suite: [cephios/protocol-tests](https://github.com/cephios/protocol-tests).
+
+## License
+
+MIT — see [LICENSE](https://github.com/cephios/cephios-core/blob/main/LICENSE).

cephios_core-0.1.0/README.md

@@ -0,0 +1,88 @@
+# cephios-core
+
+The Python reference implementation of **The Cephios Protocol, version 1.0** — the
+language-independent wire protocol for end-to-end-encrypted neural-data capture and ingestion.
+
+`cephios-core` implements the **client side** of the protocol (the device/SDK side that runs on
+the tenant's own machine). It is verified against the published [conformance test-vector
+suite](https://github.com/cephios/protocol-tests): it passes every §17.3 gated category — the six
+100%-threshold categories (`envelope_encryption`, `wrapped_dek`, `key_derivation`,
+`error_taxonomy`, `envelope_versioning`, `control_plane_erasure`) and `ingestion_idempotency`
+(threshold ≥ 90%). `session_lifecycle` is executed and reported but is not a §17.3 gating criterion.
+
+## Install
+
+```bash
+pip install cephios-core
+```
+
+Requires **Python 3.10+**. Runtime dependencies: `cryptography`, `httpx`, `argon2-cffi`, `apsw`.
+
+## What it implements
+
+Each surface is exposed from its own submodule (the top-level package deliberately exports only
+`__version__`):
+
+- **Argon2id member-key derivation** (`cephios_core.keyderiv`) — §5.2/§5.3 derivation of the
+  X25519 private-key seed + auth-verification token from a master password, client-side only.
+- **AES-256-GCM envelope** (`cephios_core.envelope`) — §6.1/§6.4/§6.5 `construct` (fresh random
+  nonce) / `deconstruct`, with the 16-byte header bound as AEAD associated data.
+- **X25519-ECIES wrapped DEK** (`cephios_core.wrapped_dek`) — §6.3 `wrap_dek` / `unwrap_dek` of
+  the 76-byte wrapped-DEK envelope.
+- **Durable ingestion buffer + uploader** (`cephios_core.buffer`, `cephios_core.ingest`,
+  `cephios_core.uploader`) — the §7 HTTP ingestion path (`POST /v1/ingest`, raw octet-stream body)
+  with a **persist-before-ack, never-silent** local buffer (four typed events —
+  `BufferPressure` / `BufferDrop` / `BufferRejected` / `BufferLost`) and the §7.7.4 disposition
+  uploader (200 → purge; 429 → retain + honor `Retry-After`; 5xx → retain + retry;
+  non-retryable 4xx → emit-then-purge). The `capture()` path encrypts **before** the record
+  reaches the buffer, so the buffer only ever holds ciphertext.
+- **Control-plane + key-management client** (`cephios_core.control`) — §9 sessions
+  (open / close / read), the §8 wrapped-DEK HTTP shapes (public-key upload, wrapped-DEK
+  upload / fetch / revoke), and §10.5 subject erasure.
+- **Typed error taxonomy** (`cephios_core.errors`) — the full §14 twelve-category `CephiosError`
+  hierarchy and the §14.1 wire-error decoder.
+
+The network client is async-first (`httpx.AsyncClient`) with a synchronous facade; the crypto and
+the buffer are synchronous.
+
+## Example
+
+```python
+import os
+from cephios_core.envelope import construct, deconstruct
+
+dek = os.urandom(32)                      # 32-byte AES-256 data-encryption key
+plaintext = b"neural-sample-bytes"
+envelope = construct(dek, plaintext)      # §6.4 — fresh random nonce per call
+assert deconstruct(envelope, dek) == plaintext
+```
+
+## Conformance
+
+The package ships a runner that executes the published v1.0 vectors and enforces the §17.3
+thresholds, exiting non-zero if any gated category misses. The vectors are **not** bundled in the
+wheel (they are the separate [cephios/protocol-tests](https://github.com/cephios/protocol-tests)
+suite), so pass the vector directory explicitly:
+
+```bash
+cephios-conformance path/to/protocol-tests/v1.0
+# equivalently: python -m cephios_core.conformance path/to/protocol-tests/v1.0
+```
+
+## Status & limits
+
+This is an early (**0.1.0**) release. The client-side v1.0 surface above is implemented and passes
+the published §17.3 conformance suite, but the public API may still evolve and the package is not
+yet production-hardened. The buffer's durability is proven against a **process kill** (a real
+SIGKILL of a subprocess mid-write, after which acked records survive on reopen); power-loss /
+kernel-crash durability is not yet independently proven. The Cephios cloud/server is a separate
+system and is **not** part of this package, and the realtime protocol (§11) is not implemented here.
+
+## References
+
+- Protocol specification: *The Cephios Protocol, version 1.0* (`CONTRACT_SPEC.md`).
+- Conformance test-vector suite: [cephios/protocol-tests](https://github.com/cephios/protocol-tests).
+
+## License
+
+MIT — see [LICENSE](https://github.com/cephios/cephios-core/blob/main/LICENSE).

cephios_core-0.1.0/pyproject.toml

@@ -0,0 +1,110 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cephios-core"
+dynamic = ["version"]
+description = "The Python reference implementation of The Cephios Protocol v1.0"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Cephios" }]
+keywords = ["cephios", "neural-data", "encryption", "protocol", "conformance"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Security :: Cryptography",
+]
+dependencies = [
+    "cryptography>=42",
+    "httpx>=0.27",
+    "argon2-cffi>=23.1",
+    # apsw is the §7.7.1 SDK durable-buffer storage engine (WAL + synchronous=FULL).
+    # Lower-bound pin only, NO upper cap: apsw uses SQLite-style versioning, NOT semver.
+    # Its version is <bundled-SQLite-version>.<apsw-packaging-revision> (e.g. 3.47.0.0 =
+    # SQLite 3.47.0, apsw rev 0). The leading "3" is SQLite's major, not a semver
+    # breaking-change boundary, so a `>=X,<4` cap would be wrong. The 3.47 floor selects a
+    # SQLite (Oct 2024) whose WAL + synchronous + PRAGMA features (all present since SQLite
+    # 3.7) we rely on, and which ships cp310-cp313 manylinux/macos/win wheels (the CI matrix).
+    "apsw>=3.47",
+]
+
+[project.optional-dependencies]
+# Conformance-runner extra (Group 12 Commit 6). Intentionally EMPTY: the §17.3 runner
+# (cephios_core.conformance) drives only the in-package crypto + the httpx-based clients, and
+# httpx is already a core dependency — so the runner needs ZERO additional dependencies. The
+# extra name is kept stable (declared in C2) for forward compatibility; install plain
+# `cephios-core` and run `cephios-conformance` (or `python -m cephios_core.conformance`).
+conformance = []
+
+# The §17.3 conformance runner CLI (Group 12 Commit 6). OS-agnostic console entry point; CI
+# invokes `python -m cephios_core.conformance` (equivalent) so it does not depend on the script
+# being on PATH across the {ubuntu,macos,windows} matrix.
+[project.scripts]
+cephios-conformance = "cephios_core.conformance:main"
+
+[project.urls]
+Homepage = "https://github.com/cephios/cephios-core"
+Repository = "https://github.com/cephios/cephios-core"
+"Conformance suite" = "https://github.com/cephios/protocol-tests"
+
+[dependency-groups]
+dev = [
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "pytest>=8",
+]
+
+[tool.hatch.version]
+path = "src/cephios_core/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cephios_core"]
+
+# hatchling does not ship non-.py package data by default; force-include the PEP 561
+# marker so an installed cephios-core is type-checkable (the by-package mypy gate).
+[tool.hatch.build.targets.wheel.force-include]
+"src/cephios_core/py.typed" = "cephios_core/py.typed"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["cephios_core", "vector_loader"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+packages = ["cephios_core"]
+
+# apsw (3.53.x) ships a PEP 646 stub: apsw/__init__.pyi:138 uses `*tuple[...]` unpacking in a
+# subscript, valid only on Python >=3.11. Under the 3.10-target check the 3.10-interpreter CI
+# cells reject it at parse time (Invalid syntax), failing the gate on a third-party stub — not
+# our code. Keep apsw opaque to mypy (skip following its stub); cephios_core stays strict.
+[[tool.mypy.overrides]]
+# Both the top-level `apsw` module (where the offending __init__.pyi:138 lives, reached via
+# `import apsw`) and any submodules: the `apsw.*` wildcard alone does NOT cover `apsw` itself.
+module = ["apsw", "apsw.*"]
+follow_imports = "skip"
+# apsw ships a .pyi stub; `follow_imports = skip` does NOT apply to stub files unless
+# follow_imports_for_stubs is also set (it defaults to false), so this key is what actually
+# stops mypy parsing apsw/__init__.pyi:138.
+follow_imports_for_stubs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+pythonpath = ["tests"]

cephios_core-0.1.0/src/cephios_core/__init__.py

@@ -0,0 +1,10 @@
+"""cephios-core — the Python reference implementation of The Cephios Protocol v1.0.
+
+This module is the single source of truth for the package version: hatchling reads
+``__version__`` here via ``[tool.hatch.version]`` in ``pyproject.toml``. The protocol
+surface itself (key derivation, envelope, wrapped-DEK, ingestion, buffer, errors) is
+implemented in subsequent Group 12 commits; this scaffold deliberately exposes nothing
+beyond the version so the public API can be added deliberately under the IS commitment.
+"""
+
+__version__ = "0.1.0"