sentinelworks 0.1.0__tar.gz

sentinelworks-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# generated (LLD 2, 4)
+contracts/gen/
+contracts/.build/
+go/pkg/contracts/
+sdk/python/src/sentinelworks/_gen/
+jobs/_gen/
+sdk/python/src/sentinelworks/assets/
+sdk/python/src/sentinelworks/adapters/*/declarations/*.json
+console/src/api/gen/
+# build output
+/bin/
+/dist/
+console/dist/
+# tool caches
+.venv/
+node_modules/
+__pycache__/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.benchmarks/
+# Terraform (commit .terraform.lock.hcl)
+.terraform/
+*.tfstate
+*.tfstate.*
+*.tfplan
+# secrets and local settings
+.env
+.env.*
+.claude/settings.local.json*
+# Terraform crash logs (WP-02 3)
+infra/**/crash.log
+# Offline policy render of infra/bootstrap (WP-02 12.5): generated by make -C infra tf-test
+infra/bootstrap/tests/render/out/
+
+# Image digests written by the pipeline (WP-06 3, WP-21)
+infra/envs/**/images.auto.tfvars.json
+# Shared modules carry no lock file (WP-06 7.2); terraform test creates one locally
+infra/modules/*/.terraform.lock.hcl
+# contracts test report (WP-03 11)
+contracts/tests/report/
+workers/indexer/spike/results/
+images.auto.tfvars.json
+control/control-api/internal/compliance/controls.embedded.yaml
+
+# Generated by tools/policy/export_job_assets.py (WP-45 7.3)
+jobs/rule_learner/assets/*
+!jobs/rule_learner/assets/.gitkeep

sentinelworks-0.1.0/NOTICE

@@ -0,0 +1,3 @@
+sentinelworks includes a generated copy of the Public Suffix List
+(src/sentinelworks/enrich/_psl_data.py), from https://publicsuffix.org/list/public_suffix_list.dat
+That list is subject to the Mozilla Public License, v. 2.0: https://mozilla.org/MPL/2.0/

sentinelworks-0.1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.5
+Name: sentinelworks
+Version: 0.1.0
+License-File: NOTICE
+Requires-Python: <3.14,>=3.10
+Requires-Dist: cryptography
+Requires-Dist: google-re2
+Requires-Dist: httpx
+Requires-Dist: msgspec
+Requires-Dist: orjson
+Requires-Dist: wasmtime==50.0.1
+Requires-Dist: zstandard
+Provides-Extra: aws
+Requires-Dist: botocore; extra == 'aws'
+Provides-Extra: crewai
+Requires-Dist: crewai<1.16,>=1.15.29; extra == 'crewai'
+Provides-Extra: langchain
+Requires-Dist: langchain<1.5,>=1.3.9; extra == 'langchain'
+Requires-Dist: langgraph-sdk>=0.4.4; extra == 'langchain'
+Requires-Dist: langgraph<1.3,>=1.2; extra == 'langchain'
+Provides-Extra: spiffe
+Requires-Dist: spiffe; extra == 'spiffe'

sentinelworks-0.1.0/docs/ask-resume.md

@@ -0,0 +1,25 @@
+# ASK and resume
+
+An ASK verdict pauses the run. The adapter raises a framework interrupt with this payload:
+
+```json
+{"request_id": "...", "tool": "...", "approver_class": "OPERATOR", "expires_at": "...", "kid": "...", "mac": "..."}
+```
+
+To resume, send the payload back with the decision, under the key `sentinel`:
+
+```json
+{"sentinel": {"request_id": "...", "tool": "...", "approver_class": "OPERATOR", "expires_at": "...", "kid": "...", "mac": "...", "decision": "APPROVE", "approver_token": "..."}}
+```
+
+The process that resumes need not be the one that paused: it verifies `kid` and `mac` itself. The request id depends on the thread, the call id and the arguments, not on the instance, so replicas agree.
+
+Rules:
+
+- A resume is single use. A second resume of the same value is ignored.
+- `decision` is `APPROVE` or `REJECT`. A reject denies the call and needs no approver token.
+- A resume after `expires_at` is denied.
+- The policy runs again on resume, and the stricter verdict wins.
+- An approver token must satisfy the rule's approver class. A token of a lower class leaves the run waiting.
+
+Residual risk: an approver token is bound to one request id, so a replayed token fails for any other request. A checkpoint restored to before a resume can present the same request again; the capsule's `asks_done` list is what stops it, so a rewound capsule is the case to watch.

sentinelworks-0.1.0/docs/compat.md

@@ -0,0 +1,38 @@
+# Supported framework versions
+
+| Framework | Versions | Conformance | ASK |
+|---|---|---|---|
+| LangChain | `>=1.3.9,<1.5` with LangGraph `>=1.2,<1.3` | TESTED | yes, with a durable checkpointer |
+| CrewAI | `>=1.15.29,<1.16` | TESTED | no: an ASK verdict is a DENY |
+
+**LangChain 1.5 (pending V-04).** On 2026-11-13 the LangChain conformance suite, the V-04 ASK tests, the adapter unit tests and the canary passed on `langchain` 1.5.0, `langchain-core` 1.8.0 and `langgraph` 1.2.21 with the range widened to `<1.6`. The range stays `<1.5` until the owner records V-04 for 1.5.
+
+A weekly job runs the conformance suite against the newest releases and opens an issue labelled `sdk-compat` on a failure. It never blocks a release. A person then decides V-04 (LangChain) or V-06 (CrewAI) for the new version.
+
+If ASK fails on one framework version, remove `ASK` from that version's declaration. The runtime then answers DENY with `ADAPTER_CAPABILITY` for ASK verdicts on that version, which is the stricter outcome.
+
+## CrewAI
+
+Facts below were read from CrewAI 1.15 and are checked by the V-06 suite (`tests/conformance/v06`).
+
+| Item | Outcome |
+|---|---|
+| Lowest version | 1.15.29, the first that passes the whole suite. Hook behaviour changed inside 1.15: on 1.15.4 a `HookAborted` before a model call arrives as a `ValueError`, so `PolicyError` would be lost |
+| Tool block | `HOOK_BLOCK_THEN_RESULT`: the hook stops the call, and the after-tool hook's return value is what the agent reads |
+| Capsule | `FLOW_STATE` in a persisted flow whose state derives from `SentinelFlowState`; `RUN_SCOPED` otherwise |
+| ASK | absent. A tool hook cannot pause: CrewAI swallows the exception and runs the tool (V06-09) |
+| Streaming windows | absent |
+
+**Failures.** CrewAI swallows an ordinary exception from a hook and goes ahead with the call. The adapter catches everything in its hooks and blocks instead. An application's own hook is not covered by this.
+
+**Process-wide hooks.** Hooks cover every crew in the process, instrumented or not, so all of them share one `agent_id`. The manifest lists each crew seen. A crew that was not instrumented has no kickoff callbacks, so it gets Pre-LLM to Post-Tool decisions but no Prompt Submit or Agent Response.
+
+**After a deny.** A denied run makes no model call: each agent answers from a local stand-in, and the real model is put back when the run ends. An agent the swap cannot reach, such as a hierarchical crew's manager or a `kickoff_for_each` copy, stops the run with `PolicyError` instead.
+
+**`kickoff_for_each`.** Each item is its own run on its own thread id, so per-thread ledger counters do not add up across items.
+
+**A kickoff that raises.** CrewAI skips the after-kickoff callbacks, so if something outside Sentinel raises during a run, that run has no Task End or Agent Response record, and a task description that was masked stays masked.
+
+**chromadb.** `sentinelworks[crewai]` installs `chromadb` 1.5.9, because CrewAI requires it and does not import without it. That version has known advisories with no fix yet, including a pre-auth code injection (CVE-2026-45829, CVE-2026-45830, CVE-2026-45831, CVE-2026-45833). They read as flaws in the ChromaDB server, and CrewAI embeds it as a library, so do not run a ChromaDB server from this environment or expose one to a network. The base `sentinelworks` install does not include it.
+
+**Telemetry.** CrewAI sends its own telemetry by default. Set `CREWAI_DISABLE_TELEMETRY=true`, `OTEL_SDK_DISABLED=true` and `CREWAI_TRACING_ENABLED=false` to turn it off. Sentinel does not change this for you.

sentinelworks-0.1.0/docs/credentials.md

@@ -0,0 +1,39 @@
+# Workload credentials
+
+`SENTINEL_CREDENTIAL=auto` takes the first provider that is available, in this order: enrollment token, Kubernetes token file, SPIFFE, AWS, GCP, Azure, OIDC file. Set a name to use one provider only. A named provider that is not available keeps retrying with backoff.
+
+The SDK makes one attempt per call. Tokens, paths and URLs never appear in logs or errors.
+
+## Kubernetes
+
+Project a service-account token to `SENTINEL_K8S_TOKEN_PATH` (default `/var/run/secrets/sentinel/token`). The file is read on every renewal, so a rotated token is picked up.
+
+## AWS
+
+Install `sentinelworks[aws]`. The workload needs an IAM role: ECS or EKS pod identity, IRSA, EC2 instance metadata, or session credentials. Long-lived user keys are not offered, because the cell accepts roles only.
+
+The SDK signs an STS `GetCallerIdentity` request for `us-east-1`, wherever the workload runs. The host clock must be within 5 minutes of true time.
+
+## GCP
+
+No extra package. The SDK asks the metadata server for an identity token with `format=full`, and the audience is the cell URL.
+
+## Azure
+
+No extra package. The SDK uses IMDS, or the App Service endpoint when `IDENTITY_ENDPOINT` and `IDENTITY_HEADER` are set. Set `AZURE_CLIENT_ID` for a user-assigned identity.
+
+Register the cell URL as an application identifier URI in your Entra directory. The `resource` of the token request must equal it.
+
+## SPIFFE
+
+Install `sentinelworks[spiffe]` to use the Workload API through `SPIFFE_ENDPOINT_SOCKET`. Or have a helper write a JWT-SVID to `SENTINEL_SPIFFE_JWT_PATH`, which needs no package; the helper then sets the audience.
+
+## OIDC
+
+Point `SENTINEL_OIDC_TOKEN_PATH` at a token file. The file is read on every renewal. The audience is the one your platform put in the token, and the cell checks it.
+
+## Hosts without workload identity
+
+A one-time enrollment token is single use. The instance that uses it then renews by key possession, but only while the process lives: a restarted process needs a new token, and a reused one gets `403 enrollment_token_unknown`. Platforms that restart or sleep instances, and give them no workload identity (free Render or Hugging Face instances, for example), therefore need a fresh token for every start. Your deployment would have to mint one through the control API before the process starts, and these platforms have no step for that.
+
+Until there is a supported method for such hosts, run the agent where it has a workload identity: Kubernetes, AWS, GCP, Azure, SPIFFE or an OIDC token file. `SENTINEL_OUTBOX_DIR` on a temporary filesystem loses records that were not uploaded before a restart. The cell then has a gap in the evidence for that instance.

sentinelworks-0.1.0/docs/langchain.md

@@ -0,0 +1,127 @@
+# LangChain adapter
+
+## 0. Get the SDK
+
+The distribution and the import package are both `sentinelworks`. Install only that name. `sentinel-sdk` on public PyPI is an unrelated project.
+
+- From PyPI, once the first release is published: `pip install "sentinelworks[langchain]"`.
+- Before that, use the wheel from an `sdk-release` run, which your Sentinelworks contact sends you: `pip install "sentinelworks[langchain] @ file:///path/to/sentinelworks-<version>-py3-none-any.whl"`.
+
+A `git+https://` install of the repository does not work, because the wheel carries generated code and assets that are not in git.
+
+## 1. Configure and start
+
+Set these in the deployment's environment, not in code:
+
+| Variable | Value |
+|---|---|
+| `SENTINEL_AGENT_ID` | The agent_id you registered in the console, such as `demo/support-agent` |
+| `SENTINEL_CELL_URL` | The edge URL of your cell (`https://`) |
+| `SENTINEL_ENROLLMENT_TOKEN` | Only for the one-time token method: the token from the console |
+| `SENTINEL_OUTBOX_DIR` | A writable directory for records waiting to upload |
+
+`sentinelworks.init(cell_url=..., agent_id=...)` takes the same two values as arguments, and an argument wins over the environment variable. `init()` raises `ConfigError` when either value is missing or malformed. The cell refuses to enroll an instance whose agent_id is not registered or does not match its binding or enrollment token, so use exactly the agent_id shown in the console.
+
+A complete, runnable setup:
+
+```python
+import sentinelworks
+from langchain.agents import create_agent
+from langgraph.checkpoint.postgres import PostgresSaver
+from sentinelworks.langchain import SentinelMiddleware
+
+sentinelworks.init()  # once per process, before building the agent
+
+with PostgresSaver.from_conn_string(DB_URL) as saver:
+    saver.setup()
+    agent = create_agent(
+        model,
+        tools,
+        middleware=[SentinelMiddleware()],  # last in the list
+        checkpointer=saver,
+    )
+    result = agent.invoke(
+        {"messages": [{"role": "user", "content": "hi"}]}, {"configurable": {"thread_id": "t-1"}}
+    )
+```
+
+Put `SentinelMiddleware()` last in the list. It is then innermost on model and tool calls, so it sees the arguments after every other middleware has rewritten them.
+
+### Constructor arguments
+
+`SentinelMiddleware()` takes keyword arguments only. It has no `agent_id` argument: the agent_id comes from `init()`.
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `checkpointer` | detected | The agent's checkpointer, when the middleware cannot find it on its own |
+| `retriever_tools` | `()` | Names of tools whose output is retrieved content (RAG); `create_retriever_tool` tools are detected |
+| `delegation_tools` | `()` | Names of tools that hand work to another agent |
+| `agent_name` | `None` | A label for this agent within the process, reported in the manifest |
+
+It raises `NotInitialisedError` when `init()` has not run.
+
+## Supported versions
+
+The tested range is LangChain `>=1.3.9,<1.5` with LangGraph `>=1.2,<1.3`, and the `[langchain]` extra caps it, so `pip install "sentinelworks[langchain]"` resolves a tested version. An application that pins `langchain==1.5.0` gets a resolver conflict. If you force a newer version anyway, it loads as `UNTESTED`: the SDK logs the warning `adapter.untested_version`, ASK is off (an ASK verdict becomes a denial), and the manifest shows it. Support for LangChain 1.5 is pending a V-04 decision; see [compat](compat.md).
+
+## What your application sees
+
+| Outcome | Result |
+|---|---|
+| Allowed | The normal result |
+| Denied at Session Start or Prompt Submit | `invoke` returns normally, and the last message is the refusal text |
+| Denied at Pre-LLM or Post-LLM | `sentinelworks.PolicyError` is raised from `invoke` or `stream` |
+| Denied at Pre-Tool | The model receives a structured refusal as the tool result, and the run goes on unless the policy ended it |
+| Denied at Agent Response | The last message is the safe-response text |
+
+## Tools
+
+Use these helpers when the manifest needs more than LangChain knows:
+
+```python
+from sentinelworks.langchain import declare_tool, tag_mcp_tools
+
+declare_tool(refund, action_class="TRANSFER_VALUE", value_arg="amount", subject_arg="customer_id")
+tools = tag_mcp_tools(await client.get_tools(), "crm")
+```
+
+`declare_tool` is a hint for the manifest. The admin catalog still decides how a tool is treated. An untagged MCP tool gets the server ID `unknown`.
+
+Retriever tools from `create_retriever_tool` are detected. For other retrievers or for delegation tools, pass the names: `SentinelMiddleware(retriever_tools=["kb"], delegation_tools=["helper"])`.
+
+## Capsule
+
+The middleware adds a `sentinel_capsule` field to the agent state, and your checkpointer stores it with the thread. This needs a `thread_id` and a checkpointer the middleware can see. If it cannot detect yours, pass it: `SentinelMiddleware(checkpointer=saver)`. Without one, the agent runs run-scoped, with no capsule and no ASK.
+
+## ASK
+
+ASK works on a tested LangChain version with a durable checkpointer: `PostgresSaver`, `AsyncPostgresSaver`, `SqliteSaver` or `AsyncSqliteSaver`. With `InMemorySaver`, with no checkpointer, or on an `UNTESTED` version, an ASK verdict becomes a denial (fallback `ADAPTER_CAPABILITY`). The agent's human channel must not be `NONE`. An ASK appears as a LangGraph interrupt:
+
+```python
+from langgraph.types import Command
+
+result = agent.invoke(inputs, config)
+payload = result["__interrupt__"][0].value["sentinel"]
+agent.invoke(
+    Command(resume={"sentinel": {**payload, "decision": "APPROVE", "approver_token": token}}),
+    config,
+)
+```
+
+Send the payload back unchanged. `decision` is `APPROVE` or `REJECT`. An operator rule needs a verified `approver_token`.
+
+## Other middleware
+
+- **Order.** Keep `SentinelMiddleware()` last, after `PIIMiddleware`, call limits, `@dynamic_prompt` and `HumanInTheLoopMiddleware`. Sentinel then decides on what the model and tools actually receive.
+- **Human-in-the-loop.** LangChain's `HumanInTheLoopMiddleware` and Sentinel's ASK are separate interrupts. Sentinel's carries a `sentinel` key in its value, so tell them apart by that key. Answer each interrupt with its own resume. Running both in the same turn is not covered by the conformance suite yet. Test it in your app before relying on it.
+- **Streaming.** `agent.stream(...)` and `astream` are covered, with the limits below.
+
+## Limitations
+
+- **Streaming.** Agent Response runs on each sentence window before its text is released. Text already released stays with the application when a later window is denied.
+- **Split secrets.** Each window is scanned on its own, so a secret split across two windows is not found here. The cell's leak scanner is the backstop.
+- **Structured output.** It is not streamed through the window check. The complete message is checked at the end of the run.
+- **Python 3.10 with async.** asyncio tasks carry no context on 3.10, so hooks cannot read the `thread_id`. Async runs there are run-scoped: decisions still apply, but there is no capsule and no ASK. LangGraph also streams no async tokens there, so the complete answer is checked at the end of the run. Use Python 3.11 or later for async agents.
+- **Middleware order.** The manifest lists Sentinel's hooks, not its position among other middleware, because a middleware cannot see the others.
+- **Session End.** LangChain has no signal for a closed thread, so Session End fires when a thread has been idle for 30 minutes.
+- **Hosts without workload identity** (free Render or Hugging Face instances, for example). See [credentials](credentials.md#hosts-without-workload-identity).

sentinelworks-0.1.0/docs/shutdown.md

@@ -0,0 +1,34 @@
+# Shutdown
+
+`sentinelworks.init()` installs a `SIGTERM` handler and registers an `atexit` hook. Both drain the outbox, so decision records written before an orderly exit reach the cell.
+
+## What happens on SIGTERM
+
+1. The runtime enters `DRAINING` and refuses new runs.
+2. The SDK uploads what is queued. It uses up to 20 seconds in total.
+3. It appends a `SHUTDOWN` record with the number of records acknowledged during the drain and the number left, then uploads that too.
+4. It releases the outbox lock. An instance directory with nothing left in it is deleted.
+5. It calls the handler your application had installed before `init()`. If there was none, it re-raises the default action, so the process ends with the usual `SIGTERM` status.
+
+Set your platform's termination grace period above 20 seconds. In Kubernetes, keep `terminationGracePeriodSeconds` at 30 or more.
+
+## Chaining with your own handler
+
+Install your handler before you call `sentinelworks.init()`. The SDK remembers it and calls it after the drain. A handler installed after `init()` replaces the SDK's handler, so call `sentinelworks.shutdown()` from it yourself.
+
+## Without a main thread
+
+Python allows signal handlers only on the main thread. If `init()` runs on another thread, the SDK installs no handler and relies on `atexit`. `atexit` does not run on an unhandled `SIGTERM`, so in that case handle the signal yourself and call `sentinelworks.shutdown()`.
+
+## What can be lost
+
+| Event | File mode (`SENTINEL_OUTBOX_DIR` set) | Memory mode |
+|---|---|---|
+| Orderly exit, drain finished | Nothing | Nothing |
+| Grace period runs out | Nothing: the next process recovers the directory | Records not yet acknowledged are lost; the indexer records a gap |
+| `SIGKILL` or a process crash | Nothing the operating system has received; a torn last line is skipped | The queue is lost; the indexer records a gap |
+| Power loss or an OS crash | Records still in the page cache, because the outbox does not `fsync` | The queue is lost; the indexer records a gap |
+
+The next process recovers a directory only if its `agent_id` matches and no live process holds the lock. It uploads those records with `recovery.instance_id` and then deletes the directory.
+
+An instance that has been revoked, or that never got a token, does not upload during a drain. In file mode its records stay on disk.

sentinelworks-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sentinelworks"
+dynamic = ["version"]
+license-files = ["NOTICE"]
+requires-python = ">=3.10,<3.14"          # LLD 17
+dependencies = ["msgspec", "httpx", "zstandard", "cryptography", "google-re2", "orjson", "wasmtime==50.0.1"]  # LLD 17; uv.lock pins; wasmtime is the V-02 version (docs/adr/V-02/decision.json)
+[project.optional-dependencies]
+langchain = ["langchain>=1.3.9,<1.5", "langgraph>=1.2,<1.3", "langgraph-sdk>=0.4.4"]     # conformance-tested range. LLD 18 says <1.2; every release below 1.3.9 and langgraph-sdk below 0.4.4 carries a known advisory (PYSEC-2026-2192, PYSEC-2026-4240), and scan.sh gives the SDK no exceptions
+crewai = ["crewai>=1.15.29,<1.16"]     # WP-26, V-06: the first release that passes the whole V-06 and conformance suite
+aws = ["botocore"]
+spiffe = ["spiffe"]
+
+[dependency-groups]
+dev = ["botocore", "crewai>=1.15.29,<1.16", "pytest<9.2", "pytest-benchmark", "mypy", "hypothesis", "jsonschema", "pyyaml", "langchain>=1.3.9,<1.5", "langgraph>=1.2,<1.3", "langgraph-sdk>=0.4.4", "langgraph-checkpoint-sqlite", "langgraph-checkpoint-postgres", "psycopg[binary]>=3"]   # pytest-benchmark 5.3.0 on pytest 9.2.0: AttributeError: 'Function' object has no attribute '_nodeid'. Remove when pytest-benchmark supports pytest 9.2
+
+[tool.hatch.version]
+path = "src/sentinelworks/__about__.py"          # semver: the manifest and event contracts require it
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sentinelworks"]
+artifacts = ["src/sentinelworks/_gen", "src/sentinelworks/assets", "src/sentinelworks/adapters/*/declarations/*.json"]   # generated and gitignored, but must be in the wheel
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py", "bench_*.py"]
+python_functions = ["test_*", "bench_*"]
+pythonpath = ["."]
+addopts = "--strict-markers"
+markers = ["integration", "awsdev", "bench", "deployed", "canary", "conformance", "slow"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+
+[[tool.mypy.overrides]]
+module = ["sentinelworks._gen.*", "_gen.*"]
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = ["re2", "yaml", "jsonschema", "botocore.*", "spiffe.*", "spiffe"]
+ignore_missing_imports = true

sentinelworks-0.1.0/src/sentinelworks/__about__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sentinelworks-0.1.0/src/sentinelworks/__init__.py

@@ -0,0 +1,7 @@
+"""Sentinel Framework SDK and Sentinel Runtime (LLD 17)."""
+
+from sentinelworks.__about__ import __version__
+from sentinelworks.api import init, set_principal, shutdown, status
+from sentinelworks.errors import PolicyError
+
+__all__ = ["PolicyError", "__version__", "init", "set_principal", "shutdown", "status"]

sentinelworks-0.1.0/src/sentinelworks/_b64.py

@@ -0,0 +1,26 @@
+"""base64url without padding, strict on decode, and the lowercase base32 helper."""
+
+from __future__ import annotations
+
+import base64
+import re
+
+_B64URL = re.compile(r"^[A-Za-z0-9_-]*$")
+
+
+def b64u_encode(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def b64u_decode(text: str) -> bytes:
+    """Decode strictly: no padding, the URL alphabet only, canonical trailing bits."""
+    if not _B64URL.fullmatch(text) or len(text) % 4 == 1:
+        raise ValueError("bad base64url")
+    data = base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+    if b64u_encode(data) != text:
+        raise ValueError("bad base64url")
+    return data
+
+
+def b32_lower_nopad(data: bytes) -> str:
+    return base64.b32encode(data).rstrip(b"=").decode("ascii").lower()

sentinelworks-0.1.0/src/sentinelworks/_claims.py

@@ -0,0 +1,46 @@
+"""Access token claims, decoded without trust, for binding checks only (WP-10 4.5.5).
+
+Outside transport/ so the no-I/O runtime can read them (lint rule SIO005).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from sentinelworks._b64 import b64u_decode
+
+
+@dataclass(frozen=True, slots=True)
+class AccessClaims:
+    tenant: str
+    agent_id: str
+    env: str
+    kind: str
+    sub: str
+    exp: int
+    pending: bool
+    cell: str | None
+    cnf_jkt: str | None = None  # the key the token is bound to (WP-12 5.11)
+
+
+def decode_access_claims(access_token: str) -> AccessClaims:
+    """Base64url decode of the middle part. Raises ValueError."""
+    parts = access_token.split(".")
+    if len(parts) != 3:
+        raise ValueError("not a compact token")
+    try:
+        claims = json.loads(b64u_decode(parts[1]))
+        return AccessClaims(
+            tenant=claims["tenant"],
+            agent_id=claims["agent_id"],
+            env=claims["env"],
+            kind=claims.get("kind", "APPLICATION"),
+            sub=claims["sub"],
+            exp=int(claims["exp"]),
+            pending=bool(claims.get("pending", False)),
+            cell=claims.get("cell"),
+            cnf_jkt=(claims.get("cnf") or {}).get("jkt"),
+        )
+    except (AttributeError, KeyError, TypeError) as exc:
+        raise ValueError("bad claims") from exc

sentinelworks-0.1.0/src/sentinelworks/_clock.py

@@ -0,0 +1,49 @@
+"""Cell time and monotonic-adjusted host time (WP-10 5.21)."""
+
+from __future__ import annotations
+
+import threading
+import time
+from datetime import datetime, timezone
+
+_BASE_WALL = time.time()
+_BASE_MONO = time.monotonic()
+
+
+def format_rfc3339_ms(epoch_s: float) -> str:
+    moment = datetime.fromtimestamp(round(epoch_s, 3), tz=timezone.utc)
+    return moment.strftime("%Y-%m-%dT%H:%M:%S.") + f"{moment.microsecond // 1000:03d}Z"
+
+
+def parse_rfc3339(text: str) -> float:
+    """Epoch seconds of an RFC 3339 UTC timestamp. Raises ValueError."""
+    return datetime.fromisoformat(text.replace("Z", "+00:00")).timestamp()
+
+
+def host_now_iso() -> str:
+    return format_rfc3339_ms(_BASE_WALL + (time.monotonic() - _BASE_MONO))
+
+
+class CellClock:
+    """Expiry checks use this, never the host wall clock."""
+
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._server_s: float | None = None
+        self._mono_at_sync = 0.0
+
+    def now(self) -> float:
+        server = self._server_s
+        if server is None:
+            return time.time()
+        return server + (time.monotonic() - self._mono_at_sync)
+
+    def now_s(self) -> float:
+        return self.now()
+
+    def update(self, server_time_s: float) -> None:
+        """WP-12 calls this with the verified sync state `iat`. Lower values are ignored."""
+        with self._lock:
+            if self._server_s is None or server_time_s >= self._server_s:
+                self._server_s = server_time_s
+                self._mono_at_sync = time.monotonic()