-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathmodels.py
More file actions
113 lines (97 loc) · 3.9 KB
/
Copy pathmodels.py
File metadata and controls
113 lines (97 loc) · 3.9 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
from __future__ import annotations
from dataclasses import dataclass
@dataclass(frozen=True)
class DelegationRecord:
"""A record of an agent delegation.
Business Logic: This represents one step in the 'chain of trust'.
When an agent delegates authority, it creates a new token that carries
the identity of the delegator. The broker uses these records to
enforce the maximum delegation depth (5) and to ensure that authority
cannot widen across hops — equal or narrower scope is accepted; any
scope the delegator doesn't hold is rejected.
"""
agent: str # SPIFFE ID of delegator
scope: list[str]
delegated_at: str # RFC 3339
@dataclass(frozen=True)
class AgentClaims:
"""Mirrors TknClaims from internal/token/tkn_claims.go.
Business Logic: These claims represent the 'identity' and 'authority'
of an ephemeral agent. Unlike a standard user JWT, these claims
explicitly include `orch_id` and `task_id` to tie the agent's lifecycle
to a specific unit of work in the developer's orchestration system.
The `sub` field is a SPIFFE URI, ensuring the agent is a first-class
identity in the trust domain.
"""
iss: str # broker-configured issuer
sub: str # SPIFFE URI
aud: list[str]
exp: int # Unix timestamp
nbf: int # Unix timestamp
iat: int # Unix timestamp
jti: str # unique token ID
scope: list[str]
task_id: str
orch_id: str
sid: str | None = None
delegation_chain: list[DelegationRecord] | None = None
chain_hash: str | None = None
@dataclass(frozen=True)
class ValidateResult:
"""The result of a token validation check via POST /v1/token/validate.
Business Logic: This is the authoritative way for a resource server
or the App to verify if an agent is still trusted. Because validation
is performed by the broker, it catches not just malformed tokens,
but also tokens that have been revoked by an operator or via `release()`.
"""
valid: bool
claims: AgentClaims | None = None
error: str | None = None
@dataclass(frozen=True)
class DelegatedToken:
"""A token received via an agent's delegate() call.
Business Logic: This is a 'sub-token' that carries a subset of the
original agent's authority. It is designed for 'least-privilege'
workflows where a primary agent (e.g., a Researcher) delegates
a specific, narrow task to a secondary agent (e.g., a Tool-User).
"""
access_token: str
expires_in: int
delegation_chain: list[DelegationRecord]
@dataclass(frozen=True)
class RegisterResult:
"""Result of an agent registration attempt via POST /v1/register.
Business Logic: This is the outcome of the Ed25519 challenge-response
ceremony. A successful registration results in a unique, ephemeral
identity (SPIFFE ID) and a short-lived access token.
"""
agent_id: str # SPIFFE URI
access_token: str
expires_in: int
@dataclass(frozen=True)
class HealthStatus:
"""The current health status of the broker.
Business Logic: Provides high-level visibility into whether the
broker is ready to accept new registrations or validate tokens.
"""
status: str # "ok"
version: str # e.g. "2.0.0"
uptime: int # seconds
db_connected: bool
audit_events_count: int
@dataclass(frozen=True)
class ProblemDetail:
"""RFC 7807 problem detail from broker error responses.
Business Logic: Standardized error reporting. This allows the SDK
to translate cryptic HTTP failures into meaningful developer
messages that explain *why* a business rule was violated
(e.g., "Scope ceiling violation").
"""
type: str
title: str
detail: str
instance: str
status: int | None = None
error_code: str | None = None
request_id: str | None = None
hint: str | None = None