zeropx-layercomp 0.1.0__py3-none-any.whl

layercomp/__init__.py

@@ -0,0 +1,28 @@
+"""layercomp — algebraic composition of defense-in-depth layers.
+
+Resolves the min-vs-sum-dB tension observed across security frameworks:
+- ZK/cryptography → min (weakest-link adversarial model)
+- EM shielding → sum-in-dB (passive independent attenuation)
+- Consensus systems → max (honest-majority)
+
+The correct operator depends on (threat_model, independence, correlation)
+of each layer stack. Default is min (most conservative).
+"""
+
+from .composition import (
+    Layer,
+    ThreatModel,
+    ScoreUnit,
+    CompositionResult,
+    compose,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "Layer",
+    "ThreatModel",
+    "ScoreUnit",
+    "CompositionResult",
+    "compose",
+    "__version__",
+]

layercomp/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

layercomp/cli.py

@@ -0,0 +1,131 @@
+"""layercomp CLI."""
+import argparse
+import json
+import sys
+from typing import List
+
+from .composition import Layer, ThreatModel, ScoreUnit, compose
+from . import __version__
+
+
+def _load_stack(path: str) -> List[Layer]:
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    layers = []
+    for l in data["layers"]:
+        layers.append(
+            Layer(
+                name=l["name"],
+                score=float(l["score"]),
+                unit=ScoreUnit(l.get("unit", "bits")),
+                threat_model=ThreatModel(l.get("threat_model", "adversarial")),
+                independent=bool(l.get("independent", True)),
+                notes=l.get("notes"),
+            )
+        )
+    return layers
+
+
+def cmd_score(args) -> int:
+    layers = _load_stack(args.file)
+    result = compose(layers)
+
+    if args.format == "json":
+        out = {
+            "total": result.total,
+            "unit": result.unit.value,
+            "operator_used": result.operator_used,
+            "layer_that_determined": result.layer_that_determined,
+            "rationale": result.rationale,
+            "per_layer": result.per_layer,
+            "warnings": result.warnings,
+        }
+        print(json.dumps(out, indent=2, ensure_ascii=False))
+    else:
+        print(f"layercomp v{__version__}")
+        print()
+        print(f"Composition result")
+        print(f"  operator:   {result.operator_used}")
+        print(f"  total:      {result.total} {result.unit.value}")
+        if result.layer_that_determined:
+            print(f"  determined: {result.layer_that_determined}")
+        print()
+        print(f"Rationale: {result.rationale}")
+        print()
+        print("Per-layer:")
+        for name, meta in result.per_layer.items():
+            marker = " * " if name == result.layer_that_determined else "   "
+            note = f" — {meta['notes']}" if meta.get("notes") else ""
+            print(
+                f"{marker}{name}: {meta['score']} {meta['unit']} "
+                f"[{meta['threat_model']}, indep={meta['independent']}]{note}"
+            )
+        if result.warnings:
+            print()
+            print("Warnings:")
+            for w in result.warnings:
+                print(f"  ! {w}")
+
+    return 0
+
+
+def cmd_explain(args) -> int:
+    """Show the decision tree used by compose()."""
+    print(
+        """layercomp decision tree
+=======================
+
+Given a stack of defense layers, the operator is chosen as follows:
+
+  1. If ANY layer has threat_model = ADVERSARIAL, or if threat models are mixed
+     → use min (weakest-link, most conservative). This matches:
+        - ZK security: lambda_efetiva = min{lambda_alg, lambda_FRI, ...}
+        - Container escape: attacker needs to break just one namespace/cap
+        - Jurisdictional gates: one regulator denying is enough
+
+  2. If ALL layers are CONSENSUS
+     → use max (honest-majority; system fails only if majority fails). Matches:
+        - BFT protocols
+        - Multi-sig (m-of-n where n-m+1 must fail)
+
+  3. If ALL layers are PASSIVE and all independent
+     → use sum-in-dB (equivalent to product in linear). Matches:
+        - EM shielding: SE_total_dB = SE_ns + SE_cgroup + ...
+        - Statistical decorrelation of independent side channels
+        - Noise attenuation stages
+
+  4. If PASSIVE but layers are dependent
+     → downgrade to min (with warning). Correlation invalidates additivity.
+
+Notes
+-----
+- Mixed units emit a warning; composition assumes homogeneous units.
+- "Independent" means: attacker cannot use one layer's weakness to bypass another.
+- "Adversarial" is the default and safest assumption when in doubt.
+"""
+    )
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="layercomp",
+        description="Compose defense layers with the correct algebraic operator (min/sum-dB/max)",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subs = parser.add_subparsers(dest="command", required=True)
+
+    p_score = subs.add_parser("score", help="Compute composed score for a defense stack")
+    p_score.add_argument("file", help="Path to JSON file describing the layer stack")
+    p_score.add_argument("--format", choices=["text", "json"], default="text")
+    p_score.set_defaults(func=cmd_score)
+
+    p_explain = subs.add_parser("explain", help="Show the decision tree used by compose()")
+    p_explain.set_defaults(func=cmd_explain)
+
+    args = parser.parse_args()
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

