taskfence 0.1.0__tar.gz

taskfence-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes are listed here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/). Before 1.0, minor versions may change the API.
+
+## [0.1.0] - 2026-10-31
+
+The first release: a library implementation of the commit-time authorization design from *TaskFence: Commit-Time Authorization and Revocation Safety for Long-Running MCP Agent Workflows* (ICICyTA 2026).
+
+### Added
+- **The `Fence` API.**
+  - `grant`, `revoke`, `regrant` and `issue` (signed task tokens)
+  - `guard()`, which authorizes an effect inside the transaction that commits it, plus the `@fenced` decorator
+  - `cancel_task` and `cancel_operation` fences
+  - idempotent `operation_id`s, with an explicit `Duplicate` outcome
+  - an optional application predicate, checked inside the same transaction
+  - a transactional outbox: `enqueue` and `drain_outbox`
+  - owner-side federated messages: `apply_install` and `apply_fence`, idempotent and with a monotone floor
+- **Tokens.** `tf1` format, HMAC-SHA256, and a `KeyRing` with key rotation. Standard library only; no runtime dependencies.
+- **SQLite store.** WAL mode; the fence check is a conditional UPDATE under the write lock, as evaluated in the paper.
+- **PostgreSQL store** (`taskfence[postgres]`), with two lock modes:
+  - `lock="shared"` (default): a fair advisory lock plus `FOR SHARE`
+  - `lock="exclusive"`: `FOR UPDATE`
+
+  It is safe at READ COMMITTED, REPEATABLE READ and SERIALIZABLE, and is tested in CI on Postgres 15, 16 and 17.
+- **`taskfence.testing`.** Latches for deterministic races, an independent SQL auditor (`audit`, `assert_no_violations`), and a `taskfence_latches` pytest fixture.
+- **Examples.** A SQLite quickstart, and an MCP refund-desk server with a demo client (`taskfence[examples]`).
+- **Docs.** Design, threat model and limitations.
+
+### Known limitations
+See [docs/LIMITATIONS.md](docs/LIMITATIONS.md). In short:
+- the effect must be in the same database as TaskFence's tables
+- external calls are covered only as far as the outbox
+- there is no async API yet
+- there is no MCP Tasks extension integration yet

taskfence-0.1.0/CITATION.cff

@@ -0,0 +1,26 @@
+cff-version: 1.2.0
+message: "If you use TaskFence, please cite the paper below."
+title: "TaskFence: revocation-safe side effects for long-running AI agent tasks"
+type: software
+authors:
+  - family-names: Mohammad
+    given-names: Muzeeb
+license: MIT
+version: 0.1.0
+repository-code: "https://github.com/mohdmuzeeb/taskfence"
+keywords:
+  - authorization
+  - revocation
+  - AI agents
+  - Model Context Protocol
+  - fencing tokens
+# TODO: add `doi:` for the archived research artifact (Zenodo) once it is reserved.
+preferred-citation:
+  type: conference-paper
+  title: "TaskFence: Commit-Time Authorization and Revocation Safety for Long-Running MCP Agent Workflows"
+  authors:
+    - family-names: Mohammad
+      given-names: Muzeeb
+  collection-title: "International Conference on Intelligent Cybernetics Technology & Applications (ICICyTA 2026)"
+  year: 2026
+  # TODO: add `doi:` and pages once the proceedings are published.

taskfence-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Thanks for helping. Issues, bug reports and pull requests are welcome.
+
+## Development setup
+
+```bash
+python3 -m venv .venv && .venv/bin/pip install -e ".[test,postgres,examples]"
+```
+
+```bash
+.venv/bin/python -m pytest                     # SQLite + MCP example
+```
+
+PostgreSQL tests need a server with commit timestamps enabled:
+
+```bash
+docker run -d --rm --name taskfence-pg -e POSTGRES_PASSWORD=test -p 127.0.0.1:55432:5432 postgres:16 -c track_commit_timestamp=on
+```
+
+```bash
+TASKFENCE_PG_DSN=postgresql://postgres:test@127.0.0.1:55432/postgres .venv/bin/python -m pytest
+```
+
+## Ground rules for changes
+
+- **Safety changes come with a race test.** Anything touching `guard()`, a store, or the control plane needs a latch-scheduled test in `tests/test_races.py`, or `tests/test_pg_isolation.py` for PostgreSQL-specific behavior. The test should fail without the change, and `assert_no_violations()` should pass with it.
+- **Every back-end runs the same tests.** New behavior is tested through `conftest.py`'s `backend` fixture, so it runs on SQLite, `pg-shared` and `pg-exclusive`.
+- **The core has no runtime dependencies.** The core uses only the standard library; drivers are optional extras.
+- **Claims match evidence.** If a change affects what TaskFence guarantees, update `docs/THREAT_MODEL.md` and `docs/LIMITATIONS.md` in the same pull request.
+
+Report security issues privately; see [SECURITY.md](SECURITY.md).

