hank-contracts 1.0__tar.gz

hank_contracts-1.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: hank-contracts
+Version: 1.0
+Summary: Hank wire-contract types: commercial claims, work authorization, usage, capability and subject shapes with JSON schemas and canonical serialization
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: cryptography>=41
+Requires-Dist: PyJWT>=2.8
+Requires-Dist: jsonschema>=4.26
+
+# hank-contracts
+
+Wire-contract types for Hank: commercial claims, work authorization, usage
+rows and reports, investment capability grants, the agent_api_v1 claim shape,
+and the Risk web subject assertion — frozen dataclasses, constants, JSON
+schemas, and canonical serialization only.
+
+No signing, verification, key handling, HTTP, or storage lives here. Runtimes
+keep that behavior and import these shapes. Private validation helpers moved
+with their dataclasses so trust-snapshot construction validates exactly as
+before.

hank_contracts-1.0/README.md

@@ -0,0 +1,11 @@
+# hank-contracts
+
+Wire-contract types for Hank: commercial claims, work authorization, usage
+rows and reports, investment capability grants, the agent_api_v1 claim shape,
+and the Risk web subject assertion — frozen dataclasses, constants, JSON
+schemas, and canonical serialization only.
+
+No signing, verification, key handling, HTTP, or storage lives here. Runtimes
+keep that behavior and import these shapes. Private validation helpers moved
+with their dataclasses so trust-snapshot construction validates exactly as
+before.

hank_contracts-1.0/hank_contracts/__init__.py

