lorebase-keeper 0.2.3__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 (126) hide show
  1. lorebase_keeper/__init__.py +1 -0
  2. lorebase_keeper/__main__.py +456 -0
  3. lorebase_keeper/agents/__init__.py +1 -0
  4. lorebase_keeper/agents/budget.py +247 -0
  5. lorebase_keeper/agents/context.py +529 -0
  6. lorebase_keeper/agents/explain.py +582 -0
  7. lorebase_keeper/agents/feed.py +259 -0
  8. lorebase_keeper/agents/markdown.py +219 -0
  9. lorebase_keeper/agents/pack.py +403 -0
  10. lorebase_keeper/agents/settings.py +111 -0
  11. lorebase_keeper/app.py +373 -0
  12. lorebase_keeper/auth/__init__.py +4 -0
  13. lorebase_keeper/auth/api_keys.py +127 -0
  14. lorebase_keeper/auth/audit.py +356 -0
  15. lorebase_keeper/auth/cache.py +53 -0
  16. lorebase_keeper/auth/config.py +618 -0
  17. lorebase_keeper/auth/deps.py +183 -0
  18. lorebase_keeper/auth/keyring.py +14 -0
  19. lorebase_keeper/auth/oidc.py +242 -0
  20. lorebase_keeper/auth/permissions.py +142 -0
  21. lorebase_keeper/auth/ports.py +212 -0
  22. lorebase_keeper/auth/principals.py +377 -0
  23. lorebase_keeper/auth/provider.py +250 -0
  24. lorebase_keeper/auth/rbac.py +247 -0
  25. lorebase_keeper/auth/read_audit.py +357 -0
  26. lorebase_keeper/auth/runtime.py +113 -0
  27. lorebase_keeper/auth/sessions.py +452 -0
  28. lorebase_keeper/bootstrap.py +151 -0
  29. lorebase_keeper/client_address.py +129 -0
  30. lorebase_keeper/context.py +226 -0
  31. lorebase_keeper/db.py +93 -0
  32. lorebase_keeper/deps.py +47 -0
  33. lorebase_keeper/errors.py +257 -0
  34. lorebase_keeper/health.py +61 -0
  35. lorebase_keeper/kindhealth/__init__.py +6 -0
  36. lorebase_keeper/kindhealth/config.py +51 -0
  37. lorebase_keeper/kindhealth/markdown.py +163 -0
  38. lorebase_keeper/kindhealth/models.py +179 -0
  39. lorebase_keeper/kindhealth/report.py +154 -0
  40. lorebase_keeper/kindhealth/scan.py +512 -0
  41. lorebase_keeper/middleware.py +285 -0
  42. lorebase_keeper/pagination.py +87 -0
  43. lorebase_keeper/ratelimit/__init__.py +10 -0
  44. lorebase_keeper/ratelimit/bucket.py +118 -0
  45. lorebase_keeper/ratelimit/config.py +283 -0
  46. lorebase_keeper/ratelimit/enforce.py +393 -0
  47. lorebase_keeper/ratelimit/limiter.py +149 -0
  48. lorebase_keeper/ratelimit/quotas.py +204 -0
  49. lorebase_keeper/ratelimit/shared.py +242 -0
  50. lorebase_keeper/readiness.py +257 -0
  51. lorebase_keeper/reading/__init__.py +1 -0
  52. lorebase_keeper/reading/caching.py +251 -0
  53. lorebase_keeper/reading/compiler.py +678 -0
  54. lorebase_keeper/reading/cursors.py +56 -0
  55. lorebase_keeper/reading/diff.py +408 -0
  56. lorebase_keeper/reading/graph.py +268 -0
  57. lorebase_keeper/reading/history.py +152 -0
  58. lorebase_keeper/reading/points.py +410 -0
  59. lorebase_keeper/reading/problems.py +74 -0
  60. lorebase_keeper/reading/record_history.py +722 -0
  61. lorebase_keeper/reading/records.py +780 -0
  62. lorebase_keeper/reading/requests.py +107 -0
  63. lorebase_keeper/reading/runtime.py +145 -0
  64. lorebase_keeper/reading/search.py +708 -0
  65. lorebase_keeper/reading/sensitivity.py +882 -0
  66. lorebase_keeper/reading/settings.py +339 -0
  67. lorebase_keeper/reading/snapshots.py +148 -0
  68. lorebase_keeper/reading/tree.py +98 -0
  69. lorebase_keeper/reading/views.py +264 -0
  70. lorebase_keeper/reading/visibility.py +93 -0
  71. lorebase_keeper/routes/__init__.py +1 -0
  72. lorebase_keeper/routes/admin.py +597 -0
  73. lorebase_keeper/routes/agents.py +160 -0
  74. lorebase_keeper/routes/branches.py +438 -0
  75. lorebase_keeper/routes/derivations.py +215 -0
  76. lorebase_keeper/routes/documents.py +497 -0
  77. lorebase_keeper/routes/domain_api.py +59 -0
  78. lorebase_keeper/routes/domains.py +220 -0
  79. lorebase_keeper/routes/events.py +187 -0
  80. lorebase_keeper/routes/kind_health.py +166 -0
  81. lorebase_keeper/routes/operations.py +392 -0
  82. lorebase_keeper/routes/proposal_items.py +563 -0
  83. lorebase_keeper/routes/proposals.py +1107 -0
  84. lorebase_keeper/routes/read.py +493 -0
  85. lorebase_keeper/routes/revisions.py +523 -0
  86. lorebase_keeper/routes/schema.py +682 -0
  87. lorebase_keeper/routes/schema_inference.py +437 -0
  88. lorebase_keeper/routes/schema_suggestions.py +328 -0
  89. lorebase_keeper/routes/sessions.py +286 -0
  90. lorebase_keeper/routes/source_preview.py +232 -0
  91. lorebase_keeper/routes/sources.py +200 -0
  92. lorebase_keeper/routes/trace.py +506 -0
  93. lorebase_keeper/routes/vault.py +332 -0
  94. lorebase_keeper/routes/webhooks.py +298 -0
  95. lorebase_keeper/routes/whoami.py +88 -0
  96. lorebase_keeper/services/__init__.py +1 -0
  97. lorebase_keeper/services/agent_writes.py +1035 -0
  98. lorebase_keeper/services/branches.py +337 -0
  99. lorebase_keeper/services/config.py +431 -0
  100. lorebase_keeper/services/derivation_preview.py +279 -0
  101. lorebase_keeper/services/document_urls.py +114 -0
  102. lorebase_keeper/services/domains.py +118 -0
  103. lorebase_keeper/services/errors.py +196 -0
  104. lorebase_keeper/services/operation_catalog.py +806 -0
  105. lorebase_keeper/services/operation_events.py +199 -0
  106. lorebase_keeper/services/operations.py +1229 -0
  107. lorebase_keeper/services/pii_import.py +222 -0
  108. lorebase_keeper/services/proposal_reads.py +158 -0
  109. lorebase_keeper/services/proposals.py +850 -0
  110. lorebase_keeper/services/reads.py +286 -0
  111. lorebase_keeper/services/schema.py +601 -0
  112. lorebase_keeper/services/schema_inference.py +390 -0
  113. lorebase_keeper/services/schema_suggestions.py +418 -0
  114. lorebase_keeper/services/source_preview.py +127 -0
  115. lorebase_keeper/settings.py +313 -0
  116. lorebase_keeper/tracing/__init__.py +1 -0
  117. lorebase_keeper/tracing/capture.py +350 -0
  118. lorebase_keeper/tracing/config.py +157 -0
  119. lorebase_keeper/tracing/explain.py +97 -0
  120. lorebase_keeper/tracing/middleware.py +359 -0
  121. lorebase_keeper/tracing/notes.py +80 -0
  122. lorebase_keeper/tracing/recorder.py +180 -0
  123. lorebase_keeper-0.2.3.dist-info/METADATA +21 -0
  124. lorebase_keeper-0.2.3.dist-info/RECORD +126 -0
  125. lorebase_keeper-0.2.3.dist-info/WHEEL +4 -0
  126. lorebase_keeper-0.2.3.dist-info/entry_points.txt +2 -0
