stigmem-plugin-source-attestation 0.1.0__tar.gz

stigmem_plugin_source_attestation-0.1.0/.gitignore

@@ -0,0 +1,70 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+.venv/
+venv/
+.uv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+coverage/
+
+# Node / pnpm
+node_modules/
+.next/
+.turbo/
+.jscpd/
+.pnpm-store/
+dist/
+*.tsbuildinfo
+apps/dashboard/coverage/
+adapters/mcp/coverage/
+sdks/stigmem-ts/coverage/
+
+# Environment
+.env
+.env.local
+.env.*.local
+
+# Release signing keys — public keys are attached to GitHub Releases only;
+# private keys must NEVER be committed (use offline storage).
+stigmem-release-signing-key.asc
+stigmem-release-signing-key*.asc
+*private*signing*key*.asc
+*secret*signing*key*.asc
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local Codex project instructions
+AGENTS.md
+
+# Docker
+*.log
+
+# Stigmem runtime (DB and logs are runtime state, not source)
+data/*.db
+data/*.db-shm
+data/*.db-wal
+stigmem.db
+stigmem.db-shm
+stigmem.db-wal
+logs/
+# Eval results (CI-generated artifacts)
+eval/results/

stigmem_plugin_source_attestation-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: stigmem-plugin-source-attestation
+Version: 0.1.0
+Summary: Experimental source-attestation plugin for Stigmem.
+Project-URL: Homepage, https://github.com/eidetic-labs/stigmem
+Project-URL: Documentation, https://github.com/eidetic-labs/stigmem/tree/main/features/source-attestation
+Project-URL: Repository, https://github.com/eidetic-labs/stigmem
+Project-URL: Issues, https://github.com/eidetic-labs/stigmem/issues
+Author-email: Eidetic Labs <oss@eidetic-labs.ai>
+License: Apache-2.0
+Keywords: federation,plugins,provenance,source-attestation,stigmem
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: stigmem-node<1.0.0,>=0.9.0a8
+Description-Content-Type: text/markdown
+
+# Stigmem Source Attestation Plugin
+
+Experimental source attestation plugin for Stigmem.
+
+This package provides the `stigmem-plugin-source-attestation` source package
+for alpha validation. It registers through the `stigmem.plugins` entry point
+group and is loaded by `stigmem-node` only when explicitly installed and
+configured by an operator.
+
+## Status
+
+Source attestation remains experimental. Installing this package does not add
+assertion-source enforcement, recall source weighting, or federation source
+guards to the supported default surface. Default installs remain inert unless
+the plugin is registered and the operator enables the relevant gates.
+
+The package metadata is publication-shaped for the plugin readiness track, but
+registry publication remains on hold until dry-run evidence and maintainer
+clearance are recorded. See the feature record under
+`features/source-attestation/` for the current status, evidence, and security
+notes.
+
+## Installation
+
+```bash
+pip install --pre stigmem-node==0.9.0a8 stigmem-plugin-source-attestation==0.1.0
+```
+
+## Enable
+
+Set the plugin gate environment variable to opt in:
+
+```bash
+export STIGMEM_SOURCE_ATTESTATION_ENABLED=1
+```
+
+The default install is inert; source attestation only activates when the
+package is installed, discovered through the `stigmem.plugins` entry point, and
+the operator enables the gate. Enforcement-specific gates such as
+`STIGMEM_SOURCE_ATTESTATION_ENFORCE_ASSERT_VALIDATION` and
+`STIGMEM_SOURCE_ATTESTATION_ENFORCE_FEDERATION_INBOUND` remain opt-in and must
+not be enabled with warn-only mode.
+
+## Disable
+
+Unset the plugin gate environment variable, or set it to any value other than
+`1`, `true`, `yes`, or `on`:
+
+```bash
+unset STIGMEM_SOURCE_ATTESTATION_ENABLED
+```
+
+The plugin returns to inert state at the next process start. No data migration
+is required; core source, scope, tenant, and audit enforcement continues to hold
+without plugin participation.
+
+## Test
+
+From a Stigmem repository checkout with development dependencies installed:
+
+```bash
+uv run pytest node/tests/plugins/test_source_attestation_plugin_scaffold.py \
+  node/tests/plugins/test_source_attestation_plugin_validation.py
+```
+
+The package itself ships no separate test tree; upstream plugin validation
+lives in `node/tests/plugins/`.
+
+## Uninstall
+
+```bash
+pip uninstall stigmem-plugin-source-attestation
+```
+
+Removing the package is sufficient. The gate environment variable becomes moot
+once the entry point is no longer discoverable.
+
+## Project Links
+
+- Repository: <https://github.com/eidetic-labs/stigmem>
+- Feature record: <https://github.com/eidetic-labs/stigmem/tree/main/features/source-attestation>
+- Plugin source: <https://github.com/eidetic-labs/stigmem/tree/main/experimental/source-attestation>
+- Issue tracker: <https://github.com/eidetic-labs/stigmem/issues>

stigmem_plugin_source_attestation-0.1.0/README.md

@@ -0,0 +1,83 @@
+# Stigmem Source Attestation Plugin
+
+Experimental source attestation plugin for Stigmem.
+
+This package provides the `stigmem-plugin-source-attestation` source package
+for alpha validation. It registers through the `stigmem.plugins` entry point
+group and is loaded by `stigmem-node` only when explicitly installed and
+configured by an operator.
+
+## Status
+
+Source attestation remains experimental. Installing this package does not add
+assertion-source enforcement, recall source weighting, or federation source
+guards to the supported default surface. Default installs remain inert unless
+the plugin is registered and the operator enables the relevant gates.
+
+The package metadata is publication-shaped for the plugin readiness track, but
+registry publication remains on hold until dry-run evidence and maintainer
+clearance are recorded. See the feature record under
+`features/source-attestation/` for the current status, evidence, and security
+notes.
+
+## Installation
+
+```bash
+pip install --pre stigmem-node==0.9.0a8 stigmem-plugin-source-attestation==0.1.0
+```
+
+## Enable
+
+Set the plugin gate environment variable to opt in:
+
+```bash
+export STIGMEM_SOURCE_ATTESTATION_ENABLED=1
+```
+
+The default install is inert; source attestation only activates when the
+package is installed, discovered through the `stigmem.plugins` entry point, and
+the operator enables the gate. Enforcement-specific gates such as
+`STIGMEM_SOURCE_ATTESTATION_ENFORCE_ASSERT_VALIDATION` and
+`STIGMEM_SOURCE_ATTESTATION_ENFORCE_FEDERATION_INBOUND` remain opt-in and must
+not be enabled with warn-only mode.
+
+## Disable
+
+Unset the plugin gate environment variable, or set it to any value other than
+`1`, `true`, `yes`, or `on`:
+
+```bash
+unset STIGMEM_SOURCE_ATTESTATION_ENABLED
+```
+
+The plugin returns to inert state at the next process start. No data migration
+is required; core source, scope, tenant, and audit enforcement continues to hold
+without plugin participation.
+
+## Test
+
+From a Stigmem repository checkout with development dependencies installed:
+
+```bash
+uv run pytest node/tests/plugins/test_source_attestation_plugin_scaffold.py \
+  node/tests/plugins/test_source_attestation_plugin_validation.py
+```
+
+The package itself ships no separate test tree; upstream plugin validation
+lives in `node/tests/plugins/`.
+
+## Uninstall
+
+```bash
+pip uninstall stigmem-plugin-source-attestation
+```
+
+Removing the package is sufficient. The gate environment variable becomes moot
+once the entry point is no longer discoverable.
+
+## Project Links
+
+- Repository: <https://github.com/eidetic-labs/stigmem>
+- Feature record: <https://github.com/eidetic-labs/stigmem/tree/main/features/source-attestation>
+- Plugin source: <https://github.com/eidetic-labs/stigmem/tree/main/experimental/source-attestation>
+- Issue tracker: <https://github.com/eidetic-labs/stigmem/issues>

stigmem_plugin_source_attestation-0.1.0/STATUS.md

@@ -0,0 +1,18 @@
+# Spec-X6-Source-Attestation Status
+
+This file is a compatibility pointer for existing
+`experimental/source-attestation/` links.
+
+The canonical ADR-020 status record now lives at
+[`features/source-attestation/status.md`](../../features/source-attestation/status.md).
+
+Current summary:
+
+- Status: `active`
+- Stability: `experimental`
+- Default surface: `opt-in`
+- Implementation path: `experimental/source-attestation/`
+- Package: `stigmem-plugin-source-attestation`
+
+The implementation package remains here during transition. Product status,
+gates, history, and release-facing facts belong in the feature record.

stigmem_plugin_source_attestation-0.1.0/concept.md

@@ -0,0 +1,22 @@
+---
+title: Source Attestation
+sidebar_label: Source Attestation
+audience: Integrator
+---
+
+# Source Attestation
+
+**Audience:** Node operators enforcing provenance guarantees on fact assertions.
+
+:::info Coming soon
+This guide covers Source Attestation , a the pre-reset spec addition. Spec draft is in progress.
+:::
+
+Source attestation binds a fact's `source` field to the caller's registered `entity_uri`. The node verifies that the asserted `source` matches the API key's registered identity.
+
+Three modes:
+- `enforce` — reject mismatched source claims with HTTP 403
+- `warn` — accept and log; sets `attested: false` on the fact
+- `off` — no verification (default in the pre-reset spec)
+
+When shipped, this guide will cover configuration, key registration, and audit log integration.

stigmem_plugin_source_attestation-0.1.0/pyproject.toml

@@ -0,0 +1,53 @@
+[project]
+name = "stigmem-plugin-source-attestation"
+version = "0.1.0"
+description = "Experimental source-attestation plugin for Stigmem."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [
+  { name = "Eidetic Labs", email = "oss@eidetic-labs.ai" },
+]
+keywords = ["stigmem", "plugins", "source-attestation", "provenance", "federation"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pydantic>=2,<3",
+    "stigmem-node>=0.9.0a8,<1.0.0",
+]
+
+[project.entry-points."stigmem.plugins"]
+source-attestation = "stigmem_plugin_source_attestation:plugin_manifest"
+
+[project.urls]
+Homepage = "https://github.com/eidetic-labs/stigmem"
+Documentation = "https://github.com/eidetic-labs/stigmem/tree/main/features/source-attestation"
+Repository = "https://github.com/eidetic-labs/stigmem"
+Issues = "https://github.com/eidetic-labs/stigmem/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/stigmem_plugin_source_attestation"]
+
+[tool.hatch.build.targets.wheel.sources]
+"src" = ""
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "README.md",
+  "STATUS.md",
+  "security.md",
+  "spec.md",
+  "concept.md",
+  "src/stigmem_plugin_source_attestation/**/*.py",
+]

