metaspace-membrane 0.3.1__tar.gz

metaspace_membrane-0.3.1/LICENSE

@@ -0,0 +1,113 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Szőke László-Ferenc — MetaSpace.Bio Engine Project
+                      (admin@metaspace.bio)
+
+Licensed Work:        MetaSpace Membrane — the contents of this repository.
+                      The Licensed Work is (c) 2026 Szőke László-Ferenc.
+                      Patent pending.
+
+Additional Use Grant: You may use, copy, modify, create derivative works of,
+                      and redistribute the Licensed Work for any purpose
+                      except a Competing Use. A "Competing Use" means offering
+                      the Licensed Work or a derivative of it to third parties
+                      as a commercial product or hosted service whose primary
+                      value is a safety, guardrail, or policy-enforcement
+                      membrane for AI-generated or AI-agent software. All other
+                      use is granted free of charge — including internal use,
+                      research, education, evaluation, and non-competing
+                      commercial products that merely depend on the Licensed
+                      Work.
+
+Change Date:          The fourth anniversary of the date the Licensed Work is
+                      released for each specific version.
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact admin@metaspace.bio.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph above
+terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies separately
+for each version of the Licensed Work and the Change Date may vary for each
+version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of
+the Licensed Work. If you receive the Licensed Work in original or modified form
+from a third party, the terms and conditions set forth in this License apply to
+your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other versions
+of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor as
+expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license your
+works, and to refer to it using the trademark "Business Source License", as long
+as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Notices
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.

metaspace_membrane-0.3.1/PKG-INFO