@@ -0,0 +1,108 @@
+"""Package entrypoint: re-export public wire-contract types."""
+
+from __future__ import annotations
+
+from .agent_api import (
+  AGENT_API_CLAIM_AUDIENCE,
+  AGENT_API_CLAIM_ENV_VARS,
+  AGENT_API_CLAIM_HEADERS,
+  AGENT_API_CLAIM_TTL_SECONDS_DEFAULT,
+  canonical_agent_api_claim_bytes,
+)
+from .commercial_authority import (
+  CommercialAuthorityInvalidation,
+  CommercialAuthoritySnapshot,
+  DecodedCommercialAuthorityFeedPage,
+)
+from .commercial_claims import (
+  COMMERCIAL_CLAIM_ALGORITHM,
+  COMMERCIAL_CLAIM_AUDIENCE,
+  COMMERCIAL_CLAIM_ISSUER,
+  COMMERCIAL_CLAIM_REQUIRED_FIELDS,
+  CommercialClaimError,
+  CommercialClaimTrustSnapshot,
+  CommercialContextState,
+  VerifiedCommercialClaim,
+)
+from .commercial_work import (
+  COMMERCIAL_CLAIM_HEADER,
+  COMMERCIAL_WORK_AUTHORIZATION_HEADER,
+  CommercialWorkStartContext,
+  CommercialWorkStartFacts,
+  CommercialWorkStartFactsResolver,
+  CommercialWorkStartPreflight,
+  PendingCommercialWorkStart,
+  VerifiedCommercialWorkStartClaim,
+  VerifiedWorkAuthorization,
+  WORK_AUTHORIZATION_ALGORITHM,
+  WORK_AUTHORIZATION_AUDIENCE,
+  WORK_AUTHORIZATION_ISSUER,
+  WORK_AUTHORIZATION_REQUIRED_FIELDS,
+  WORK_AUTHORIZATION_V3_REQUIRED_FIELDS,
+  WorkAuthorizationError,
+  WorkAuthorizationTrustSnapshot,
+  WorkStartSpendLedger,
+)
+from .investment_claims import (
+  INVESTMENT_CAPABILITY_CLAIM_AUDIENCE,
+  INVESTMENT_CAPABILITY_CLAIM_ISSUER,
+  INVESTMENT_CAPABILITY_CLAIM_KEY_BYTES,
+  INVESTMENT_CAPABILITY_CLAIM_KIND,
+  INVESTMENT_CAPABILITY_CLAIM_PRIVATE_KEY_ENV,
+  INVESTMENT_CAPABILITY_CLAIM_PUBLIC_KEY_ENV,
+  INVESTMENT_CAPABILITY_CLAIM_SERVER,
+  INVESTMENT_CAPABILITY_CLAIM_TTL_SECONDS,
+  INVESTMENT_CAPABILITY_CLAIM_VERSION,
+  INVESTMENT_CAPABILITY_FACADE_TOOLS,
+  INVESTMENT_JOB_PRINCIPAL_CLAIM_KIND,
+  INVESTMENT_JOB_PRINCIPAL_CLAIM_VERSION,
+  INVESTMENT_JOB_PRINCIPAL_TOOLS,
+  INVESTMENT_SELECTED_CONTENT_CLAIM_PURPOSE,
+  InvestmentCapabilityGrant,
+  RISK_CAPABILITY_CLAIM_AUDIENCE,
+  RISK_JOB_CAPABILITY_CLAIM_KIND,
+  RISK_JOB_CAPABILITY_CLAIM_VERSION,
+)
+from .subject_assertion import (
+  SUBJECT_ASSERTION_ALGORITHM,
+  SUBJECT_ASSERTION_AUDIENCE,
+  SUBJECT_ASSERTION_CLOCK_SKEW_SECONDS,
+  SUBJECT_ASSERTION_ISSUER,
+  SUBJECT_ASSERTION_MAX_LIFETIME_SECONDS,
+  SUBJECT_ASSERTION_PUBLIC_KEYS_ENV,
+  SUBJECT_ASSERTION_REPLAY_CACHE_SIZE,
+  SubjectAssertionError,
+  VerifiedGatewaySubject,
+)
+from .usage import (
+  MAX_SHIPPER_BATCH_SIZE,
+  OUTBOX_SCHEMA_VERSION,
+  SHIPPABLE_USAGE_PAYLOAD_SCHEMA_VERSION,
+  USAGE_DURABILITY_RANK,
+  AcceptanceStatus,
+  CommercialUsageBatchSender,
+  CommercialUsageCircuitOpen,
+  CommercialUsageCircuitSnapshot,
+  CommercialUsageDeliveryError,
+  CommercialUsageLineage,
+  CommercialUsageOutboxConflict,
+  CommercialUsageOutboxError,
+  CommercialUsageOutboxRow,
+  CommercialUsageOutboxSink,
+  CommercialUsageOutboxT,
+  CommercialUsagePermanentDeliveryError,
+  CommercialUsageReconciliationBatchSender,
+  CommercialUsageReconciliationReport,
+  CommercialUsageReconciliationRow,
+  CommercialUsageReconciliationShipmentRow,
+  CommercialUsageResponseError,
+  CommercialUsageShipperConfig,
+  CommercialUsageSpoolError,
+  OutboxState,
+  ReconciliationAcceptance,
+  ReconciliationShipmentState,
+  UsageAcceptance,
+  UsageDurability,
+)
+
+__version__ = "1.0"

hank_contracts-1.0/hank_contracts/agent_api.py

@@ -0,0 +1,43 @@
+"""Agent API v1 claim wire constants and canonical format (M10)."""
+
+from __future__ import annotations
+
+from typing import Final, Mapping
+
+
+AGENT_API_CLAIM_AUDIENCE: Final = "agent_api_v1"
+AGENT_API_CLAIM_TTL_SECONDS_DEFAULT: Final = 300
+AGENT_API_CLAIM_ENV_VARS: Final[Mapping[str, str]] = {
+  "audience": "AGENT_API_CLAIM_AUDIENCE",
+  "issued_at": "AGENT_API_CLAIM_ISSUED_AT",
+  "expiry": "AGENT_API_CLAIM_EXPIRY",
+  "user_id": "AGENT_API_CLAIM_USER_ID",
+  "user_email": "AGENT_API_CLAIM_USER_EMAIL",
+  "nonce": "AGENT_API_CLAIM_NONCE",
+  "signature": "AGENT_API_CLAIM_SIGNATURE",
+}
+AGENT_API_CLAIM_HEADERS: Final[Mapping[str, str]] = {
+  "audience": "X-Agent-Claim-Audience",
+  "issued_at": "X-Agent-Claim-Issued-At",
+  "expiry": "X-Agent-Claim-Expiry",
+  "user_id": "X-Agent-Claim-User-Id",
+  "user_email": "X-Agent-Claim-User-Email",
+  "nonce": "X-Agent-Claim-Nonce",
+  "signature": "X-Agent-Claim-Signature",
+}
+
+
+def canonical_agent_api_claim_bytes(
+  *,
+  audience: str,
+  issued_at: int,
+  expiry: int,
+  user_id: str,
+  user_email: str | None,
+  nonce: str,
+) -> bytes:
+  """The exact byte sequence HMAC-SHA256 signs for an agent_api_v1 claim."""
+  normalized_email = user_email or ""
+  return f"{audience}\n{issued_at}\n{expiry}\n{user_id}\n{normalized_email}\n{nonce}".encode(
+    "utf-8"
+  )