stigmem_plugin_source_attestation-0.1.0/security.md

@@ -0,0 +1,23 @@
+---
+feature: source-attestation
+spec_id: Spec-X6-Source-Attestation
+status: Experimental
+applies_to: stigmem v0.9.0a1
+last_updated: 2026-05-21
+owned_risks: []
+contributed_risks:
+  - R-22
+---
+
+# Source Attestation Security
+
+This file is a compatibility pointer for existing
+`experimental/source-attestation/security.md` links.
+
+The canonical ADR-020 feature security record now lives at
+[`features/source-attestation/security.md`](../../features/source-attestation/security.md).
+
+This compatibility file remains registered for the security-documentation
+validator while legacy links migrate. Source attestation contributes to R-22
+release supply-chain integrity; the canonical analysis is now in the feature
+record.

stigmem_plugin_source_attestation-0.1.0/spec.md

@@ -0,0 +1,30 @@
+---
+spec_id: Spec-X6-Source-Attestation
+version: 0.1.0-alpha.0
+status: Experimental
+applies_to: future experimental plugin line
+last_updated: 2026-05-21
+supersedes: pre-reset section 18 source-attestation material
+depends_on:
+  - Spec-01-Fact-Model >= 0.1.0-alpha.0
+  - Spec-09-Audit-Log >= 0.1.0-alpha.0
+title: Spec-X6-Source-Attestation
+sidebar_label: Source Attestation
+audience: Spec
+description: "Compatibility pointer for source-attestation semantics."
+stability: experimental
+since: 0.9.0a1
+---
+
+# Spec-X6-Source-Attestation
+
+This file is a compatibility pointer for existing
+`experimental/source-attestation/` links.
+
+The canonical ADR-020 feature record now lives at
+[`features/source-attestation/`](../../features/source-attestation/). The
+canonical normative spec is
+[`features/source-attestation/spec.md`](../../features/source-attestation/spec.md).
+
+The implementation package remains in `experimental/source-attestation/` during
+the transition.