@@ -0,0 +1,286 @@
1
+ """Authorization of reads against the Revision actually read (design 10.2).
2
+
3
+ Every read path (records and links, query and search, Revisions, log and diff, schema, branch
4
+ listings) resolves what it reads first and then checks the permission against it:
5
+
6
+ - a grant not narrowed to a branch (Domain-wide, or narrowed to the Kind being read) covers
7
+ every Revision; a grant narrowed to a Kind covers only that Kind, so the record reads
8
+ check every Kind a request touches against `ReadGuard.granted_kinds`;
9
+ - a branch, or `at` / a diff side naming a branch, is checked with
10
+ `AccessContext(branch=<that branch>)`;
11
+ - a tag or a bare Revision id is a pointer into the history: it is allowed when the caller may
12
+ read some branch from whose head the Revision is reachable, following parents for at most
13
+ `keeper.reads.reachability_max_depth` hops.
14
+
15
+ Callers with narrowed grants get 403 for everything they may not read, including unknown names
16
+ and Revisions, so the answer does not tell whether a Revision exists.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ from collections.abc import Collection, Iterable, Mapping, Sequence
22
+ from dataclasses import dataclass
23
+ from typing import Protocol
24
+
25
+ from sqlalchemy.ext.asyncio import AsyncSession
26
+
27
+ from lorebase_keeper.auth.deps import missing_permission, refusal
28
+ from lorebase_keeper.auth.permissions import Permission
29
+ from lorebase_keeper.auth.principals import Principal
30
+ from lorebase_keeper.auth.rbac import AccessContext, Authorizer
31
+ from lorebase_keeper.context import StoreAccess, require_domain, resolve_revision
32
+ from lorebase_keeper.errors import FORBIDDEN, ProblemError
33
+ from lorebase_store.models.enums import RefKind
34
+ from lorebase_store.repositories import DomainRow, RefRepository, RevisionRepository
35
+
36
+
37
+ @dataclass(frozen=True)
38
+ class ReadTarget:
39
+ """What a read resolved to: a Revision, and the ref it was read through (none for a bare
40
+ Revision id)."""
41
+
42
+ revision: bytes
43
+ ref: str | None = None
44
+ kind: RefKind | None = None
45
+
46
+
47
+ class ReadSource(Protocol):
48
+ """The store as seen by read authorization, inside one transaction."""
49
+
50
+ async def lookup(self, *, branch: str | None, at: str | None) -> ReadTarget:
51
+ """Resolve a branch (default: the Domain's) or `at` (Revision id, tag or branch name);
52
+ a 404 `ProblemError` when unknown."""
53
+ ...
54
+
55
+ async def branch_heads(self) -> Mapping[str, bytes]:
56
+ """Head Revision of every branch of the Domain."""
57
+ ...
58
+
59
+ async def parents(self, revision: bytes) -> Sequence[bytes]: ...
60
+
61
+ async def generations(self, revisions: Iterable[bytes]) -> Mapping[bytes, int]: ...
62
+
63
+
64
+ class StoreReadSource:
65
+ """`ReadSource` over the repositories of one Domain."""
66
+
67
+ def __init__(self, session: AsyncSession, domain: DomainRow) -> None:
68
+ self._session = session
69
+ self._domain = domain
70
+ self._revisions = RevisionRepository(session, domain.id)
71
+
72
+ async def lookup(self, *, branch: str | None, at: str | None) -> ReadTarget:
73
+ resolved = await resolve_revision(self._session, self._domain, branch=branch, at=at)
74
+ ref = resolved.ref
75
+ return ReadTarget(
76
+ revision=resolved.revision.id,
77
+ ref=None if ref is None else ref.name,
78
+ kind=None if ref is None else ref.kind,
79
+ )
80
+
81
+ async def branch_heads(self) -> Mapping[str, bytes]:
82
+ refs = await RefRepository(self._session, self._domain.id).all(RefKind.BRANCH)
83
+ return {ref.name: ref.head for ref in refs}
84
+
85
+ async def parents(self, revision: bytes) -> Sequence[bytes]:
86
+ return await self._revisions.parents(revision)
87
+
88
+ async def generations(self, revisions: Iterable[bytes]) -> Mapping[bytes, int]:
89
+ return await self._revisions.generations(revisions)
90
+
91
+
92
+ async def reachable(
93
+ source: ReadSource, heads: Collection[bytes], target: bytes, max_depth: int
94
+ ) -> bool:
95
+ """Whether `target` is one of `heads` or an ancestor of one within `max_depth` parent hops."""
96
+ floor = (await source.generations([target])).get(target)
97
+ if floor is None:
98
+ return False
99
+ frontier = set(heads)
100
+ seen = set(frontier)
101
+ for depth in range(max_depth + 1):
102
+ if target in frontier:
103
+ return True
104
+ if depth == max_depth or not frontier:
105
+ return False
106
+ generations = await source.generations(frontier)
107
+ # Only a Revision above the target in the history can have it as an ancestor.
108
+ above = [r for r in frontier if generations.get(r, -1) > floor]
109
+ parents = {p for r in above for p in await source.parents(r)}
110
+ frontier = parents - seen
111
+ seen |= frontier
112
+ return False
113
+
114
+
115
+ @dataclass(frozen=True)
116
+ class ReadGuard:
117
+ """A caller reading one Domain, whose permissions are checked against what is read.
118
+
119
+ `kind` is the Kind the request reads, when it names one, so grants narrowed to that Kind
120
+ apply.
121
+ """
122
+
123
+ authorizer: Authorizer
124
+ principal: Principal
125
+ permissions: tuple[Permission, ...]
126
+ domain_id: str
127
+ max_depth: int
128
+ kind: str | None = None
129
+
130
+ async def may(self, branch: str | None = None) -> bool:
131
+ """Every permission for `branch`; `None` asks for grants not narrowed to branches."""
132
+ context = AccessContext(kind=self.kind, branch=branch)
133
+ return all(
134
+ [
135
+ await self.authorizer.allows(self.principal, p, self.domain_id, context)
136
+ for p in self.permissions
137
+ ]
138
+ )
139
+
140
+ async def wide(self) -> bool:
141
+ """Whether the grants cover every Revision (none of them is narrowed to branches)."""
142
+ return await self.may(None)
143
+
144
+ async def require_wide(self) -> None:
145
+ """403 unless the grants cover the whole Domain: for Domain-wide reads (Source runs)
146
+ that grants narrowed to a Kind or a branch must not see."""
147
+ if not await self.wide():
148
+ raise self.denied()
149
+
150
+ async def granted_kinds(self) -> frozenset[str]:
151
+ """Kinds the caller may read through grants narrowed to a Kind: every Revision, those
152
+ Kinds only."""
153
+ found: frozenset[str] | None = None
154
+ for permission in self.permissions:
155
+ kinds = await self.authorizer.granted_kinds(self.principal, permission, self.domain_id)
156
+ found = kinds if found is None else found & kinds
157
+ return found or frozenset()
158
+
159
+ def kind_denied(self, kind: str) -> ProblemError:
160
+ """403 for a Kind outside the Kinds a Kind-narrowed caller may read."""
161
+ permission = self.permissions[0]
162
+ return ProblemError(
163
+ FORBIDDEN,
164
+ f"Missing permission {permission.value} on Kind {kind} in Domain {self.domain_id}.",
165
+ extensions={"permission": permission.value, "domain": self.domain_id, "kind": kind},
166
+ )
167
+
168
+ async def precheck(self) -> None:
169
+ """403 before any lookup when no grant of the caller holds a permission at all; 404
170
+ instead when the Domain does not exist and the caller may be told so."""
171
+ for permission in self.permissions:
172
+ if not await self.authorizer.allows_anywhere(
173
+ self.principal, permission, self.domain_id
174
+ ):
175
+ raise await refusal(self.authorizer, self.principal, permission, self.domain_id)
176
+
177
+ def denied(self) -> ProblemError:
178
+ return missing_permission(self.permissions[0], self.domain_id)
179
+
180
+ async def require_branch(self, name: str) -> None:
181
+ if not await self.may(name):
182
+ raise self.denied()
183
+
184
+ async def require(self, source: ReadSource, target: ReadTarget, *, wide: bool) -> None:
185
+ """Require the permissions for the Revision `target` resolved to (see module doc)."""
186
+ if wide:
187
+ return
188
+ if target.kind is RefKind.BRANCH:
189
+ assert target.ref is not None
190
+ await self.require_branch(target.ref)
191
+ return
192
+ readable = [
193
+ head for name, head in (await source.branch_heads()).items() if await self.may(name)
194
+ ]
195
+ if readable and await reachable(source, readable, target.revision, self.max_depth):
196
+ return
197
+ raise self.denied()
198
+
199
+ def unknown(self, error: ProblemError, *, wide: bool) -> ProblemError:
200
+ """The answer to a lookup that found nothing: the 404 itself only for wide callers."""
201
+ if wide or error.status_code != 404:
202
+ return error
203
+ return self.denied()
204
+
205
+
206
+ async def authorize_read(
207
+ source: ReadSource,
208
+ authorizer: Authorizer,
209
+ principal: Principal,
210
+ permissions: Sequence[Permission],
211
+ domain_id: str,
212
+ *,
213
+ branch: str | None,
214
+ at: str | None,
215
+ wide: bool,
216
+ max_depth: int,
217
+ kind: str | None = None,
218
+ ) -> ReadTarget:
219
+ """Resolve `branch`/`at` and require every permission for the Revision it resolved to.
220
+
221
+ `wide` tells whether the caller holds the permissions through grants not narrowed to
222
+ branches, which cover every Revision; the lookup then answers 404 for unknown names.
223
+ Otherwise unknown names are refused as forbidden, like Revisions the caller may not read.
224
+ """
225
+ guard = ReadGuard(authorizer, principal, tuple(permissions), domain_id, max_depth, kind)
226
+ try:
227
+ target = await source.lookup(branch=branch, at=at)
228
+ except ProblemError as error:
229
+ raise guard.unknown(error, wide=wide) from None
230
+ await guard.require(source, target, wide=wide)
231
+ return target
232
+
233
+
234
+ async def resolve_readable(
235
+ store: StoreAccess,
236
+ authorizer: Authorizer,
237
+ principal: Principal,
238
+ permissions: Sequence[Permission],
239
+ domain_id: str,
240
+ *,
241
+ branch: str | None,
242
+ at: str | None,
243
+ max_depth: int,
244
+ kind: str | None = None,
245
+ ) -> ReadTarget:
246
+ """The Revision a request reads, after requiring `permissions` for it.
247
+
248
+ 403 (naming the first permission) when the caller lacks them for what `branch`/`at`
249
+ resolve to; 404 for unknown names only to callers whose grants are Domain-wide.
250
+ """
251
+ guard = ReadGuard(authorizer, principal, tuple(permissions), domain_id, max_depth, kind)
252
+ await guard.precheck()
253
+ wide = await guard.wide()
254
+ try:
255
+ async with store.sessions() as session, session.begin():
256
+ domain = await require_domain(session, domain_id)
257
+ return await authorize_read(
258
+ StoreReadSource(session, domain),
259
+ authorizer,
260
+ principal,
261
+ permissions,
262
+ domain_id,
263
+ branch=branch,
264
+ at=at,
265
+ wide=wide,
266
+ max_depth=max_depth,
267
+ kind=kind,
268
+ )
269
+ except ProblemError as error:
270
+ raise guard.unknown(error, wide=wide) from None
271
+
272
+
273
+ async def resolve_kind_limited(
274
+ store: StoreAccess, guard: ReadGuard, *, branch: str | None, at: str | None
275
+ ) -> ReadTarget:
276
+ """The Revision a caller holding grants narrowed to Kinds reads (they cover every branch
277
+ and Revision, for those Kinds). Unknown Domains, branches and Revisions answer 403, like
278
+ names the caller may not read."""
279
+ try:
280
+ async with store.sessions() as session, session.begin():
281
+ domain = await require_domain(session, guard.domain_id)
282
+ return await StoreReadSource(session, domain).lookup(branch=branch, at=at)
283
+ except ProblemError as error:
284
+ if error.status_code == 404:
285
+ raise guard.denied() from None
286
+ raise