@withgateway/sdk 0.3.3 → 0.4.0

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 (123) hide show
  1. package/README.md +4 -3
  2. package/dist/cli.js +2221 -962
  3. package/dist/cli.js.map +1 -1
  4. package/dist/cli.mjs +2212 -953
  5. package/dist/cli.mjs.map +1 -1
  6. package/dist/files/index.js +81 -19
  7. package/dist/files/index.js.map +1 -1
  8. package/dist/files/index.mjs +79 -17
  9. package/dist/files/index.mjs.map +1 -1
  10. package/dist/hooks/index.d.mts +1 -1
  11. package/dist/hooks/index.d.ts +1 -1
  12. package/dist/hooks/index.js +124 -11
  13. package/dist/hooks/index.js.map +1 -1
  14. package/dist/hooks/index.mjs +124 -11
  15. package/dist/hooks/index.mjs.map +1 -1
  16. package/dist/{index-C3UzD0G3.d.mts → index-CDPQBsU5.d.mts} +19 -3
  17. package/dist/{index-C3UzD0G3.d.ts → index-CDPQBsU5.d.ts} +19 -3
  18. package/dist/index.d.mts +2 -2
  19. package/dist/index.d.ts +2 -2
  20. package/dist/index.js +903 -221
  21. package/dist/index.js.map +1 -1
  22. package/dist/index.mjs +868 -212
  23. package/dist/index.mjs.map +1 -1
  24. package/dist/traces/index.js +78 -16
  25. package/dist/traces/index.js.map +1 -1
  26. package/dist/traces/index.mjs +76 -14
  27. package/dist/traces/index.mjs.map +1 -1
  28. package/dist/tracing/index.js +7 -1
  29. package/dist/tracing/index.js.map +1 -1
  30. package/dist/tracing/index.mjs +7 -1
  31. package/dist/tracing/index.mjs.map +1 -1
  32. package/dist/worlds/index.d.mts +692 -410
  33. package/dist/worlds/index.d.ts +692 -410
  34. package/dist/worlds/index.js +740 -197
  35. package/dist/worlds/index.js.map +1 -1
  36. package/dist/worlds/index.mjs +736 -193
  37. package/dist/worlds/index.mjs.map +1 -1
  38. package/package.json +1 -1
  39. package/runtime/gatewaysdk/environment/_materialize.py +5 -25
  40. package/runtime/gatewaysdk/environment/_world.py +58 -65
  41. package/runtime/gatewaysdk/environment/backing.py +20 -24
  42. package/runtime/gatewaysdk/environment/core.py +1 -16
  43. package/runtime/gatewaysdk/environment/legacy_sqlite.py +14 -27
  44. package/runtime/gatewaysdk/environment/schema/admission.py +174 -0
  45. package/runtime/gatewaysdk/environment/schema/api.py +174 -471
  46. package/runtime/gatewaysdk/environment/schema/assertions.py +458 -0
  47. package/runtime/gatewaysdk/environment/schema/batch.py +3 -3
  48. package/runtime/gatewaysdk/environment/schema/cache_layout.py +5 -0
  49. package/runtime/gatewaysdk/environment/schema/call_capture.py +309 -0
  50. package/runtime/gatewaysdk/environment/schema/call_log.py +230 -18
  51. package/runtime/gatewaysdk/environment/schema/call_redaction.py +201 -19
  52. package/runtime/gatewaysdk/environment/schema/cast.py +15 -35
  53. package/runtime/gatewaysdk/environment/schema/conform.py +6 -27
  54. package/runtime/gatewaysdk/environment/schema/connector.py +89 -152
  55. package/runtime/gatewaysdk/environment/schema/connectors/confluence/connector.toml +1 -12
  56. package/runtime/gatewaysdk/environment/schema/connectors/github/connector.toml +1 -0
  57. package/runtime/gatewaysdk/environment/schema/connectors/servicenow/connector.toml +2 -5
  58. package/runtime/gatewaysdk/environment/schema/cors.py +54 -0
  59. package/runtime/gatewaysdk/environment/schema/credentials.py +313 -8
  60. package/runtime/gatewaysdk/environment/schema/data.py +14 -13
  61. package/runtime/gatewaysdk/environment/schema/database/base.py +106 -165
  62. package/runtime/gatewaysdk/environment/schema/database/guard.py +43 -36
  63. package/runtime/gatewaysdk/environment/schema/database/reads.py +169 -0
  64. package/runtime/gatewaysdk/environment/schema/database/sqlite.py +57 -31
  65. package/runtime/gatewaysdk/environment/schema/declared_routes.py +210 -0
  66. package/runtime/gatewaysdk/environment/schema/door.py +899 -0
  67. package/runtime/gatewaysdk/environment/schema/envelope.py +86 -28
  68. package/runtime/gatewaysdk/environment/schema/grading.py +58 -86
  69. package/runtime/gatewaysdk/environment/schema/handler_errors.py +25 -4
  70. package/runtime/gatewaysdk/environment/schema/host.py +229 -1695
  71. package/runtime/gatewaysdk/environment/schema/host_control.py +144 -0
  72. package/runtime/gatewaysdk/environment/schema/host_handoff.py +370 -0
  73. package/runtime/gatewaysdk/environment/schema/host_loops.py +97 -0
  74. package/runtime/gatewaysdk/environment/schema/host_owners.py +121 -0
  75. package/runtime/gatewaysdk/environment/schema/host_proxy.py +111 -0
  76. package/runtime/gatewaysdk/environment/schema/host_requests.py +6 -0
  77. package/runtime/gatewaysdk/environment/schema/host_session.py +126 -0
  78. package/runtime/gatewaysdk/environment/schema/host_surfaces.py +79 -21
  79. package/runtime/gatewaysdk/environment/schema/host_transfers.py +127 -0
  80. package/runtime/gatewaysdk/environment/schema/host_versions.py +242 -0
  81. package/runtime/gatewaysdk/environment/schema/host_workers.py +577 -0
  82. package/runtime/gatewaysdk/environment/schema/journal.py +437 -0
  83. package/runtime/gatewaysdk/environment/schema/ledger_spill.py +828 -0
  84. package/runtime/gatewaysdk/environment/schema/local.py +31 -116
  85. package/runtime/gatewaysdk/environment/schema/platform.py +15 -17
  86. package/runtime/gatewaysdk/environment/schema/request_body.py +238 -0
  87. package/runtime/gatewaysdk/environment/schema/request_ledger.py +958 -0
  88. package/runtime/gatewaysdk/environment/schema/route_bindings.py +25 -3
  89. package/runtime/gatewaysdk/environment/schema/route_miss.py +54 -0
  90. package/runtime/gatewaysdk/environment/schema/runtime.py +129 -176
  91. package/runtime/gatewaysdk/environment/schema/session_files.py +133 -24
  92. package/runtime/gatewaysdk/environment/schema/session_move.py +275 -0
  93. package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +5 -1
  94. package/runtime/gatewaysdk/environment/schema/skills/benchmarks-getting-started/SKILL.md +8 -9
  95. package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +31 -6
  96. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +12 -8
  97. package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +13 -13
  98. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +23 -23
  99. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  100. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/gotchas.md +35 -2
  101. package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/references/journal-checks.md +182 -0
  102. package/runtime/gatewaysdk/environment/schema/snapshot.py +149 -29
  103. package/runtime/gatewaysdk/environment/schema/spill_files.py +228 -0
  104. package/runtime/gatewaysdk/environment/schema/tasks.py +229 -323
  105. package/runtime/gatewaysdk/environment/schema/tools_world.py +84 -203
  106. package/runtime/gatewaysdk/environment/schema/validation.py +69 -1
  107. package/runtime/gatewaysdk/environment/schema/verbs.py +32 -36
  108. package/runtime/gatewaysdk/environment/schema/worker.py +6 -4
  109. package/runtime/gatewaysdk/environment/schema/workers.py +203 -39
  110. package/runtime/gatewaysdk/environment/schema/world_host.py +953 -0
  111. package/runtime/gatewaysdk/environment/schema/world_tests.py +9 -11
  112. package/runtime/gatewaysdk/environment/world.py +1 -1
  113. package/runtime/gatewaysdk/environment/world_session_contract.py +14 -0
  114. package/skills/agents/connector-template-author.md +5 -1
  115. package/skills/benchmarks-getting-started/SKILL.md +8 -9
  116. package/skills/connector-schema-authoring/SKILL.md +31 -6
  117. package/skills/connector-schema-authoring/connector-worlds.md +129 -7
  118. package/skills/world-data-ingestion/ROWS.md +12 -8
  119. package/skills/world-data-ingestion/SKILL.md +13 -13
  120. package/skills/worlds-getting-started/SKILL.md +23 -23
  121. package/skills/worlds-getting-started/references/cli-mcp-map.md +11 -6
  122. package/skills/worlds-getting-started/references/gotchas.md +35 -2
  123. package/skills/worlds-getting-started/references/journal-checks.md +182 -0