hank_contracts-1.0/hank_contracts/commercial_authority.py

@@ -0,0 +1,79 @@
+"""Commercial authority snapshot/invalidation shapes (M10: moved from agent_gateway)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib.resources import files
+import json
+from typing import Literal
+from uuid import UUID
+
+from jsonschema import Draft202012Validator
+
+
+@dataclass(frozen=True)
+class CommercialAuthoritySnapshot:
+  context_id: UUID
+  active: bool
+  entitlement_revision: int
+  commercial_account_id: int | None
+  token_id: UUID | None
+
+  def __post_init__(self) -> None:
+    if type(self.context_id) is not UUID or (
+      self.token_id is not None and type(self.token_id) is not UUID
+    ):
+      raise ValueError("commercial authority UUID identity is invalid")
+    if type(self.active) is not bool:
+      raise ValueError("commercial authority active state must be boolean")
+    if type(self.entitlement_revision) is not int or self.entitlement_revision < 0:
+      raise ValueError("commercial authority revision cannot be negative")
+    if self.commercial_account_id is not None and (
+      type(self.commercial_account_id) is not int or self.commercial_account_id <= 0
+    ):
+      raise ValueError("commercial account identity must be positive")
+
+
+@dataclass(frozen=True)
+class CommercialAuthorityInvalidation:
+  kind: Literal["context", "token", "entitlement", "agreement", "emergency"]
+  commercial_account_id: int
+  entitlement_revision: int
+  context_id: UUID | None = None
+  token_id: UUID | None = None
+
+  def __post_init__(self) -> None:
+    if self.kind not in {"context", "token", "entitlement", "agreement", "emergency"}:
+      raise ValueError("commercial invalidation kind is invalid")
+    if (
+      self.context_id is not None and type(self.context_id) is not UUID
+    ) or (self.token_id is not None and type(self.token_id) is not UUID):
+      raise ValueError("commercial invalidation UUID identity is invalid")
+    if (
+      type(self.commercial_account_id) is not int
+      or type(self.entitlement_revision) is not int
+      or self.commercial_account_id <= 0
+      or self.entitlement_revision <= 0
+    ):
+      raise ValueError("commercial invalidation identity is invalid")
+    if self.kind == "context" and self.context_id is None:
+      raise ValueError("context invalidation requires context identity")
+    if self.kind == "token" and self.token_id is None:
+      raise ValueError("token invalidation requires token identity")
+
+
+_SCHEMA_PATH = (
+  files("hank_contracts")
+  / "contracts"
+  / "commercial-authority-v1"
+  / "commercial-authority-invalidation-feed-v1.schema.json"
+)
+_SCHEMA = json.loads(_SCHEMA_PATH.read_text(encoding="utf-8"))
+_VALIDATOR = Draft202012Validator(_SCHEMA)
+
+
+@dataclass(frozen=True)
+class DecodedCommercialAuthorityFeedPage:
+  invalidations: tuple[CommercialAuthorityInvalidation, ...]
+  next_sequence: int
+  high_water_sequence: int

hank_contracts-1.0/hank_contracts/commercial_claims.py

@@ -0,0 +1,99 @@
+"""Commercial execution claim shapes (M10: moved from agent_gateway)."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Callable, Mapping, TypeGuard
+from uuid import UUID
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+
+COMMERCIAL_CLAIM_ALGORITHM = "EdDSA"
+COMMERCIAL_CLAIM_ISSUER = "risk-module-commercial-control"
+COMMERCIAL_CLAIM_AUDIENCE = "hank-agent-gateway"
+_STABLE_CODE = re.compile(r"^[a-z][a-z0-9._:-]{0,127}$")
+COMMERCIAL_CLAIM_REQUIRED_FIELDS = frozenset({
+  "schema_version", "kid", "iss", "aud", "sub", "environment", "surface",
+  "commercial_account_id", "agreement_id", "agreement_terms_revision",
+  "offer_code", "effective_scopes", "entitlement_revision", "payer_policy_version",
+  "budget_policy_version", "shadow_rate_version", "manifest_version",
+  "authorized_work_start_deadline", "usage_accept_until", "iat", "exp", "jti",
+})
+
+
+class CommercialClaimError(ValueError):
+  def __init__(self, code: str) -> None:
+    self.code = code
+    super().__init__(code)
+
+
+def _load_ed25519_public_key(pem: bytes) -> Ed25519PublicKey:
+  key = load_pem_public_key(pem)
+  if not isinstance(key, Ed25519PublicKey):
+    raise ValueError("commercial verification keys must be Ed25519")
+  return key
+
+
+@dataclass(frozen=True)
+class CommercialContextState:
+  active: bool
+  entitlement_revision: int
+
+
+@dataclass(frozen=True)
+class CommercialClaimTrustSnapshot:
+  public_keys_by_id: Mapping[str, bytes]
+  environment: str
+  manifest_versions: frozenset[str]
+  payer_policy_versions: frozenset[str]
+  budget_policy_versions: frozenset[str]
+  shadow_rate_versions: frozenset[str]
+  current_agreement_terms_revision: Callable[[UUID], int | None]
+  resolve_context_state: Callable[[UUID], CommercialContextState] | None = None
+
+  def __post_init__(self) -> None:
+    if self.environment not in {"dev", "staging", "prod"}:
+      raise ValueError("commercial trust environment is invalid")
+    if not self.public_keys_by_id:
+      raise ValueError("commercial trust snapshot requires verification keys")
+    for key_id, pem in self.public_keys_by_id.items():
+      if not _STABLE_CODE.fullmatch(key_id):
+        raise ValueError("commercial verification key id is invalid")
+      _load_ed25519_public_key(pem)
+    for versions in (
+      self.manifest_versions, self.payer_policy_versions,
+      self.budget_policy_versions, self.shadow_rate_versions,
+    ):
+      if not versions or any(not _valid_version(value) for value in versions):
+        raise ValueError("commercial trust versions must be non-empty bounded strings")
+
+
+@dataclass(frozen=True)
+class VerifiedCommercialClaim:
+  schema_version: int
+  key_id: str
+  subject: str
+  environment: str
+  surface: str
+  commercial_account_id: UUID
+  agreement_id: UUID
+  agreement_terms_revision: int
+  offer_code: str
+  effective_scopes: tuple[str, ...]
+  entitlement_revision: int
+  payer_policy_version: str
+  budget_policy_version: str
+  shadow_rate_version: str
+  manifest_version: str
+  authorized_work_start_deadline: int
+  usage_accept_until: int
+  issued_at: int
+  expires_at: int
+  context_id: UUID
+
+
+def _valid_version(value: object) -> TypeGuard[str]:
+  return isinstance(value, str) and 1 <= len(value) <= 256 and not value.isspace()

