vgi-python 0.42.1__tar.gz → 0.43.1__tar.gz

{vgi_python-0.42.1 → vgi_python-0.43.1}/CLAUDE.md

@@ -96,9 +96,13 @@ e.g. to pass an unusual filter to `unittest`):
 ```bash
 cd ~/Development/vgi
 VGI_TEST_WORKER="uv run --project ~/Development/vgi-python vgi-fixture-worker" \
-    ./build/release/test/unittest "test/sql/integration/*"
+    ./build/release/test/unittest --test-config test/configs/no_error_skip.json "test/sql/integration/*"
 ```
 
+Always pass `--test-config test/configs/no_error_skip.json` to `unittest`: without
+it, DuckDB's runner reports any error mentioning "HTTP" or "Unable to connect" as
+a SKIP and exits 0.
+
 **HTTP transport** (worker as an HTTP server):
 ```bash
 cd ~/Development/vgi
@@ -142,7 +146,7 @@ with elapsed milliseconds. This helps identify slow queries and bottlenecks.
 # Timing output goes to stderr, grep for the bracket-prefixed lines:
 cd ~/Development/vgi
 VGI_TEST_WORKER="uv run --project ~/Development/vgi-python vgi-fixture-worker" \
-    ./build/release/test/unittest "test/sql/integration/table/writable_table*" \
+    ./build/release/test/unittest --test-config test/configs/no_error_skip.json "test/sql/integration/table/writable_table*" \
     2>&1 | grep "^\[stmt\|^\[query" | sort -t']' -k2 -rn
 ```
 
@@ -166,7 +170,7 @@ uv run coverage run -m pytest --no-cov -n auto
 # 3. Run DuckDB subprocess integration tests with coverage
 cd ~/Development/vgi
 VGI_TEST_WORKER="/tmp/vgi-coverage-worker.sh" \
-    ./build/release/test/unittest "test/sql/integration/*"
+    ./build/release/test/unittest --test-config test/configs/no_error_skip.json "test/sql/integration/*"
 
 # 4. Run DuckDB HTTP integration tests with coverage
 cd ~/Development/vgi
@@ -503,6 +507,20 @@ one. Allowlist rules are unchanged. See `docs/authentication.md` and
 `tests/test_grant_auth.py`, which also runs the shared
 `grant_token_vectors.json` through `create_app`.
 
+### Attach Tickets (`vgi.attach_tickets.v1`)
+
+`seal_attach` seals a user's ATTACH (catalog name, options incl. secrets,
+version specs) into a `vgia1.` ticket under `VGI_SIGNING_KEY`, AAD
+`"vgi.attach_ticket.v1\0" + principal` (principal only, not domain). A runner
+holding the user's grant reattaches with the single option `vgi_attach_ticket`;
+`Worker.catalog_attach` (and `MetaWorker`, before routing) redeems it before any
+catalog code. Hosted on HTTP only, only with an explicitly configured signing key
+(`signing_key_configured` in `build_rpc_server`; a minted key never counts) and
+the ability to issue grants. `vgi_attach_ticket` is a reserved attach-option
+name. Code: `vgi/attach_ticket.py`; spec: `docs/protocol/vgi-attach-tickets.md`;
+vectors: `vgi/_test_fixtures/attach_ticket_vectors.json` (regenerate with
+`scripts/gen_attach_ticket_vectors.py`); fixture catalog: `ticket_probe`.
+
 ### Hosting Additional Protocols (`hosted_protocols`)
 
 Every transport (stdio, unix/named pipe, TCP, Iroh, HTTP) builds its `RpcServer`
@@ -523,6 +541,15 @@ hook. `MetaWorker` hosts its children's lists concatenated. Identity is not
 supplied through this hook. It stays opt-in via `resolve_token`/`mint_grant`
 and is hosted on HTTP only. See `docs/api/worker.md`.
 