@@ -0,0 +1,383 @@
+Metadata-Version: 2.4
+Name: metaspace-membrane
+Version: 0.3.1
+Summary: A deterministic safety membrane for machine-generated software (MetaSpace.Bio Engine Project).
+Author-email: Szőke László-Ferenc <admin@metaspace.bio>
+License: BUSL-1.1
+Project-URL: Homepage, https://metaspace.bio
+Project-URL: Repository, https://github.com/LemonScripter/metaspace-membrane
+Project-URL: Issues, https://github.com/LemonScripter/metaspace-membrane/issues
+Project-URL: Landing, https://ai-membrane.metaspace.bio
+Keywords: security,sandbox,webassembly,capability,ai-safety,guardrail,claude-code,agent-safety
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: License :: Other/Proprietary License
+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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: pro
+Requires-Dist: cryptography>=41; extra == "pro"
+Provides-Extra: proofs
+Requires-Dist: wasmtime>=13; extra == "proofs"
+Requires-Dist: cryptography>=41; extra == "proofs"
+Dynamic: license-file
+
+# MetaSpace Membrane
+
+**A deterministic safety membrane for machine-generated software.**
+
+![proofs: reproducible](https://img.shields.io/badge/proofs-reproducible-brightgreen)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21426514.svg)](https://doi.org/10.5281/zenodo.21426514)
+![License: BUSL-1.1](https://img.shields.io/badge/license-BUSL--1.1-blue)
+
+MetaSpace Membrane turns an *undecidable* question — *"is this AI doing the right thing?"* —
+into a *decidable* one — *"is this effect inside the declared boundary?"* — and enforces the
+answer **deny-by-default**. One `.bio` constitution, three membranes, two products.
+
+> Part of the **MetaSpace.Bio Engine Project** — Szőke László-Ferenc (admin@metaspace.bio).
+> **Patent pending.**
+
+---
+
+## Watch the 60-second explainer
+
+[![MetaSpace Membrane — 60-second explainer](assets/explainer-poster.png)](assets/explainer.mp4)
+
+*Containment, not correctness — the idea in one minute.* ▶ click to play
+
+---
+
+## Screenshots
+
+**The Warden control panel** (`metaspace ui`) — a localhost web UI to configure the membrane
+per working directory. No config files to hand-edit; every project shows its mode
+(observe / dry-run / **enforcing**) at a glance.
+
+![MetaSpace Warden control panel](assets/panel.png)
+
+**The one-line pitch** — the agent can be *completely* deceived; the harmful effect still
+cannot occur.
+
+![MetaSpace Warden — deny-by-default containment layer](assets/landing.png)
+
+---
+
+## Why
+
+You cannot prove that a generated program does the right thing (Rice's theorem — undecidable).
+So we stop verifying intent and **contain effects** instead. A membrane sits at a chokepoint,
+reads the constitution, and blocks anything not explicitly granted. A bug becomes *a deviation
+from the constitution* — machine-measurable and enforceable.
+
+The guarantee is only as hard as the chokepoint is unbypassable:
+
+```
+heuristic    ->  language guard  ->  harness hook  ->  WebAssembly
+(advisory)       (bypassable)        (hard on agent)   (unbypassable)
+```
+
+> **Case study — "Friendly Fire" (AI Now Institute, 2026):** a prompt-injected coding agent is
+> steered by a malicious repo into running a payload → RCE. We assume the model is *fully*
+> deceived and still make the effect unreachable. A real functional payload fires without the
+> membrane and never with it. See **[`docs/THREAT_FRIENDLY_FIRE.md`](docs/THREAT_FRIENDLY_FIRE.md)**
+> · reproduce with `python evidence/run_friendly_fire_proof.py`.
+
+## Install & try (60 seconds)
+
+```bash
+pip install "git+https://github.com/LemonScripter/metaspace-membrane"
+metaspace install     # user-level, starts in dry-run (observe, no blocking)
+metaspace demo        # live self-test: watch it block the attack, then `metaspace enforce`
+```
+
+![`metaspace demo` — the "Friendly Fire" attack blocked live](assets/demo.gif)
+
+*`metaspace demo` running the real hook: the agent is assumed fully deceived, yet every attack effect is blocked while normal work still runs.*
+
+Requires **Python 3.10+** (the hook has zero third-party dependencies — nothing else to install).
+The membrane installs **outside any project's write scope**, so a prompt-injected agent cannot
+disable it. Full guide + honest scope: **[`docs/INSTALL.md`](docs/INSTALL.md)**.
+
+---
+
+## Two products, one engine
+
+| | **Product A — App membrane** | **Product B — Agent membrane** |
+|---|---|---|
+| Contains | any application ⊂ its `.bio` | the coding assistant ⊂ its limits |
+| Chokepoint | WebAssembly capability import | Claude Code PreToolUse hook |
+| Guarantee | **unbypassable** (hard, WebAssembly only) | hard on the agent (sits outside it) |
+| Status | WebAssembly/WASI **or** OS-sandbox (Landlock): real native programs, kernel-contained | **Warden MVP** — install → enforce → report loop, proven end-to-end |
+
+Both are built on the same `core/` decision engine (`guard.py`) and the same `.bio` file.
+
+---
+
+## Status & maturity
+
+This is a **research prototype / reference implementation** (TRL ~3–4). The mechanisms are real,
+falsifiable, and enforced by real substrates — run `python evidence/run_falsification.py` to make
+the repo try (and fail) to prove itself hollow, and `python evidence/run_fuzz.py` for 5000
+adversarial cases. They are demonstrated on **real programs** and fuzzed inputs, but at lab scale,
+by a single author, **without a third-party security audit or production users**. "Patent pending"
+refers to the underlying method; the two "products" are working **proofs-of-concept**, not shipped
+software. See [`SECURITY.md`](SECURITY.md) for the threat model and how to try to break it.
+
+---
+
+## The `metaspace` CLI
+
+```bash
+pip install .                             # installs the `metaspace` command
+metaspace init .                          # synthesize a draft constitution from your code
+metaspace ratify metaspace.bio            # review + justify + stamp RATIFIED
+metaspace gate metaspace.bio              # exit 0 only if RATIFIED (use in CI)
+metaspace report path/to/audit.jsonl      # human-readable session safety report
+```
+
+One entry point over the engine: `synthesize`, `ratify`, `gate`, `report`, `init`. Cross-platform
+by construction, and **verified on Linux**: `run_proofs.py` is green on Debian (kernel 6.1,
+Python 3.11) and on Windows — **22/22 on Linux** (including the kernel-enforced Landlock
+sandbox) and 21 pass + 1 skip on Windows (the Landlock proof runs only where the OS provides
+it). The runs also surfaced and fixed real bugs (a path-portability bug, a shared-parser bug).
+macOS is not yet verified (no host available) — see [`SECURITY.md`](SECURITY.md).
+
+---
+
+## Run the proofs (the evidence is a reproducible run)
+
+```bash
+pip install wasmtime
+python run_proofs.py        # runs every proof; exit 0 if all pass
+```
+
+Or run them individually:
+
+```bash
+python products/app_membrane/run_wasm_demo.py         # every capability kind mediated (FS/NET/ENV/SUBPROCESS): 4 ALLOW / 5 DENY
+python products/app_membrane/bypass_proof.py          # ungranted gate -> unknown import (blocked)
+python products/app_membrane/wasi/run_wasi_demo.py    # real Rust program contained by WASI capabilities
+python evidence/run_landlock_demo.py                  # real native program OS-confined by .bio (Linux/Landlock, M3)
+python evidence/demos/run_synth_demo.py               # code -> constitution -> enforcement (closed loop)
+python evidence/demos/run_ratify_demo.py              # ratification is content-bound (tamper detected)
+python evidence/demos/run_gate_demo.py                # production gate: only RATIFIED runs
+python evidence/demos/run_knowledge_demo.py           # 2 ALLOW / 5 DENY (hallucination blocked)
+python evidence/demos/run_entailment_demo.py          # soft tier flags faithfulness (never blocks)
+python products/ai_membrane/test_hook.py              # 17/17
+python evidence/run_product_e2e.py                    # Warden loop: real hook -> audit -> report (M1)
+python evidence/run_mcp_e2e.py                        # one core, second harness: MCP broker parity (M2)
+python evidence/run_team_gate_e2e.py                  # team/CI gate: only a ratified, unbroadened .bio passes (M4)
+python evidence/run_falsification.py                  # self-falsification: proofs are real, not slop
+```
+
+The last one is a **self-falsification audit**: it mutates a constitution (the decision flips),
+sabotages `guard.check()` (a proof then fails), and has WebAssembly itself refuse an ungranted
+syscall — so the evidence is measuring real behaviour, not printing `PASS`.
+
+No hosted CI required — the proof is a command anyone can run.
+
+---
+
+## MetaSpace Warden — the agent membrane (Product B)
+
+**Warden** is the shipping product: a deny-by-default membrane for a Claude Code session. You
+install it, it enforces a hardened default constitution from *outside* the agent, and it leaves
+a session safety report. The whole loop is a reproducible proof
+(`python evidence/run_product_e2e.py`), driving the *real* hook over a realistic session:
+
+```
+install the membrane  ->  the agent acts (writes, shell, fetches)
+                      ->  the hook enforces the shipped constitution (deny-by-default)
+                      ->  it logs a project-local audit (.metaspace/session_audit.jsonl)
+                      ->  `metaspace report` summarizes what was blocked, by capability
+```
+
+In the proof, of a realistic 11-step session the membrane allows 6 legitimate actions and blocks
+5 (a write outside the project, `git push`, `rm -rf /`, a `curl … | bash`, and a beacon to an
+unlisted host) — then `metaspace report` shows the block breakdown (FILESYSTEM / SHELL / NETWORK).
+
+**As a Claude Code plugin (one command):**
+
+```
+/plugin marketplace add LemonScripter/metaspace-membrane
+/plugin install metaspace-membrane@metaspace
+```
+
+Restart the session and run `/hooks` to confirm the PreToolUse membrane is active. The plugin
+ships a hardened default constitution (project-only writes, host allowlist, dangerous-command
+block); `${CLAUDE_PROJECT_DIR}` is used as the project boundary automatically.
+
+**Or as a portable installer** (writes `.claude/settings.json` directly, with an editable
+constitution in `.claude/metaspace/`):
+
+```bash
+python products/ai_membrane/install.py /path/to/your/project
+```
+
+Restart the Claude Code session, then run `/hooks` to confirm it is active. Removing the hook
+block reverts either method.
+
+The session constitution is deny-by-default: writes are limited to the project directory,
+outbound network to an allowlist, and dangerous shell patterns are blocked. The membrane logs
+every decision to `.metaspace/session_audit.jsonl` in the project; after a session, see what it
+blocked with:
+
+```bash
+metaspace report          # reads ./.metaspace/session_audit.jsonl by default
+```
+
+### Other harnesses: the generic MCP broker
+
+The membrane's decision lives in one harness-independent core (`core/agent_adapter.py`); the
+Claude Code hook is just one thin adapter over it. A second adapter — a generic **MCP
+capability-broker** (`products/mcp_membrane/server.py`, a minimal JSON-RPC stdio server) —
+exposes *mediated effect tools* (`fs_write`, `fs_read`, `net_fetch`) to any MCP-capable agent,
+each gated by the same core, deny-by-default. `python evidence/run_mcp_e2e.py` drives both the
+hook and the broker over their real interfaces and shows they reach identical verdicts.
+
+**Honest condition (the hard-vs-advisory line):** an MCP tool the agent may *voluntarily* call
+is only advisory — back to self-discipline, which does not contain a misaligned agent. The
+broker is *hard* only when the agent is deployed with its ambient authority removed, so the
+broker's tools are its **only** path to the filesystem/network. Under that condition the
+guarantee equals the hook's; the broker cannot constrain effects reached through some other
+unmediated tool.
+
+### Team / CI: gate the constitution at merge time
+
+Commit a **ratified** `metaspace.bio` to your repo, and make "the effect boundary here is
+human-ratified and hasn't been silently broadened" a build-breaking check — the same
+content-bound ratification as the runtime gate, now enforced in CI and pre-commit:
+
+```yaml
+# .github/workflows/metaspace-gate.yml  (ships in this repo as a template)
+- run: pip install "metaspace-membrane @ git+https://github.com/LemonScripter/metaspace-membrane"
+- run: metaspace gate metaspace.bio      # exit 0 only if RATIFIED and unbroadened
+```
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: https://github.com/LemonScripter/metaspace-membrane
+    rev: main
+    hooks: [{ id: metaspace-gate }]
+```
+
+An unratified constitution, or one widened after ratifying (→ TAMPERED), fails the build.
+`python evidence/run_team_gate_e2e.py` proves the whole flow with the real CLI. (Honest note:
+there is no hosted-CI badge — GitHub Actions is disabled on this repo — so the gate logic is
+proven locally and cross-OS instead, on Windows and real Linux.)
+
+---
+
+## The `.bio` constitution
+
+One file, three lenses:
+
+```bio
+CAPABILITIES {
+  FILESYSTEM write "out/**"
+  NETWORK    out   "api.allowed.com"
+}
+
+KNOWLEDGE {
+  ENTITY order FROM "kb/orders.json"
+  FIELD  order.status IN pending, shipped, delivered, refunded
+  ACTUATE refund PROVENANCE verified_db
+  CITATION REQUIRED
+  SOURCE verified_db
+}
+```
+
+- **Capability** — mediates effects on the world (deny-by-default).
+- **Value invariant** — guards safety bounds.
+- **Knowledge** — grounded facts only: no invented entities, no ungrounded actuation.
+
+---
+
+## Synthesize a constitution from code
+
+Point the synthesizer at a file or directory; it detects the code's real effects
+(filesystem, network, env, subprocess, hardware, import-path) and drafts a `.bio` — marked
+`SYNTHESIZED`, since a human ratifies before it is trusted:
+
+```bash
+python synthesize.py path/to/app --out app.constitution.bio
+```
+
+`evidence/demos/run_synth_demo.py` runs the loop end-to-end: it synthesizes a constitution
+from a sample app, feeds it straight into the membrane, and shows the app can then only do
+what it declared — an effect it never had (a subprocess) is denied by default. This is a
+static heuristic; the runtime membrane, not the synthesis, is the guarantee.
+
+Ratify a reviewed constitution (SYNTHESIZED 🟡 → RATIFIED 🟢):
+
+```bash
+python ratify.py app.constitution.bio --yes
+```
+
+Ratification is **content-bound**: the stamp carries a fingerprint of the enforced policy, so
+a later edit that widens a scope or adds a capability is detected as TAMPERED 🔴 — you cannot
+ratify a policy and then quietly broaden it.
+
+In production, gate the membrane on ratification — `Guard(..., require_ratified=True)` (or
+`core.gate`) runs **only** a RATIFIED constitution; a SYNTHESIZED or TAMPERED one is refused,
+fail-closed. A policy is enforceable only after human ratification.
+
+Capabilities the dry-run learned are marked **provisional**: ratification is refused until each
+carries a written `JUSTIFY` reason — a per-item, read-gated justification that defeats
+rubber-stamping (`--yes` cannot bypass it). The code enforces the justification's *presence*,
+not its *truth*, so the human's judgement on the reason still matters.
+
+---
+
+## Layout
+
+```
+core/          shared decision engine (guard, knowledge, analyzer, agent_adapter)
+products/      app_membrane (WebAssembly + Landlock) · ai_membrane (hook + installer) · mcp_membrane (broker)
+evidence/      runnable proofs + decisions
+docs/          ARCHITECTURE.md
+```
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full technical background, or the
+technical whitepaper [`docs/MetaSpace_Membrane_Whitepaper_EN.pdf`](docs/MetaSpace_Membrane_Whitepaper_EN.pdf)
+(LaTeX source alongside; every claim is a reproducible run or true by construction).
+
+---
+
+## Honest limits
+
+- Product A's hard guarantee requires a real substrate: the WebAssembly capability model, or an
+  OS sandbox (**Landlock**, `products/app_membrane/sandbox_enforcer.py`) that confines a stock
+  native program's filesystem writes to its `.bio` from the kernel. A language-level guard is
+  bypassable and is not shipped as a product. The Landlock MVP confines *writes* (read/execute
+  unrestricted so any binary runs); it is Linux-only and fail-closed if unavailable.
+- The code→constitution synthesis is a static heuristic; a **dry-run learning mode**
+  (`core/dryrun.py`) observes concrete runtime effects and augments the constitution *before*
+  ratification, so it does not false-positive-block legitimate dynamic behaviour.
+- The agent membrane affects tool effects, not the model's prose; its shell check is a
+  **structural allowlist** (`core/shell_policy.py`) — obfuscation-resistant and fail-closed.
+- The epistemic tier has two parts, named honestly: a **hard tier** that is a real
+  deterministic *membrane* (it contains/blocks), and a **soft tier** that is *not* a membrane but
+  an **advisory flag** (it qualifies/flags, never blocks). The reproducible threat-model matrix
+  (`evidence/demos/run_threat_matrix_demo.py`, rendered in `docs/ARCHITECTURE.md`) shows exactly
+  what each layer catches — including where a schema-valid but fabricated statement passes the
+  hard layers and is only flagged.
+
+---
+
+© Szőke László-Ferenc — MetaSpace.Bio Engine Project. Patent pending. Licensed under the
+**Business Source License 1.1** — see [LICENSE](LICENSE). Source-available: free to use, copy,
+modify and redistribute for **any non-competing purpose** (internal use, research, education, and
+products that merely depend on it); each version converts to **Apache-2.0** four years after its
+release. The only reserved use is offering a competing commercial safety-membrane product/service.
+For commercial or competing-use licensing: admin@metaspace.bio.
+
+<sub>Designed and authored by Szőke László-Ferenc, with AI pair-programming assistance (Claude).</sub>