hank_contracts-1.0/hank_contracts/commercial_work.py

@@ -0,0 +1,232 @@
+"""Commercial work authorization and work-start shapes (M10: moved from agent_gateway)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal, ROUND_CEILING
+import re
+from threading import Lock
+from typing import Any, Callable, Literal, Mapping
+from uuid import UUID
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import load_pem_public_key
+
+from .commercial_claims import VerifiedCommercialClaim
+
+
+WORK_AUTHORIZATION_ALGORITHM = "EdDSA"
+WORK_AUTHORIZATION_ISSUER = "risk-module-commercial-work-control"
+WORK_AUTHORIZATION_AUDIENCE = "hank-agent-gateway-work-start"
+_CODE = re.compile(r"^[a-z][a-z0-9._:-]{0,127}$")
+WORK_AUTHORIZATION_REQUIRED_FIELDS = frozenset({
+  "schema_version", "kid", "iss", "aud", "jti", "environment",
+  "execution_claim_jti", "workflow_run_id", "workflow_attempt_group_id",
+  "workflow_attempt_number", "retry_of_workflow_run_id",
+  "workflow_attempt_kind", "primary_inference_observability",
+  "funding_route_id", "provider", "billing_mode", "reservation_id",
+  "operation", "capability_id", "request_id", "session_id", "iat", "exp",
+})
+# V3 binds the account and a reserved budget, never a model or provider
+# (rulings-index WA-ACCOUNT-BUDGET). V1 and V2 tokens are not accepted.
+WORK_AUTHORIZATION_V3_REQUIRED_FIELDS = WORK_AUTHORIZATION_REQUIRED_FIELDS | {
+  "credential_principal", "reserved_spend_microusd",
+}
+
+
+def _load_ed25519_public_key(pem: bytes) -> Ed25519PublicKey:
+  key = load_pem_public_key(pem)
+  if not isinstance(key, Ed25519PublicKey):
+    raise ValueError("work authorization verification keys must be Ed25519")
+  return key
+
+
+class WorkAuthorizationError(ValueError):
+  def __init__(self, code: str) -> None:
+    self.code = code
+    super().__init__(code)
+
+
+@dataclass(frozen=True)
+class WorkAuthorizationTrustSnapshot:
+  public_keys_by_id: Mapping[str, bytes]
+  environment: str
+  manifest_version: str
+  capability_required_scopes: Mapping[str, frozenset[str]]
+  capability_allowed_operations: Mapping[str, frozenset[str]]
+  retired_at_by_key_id: Mapping[str, int | None]
+
+  def __post_init__(self) -> None:
+    if self.environment not in {"dev", "staging", "prod"}:
+      raise ValueError("work authorization trust environment is invalid")
+    if not isinstance(self.manifest_version, str) or not self.manifest_version:
+      raise ValueError("work authorization manifest version is invalid")
+    if not self.public_keys_by_id:
+      raise ValueError("work authorization trust requires verification keys")
+    if set(self.retired_at_by_key_id) != set(self.public_keys_by_id):
+      raise ValueError("work authorization key retirement inventory is incomplete")
+    for key_id, pem in self.public_keys_by_id.items():
+      if not _CODE.fullmatch(key_id):
+        raise ValueError("work authorization verification key id is invalid")
+      _load_ed25519_public_key(pem)
+      retired_at = self.retired_at_by_key_id[key_id]
+      if retired_at is not None and (type(retired_at) is not int or retired_at <= 0):
+        raise ValueError("work authorization retirement cutoff is invalid")
+    if not self.capability_required_scopes:
+      raise ValueError("work authorization manifest capability map is empty")
+    if set(self.capability_allowed_operations) != set(
+      self.capability_required_scopes
+    ):
+      raise ValueError("work authorization manifest operation map is incomplete")
+    for capability, scopes in self.capability_required_scopes.items():
+      if (
+        not _CODE.fullmatch(capability)
+        or not isinstance(scopes, frozenset)
+        or not scopes
+      ):
+        raise ValueError("work authorization manifest capability is invalid")
+      if any(not _CODE.fullmatch(scope) for scope in scopes):
+        raise ValueError("work authorization manifest scope is invalid")
+      operations = self.capability_allowed_operations[capability]
+      if (
+        not isinstance(operations, frozenset)
+        or not operations
+        or any(not _CODE.fullmatch(operation) for operation in operations)
+      ):
+        raise ValueError("work authorization manifest operation is invalid")
+
+
+@dataclass(frozen=True)
+class VerifiedWorkAuthorization:
+  schema_version: int
+  key_id: str
+  token_sha256: str
+  authorization_id: UUID
+  environment: str
+  execution_context_id: UUID
+  workflow_run_id: UUID
+  workflow_attempt_group_id: UUID
+  workflow_attempt_number: int
+  retry_of_workflow_run_id: UUID | None
+  workflow_attempt_kind: str
+  primary_inference_observability: str
+  funding_route_id: UUID
+  provider: str
+  billing_mode: Literal["byok", "metered"]
+  reservation_id: UUID | None
+  operation: str
+  capability_id: str | None
+  request_id: str
+  session_id: str
+  issued_at: int
+  expires_at: int
+  # None exactly when billing_mode is byok (no reservation hold).
+  reserved_spend_microusd: int | None = None
+  credential_principal: Literal["user", "service"] | None = None
+
+
+COMMERCIAL_CLAIM_HEADER = "X-Hank-Commercial-Claim"
+COMMERCIAL_WORK_AUTHORIZATION_HEADER = "X-Hank-Work-Authorization"
+
+
+@dataclass(frozen=True)
+class CommercialWorkStartFacts:
+  operation: str
+  billing_mode: str
+  capability_id: str | None
+  credential_principal: str
+
+
+@dataclass(frozen=True)
+class VerifiedCommercialWorkStartClaim:
+  """Verified account identity awaiting facts from the prepared request."""
+
+  claim: VerifiedCommercialClaim
+  _authorization_token: str = field(repr=False, compare=False)
+  _gate_binding: object = field(repr=False, compare=False)
+
+
+@dataclass(frozen=True)
+class PendingCommercialWorkStart:
+  """Token-free verified authority awaiting durable one-time consumption."""
+
+  claim: VerifiedCommercialClaim
+  authorization: VerifiedWorkAuthorization
+  _gate_binding: object = field(repr=False, compare=False)
+
+
+@dataclass(frozen=True)
+class CommercialWorkStartContext:
+  """Token-free request context available only after durable consumption."""
+
+  claim: VerifiedCommercialClaim
+  authorization: VerifiedWorkAuthorization
+  # Opaque handle: the durable consumption record lives with the gateway
+  # store that owns it; the contract layer never inspects it.
+  consumption: Any
+  spend_ledger: "WorkStartSpendLedger | None" = None
+
+  def __post_init__(self) -> None:
+    if self.spend_ledger is None:
+      object.__setattr__(
+        self,
+        "spend_ledger",
+        WorkStartSpendLedger.for_authorization(self.authorization),
+      )
+
+CommercialWorkStartFactsResolver = Callable[
+  [Any, Any, str | None], CommercialWorkStartFacts
+]
+CommercialWorkStartPreflight = Callable[[PendingCommercialWorkStart], None]
+
+
+_MICRO_USD = Decimal(1_000_000)
+
+
+@dataclass
+class WorkStartSpendLedger:
+  """Cumulative producer-estimated microUSD for one work authorization.
+
+  One ledger per work start, shared by the root and its children because they
+  share the context. Fed only from CommercialUsageProducer.emit.
+  """
+
+  authorization_id: UUID
+  reserved_spend_microusd: int | None
+  _spent_microusd: int = 0
+  _lock: Lock = field(default_factory=Lock, repr=False, compare=False)
+
+  @classmethod
+  def for_authorization(
+    cls, authorization: VerifiedWorkAuthorization
+  ) -> "WorkStartSpendLedger":
+    reserved = authorization.reserved_spend_microusd
+    if authorization.billing_mode != "metered":
+      reserved = None
+    return cls(
+      authorization_id=authorization.authorization_id,
+      reserved_spend_microusd=reserved,
+    )
+
+  def record_usd(self, cost_usd: object) -> None:
+    if cost_usd is None:
+      return
+    amount = Decimal(str(cost_usd))
+    if amount <= 0:
+      return
+    micro = int(
+      (amount * _MICRO_USD).to_integral_value(rounding=ROUND_CEILING)
+    )
+    with self._lock:
+      self._spent_microusd += micro
+
+  @property
+  def spent_microusd(self) -> int:
+    with self._lock:
+      return self._spent_microusd
+
+  def reached(self) -> bool:
+    reserved = self.reserved_spend_microusd
+    if reserved is None:
+      return False
+    return self.spent_microusd >= reserved