+Client side, `Client.list_protocols()` returns the hosted set as
+`vgi_rpc.HostedProtocol` (re-exported from `vgi.client`) in server order, over
+any transport, and `Client.describe_protocol(name)` returns one protocol's
+methods. Both are thin wrappers over vgi-rpc's public `list_protocols` /
+`describe_protocol` on the primary proxy (no private vgi-rpc imports). A worker
+without reflection (`ReflectionNotSupportedError`) yields
+`[HostedProtocol("vgi.v2", "", "")]` rather than an error. Tests: `tests/test_client_reflection.py`; cross-language coverage is the
+C++ repo's `test/sql/integration/reflection/`. See `docs/api/client.md`.
+
 ### Access Log Sampling and Async Emission
 
 `--access-log-sample 0.05` keeps 5% of *successful* calls. Errors are always

{vgi_python-0.42.1 → vgi_python-0.43.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vgi-python
-Version: 0.42.1
+Version: 0.43.1
 Summary: Vector Gateway Interface - Connect DuckDB to external programs via Apache Arrow
 Project-URL: Homepage, https://query.farm
 Project-URL: Repository, https://github.com/Query-farm/vgi-python
@@ -162,7 +162,7 @@ Requires-Dist: httpx2>=2.12.0
 Requires-Dist: platformdirs
 Requires-Dist: pyarrow
 Requires-Dist: typer>=0.9
-Requires-Dist: vgi-rpc>=0.49.0
+Requires-Dist: vgi-rpc>=0.50.0
 Provides-Extra: azure
 Requires-Dist: azure-identity>=1.16.0; extra == 'azure'
 Requires-Dist: pymssql>=2.3.0; extra == 'azure'

{vgi_python-0.42.1 → vgi_python-0.43.1}/ci/run-integration.sh

@@ -336,6 +336,13 @@ EOF
 "$HAYBARN_UNITTEST" "test/_warm.test" >/dev/null 2>&1 || echo "::warning::extension warm step did not fully succeed"
 rm -f "$STAGE/test/_warm.test"
 
+# DuckDB's sqllogictest runner, given no --test-config, turns any error whose
+# text contains "HTTP" or "Unable to connect" into a SKIP and exits 0. Over the
+# http transport every worker error carries "HTTP", so real failures read as
+# skips. The extension ships a config that disables that; every run below uses it.
+TEST_CONFIG="$VGI_SRC/test/configs/no_error_skip.json"
+[ -f "$TEST_CONFIG" ] || { echo "::error::missing $TEST_CONFIG (VGI_REF predates it?)"; exit 1; }
+
 # Run the lane, streaming the native sqllogictest report (a progress line per
 # file + the final "All tests passed (.. N assertions ..)" summary). Out-of-scope
 # tests were dropped at staging; any failed assertion exits non-zero.
@@ -366,7 +373,7 @@ run_unittest() {
   # `set +e` rather than `|| true`: the latter runs before PIPESTATUS is read and
   # overwrites it with true's 0, silently swallowing every real test failure.
   set +e
-  "$HAYBARN_UNITTEST" "$@" 2>&1 | tee "$log"
+  "$HAYBARN_UNITTEST" --test-config "$TEST_CONFIG" "$@" 2>&1 | tee "$log"
   rc="${PIPESTATUS[0]}"
   set -e
   if grep -q 'due to a fatal error condition' "$log"; then

vgi_python-0.43.1/docs/api/client.md

@@ -0,0 +1,38 @@
+# Client
+
+The Python `Client` spawns or connects to a worker, streams Arrow data to and from its functions,
+and surfaces errors as `ClientError`. It is the pure-Python counterpart to the DuckDB extension.
+
+## Discovering hosted protocols
+
+Every worker hosts the vgi-rpc reflection protocol, `vgi_rpc.Reflection.v1`, on every transport.
+`Client.list_protocols()` asks it what the worker hosts, in the worker's order: `vgi.v2` first,
+then any protocols the worker adds through `Worker.hosted_protocols()`, then the framework's own.
+Each entry is a `HostedProtocol` (vgi-rpc's, re-exported from `vgi.client`) with `name`,
+`version`, `hash`, `deprecated`, `deprecation_message` and `features`. The hash is a SHA-256 hex digest of the
+protocol's canonical description, so two equal hashes mean the same method surface.
+`Client.describe_protocol(name)` returns one protocol's methods and schemas as a
+`vgi_rpc.ServiceDescription`. Both are thin wrappers over vgi-rpc's `list_protocols(proxy)` /
+`describe_protocol(proxy, name)` on the client's primary connection.
+
+```python test="skip"
+from vgi.client import Client
+
+with Client("vgi-fixture-worker") as client:
+    hosted = {p.name for p in client.list_protocols()}
+    if "conformance.Secondary.v1" in hosted:
+        print(client.describe_protocol("conformance.Secondary.v1"))
+```
+
+A worker that does not host reflection (one built before it existed answers `UNIMPLEMENTED` /
+`protocol_not_supported`, which vgi-rpc raises as `ReflectionNotSupportedError`) is not an
+error for `list_protocols()`. It returns the single entry
+`HostedProtocol("vgi.v2", "", "")`, because `vgi.v2` is the one protocol every worker hosts. The
+empty hash marks the entry as inferred rather than reported.
+
+Both calls use the client's primary connection. Do not call them while a stream is open on
+the same client.
+
+## API reference
+
+::: vgi.client

{vgi_python-0.42.1 → vgi_python-0.43.1}/docs/api/worker.md

@@ -86,6 +86,10 @@ Identity stays framework-owned. You enable it by overriding
 only on HTTP, which authenticates callers. Its introspection allowlist names principals, and the
 other transports have no principals to check.
 
+`vgi.attach_tickets.v1` is framework-owned too. It is hosted on HTTP only, and only when
+`VGI_SIGNING_KEY` is configured explicitly and the worker can issue grants (grant keys, or its own
+`mint_grant`). See [Attach tickets](../protocol/vgi-attach-tickets.md).
+
 ## Worker
 
 ::: vgi.worker
@@ -97,3 +101,7 @@ other transports have no principals to check.
 ## Serving
 
 ::: vgi.serve
+
+## Attach tickets
+
+::: vgi.attach_ticket

{vgi_python-0.42.1 → vgi_python-0.43.1}/docs/catalog-interface.md

@@ -351,6 +351,8 @@ ATTACH 'mydb' (TYPE vgi, LOCATION 'https://worker.example.com', api_key getenv('
 
 On the wire, `required` and `secret` are nullable boolean columns appended after the four shared spec columns (`name`, `description`, `type`, `default_value`), in that order. Readers look columns up by name, so a spec from a peer that predates either column reads it as `false`, and older peers ignore columns they don't know.
 
+**Never put a secret option's value in `attach_opaque_data`.** On HTTP the worker seals the value, but over stdio and a unix socket it reaches the client, and the DuckDB extension, unsealed. Keep the credential server-side, re-derive it per call, or store a digest of it, as the `ticket_probe` fixture does (see [Opaque values: sealing](protocol/vgi-opaque-data-sealing.md), rule 5).
+
 `secret` does not change what the worker itself logs: attach options are never logged unless the catalog opts in through `loggable_attach_options()` (below), which must never return a secret option.
 
 ---

vgi_python-0.43.1/docs/protocol/vgi-attach-tickets.md

@@ -0,0 +1,329 @@
+# VGI Attach Tickets
+
+**Status:** Normative. Reference implementation: vgi-python `vgi/attach_ticket.py`.
+**Protocol:** `vgi.attach_tickets.v1`, version `1.0.0`. No change to `vgi.v2`.
+**Vectors:** [`vgi/_test_fixtures/attach_ticket_vectors.json`](https://github.com/Query-farm/vgi-python/blob/main/vgi/_test_fixtures/attach_ticket_vectors.json)
+
+An SDK implements attach tickets from this page alone. The words MUST, MUST
+NOT and SHOULD are used as in RFC 2119.
+
+## 1. Purpose
+
+An attach ticket lets a runner reattach a user's catalog later, as that user,
+without ever seeing the user's attach options. While the user is attached and
+logged in, the client calls `seal_attach` on the worker. The worker seals the
+options the user attached with, secret ones included, into a ticket that only
+this worker can open. Later a runner attaches with one option,
+`vgi_attach_ticket`, and the worker restores the original attach before any
+catalog code runs.
+
+A ticket says *what* to attach. A sealed grant (`vgi_rpc.Identity.v1`
+`issue_grant`) says *who* attaches. The two are separate on purpose:
+
+- **A ticket carries no authority.** It opens only under the caller's
+  principal, so it attaches nothing without a grant (or login) for the same
+  principal. Issuing one needs no fresh login, and a leaked ticket alone
+  exposes nothing usable.
+- **A ticket adds no authentication path.** Secret options never enter
+  `AuthContext`.
+
+## 2. Token format
+
+```
+ticket   = "vgia1." base64url_nopad( envelope )
+envelope = version(1) = 0x01 || nonce(24) || XChaCha20-Poly1305(key, nonce, payload, aad)   ; ciphertext || tag(16)
+key      = normalize(VGI_SIGNING_KEY)
+aad      = "vgi.attach_ticket.v1" 0x00 || UTF-8(principal)
+```
+
+- **Envelope.** The same XChaCha20-Poly1305 construction and
+  `version || nonce || ciphertext || tag` layout every SDK already uses to seal
+  `attach_opaque_data` (vgi-rpc's `crypto.seal_bytes`). The version byte is
+  `0x01`, fixed by this format and independent of the attach envelope's own
+  version. The nonce MUST be 24 fresh random bytes per ticket.
+- **Key.** The worker's `VGI_SIGNING_KEY`, as bytes (the UTF-8 of the
+  environment value), normalized exactly as for the attach envelope: a 32-byte
+  key is used as-is; any other length is replaced by `SHA-256(key)`.
+- **AAD.** The **principal only**. The attach envelope binds
+  `(auth domain, principal)`; a ticket MUST NOT, because it is sealed while the
+  user is logged in (domain `jwt`, say) and opened when a runner presents their
+  grant (domain `grant`). The principal is the same in both, since a grant is
+  minted for its caller's principal. The distinct AAD prefix means an attach
+  envelope never opens as a ticket, nor the reverse.
+- **Encoding.** Unpadded base64url (RFC 4648 §5). Only the canonical spelling
+  is valid: no `=`, no `+` or `/`, length mod 4 ≠ 1, and zero trailing bits
+  (re-encoding the decoded bytes MUST give the same text).
+- **Size.** A verifier refuses a ticket longer than 32768 characters before
+  decoding it.
+
+### 2.1 Payload
+
+All integers little-endian. A *string* is a `u16` byte length followed by
+that many bytes of UTF-8.
+
+| # | Field | Encoding | Rule |
+| --- | --- | --- | --- |
+| 1 | `issued_at` | int64 | Unix seconds |
+| 2 | `expires_at` | int64 | Unix seconds; `0` means no expiry; otherwise `> issued_at` |
+| 3 | `ticket_id` | string | Exactly 32 lowercase hex characters (16 random bytes) |
+| 4 | `catalog_name` | string | Non-empty |
+| 5 | `data_version_spec` | string | `""` means none (`null` on the wire) |
+| 6 | `implementation_version` | string | `""` means none (`null` on the wire) |
+| 7 | `options` | `u32` length + bytes | Arrow IPC stream of the one-row options record, exactly as `CatalogAttachRequest.options` carries it; length `0` means no options; at most 16384 bytes |
+
+The options bytes are opaque to the ticket format. A port seals the bytes it
+received (or its own serialization of the same record) and, on redemption,
+deserializes them as it would `CatalogAttachRequest.options`.
+
+## 3. Verifying a ticket
+
+Steps in this order. Every failure before step 6 is
+`attach_ticket_invalid`, with no distinction between causes.
+
+1. **Prefix.** The text starts with `vgia1.`.
+2. **Length.** At most 32768 characters.
+3. **Base64url.** The remainder is canonical unpadded base64url (§2).
+4. **Caller.** The caller is authenticated and has a non-empty principal.
+   An anonymous caller never opens a ticket.
+5. **Open.** Open the envelope with the worker's key and
+   `aad = "vgi.attach_ticket.v1" 0x00 || UTF-8(caller principal)`, expecting
+   version `0x01`. Any failure (short envelope, wrong version, wrong key, wrong
+   principal, tampering) is `attach_ticket_invalid`. **There is no separate
+   principal comparison:** the AAD is the check.
+6. **Parse.** Strictly, per §2.1: exact lengths, strict UTF-8, no trailing
+   bytes, the field rules in the table. Failure is `attach_ticket_invalid`.
+7. **Lifetime.** With `skew = 60` seconds and `now` the current Unix time:
+   `issued_at > now + skew` (not yet valid) or, when `expires_at ≠ 0`,
+   `now ≥ expires_at + skew` (expired) is `attach_ticket_expired`.
+
+The lifetime is inside the ciphertext, so it is trusted only after step 5.
+`attach_ticket_expired` is therefore only ever reported for an authentic
+ticket presented by its own principal.
+
+## 4. Errors
+
+Errors use vgi-rpc's error model: `vgi_rpc.error_code`, `vgi_rpc.error_kind`
+and `vgi_rpc.error_details`.
+
+| `error_kind` | `error_code` | Details | When |
+| --- | --- | --- | --- |
+| `attach_ticket_invalid` | `INVALID_ARGUMENT` | `BadRequest`, field `vgi_attach_ticket` | §3 steps 1–6, a non-string ticket value, or a worker without a signing key |
+| `attach_ticket_expired` | `FAILED_PRECONDITION` | `PreconditionFailure`, type `ATTACH_TICKET`, subject `vgi_attach_ticket` | §3 step 7 |
+| `invalid_request` | `INVALID_ARGUMENT` | `BadRequest`, one violation per bad field | Another option beside the ticket (§6); a `seal_attach` request that fails validation (§5.3) |
+| `action_denied` | `PERMISSION_DENIED` | `ErrorInfo`, `metadata.action = "seal_attach"` | Anonymous `seal_attach`, or a worker refusing by policy |
+
+No error message, log line or detail ever contains the ticket text or a
+restored option value.
+
+## 5. `vgi.attach_tickets.v1`
+
+### 5.1 Hosting
+
+A worker hosts the protocol when **all** of these hold, and otherwise does not
+host it at all (absent, not hosted-and-refusing, so a client learns the answer
+from `vgi_rpc.Reflection.v1` `list_protocols`):
+
+1. The transport is HTTP. Other transports have no caller identity.
+2. `VGI_SIGNING_KEY` is configured explicitly. A key the process generated for
+   itself MUST NOT enable the protocol: every ticket would die on restart. (A
+   pre-fork server that generates one key and hands it to its children marks
+   it as generated; vgi-python uses the private `VGI_SIGNING_KEY_MINTED=1`.)
+3. The worker can issue grants: grant keys are configured
+   (`VGI_RPC_GRANT_KEYS`) or the worker supplies its own `mint_grant`. A ticket
+   is useless without a grant.
+
+It is hosted beside `vgi.v2` and never changes how a `vgi.v2` request is
+dispatched. Wire name `vgi.attach_tickets.v1`, `protocol_version = "1.0.0"`.
+
+### 5.2 Shapes
+
+One unary method, `seal_attach(request: SealAttachRequest) -> AttachTicket`.
+
+`SealAttachRequest`:
+
+| Field | Arrow type | Meaning |
+| --- | --- | --- |
+| `catalog_name` | `utf8` not null | The catalog the caller attached |
+| `options` | `binary` nullable | Arrow IPC stream of the one-row options record, as `CatalogAttachRequest.options`; null for none |
+| `data_version_spec` | `utf8` not null | As given at ATTACH; `""` for none |
+| `implementation_version` | `utf8` not null | As given at ATTACH; `""` for none |
+| `ttl_seconds` | `int64` not null | Requested lifetime; `0` = as long as the worker allows |
+
+`AttachTicket`:
+
+| Field | Arrow type | Meaning |
+| --- | --- | --- |
+| `ticket` | `utf8` not null | The `vgia1.` text |
+| `expires_at` | `float64` not null | Unix seconds; `+inf` when the ticket has no expiry |
+
+### 5.3 Rules
+
+In this order:
+
+1. **Caller.** Anonymous (unauthenticated, or no principal) is
+   `action_denied`. The principal sealed is always the caller's; there is no
+   subject parameter.
+2. **No freshness requirement.** Unlike `issue_grant`, a stale login may seal.
+3. **Validation**, all violations reported together as `invalid_request`
+   with one `BadRequest` field violation each:
+   - `ttl_seconds < 0` → field `ttl_seconds`.
+   - `options` with more than one row → field `options`. Zero rows or null
+     means no options.
+   - `catalog_name` not among the worker's catalogs (`catalog_catalogs`) →
+     field `catalog_name`.
+   - An option whose name (case-insensitive) is `vgi_attach_ticket` → field
+     `options.<name>`.
+   - An option the catalog does not declare in its `attach_option_specs`
+     (names compared case-insensitively) → field `options.<name>`.
+   - A declared `required` option missing → field `options.<spec name>`.
+   - Options larger than 16384 bytes once serialized → field `options`.
+
+   Validation never attaches: it has no side effects. Option *values* are not
+   type-checked here; the catalog checks them when the ticket is redeemed.
+4. **Lifetime.** Let `max` be the worker's grant maximum lifetime: the grant
+   keys' `max_ttl_seconds` when grant keys are configured, otherwise
+   `VGI_RPC_GRANT_MAX_TTL_SECONDS` when set, otherwise none.
+   `issued_at = now` (integer seconds), and
+
+   | `ttl_seconds` | `max` set | `expires_at` |
+   | --- | --- | --- |
+   | `0` | yes | `issued_at + max` |
+   | `0` | no | `0` (no expiry) |
+   | `> 0` | yes | `issued_at + min(ttl_seconds, max)` |
+   | `> 0` | no | `issued_at + ttl_seconds` |
+
+   So the two halves of a held entry (grant and ticket) expire together.
+5. **Seal** per §2 with a fresh `ticket_id` and nonce. Return the text and
+   `expires_at` (`+inf` for `0`).
+
+A worker MAY refuse by policy with `action_denied`.
+
+## 6. Redeeming: what `catalog_attach` does
+
+When a `vgi.v2` `catalog_attach` request's options contain a key equal,
+case-insensitively, to `vgi_attach_ticket`, the SDK framework, before any
+catalog code:
+
+1. **Rejects any other option alongside it** — including a second spelling of
+   the ticket key — as `invalid_request`, one `BadRequest` violation
+   `options.<name>` per extra option. The sealed options are authoritative, so
+   there is nothing to merge. This check comes before the ticket is opened.
+2. **Verifies the ticket** per §3 under the caller's principal and the
+   worker's signing key. A non-string value, or a worker with no signing key
+   (subprocess and unix transports), is `attach_ticket_invalid`.
+3. **Replaces the request** with the one the user originally made:
+   `name = catalog_name`, `options =` the sealed options (null when length
+   0), `data_version_spec` / `implementation_version =` the sealed strings
+   (null when `""`). `client_capabilities` is kept from the incoming request.
+   The incoming `name` is ignored.
+4. **Proceeds as a normal attach** with the restored request: the catalog's
+   own `catalog_attach` runs unchanged, sealing of `attach_opaque_data`,
+   lifecycle logging (`loggable_attach_options` sees the restored options as
+   usual) and tracing all behave as if the user had typed it.
+
+A worker composing several catalogs (vgi-python's `MetaWorker`) redeems
+**before** routing, so the sealed catalog name, not the request's name, picks
+the catalog.
+
+**Reserved name.** `vgi_attach_ticket` is reserved: declaring an attach option
+with that name (compared case-insensitively) MUST fail at worker startup.
+
+**Never logged.** Neither the ticket nor the restored options (beyond what
+`loggable_attach_options` returns) may reach a log, span, breadcrumb or error.
+
+**Principal namespaces.** A ticket sealed for `alice` opens for any caller
+whose principal is `alice`, whatever authenticated them. That is already true
+of grants. A deployment whose authenticators map one string to different
+people has that problem today; tickets do not add it.
+
+**Key rotation.** Tickets live as long as `VGI_SIGNING_KEY` does. Rotating it
+invalidates every ticket, as it already invalidates attach envelopes.
+
+## 7. Fixture catalog: `ticket_probe`
+
+Every SDK's fixture worker serves this catalog identically (in vgi-python,
+`vgi/_test_fixtures/ticket_probe.py`, in both `vgi-fixture-worker` and
+`vgi-fixture-http`). The cross-SDK sqllogictests in
+`vgi/test/sql/integration/attach_ticket/` run against it.
+
+- Catalog `ticket_probe`, default schema `main`.
+- Attach options, in this order:
+
+  | Name | Type | Required | Secret | Default |
+  | --- | --- | --- | --- | --- |
+  | `region` | `VARCHAR` | no | no | `'us-east-1'` |
+  | `api_key` | `VARCHAR` | **yes** | **yes** | none |
+
+- Table `main.probe`, backed by the table function `main.ticket_probe` (no
+  arguments). Exactly one row:
+
+  | Column | Type | Value |
+  | --- | --- | --- |
+  | `region` | `VARCHAR` | The attached `region`, or `'us-east-1'` |
+  | `api_key_sha256` | `VARCHAR` | The first 12 lowercase hex characters of `SHA-256(UTF-8(api_key))` |
+
+  The key itself is never returned. Option names are matched
+  case-insensitively.
+
+- Attaching without `api_key` fails (the option is required). So a reattach
+  with nothing but `vgi_attach_ticket` reading the same row proves the secret
+  took effect without travelling again.
+
+For example, `api_key = 'sk-test-0123456789'` reads back as
+`api_key_sha256 = '0d3b56072291'`.
+
+### 7.1 Fixture HTTP server
+
+The fixture HTTP server hosts `vgi.attach_tickets.v1` when started with both:
+
+```bash
+VGI_SIGNING_KEY=<any stable value> \
+VGI_RPC_GRANT_KEYS=<base64 of 32 bytes> \
+vgi-fixture-http
+```
+
+Its default test authenticator accepts `Bearer vgi-test-alice` (principal
+`alice`) and `Bearer vgi-test-bob` (principal `bob`) as **fresh** logins (it
+stamps `auth_time = now`), so a client can `issue_grant` with nothing but a
+bearer token. When grant keys are configured, a `Bearer vgig1.…` falls
+through to the sealed-grant authenticator; any other unknown bearer stays
+anonymous as before.
+
+## 8. Vectors
+
+`attach_ticket_vectors.json` pins the format byte for byte. Every SDK's unit
+tests MUST consume it. Keys and options are standard base64; nonces and
+payloads are hex. `defaults` supplies `signing_key_b64` and `now` for cases
+that omit them.
+
+| Section | Each case gives | A port must |
+| --- | --- | --- |
+| `mint` | key, principal, catalog, options bytes, version specs, `issued_at`, `expires_at`, `ticket_id`, `nonce_hex`, plus `aad_hex`, `payload_hex` and `token` | Seal with exactly these inputs and produce exactly `payload_hex`, `aad_hex` and `token` |
+| `accept` | `token`, `principal`, `now` | Open it and produce exactly `claims` (options compared as bytes) |
+| `reject` | `token`, `principal`, optional `now` / key | Refuse it with exactly `error_kind` |
+| `redeem` | the incoming options map (strings), `principal` | Apply §6 and either produce `result` (catalog name, version specs, decoded options; `null` means the request is untouched) or refuse with `error_kind` |
+
+The reject cases cover a wrong principal, an anonymous caller, a principal
+differing only in case, tampering, another worker's key, expiry and
+not-yet-valid (with the 60 s skew edges in `accept`), an attach envelope
+presented as a ticket (both as minted and re-sealed with the ticket version
+byte), a `(domain, principal)` AAD, non-canonical / padded / standard-alphabet
+base64, wrong and missing prefixes, short and over-long tickets, trailing,
+truncated and overrunning payloads, oversize options, bad ticket ids, an empty
+or non-UTF-8 catalog name, and an empty lifetime.
+
+The file is generated by `scripts/gen_attach_ticket_vectors.py`; vgi-python's
+`tests/test_attach_ticket.py` fails if the two drift.
+
+## 9. Porting checklist
+
+Each of these, removed, MUST turn a test red in your SDK:
+
+- The principal in the AAD (or swapping in the attach envelope's
+  `(domain, principal)` AAD).
+- The expiry check.
+- The "no other option beside the ticket" rule.
+- Redeeming before routing, in a worker that composes catalogs.
+- The reserved-name check on attach option declarations.
+- The hosting conditions: no protocol without an explicit key, without the
+  ability to issue grants, or off HTTP.