@@ -1,20 +1,325 @@
1
- """How a ``basic`` world's credential rides a request: as the Basic *user*,
2
- with an empty password (``Basic b64("<key>:")``). The host and the local
3
- server present it that way (``api.vendor_credential``), and the world
4
- (``WorldApp.authorized``) and the host's gate (``vendor_shaped_token``) read
5
- it back with :func:`basic_user`, so the two sides cannot drift."""
1
+ """How a vendor's credential rides a request: one :class:`AuthScheme` kind per
2
+ ``[auth] scheme`` of ``connector.toml``.
3
+
4
+ A kind knows where a value sits in a request (:meth:`AuthScheme.read`) and how
5
+ to put it there (:meth:`AuthScheme.carry`). The door (:mod:`.door`), the
6
+ credential the World Host presents to a world, capture and the conformance run
7
+ read and write a credential through it alone, so no two of them can disagree on
8
+ a shape. ``sdk-ts/src/hooks/vendorAuth.ts`` carries the same shapes to a live
9
+ vendor; ``conformance/vendor-auth.json`` pins both. A ``bearer`` value rides
10
+ ``Authorization`` after the first of the words the vendor takes (``prefixes``,
11
+ ``["Bearer"]`` unless declared). A ``basic`` value is the Basic *user* with an
12
+ empty password (``Basic b64("<key>:")``), or the password under any user when
13
+ the vendor reads it there (``credential = "password"``, ``Basic b64(":<key>")``);
14
+ a value that already holds a colon is the whole ``user:password``.
15
+ """
6
16
 