taskfence-0.1.0/LICENSE

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

taskfence-0.1.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE README.md CHANGELOG.md CITATION.cff SECURITY.md CONTRIBUTING.md
+recursive-include tests *.py
+recursive-include examples *.py *.md
+recursive-include docs *.md
+global-exclude __pycache__ *.py[cod] *.sqlite*

taskfence-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: taskfence
+Version: 0.1.0
+Summary: Revocation-safe side effects for long-running AI agent tasks: commit-time authorization in your own database transaction.
+Author: Muzeeb Mohammad
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mohdmuzeeb/taskfence
+Project-URL: Documentation, https://github.com/mohdmuzeeb/taskfence/tree/main/docs
+Project-URL: Issues, https://github.com/mohdmuzeeb/taskfence/issues
+Project-URL: Changelog, https://github.com/mohdmuzeeb/taskfence/blob/main/CHANGELOG.md
+Keywords: ai-agents,mcp,model-context-protocol,authorization,revocation,fencing-token
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: Pytest
+Classifier: Topic :: Security
+Classifier: Topic :: Database
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == "postgres"
+Provides-Extra: examples
+Requires-Dist: mcp>=2.3; extra == "examples"
+Dynamic: license-file
+
+# TaskFence
+
+[![CI](https://github.com/mohdmuzeeb/taskfence/actions/workflows/ci.yml/badge.svg)](https://github.com/mohdmuzeeb/taskfence/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/taskfence)](https://pypi.org/project/taskfence/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/mohdmuzeeb/taskfence/blob/main/LICENSE)
+
+**Revocation-safe side effects for long-running AI agent tasks.**
+
+If a user revokes permission while an agent task is running, TaskFence guarantees the task cannot commit its side effect afterwards. The check runs **inside your own database transaction**, at commit time, not before it.
+
+## The problem
+
+1. An agent task is admitted: the user has granted `refund.issue`.
+2. The task works for 10 minutes (LLM calls, tool calls, waiting for input).
+3. At minute 4, the user revokes the grant.
+4. At minute 10, the task writes the refund. **Most servers allow this**, because they checked permission when the task started, or just before the write in a separate step.
+
+The TaskFence paper measured this window. In one randomized run, designs that check at start or in a separate pre-commit step let 317 provable commits through after revocation. Checking inside the commit transaction let none through.
+
+## Install
+
+```bash
+pip install taskfence                 # SQLite; core has no dependencies
+```
+
+```bash
+pip install "taskfence[postgres]"     # PostgreSQL via psycopg 3
+```
+
+Requires Python 3.12+. PostgreSQL 15, 16 and 17 are tested in CI.
+
+## Example
+
+```python
+from taskfence import Denied, Fence, KeyRing
+from taskfence.stores.sqlite import connect
+
+fence = Fence(KeyRing.from_env("TASKFENCE_KEYS"))   # or KeyRing.generate() to try it out
+conn = connect("app.sqlite")
+fence.migrate(conn)
+conn.executescript("CREATE TABLE IF NOT EXISTS orders (id TEXT PRIMARY KEY, refunded INTEGER DEFAULT 0);"
+                   "INSERT OR IGNORE INTO orders VALUES ('order:9001', 0);")
+
+# The user grants the agent permission; a task is admitted with a signed token.
+g = fence.grant(conn, principal="user:42", operation="refund.issue", resources=["order:9001"])
+token = fence.issue(conn, g.grant_id, task_id="task-1")
+
+# ... the task works for minutes; meanwhile the user may call fence.revoke(conn, g.grant_id) ...
+
+try:
+    with fence.transaction(conn):            # do slow work BEFORE opening the transaction
+        fence.guard(conn, token, operation="refund.issue", resource="order:9001",
+                    operation_id="task-1:refund")
+        conn.execute("UPDATE orders SET refunded = 1 WHERE id = 'order:9001'")
+except Denied as e:
+    print("blocked:", e.code)                # STALE_EPOCH if access was revoked meanwhile
+```
+
+[examples/01_quickstart_sqlite.py](https://github.com/mohdmuzeeb/taskfence/blob/main/examples/01_quickstart_sqlite.py) runs this with a revocation in the middle and prints `refund blocked: STALE_EPOCH`.
+
+For PostgreSQL:
+
+```python
+from taskfence.stores.postgres import PostgresStore, connect
+fence = Fence(KeyRing.from_env(), PostgresStore())   # fair shared locking per grant (default)
+```
+
+## How it works
+
+- **Grants have epochs.** Revoking a grant raises a fence (`min_epoch`) in your database. Regranting starts a new epoch.
+- **Tasks carry a signed token** naming the epoch they were admitted under.
+- **`guard()` checks the token in the same transaction as the effect.** The commit either sees the revocation, or is strictly ordered before it.
+- **The same check also:**
+  - fences cancelled tasks
+  - makes each `operation_id` commit at most once
+  - enforces resource scope and an optional application predicate
+  - can write an outbox entry for external calls
+
+Details: [docs/DESIGN.md](https://github.com/mohdmuzeeb/taskfence/blob/main/docs/DESIGN.md) and [docs/THREAT_MODEL.md](https://github.com/mohdmuzeeb/taskfence/blob/main/docs/THREAT_MODEL.md).
+
+## What it guarantees, and what it does not
+
+- ✅ No effect protected by `guard()` commits after revocation, or after task cancellation, has taken effect.
+- ✅ A revocation waits for at most the guarded transactions already in flight, never for a whole task.
+- ❌ Not retroactive: effects that committed before the revocation stay committed.
+- ❌ External calls (payments, e-mail) are covered only as far as the outbox entry. Your downstream must be idempotent.
+- ❌ The effect must be in the same database as TaskFence's tables. Federated multi-service mode is planned for v0.2.
+
+Read [docs/LIMITATIONS.md](https://github.com/mohdmuzeeb/taskfence/blob/main/docs/LIMITATIONS.md) before relying on it.
+
+## Testing your own code for revocation races
+
+`taskfence.testing` stages races deterministically with latches, and checks the database with an independent auditor:
+
+```python
+from taskfence.testing import assert_no_violations, hook, run_in_thread
+
+# `taskfence_latches` is a fixture that ships with taskfence; `fence`, `conn` and `grant` are yours.
+def test_revoke_while_refund_runs(taskfence_latches, fence, conn, grant):
+    token = fence.issue(conn, grant.grant_id, task_id="t1")
+    pause = taskfence_latches.pause_at("app.before_txn")    # your code calls hook("app.before_txn")
+    worker = run_in_thread(lambda: my_refund(token))
+    pause.wait_reached()
+    fence.revoke(conn, grant.grant_id)                      # revoke while the task is mid-flight
+    pause.release()
+    worker.join()
+    assert_no_violations(conn)                              # no commit after the revocation
+```
+
+## Using with MCP servers
+
+[examples/03_mcp_server](https://github.com/mohdmuzeeb/taskfence/tree/main/examples/03_mcp_server) is a refund-desk MCP server whose background refunds are fenced by TaskFence. A demo drives it with the official MCP client and shows four cases:
+- a refund revoked mid-task is blocked
+- a refund cancelled mid-task is blocked
+- a refund on another customer's order is blocked
+- a refund after a fresh grant commits
+
+The Python MCP SDK does not include the MCP Tasks extension yet, so the example uses start-then-poll tools.
+
+## Roadmap
+
+- **v0.2:** a federated grant authority (signed service-to-service RPC), TypeScript middleware for the MCP Tasks extension, and an async API
+- **v0.3:** `taskfence scan`, a revocation-race checker for MCP servers
+
+## Research and citation
+
+TaskFence is based on peer-reviewed research:
+
+> M. Mohammad, "TaskFence: Commit-Time Authorization and Revocation Safety for Long-Running MCP Agent Workflows," *International Conference on Intelligent Cybernetics Technology & Applications (ICICyTA 2026)*.
+
+If you use TaskFence, please cite the paper. GitHub's "Cite this repository" button uses [CITATION.cff](https://github.com/mohdmuzeeb/taskfence/blob/main/CITATION.cff). The archived research artifact (code, preregistration, wire traces, raw databases) will be linked here once it has a DOI.
+
+## Contributing and security
+
+Issues and pull requests are welcome; see [CONTRIBUTING.md](https://github.com/mohdmuzeeb/taskfence/blob/main/CONTRIBUTING.md). Report vulnerabilities privately as described in [SECURITY.md](https://github.com/mohdmuzeeb/taskfence/blob/main/SECURITY.md).
+
+## License
+
+MIT

taskfence-0.1.0/README.md

@@ -0,0 +1,139 @@
+# TaskFence
+
+[![CI](https://github.com/mohdmuzeeb/taskfence/actions/workflows/ci.yml/badge.svg)](https://github.com/mohdmuzeeb/taskfence/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/taskfence)](https://pypi.org/project/taskfence/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/mohdmuzeeb/taskfence/blob/main/LICENSE)
+
+**Revocation-safe side effects for long-running AI agent tasks.**
+
+If a user revokes permission while an agent task is running, TaskFence guarantees the task cannot commit its side effect afterwards. The check runs **inside your own database transaction**, at commit time, not before it.
+
+## The problem
+
+1. An agent task is admitted: the user has granted `refund.issue`.
+2. The task works for 10 minutes (LLM calls, tool calls, waiting for input).
+3. At minute 4, the user revokes the grant.
+4. At minute 10, the task writes the refund. **Most servers allow this**, because they checked permission when the task started, or just before the write in a separate step.
+
+The TaskFence paper measured this window. In one randomized run, designs that check at start or in a separate pre-commit step let 317 provable commits through after revocation. Checking inside the commit transaction let none through.
+
+## Install
+
+```bash
+pip install taskfence                 # SQLite; core has no dependencies
+```
+
+```bash
+pip install "taskfence[postgres]"     # PostgreSQL via psycopg 3
+```
+
+Requires Python 3.12+. PostgreSQL 15, 16 and 17 are tested in CI.
+
+## Example
+
+```python
+from taskfence import Denied, Fence, KeyRing
+from taskfence.stores.sqlite import connect
+
+fence = Fence(KeyRing.from_env("TASKFENCE_KEYS"))   # or KeyRing.generate() to try it out
+conn = connect("app.sqlite")
+fence.migrate(conn)
+conn.executescript("CREATE TABLE IF NOT EXISTS orders (id TEXT PRIMARY KEY, refunded INTEGER DEFAULT 0);"
+                   "INSERT OR IGNORE INTO orders VALUES ('order:9001', 0);")
+
+# The user grants the agent permission; a task is admitted with a signed token.
+g = fence.grant(conn, principal="user:42", operation="refund.issue", resources=["order:9001"])
+token = fence.issue(conn, g.grant_id, task_id="task-1")
+
+# ... the task works for minutes; meanwhile the user may call fence.revoke(conn, g.grant_id) ...
+
+try:
+    with fence.transaction(conn):            # do slow work BEFORE opening the transaction
+        fence.guard(conn, token, operation="refund.issue", resource="order:9001",
+                    operation_id="task-1:refund")
+        conn.execute("UPDATE orders SET refunded = 1 WHERE id = 'order:9001'")
+except Denied as e:
+    print("blocked:", e.code)                # STALE_EPOCH if access was revoked meanwhile
+```
+
+[examples/01_quickstart_sqlite.py](https://github.com/mohdmuzeeb/taskfence/blob/main/examples/01_quickstart_sqlite.py) runs this with a revocation in the middle and prints `refund blocked: STALE_EPOCH`.
+
+For PostgreSQL:
+
+```python
+from taskfence.stores.postgres import PostgresStore, connect
+fence = Fence(KeyRing.from_env(), PostgresStore())   # fair shared locking per grant (default)
+```
+
+## How it works
+
+- **Grants have epochs.** Revoking a grant raises a fence (`min_epoch`) in your database. Regranting starts a new epoch.
+- **Tasks carry a signed token** naming the epoch they were admitted under.
+- **`guard()` checks the token in the same transaction as the effect.** The commit either sees the revocation, or is strictly ordered before it.
+- **The same check also:**
+  - fences cancelled tasks
+  - makes each `operation_id` commit at most once
+  - enforces resource scope and an optional application predicate
+  - can write an outbox entry for external calls
+
+Details: [docs/DESIGN.md](https://github.com/mohdmuzeeb/taskfence/blob/main/docs/DESIGN.md) and [docs/THREAT_MODEL.md](https://github.com/mohdmuzeeb/taskfence/blob/main/docs/THREAT_MODEL.md).
+
+## What it guarantees, and what it does not
+
+- ✅ No effect protected by `guard()` commits after revocation, or after task cancellation, has taken effect.
+- ✅ A revocation waits for at most the guarded transactions already in flight, never for a whole task.
+- ❌ Not retroactive: effects that committed before the revocation stay committed.
+- ❌ External calls (payments, e-mail) are covered only as far as the outbox entry. Your downstream must be idempotent.
+- ❌ The effect must be in the same database as TaskFence's tables. Federated multi-service mode is planned for v0.2.
+
+Read [docs/LIMITATIONS.md](https://github.com/mohdmuzeeb/taskfence/blob/main/docs/LIMITATIONS.md) before relying on it.
+
+## Testing your own code for revocation races
+
+`taskfence.testing` stages races deterministically with latches, and checks the database with an independent auditor:
+
+```python
+from taskfence.testing import assert_no_violations, hook, run_in_thread
+
+# `taskfence_latches` is a fixture that ships with taskfence; `fence`, `conn` and `grant` are yours.
+def test_revoke_while_refund_runs(taskfence_latches, fence, conn, grant):
+    token = fence.issue(conn, grant.grant_id, task_id="t1")
+    pause = taskfence_latches.pause_at("app.before_txn")    # your code calls hook("app.before_txn")
+    worker = run_in_thread(lambda: my_refund(token))
+    pause.wait_reached()
+    fence.revoke(conn, grant.grant_id)                      # revoke while the task is mid-flight
+    pause.release()
+    worker.join()
+    assert_no_violations(conn)                              # no commit after the revocation
+```
+
+## Using with MCP servers
+
+[examples/03_mcp_server](https://github.com/mohdmuzeeb/taskfence/tree/main/examples/03_mcp_server) is a refund-desk MCP server whose background refunds are fenced by TaskFence. A demo drives it with the official MCP client and shows four cases:
+- a refund revoked mid-task is blocked
+- a refund cancelled mid-task is blocked
+- a refund on another customer's order is blocked
+- a refund after a fresh grant commits
+
+The Python MCP SDK does not include the MCP Tasks extension yet, so the example uses start-then-poll tools.
+
+## Roadmap
+
+- **v0.2:** a federated grant authority (signed service-to-service RPC), TypeScript middleware for the MCP Tasks extension, and an async API
+- **v0.3:** `taskfence scan`, a revocation-race checker for MCP servers
+
+## Research and citation
+
+TaskFence is based on peer-reviewed research:
+
+> M. Mohammad, "TaskFence: Commit-Time Authorization and Revocation Safety for Long-Running MCP Agent Workflows," *International Conference on Intelligent Cybernetics Technology & Applications (ICICyTA 2026)*.
+
+If you use TaskFence, please cite the paper. GitHub's "Cite this repository" button uses [CITATION.cff](https://github.com/mohdmuzeeb/taskfence/blob/main/CITATION.cff). The archived research artifact (code, preregistration, wire traces, raw databases) will be linked here once it has a DOI.
+
+## Contributing and security
+
+Issues and pull requests are welcome; see [CONTRIBUTING.md](https://github.com/mohdmuzeeb/taskfence/blob/main/CONTRIBUTING.md). Report vulnerabilities privately as described in [SECURITY.md](https://github.com/mohdmuzeeb/taskfence/blob/main/SECURITY.md).
+
+## License
+
+MIT

taskfence-0.1.0/SECURITY.md

@@ -0,0 +1,25 @@
+# Security policy
+
+TaskFence is a security library, so reports are very welcome.
+
+## Reporting a vulnerability
+
+Please **do not open a public issue**. Report privately through GitHub's private vulnerability reporting: the **Security** tab of this repository, then **Report a vulnerability**.
+
+Include:
+- the TaskFence version
+- the store (SQLite or PostgreSQL and its version)
+- the isolation level
+- a minimal reproduction, ideally a test using `taskfence.testing` latches and `audit()`
+
+You should get an acknowledgment within 7 days. Fixes for confirmed issues are released with a GitHub security advisory that credits the reporter, unless they prefer otherwise.
+
+## What counts
+
+Anything that lets an effect commit after its revocation or cancellation is effective, as defined in [docs/THREAT_MODEL.md](docs/THREAT_MODEL.md). Also reportable: token forgery, a scope or principal bypass, or a way to make the auditor miss a violation.
+
+The limitations listed in [docs/LIMITATIONS.md](docs/LIMITATIONS.md) are known and documented, not vulnerabilities.
+
+## Supported versions
+
+Only the latest release receives fixes during the 0.x series.