stigmem_plugin_source_attestation-0.1.0/src/stigmem_plugin_source_attestation/__init__.py

@@ -0,0 +1,12 @@
+"""Experimental source-attestation plugin scaffold."""
+
+from __future__ import annotations
+
+from .config import SourceAttestationConfig
+from .manifest import PLUGIN_NAME, plugin_manifest
+
+__all__ = [
+    "PLUGIN_NAME",
+    "SourceAttestationConfig",
+    "plugin_manifest",
+]

stigmem_plugin_source_attestation-0.1.0/src/stigmem_plugin_source_attestation/config.py

@@ -0,0 +1,48 @@
+"""Configuration schema for the source-attestation plugin."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+
+from pydantic import BaseModel, model_validator
+
+
+class SourceAttestationConfig(BaseModel):
+    """Operator-controlled gates for experimental source attestation."""
+
+    enabled: bool = False
+    enforce_assert_validation: bool = False
+    apply_recall_rank: bool = False
+    enforce_federation_inbound: bool = False
+    warn_only: bool = True
+
+    @model_validator(mode="after")
+    def _validate_warn_only_boundary(self) -> SourceAttestationConfig:
+        enforcing = self.enforce_assert_validation or self.enforce_federation_inbound
+        if enforcing and self.warn_only:
+            raise ValueError("warn_only must be false when enforcement gates are enabled")
+        return self
+
+
+def load_config_from_env(
+    environ: Mapping[str, str] | None = None,
+) -> SourceAttestationConfig:
+    """Load source-attestation plugin gates from environment variables."""
+
+    env = environ if environ is not None else os.environ
+    prefix = "STIGMEM_SOURCE_ATTESTATION_"
+    return SourceAttestationConfig(
+        enabled=_env_bool(env, f"{prefix}ENABLED"),
+        enforce_assert_validation=_env_bool(env, f"{prefix}ENFORCE_ASSERT_VALIDATION"),
+        apply_recall_rank=_env_bool(env, f"{prefix}APPLY_RECALL_RANK"),
+        enforce_federation_inbound=_env_bool(env, f"{prefix}ENFORCE_FEDERATION_INBOUND"),
+        warn_only=_env_bool(env, f"{prefix}WARN_ONLY", default=True),
+    )
+
+
+def _env_bool(env: Mapping[str, str], name: str, *, default: bool = False) -> bool:
+    raw = env.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}

stigmem_plugin_source_attestation-0.1.0/src/stigmem_plugin_source_attestation/handlers.py

@@ -0,0 +1,147 @@
+"""Hook handlers for the source-attestation plugin."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ValidationError
+from stigmem_node.entity_normalizer import NormalizationError, normalize_entity_uri
+from stigmem_node.plugins import Allow, Deny, PluginContext, PluginHealth, PluginHealthStatus
+
+from .config import load_config_from_env
+
+
+def config_validate(_ctx: PluginContext, **_: Any) -> Allow | Deny:
+    """Validate operator gates before the plugin is registered."""
+
+    try:
+        load_config_from_env()
+    except ValidationError as exc:
+        return Deny(f"invalid source-attestation plugin config: {exc}")
+    return Allow()
+
+
+def pre_assert_validate(_ctx: PluginContext, **kwargs: Any) -> Allow | Deny:
+    """Gate source/identity binding behind explicit plugin configuration.
+
+    Returns Allow() when the plugin is disabled or assertion enforcement is not
+    enabled. When both gates are enabled, the handler rejects declared source
+    values that do not match the authenticated principal or its delegated
+    source-entity list.
+    """
+
+    config = load_config_from_env()
+    if not (config.enabled and config.enforce_assert_validation):
+        return Allow()
+
+    req = kwargs.get("req")
+    identity = kwargs.get("identity")
+    source = _normalized_or_none(getattr(req, "source", None))
+    authorized_sources = _authorized_source_entities(identity)
+    if source is not None and source in authorized_sources:
+        return Allow()
+
+    return Deny(
+        "source_attestation_failed: declared source does not match authenticated principal"
+    )
+
+
+def recall_rank(_ctx: PluginContext, scored_results: list[Any], **kwargs: Any) -> dict[str, float]:
+    """Contribute source-trust score deltas only when explicitly enabled.
+
+    Returns an empty delta map when the plugin is disabled, recall ranking is
+    not enabled, or the active recall weights set source_trust to zero. Only
+    enabled deployments add source-trust contribution to caller-owned scoring.
+    """
+
+    config = load_config_from_env()
+    if not (config.enabled and config.apply_recall_rank):
+        return {}
+
+    from stigmem_node.source_trust import compute_source_trust
+
+    identity = kwargs.get("identity")
+    weights = kwargs.get("weights")
+    source_weight = float(getattr(weights, "source_trust", 0.0))
+    if source_weight <= 0.0:
+        return {}
+
+    base_weight = (
+        float(getattr(weights, "lexical", 0.0))
+        + float(getattr(weights, "semantic", 0.0))
+        + float(getattr(weights, "graph", 0.0))
+        + source_weight
+        + float(getattr(weights, "recency", 0.0))
+    )
+    if base_weight <= 0.0:
+        base_weight = 1.0
+
+    deltas: dict[str, float] = {}
+    for scored in scored_results:
+        fact = getattr(scored, "fact", None)
+        fact_id = getattr(fact, "id", None)
+        source = getattr(fact, "source", None)
+        scope = getattr(fact, "scope", None)
+        confidence = float(getattr(fact, "confidence", 0.0))
+        if fact_id is None or source is None or scope is None:
+            continue
+        trust = compute_source_trust(source, scope, identity)
+        deltas[str(fact_id)] = (source_weight * trust / base_weight) * max(0.0, confidence)
+
+    return deltas
+
+
+def federation_inbound_validate(_ctx: PluginContext, **kwargs: Any) -> Allow | Deny:
+    """Gate inbound source-attestation policy behind explicit plugin configuration.
+
+    Returns Allow() when the plugin is disabled or federation-inbound
+    enforcement is not enabled. When both gates are enabled, the handler
+    rejects federated facts whose normalized source does not match the peer
+    node identifier or capability-token subject.
+    """
+
+    config = load_config_from_env()
+    if not (config.enabled and config.enforce_federation_inbound):
+        return Allow()
+
+    fact = kwargs.get("fact") or {}
+    fact_source = _normalized_or_none(fact.get("source")) if isinstance(fact, dict) else None
+    peer = kwargs.get("peer") or {}
+    cap_token = kwargs.get("cap_token") or {}
+    expected_source = None
+    if isinstance(peer, dict):
+        expected_source = peer.get("node_id")
+    if expected_source is None and isinstance(cap_token, dict):
+        expected_source = cap_token.get("subject")
+    if fact_source is not None and fact_source == _normalized_or_none(expected_source):
+        return Allow()
+
+    return Deny("source_attestation_failed: federated fact source does not match sender")
+
+
+def health_check(_ctx: PluginContext) -> PluginHealth:
+    """Report scaffold health for registry lifecycle tests."""
+
+    return PluginHealth(
+        status=PluginHealthStatus.HEALTHY,
+        message="source attestation plugin scaffold registered",
+    )
+
+
+def _authorized_source_entities(identity: Any) -> set[str]:
+    source_entities = {getattr(identity, "entity_uri", None)}
+    source_entities.update(getattr(identity, "allowed_source_entities", ()) or ())
+    return {
+        normalized
+        for raw in source_entities
+        if (normalized := _normalized_or_none(raw)) is not None
+    }
+
+
+def _normalized_or_none(raw: Any) -> str | None:
+    if not isinstance(raw, str):
+        return None
+    try:
+        return normalize_entity_uri(raw)
+    except NormalizationError:
+        return None