7
17
  from __future__ import annotations
8
18
 
9
19
  import base64
20
+ import re
21
+ from abc import ABC, abstractmethod
22
+ from dataclasses import dataclass
23
+ from typing import Any, Callable, ClassVar, Mapping
24
+
25
+ from .validation import fail, string_of, ttl_seconds_of
26
+
27
+ DEFAULT_TOKEN_PATH = "/oauth/token"
28
+ OAUTH2_KEYS = frozenset({"token_url", "client_id_env", "scope", "ttl_seconds"})
29
+ AUTH_WORD = re.compile(r"[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}")
30
+ BASIC_HALVES = ("user", "password")
10
31
 
32
+ Headers = Mapping[str, str]
33
+ Query = Mapping[str, list[str]]
34
+ Carried = tuple[dict[str, str], dict[str, str]]
11
35
 
12
- def basic_user(authorization: str) -> str | None:
13
- """The user of a ``Basic`` authorization header, or None when it is not one."""
36
+
37
+ def basic_pair(authorization: str) -> tuple[str, str] | None:
38
+ """The user and password of a ``Basic`` authorization header (the password empty
39
+ when it names none), or None when it is not one."""
14
40
  if not authorization.lower().startswith("basic "):
15
41
  return None
16
42
  try:
17
43
  decoded = base64.b64decode(authorization[6:].strip().encode("ascii"), validate=True).decode("utf-8")
18
44
  except (ValueError, UnicodeDecodeError):
19
45
  return None