layercomp/composition.py

@@ -0,0 +1,149 @@
+"""Core composition algebra."""
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional, Dict, Any
+
+
+class ThreatModel(Enum):
+    ADVERSARIAL = "adversarial"  # attacker chooses weakest link (crypto, security bounds)
+    PASSIVE = "passive"          # random noise/leakage, all layers filter (EM shielding, statistical isolation)
+    CONSENSUS = "consensus"      # need majority to fail (BFT, multi-sig, honest-majority)
+
+
+class ScoreUnit(Enum):
+    BITS = "bits"        # cryptographic bit-security
+    DB = "dB"            # decibels (10*log10 or 20*log10 of ratio)
+    LINEAR = "linear"    # linear probability, factor, or dimensionless ratio
+    ORDINAL = "ordinal"  # relative rank only, no arithmetic guaranteed
+
+
+@dataclass
+class Layer:
+    name: str
+    score: float
+    unit: ScoreUnit = ScoreUnit.BITS
+    threat_model: ThreatModel = ThreatModel.ADVERSARIAL
+    independent: bool = True
+    notes: Optional[str] = None
+
+    def __post_init__(self):
+        if not isinstance(self.unit, ScoreUnit):
+            self.unit = ScoreUnit(self.unit)
+        if not isinstance(self.threat_model, ThreatModel):
+            self.threat_model = ThreatModel(self.threat_model)
+
+
+@dataclass
+class CompositionResult:
+    total: float
+    unit: ScoreUnit
+    operator_used: str
+    layer_that_determined: Optional[str]
+    per_layer: Dict[str, Dict[str, Any]]
+    warnings: List[str] = field(default_factory=list)
+    rationale: str = ""
+
+
+def compose(layers: List[Layer], target_unit: Optional[ScoreUnit] = None) -> CompositionResult:
+    """Compose defense layers into a single bound using the correct operator.
+
+    Decision tree:
+    - If any threat model is ADVERSARIAL, or mixed models → use min (most conservative)
+    - If all layers PASSIVE and all independent → use sum-in-dB (equivalent to product in linear)
+    - If all layers CONSENSUS → use max
+    - If dependent layers with passive/consensus model → downgrade to min with warning
+    """
+    if not layers:
+        raise ValueError("no layers provided")
+
+    warnings: List[str] = []
+    threat_models = set(l.threat_model for l in layers)
+    units = set(l.unit for l in layers)
+
+    if len(units) > 1:
+        warnings.append(
+            f"mixed units {[u.value for u in units]} — composition assumes homogeneous units; "
+            "convert layers to a single unit before composition or interpret result cautiously"
+        )
+
+    if target_unit is None:
+        target_unit = layers[0].unit
+
+    # Determine operator
+    if ThreatModel.ADVERSARIAL in threat_models:
+        primary = ThreatModel.ADVERSARIAL
+        if len(threat_models) > 1:
+            warnings.append(
+                f"mixed threat models {[t.value for t in threat_models]} — falling back to adversarial (min)"
+            )
+    elif threat_models == {ThreatModel.CONSENSUS}:
+        primary = ThreatModel.CONSENSUS
+    elif threat_models == {ThreatModel.PASSIVE}:
+        all_indep = all(l.independent for l in layers)
+        if not all_indep:
+            warnings.append(
+                "passive threat model with dependent layers — additive composition unsafe; "
+                "falling back to min"
+            )
+            primary = ThreatModel.ADVERSARIAL
+        else:
+            primary = ThreatModel.PASSIVE
+    else:
+        primary = ThreatModel.ADVERSARIAL
+
+    # Apply operator
+    if primary == ThreatModel.ADVERSARIAL:
+        operator = "min"
+        determining = min(layers, key=lambda l: l.score)
+        total = determining.score
+        det_name = determining.name
+        rationale = (
+            "adversarial threat model — attacker selects weakest layer. "
+            "Composition is the minimum score across layers."
+        )
+    elif primary == ThreatModel.PASSIVE:
+        if target_unit == ScoreUnit.DB:
+            operator = "sum-in-dB"
+            total = sum(l.score for l in layers)
+        else:
+            operator = "sum-in-dB (raw)"
+            total = sum(l.score for l in layers)
+            warnings.append(
+                f"passive composition on non-dB unit ({target_unit.value}) is unusual; "
+                "consider recasting layers in dB — result reported as raw sum"
+            )
+        det_name = None
+        rationale = (
+            "passive threat model with independent layers — attenuations add. "
+            "In dB this is sum; in linear it would be product of factors."
+        )
+    else:  # CONSENSUS
+        operator = "max"
+        determining = max(layers, key=lambda l: l.score)
+        total = determining.score
+        det_name = determining.name
+        rationale = (
+            "consensus / honest-majority model — system fails only when majority fails. "
+            "Composition is the maximum score across layers (strongest quorum member)."
+        )
+
+    per_layer = {
+        l.name: {
+            "score": l.score,
+            "unit": l.unit.value,
+            "threat_model": l.threat_model.value,
+            "independent": l.independent,
+            "notes": l.notes,
+        }
+        for l in layers
+    }
+
+    return CompositionResult(
+        total=total,
+        unit=target_unit,
+        operator_used=operator,
+        layer_that_determined=det_name,
+        per_layer=per_layer,
+        warnings=warnings,
+        rationale=rationale,
+    )

