city-sdk 0.9.0__tar.gz

city_sdk-0.9.0/.gitignore

@@ -0,0 +1,72 @@
+# Terraform
+**/.terraform/
+*.tfstate
+*.tfstate.backup
+*.tfstate.lock.info
+crash.log
+crash.*.log
+override.tf
+override.tf.json
+*_override.tf
+*_override.tf.json
+*.tfplan
+*.tfplan.json
+*.pyc
+__pycache__/
+
+# Local city CLI keystore and team token
+.city/
+
+# Terraform variable files with secrets — keep *.tfvars.example, ignore actual values
+*.tfvars
+*.tfvars.json
+
+# Terragrunt cache
+**/.terragrunt-cache/
+
+# Provider lock files (optional: remove if you want to pin providers in VCS)
+# **/.terraform.lock.hcl
+
+# GCP service account key files
+*.json
+!**/cloudbuild*.json
+# Firebase web app configs are public client identifiers (not secrets)
+!**/firebase-config*.json
+# Contract schemas and examples are source, not credentials
+!specs/**/*.json
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Node.js / Next.js config files
+!package-lock.json
+!package.json
+!tsconfig.json
+!next.config.mjs
+!next.config.js
+node_modules/
+services/ui/dist/
+services/ui/.env
+services/ui/.env.local
+services/ui/.env.*.local
+.venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Elementor kit workdir / local backups (keep the published zip + README tracked)
+landing/elementor-export/.kit-work/
+landing/elementor-export/*.bak.zip
+landing/elementor-export/migrate_to_native.py
+landing/elementor-export/pni-elementor-kit.zip
+landing/elementor-export/README.md
+.publish/

city_sdk-0.9.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.5
+Name: city-sdk
+Version: 0.9.0
+Summary: City harness and the day-1 Market facade (includes cap).
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=43
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: rfc8785>=0.1.4
+Requires-Dist: uvicorn>=0.32

city_sdk-0.9.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "city-sdk"
+version = "0.9.0"
+description = "City harness and the day-1 Market facade (includes cap)."
+requires-python = ">=3.12"
+dependencies = [
+    "cryptography>=43",
+    "fastapi>=0.115",
+    "httpx>=0.27",
+    "pydantic>=2",
+    "rfc8785>=0.1.4",
+    "uvicorn>=0.32",
+]
+
+[project.scripts]
+city-sdk = "city_sdk.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/city_sdk", "src/cap"]

city_sdk-0.9.0/src/cap/__init__.py

@@ -0,0 +1 @@
+"""CAP library namespace (``cap.core``, later ``cap.sdk``, …)."""

city_sdk-0.9.0/src/cap/core/__init__.py

@@ -0,0 +1,32 @@
+"""CAP canonicalization, signatures, grants, envelopes, and error codes."""
+
+from cap.core.envelope import build, sign, verify
+from cap.core.errors import CapError, http_status_for
+from cap.core.grant import SignedGrant
+from cap.core.grant import issue as issue_grant
+from cap.core.grant import verify as verify_grant
+from cap.core.jcs import canonicalize, card_digest, digest
+from cap.core.jws import sign_detached, verify_detached
+from cap.core.keys import KeyPair, PrivateKey, PublicKey, generate
+
+__version__ = "0.9.0"
+
+__all__ = [
+    "CapError",
+    "KeyPair",
+    "PrivateKey",
+    "PublicKey",
+    "SignedGrant",
+    "build",
+    "canonicalize",
+    "card_digest",
+    "digest",
+    "generate",
+    "http_status_for",
+    "issue_grant",
+    "sign",
+    "sign_detached",
+    "verify",
+    "verify_detached",
+    "verify_grant",
+]

city_sdk-0.9.0/src/cap/core/envelope.py

@@ -0,0 +1,156 @@
+"""Build, sign, and verify a CAP envelope."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from datetime import datetime, timedelta
+
+from cap.core.errors import CapError
+from cap.core.grant import SignedGrant
+from cap.core.grant import verify as verify_grant
+from cap.core.jcs import canonicalize
+from cap.core.jws import sign_detached, verify_detached
+from cap.core.keys import PrivateKey, PublicKey
+from cap.core.timeutil import format_time, parse_time
+
+_SKEW = timedelta(seconds=120)
+_DEFAULT_TTL = timedelta(seconds=60)
+
+
+def build(
+    *,
+    msg_id: str,
+    message_type: str,
+    sender: str,
+    recipient: str,
+    sent_at: datetime,
+    body: Mapping[str, object],
+    profile: str | None = None,
+    expires_at: datetime | None = None,
+    conversation_id: str | None = None,
+    need_id: str | None = None,
+    in_reply_to: str | None = None,
+    traceparent: str | None = None,
+) -> dict[str, object]:
+    envelope: dict[str, object] = {
+        "cap": "1.0",
+        "msg_id": msg_id,
+        "type": message_type,
+        "from": sender,
+        "to": recipient,
+        "sent_at": format_time(sent_at),
+        "body": dict(body),
+    }
+    if profile is not None:
+        envelope["profile"] = profile
+    if expires_at is not None:
+        envelope["expires_at"] = format_time(expires_at)
+    if conversation_id is not None:
+        envelope["conversation_id"] = conversation_id
+    if need_id is not None:
+        envelope["need_id"] = need_id
+    if in_reply_to is not None:
+        envelope["in_reply_to"] = in_reply_to
+    if traceparent is not None:
+        envelope["traceparent"] = traceparent
+    return envelope
+
+
+def sign(
+    envelope: Mapping[str, object],
+    private: PrivateKey,
+    *,
+    kid: str,
+    grant_id: str | None = None,
+) -> dict[str, object]:
+    unsigned = {key: value for key, value in envelope.items() if key != "sig"}
+    sender = unsigned.get("from")
+    if not isinstance(sender, str) or not kid.startswith(sender + "#"):
+        raise CapError("KEY_UNKNOWN", "kid is not under from")
+    sig: dict[str, str] = {"alg": "EdDSA", "kid": kid}
+    if grant_id is not None:
+        sig["grant"] = grant_id
+    sig["jws"] = sign_detached(private, canonicalize(unsigned).encode("utf-8"), kid=kid)
+    signed = dict(unsigned)
+    signed["sig"] = sig
+    return signed
+
+
+def verify(
+    envelope: Mapping[str, object],
+    *,
+    now: datetime,
+    key_for_kid: Callable[[str], PublicKey],
+    grant_for_id: Callable[[str], SignedGrant] | None = None,
+    controller_public: PublicKey | None = None,
+    required_permission: str | None = None,
+    target_visible: Callable[[str], bool] | None = None,
+    record_verifier: Callable[[Mapping[str, object]], None] | None = None,
+) -> None:
+    """Verify signature, ``from``/``kid``, grant chain, expiry, and clock skew.
+
+    ``target_visible`` defaults to true. The Relay supplies the Index check.
+    """
+    if now.tzinfo is None:
+        raise CapError("SCHEMA_INVALID", "now must be timezone-aware")
+    msg_id = envelope.get("msg_id")
+    msg = msg_id if isinstance(msg_id, str) else None
+    unsigned = {key: value for key, value in envelope.items() if key != "sig"}
+    for field in ("cap", "msg_id", "type", "from", "to", "sent_at", "body"):
+        if field not in unsigned:
+            raise CapError("SCHEMA_INVALID", f"missing {field}", msg)
+    if unsigned.get("cap") != "1.0":
+        raise CapError("SCHEMA_INVALID", "cap must be 1.0", msg)
+    sender = unsigned["from"]
+    recipient = unsigned["to"]
+    if not isinstance(sender, str) or not isinstance(recipient, str):
+        raise CapError("SCHEMA_INVALID", "from and to must be strings", msg)
+    sig = envelope.get("sig")
+    if not isinstance(sig, Mapping):
+        raise CapError("SCHEMA_INVALID", "sig is required", msg)
+    if sig.get("alg") != "EdDSA":
+        raise CapError("SIGNATURE_INVALID", "sig.alg must be EdDSA", msg)
+    kid = sig.get("kid")
+    token = sig.get("jws")
+    if not isinstance(kid, str) or not isinstance(token, str):
+        raise CapError("SCHEMA_INVALID", "sig.kid and sig.jws are required", msg)
+    if not kid.startswith(sender + "#"):
+        raise CapError("KEY_UNKNOWN", "kid is not under from", msg)
+    try:
+        public = key_for_kid(kid)
+    except KeyError as exc:
+        raise CapError("KEY_UNKNOWN", kid, msg) from exc
+    verify_detached(public, canonicalize(unsigned).encode("utf-8"), token, kid=kid)
+    grant_id = sig.get("grant")
+    if grant_id is not None:
+        if not isinstance(grant_id, str):
+            raise CapError("SCHEMA_INVALID", "sig.grant must be a string", msg)
+        if grant_for_id is None or controller_public is None:
+            raise CapError("SIGNATURE_INVALID", "grant resolver is required", msg)
+        try:
+            signed_grant = grant_for_id(grant_id)
+        except KeyError as exc:
+            raise CapError("SIGNATURE_INVALID", "unknown grant", msg) from exc
+        if signed_grant.grant.get("grant_id") != grant_id:
+            raise CapError("SIGNATURE_INVALID", "grant_id mismatch", msg)
+        if signed_grant.grant.get("agent_id") != sender:
+            raise CapError("SIGNATURE_INVALID", "grant agent_id mismatch", msg)
+        if signed_grant.grant.get("agent_pubkey") != public.to_jwk():
+            raise CapError("KEY_UNKNOWN", "grant key does not match kid", msg)
+        verify_grant(
+            signed_grant,
+            controller_public,
+            now=now,
+            required_permission=required_permission,
+            record_verifier=record_verifier,
+        )
+    sent_at = parse_time(unsigned["sent_at"])
+    if abs(now - sent_at) > _SKEW:
+        raise CapError("EXPIRED", "sent_at outside ±120s", msg)
+    expires_raw = unsigned.get("expires_at")
+    expires_at = parse_time(expires_raw) if expires_raw is not None else sent_at + _DEFAULT_TTL
+    if now > expires_at:
+        raise CapError("EXPIRED", "expires_at passed", msg)
+    visible = True if target_visible is None else target_visible(recipient)
+    if not visible:
+        raise CapError("TARGET_NOT_VISIBLE", recipient, msg)

city_sdk-0.9.0/src/cap/core/errors.py

@@ -0,0 +1,59 @@
+"""City error codes and the CAP error body (``specs/cap/error.json``)."""
+
+from __future__ import annotations
+
+# specification 04 §6.9. Profile codes are listed there and are not in error-codes.json.
+HTTP_STATUS: dict[str, int] = {
+    "SCHEMA_INVALID": 400,
+    "SIGNATURE_INVALID": 401,
+    "KEY_UNKNOWN": 401,
+    "GRANT_EXPIRED": 401,
+    "GRANT_PERMISSION_DENIED": 403,
+    "TARGET_NOT_VISIBLE": 404,
+    "IDEMPOTENCY_CONFLICT": 400,
+    "DUPLICATE": 409,
+    "EXPIRED": 410,
+    "POLICY_VIOLATION": 422,
+    "STALE_FENCE": 422,
+    "STALE_EPOCH": 422,
+    "OUT_OF_SCOPE": 422,
+    "NO_CAPACITY": 422,
+    "CONSENT_MISSING": 422,
+    "RATE_LIMITED": 429,
+    "DRAINING": 503,
+    "QUARANTINED": 503,
+    "SUSPENDED": 503,
+    "UPSTREAM_TIMEOUT": 504,
+    "AGENT_LOST_CUSTODY": 502,
+}
+
+
+class CapError(Exception):
+    """A CAP failure. ``body()`` matches ``specs/cap/error.json``."""
+
+    def __init__(self, code: str, message: str = "", msg_id: str | None = None) -> None:
+        self.code = code
+        self.message = message
+        self.msg_id = msg_id
+        super().__init__(code if not message else f"{code}: {message}")
+
+    def http_status(self) -> int:
+        try:
+            return HTTP_STATUS[self.code]
+        except KeyError as exc:
+            raise CapError("SCHEMA_INVALID", f"unknown error code {self.code}") from exc
+
+    def body(self) -> dict[str, str]:
+        payload: dict[str, str] = {"code": self.code}
+        if self.message:
+            payload["message"] = self.message
+        if self.msg_id is not None:
+            payload["msg_id"] = self.msg_id
+        return payload
+
+
+def http_status_for(code: str) -> int:
+    try:
+        return HTTP_STATUS[code]
+    except KeyError as exc:
+        raise CapError("SCHEMA_INVALID", f"unknown error code {code}") from exc

city_sdk-0.9.0/src/cap/core/generated/__init__.py

@@ -0,0 +1 @@
+"""Models produced by ``make gen``. Do not edit by hand."""

city_sdk-0.9.0/src/cap/core/generated/clients/agent.py

@@ -0,0 +1,163 @@
+# generated by datamodel-codegen:
+#   filename:  agent.yaml
+#   timestamp: 2026-10-10T14:29:54+00:00
+
+from __future__ import annotations
+from enum import Enum, StrEnum
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, RootModel, conint, constr
+from typing import Any, Literal
+from uuid import UUID
+
+
+class Status(Enum):
+    ok = "ok"
+    degraded = "degraded"
+    draining = "draining"
+    quarantined = "quarantined"
+
+
+class Policy(BaseModel):
+    epoch: int
+    digest: str
+    applied_at: AwareDatetime | None = None
+
+
+class Health(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    status: Status
+    agent_id: str
+    version: str
+    cap_versions: list[str]
+    profiles: list[str]
+    card_digest: str
+    policy: Policy | None = None
+    load: dict[str, Any] | None = None
+    build: dict[str, Any] | None = None
+    models: list[dict[str, Any]] | None = None
+    uptime_s: conint(ge=0)
+
+
+class Delivery1(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    msg_id: UUID
+    mailbox: str
+    fence: conint(ge=1)
+    attempt: conint(ge=1)
+    lease_until: AwareDatetime
+
+
+class Sig(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    alg: Literal["EdDSA"]
+    kid: str
+    grant: str | None = None
+    jws: str
+
+
+class Envelope(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    cap: Literal["1.0"]
+    profile: constr(pattern=r"^[a-z][a-z0-9-]*/[0-9]+\.[0-9]+$") | None = None
+    msg_id: UUID
+    type: constr(pattern=r"^[a-z][a-z0-9.-]*$")
+    from_: constr(pattern=r"^[a-z][a-z0-9-]*:[A-Za-z0-9][A-Za-z0-9._/-]*$") = Field(
+        ..., alias="from"
+    )
+    to: constr(pattern=r"^[a-z][a-z0-9-]*:[A-Za-z0-9][A-Za-z0-9._/-]*$")
+    conversation_id: constr(max_length=128) | None = None
+    need_id: constr(max_length=128) | None = None
+    in_reply_to: UUID | None = None
+    fence: conint(ge=1) | None = None
+    sent_at: AwareDatetime
+    expires_at: AwareDatetime | None = None
+    traceparent: constr(pattern=r"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$") | None = None
+    body: dict[str, Any]
+    sig: Sig
+
+
+class Status1(Enum):
+    processed = "processed"
+    received = "received"
+    rejected = "rejected"
+    retryable = "retryable"
+
+
+class DeliveryAck(BaseModel):
+    status: Status1
+    envelopes: list[Envelope] | None = None
+
+
+class Probe(StrEnum):
+    live = "live"
+    ready = "ready"
+
+
+class Error(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    code: constr(pattern=r"^[A-Z][A-Z0-9_]*$")
+    message: str | None = None
+    msg_id: UUID | None = None
+
+
+class Profile(RootModel[constr(pattern=r"^[a-z][a-z0-9-]*/[0-9]+\.[0-9]+$")]):
+    root: constr(pattern=r"^[a-z][a-z0-9-]*/[0-9]+\.[0-9]+$")
+
+
+class Endpoints(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    mailbox: str
+    send_via: str | None = None
+
+
+class Key(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    kid: str
+    kty: Literal["OKP"]
+    crv: Literal["Ed25519"]
+    x: str
+
+
+class Card(BaseModel):
+    agent_id: constr(pattern=r"^agent:[a-z0-9-]+/[a-z0-9-]+$")
+    team: constr(pattern=r"^team:[a-z0-9-]+$")
+    name: str
+    version: constr(pattern=r"^[0-9]+\.[0-9]+\.[0-9]+$")
+    cap_versions: list[Literal["1.0"]] = Field(..., min_length=1)
+    profiles: list[Profile] = Field(..., min_length=1)
+    data_processing: list[dict[str, Any]] | None = None
+    ai_act_transparency: str | None = None
+    governable: list[str] | None = None
+    max_inflight: conint(ge=1) | None = None
+    consent: dict[str, Any] | None = None
+    build: dict[str, Any] | None = None
+    dependencies: dict[str, Any] | None = None
+    endpoints: Endpoints
+    keys: list[Key] = Field(..., min_length=1)
+    grant: str | None = None
+    signatures: dict[str, Any] | None = None
+
+
+class AuditGetResponse(BaseModel):
+    entries: list[dict[str, Any]]
+
+
+class Delivery(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    delivery: Delivery1
+    envelope: Envelope

city_sdk-0.9.0/src/cap/core/generated/clients/attestation.py

@@ -0,0 +1,104 @@
+# generated by datamodel-codegen:
+#   filename:  attestation.yaml
+#   timestamp: 2026-10-10T14:29:54+00:00
+
+from __future__ import annotations
+from typing import Any, Literal
+from pydantic import AwareDatetime, BaseModel, ConfigDict, Field, RootModel, conint, constr
+from uuid import UUID
+
+
+class CityEvent1(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    record_kind: Literal["intent"]
+    record_id: str
+    observer: str
+    actor: str
+    subject: str | None = None
+    action: str
+    msg_type: str | None = None
+    msg_id: str | None = None
+    conversation_id: str | None = None
+    need_id: str | None = None
+    trace_id: str | None = None
+    time: AwareDatetime
+    envelope_digest: str | None = None
+    envelope_sig: str | None = None
+    payload_ref: str | None = None
+
+
+class CityEvent2(BaseModel):
+    model_config = ConfigDict(
+        extra="allow",
+    )
+    record_kind: Literal["event"]
+    record_id: str
+    observer: str
+    type: str
+    about_record: str | None = None
+    outcome: dict[str, Any] | None = None
+    transport_policy: str | None = None
+    time: AwareDatetime
+
+
+class CityEvent(RootModel[CityEvent1 | CityEvent2]):
+    root: CityEvent1 | CityEvent2 = Field(..., title="city-events record")
+
+
+class Sig(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    alg: Literal["EdDSA"]
+    kid: str
+    grant: str | None = None
+    jws: str
+
+
+class Envelope(BaseModel):
+    model_config = ConfigDict(
+        extra="forbid",
+    )
+    cap: Literal["1.0"]
+    profile: constr(pattern=r"^[a-z][a-z0-9-]*/[0-9]+\.[0-9]+$") | None = None
+    msg_id: UUID
+    type: constr(pattern=r"^[a-z][a-z0-9.-]*$")
+    from_: constr(pattern=r"^[a-z][a-z0-9-]*:[A-Za-z0-9][A-Za-z0-9._/-]*$") = Field(
+        ..., alias="from"
+    )
+    to: constr(pattern=r"^[a-z][a-z0-9-]*:[A-Za-z0-9][A-Za-z0-9._/-]*$")
+    conversation_id: constr(max_length=128) | None = None
+    need_id: constr(max_length=128) | None = None
+    in_reply_to: UUID | None = None
+    fence: conint(ge=1) | None = None
+    sent_at: AwareDatetime
+    expires_at: AwareDatetime | None = None
+    traceparent: constr(pattern=r"^00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$") | None = None
+    body: dict[str, Any]
+    sig: Sig
+
+
+class V1ProofRecordIdGetResponse(BaseModel):
+    record_id: str
+    seal: str
+    proof: list[str]
+
+
+class Seal(BaseModel):
+    seal_id: str
+    prev: str
+    root: str
+
+
+class V1SealsGetResponse(BaseModel):
+    seals: list[Seal]
+
+
+class V1RecordsGetResponse(BaseModel):
+    records: list[CityEvent]
+
+
+class V1ConversationsIdGetResponse(BaseModel):
+    envelopes: list[Envelope]