20
- return decoded.split(":", 1)[0]
46
+ user, _, password = decoded.partition(":")
47
+ return user, password
48
+
49
+
50
+ class AuthScheme(ABC):
51
+ """Where a vendor's credential sits in a request. ``requires_credential``:
52
+ the vendor refuses a call without one; ``carries_minted``: a token the
53
+ world's declared ``[auth.login]`` mints may ride it."""
54
+
55
+ name: ClassVar[str]
56
+ keys: ClassVar[frozenset[str]] = frozenset()
57
+ requires_credential: ClassVar[bool] = True
58
+ carries_minted: ClassVar[bool] = True
59
+
60
+ @staticmethod
61
+ def parse(table: Mapping[str, Any], location: str = "/auth") -> AuthScheme:
62
+ """The kind ``table["scheme"]`` names, read from the rest of ``table``: the
63
+ one place a scheme's kind is decided. A setting of another kind is refused."""
64
+ kind = SCHEMES.get(string_of(dict(table), "scheme", location) or "")
65
+ if kind is None:
66
+ fail("spec", f"auth.scheme must be one of {', '.join(SCHEMES)}", f"{location}/scheme")
67
+ stray = sorted(SCHEME_KEYS.intersection(table) - kind.keys)
68
+ if stray:
69
+ owners = " or ".join(name for name, other in SCHEMES.items() if stray[0] in other.keys)
70
+ fail("spec", f"{stray[0]} belongs to auth.scheme {owners}", f"{location}/{stray[0]}")
71
+ return kind.from_table(table, location)
72
+
73
+ @classmethod
74
+ def from_table(cls, table: Mapping[str, Any], location: str) -> AuthScheme:
75
+ string_of(dict(table), "name", location, required=False)
76
+ return cls()
77
+
78
+ @abstractmethod
79
+ def read(self, headers: Headers, query: Query) -> str | None:
80
+ """The value a request carries this way (``headers`` lower-cased), or None."""
81
+
82
+ @abstractmethod
83
+ def carry(self, value: str) -> Carried:
84
+ """``(headers, query)`` carrying ``value`` this way, header names lower-cased."""
85
+
86
+ def security_scheme(self, token_path: str | None) -> dict:
87
+ """The OpenAPI security scheme a world's ``openapi.json`` declares for it."""
88
+ return {}
89
+
90
+ def capture_value(self, secret: Callable[[], str], mint: Callable[[], str]) -> str | None:
91
+ """What capture sends the live vendor: the connection's secret, unless this
92
+ kind exchanges it for a token first."""
93
+ return secret()
94
+
95
+ def token_request(
96
+ self, base_url: str, client_secret: Callable[[], str], environ: Mapping[str, str]
97
+ ) -> tuple[str, dict[str, str]]:
98
+ """The URL and form an RFC 6749 client-credentials exchange posts."""
99
+ fail("secret", "Only an oauth2 connection mints tokens", "/auth/scheme")
100
+
101
+ @property
102
+ def env_names(self) -> tuple[str, ...]:
103
+ """Environment variables capture reads for this kind beside ``secret_env``."""
104
+ return ()
105
+
106
+ @property
107
+ def secret_param(self) -> str | None:
108
+ """The query parameter a value rides in, which no log keeps."""
109
+ return None
110
+
111
+ @property
112
+ def secret_header(self) -> str | None:
113
+ """The header a value rides in (lower-cased), which no log keeps."""
114
+ return None
115
+
116
+
117
+ @dataclass(frozen=True)
118
+ class NoAuth(AuthScheme):
119
+ name: ClassVar[str] = "none"
120
+ requires_credential: ClassVar[bool] = False
121
+ carries_minted: ClassVar[bool] = False
122
+
123
+ @classmethod
124
+ def from_table(cls, table: Mapping[str, Any], location: str) -> NoAuth:
125
+ if "name" in table or "secret_env" in table:
126
+ fail("spec", "auth.scheme none takes no name or secret_env", location)
127
+ return cls()
128
+
129
+ def read(self, headers: Headers, query: Query) -> str | None:
130
+ return None
131
+
132
+ def carry(self, value: str) -> Carried:
133
+ return {}, {}
134
+
135
+ def capture_value(self, secret: Callable[[], str], mint: Callable[[], str]) -> str | None:
136
+ return None
137
+
138
+
139
+ @dataclass(frozen=True)
140
+ class BearerAuth(AuthScheme):
141
+ """``Authorization: <word> <value>``, the word one of ``prefixes`` in any case
142
+ (GitHub takes ``Bearer`` and ``token``); a call carries the first."""
143
+
144
+ name: ClassVar[str] = "bearer"
145
+ keys: ClassVar[frozenset[str]] = frozenset({"prefixes"})
146
+ prefixes: tuple[str, ...] = ("Bearer",)
147
+
148
+ @classmethod
149
+ def from_table(cls, table: Mapping[str, Any], location: str) -> BearerAuth:
150
+ string_of(dict(table), "name", location, required=False)
151
+ return cls(cls.prefixes_of(table, location))
152
+
153
+ @staticmethod
154
+ def prefixes_of(table: Mapping[str, Any], location: str) -> tuple[str, ...]:
155
+ words = table.get("prefixes", ["Bearer"])
156
+ valid = (
157
+ isinstance(words, list)
158
+ and bool(words)
159
+ and all(isinstance(w, str) and AUTH_WORD.fullmatch(w) for w in words)
160
+ )
161
+ if not valid or len({word.lower() for word in words}) != len(words):
162
+ fail(
163
+ "spec",
164
+ "prefixes lists the distinct words the vendor takes before the key in Authorization",
165
+ f"{location}/prefixes",
166
+ )
167
+ return tuple(words)
168
+
169
+ def read(self, headers: Headers, query: Query) -> str | None:
170
+ word, _, value = headers.get("authorization", "").partition(" ")
171
+ return value if word.lower() in {prefix.lower() for prefix in self.prefixes} else None
172
+
173
+ def carry(self, value: str) -> Carried:
174
+ return {"authorization": f"{self.prefixes[0]} {value}"}, {}
175
+
176
+ def security_scheme(self, token_path: str | None) -> dict:
177
+ return {"type": "http", "scheme": "bearer"}
178
+
179
+
180
+ @dataclass(frozen=True)
181
+ class HeaderAuth(AuthScheme):
182
+ name: ClassVar[str] = "header"
183
+ header: str
184
+
185
+ @classmethod
186
+ def from_table(cls, table: Mapping[str, Any], location: str) -> HeaderAuth:
187
+ return cls(string_of(dict(table), "name", location) or "")
188
+
189
+ def read(self, headers: Headers, query: Query) -> str | None:
190
+ return headers.get(self.header.lower())
191
+
192
+ def carry(self, value: str) -> Carried:
193
+ return {self.header.lower(): value}, {}
194
+
195
+ def security_scheme(self, token_path: str | None) -> dict:
196
+ return {"type": "apiKey", "in": "header", "name": self.header}
197
+
198
+ @property
199
+ def secret_header(self) -> str | None:
200
+ return self.header.lower()
201
+
202
+
203
+ @dataclass(frozen=True)
204
+ class BasicAuth(AuthScheme):
205
+ """``Authorization: Basic``, the key the user with an empty password, or with
206
+ ``credential = "password"`` the password under any user (Atlassian's
207
+ ``email:api_token``, ServiceNow's ``user:password``)."""
208
+
209
+ name: ClassVar[str] = "basic"
210
+ keys: ClassVar[frozenset[str]] = frozenset({"credential"})
211
+ credential: str = "user"
212
+
213
+ @classmethod
214
+ def from_table(cls, table: Mapping[str, Any], location: str) -> BasicAuth:
215
+ given = dict(table)
216
+ string_of(given, "name", location, required=False)
217
+ half = string_of(given, "credential", location, default="user", required=False)
218
+ if half not in BASIC_HALVES:
219
+ fail(
220
+ "spec",
221
+ "credential is the half of the Basic pair the key is: user or password",
222
+ f"{location}/credential",
223
+ )
224
+ return cls(half)
225
+
226
+ def read(self, headers: Headers, query: Query) -> str | None:
227
+ pair = basic_pair(headers.get("authorization", ""))
228
+ return None if pair is None else pair[BASIC_HALVES.index(self.credential)]
229
+
230
+ def carry(self, value: str) -> Carried:
231
+ halves = {"user": f"{value}:", "password": f":{value}"}
232
+ pair = value if ":" in value else halves[self.credential]
233
+ return {"authorization": "Basic " + base64.b64encode(pair.encode("utf-8")).decode("ascii")}, {}
234
+
235
+ def security_scheme(self, token_path: str | None) -> dict:
236
+ return {"type": "http", "scheme": "basic"}
237
+
238
+
239
+ @dataclass(frozen=True)
240
+ class QueryAuth(AuthScheme):
241
+ name: ClassVar[str] = "query"
242
+ param: str
243
+
244
+ @classmethod
245
+ def from_table(cls, table: Mapping[str, Any], location: str) -> QueryAuth:
246
+ return cls(string_of(dict(table), "name", location) or "")
247
+
248
+ def read(self, headers: Headers, query: Query) -> str | None:
249
+ values = query.get(self.param)
250
+ return values[0] if values else None
251
+
252
+ def carry(self, value: str) -> Carried:
253
+ return {}, {self.param: value}
254
+
255
+ def security_scheme(self, token_path: str | None) -> dict:
256
+ return {"type": "apiKey", "in": "query", "name": self.param}
257
+
258
+ @property
259
+ def secret_param(self) -> str | None:
260
+ return self.param
261
+
262
+
263
+ @dataclass(frozen=True, kw_only=True)
264
+ class OAuth2Auth(BearerAuth):
265
+ """RFC 6749 client credentials: calls carry a bearer the vendor's token route
266
+ minted. ``token_url`` is where capture exchanges ``client_id_env`` and the
267
+ secret (a path under ``base_url`` or an absolute URL); a world serves its own
268
+ token route on that path, or on ``/oauth/token`` when it is absolute. Its tokens
269
+ live as long as the session unless ``ttl_seconds`` declares a lifetime."""
270
+
271
+ name: ClassVar[str] = "oauth2"
272
+ keys: ClassVar[frozenset[str]] = OAUTH2_KEYS | {"prefixes"}
273
+ carries_minted: ClassVar[bool] = False
274
+ client_id_env: str
275
+ token_url: str = DEFAULT_TOKEN_PATH
276
+ scope: str | None = None
277
+ ttl_s: int | None = None
278
+
279
+ @classmethod
280
+ def from_table(cls, table: Mapping[str, Any], location: str) -> OAuth2Auth:
281
+ given = dict(table)
282
+ string_of(given, "name", location, required=False)
283
+ token_url = string_of(given, "token_url", location, default=DEFAULT_TOKEN_PATH, required=False) or ""
284
+ if not token_url.startswith(("/", "https://", "http://")):
285
+ fail("spec", "auth.token_url is a path under base_url or an absolute URL", f"{location}/token_url")
286
+ client_id_env = string_of(given, "client_id_env", location) or ""
287
+ return cls(
288
+ prefixes=cls.prefixes_of(given, location),
289
+ client_id_env=client_id_env,
290
+ token_url=token_url,
291
+ scope=string_of(given, "scope", location, required=False),
292
+ ttl_s=ttl_seconds_of(given, location),
293
+ )
294
+
295
+ @property
296
+ def env_names(self) -> tuple[str, ...]:
297
+ return (self.client_id_env,)
298
+
299
+ @property
300
+ def served_token_path(self) -> str:
301
+ return self.token_url if self.token_url.startswith("/") else DEFAULT_TOKEN_PATH
302
+
303
+ def capture_value(self, secret: Callable[[], str], mint: Callable[[], str]) -> str | None:
304
+ return mint()
305
+
306
+ def token_request(
307
+ self, base_url: str, client_secret: Callable[[], str], environ: Mapping[str, str]
308
+ ) -> tuple[str, dict[str, str]]:
309
+ client_id = environ.get(self.client_id_env)
310
+ if not client_id:
311
+ fail("secret", f"Set {self.client_id_env} to the connection's client id", "/auth/client_id_env")
312
+ form = {"grant_type": "client_credentials", "client_id": client_id, "client_secret": client_secret()}
313
+ scope = {"scope": self.scope} if self.scope else {}
314
+ absolute = self.token_url.startswith(("https://", "http://"))
315
+ return (self.token_url if absolute else base_url + self.token_url), {**form, **scope}
316
+
317
+ def security_scheme(self, token_path: str | None) -> dict:
318
+ flow = {"tokenUrl": token_path or DEFAULT_TOKEN_PATH, "scopes": {self.scope or "api": "API access"}}
319
+ return {"type": "oauth2", "flows": {"clientCredentials": flow}}
320
+
321
+
322
+ SCHEMES: dict[str, type[AuthScheme]] = {
323
+ kind.name: kind for kind in (HeaderAuth, BearerAuth, BasicAuth, QueryAuth, OAuth2Auth, NoAuth)
324
+ }
325
+ SCHEME_KEYS = frozenset().union(*(kind.keys for kind in SCHEMES.values()))
@@ -39,9 +39,9 @@ from ..legacy_sqlite import MODES, LegacySQLiteBacking, schema_columns, seed_sta
39
39
  from ..world import KIND_API, KIND_HARBOR, KIND_MOCK_TOOLS, SCHEMA_MANIFEST_KIND, World