stigmem_plugin_source_attestation-0.1.0/src/stigmem_plugin_source_attestation/manifest.py

@@ -0,0 +1,43 @@
+"""Plugin manifest factory for source attestation."""
+
+from __future__ import annotations
+
+from stigmem_node.plugins import PluginManifest
+
+from . import handlers
+from .config import SourceAttestationConfig
+
+PLUGIN_NAME = "stigmem-plugin-source-attestation"
+PLUGIN_VERSION = "0.1.0"
+REQUIRES_STIGMEM = ">=0.9.0a3"
+
+
+def plugin_manifest() -> PluginManifest:
+    """Return the entry-point manifest consumed by ``stigmem.plugins`` discovery."""
+
+    return PluginManifest(
+        name=PLUGIN_NAME,
+        version=PLUGIN_VERSION,
+        requires_stigmem=REQUIRES_STIGMEM,
+        capabilities=frozenset(
+            {
+                "facts.read",
+                "facts.write",
+                "recall.read",
+                "federation.read",
+                "federation.write",
+                "identity.read",
+                "audit.emit",
+                "config.read",
+            }
+        ),
+        hooks={
+            "config_validate": handlers.config_validate,
+            "pre_assert_validate": handlers.pre_assert_validate,
+            "recall_rank": handlers.recall_rank,
+            "federation_inbound_validate": handlers.federation_inbound_validate,
+        },
+        config_schema=SourceAttestationConfig,
+        health_check=handlers.health_check,
+        async_safe=True,
+    )