chitmark 0.6.2__tar.gz → 0.6.3__tar.gz

{chitmark-0.6.2 → chitmark-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: chitmark
-Version: 0.6.2
+Version: 0.6.3
 Summary: Official Python SDK for Chitmark by Open Agent Ledger: trust decisions on agent-mediated actions (verify, feedback, challenge)
 Project-URL: Homepage, https://chitmark.com
 Project-URL: Documentation, https://chitmark.com/docs
@@ -80,7 +80,14 @@ with Chitmark(api_key="ck_live_...") as client:
 | `client.feedback(...)`  | `POST /v1/feedback`  | Learn    |
 | `client.challenge(...)` | `POST /v1/challenge` | Escalate |
 
-Timeouts and transport errors return a degraded challenge verdict and never raise on `verify`. HTTP errors raise `ChitmarkApiError` with the status attached. Set `on_degraded` to `challenge`, never allow on degraded.
+Store-outage degradation on verify is HTTP 200 with a Verdict
+(``degraded: True``); the client deserializes it like any other Verdict.
+Verify never returns HTTP 503. Timeouts and transport errors synthesize a
+local degraded challenge Verdict and never raise on ``verify``. HTTP 4xx /
+429 Error responses raise ``ChitmarkApiError``. Set ``on_degraded`` to
+``challenge``, never allow on degraded.
+
+Use `is_eligible_allow(verdict)` before any protected action: only an explicit non-degraded `allow` is eligible. Unknown or malformed decisions fail closed.
 
 ### Report outcomes
 
@@ -95,12 +102,12 @@ db.accounts.update(user_id, chitmark_event_id=verdict["eventId"])
 client.feedback(
     event_id=account.chitmark_event_id,  # the stored join key
     outcome="credit_burn",
-    value=87.4,  # dollar amount: unit rides along (default "usd")
+    value=87.4,  # measured magnitude: unit rides along (default "usd"; also "credits" | "count")
     observed_at="2026-08-06T04:00:00Z",
 )
 ```
 
-Exact duplicate feedback bodies derive the same warehouse id, so retrying a connector never double-counts a burned value. `unit` ships only alongside `value`.
+Exact duplicate feedback bodies derive the same warehouse id (`eventId` + `outcome` + `value` + `unit` + `observedAt`), so retrying a connector with a stable business timestamp never double-counts a burned value. Prefer an idempotency key; omitting `observedAt` uses server time. `unit` ships only alongside `value`.
 
 ### Handle a challenge
 
@@ -129,12 +136,12 @@ if instructions["type"] == "pow":
         session="sess_9f3a",
         proof={"type": "proof_of_work", "nonce": str(nonce)},
     )
-    # Re-verify with context={"challengeId": ...} so the next verdict honors it.
+    # Re-verify with context={"challengeId": ...}; completion alone does not authorize.
 ```
 
 ### Verify the receipt
 
-Every production verdict ships a `verdictToken`: an ES256 JWT bound to session, origin, and event. Verify it before acting on high-value decisions (install the `verdict` extra for the crypto dependency):
+Every production verdict ships a `verdictToken`: an ES256 JWT bound to session, origin, and event. Verify authenticity, then authorize on the decision (install the `verdict` extra for the crypto dependency):
 
 ```python
 pip install "chitmark[verdict]"
@@ -145,13 +152,19 @@ from chitmark.verify_token import verify_verdict_token
 
 claims = verify_verdict_token(
     verdict["verdictToken"],
-    session="sess_9f3a",  # enforce session binding (recommended)
-    aud="api.chitmark.com",  # enforce origin binding
+    session="sess_9f3a",
+    tenant_id="org_acme",
 )
-# claims: {"eventId", "decision", "actorType", "confidence", "jti", "exp", ...}
+
+if claims["degraded"] or claims["decision"] != "allow":
+    raise ChallengeRequiredError()  # HTTP 428 / challenge response
+
+# Only now trust the allow.
 ```
 
-Rejects expired tokens, unknown keys, bad signatures, and session or origin mismatches with typed error codes.
+Rejects expired tokens, unknown keys, bad signatures, and session or origin mismatches with typed error codes. A verified token that is not a non-degraded `allow` must still fail closed.
+
+Cache JWKS using HTTP headers: respect `Cache-Control` (`max-age=60`), and when `ETag` or `Last-Modified` are present use conditional requests (`If-None-Match` / `If-Modified-Since`) instead of a hard-coded refresh interval. Refresh immediately on unknown `kid`. Do not fetch on every verification. Every signed JWT requires `kid`. Keys are EC P-256 for ES256: require JWT `alg === "ES256"` before verifying (`wrong_algorithm` otherwise); never trust the token-requested alg. Rotation overlaps old and new keys; the old key stays until tokens under it expire (keep ≥ 5 minutes + 60 seconds). An empty JWKS (`keys: []`) means verification is impossible: fail closed; never treat an empty set as proof a token is valid (local/CI may also emit `unsigned.<eventId>`). Pass a cached `jwks=` mapping into `verify_verdict_token` to skip the network call.
 
 ### PII modes
 

{chitmark-0.6.2 → chitmark-0.6.3}/README.md

@@ -46,7 +46,14 @@ with Chitmark(api_key="ck_live_...") as client:
 | `client.feedback(...)`  | `POST /v1/feedback`  | Learn    |
 | `client.challenge(...)` | `POST /v1/challenge` | Escalate |
 
-Timeouts and transport errors return a degraded challenge verdict and never raise on `verify`. HTTP errors raise `ChitmarkApiError` with the status attached. Set `on_degraded` to `challenge`, never allow on degraded.
+Store-outage degradation on verify is HTTP 200 with a Verdict
+(``degraded: True``); the client deserializes it like any other Verdict.
+Verify never returns HTTP 503. Timeouts and transport errors synthesize a
+local degraded challenge Verdict and never raise on ``verify``. HTTP 4xx /
+429 Error responses raise ``ChitmarkApiError``. Set ``on_degraded`` to
+``challenge``, never allow on degraded.
+
+Use `is_eligible_allow(verdict)` before any protected action: only an explicit non-degraded `allow` is eligible. Unknown or malformed decisions fail closed.
 
 ### Report outcomes
 
@@ -61,12 +68,12 @@ db.accounts.update(user_id, chitmark_event_id=verdict["eventId"])
 client.feedback(
     event_id=account.chitmark_event_id,  # the stored join key
     outcome="credit_burn",
-    value=87.4,  # dollar amount: unit rides along (default "usd")
+    value=87.4,  # measured magnitude: unit rides along (default "usd"; also "credits" | "count")
     observed_at="2026-08-06T04:00:00Z",
 )
 ```
 
-Exact duplicate feedback bodies derive the same warehouse id, so retrying a connector never double-counts a burned value. `unit` ships only alongside `value`.
+Exact duplicate feedback bodies derive the same warehouse id (`eventId` + `outcome` + `value` + `unit` + `observedAt`), so retrying a connector with a stable business timestamp never double-counts a burned value. Prefer an idempotency key; omitting `observedAt` uses server time. `unit` ships only alongside `value`.
 
 ### Handle a challenge
 
@@ -95,12 +102,12 @@ if instructions["type"] == "pow":
         session="sess_9f3a",
         proof={"type": "proof_of_work", "nonce": str(nonce)},
     )
-    # Re-verify with context={"challengeId": ...} so the next verdict honors it.
+    # Re-verify with context={"challengeId": ...}; completion alone does not authorize.
 ```
 
 ### Verify the receipt
 
-Every production verdict ships a `verdictToken`: an ES256 JWT bound to session, origin, and event. Verify it before acting on high-value decisions (install the `verdict` extra for the crypto dependency):
+Every production verdict ships a `verdictToken`: an ES256 JWT bound to session, origin, and event. Verify authenticity, then authorize on the decision (install the `verdict` extra for the crypto dependency):
 
 ```python
 pip install "chitmark[verdict]"
@@ -111,13 +118,19 @@ from chitmark.verify_token import verify_verdict_token
 
 claims = verify_verdict_token(
     verdict["verdictToken"],
-    session="sess_9f3a",  # enforce session binding (recommended)
-    aud="api.chitmark.com",  # enforce origin binding
+    session="sess_9f3a",
+    tenant_id="org_acme",
 )
-# claims: {"eventId", "decision", "actorType", "confidence", "jti", "exp", ...}
+
+if claims["degraded"] or claims["decision"] != "allow":
+    raise ChallengeRequiredError()  # HTTP 428 / challenge response
+
+# Only now trust the allow.
 ```
 
-Rejects expired tokens, unknown keys, bad signatures, and session or origin mismatches with typed error codes.
+Rejects expired tokens, unknown keys, bad signatures, and session or origin mismatches with typed error codes. A verified token that is not a non-degraded `allow` must still fail closed.
+
+Cache JWKS using HTTP headers: respect `Cache-Control` (`max-age=60`), and when `ETag` or `Last-Modified` are present use conditional requests (`If-None-Match` / `If-Modified-Since`) instead of a hard-coded refresh interval. Refresh immediately on unknown `kid`. Do not fetch on every verification. Every signed JWT requires `kid`. Keys are EC P-256 for ES256: require JWT `alg === "ES256"` before verifying (`wrong_algorithm` otherwise); never trust the token-requested alg. Rotation overlaps old and new keys; the old key stays until tokens under it expire (keep ≥ 5 minutes + 60 seconds). An empty JWKS (`keys: []`) means verification is impossible: fail closed; never treat an empty set as proof a token is valid (local/CI may also emit `unsigned.<eventId>`). Pass a cached `jwks=` mapping into `verify_verdict_token` to skip the network call.
 
 ### PII modes
 

{chitmark-0.6.2 → chitmark-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "chitmark"
-version = "0.6.2"
+version = "0.6.3"
 description = "Official Python SDK for Chitmark by Open Agent Ledger: trust decisions on agent-mediated actions (verify, feedback, challenge)"
 readme = "README.md"
 license = { text = "Proprietary: no open-source grant. Copyright (c) 2026 Open Agent Ledger. All rights reserved." }

{chitmark-0.6.2 → chitmark-0.6.3}/src/chitmark/__init__.py

@@ -4,7 +4,7 @@ Trust decisions on agent-mediated actions (verify, feedback, challenge),
 tuned by business outcomes.
 """
 
-from chitmark.client import SDK_VERSION, Chitmark
+from chitmark.client import SDK_VERSION, Chitmark, is_eligible_allow
 from chitmark.errors import ChitmarkApiError, ChitmarkError
 from chitmark.pii import hash_email_sha256, truncate_ip
 from chitmark.types import (
@@ -14,6 +14,7 @@ from chitmark.types import (
     Decision,
     DecisionCosts,
     FeedbackResponse,
+    FeedbackSource,
     Outcome,
     Principal,
     Subject,
@@ -35,6 +36,7 @@ __all__ = [
     "Decision",
     "DecisionCosts",
     "FeedbackResponse",
+    "FeedbackSource",
     "Outcome",
     "Principal",
     "Subject",
@@ -43,6 +45,7 @@ __all__ = [
     "VerdictTokenError",
     "VerifyContext",
     "hash_email_sha256",
+    "is_eligible_allow",
     "truncate_ip",
     "verify_verdict_token",
 ]

{chitmark-0.6.2 → chitmark-0.6.3}/src/chitmark/client.py

@@ -22,6 +22,8 @@ from chitmark.types import (
     ChitmarkEnv,
     Decision,
     FeedbackResponse,
+    FeedbackSource,
+    FeedbackUnit,
     OnDegraded,
     Outcome,
     PiiMode,
@@ -30,7 +32,7 @@ from chitmark.types import (
     VerifyContext,
 )
 
-__all__ = ["Chitmark", "DEFAULT_BASE_URLS", "SDK_VERSION"]
+__all__ = ["Chitmark", "DEFAULT_BASE_URLS", "SDK_VERSION", "is_eligible_allow"]
 
 SDK_VERSION = "0.6.0"
 
@@ -66,6 +68,15 @@ def _enforce_degraded_never_allow(verdict: Verdict) -> Verdict:
     return verdict
 
 
+def is_eligible_allow(verdict: Mapping[str, Any] | Verdict) -> bool:
+    """True only for an explicit non-degraded allow.
+
+    Use this before any protected action so unknown or malformed decisions
+    cannot fall through. Fail closed: anything else is ineligible.
+    """
+    return verdict.get("decision") == "allow" and not verdict.get("degraded")
+
+
 def _is_well_formed_verdict(value: Any) -> bool:
     """Minimal shape guard for a 200 verify response.
 
@@ -204,13 +215,26 @@ class Chitmark:
         context: VerifyContext | Mapping[str, Any] | None = None,
         idempotency_key: str | None = None,
     ) -> Verdict:
-        """Score + route an inbound action. Degrades to challenge on timeout/transport.
+        """Score + route an inbound action.
+
+        Store-outage degradation arrives as HTTP 200 with a Verdict body
+        (``degraded: True``, ``decision: "challenge"``). The client
+        deserializes that like any other Verdict. Verify never returns
+        HTTP 503.
+
+        HTTP 4xx / 429 Error responses raise ``ChitmarkApiError``. Transport
+        timeout / network failure synthesizes a local degraded challenge
+        Verdict (never allow).
+
+        ``session`` is a binding id you supply (prefer high-entropy,
+        server-generated); it binds challenge and ``verdictToken``.
 
         ``context`` carries per-request policy flags: ``challengeId``
         (honor a cleared challenge once), ``challengePolicy``
         ("default" | "confirmed_tail_only"), and ``decisionCosts``
-        (falseAllow/falseChallenge/falseDeny: repositions the
-        allow/challenge/deny boundaries, defaults 1:1:3).
+        (relative, dimensionless weights for falseAllow / falseChallenge /
+        falseDeny: abusive allow, over-friction challenge on legitimate
+        traffic, legitimate deny; defaults 1:1:3).
         """
         body: dict[str, Any] = {
             "action": action,
@@ -249,15 +273,30 @@ class Chitmark:
         event_id: str,
         outcome: Outcome,
         value: float | None = None,
-        unit: str = "usd",
+        unit: FeedbackUnit = "usd",
+        source: FeedbackSource | None = None,
         observed_at: str | None = None,
         idempotency_key: str | None = None,
     ) -> FeedbackResponse:
         """Report a downstream outcome joined on eventId.
 
-        ``unit`` rides along only when ``value`` is present: a currency
-        without an amount is wire noise, and parity with the TypeScript SDK
-        means neither field is sent unless the caller set it.
+        Security invariant: feedback cannot create attribution. It only
+        attaches an outcome to an existing verify event for this tenant.
+        Unknown or cross-tenant ``event_id`` values return 404. Never invent
+        a join from email/IP.
+
+        Append-only (not latest-wins): multiple outcomes may attach to one
+        eventId. Exact duplicates share one feedbackId. Compatible labels
+        coexist; conflicting pairs quarantine the new observation without
+        deleting prior evidence. HTTP ``{ok: true}`` still acknowledges
+        quarantined ingest.
+
+        ``value`` is the measured economic magnitude for this outcome,
+        expressed in ``unit`` (``usd`` | ``credits`` | ``count``). ``unit``
+        rides along only when ``value`` is present. Different units are not
+        converted or comparable. ``source`` is optional provenance (billing,
+        usage_metering, trust_queue, manual_review, customer_system,
+        automated_detector) and is included in warehouse identity when set.
         ``idempotency_key`` is sent as both the ``Idempotency-Key`` header
         and body ``idempotencyKey`` so exact retries replay the original
         acknowledgement; a reused key with a different payload conflicts.
@@ -266,6 +305,8 @@ class Chitmark:
         if value is not None:
             body["value"] = value
             body["unit"] = unit
+        if source is not None:
+            body["source"] = source
         if observed_at is not None:
             body["observedAt"] = observed_at
         if idempotency_key is not None:
@@ -290,9 +331,11 @@ class Chitmark:
     ) -> ChallengeResponse:
         """Issue an asymmetric-cost challenge.
 
-        ``risk_tier`` scales the issued proof-of-work difficulty
-        so the challenge's economic tax rises with risk; completion is
-        always validated against the difficulty that was issued.
+        ``session`` is a binding id you supply (prefer high-entropy,
+        server-generated). ``risk_tier`` scales issued PoW difficulty
+        monotonically; difficulty is sealed in ``instructions`` and
+        completion validates that value only. ``prefer`` is ordered hints:
+        first issuable method wins.
         """
         body: dict[str, Any] = {"eventId": event_id, "session": session}
         if prefer is not None:
@@ -314,9 +357,10 @@ class Chitmark:
     ) -> ChallengeCompletionResponse:
         """Complete a challenge by submitting its solved proof.
 
-        Clears only the bound session, once (anti-replay). Re-verify with
-        ``context={"challengeId": challenge_id}`` so the next verify honors
-        the cleared session.
+        Clears only the bound session, once. Does not authorize the action:
+        re-verify with ``context={"challengeId": challenge_id}`` and proceed
+        only on non-degraded ``allow`` (honored clear sets
+        ``challengeCleared: True``).
         """
         body: dict[str, Any] = {
             "eventId": event_id,

{chitmark-0.6.2 → chitmark-0.6.3}/src/chitmark/types.py

@@ -19,6 +19,13 @@ Action = (
     ]
     | str
 )
+# Outcomes reported via feedback. Prefer fast labels first
+# (credit_burn, multi_account_cluster, abuse_confirmed).
+# false_positive: a previously attributed abuse signal on this eventId was
+# reviewed and determined not to represent abuse (T&S clear / overturn).
+# Conflicts with abuse-positive labels. Not "Chitmark challenged/denied a
+# legitimate user": that is context.decisionCosts.falseChallenge / falseDeny
+# on verify.
 Outcome = Literal[
     "credit_burn",
     "multi_account_cluster",
@@ -28,6 +35,18 @@ Outcome = Literal[
     "churned",
     "false_positive",
 ]
+# Scale for feedback value. Allowlist only (not free-form). Values in
+# different units are not converted or comparable.
+FeedbackUnit = Literal["usd", "credits", "count"]
+# Provenance of a feedback label: why you trusted this outcome.
+FeedbackSource = Literal[
+    "billing",
+    "usage_metering",
+    "trust_queue",
+    "manual_review",
+    "customer_system",
+    "automated_detector",
+]
 ChallengeMethod = Literal[
     "payment_preauth",
     "proof_of_work",
@@ -42,19 +61,49 @@ OnDegraded = Literal["challenge"]
 
 class PrincipalRequired(TypedDict):
     """Required principal fields from verify."""
+
     resolved: bool
     identityBasis: list[str]
 
 
 class Principal(PrincipalRequired, total=False):
-    """Principal resolution from verify."""
+    """Principal attribution: who is acting and on whose behalf.
+
+    Not an authorization credential. ``resolved is True`` is not "this is a
+    human", not an IdP login, and not permission to unlock an action. Gate
+    on ``decision`` (plus ``degraded`` / ``enforcementMode``).
+
+    - ``resolved``: usable principal signal (today: verified Web Bot Auth
+      operator signature and/or enrichment known-good).
+    - ``operator``: bot maker from Web Bot Auth Signature-Agent when the
+      operator channel verified; does not by itself prove ``onBehalfOf``.
+    - ``onBehalfOf``: principal the agent is acting for when known
+      (organization **or** end-user identifier). Often absent at the wedge.
+    - ``identityBasis``: contributing signal sources (mixed cryptographic
+      and inferred strength).
+    """
 
     operator: str
     onBehalfOf: str
 
-
 class Verdict(TypedDict):
-    """Verdict object: single source of truth for a verify call."""
+    """Verdict object: single source of truth for a verify call.
+
+    ``confidence`` is a model confidence measure for the returned decision
+    (0..1). It is not a calibrated probability of abuse, and not the
+    threshold ``decisionCosts`` moves. Gate on ``decision`` (plus
+    ``degraded`` / ``enforcementMode``); use confidence for ops triage and
+    dashboards, not as a substitute allow/deny cutoff.
+
+    ``reasons`` is ``list[str]`` display copy for ops today. Do not scrape
+    reason text as a stable machine API. A future additive revision may
+    expose structured ``{code, message, category}`` entries while keeping a
+    human-readable message.
+
+    Under ``enforcementMode == "log_only"``, ``verdictToken`` is a signed
+    observation receipt and does not authorize the action. Mode is on this
+    body (not a JWT claim today): gate only when mode is ``enforce``.
+    """
 
     decision: Decision
     actorType: ActorType
@@ -70,6 +119,7 @@ class Verdict(TypedDict):
 class VerdictTokenClaims(TypedDict, total=False):
     """Decoded verdictToken JWT payload (see SDK.md §6)."""
 
+    iss: str
     eventId: str
     decision: Decision
     actorType: ActorType
@@ -84,7 +134,13 @@ class VerdictTokenClaims(TypedDict, total=False):
 
 
 class VerdictWithChallenge(Verdict, total=False):
-    """Optional verdict additions for cleared challenges."""
+    """Optional verdict additions for cleared challenges.
+
+    ``challengeCleared: true`` means this verify honored
+    ``context.challengeId`` for the session. Guaranteed only with
+    ``decision: allow`` and ``degraded: false`` (clear short-circuits
+    scoring). Under ``log_only``, still observation-only.
+    """
 
     challengeCleared: bool
 
@@ -103,13 +159,22 @@ class Subject(TypedDict, total=False):
 
 
 class DecisionCosts(TypedDict, total=False):
-    """Cost ratio repositions the allow/challenge/deny boundaries.
+    """Relative, dimensionless weights for three error classes.
+
+    Not dollars and not score thresholds; only ratios matter. Repositions
+    the allow/challenge/deny boundaries for a single verify.
+
+    - ``falseAllow``: cost of allowing abusive traffic
+    - ``falseChallenge``: cost of challenging legitimate traffic when allow
+      would have been fine (a challenge can still be appropriate for
+      legitimate users; this names the over-friction case)
+    - ``falseDeny``: cost of denying legitimate traffic
 
     Higher ``falseAllow`` challenges earlier (abuse-averse); higher
     ``falseChallenge`` lets more of the gray zone through; higher
     ``falseDeny`` reserves deny for confirmed abuse. Defaults 1:1:3 keep
-    the fail-to-challenge semantics; missing/non-positive fields fall back
-    to their default.
+    fail-to-challenge semantics; missing/non-positive fields fall back to
+    their default.
     """
 
     falseAllow: float
@@ -122,15 +187,26 @@ class VerifyContext(TypedDict, total=False):
 
     Unknown keys are carried (not scored); ``decisionCosts`` repositions
     the allow/challenge/deny boundaries for this request.
+
+    ``logOnly`` is an integration-side control: set it in server code (or
+    rely on env/key log-only policy). Never derive it from client-provided
+    request data. The verdict reports the effective mode as
+    ``enforcementMode``.
     """
 
     challengeId: str
     challengePolicy: Literal["default", "confirmed_tail_only"]
+    logOnly: bool
     decisionCosts: DecisionCosts
 
 
 class VerifyParams(TypedDict, total=False):
-    """Parameters for Client.verify."""
+    """Parameters for Client.verify.
+
+    ``session`` is supplied by you: prefer a high-entropy, server-generated
+    id (binds challenge and verdictToken). Client-generated values are
+    attacker-influenced.
+    """
 
     idempotency_key: str
     action: Action
@@ -146,13 +222,18 @@ class FeedbackParams(TypedDict, total=False):
     event_id: str
     outcome: Outcome
     value: float
-    unit: str
+    unit: FeedbackUnit
+    source: FeedbackSource
     observed_at: str
     idempotency_key: str
 
 
 class ChallengeParams(TypedDict, total=False):
-    """Parameters for Client.challenge (issue mode)."""
+    """Parameters for Client.challenge (issue mode).
+
+    ``session`` is a binding id you supply (prefer high-entropy,
+    server-generated). Same value across issue, complete, and re-verify.
+    """
 
     event_id: str
     session: str

{chitmark-0.6.2 → chitmark-0.6.3}/src/chitmark/verify_token.py

@@ -1,13 +1,26 @@
 """Client-side verdictToken verification (MVP-016).
 
 A verdictToken is an ES256 JWT decision receipt minted by the edge and bound
-to session (``sub``), origin hint (``aud``), issuing tenant (``tid``), and
-``jti`` with a short ``exp``. This module validates shape, signature (against
-the JWKS served from ``GET /.well-known/jwks.json``), expiry, session
-binding, and, when expected values are supplied, tenant and origin binding.
-``aud`` reflects request headers and is attacker influenced: always verify
-``session`` and ``tenant_id``, never ``aud`` alone. Rejection reasons are
-surfaced as ``VerdictTokenError.code``.
+to session (``sub``), origin hint (``aud``), issuing tenant (``tid``), and a
+unique ``jti`` (correlation id) with a short ``exp`` (5 minutes). Every signed
+token requires a ``kid`` in the JWT header. Signature verification proves
+authenticity and integrity; it does not make the JWT single-use. This module
+always enforces ``session`` and ``tenant_id`` (security boundary), validates
+``iss`` against the Chitmark issuer, and optionally ``aud``. ``aud`` reflects
+request headers and is attacker influenced: never enforce ``aud`` alone.
+Rejection reasons are surfaced as ``VerdictTokenError.code``.
+
+JWKS: respect ``Cache-Control`` and, when present, ``ETag`` /
+``Last-Modified`` via conditional requests (instead of a hard-coded
+refresh interval). Refresh immediately on unknown ``kid``. Do not fetch on
+every verification; never permanently pin a single signing key. Each JWKS
+key is EC P-256 for ES256: require JWT ``alg == "ES256"`` before verifying
+(``wrong_algorithm`` otherwise); never trust the token-requested algorithm.
+Rotation overlaps old and new keys; the old key stays published until tokens under
+it expire (keep ≥ 5 minutes + 60 seconds). Pass a cached ``jwks`` mapping
+to skip the network call. An empty JWKS (``keys: []``) means no token can
+be cryptographically verified: fail closed; never treat an empty set as
+evidence that a token is valid (local/CI may emit ``unsigned.<eventId>``).
 
 Requires the optional extras ``PyJWT`` and ``cryptography``
 (``uv sync --extra verdict``).
@@ -42,14 +55,16 @@ class VerdictTokenError(ChitmarkError):
 
 DEFAULT_JWKS_URL = "https://api.chitmark.com/.well-known/jwks.json"
 DEFAULT_LEEWAY_SECONDS = 30
+VERDICT_TOKEN_ISSUER = "https://api.chitmark.com"
 
 
 def verify_verdict_token(
     token: str,
     *,
-    session: str | None = None,
-    tenant_id: str | None = None,
+    session: str,
+    tenant_id: str,
     aud: str | None = None,
+    issuer: str = VERDICT_TOKEN_ISSUER,
     jwks: Mapping[str, Any] | None = None,
     jwks_url: str = DEFAULT_JWKS_URL,
     http_client: httpx.Client | None = None,
@@ -59,10 +74,19 @@ def verify_verdict_token(
 
     Args:
         token: The ES256 JWT from a verify verdict.
-        session: Expected session; token ``sub`` must equal this.
-        tenant_id: Expected issuing tenant; token ``tid`` must equal this.
+        session: Expected session; token ``sub`` must equal this (required).
+        tenant_id: Expected issuing tenant; token ``tid`` must equal this
+            (required).
         aud: Expected origin hint; token ``aud`` must equal this when provided.
-        jwks: Pre-fetched JWKS mapping; skips the network fetch.
+        issuer: Expected ``iss``; defaults to ``https://api.chitmark.com``.
+        jwks: Pre-fetched/cached JWKS mapping; skips the network fetch.
+            Prefer caching via HTTP headers (``Cache-Control``, ``ETag``,
+            and ``Last-Modified`` when present) with conditional refresh
+            and immediate refresh on unknown ``kid``, rather than fetching
+            on every verification. Never permanently pin a single signing
+            key. Rotation overlaps old+new keys; keep the retiring key
+            until tokens under it expire (≥ 5 min TTL + 60s JWKS cache
+            skew).
         jwks_url: JWKS endpoint; defaults to the production API.
         http_client: Reusable ``httpx.Client`` for the JWKS fetch.
         leeway_seconds: Clock-skew tolerance.
@@ -71,8 +95,8 @@ def verify_verdict_token(
         VerdictTokenError: with a machine-readable ``code``:
             ``malformed_token``, ``wrong_algorithm``, ``wrong_type``,
             ``jwks_unavailable``, ``unknown_kid``, ``invalid_signature``,
-            ``expired``, ``not_yet_valid``, ``wrong_session``,
-            ``wrong_tenant``, or ``wrong_aud``.
+            ``expired``, ``not_yet_valid``, ``wrong_issuer``,
+            ``wrong_session``, ``wrong_tenant``, or ``wrong_aud``.
     """
     if pyjwt is None:  # pragma: no cover
         raise VerdictTokenError(
@@ -140,12 +164,17 @@ def verify_verdict_token(
             code="malformed_token",
         ) from None
 
-    if session is not None and claims.get("sub") != session:
+    if claims.get("iss") != issuer:
+        raise VerdictTokenError(
+            "verdictToken was not issued by Chitmark",
+            code="wrong_issuer",
+        )
+    if claims.get("sub") != session:
         raise VerdictTokenError(
             "verdictToken was minted for a different session",
             code="wrong_session",
         )
-    if tenant_id is not None and claims.get("tid") != tenant_id:
+    if claims.get("tid") != tenant_id:
         raise VerdictTokenError(
             "verdictToken was minted for a different tenant",
             code="wrong_tenant",

{chitmark-0.6.2 → chitmark-0.6.3}/tests/test_client.py

@@ -9,7 +9,11 @@ import pytest
 import respx
 
 from chitmark import Chitmark, ChitmarkError
-from chitmark.client import _degraded_challenge_verdict, _enforce_degraded_never_allow
+from chitmark.client import (
+    _degraded_challenge_verdict,
+    _enforce_degraded_never_allow,
+    is_eligible_allow,
+)
 from chitmark.pii import hash_email_sha256, truncate_ip
 from chitmark.types import Verdict
 
@@ -45,6 +49,27 @@ def test_degraded_never_allow() -> None:
     assert _enforce_degraded_never_allow(bad)["decision"] == "challenge"
 
 
+def test_is_eligible_allow() -> None:
+    allow: Verdict = {
+        "decision": "allow",
+        "actorType": "human",
+        "confidence": 0.9,
+        "reasons": ["ok"],
+        "principal": {"resolved": False, "identityBasis": []},
+        "verdictToken": "tok",
+        "eventId": "evt_ok",
+        "degraded": False,
+        "enforcementMode": "enforce",
+    }
+    assert is_eligible_allow(allow) is True
+
+    degraded_allow = {**allow, "degraded": True}
+    assert is_eligible_allow(degraded_allow) is False
+    assert is_eligible_allow({**allow, "decision": "challenge"}) is False
+    assert is_eligible_allow({**allow, "decision": "deny"}) is False
+    assert is_eligible_allow({**allow, "decision": "weird"}) is False  # type: ignore[typeddict-item]
+
+
 def test_requires_api_key() -> None:
     with pytest.raises(ChitmarkError, match="api_key"):
         Chitmark(api_key="")

{chitmark-0.6.2 → chitmark-0.6.3}/tests/test_client_extra.py

@@ -169,11 +169,13 @@ def test_feedback_sends_value_unit_and_observed_at() -> None:
             event_id="evt_x",
             outcome="credit_burn",
             value=4.2,
+            source="usage_metering",
             observed_at="2026-08-01T00:00:00Z",
         )
         sent = respx.calls[-1].request.content
         assert b'"value":4.2' in sent
         assert b'"unit":"usd"' in sent
+        assert b'"source":"usage_metering"' in sent
         assert b'"observedAt":"2026-08-01T00:00:00Z"' in sent
 
 

{chitmark-0.6.2 → chitmark-0.6.3}/tests/test_verify_token.py

@@ -92,6 +92,7 @@ def _mint(keys: dict, **overrides: object) -> str:
         "decision": "allow",
         "actorType": "human",
         "confidence": 0.56,
+        "iss": "https://api.chitmark.com",
         "aud": "https://app.acme.com",
         "sub": "sess_token_a",
         "tid": "org_unit",
@@ -114,12 +115,7 @@ def _jwks(keys: dict) -> dict:
 def test_accepts_valid_signed_token(keys: dict) -> None:
     token = _mint(keys, sub="sess_token_a", aud="https://app.acme.com")
 
-    claims = verify_verdict_token(
-        token,
-        session="sess_token_a",
-        aud="https://app.acme.com",
-        jwks=_jwks(keys),
-    )
+    claims = verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", aud="https://app.acme.com", jwks=_jwks(keys))
 
     assert claims["eventId"] == "evt_token_test"
     assert claims["decision"] == "allow"
@@ -133,7 +129,7 @@ def test_rejects_wrong_session(keys: dict) -> None:
     token = _mint(keys, sub="sess_other")
 
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token(token, session="sess_token_a", jwks=_jwks(keys))
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert exc.value.code == "wrong_session"
 
 
@@ -141,7 +137,7 @@ def test_rejects_wrong_audience(keys: dict) -> None:
     token = _mint(keys, aud="https://other.app")
 
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token(token, aud="https://app.acme.com", jwks=_jwks(keys))
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", aud="https://app.acme.com", jwks=_jwks(keys))
     assert exc.value.code == "wrong_aud"
 
 
@@ -149,16 +145,22 @@ def test_rejects_wrong_tenant(keys: dict) -> None:
     token = _mint(keys, tid="org_other")
 
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token(token, tenant_id="org_unit", jwks=_jwks(keys))
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert exc.value.code == "wrong_tenant"
 
 
+def test_rejects_wrong_issuer(keys: dict) -> None:
+    token = _mint(keys, iss="https://evil.example")
+
+    with pytest.raises(VerdictTokenError) as exc:
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
+    assert exc.value.code == "wrong_issuer"
+
+
 def test_accepts_expected_tenant(keys: dict) -> None:
     token = _mint(keys, tid="org_unit", sub="sess_token_a")
 
-    claims = verify_verdict_token(
-        token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys)
-    )
+    claims = verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert claims["tid"] == "org_unit"
 
 
@@ -166,7 +168,7 @@ def test_rejects_expired_token(keys: dict) -> None:
     token = _mint(keys, exp=int(time.time()) - 120)
 
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token(token, jwks=_jwks(keys))
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert exc.value.code == "expired"
 
 
@@ -174,7 +176,7 @@ def test_rejects_unknown_kid(keys: dict) -> None:
     token = _mint(keys)
 
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token(token, jwks={"keys": []})
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks={"keys": []})
     assert exc.value.code == "unknown_kid"
 
 
@@ -187,7 +189,7 @@ def test_rejects_tampered_signature(keys: dict) -> None:
     tampered = f"{header}.{payload}.{tampered_sig}"
 
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token(tampered, jwks=_jwks(keys))
+        verify_verdict_token(tampered, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert exc.value.code == "invalid_signature"
 
 
@@ -198,7 +200,7 @@ def test_rejects_wrong_algorithm(keys: dict) -> None:
     wrong = f"{wrong_header}.{payload}.{signature}"
 
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token(wrong, jwks=_jwks(keys))
+        verify_verdict_token(wrong, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert exc.value.code == "wrong_algorithm"
 
 
@@ -209,13 +211,13 @@ def test_rejects_missing_jwt_typ(keys: dict) -> None:
     wrong = f"{wrong_header}.{payload}.{signature}"
 
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token(wrong, jwks=_jwks(keys))
+        verify_verdict_token(wrong, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert exc.value.code == "wrong_type"
 
 
 def test_rejects_malformed_token() -> None:
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token("not-a-jwt", jwks={"keys": []})
+        verify_verdict_token("not-a-jwt", session="sess_token_a", tenant_id="org_unit", jwks={"keys": []})
     assert exc.value.code == "malformed_token"
 
 
@@ -226,7 +228,7 @@ def test_fetches_jwks_from_url(keys: dict) -> None:
         return_value=httpx.Response(200, json=_jwks(keys)),
     )
 
-    claims = verify_verdict_token(token, session="sess_fetch")
+    claims = verify_verdict_token(token, session="sess_fetch", tenant_id="org_unit")
 
     assert route.called
     assert claims["sub"] == "sess_fetch"
@@ -240,14 +242,14 @@ def test_jwks_fetch_failure_is_surfaced(keys: dict) -> None:
     )
 
     with pytest.raises(VerdictTokenError) as exc:
-        verify_verdict_token(token)
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit")
     assert exc.value.code == "jwks_unavailable"
 
 
 def test_accepts_degraded_receipt(keys: dict) -> None:
     token = _mint(keys, decision="challenge", degraded=True)
 
-    claims = verify_verdict_token(token, jwks=_jwks(keys))
+    claims = verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
 
     assert claims["decision"] == "challenge"
     assert claims["degraded"] is True

{chitmark-0.6.2 → chitmark-0.6.3}/tests/test_verify_token_extra.py

@@ -89,6 +89,7 @@ def _mint(keys: dict, **overrides: object) -> str:
     claims = {
         "iss": "https://api.chitmark.com",
         "sub": "sess_token_a",
+        "tid": "org_unit",
         "aud": "https://api.chitmark.com",
         "iat": now,
         "exp": now + 300,
@@ -125,38 +126,38 @@ def _jwks(keys: dict) -> dict:
 def test_rejects_missing_or_empty_kid(keys: dict) -> None:
     token = _mint(keys, _header_remove=["kid"])
     with pytest.raises(VerdictTokenError) as excinfo:
-        verify_verdict_token(token, jwks=_jwks(keys))
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert excinfo.value.code == "unknown_kid"
 
     token2 = _mint(keys, _header={"kid": ""})
     with pytest.raises(VerdictTokenError) as excinfo2:
-        verify_verdict_token(token2, jwks=_jwks(keys))
+        verify_verdict_token(token2, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert excinfo2.value.code == "unknown_kid"
 
     token3 = _mint(keys, _header={"kid": 123})
     with pytest.raises(VerdictTokenError) as excinfo3:
-        verify_verdict_token(token3, jwks=_jwks(keys))
+        verify_verdict_token(token3, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert excinfo3.value.code == "malformed_token"
 
 
 def test_rejects_future_iat(keys: dict) -> None:
     token = _mint(keys, iat=int(time.time()) + 3600)
     with pytest.raises(VerdictTokenError) as excinfo:
-        verify_verdict_token(token, jwks=_jwks(keys))
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert excinfo.value.code == "not_yet_valid"
 
 
 def test_rejects_undecodable_payload(keys: dict) -> None:
     token = _mint(keys, _raw_payload=b"hello")
     with pytest.raises(VerdictTokenError) as excinfo:
-        verify_verdict_token(token, jwks=_jwks(keys))
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=_jwks(keys))
     assert excinfo.value.code == "malformed_token"
 
 
 def test_rejects_malformed_header() -> None:
     token = "a.b.c"
     with pytest.raises(VerdictTokenError) as excinfo:
-        verify_verdict_token(token, jwks={"keys": []})
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks={"keys": []})
     assert excinfo.value.code == "malformed_token"
 
 
@@ -170,7 +171,7 @@ def test_rejects_jwk_with_bad_curve_data(keys: dict) -> None:
     }
     token = _mint(keys)
     with pytest.raises(VerdictTokenError) as excinfo:
-        verify_verdict_token(token, jwks={"keys": [bad]})
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks={"keys": [bad]})
     assert excinfo.value.code == "invalid_signature"
 
 
@@ -181,7 +182,7 @@ def test_jwks_fetch_network_error(keys: dict) -> None:
     )
     token = _mint(keys)
     with pytest.raises(VerdictTokenError) as excinfo:
-        verify_verdict_token(token)
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit")
     assert excinfo.value.code == "jwks_unavailable"
 
 
@@ -192,7 +193,7 @@ def test_jwks_fetch_non_200(keys: dict) -> None:
     )
     token = _mint(keys)
     with pytest.raises(VerdictTokenError) as excinfo:
-        verify_verdict_token(token)
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit")
     assert excinfo.value.code == "jwks_unavailable"
 
 
@@ -203,7 +204,7 @@ def test_jwks_fetch_invalid_json(keys: dict) -> None:
     )
     token = _mint(keys)
     with pytest.raises(VerdictTokenError) as excinfo:
-        verify_verdict_token(token)
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit")
     assert excinfo.value.code == "jwks_unavailable"
 
 
@@ -214,7 +215,7 @@ def test_jwks_fetch_with_reusable_client(keys: dict) -> None:
     )
     client = httpx.Client()
     try:
-        claims = verify_verdict_token(_mint(keys), http_client=client)
+        claims = verify_verdict_token(_mint(keys), session="sess_token_a", tenant_id="org_unit", http_client=client)
         assert claims["jti"] == "jwt_1"
         assert client.is_closed is False
     finally:
@@ -224,19 +225,14 @@ def test_jwks_fetch_with_reusable_client(keys: dict) -> None:
 def test_jwks_mapping_and_keys_list_shapes(keys: dict) -> None:
     token = _mint(keys)
     with pytest.raises(VerdictTokenError) as excinfo:
-        verify_verdict_token(token, jwks=["not", "a", "mapping"])
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks=["not", "a", "mapping"])
     assert excinfo.value.code == "jwks_unavailable"
 
     with pytest.raises(VerdictTokenError) as excinfo2:
-        verify_verdict_token(token, jwks={"nokeys": True})
+        verify_verdict_token(token, session="sess_token_a", tenant_id="org_unit", jwks={"nokeys": True})
     assert excinfo2.value.code == "jwks_unavailable"
 
 
 def test_accepts_valid_token_with_explicit_audience(keys: dict) -> None:
-    claims = verify_verdict_token(
-        _mint(keys),
-        session="sess_token_a",
-        aud="https://api.chitmark.com",
-        jwks=_jwks(keys),
-    )
+    claims = verify_verdict_token(_mint(keys), session="sess_token_a", tenant_id="org_unit", aud="https://api.chitmark.com", jwks=_jwks(keys))
     assert claims["v"] == 1