40
40
  from .cast import EntityCasters
41
41
  from .compiler import bundle_mode, check_bundle, compile_bundle
42
+ from .database import RowMatch, WorldDatabase
42
43
  from .primary_key import PrimaryKey
43
44
  from .proof import SCRATCH_IGNORE, RowProof
44
- from .database import RowMatch, WorldDatabase
45
45
  from .tree_import import refuse_unpublishable_journal
46
46
  from .validation import ContractError, digest, encoded, fail, journal_paths, read_json
47
47
 
@@ -483,12 +483,12 @@ def entity_counts(root: str | Path) -> dict[str, int]:
483
483
  if kind not in (KIND_SCHEMA, KIND_MOCK_TOOLS):
484
484
  _refuse_kind(kind, root)
485
485
  if kind == KIND_SCHEMA:
486
- from .snapshot import current_default
486
+ from .snapshot import held_default
487
487
 
488
488
  contract = check_bundle(root)
489
- snapshot = current_default(root, contract)
490
- if snapshot is not None:
491
- return dict(snapshot["entityCounts"])
489
+ held = held_default(root, contract)
490
+ if held is not None:
491
+ return dict(held[1]["entityCounts"])
492
492
  from .._materialize import materialize_template
493
493
 
494
494
  with tempfile.TemporaryDirectory(prefix="gateway-show-") as scratch:
@@ -503,13 +503,13 @@ def entity_counts(root: str | Path) -> dict[str, int]:
503
503
  @contextmanager
504
504
  def schema_store(root: Path, contract: Any, scenario: str | None = None) -> Iterator[WorldDatabase]:
505
505
  """The rows of a schema world, read only: the compiled snapshot opened in place
506
- when it is current (the default snapshot is this data through this contract),
507
- else the data files applied in a scratch copy, as a served world would. With
508
- ``scenario``, the rows a session opened in ``scenarios/<scenario>/`` starts
509
- from: the template with the scenario's seed overlay replacing whole entities,
510
- built in scratch (the compiled scenario snapshot is not
506
+ when it is current (the default snapshot is this data through this contract, or a
507
+ pinned tree's copy in the snapshot store), else the data files applied in a scratch
508
+ copy, as a served world would. With ``scenario``, the rows a session opened in
509
+ ``scenarios/<scenario>/`` starts from: the template with the scenario's seed overlay
510
+ replacing whole entities, built in scratch (the compiled scenario snapshot is not
511
511
  consulted, so the answer is the tree as it is now)."""
512
- from .snapshot import SCENARIOS, current_default, default_snapshot, scenario_dirs, scenario_overlay
512
+ from .snapshot import SCENARIOS, held_default, scenario_dirs, scenario_overlay
513
513
 
514
514
  overlay: dict[str, list] | None = None
515
515
  if scenario is not None:
@@ -521,8 +521,9 @@ def schema_store(root: Path, contract: Any, scenario: str | None = None) -> Iter
521
521
  f"/{SCENARIOS}/{scenario}",
522
522
  )
523
523
  overlay = scenario_overlay(scenarios[scenario])
524
- if overlay is None and current_default(root, contract) is not None:
525
- with WorldDatabase.open(default_snapshot(root, contract), contract, audit=False) as store:
524
+ held = held_default(root, contract) if overlay is None else None
525
+ if held is not None:
526
+ with WorldDatabase.open(held[0], contract, audit=False) as store:
526
527
  yield store
527
528
  return
528
529
  from .._materialize import materialize_template