sentrykit 0.1.0rc1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. sentrykit/__init__.py +200 -0
  2. sentrykit/audit.py +967 -0
  3. sentrykit/cedar.py +750 -0
  4. sentrykit/cli.py +1405 -0
  5. sentrykit/config.py +300 -0
  6. sentrykit/constraints.py +928 -0
  7. sentrykit/context.py +393 -0
  8. sentrykit/decorator.py +252 -0
  9. sentrykit/engine.py +1509 -0
  10. sentrykit/envelope.py +513 -0
  11. sentrykit/errors.py +252 -0
  12. sentrykit/integrations/__init__.py +1 -0
  13. sentrykit/integrations/base.py +767 -0
  14. sentrykit/integrations/fastapi.py +361 -0
  15. sentrykit/integrations/flask.py +342 -0
  16. sentrykit/integrations/mcp.py +929 -0
  17. sentrykit/integrations/pydantic_ai.py +728 -0
  18. sentrykit/integrations/tools.py +479 -0
  19. sentrykit/masking.py +459 -0
  20. sentrykit/policy/__init__.py +40 -0
  21. sentrykit/policy/loader.py +764 -0
  22. sentrykit/policy/pack/10-rbac.cedar +9 -0
  23. sentrykit/policy/pack/20-groups.cedar +9 -0
  24. sentrykit/policy/pack/30-ownership.cedar +8 -0
  25. sentrykit/policy/pack/40-delegation.cedar +40 -0
  26. sentrykit/policy/pack/50-expiry.cedar +24 -0
  27. sentrykit/policy/pack/60-break-glass.cedar +34 -0
  28. sentrykit/policy/pack/70-separation-of-duties.cedar +22 -0
  29. sentrykit/policy/pack/80-jit-elevation.cedar +32 -0
  30. sentrykit/policy/pack/entities.json +3 -0
  31. sentrykit/policy/pack/pack.cedarschema +45 -0
  32. sentrykit/policy/pack/templates/time-boxed-grant.cedartemplate +5 -0
  33. sentrykit/py.typed +0 -0
  34. sentrykit/registry.py +666 -0
  35. sentrykit/stores/__init__.py +116 -0
  36. sentrykit/stores/base.py +870 -0
  37. sentrykit/stores/composite.py +635 -0
  38. sentrykit/stores/filesystem.py +400 -0
  39. sentrykit/stores/jsonfile.py +701 -0
  40. sentrykit/stores/jsonl.py +357 -0
  41. sentrykit/stores/memory.py +500 -0
  42. sentrykit-0.1.0rc1.dist-info/METADATA +541 -0
  43. sentrykit-0.1.0rc1.dist-info/RECORD +46 -0
  44. sentrykit-0.1.0rc1.dist-info/WHEEL +4 -0
  45. sentrykit-0.1.0rc1.dist-info/entry_points.txt +20 -0
  46. sentrykit-0.1.0rc1.dist-info/licenses/LICENSE +201 -0
