langgraph-secure-agents 0.1.0__tar.gz

langgraph_secure_agents-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

langgraph_secure_agents-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,186 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality checks (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and development dependencies
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check .
+
+      - name: Check formatting
+        run: ruff format --check .
+
+      - name: Validate workflow YAML, action SHA pins, and release permissions
+        run: |
+          python - <<'PY'
+          import re
+          from pathlib import Path
+          import yaml
+
+          paths = (
+              Path(".github/workflows/ci.yml"),
+              Path(".github/workflows/release.yml"),
+              Path(".github/dependabot.yml"),
+          )
+          documents = {}
+          for path in paths:
+              with path.open(encoding="utf-8") as stream:
+                  document = yaml.safe_load(stream)
+              if not isinstance(document, dict):
+                  raise SystemExit(f"{path} must contain a YAML mapping")
+              documents[path.as_posix()] = document
+
+          sha_pattern = re.compile(r"^[0-9a-f]{40}$")
+          for path in paths[:2]:
+              for job_name, job in documents[path.as_posix()].get("jobs", {}).items():
+                  for step in job.get("steps", []):
+                      action = step.get("uses")
+                      if action and ("@" not in action or not sha_pattern.fullmatch(action.rsplit("@", 1)[1].split()[0])):
+                          raise SystemExit(f"{path}: {job_name} action is not pinned to a full SHA: {action}")
+
+          release = documents[".github/workflows/release.yml"]
+          jobs = release.get("jobs", {})
+          triggers = release.get("on", release.get(True, {}))
+          if triggers.get("push", {}).get("branches") != ["main"]:
+              raise SystemExit("automatic release workflow must run on pushes to main")
+          if jobs.get("release", {}).get("permissions", {}).get("contents") != "write":
+              raise SystemExit("versioning job must request contents: write")
+          if jobs.get("publish-pypi", {}).get("permissions", {}).get("id-token") != "write":
+              raise SystemExit("PyPI publishing job must request id-token: write")
+          if "contents" in jobs.get("publish-pypi", {}).get("permissions", {}):
+              raise SystemExit("PyPI publishing job must not request repository contents permissions")
+          if jobs.get("publish-pypi", {}).get("needs") != "release":
+              raise SystemExit("PyPI publishing must depend on the release job")
+          print("Workflow YAML, action SHA pins, and automatic-release permissions validated.")
+          PY
+
+      - name: Type check
+        run: mypy src
+
+      - name: Test
+        run: pytest --cov=langgraph_secure_agents --cov-report=term-missing --cov-fail-under=98
+
+  package-build:
+    name: Build and validate distributions
+    runs-on: ubuntu-latest
+    needs: quality
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+
+      - name: Build wheel and source distribution
+        run: python -m build
+
+      - name: Validate distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload validated distributions
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: package-dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 1
+
+  package-smoke:
+    name: Install and smoke-test distributions
+    runs-on: ubuntu-latest
+    needs: package-build
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+
+      - name: Download distributions built by the read-only job
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: package-dist
+          path: dist/
+
+      - name: Install wheel into a clean environment
+        run: |
+          python -m venv /tmp/langgraph-secure-agents-smoke
+          /tmp/langgraph-secure-agents-smoke/bin/python -m pip install --no-deps dist/*.whl
+
+      - name: Smoke-test the installed wheel
+        working-directory: /tmp
+        run: |
+          /tmp/langgraph-secure-agents-smoke/bin/python - <<'PY'
+          from langgraph_secure_agents import AccessRequest, Effect, PolicyEngine, PolicyRule, Principal
+
+          policy = PolicyEngine([
+              PolicyRule(
+                  rule_id="wheel-smoke-test",
+                  effect=Effect.ALLOW,
+                  actions=frozenset({"read"}),
+                  resources=frozenset({"reports"}),
+                  roles=frozenset({"analyst"}),
+              )
+          ])
+          decision = policy.evaluate(
+              AccessRequest(Principal("smoke-user", frozenset({"analyst"})), "read", "reports")
+          )
+          assert decision.allowed, decision
+          print("Installed wheel smoke test passed.")
+          PY
+
+      - name: Smoke-test optional LangChain agent extra
+        run: |
+          python -m venv /tmp/langgraph-secure-agents-extra
+          /tmp/langgraph-secure-agents-extra/bin/python -m pip install ".[langchain-agents]"
+          /tmp/langgraph-secure-agents-extra/bin/python - <<'PY'
+          from langgraph_secure_agents import PolicyEngine, Principal
+          from langgraph_secure_agents.middleware import create_authorization_middleware
+
+          middleware = create_authorization_middleware(
+              PolicyEngine(),
+              lambda context: Principal("smoke-user"),
+          )
+          assert callable(middleware.wrap_tool_call)
+          print("Optional middleware extra smoke test passed.")
+          PY

langgraph_secure_agents-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,168 @@
+name: Automatic Release
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: automatic-release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  quality:
+    name: Release quality gate (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    permissions:
+      contents: read
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install development dependencies
+        run: python -m pip install --upgrade pip && python -m pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Check formatting
+        run: ruff format --check .
+      - name: Type check
+        run: mypy src
+      - name: Test
+        run: pytest --cov=langgraph_secure_agents --cov-report=term-missing --cov-fail-under=98
+
+  package-smoke:
+    name: Build and smoke-test distributions
+    runs-on: ubuntu-latest
+    needs: quality
+    permissions:
+      contents: read
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Set up Python
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+      - name: Build and validate distributions
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Install wheel in a clean environment and smoke-test core API
+        run: |
+          python -m venv /tmp/langgraph-secure-agents-smoke
+          /tmp/langgraph-secure-agents-smoke/bin/python -m pip install --no-deps dist/*.whl
+          cd /tmp
+          /tmp/langgraph-secure-agents-smoke/bin/python - <<'PY'
+          from langgraph_secure_agents import AccessRequest, Effect, PolicyEngine, PolicyRule, Principal
+
+          policy = PolicyEngine([
+              PolicyRule(
+                  rule_id="release-smoke-test",
+                  effect=Effect.ALLOW,
+                  actions=frozenset({"read"}),
+                  resources=frozenset({"reports"}),
+                  roles=frozenset({"analyst"}),
+              )
+          ])
+          result = policy.evaluate(
+              AccessRequest(Principal("release-user", frozenset({"analyst"})), "read", "reports")
+          )
+          assert result.allowed, result
+          print("Installed wheel smoke test passed.")
+          PY
+      - name: Smoke-test optional LangChain middleware extra
+        run: |
+          python -m venv /tmp/langgraph-secure-agents-extra
+          /tmp/langgraph-secure-agents-extra/bin/python -m pip install ".[langchain-agents]"
+          /tmp/langgraph-secure-agents-extra/bin/python - <<'PY'
+          from langgraph_secure_agents import PolicyEngine, Principal
+          from langgraph_secure_agents.middleware import create_authorization_middleware
+
+          middleware = create_authorization_middleware(PolicyEngine(), lambda context: Principal("smoke-user"))
+          assert callable(middleware.wrap_tool_call)
+          print("Optional middleware extra smoke test passed.")
+          PY
+
+  release:
+    name: Version and prepare release
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    needs: [quality, package-smoke]
+    permissions:
+      contents: write
+    outputs:
+      released: ${{ steps.semantic.outputs.released }}
+      tag: ${{ steps.semantic.outputs.tag }}
+      version: ${{ steps.semantic.outputs.version }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+      - name: Create semantic version and GitHub Release
+        id: semantic
+        uses: python-semantic-release/python-semantic-release@b700dbeb1f431a0fcc30a79f3f0869407fe07278 # v10.7.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          git_committer_name: "github-actions"
+          git_committer_email: "actions@users.noreply.github.com"
+      - name: Set up Python for distribution build
+        if: steps.semantic.outputs.released == 'true'
+        uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
+        with:
+          python-version: "3.12"
+      - name: Build and validate distributions
+        if: steps.semantic.outputs.released == 'true'
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - name: Upload validated distributions
+        if: steps.semantic.outputs.released == 'true'
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: release-dist
+          path: dist/
+          if-no-files-found: error
+          retention-days: 1
+      - name: Attach distributions to GitHub Release
+        if: steps.semantic.outputs.released == 'true'
+        uses: softprops/action-gh-release@efb35369e0ad2afab669f228072c1b0d510eae64 # v3.0.3
+        with:
+          tag_name: ${{ steps.semantic.outputs.tag }}
+          fail_on_unmatched_files: true
+          files: dist/*
+
+  publish-pypi:
+    name: Publish to PyPI using Trusted Publishing
+    runs-on: ubuntu-latest
+    needs: release
+    if: needs.release.outputs.released == 'true'
+    environment:
+      name: pypi
+      url: https://pypi.org/project/langgraph-secure-agents/
+    permissions:
+      id-token: write
+    steps:
+      - name: Download validated distributions
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: release-dist
+          path: dist/
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/
+          print-hash: true

langgraph_secure_agents-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+.idea/
+.vscode/

langgraph_secure_agents-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+Notable user-facing changes are recorded here. This project follows PEP 440 versioning; pre-release versions may include API changes.
+
+## Unreleased
+
+- Prepare the first public alpha distribution.
+- Document deterministic policy evaluation, callable protection, optional LangChain/LangGraph middleware, and checkpoint-bound human-approval handling.
+- Explicitly document host-application responsibilities for identity, reviewer authentication, approval consumption, and downstream authorization.
+
+## 0.1.0a0
+
+Initial alpha scope:
+
+- Immutable authorization models and deterministic policy evaluation.
+- Default-deny and deny-overrides semantics with constrained wildcard selectors.
+- Synchronous and asynchronous Python callable protection.
+- Optional LangChain agent middleware for LangGraph tool execution.
+- Human-approval interrupts with request fingerprints bound to the execution scope and matched policy definitions.
+- Fail-closed behavior for configured audit/resolver errors and malformed approval responses.
+- Threat model, security reporting guidance, model-free example, CI, distribution smoke tests, and automated GitHub/PyPI release workflow.
+
+This alpha has not received an independent security audit and is not suitable as the sole security boundary for production or sensitive data.

langgraph_secure_agents-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peyman Salimi
+
+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.

langgraph_secure_agents-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: langgraph-secure-agents
+Version: 0.1.0
+Summary: Deterministic access control for LangGraph agents.
+Project-URL: Homepage, https://github.com/peymanpro/LangGraph-SecureAgents
+Project-URL: Repository, https://github.com/peymanpro/LangGraph-SecureAgents
+Project-URL: Issues, https://github.com/peymanpro/LangGraph-SecureAgents/issues
+Project-URL: Security, https://github.com/peymanpro/LangGraph-SecureAgents/blob/main/SECURITY.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: access-control,ai-agents,authorization,langgraph,security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: langchain<2.0,>=1.0; extra == 'dev'
+Requires-Dist: langgraph<2.0,>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.13; extra == 'dev'
+Requires-Dist: pytest-cov>=6.0; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: pyyaml>=6.0; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: langchain-agents
+Requires-Dist: langchain-core<2.0,>=1.0; extra == 'langchain-agents'
+Requires-Dist: langchain<2.0,>=1.0; extra == 'langchain-agents'
+Requires-Dist: langgraph<2.0,>=1.2; extra == 'langchain-agents'
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2.0,>=1.2; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# LangGraph-SecureAgents
+
+**Deterministic access control for LangGraph-powered agents.**
+
+LangGraph-SecureAgents is an experimental Python library for enforcing authorization at agent tool-execution boundaries. Agent orchestration may be handled by LangGraph; authorization decisions are made by trusted application code, never by an LLM.
+
+> **Status:** early development. The policy engine, guarded-callable primitive, and optional agent middleware are implemented, but the API is not stable and has not received an independent security audit. Do not use this project to protect production data yet.
+
+## Security principles
+
+Read the [threat model](docs/threat-model.md) for trust boundaries and deployment guidance, and [SECURITY.md](SECURITY.md) for vulnerability reporting and security limitations.
+
+1. **Default deny:** no matching allow policy means access is denied.
+2. **Deny overrides:** an explicit deny rule wins over any matching allow rule.
+3. **Deterministic authorization:** model output cannot grant permissions.
+4. **Enforce at execution:** evaluate policy immediately before a protected operation.
+5. **Trusted identity:** the application must resolve principal identity and roles from authenticated context, never from LLM-controlled tool arguments.
+6. **Fail closed:** resolver or configured audit failures prevent protected execution.
+7. **Least privilege:** rules specify a principal or role, action, and resource.
+
+## Installation
+
+Requires Python 3.11 or newer.
+
+### Install the published package
+
+After the first PyPI release is available, install the alpha package with its optional agent middleware:
+
+```bash
+python -m pip install --pre "langgraph-secure-agents[langchain-agents]"
+```
+
+For the core policy engine and callable guard without LangGraph middleware:
+
+```bash
+python -m pip install --pre langgraph-secure-agents
+```
+
+The `--pre` flag is needed while the latest published version is an alpha pre-release. Until the package is available on PyPI, use the source-install instructions below.
+
+### Install from a source checkout
+
+Clone this repository, then install the core package and development tools:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+Install the optional middleware dependencies from the same checkout:
+
+```bash
+python -m pip install -e ".[langchain-agents]"
+```
+
+The core policy engine and callable guard do not require LangGraph or an LLM provider.
+
+## Run the model-free LangGraph example
+
+The example uses fake payroll records and a trusted runtime context. It needs no model API key:
+
+```bash
+python examples/policy_guarded_workflow.py
+```
+
+It demonstrates an allowed HR request, a denied request for an unapproved resource, and a denied request from a user without the required role.
+
+## Quick start: deterministic policy engine
+
+```python
+from langgraph_secure_agents import (
+    AccessRequest,
+    DecisionReason,
+    Effect,
+    PolicyEngine,
+    PolicyRule,
+    Principal,
+)
+
+policy = PolicyEngine(
+    [
+        PolicyRule(
+            rule_id="analysts-read-reports",
+            effect=Effect.ALLOW,
+            principal_ids=frozenset(),
+            roles=frozenset({"analyst"}),
+            actions=frozenset({"read"}),
+            resources=frozenset({"reports"}),
+        )
+    ]
+)
+
+decision = policy.evaluate(
+    AccessRequest(
+        principal=Principal("user-123", roles=frozenset({"analyst"})),
+        action="read",
+        resource="reports",
+    )
+)
+
+assert decision.allowed
+assert decision.reason is DecisionReason.EXPLICIT_ALLOW
+```
+
+### Decision outcomes and policy updates
+
+`Decision.reason` is a public `DecisionReason` enum with stable machine-readable values: `explicit_allow`, `explicit_deny`, `default_deny`, `approval_required`, `approval_invalid`, `approval_denied`, and `human_approved`. Use the enum constants in application code rather than comparing free-form strings. `matched_rule_ids` identifies the policy rules responsible for a rule-based outcome; a default-deny decision has no matched rule IDs. `requires_approval` is true only for `approval_required`.
+
+A `PolicyEngine`'s rules cannot be replaced after construction. To deploy a policy change, construct and validate a new engine, then switch the application to it using the application's own configuration/reload mechanism. Do not mutate private state on a live engine. This matters for approval pauses: the request fingerprint binds approval to the matched rule definitions, so a resumed decision must still refer to the policy that produced the interrupt.
+
+## Protect a Python callable
+
+```python
+from langgraph_secure_agents import PolicyEngine, Principal, protect_callable
+
+# This resolver must read a trusted, request-scoped identity source.
+current_principal = lambda: Principal("user-123", roles=frozenset({"analyst"}))
+
+protected_lookup = protect_callable(
+    lookup_report,
+    policy=policy,
+    principal_resolver=current_principal,
+    action="read",
+    resource_resolver=lambda report_id: f"report:{report_id}",
+)
+```
+
+The resource resolver must describe the same resource the wrapped function actually accesses. Resolver callbacks receive detached copies of arguments, and attempts to mutate those copies fail closed before execution. Resolvers must otherwise be trusted, side-effect-free application code. For multi-user applications, the principal resolver must read request-scoped trusted context; do not capture one user's identity in a process-wide shared tool.
+
+## Optional agent middleware
+
+The optional module `langgraph_secure_agents.middleware` provides `create_authorization_middleware` for LangChain agents built on LangGraph. It intercepts tool calls before execution. By default, the policy action is `execute` and the resource is the tool name. Custom resolvers can map tool calls to domain-level actions and resources.
+
+The middleware receives runtime context from the agent invocation. The application must configure a principal resolver that validates this context and creates a `Principal` from trusted identity data. Custom action/resource resolvers receive detached copies of tool arguments; attempts to mutate these copies fail closed. Denied calls return an error tool message and do not invoke the tool handler.
+
+## Human approval for sensitive actions
+
+A policy can explicitly require approval instead of granting access immediately:
+
+```python
+approval_policy = PolicyEngine(
+    [
+        PolicyRule(
+            rule_id="approval-required-payroll-read",
+            effect=Effect.REQUIRE_APPROVAL,
+            actions=frozenset({"read"}),
+            resources=frozenset({"payroll:employee-7"}),
+            roles=frozenset({"hr"}),
+        )
+    ]
+)
+```
+
+When this policy is used with the optional agent middleware, LangGraph pauses at an interrupt before the tool handler executes. The paused payload describes the principal, action, resource, policy rule, tool, and a request fingerprint. After a reviewer makes a decision, the host application resumes the same checkpoint/thread with a value shaped like:
+
+```python
+{
+    "approved": True,
+    "request_fingerprint": fingerprint_from_interrupt_payload,
+}
+```
+
+The middleware rejects missing, malformed, or mismatched approval responses. The fingerprint binds the response to the current principal, roles, tool call, arguments, action, resource, exact matched policy definitions, and LangGraph execution scope (`thread_id`, `checkpoint_id`, `checkpoint_ns`, and `task_id`). This makes the fingerprint different in another checkpointed execution even when request fields and the tool-call ID are repeated. Approval-required calls need LangGraph 1.2 or newer with an active checkpointer; missing execution metadata fails closed. Fingerprinting rejects non-string JSON object keys, non-finite numbers, cyclic structures, and other non-JSON argument values. **The fingerprint is a deterministic request-binding check, not proof of reviewer identity, permission, or one-time use.** The host application must authenticate the reviewer, authorize who can resume the paused run, and protect the resume endpoint. For side-effecting tools, ensure request IDs are unique per operation and durably consume each approval once. The `approval_validator` callback described below can enforce reviewer validation and atomic consumption at the middleware boundary. An explicit matching deny rule always takes precedence over approval.
+
+For deployments that need enforcement in the library boundary, pass an `approval_validator` callback to `create_authorization_middleware`. It receives the resumed approval mapping, the resolved `AccessRequest`, and the request fingerprint. It should authenticate and authorize the reviewer, then atomically claim/consume the fingerprint in a durable store; return the literal `True` only for a valid first use. A false or non-boolean result rejects the approval, and an exception fails closed by preventing tool execution. Implement this callback with your application's identity provider and transactional storage—do not use an in-memory set for multi-process or persistent workloads. The callback is invoked for validly-shaped approval and rejection responses, so the host can consume either human decision once. If the callback is omitted, the host must enforce these controls outside the library. An explicit matching deny rule always takes precedence over approval.
+
+## Validation
+
+```bash
+ruff check .
+ruff format --check .
+mypy src
+pytest
+```
+
+GitHub Actions runs these checks across Python 3.11, 3.12, and 3.13 on pull requests and pushes to `main`, with a 98% minimum line-coverage gate. A separate packaging job builds both a wheel and source distribution, validates metadata, smoke-tests the installed wheel in a clean environment, and installs the `langchain-agents` extra in a separate environment to verify the optional middleware dependencies.
+
+After a change is merged into `main`, the automatic release workflow analyzes Conventional Commit messages. If a release-worthy change exists and all release quality checks pass, it updates the version and changelog, creates a version commit and Git tag, builds distributions, creates a GitHub Release, and publishes to PyPI using Trusted Publishing. No manual tag creation is required. See [the release process](docs/releasing.md).
+
+## Roadmap
+
+- [x] Typed package foundation, license, and CI
+- [x] Policy models and default-deny evaluation
+- [x] Deny-overrides semantics and constrained wildcards
+- [x] Guarded callable and fail-closed auditing
+- [x] Optional agent tool-call middleware
+- [x] Model-free LangGraph workflow example with mock payroll data
+- [ ] Example conversational agent using a model provider
+- [x] Human-approval interrupt integration for selected sensitive actions
+- [x] Initial threat model and security reporting guidance
+- [ ] API review and release-readiness checks
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for user-facing changes and release notes.
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Disclaimer
+
+This project is experimental and is not a substitute for a complete application security review. Integrators remain responsible for authenticating principals, validating trusted context, enforcing tenant boundaries, and protecting downstream resources.