policy-as-code-engine 0.2.0__tar.gz → 0.2.1__tar.gz

{policy_as_code_engine-0.2.0 → policy_as_code_engine-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: policy-as-code-engine
-Version: 0.2.0
+Version: 0.2.1
 Summary: Declarative policy evaluator with Decision Card field conversion and optional best-effort audit events.
 Project-URL: Homepage, https://github.com/mizcausevic-dev/policy-as-code-engine
 Project-URL: Repository, https://github.com/mizcausevic-dev/policy-as-code-engine
@@ -232,7 +232,15 @@ Evaluate converted cards with `PolicyEvaluator.evaluate(bundle, context)` or the
 
 The API is a local/reference integration. Bearer roles, buyer-key checks, vendor/action binding, condition assertions, and request bounds protect its basic boundary, but it has no durable bundle/condition store, revocation feed, key-rotation workflow, tenant isolation, or built-in rate limiting. `decision.scope` remains free text and is **not** parsed into the action mapping. The evaluating service must derive `action` and `resource.vendor_id` from its own authenticated request, select the right bundle, and combine the result with its own subject/resource authorization. A card approval alone is not permission to run every operation. A buyer withdrawal after registration is not discovered automatically; operators must stop using the bundle and update the source of truth. Do not treat this reference API as standalone production authorization until those controls are designed and tested for the deployment.
 
-When `AUDIT_STREAM_URL` is configured, registration, condition assertion, and allow/deny events are posted synchronously and best effort. Free-text reasons, condition descriptions, and bundle sources are excluded from these outbound events; IDs may still be sensitive in some deployments. Failed delivery is not retried or durably queued and can add up to the configured timeout to a request. Use a trusted local audit path and a separate persistence design when audit completeness matters.
+When `AUDIT_STREAM_URL` is configured with the private sink base URL or exact `/events` endpoint, also set `AUDIT_STREAM_TOKEN` to the sink's separate bearer credential (at least 32 visible ASCII characters) from a secret store. The URL requires HTTPS except for numeric loopback HTTP addresses. Registration, condition assertion, and allow/deny events are posted synchronously and best effort. Invalid configuration prevents outbound delivery and logs a failure; HTTP errors are logged without the URL or token. Free-text reasons, condition descriptions, and bundle sources are excluded from these outbound events; IDs may still be sensitive in some deployments. Failed delivery is not retried or durably queued and can add up to the configured timeout to a request. Use a trusted local audit path and a separate persistence design when audit completeness matters.
+
+### Opt-in synthetic pilot
+
+The v0.2.1 source tree packages a separate `policy_as_code_engine.pilot_app:app` for **local synthetic drills**. It uses tenant-scoped, short-lived Ed25519 assertions; a local SQLite file for buyer-key/card/condition state and committed minimal receipts; per-evaluation card/key revocation checks; and a deny-all default. It has no generic bundle or one-shot evaluation route. The main reference API above does not invoke this pilot surface, and the published v0.2.0 package does not contain it. See [the synthetic pilot guide](docs/SYNTHETIC_PILOT.md) for configuration, tests, and limitations. A local SQLite file, fictional issuer, and loopback guard do not clear hosted customer-use gates.
+
+### v0.2.1 changes
+
+This version adds authenticated, redirect-safe, best-effort audit delivery and packages the opt-in synthetic pilot module. If you already set `AUDIT_STREAM_URL`, configure the sink to require a separate bearer credential and set `AUDIT_STREAM_TOKEN` before upgrading. Without a valid token, audit delivery fails and is logged, while policy evaluation continues because delivery is best effort. This version does not add hosted authorization, audit completeness, or a revocation feed to the reference API. A source version string alone does not establish PyPI availability; check the tagged workflow and published artifacts before making a release claim.
 
 ### Migrating from 0.1.1 to 0.2.0
 

{policy_as_code_engine-0.2.0 → policy_as_code_engine-0.2.1}/README.md

@@ -185,7 +185,15 @@ Evaluate converted cards with `PolicyEvaluator.evaluate(bundle, context)` or the
 
 The API is a local/reference integration. Bearer roles, buyer-key checks, vendor/action binding, condition assertions, and request bounds protect its basic boundary, but it has no durable bundle/condition store, revocation feed, key-rotation workflow, tenant isolation, or built-in rate limiting. `decision.scope` remains free text and is **not** parsed into the action mapping. The evaluating service must derive `action` and `resource.vendor_id` from its own authenticated request, select the right bundle, and combine the result with its own subject/resource authorization. A card approval alone is not permission to run every operation. A buyer withdrawal after registration is not discovered automatically; operators must stop using the bundle and update the source of truth. Do not treat this reference API as standalone production authorization until those controls are designed and tested for the deployment.
 
-When `AUDIT_STREAM_URL` is configured, registration, condition assertion, and allow/deny events are posted synchronously and best effort. Free-text reasons, condition descriptions, and bundle sources are excluded from these outbound events; IDs may still be sensitive in some deployments. Failed delivery is not retried or durably queued and can add up to the configured timeout to a request. Use a trusted local audit path and a separate persistence design when audit completeness matters.
+When `AUDIT_STREAM_URL` is configured with the private sink base URL or exact `/events` endpoint, also set `AUDIT_STREAM_TOKEN` to the sink's separate bearer credential (at least 32 visible ASCII characters) from a secret store. The URL requires HTTPS except for numeric loopback HTTP addresses. Registration, condition assertion, and allow/deny events are posted synchronously and best effort. Invalid configuration prevents outbound delivery and logs a failure; HTTP errors are logged without the URL or token. Free-text reasons, condition descriptions, and bundle sources are excluded from these outbound events; IDs may still be sensitive in some deployments. Failed delivery is not retried or durably queued and can add up to the configured timeout to a request. Use a trusted local audit path and a separate persistence design when audit completeness matters.
+
+### Opt-in synthetic pilot
+
+The v0.2.1 source tree packages a separate `policy_as_code_engine.pilot_app:app` for **local synthetic drills**. It uses tenant-scoped, short-lived Ed25519 assertions; a local SQLite file for buyer-key/card/condition state and committed minimal receipts; per-evaluation card/key revocation checks; and a deny-all default. It has no generic bundle or one-shot evaluation route. The main reference API above does not invoke this pilot surface, and the published v0.2.0 package does not contain it. See [the synthetic pilot guide](docs/SYNTHETIC_PILOT.md) for configuration, tests, and limitations. A local SQLite file, fictional issuer, and loopback guard do not clear hosted customer-use gates.
+
+### v0.2.1 changes
+
+This version adds authenticated, redirect-safe, best-effort audit delivery and packages the opt-in synthetic pilot module. If you already set `AUDIT_STREAM_URL`, configure the sink to require a separate bearer credential and set `AUDIT_STREAM_TOKEN` before upgrading. Without a valid token, audit delivery fails and is logged, while policy evaluation continues because delivery is best effort. This version does not add hosted authorization, audit completeness, or a revocation feed to the reference API. A source version string alone does not establish PyPI availability; check the tagged workflow and published artifacts before making a release claim.
 
 ### Migrating from 0.1.1 to 0.2.0
 

policy_as_code_engine-0.2.1/docs/SYNTHETIC_PILOT.md

@@ -0,0 +1,115 @@
+# Local synthetic policy pilot
+
+The v0.2.1 source tree packages `policy_as_code_engine.pilot_app:app`
+as a separate, opt-in FastAPI surface. The published v0.2.0 package does not
+contain it, and the main reference HTTP API does not invoke it. **Use fictional
+buyers, vendors, cards, and assertions only.**
+The pilot is not a customer authorization service or a hosted deployment.
+
+## What it proves locally
+
+- A short-lived Ed25519 assertion must name the configured issuer and audience,
+  tenant, subject, and `admin` or `evaluate` role. Evaluation assertions must
+  also name the exact `use` action and vendor. The service builds the policy
+  context from that signed assertion, not from an evaluation request body.
+- Buyer public keys are pinned to a tenant, buyer ID, key ID, and URL by a
+  pilot administrator. A positive v0.1 Decision Card needs its exact v2
+  attestation and a currently active key. The URL selects the enrolled key;
+  it does not prove the buyer's organizational authority.
+- SQLite holds keys, derived bundles, condition assertions, and minimal audit
+  receipts on one local disk. Each state mutation and its receipt commit in one
+  transaction. Evaluation inserts a receipt before returning an `allow`.
+  Missing or unwritable state returns 503. A card or buyer-key revocation is
+  checked again on the next evaluation, including after process restart.
+- Positive results require **both** `POLICY_PILOT_ALLOW_SYNTHETIC=1` and
+  `POLICY_PILOT_DENY_ALL=0`. The default is deny-all. The app's own entry point
+  binds `127.0.0.1:8090`, and a non-loopback caller is rejected. Requests are
+  capped at 128 KiB, 32 JSON nesting levels, and five seconds; responses
+  request `Cache-Control: no-store`.
+
+## Configuration
+
+Install the repository with `pip install -e ".[dev]"`, then set these values
+in the local process environment. Keep private signing keys outside the repo.
+The service receives **public keys only**; an independent trusted caller mints
+the signed assertions. Do not use the fictional keys in `tests/` for any real
+identity or buyer enrollment.
+
+| Variable | Purpose |
+| --- | --- |
+| `POLICY_PILOT_DB_PATH` | Absolute path to a local SQLite file in an existing private directory. It is created on startup. Do not place it on Cloud Run's ephemeral filesystem for a hosted claim. |
+| `POLICY_PILOT_ISSUER` | Exact synthetic assertion issuer string. |
+| `POLICY_PILOT_AUDIENCE` | Exact audience of this pilot service. |
+| `POLICY_PILOT_ISSUER_PUBLIC_KEY_B64` | Base64 encoding of the issuer's 32-byte Ed25519 public key. |
+| `POLICY_PILOT_ALLOW_SYNTHETIC` | Must equal `1` before any `allow` is possible. |
+| `POLICY_PILOT_DENY_ALL` | Defaults to `1`; must equal `0` for a synthetic `allow`. Set to `1` first in a local rollback drill. |
+
+The compact bearer assertion has a fixed `{"alg":"EdDSA","typ":"JWT"}`
+header and claims `iss`, `aud`, `sub`, `tenant`, `role`, `iat`, `nbf`, and `exp`.
+The `evaluate` role also needs signed `action="use"` and `vendor_id`. Maximum
+lifetime is five minutes. The tenant is taken only from the verified assertion.
+The issuer key and the process environment are operator trust boundaries, not
+customer identity proof.
+
+Run the app locally with:
+
+```powershell
+$env:PYTHONPATH = 'C:\Users\chaus\OneDrive\Documents\ChatGPT\buyer-side governance Kinetic Gain\policy-as-code-engine\src'
+python -m policy_as_code_engine.pilot_app
+```
+
+The command requires the four mandatory variables above to use protected
+routes. `GET /healthz` is liveness. `GET /readyz` checks the configured issuer,
+database schema version, required tables and columns, and SQLite quick check;
+it is **not** evidence that a hosted gateway, buyer
+authority, egress policy, backup, or rollback exists.
+
+## API surface
+
+| Route | Role | Result |
+| --- | --- | --- |
+| `POST /v1/keys` | tenant admin | Enroll one synthetic buyer public key and receipt. |
+| `POST /v1/keys/{key_id}/revoke` | tenant admin | Revoke key; next evaluation of its cards denies. |
+| `POST /v1/cards` | tenant admin | Verify a signed positive v0.1 card, derive one scoped bundle, record hash and receipt. Duplicate tenant/bundle IDs are rejected. |
+| `POST /v1/bundles/{bundle_id}/revoke` | tenant admin | Revoke the card bundle. |
+| `PUT /v1/bundles/{bundle_id}/conditions/{condition_id}` | tenant admin | Record a condition assertion valid for at most seven days. |
+| `POST /v1/bundles/{bundle_id}/evaluate` | tenant evaluator | Derive action and vendor from the signed assertion; return `allow` or `deny` plus a committed receipt ID. Request bodies are rejected. |
+| `GET /v1/receipts` | tenant admin | Last 100 minimal receipts for that tenant only. |
+
+The pilot has no generic `/bundles`, one-shot `/evaluate`, raw card read,
+customer login, or remote fetch route. Its stored bundle descriptions can
+contain the synthetic card's vendor text, so the database remains synthetic.
+
+## Reproducible local drill
+
+```powershell
+Set-Location 'C:\Users\chaus\OneDrive\Documents\ChatGPT\buyer-side governance Kinetic Gain\policy-as-code-engine'
+$env:PYTHONPATH = (Resolve-Path 'src').Path
+python -m pytest -q tests/test_pilot_app.py
+```
+
+The tests generate temporary issuer and buyer keys and a temporary SQLite
+file. They exercise default deny, scoped allow, a deny-all rollback switch,
+wrong issuer audience, expired or tampered assertions, cross-tenant lookup,
+wrong vendor, role separation, signed-card tampering, condition state,
+old/new key overlap, key/card revocation across a restart, strict body limits,
+headerless evaluation bodies, missing schema tables, and a known-positive audit
+write failure. A 503 on the injected receipt write
+failure is the expected fail-closed outcome.
+
+## What remains blocked
+
+This SQLite file is not a shared multi-instance store; it has no backed-up
+restore, retention scheduler, migration playbook, or transactional delivery
+outbox to another audit sink. The pilot issuer is a configured synthetic key,
+not enrolled customer identity; it has no issuer rotation or replay prevention
+for write assertions. Key enrollment is an operator assertion and does not
+verify a buyer's real-world authority. The local loopback guard is not a
+hosted gateway, distributed rate limit, or network egress policy. No remote
+vendor fetching or customer traffic should be enabled from this pilot.
+
+For hosted use, see the separate workspace release plan and the live release
+gates. A real rollback needs an immutable deployed prior revision, a traffic
+switch, and a database backup or compatible forward repair demonstrated on
+the named deployment target. Setting a local deny-all flag is only a local
+control drill.

{policy_as_code_engine-0.2.0 → policy_as_code_engine-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "policy-as-code-engine"
-version = "0.2.0"
+version = "0.2.1"
 description = "Declarative policy evaluator with Decision Card field conversion and optional best-effort audit events."
 readme = "README.md"
 license = { text = "MIT" }
@@ -70,7 +70,7 @@ Issues        = "https://github.com/mizcausevic-dev/policy-as-code-engine/issues
 packages = ["src/policy_as_code_engine"]
 
 [tool.hatch.build.targets.sdist]
-only-include = ["src", "tests", "examples", "LICENSE", "README.md"]
+only-include = ["src", "tests", "examples", "docs", "LICENSE", "README.md"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{policy_as_code_engine-0.2.0 → policy_as_code_engine-0.2.1}/src/policy_as_code_engine/__init__.py

@@ -33,7 +33,7 @@ from .models import (
     Rule,
 )
 
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "Decision",

{policy_as_code_engine-0.2.0 → policy_as_code_engine-0.2.1}/src/policy_as_code_engine/audit_stream.py

@@ -1,8 +1,9 @@
 """
 Optional audit-stream-py integration.
 
-When the `AUDIT_STREAM_URL` env var is set, this module fires governance
-events at `{AUDIT_STREAM_URL}/events` for the moments the service produces.
+When `AUDIT_STREAM_URL` is set to the sink base URL (or its `/events`
+endpoint), this module fires governance events at the normalized endpoint.
+`AUDIT_STREAM_TOKEN` supplies the sink's bearer credential.
 Best-effort: a failed POST is logged, not raised — audit-stream outages
 must never block policy registration or evaluation.
 
@@ -15,15 +16,17 @@ Event kinds this service emits:
                                 is "deny"
     policy_condition_asserted   on a successful admin condition assertion
 
-Same opt-in pattern as procurement-decision-api.audit_stream and
-aeo-validator-service.audit_stream. Identical config envvars.
+The sink contract is aligned with procurement-decision-api.audit_stream.
 """
 
 from __future__ import annotations
 
+import ipaddress
 import math
 import os
+import re
 from typing import Any
+from urllib.parse import urlsplit, urlunsplit
 
 import httpx
 
@@ -43,6 +46,43 @@ def base_url() -> str | None:
     return raw.rstrip("/")
 
 
+def events_url() -> str | None:
+    """Normalize a sink base or exact `/events` URL without forwarding URL credentials."""
+    raw = base_url()
+    if raw is None:
+        return None
+    try:
+        parsed = urlsplit(raw)
+        hostname = parsed.hostname
+    except ValueError:
+        return None
+    if (
+        parsed.scheme not in {"http", "https"}
+        or not parsed.netloc
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+    ):
+        return None
+    if parsed.scheme == "http":
+        try:
+            if not ipaddress.ip_address(hostname or "").is_loopback:
+                return None
+        except ValueError:
+            return None
+    path = parsed.path.rstrip("/")
+    if not path.endswith("/events"):
+        path += "/events"
+    return urlunsplit((parsed.scheme, parsed.netloc, path, "", ""))
+
+
+def audit_token() -> str | None:
+    """Return only a token accepted by the sink's configured-token syntax."""
+    token = os.environ.get("AUDIT_STREAM_TOKEN", "")
+    return token if re.fullmatch(r"[!-~]{32,}", token) else None
+
+
 def timeout_s() -> float:
     """Configured per-call timeout. Defaults to 2.5s."""
     raw = os.environ.get("AUDIT_STREAM_TIMEOUT_S", "").strip()
@@ -62,8 +102,12 @@ async def emit(
     payload: dict[str, Any],
 ) -> None:
     """Fire one event. Silent no-op when AUDIT_STREAM_URL is unset."""
-    url = base_url()
-    if url is None:
+    if not is_enabled():
+        return
+    url = events_url()
+    token = audit_token()
+    if url is None or token is None:
+        print(f"audit-stream emit failed (kind={kind}): InvalidConfiguration", flush=True)
         return
 
     body = {
@@ -73,11 +117,18 @@ async def emit(
     }
     try:
         response = await client.post(
-            f"{url}/events",
+            url,
             json=body,
+            headers={"Authorization": f"Bearer {token}"},
+            follow_redirects=False,
             timeout=timeout_s(),
         )
         response.raise_for_status()
+    except httpx.HTTPStatusError as err:
+        print(
+            f"audit-stream emit failed (kind={kind}): HTTPStatusError status={err.response.status_code}",
+            flush=True,
+        )
     except (httpx.HTTPError, OSError) as err:
         print(
             f"audit-stream emit failed (kind={kind}): {type(err).__name__}",