zeropx_layercomp-0.1.0.dist-info/METADATA

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: zeropx-layercomp
+Version: 0.1.0
+Summary: Algebraic composition of defense-in-depth layers — pick min, sum-dB, or max correctly
+Project-URL: Homepage, https://github.com/NixEngine/zeropx-layercomp
+Project-URL: Repository, https://github.com/NixEngine/zeropx-layercomp
+Project-URL: Issues, https://github.com/NixEngine/zeropx-layercomp/issues
+Author-email: "Dr. Vander Geraldo Rodrigues da Cunha Júnior" <vgrcjr@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: audit,composition,container,cryptography,defense-in-depth,security,zk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# zeropx-layercomp
+
+**Algebraic composition of defense-in-depth layers.** Pick the right operator (min, sum-dB, or max) based on the threat model — not by habit.
+
+## Why
+
+There is a subtle but consequential inconsistency in how the literature composes layered defenses:
+
+- **ZK / cryptographic security** uses `λ_efetiva = min{λ_alg, λ_FRI, λ_hash, ...}` — the weakest link.
+- **EM shielding / passive attenuation** uses `SE_total_dB = SE_1 + SE_2 + ...` — additive in decibels (product in linear).
+- **Consensus systems** use `max` — you fail only if the majority does.
+
+The same word "defense-in-depth" describes all three, but the arithmetic is different, and the wrong choice can inflate a bound by orders of magnitude.
+
+`layercomp` implements the decision tree and lets you feed a stack description and get the correctly composed score, with an explanation of which operator was used and why.
+
+## Install
+
+```bash
+pip install zeropx-layercomp
+```
+*(Python import module: `layercomp` | CLI command: `layercomp`)*
+
+Zero runtime dependencies. Python 3.10+.
+
+## Quick start
+
+Describe your stack in a JSON file:
+
+```json
+{
+  "layers": [
+    { "name": "arithmetization", "score": 128, "unit": "bits", "threat_model": "adversarial" },
+    { "name": "FRI",              "score": 100, "unit": "bits", "threat_model": "adversarial" },
+    { "name": "Poseidon2",        "score":  95, "unit": "bits", "threat_model": "adversarial",
+      "notes": "BBLP22 instance ~2^95, marked Unresolved by Least Authority" }
+  ]
+}
+```
+
+Then:
+
+```bash
+layercomp score my-zk-stack.json
+```
+
+Output:
+
+```
+layercomp v0.1.0
+
+Composition result
+  operator:   min
+  total:      95 bits
+  determined: Poseidon2
+
+Rationale: adversarial threat model — attacker selects weakest layer.
+Composition is the minimum score across layers.
+
+Per-layer:
+   arithmetization: 128 bits [adversarial, indep=True]
+   FRI: 100 bits [adversarial, indep=True]
+ * Poseidon2: 95 bits [adversarial, indep=True] — BBLP22 instance ~2^95, marked Unresolved by Least Authority
+```
+
+## Decision tree
+
+```
+layercomp explain
+```
+
+Prints:
+
+```
+1. Any layer ADVERSARIAL or mixed → min (most conservative)
+2. All CONSENSUS → max (honest-majority)
+3. All PASSIVE and all independent → sum-in-dB
+4. PASSIVE but dependent → downgrade to min with warning
+```
+
+## The common mistake this fixes
+
+Two frameworks routinely conflate these operators:
+
+- Container hardening scored with `SE_container = SE_ns + SE_cgroup + SE_seccomp + SE_net` is wrong under the adversarial model (attacker needs to escape *one* namespace, not all). It should be `min(...)`.
+- Meanwhile, `sum-in-dB` is the right composition for a Faraday cage against a passive EM leakage — the field really is attenuated through every layer in series.
+
+The distinction is `who is choosing the attack path`: an adversary chooses the weakest link; nature/noise flows through everything.
+
+## As a library
+
+```python
+from layercomp import Layer, ThreatModel, ScoreUnit, compose
+
+result = compose([
+    Layer("arithmetization", 128, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+    Layer("FRI",              100, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+    Layer("Poseidon2",         95, ScoreUnit.BITS, ThreatModel.ADVERSARIAL),
+])
+
+print(result.total)              # 95
+print(result.operator_used)      # 'min'
+print(result.layer_that_determined)  # 'Poseidon2'
+print(result.rationale)          # human-readable explanation
+```
+
+## Testing
+
+```bash
+pip install -e ".[test]"
+python -m pytest tests/ -v
+```
+
+## Companion tools
+
+`zeropx-layercomp` is part of the ZeroPx Auditor's Toolkit of zero-dependency Python packages:
+
+- **zeropx-gguf-inspect** — static read-only inspection of GGUF model files without loading them
+- **zeropx-corpus-scan** — byte-honest SHA-256 inventory of a document corpus
+- **zeropx-receipt-chain** — append-only tamper-evident event ledger
+- **zeropx-poseidon2-goldilocks** — pure-Python Poseidon2 reference implementation over Goldilocks
+
+## Author & Provenance
+
+**Sole Author:** Dr. Vander Geraldo Rodrigues da Cunha Júnior (`vgrcjr@gmail.com`).
+
+*Technical & AI-Assisted Provenance Disclosure:* Auxiliary computational/LLM tooling was used strictly for boilerplate and test-harness scaffolding under 1:1 human architectural design, algebraic verification, code review, and sole human authorship. Zero runtime third-party or AI dependencies.
+
+## License
+
+MIT.

