stigmem-plugin-source-attestation 0.1.0__py3-none-any.whl

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/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/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/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,
+    )

stigmem_plugin_source_attestation-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+stigmem_plugin_source_attestation/__init__.py,sha256=YBQ6ZoUBCzantFo-SdzDz0kj-4h_ARC26Y2PPojmdhI,275
+stigmem_plugin_source_attestation/config.py,sha256=Uk8LyNig3hMDdDd1S20zZE6AtrCitEkAh_CddNVW7ig,1743
+stigmem_plugin_source_attestation/handlers.py,sha256=DodZgnBoMpyeKTwlM4uHnpOgJ7lPEnANHpjAML8oMYM,5283
+stigmem_plugin_source_attestation/manifest.py,sha256=Ean8DS_9_9gXjfCCOsSGSrfiM2ifJLmmSlUw9NTilR4,1300
+stigmem_plugin_source_attestation-0.1.0.dist-info/METADATA,sha256=M3y-fOgetcnomA88m9EsTxWJrEDyBxnrnjcB-h0OdRE,3923
+stigmem_plugin_source_attestation-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+stigmem_plugin_source_attestation-0.1.0.dist-info/entry_points.txt,sha256=OUSYxVhSNsIbv3UNoWu9FVmhJEmhZYx6N-Zkefq25V0,89
+stigmem_plugin_source_attestation-0.1.0.dist-info/RECORD,,

stigmem_plugin_source_attestation-0.1.0.dist-info/WHEEL

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

stigmem_plugin_source_attestation-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[stigmem.plugins]
+source-attestation = stigmem_plugin_source_attestation:plugin_manifest