offwork 0.1.2__tar.gz → 0.1.4__tar.gz

{offwork-0.1.2 → offwork-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: offwork
-Version: 0.1.2
+Version: 0.1.4
 Summary: Distributed Python task execution via automatic function serialization
 License: AGPL-3.0-only
 License-File: LICENSE
@@ -27,32 +27,35 @@ Description-Content-Type: text/markdown
 
 # offwork
 
-**Run any Python function on a remote worker — zero setup, zero deployment.**
-
 [![PyPI](https://img.shields.io/pypi/v/offwork)](https://pypi.org/project/offwork/)
 [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
 [![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-green)](LICENSE)
 [![Typed](https://img.shields.io/badge/typing-strict%20mypy-blue)](https://mypy-lang.org/)
 [![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)]()
 
-Add `@offwork.task` to a function. offwork captures its source, all dependencies, and all imports automatically. Workers reconstruct and execute everything from scratch — no shared filesystem, no deployment pipeline. Missing packages are installed on the fly.
+**Run any Python function on a remote worker with just two lines of code.**
+
+Put `.connect()` somewhere at the start of your script, add `@offwork.task` to your function, that's it.
+You can now run it remotely — no shared codebase, no deployment pipeline.
+
+`offwork` captures its entire dependency graph (helpers, imports, closures, constants) and ships it to the worker as a self-contained payload. The worker doesn't need to have any prior knowledge of your code.
 
 ## Quick start
 
 ```bash
 pip install offwork
+offwork worker --backend local://localhost:9748 --tmp  # start a worker in a temp venv
 ```
 
 ```python
 import asyncio, math, offwork
-import offwork
 
 offwork.connect("local://localhost:9748")
 
-def add(a, b):
+def add(a: float, b: float) -> float:
     return a + b
 
-@offwork.task
+@offwork.task  # only the entry point needs this - add() is captured automatically
 def hypotenuse(a: float, b: float) -> float:
     return math.sqrt(add(a**2, b**2))
 
@@ -62,66 +65,69 @@ async def main():
 asyncio.run(main())
 ```
 
-Only the entry point needs `@offwork.task` — everything it calls is captured automatically.
+`.run()` serializes the function graph, submits it to the worker, and returns the result. The worker reconstructs source, installs any missing packages, and executes.
+
+### Multi-machine
+
+Swap `local://` for Redis or RabbitMQ to run on a remote worker:
 
 ```bash
-offwork worker --backend local://localhost:9748 --tmp   # start a worker
-python my_script.py                                    # → 5.0
+pip install offwork[redis]
+offwork worker --backend redis://other-machine:6379
 ```
 
-For multi-machine, swap `local://` for `redis://` or an `https://` managed broker URL.
+See [Features](docs/FEATURES.md) for the full API.
 
 ## Features
 
 | | |
 |-|-|
-| **Auto dependency capture** | Functions, classes, constants, closures — recursive AST analysis |
-| **Package auto-install** | Workers `pip install` missing packages before execution |
-| **Async-native** | `.run()`, `.start()`, `.map()`, `asyncio.gather` |
+| **Async-native** | `.run()`, `.start()`, `.map()`, `asyncio.gather` — all coroutines |
+| **Scheduling** | `.run_in(delay)`, `.run_at(datetime)`, `.run_every(interval)` with cancellation |
 | **Retry & timeout** | `@offwork.task(timeout=30, retries=3)` with exponential backoff |
-| **Scheduling** | `.run_in(delay)`, `.run_at(datetime)`, `.run_every(freq)` with cancellation |
 | **Throttling** | `@offwork.task(throttle=timedelta(hours=24)/50)` — rate-limit executions |
 | **Progress & cancellation** | `offwork.progress(3, 10)` inside tasks; `await future.cancel()` on client |
-| **Heartbeat & stall detection** | Workers heartbeat; clients raise `TaskStalled` on silence |
-| **Content-hash caching** | Same code = cache hit, regardless of client |
-| **Pluggable backends** | `local://` (TCP), `redis://`, `amqp://` (RabbitMQ), `https://` (hosted) |
-| **Docker sandbox** | Container isolation, transparent to clients |
+| **Heartbeat & stall detection** | Workers heartbeat every second; clients raise `TaskStalled` on silence |
+| **Package auto-install** | Workers `pip install` missing packages before execution |
+| **Docker sandbox** | Optional container isolation, fully transparent to clients |
 | **Signed execution** | Pre-shared token or PIN pairing + HMAC-SHA256 task authentication |
-| **Graceful shutdown** | Ctrl+C drains in-flight tasks; second Ctrl+C force-quits |
 
-## Sandbox
+### Security
+
+#### Signing
 
-Run tasks inside Docker containers for isolation — transparent to clients:
+To make sure your worker only executes trusted code, use `--require-signing`.<br>
+Configure a shared token or pair interactively with a PIN. See [Signing & Pairing](docs/SIGNING.md) for details.
 
 ```bash
-offwork sandbox setup                                      # build image (once)
-offwork worker --backend redis://localhost:6379 --sandbox  # run with isolation
+# Token (CI/CD)
+offwork token generate
+export OFFWORK_SIGNING_TOKEN=<token>                         # client & worker
+offwork worker --backend redis://localhost:6379 --require-signing
+
+# PIN pairing (interactive)
+offwork worker --backend redis://localhost:6379 --pair       # shows 6-digit PIN
+offwork pair --backend redis://localhost:6379                # client: enter PIN
 ```
 
-See [Sandbox](docs/SANDBOX.md) for configuration.
+After pairing, tasks are signed automatically with no client code changes. See [Signing & Pairing](docs/SIGNING.md).
 
-## Signing
+#### Sandbox
 
-Pre-shared token or PIN-based pairing + HMAC-SHA256 — workers reject untrusted or tampered tasks:
+To avoid side-effects on the worker machine, run tasks inside Docker containers:
 
 ```bash
-# Token-based (recommended for CI/CD)
-offwork token generate
-export OFFWORK_SIGNING_TOKEN=<token>                         # set on client & worker
-offwork worker --backend redis://localhost:6379 --require-signing
-
-# PIN-based pairing (interactive)
-offwork worker --backend redis://localhost:6379 --pair       # displays a 6-digit PIN
-offwork pair --backend redis://localhost:6379                # on client: enter the PIN
+offwork sandbox setup                                      # build image (once)
+offwork worker --backend redis://localhost:6379 --sandbox  # run with isolation
 ```
 
-After setup, tasks are signed automatically. No client-side code changes. See [Signing & Pairing](docs/SIGNING.md).
+See [Sandbox](docs/SANDBOX.md) for configuration.
 
 ## Documentation
 
 | | |
 |-|-|
-| **[Quick Start](docs/QUICK_START.md)** | Tutorial and API walkthrough |
+| **[Features](docs/FEATURES.md)** | Full feature guide and API walkthrough |
 | **[Technical Overview](docs/TECHNICAL_OVERVIEW.md)** | Architecture, serialization format, internals |
 | **[Signing & Pairing](docs/SIGNING.md)** | Cryptographic task signing protocol |
 | **[Sandbox](docs/SANDBOX.md)** | Docker container isolation |
@@ -129,11 +135,11 @@ After setup, tasks are signed automatically. No client-side code changes. See [S
 ## Examples
 
 ```bash
-offwork worker --backend local://localhost:9748 --tmp
-offwork run examples/remote_execution.py
+offwork worker --backend local://localhost:9748 --tmp  # start worker
+offwork run examples/remote_execution.py              # run any example
 ```
 
-[`remote_execution.py`](examples/remote_execution.py) · [`async_execution.py`](examples/async_execution.py) · [`package_installation.py`](examples/package_installation.py) · [`progress_reporting.py`](examples/progress_reporting.py) · [`cancellation.py`](examples/cancellation.py) · [`scheduling.py`](examples/scheduling.py) · [`throttling_and_retry.py`](examples/throttling_and_retry.py) · [`large_module.py`](examples/large_module.py)
+See [examples/README.md](examples/README.md) for a guide to all examples.
 
 ## License
 

offwork-0.1.4/README.md

@@ -0,0 +1,119 @@
+# offwork
+
+[![PyPI](https://img.shields.io/pypi/v/offwork)](https://pypi.org/project/offwork/)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-green)](LICENSE)
+[![Typed](https://img.shields.io/badge/typing-strict%20mypy-blue)](https://mypy-lang.org/)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)]()
+
+**Run any Python function on a remote worker with just two lines of code.**
+
+Put `.connect()` somewhere at the start of your script, add `@offwork.task` to your function, that's it.
+You can now run it remotely — no shared codebase, no deployment pipeline.
+
+`offwork` captures its entire dependency graph (helpers, imports, closures, constants) and ships it to the worker as a self-contained payload. The worker doesn't need to have any prior knowledge of your code.
+
+## Quick start
+
+```bash
+pip install offwork
+offwork worker --backend local://localhost:9748 --tmp  # start a worker in a temp venv
+```
+
+```python
+import asyncio, math, offwork
+
+offwork.connect("local://localhost:9748")
+
+def add(a: float, b: float) -> float:
+    return a + b
+
+@offwork.task  # only the entry point needs this - add() is captured automatically
+def hypotenuse(a: float, b: float) -> float:
+    return math.sqrt(add(a**2, b**2))
+
+async def main():
+    print(await hypotenuse.run(3.0, 4.0))  # 5.0
+
+asyncio.run(main())
+```
+
+`.run()` serializes the function graph, submits it to the worker, and returns the result. The worker reconstructs source, installs any missing packages, and executes.
+
+### Multi-machine
+
+Swap `local://` for Redis or RabbitMQ to run on a remote worker:
+
+```bash
+pip install offwork[redis]
+offwork worker --backend redis://other-machine:6379
+```
+
+See [Features](docs/FEATURES.md) for the full API.
+
+## Features
+
+| | |
+|-|-|
+| **Async-native** | `.run()`, `.start()`, `.map()`, `asyncio.gather` — all coroutines |
+| **Scheduling** | `.run_in(delay)`, `.run_at(datetime)`, `.run_every(interval)` with cancellation |
+| **Retry & timeout** | `@offwork.task(timeout=30, retries=3)` with exponential backoff |
+| **Throttling** | `@offwork.task(throttle=timedelta(hours=24)/50)` — rate-limit executions |
+| **Progress & cancellation** | `offwork.progress(3, 10)` inside tasks; `await future.cancel()` on client |
+| **Heartbeat & stall detection** | Workers heartbeat every second; clients raise `TaskStalled` on silence |
+| **Package auto-install** | Workers `pip install` missing packages before execution |
+| **Docker sandbox** | Optional container isolation, fully transparent to clients |
+| **Signed execution** | Pre-shared token or PIN pairing + HMAC-SHA256 task authentication |
+
+### Security
+
+#### Signing
+
+To make sure your worker only executes trusted code, use `--require-signing`.<br>
+Configure a shared token or pair interactively with a PIN. See [Signing & Pairing](docs/SIGNING.md) for details.
+
+```bash
+# Token (CI/CD)
+offwork token generate
+export OFFWORK_SIGNING_TOKEN=<token>                         # client & worker
+offwork worker --backend redis://localhost:6379 --require-signing
+
+# PIN pairing (interactive)
+offwork worker --backend redis://localhost:6379 --pair       # shows 6-digit PIN
+offwork pair --backend redis://localhost:6379                # client: enter PIN
+```
+
+After pairing, tasks are signed automatically with no client code changes. See [Signing & Pairing](docs/SIGNING.md).
+
+#### Sandbox
+
+To avoid side-effects on the worker machine, run tasks inside Docker containers:
+
+```bash
+offwork sandbox setup                                      # build image (once)
+offwork worker --backend redis://localhost:6379 --sandbox  # run with isolation
+```
+
+See [Sandbox](docs/SANDBOX.md) for configuration.
+
+## Documentation
+
+| | |
+|-|-|
+| **[Features](docs/FEATURES.md)** | Full feature guide and API walkthrough |
+| **[Technical Overview](docs/TECHNICAL_OVERVIEW.md)** | Architecture, serialization format, internals |
+| **[Signing & Pairing](docs/SIGNING.md)** | Cryptographic task signing protocol |
+| **[Sandbox](docs/SANDBOX.md)** | Docker container isolation |
+
+## Examples
+
+```bash
+offwork worker --backend local://localhost:9748 --tmp  # start worker
+offwork run examples/remote_execution.py              # run any example
+```
+
+See [examples/README.md](examples/README.md) for a guide to all examples.
+
+## License
+
+[AGPL-3.0](LICENSE)

{offwork-0.1.2 → offwork-0.1.4}/offwork/__init__.py

@@ -8,14 +8,18 @@ from offwork.core.task import Task
 from offwork.core.errors import (
     Error,
     RemoteError,
+    ReplayError,
     TaskStalled,
     WorkerError,
     PairingError,
+    StaleTaskError,
     TaskCancelled,
     SignatureError,
     DependencyError,
     ThrottleError,
     WorkerOnlyError,
+    ClientRevokedError,
+    IdentityMismatchError,
 )
 from offwork.core.models import ImportInfo, FunctionNode
 from offwork.graph.graph import Graph
@@ -31,18 +35,29 @@ from offwork.core.pairing import (
     respond_to_pairing,
 )
 from offwork.core.signing import (
-    sign_json,
+    NonceLRU,
     derive_key,
     verify_signature,
     compute_signature,
-    verify_and_load_json,
 )
 from offwork.core.token import (
     load_token,
     save_token,
     clear_token,
     generate_token,
-    resolve_signing_key,
+    resolve_root_token,
+)
+from offwork.core.identity import (
+    get_client_id,
+    get_public_key,
+    clear_identity,
+    get_identity_seed,
+    get_identity_fingerprint,
+)
+from offwork.core.clients import KnownClients, ClientEntry
+from offwork.core.envelope import (
+    build_signed_envelope,
+    verify_task_envelope,
 )
 from offwork.core.version import _VERSION
 from offwork.core.progress import ProgressInfo
@@ -131,6 +146,10 @@ __all__ = [
     "TaskCancelled",
     "ThrottleError",
     "SignatureError",
+    "ReplayError",
+    "StaleTaskError",
+    "ClientRevokedError",
+    "IdentityMismatchError",
     "PairingError",
     "WorkerOnlyError",
     # Graph
@@ -139,15 +158,24 @@ __all__ = [
     # Signing
     "compute_signature",
     "verify_signature",
-    "sign_json",
-    "verify_and_load_json",
     "derive_key",
+    "NonceLRU",
+    "build_signed_envelope",
+    "verify_task_envelope",
     # Token
     "generate_token",
     "save_token",
     "load_token",
     "clear_token",
-    "resolve_signing_key",
+    "resolve_root_token",
+    # Identity / clients
+    "get_client_id",
+    "get_identity_seed",
+    "get_public_key",
+    "get_identity_fingerprint",
+    "clear_identity",
+    "KnownClients",
+    "ClientEntry",
     # Pairing
     "generate_pin",
     "save_shared_key",

{offwork-0.1.2 → offwork-0.1.4}/offwork/__main__.py

@@ -44,6 +44,8 @@ def _build_worker_cmd(python: str, args: argparse.Namespace) -> list[str]:
         cmd.extend(["--log-level", args.log_level])
     if args.require_signing:
         cmd.append("--require-signing")
+    if args.clock_skew != 300.0:
+        cmd.extend(["--clock-skew", str(args.clock_skew)])
     if args.sandbox:
         cmd.append("--sandbox")
     return cmd
@@ -108,6 +110,7 @@ def _cmd_worker(args: argparse.Namespace) -> None:
         auto_install=not args.no_auto_install,
         sandbox=bool(args.sandbox),
         require_signing=bool(args.require_signing),
+        clock_skew=float(args.clock_skew),
     ))
 
 
@@ -142,6 +145,7 @@ async def _pair_then_serve(args: argparse.Namespace) -> None:
         auto_install=not args.no_auto_install,
         sandbox=bool(args.sandbox),
         require_signing=True,
+        clock_skew=float(args.clock_skew),
     )
 
 
@@ -395,7 +399,9 @@ def _add_worker_parser(sub: "argparse._SubParsersAction[argparse.ArgumentParser]
     p.add_argument("--sandbox", action="store_true", default=False,
                     help="Run function execution inside an isolated Docker sandbox.")
     p.add_argument("--require-signing", action="store_true", default=False,
-                    help="Only accept tasks with valid HMAC signatures from paired clients.")
+                    help="Only accept tasks with valid signed envelopes (per-client HMAC + Ed25519).")
+    p.add_argument("--clock-skew", type=float, default=300.0, metavar="SECONDS",
+                    help="Maximum clock skew between client and worker (default: 300s)")
     p.add_argument("--pair", action="store_true", default=False,
                     help="Generate a pairing PIN, wait for a client to pair, then start "
                          "serving with signing enabled.")
@@ -649,6 +655,7 @@ def _build_parser() -> argparse.ArgumentParser:
     _add_sandbox_parser(sub)
     _add_pair_parser(sub)
     _add_token_parser(sub)
+    _add_clients_parser(sub)
     return parser
 
 
@@ -703,22 +710,27 @@ def _cmd_token_generate(args: argparse.Namespace) -> None:
 
 
 def _cmd_token_show(_args: argparse.Namespace) -> None:
-    """Show the current signing token status."""
+    """Show the current signing token + local identity status."""
     from offwork.core.token import load_token, _TOKEN_ENV_VAR
+    from offwork.core.identity import get_client_id, get_identity_fingerprint
 
     env_val = os.environ.get(_TOKEN_ENV_VAR)
     if env_val is not None:
         print(f"  Source: {_TOKEN_ENV_VAR} environment variable")
         print(f"  Token:  {env_val.strip()[:16]}... (truncated)")
-        return
-
-    token = load_token()
-    if token is not None:
-        print(f"  Source: ~/.offwork/token")
-        print(f"  Token:  {token[:16]}... (truncated)")
     else:
-        print("  No signing token configured.")
-        print("  Generate one with: offwork token generate")
+        token = load_token()
+        if token is not None:
+            print(f"  Source: ~/.offwork/token")
+            print(f"  Token:  {token[:16]}... (truncated)")
+        else:
+            print("  No signing token configured.")
+            print("  Generate one with: offwork token generate")
+
+    print()
+    print("  Local identity:")
+    print(f"    client_id:    {get_client_id()}")
+    print(f"    fingerprint:  {get_identity_fingerprint()}")
 
 
 def _cmd_token_clear(_args: argparse.Namespace) -> None:
@@ -749,6 +761,98 @@ def _add_token_parser(sub: "argparse._SubParsersAction[argparse.ArgumentParser]"
     token_sub.add_parser("clear", help="Remove the saved token")
 
 
+# -- Clients (known-clients registry) ---------------------------------------
+
+
+def _cmd_clients(args: argparse.Namespace) -> None:
+    """Handle ``offwork clients`` subcommands."""
+    action = getattr(args, "clients_action", None)
+    if action is None:
+        print("Usage: offwork clients {list|show|revoke|approve}", file=sys.stderr)
+        sys.exit(1)
+    handlers = {
+        "list": _cmd_clients_list,
+        "show": _cmd_clients_show,
+        "revoke": _cmd_clients_revoke,
+        "approve": _cmd_clients_approve,
+    }
+    handlers[action](args)
+
+
+def _format_ts(ts: float) -> str:
+    import datetime as _dt
+
+    return _dt.datetime.fromtimestamp(ts).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _cmd_clients_list(_args: argparse.Namespace) -> None:
+    from offwork.core.clients import KnownClients
+
+    entries = KnownClients().list_clients()
+    if not entries:
+        print("No known clients.")
+        return
+    print(f"{'CLIENT_ID':<34} {'FINGERPRINT':<18} "
+          f"{'FIRST_SEEN':<20} {'LAST_SEEN':<20} STATE")
+    import hashlib
+    for e in entries:
+        fp = hashlib.sha256(bytes.fromhex(e.pubkey)).hexdigest()[:16]
+        state = "revoked" if e.revoked else "active"
+        print(f"{e.client_id:<34} {fp:<18} "
+              f"{_format_ts(e.first_seen):<20} {_format_ts(e.last_seen):<20} {state}")
+
+
+def _cmd_clients_show(args: argparse.Namespace) -> None:
+    import hashlib
+
+    from offwork.core.clients import KnownClients
+
+    entry = KnownClients().get(args.client_id)
+    if entry is None:
+        print(f"No client with id {args.client_id!r}.", file=sys.stderr)
+        sys.exit(1)
+    fp = hashlib.sha256(bytes.fromhex(entry.pubkey)).hexdigest()[:16]
+    print(f"  client_id:    {entry.client_id}")
+    print(f"  pubkey:       {entry.pubkey}")
+    print(f"  fingerprint:  {fp}")
+    print(f"  first_seen:   {_format_ts(entry.first_seen)}")
+    print(f"  last_seen:    {_format_ts(entry.last_seen)}")
+    print(f"  revoked:      {entry.revoked}")
+
+
+def _cmd_clients_revoke(args: argparse.Namespace) -> None:
+    from offwork.core.clients import KnownClients
+
+    if KnownClients().revoke(args.client_id):
+        print(f"Revoked client {args.client_id}.")
+    else:
+        print(f"Client {args.client_id} not found or already revoked.")
+
+
+def _cmd_clients_approve(args: argparse.Namespace) -> None:
+    from offwork.core.clients import KnownClients
+
+    if KnownClients().approve(args.client_id):
+        print(f"Un-revoked client {args.client_id}.")
+    else:
+        print(f"Client {args.client_id} not found or not revoked.")
+
+
+def _add_clients_parser(sub: "argparse._SubParsersAction[argparse.ArgumentParser]") -> None:
+    p = sub.add_parser(
+        "clients",
+        help="Inspect and manage the known-clients registry (worker side)",
+    )
+    clients_sub = p.add_subparsers(dest="clients_action")
+    clients_sub.add_parser("list", help="List all known clients")
+    show = clients_sub.add_parser("show", help="Show details for one client")
+    show.add_argument("client_id", help="Client id to show")
+    rev = clients_sub.add_parser("revoke", help="Revoke a client")
+    rev.add_argument("client_id", help="Client id to revoke")
+    appr = clients_sub.add_parser("approve", help="Un-revoke a client")
+    appr.add_argument("client_id", help="Client id to un-revoke")
+
+
 _COMMAND_HANDLERS: dict[str, Callable[[argparse.Namespace], None]] = {
     "worker": _cmd_worker,
     "run": _cmd_run,
@@ -758,6 +862,7 @@ _COMMAND_HANDLERS: dict[str, Callable[[argparse.Namespace], None]] = {
     "sandbox": _cmd_sandbox,
     "pair": _dispatch_pair,
     "token": _cmd_token,
+    "clients": _cmd_clients,
 }