sentrykit/errors.py ADDED
@@ -0,0 +1,252 @@
1
+ """Exception hierarchy for sentrykit.
2
+
3
+ Every error carries structured, machine-readable detail so context providers can render a
4
+ useful response (and so the audit record is precise). Never raise a bare ``Exception``.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from typing import Any
10
+
11
+
12
+ class SentrykitError(Exception):
13
+ """Base class for all sentrykit errors.
14
+
15
+ When :attr:`audit_failure` is set, both halves of it matter. The refusal is *correct*: it
16
+ is the one the decision produced, it stands, and it is not softened because nobody could
17
+ write it down — deciding and recording are separate guarantees, and losing the second does
18
+ not forfeit the first. And the refusal is *unrecorded*: there is no audit record that this
19
+ boundary was tested, so nothing in the trail will later show a caller probing which
20
+ actions exist and which argument values are accepted.
21
+
22
+ It lives on the base class because any refusal can arrive this way, and it travels with
23
+ the exception so that whoever renders the refusal — a provider's response, a host's own
24
+ error handler, a report — can say so at the point a reader is looking. The alternative is
25
+ to leave the fact in an operational log, and the operational channel is deliberately not
26
+ the audit trail: a fact that only ever lands there is a fact nobody can prove afterwards.
27
+
28
+ Attributes:
29
+ audit_failure: The audit sink failure that stopped this refusal from being recorded,
30
+ or ``None`` — which is what it is on every refusal a reachable sink accepted, so
31
+ on all but a vanishing fraction of them.
32
+ """
33
+
34
+ audit_failure: AuditUnavailable | None = None
35
+
36
+
37
+ class ConfigurationError(SentrykitError):
38
+ """Raised when sentrykit is misconfigured (bad settings, missing backend, etc.)."""
39
+
40
+
41
+ class NoContext(SentrykitError):
42
+ """Raised when a protected callable is invoked with no resolvable principal.
43
+
44
+ This is a fail-closed condition: no ambient context and no explicit override means the
45
+ call is denied.
46
+ """
47
+
48
+ def __init__(self, action: str) -> None:
49
+ self.action = action
50
+ super().__init__(f"no principal in context for action {action!r}; denying (fail-closed)")
51
+
52
+
53
+ class AuthzDenied(SentrykitError):
54
+ """Raised when the coarse Cedar gate denies the invocation.
55
+
56
+ ``engine_errors`` separates the two ways a call can fail to be authorized. A plain
57
+ denial has none: a policy said no, or no policy said yes. A denial carrying engine
58
+ errors means Cedar could not evaluate cleanly -- an unparseable policy, a missing
59
+ attribute -- and ``fail_mode="closed"`` turned that failure into a refusal. Operators
60
+ need to tell those apart, because the second is a bug in the policy set, not a correctly
61
+ enforced boundary.
62
+ """
63
+
64
+ def __init__(
65
+ self,
66
+ action: str,
67
+ resource: str | None,
68
+ determining_policies: list[str],
69
+ engine_errors: list[str] | None = None,
70
+ ) -> None:
71
+ """Record a refusal.
72
+
73
+ Args:
74
+ action: The full Cedar uid of the refused action, e.g. ``Action::"tool.search"``
75
+ -- always the uid spelling, never the bare id, so an error message is
76
+ unambiguous about which entity type was involved.
77
+ resource: The full Cedar uid of the resource, in the same spelling.
78
+ determining_policies: Ids of the policies that decided it, named by their ``@id``
79
+ annotation where they declare one. Empty on a default deny, which means no
80
+ policy matched at all.
81
+ engine_errors: Cedar's own errors when this refusal came from an engine failure,
82
+ and empty when it is an ordinary policy denial.
83
+ """
84
+ self.action = action
85
+ self.resource = resource
86
+ self.determining_policies = determining_policies
87
+ self.engine_errors = engine_errors or []
88
+ detail = (
89
+ f"denied: action={action!r} resource={resource!r} "
90
+ f"determining_policies={determining_policies}"
91
+ )
92
+ if self.engine_errors:
93
+ detail += f" engine_errors={self.engine_errors}"
94
+ super().__init__(detail)
95
+
96
+
97
+ class ReservedKey(SentrykitError):
98
+ """Raised when caller-supplied data spells one of Cedar's reserved ``__`` keys.
99
+
100
+ Cedar's request JSON reserves record keys beginning with ``__`` for its own escape
101
+ forms: ``__entity`` promotes a plain record into a typed entity reference, and
102
+ ``__extn`` into an extension value. A caller who can put either key inside an argument
103
+ can therefore hand the evaluator an entity reference of their own choosing, and an
104
+ argument-aware ``forbid`` will read it as a genuine one -- so
105
+ ``forbid ... when { !(context.args.region in Group::"approved") }`` is satisfied by
106
+ passing the approved group itself as the region, because Cedar's ``in`` is reflexive.
107
+
108
+ sentrykit refuses the request instead of deciding it, and the refusal is deliberately
109
+ *not* arbitrated by ``fail_mode``: a forged request is not a broken policy set, and
110
+ ``fail_mode="open"`` exists to tolerate operator error, never caller input.
111
+
112
+ This closes the *spelling*, not the general question of who chooses an entity's type. A
113
+ parameter a callable annotates as :class:`~sentrykit.cedar.EntityRef` is a caller-chosen
114
+ entity by construction, and the same reflexive ``in`` applies to it -- see
115
+ :func:`~sentrykit.cedar.coerce_value` for how a policy pins that down.
116
+
117
+ Attributes:
118
+ key: The reserved key that was supplied.
119
+ path: Where it appeared inside the request context, e.g. ``args.region`` or
120
+ ``args.regions[2].id``. Empty when the value was coerced on its own.
121
+ """
122
+
123
+ def __init__(self, key: str, path: str = "") -> None:
124
+ self.key = key
125
+ self.path = path
126
+ located = f" at {path!r}" if path else ""
127
+ super().__init__(
128
+ f"reserved key {key!r}{located} is not permitted in supplied data: keys "
129
+ "beginning with '__' are Cedar's own escape forms and may not be spelled by "
130
+ "a caller"
131
+ )
132
+
133
+
134
+ class ArgumentRejected(SentrykitError):
135
+ """Raised (in strict mode) when a supplied argument violates its policy constraint."""
136
+
137
+ def __init__(self, name: str, reason: str, policy: str | None = None) -> None:
138
+ self.name = name
139
+ self.reason = reason
140
+ self.policy = policy
141
+ super().__init__(f"argument {name!r} rejected: {reason}")
142
+
143
+
144
+ class SignatureDefaultRejected(SentrykitError):
145
+ """Raised when the only value left for a governed argument is one the policy refuses.
146
+
147
+ The argument has a constraint, nothing the caller supplied survived it, no policy default
148
+ applies — and the callable's own signature default does not satisfy the constraint either.
149
+ Python would otherwise fill the slot from that default, which is how a bound could be
150
+ exceeded by a value no rule ever saw.
151
+
152
+ This is the same rule a *policy* default has always been held to: a default is checked
153
+ against the constraint that governs it, so omitting an argument is not a way around that
154
+ rule. A signature default is a default from a different source, and it answers to the
155
+ same check.
156
+
157
+ ``declared`` says whose mistake it is. When it is true the refusing rule came from an
158
+ argument ceiling — reviewed, version-controlled policy text — so the operator's policy file
159
+ and their application code disagree about the same parameter, and every caller of the
160
+ action is affected equally. When it is false the rule came from this principal's own grant
161
+ data, so the refusal is specific to them and is ordinary authorization rather than a
162
+ misconfiguration.
163
+
164
+ Not a :class:`ConfigurationError` even in the ``declared`` case, for two reasons: it
165
+ refuses one call rather than failing the wiring, and there is no moment at which it could
166
+ fail the wiring instead, since nothing enumerates protected callables for a policy load to
167
+ check against. Classifying it with configuration faults would also make it unqueryable in
168
+ the audit trail, where it has its own outcome.
169
+ """
170
+
171
+ def __init__(
172
+ self, name: str, reason: str, policy: str | None = None, *, declared: bool = False
173
+ ) -> None:
174
+ """Record the refusal.
175
+
176
+ Args:
177
+ name: The governed parameter with no usable value.
178
+ reason: Why the signature default was refused, from the rejection that produced
179
+ it — the rule's own sentence, so the caller reads the same explanation they
180
+ would have got had they proposed the value themselves.
181
+ policy: Id of the grant or the reviewed policy that carried the constraint.
182
+ declared: Whether that constraint came from an argument ceiling rather than from
183
+ grant data.
184
+ """
185
+ self.name = name
186
+ self.reason = reason
187
+ self.policy = policy
188
+ self.declared = declared
189
+ source = "a reviewed argument ceiling" if declared else "this principal's grant"
190
+ super().__init__(
191
+ f"argument {name!r} has no value that may be used: nothing the caller supplied "
192
+ f"survived, no policy default applies, and the callable's own default is refused "
193
+ f"by {source} ({reason})"
194
+ )
195
+
196
+
197
+ class NoValidArguments(SentrykitError):
198
+ """Raised when the caller supplied arguments and the policy rejected every one of them.
199
+
200
+ Deliberately raised even when defaults could complete the call. Filling in defaults after
201
+ discarding everything the caller asked for would answer a question they did not ask --
202
+ the caller wanted orders for one customer and would silently get their own. Partial
203
+ rejection is different: some of the request stood, so narrowing the rest to what the
204
+ principal is entitled to is a refinement rather than a substitution.
205
+
206
+ ``allowed`` describes what the principal *may* pass, so the caller can retry correctly.
207
+ """
208
+
209
+ def __init__(self, allowed: dict[str, Any], rejected: list[dict[str, Any]]) -> None:
210
+ self.allowed = allowed
211
+ self.rejected = rejected
212
+ super().__init__("no valid arguments remain after policy filtering")
213
+
214
+
215
+ class DefaultUnavailable(SentrykitError):
216
+ """Raised when a required argument is missing and no policy default is configured."""
217
+
218
+ def __init__(self, name: str) -> None:
219
+ self.name = name
220
+ super().__init__(f"argument {name!r} is required but no policy default is configured")
221
+
222
+
223
+ class ValidationFailed(SentrykitError):
224
+ """Raised when the filtered/defaulted arguments fail the callable's pydantic model.
225
+
226
+ ``errors`` mirrors pydantic's structured ``ValidationError.errors()`` output.
227
+ """
228
+
229
+ def __init__(self, errors: list[dict[str, Any]]) -> None:
230
+ self.errors = errors
231
+ super().__init__(f"argument validation failed with {len(errors)} error(s)")
232
+
233
+
234
+ class AuditUnavailable(SentrykitError):
235
+ """Raised when an audit record could not be written to its sink.
236
+
237
+ An operational failure, not an authorization one — but under ``fail_mode="closed"`` it
238
+ still refuses the governed call, because an action nobody can prove happened is an action
239
+ that should not have happened ("can't prove it, don't do it", per the logging standards).
240
+
241
+ ``sink`` names the backend that failed; ``failures`` carries one entry per sink when a
242
+ fan-out composite raised, so an operator can see whether one replica or all of them are
243
+ down.
244
+ """
245
+
246
+ def __init__(
247
+ self, sink: str, reason: str, failures: list[dict[str, Any]] | None = None
248
+ ) -> None:
249
+ self.sink = sink
250
+ self.reason = reason
251
+ self.failures = failures or []
252
+ super().__init__(f"audit sink {sink!r} could not accept the record: {reason}")
@@ -0,0 +1 @@
1
+ """Framework context providers, each behind its own optional extra."""