zeropx_layercomp-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+layercomp/__init__.py,sha256=uYWWOlLKz9IuQ4qq8kr5dx29pVMk-EtDNlh_hKPz1DQ,698
+layercomp/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+layercomp/cli.py,sha256=j0Lxy_CGXYpQQbDF4vUHRM0zrv37TQaMgniWiv7ipqE,4563
+layercomp/composition.py,sha256=oaKJy2KeIMhzSRA8fx-okUIZcaojsOpilN0pbsBaZMQ,5341
+zeropx_layercomp-0.1.0.dist-info/METADATA,sha256=3UPctnBXd9xTqKlXuj0Lnw0MivoTxf9geAAtpTohrFU,5765
+zeropx_layercomp-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+zeropx_layercomp-0.1.0.dist-info/entry_points.txt,sha256=yzlSH2vPgflsIRfB9QGI8MLjhbH_KpALc8LBwosziiU,49
+zeropx_layercomp-0.1.0.dist-info/licenses/LICENSE,sha256=SX_pPYQ-U0R-NtHc52RS7HRijupxgXsZya1ioFUdv2U,1102
+zeropx_layercomp-0.1.0.dist-info/RECORD,,

zeropx_layercomp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

zeropx_layercomp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+layercomp = layercomp.cli:main

zeropx_layercomp-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dr. Vander Geraldo Rodrigues da Cunha Júnior
+
+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.