taskfence 0.1.0__py3-none-any.whl

taskfence-0.1.0.dist-info/METADATA

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

@@ -0,0 +1,18 @@
+taskfence/__init__.py,sha256=3VK2XnN0yhFV88VwFiGutf9rGhyVGiwWJ_71hSA1paE,481
+taskfence/_hooks.py,sha256=pH3wqDChRp76UMSrVTsFMJYO20VSZnL3xWbdQBoyO0Q,844
+taskfence/fence.py,sha256=xfFnT10YTtGy5cjqIp8l1LfI543wpwfXvM-eSOYYFlo,10315
+taskfence/outcomes.py,sha256=yW1tEKB0DalQ1WWCTJ0J0aIJUXWScFJTBf4xAqnEaI0,2627
+taskfence/tokens.py,sha256=79kBF07u_x6lgsg4bWBJnFsGgG3eOxLR5YyYWWNJ4fo,3873
+taskfence/stores/__init__.py,sha256=w0J6BqRsYZmpPyIYA8SdSdO4rZ3iOqJkwuIYIj6FNuE,79
+taskfence/stores/postgres.py,sha256=Xq8_Ssb4ffsE23bOR2ubfW9zgU7FzFxt-V_7UeMj6-M,17012
+taskfence/stores/sqlite.py,sha256=8zMmWD2Bg02s4gM2MkFg32OpGADJAmD1XdlzrHTaiC0,15295
+taskfence/testing/__init__.py,sha256=sPpvfMaAzfleWVjPCE-YjUIFeKeabR45v0SU_5BaoTk,410
+taskfence/testing/audit.py,sha256=FT_cpHBwVHH7sUE0_QYp5yrfh7wV4T5KhY5oLYbiB-o,3213
+taskfence/testing/latches.py,sha256=nilSP8VAiUC8AeS4zrkU8UbGz8iZkSsHzPFCVLvaZBE,4569
+taskfence/testing/plugin.py,sha256=swPoFIP50NPoOW42EscodowbYiUOMND1FCgyYNAr2sI,307
+taskfence-0.1.0.dist-info/licenses/LICENSE,sha256=htAZdhshqoCQDSpdWYVFuofP6-oq6Aa-mvDSjlmfgO4,1072
+taskfence-0.1.0.dist-info/METADATA,sha256=wdNisgPoCqXszaCmOl51trFN0z_7o5kLbugMmyySnes,8406
+taskfence-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+taskfence-0.1.0.dist-info/entry_points.txt,sha256=Rpi9VgUPq0RZkgp4EB5FPgc_zbuzexzuLeU7swJ092M,48
+taskfence-0.1.0.dist-info/top_level.txt,sha256=S82N3a-i8vd8TaZJDA4wBXBnHpynrwOTXtKqR19JM-w,10
+taskfence-0.1.0.dist-info/RECORD,,

taskfence-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

taskfence-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+taskfence = taskfence.testing.plugin

taskfence-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+taskfence