kiosk-server 0.5.20

data/lib/kiosk/server/schemas/auth.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kiosk.tech/spec/schemas/auth.schema.json",
+  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/auth.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE wire bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
+  "title": "Kiosk registration and login (kiosk-pop)",
+  "description": "The wire objects of Section 5: kiosk-pop, a proof-of-possession challenge-response. The caller proves that it holds the private key of the public key it presents, and the operator answers with a short-lived access token. The roots are open: they state what MUST be present and the shape of each member.",
+  "$defs": {
+    "challenge": {
+      "type": "object",
+      "description": "Section 5.1 -- the answer to GET <endpoint>/auth/challenge?public_key=<url-encoded PEM>. Single-use and short-lived; the nonce is worthless to anyone without the matching private key, which is why the endpoint is unauthenticated.",
+      "required": ["challenge", "exp"],
+      "properties": {
+        "challenge": {
+          "type": "string",
+          "description": "The server-issued nonce to sign. It becomes the `nonce` claim of the possession proof.",
+          "minLength": 1
+        },
+        "exp": {
+          "type": "integer",
+          "description": "Unix expiry of the challenge."
+        }
+      }
+    },
+    "possessionProof": {
+      "type": "object",
+      "description": "Section 5.2 -- the decoded payload of `signed`, a compact RS256 JWS. This is the object the register, login, claim and device-grant token calls all carry. It is a PAYLOAD, not a request body: the wire carries the compact serialisation, and this schema describes what a verifier reads out of it.",
+      "required": ["aud", "nonce", "jti"],
+      "properties": {
+        "aud": {
+          "type": "string",
+          "description": "ORIGIN-BINDING, and the reason a relayed proof is worthless. MUST be the origin the AI assistant dialed (Section 15.1); the operator rejects any other `aud`."
+        },
+        "nonce": {
+          "type": "string",
+          "description": "The `challenge` from Section 5.1. Single-use and server-TTL-bounded."
+        },
+        "jti": {
+          "type": "string",
+          "description": "A unique id."
+        },
+        "pub": {
+          "type": "string",
+          "description": "RFC 7638 thumbprint of the public key; verified only when present."
+        },
+        "iat": {
+          "type": "integer",
+          "description": "Informational only -- the server-issued `nonce` is the authoritative freshness bound, so an operator MUST NOT rely on this claim for freshness."
+        }
+      }
+    },
+    "credentialRequest": {
+      "type": "object",
+      "description": "Section 5.3 -- the body of POST /auth/register and POST /auth/login. Register also accepts an optional proof-of-work proof, which rides in the `Kiosk-PoW` request HEADER (Sections 5.5 and 10.1) and never in this body, so that the signed bytes are identical on the retry.",
+      "required": ["public_key", "signed"],
+      "properties": {
+        "public_key": {
+          "type": "string",
+          "description": "The AI assistant's public key, PEM-encoded. An AI assistant SHOULD generate a fresh keypair per operator origin (Section 15.3)."
+        },
+        "signed": {
+          "type": "string",
+          "description": "The possession proof of Section 5.2, as a compact RS256 JWS. Its decoded payload is `#/$defs/possessionProof`."
+        }
+      }
+    },
+    "registration": {
+      "type": "object",
+      "description": "Section 5.3 -- the 201 answer to POST /auth/register. Registering an already-known key answers 409 conflict instead (use login). This is also the 201 answer to POST /auth/claim (Section 6.2), which is why `#/$defs/claimResponse` in binding.schema.json refers here rather than restating it.",
+      "required": ["agent_id", "user_id", "access_token"],
+      "properties": {
+        "agent_id": {
+          "type": "string",
+          "description": "The acting agent id. Stable across a rebind (Section 6.3)."
+        },
+        "user_id": {
+          "type": "string",
+          "description": "The identity the key maps to. An operator MUST map a known key to the same `user_id` so a saved payment card survives across sessions."
+        },
+        "access_token": {
+          "type": "string",
+          "description": "The access token, a compact RS256 JWT. Its claims are `#/$defs/accessTokenClaims`."
+        }
+      }
+    },
+    "token": {
+      "type": "object",
+      "description": "Section 5.3: the 200 answer to POST /auth/login; an unknown key answers 404 not_found. It is ALSO the 200 answer to POST /auth/revoke (Section 5.5), with a token issued after the new watermark.",
+      "required": ["access_token"],
+      "properties": {
+        "access_token": {
+          "type": "string",
+          "description": "The access token, a compact RS256 JWT. Its claims are `#/$defs/accessTokenClaims`."
+        }
+      }
+    },
+    "accessTokenClaims": {
+      "type": "object",
+      "description": "Section 5.4 -- the decoded claim set of `access_token`. A 3-part RS256 JWT signed by the operator and verifiable statelessly against the JWKS of Section 4.4, presented as `Authorization: Bearer`.",
+      "required": ["sub", "agent_id", "actor", "iss", "aud", "iat", "nbf", "exp", "jti"],
+      "properties": {
+        "sub": {
+          "type": "string",
+          "description": "The identity's `user_id`."
+        },
+        "agent_id": {
+          "type": "string",
+          "description": "The acting agent id."
+        },
+        "actor": {
+          "const": "agent",
+          "description": "Always the string \"agent\". A token minted for anything else is not a Kiosk access token."
+        },
+        "role": {
+          "type": "string",
+          "description": "The role the operator assigns (Section 5.4). It is omitted when absent, never null. No endpoint accepts a role that the client requests."
+        },
+        "iss": {
+          "type": "string",
+          "description": "The operator issuer."
+        },
+        "aud": {
+          "description": "The operator issuer. A string, or the array spelling RFC 7519 permits.",
+          "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+          ]
+        },
+        "iat": { "type": "integer", "description": "Issued-at. Also what the revoked-before watermark of Section 15.4 is compared against." },
+        "nbf": { "type": "integer", "description": "Not-before." },
+        "exp": { "type": "integer", "description": "Expiry. Default lifetime is 1 hour; the durable credential is the private key, not the token." },
+        "jti": { "type": "string", "description": "Unique token id." }
+      }
+    }
+  }
+}

data/lib/kiosk/server/schemas/binding.schema.json

@@ -0,0 +1,145 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kiosk.tech/spec/schemas/binding.schema.json",
+  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/binding.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE wire bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
+  "title": "Kiosk account binding -- claim and link",
+  "description": "The wire objects of Section 6, the one-time ceremonies that bind an AI assistant to an existing operator account: claim, an RFC 8628 device grant, and link. Both need the human's approval and a valid possession proof. The two /oauth/* requests are form-encoded and have no schema here; their error answer has one.",
+  "$defs": {
+    "deviceAuthorization": {
+      "type": "object",
+      "description": "Section 6.1 step 1: the answer to POST <endpoint>/oauth/device_authorization. All six members are required, also the two that RFC 8628 makes optional.",
+      "required": [
+        "device_code",
+        "user_code",
+        "verification_uri",
+        "verification_uri_complete",
+        "expires_in",
+        "interval"
+      ],
+      "properties": {
+        "device_code": {
+          "type": "string",
+          "description": "The opaque code the AI assistant polls with. Never shown to the human."
+        },
+        "user_code": {
+          "type": "string",
+          "description": "The short code the human types at the verification page."
+        },
+        "verification_uri": {
+          "type": "string",
+          "format": "uri",
+          "description": "The operator's session-authenticated approval page (Section 15.8), which names the access the approval hands over."
+        },
+        "verification_uri_complete": {
+          "type": "string",
+          "format": "uri",
+          "description": "The same page with the `user_code` already carried, so the human does not have to type it."
+        },
+        "expires_in": {
+          "type": "integer",
+          "description": "Seconds until the authorization expires."
+        },
+        "interval": {
+          "type": "integer",
+          "description": "Seconds the AI assistant waits between polls. A poll that arrives sooner may be answered `slow_down`."
+        }
+      }
+    },
+    "deviceTokenResponse": {
+      "type": "object",
+      "description": "Section 6.1 step 3: the success answer to POST <endpoint>/oauth/token. The bound principal (`user_id`, `agent_id`) is in the access token's claims.",
+      "required": ["access_token", "token_type", "expires_in"],
+      "properties": {
+        "access_token": {
+          "type": "string",
+          "description": "The access token. Its claims are auth.schema.json#/$defs/accessTokenClaims."
+        },
+        "token_type": {
+          "const": "Bearer",
+          "description": "Always \"Bearer\"."
+        },
+        "expires_in": {
+          "type": "integer",
+          "description": "Seconds until the access token expires."
+        },
+        "scope": {
+          "type": "string",
+          "description": "The approving human's role, as the scope that RFC 6749 Section 5.1 grants. It is present only when the binding carries a role, and never null. An AI assistant MUST NOT treat its absence as an error."
+        }
+      }
+    },
+    "oauthError": {
+      "type": "object",
+      "description": "Section 6.1: the error answer of both /oauth/* endpoints, the one error on this wire that is not an RFC 9457 problem document. The status is 400 for every code except `invalid_client`, which is 401.",
+      "required": ["error"],
+      "properties": {
+        "error": {
+          "enum": [
+            "authorization_pending",
+            "slow_down",
+            "expired_token",
+            "access_denied",
+            "invalid_grant",
+            "invalid_client",
+            "invalid_request",
+            "unsupported_grant_type"
+          ],
+          "description": "The OAuth error code. A closed vocabulary: an operator MUST NOT emit anything outside it, or an AI assistant polling this ceremony has a branch it cannot take."
+        },
+        "error_description": {
+          "type": "string",
+          "description": "Human-readable detail. An AI assistant branches on `error` and never on this string."
+        }
+      }
+    },
+    "linkCode": {
+      "type": "object",
+      "description": "Section 6.2 -- the 201 answer to POST <endpoint>/auth/link, called on the operator's own session by the signed-in human. 201 rather than 200 because the call MINTS a redeemable single-use credential.",
+      "required": ["link_code", "expires_in"],
+      "properties": {
+        "link_code": {
+          "type": "string",
+          "description": "A long opaque token, paste-grade -- the human hands it to their AI assistant. Stored hashed, single-use, short-TTL and attempt-capped (Section 6.3)."
+        },
+        "expires_in": {
+          "type": "integer",
+          "description": "Seconds until the link code expires."
+        }
+      }
+    },
+    "claimRequest": {
+      "type": "object",
+      "description": "Section 6.2 -- the body of POST <endpoint>/auth/claim, which redeems a link code. The possession proof is REQUIRED, so a leaked code alone can never bind a key its holder does not control.",
+      "required": ["code", "public_key", "signed"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "description": "The `link_code` the human handed over."
+        },
+        "public_key": {
+          "type": "string",
+          "description": "The AI assistant's public key, PEM-encoded."
+        },
+        "signed": {
+          "type": "string",
+          "description": "The possession proof of Section 5.2, as a compact RS256 JWS."
+        }
+      }
+    },
+    "claimResponse": {
+      "$ref": "https://kiosk.tech/spec/schemas/auth.schema.json#/$defs/registration",
+      "description": "Section 6.2: the 201 answer to POST <endpoint>/auth/claim, in the shape of the register answer. A new key, a rebound key and a repeated bind give answers that cannot be told apart (Section 6.3)."
+    },
+    "unlinkRequest": {
+      "type": "object",
+      "description": "Section 6.3 -- the body of POST <endpoint>/auth/unlink, called on the operator's own session. The response is 204 No Content and carries no body at all, which is why no response object appears here.",
+      "required": ["agent_id"],
+      "properties": {
+        "agent_id": {
+          "type": "string",
+          "description": "The bound AI assistant to deactivate. Its tokens stop verifying and /auth/login answers 404 (Section 15.4)."
+        }
+      }
+    }
+  }
+}

data/lib/kiosk/server/schemas/kyc.schema.json

@@ -0,0 +1,114 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kiosk.tech/spec/schemas/kyc.schema.json",
+  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/kyc.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE wire bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
+  "title": "Kiosk KYC attestation",
+  "description": "The decoded JWS payload of a KYC attestation, the POST /kiosk/agents/kyc request body, the request_kyc answer, and the data of the kyc_verification event that delivers the attestation.",
+  "$defs": {
+    "attestation": {
+      "type": "object",
+      "description": "Signed by the KYC provider, verified with its configured public key.",
+      "required": [
+        "sub",
+        "level",
+        "iss",
+        "aud",
+        "exp"
+      ],
+      "properties": {
+        "sub": {
+          "type": "string",
+          "description": "MUST equal the authenticated user_id."
+        },
+        "level": {
+          "const": "verified",
+          "description": "Binary; anything other than \"verified\" is rejected."
+        },
+        "iss": {
+          "type": "string",
+          "description": "MUST equal the provider-configured KYC issuer."
+        },
+        "aud": {
+          "type": "string",
+          "description": "OPERATOR-BINDING. The operator the attestation was minted for. MUST equal the operator's configured kyc_audience (its origin, or a stable handle it declares); the operator rejects any other aud. This stops a claim minted for operator A being replayed to operator B."
+        },
+        "iat": {
+          "type": "integer",
+          "description": "Issued-at timestamp. Not enforced by the verifier."
+        },
+        "exp": {
+          "type": "integer",
+          "description": "One year after iat. An expired attestation is rejected."
+        },
+        "attributes": {
+          "$ref": "#/$defs/attributes"
+        }
+      }
+    },
+    "attributes": {
+      "type": "object",
+      "description": "Optional named boolean attributes that the KYC provider vouches for, e.g. age_over_18. Only a value that is literally true counts; an action MAY require named attributes and refuse with kyc_required (403).",
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "request": {
+      "type": "object",
+      "required": [
+        "kyc_jws"
+      ],
+      "properties": {
+        "kyc_jws": {
+          "type": "string",
+          "description": "The attestation as a compact RS256 JWS."
+        }
+      }
+    },
+    "verification": {
+      "type": "object",
+      "description": "The answer to the request_kyc action: a verification opened at the KYC provider, whose page the AI assistant relays to its human.",
+      "additionalProperties": false,
+      "required": [
+        "request_id",
+        "verification_url",
+        "status"
+      ],
+      "properties": {
+        "request_id": {
+          "type": "string",
+          "description": "The provider's id for this verification; the kyc_verification event carries it back."
+        },
+        "verification_url": {
+          "type": "string",
+          "description": "The provider page the human completes."
+        },
+        "status": {
+          "const": "pending"
+        }
+      }
+    },
+    "verificationEvent": {
+      "type": "object",
+      "description": "The data of a kyc_verification event: the human approved, and the event carries the provider-signed attestation to submit to POST /kiosk/agents/kyc.",
+      "additionalProperties": false,
+      "required": [
+        "request_id",
+        "status",
+        "kyc_jws"
+      ],
+      "properties": {
+        "request_id": {
+          "type": "string",
+          "description": "The request_id request_kyc returned."
+        },
+        "status": {
+          "const": "approved"
+        },
+        "kyc_jws": {
+          "type": "string",
+          "description": "The attestation as a compact RS256 JWS."
+        }
+      }
+    }
+  }
+}

data/lib/kiosk/server/schemas/mandates.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kiosk.tech/spec/schemas/mandates.schema.json",
+  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/mandates.schema.json. It is here so RequestValidation can hold a reserved-plane request body to it at runtime, and so e2e/schema_conformance.rb can validate this origin's LIVE wire bytes against the PUBLISHED schema -- both with no second checkout and no network fetch. Identical to the upstream copy as PARSED JSON once this $comment is removed.",
+  "title": "Kiosk AP2 payment mandates",
+  "description": "The decoded JWS payloads of the three AP2 mandates and the POST /kiosk/pay request body. On the wire each mandate is an RS256 compact JWS string; these schemas describe the decoded claim sets.",
+  "$defs": {
+    "baseClaims": {
+      "type": "object",
+      "description": "Claims every mandate MUST carry.",
+      "required": ["id", "user_id", "agent_id", "iss", "iat", "exp"],
+      "properties": {
+        "id": { "type": "string", "description": "Unique mandate id." },
+        "user_id": { "type": "string", "description": "MUST match the authenticated identity (string-compared)." },
+        "agent_id": { "type": "string", "description": "MUST match the authenticated identity (string-compared)." },
+        "iss": { "type": "string", "description": "MUST equal the provider issuer from /.well-known/kiosk.json, verbatim." },
+        "iat": { "type": "integer" },
+        "exp": { "type": "integer", "description": "An exp already in the past is rejected." }
+      }
+    },
+    "intent": {
+      "allOf": [{ "$ref": "#/$defs/baseClaims" }],
+      "type": "object",
+      "required": ["cap_amount_cents", "currency"],
+      "properties": {
+        "cap_amount_cents": { "type": "integer", "minimum": 1, "description": "Spending cap; there is no \"no cap\" spelling -- a nil cap is rejected. MUST be positive; a non-positive amount is rejected." },
+        "currency": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z]{3}$", "description": "An ISO 4217 ALPHA-3 code, and the `pattern` is the domain: three ASCII letters, either case. An operator MAY refuse more (Section 11.1)."},
+        "scope": { "type": "string", "description": "Provider-defined scope." }
+      }
+    },
+    "cart": {
+      "allOf": [{ "$ref": "#/$defs/baseClaims" }],
+      "type": "object",
+      "required": ["intent_mandate_id", "total_amount_cents", "currency", "line_items"],
+      "properties": {
+        "intent_mandate_id": { "type": "string", "description": "MUST equal the intent mandate id; cart total MUST NOT exceed the intent cap." },
+        "total_amount_cents": { "type": "integer", "minimum": 1, "description": "MUST be positive; a non-positive amount is rejected." },
+        "currency": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z]{3}$", "description": "MUST equal the intent currency, and MUST be an ISO 4217 alpha-3 code -- see the intent's note; equality to another empty string, or to another currency NAME, is not a check." },
+        "line_items": { "type": "array", "minItems": 1, "description": "Provider-defined line items, at least one. The operator matches a settlement to its own record through them." }
+      }
+    },
+    "payment": {
+      "allOf": [{ "$ref": "#/$defs/baseClaims" }],
+      "type": "object",
+      "required": ["cart_mandate_id", "amount_cents", "currency"],
+      "properties": {
+        "cart_mandate_id": { "type": "string", "description": "MUST equal the cart mandate id." },
+        "amount_cents": { "type": "integer", "minimum": 1, "description": "MUST equal the cart total, same currency. MUST be positive; a non-positive amount is rejected." },
+        "currency": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z]{3}$", "description": "MUST equal the cart currency, and MUST be an ISO 4217 alpha-3 code." },
+        "payment_method": { "type": "string", "description": "PSP method identifier (e.g. \"on_file\")." }
+      }
+    },
+    "payRequest": {
+      "type": "object",
+      "description": "The POST /kiosk/pay request body: the three mandates as compact JWS strings.",
+      "required": ["intent_mandate_jws", "cart_mandate_jws", "payment_mandate_jws"],
+      "properties": {
+        "intent_mandate_jws": { "type": "string" },
+        "cart_mandate_jws": { "type": "string" },
+        "payment_mandate_jws": { "type": "string" }
+      }
+    },
+    "settlement": {
+      "type": "object",
+      "description": "The pay response body, answered verbatim: there is no envelope, no ok flag and no kind discriminator (protocol.md 8.2, 11.3).",
+      "required": ["settlement_id", "psp_reference", "settled_amount_cents", "currency"],
+      "properties": {
+        "settlement_id": { "type": "string" },
+        "psp_reference": { "type": "string" },
+        "settled_amount_cents": { "type": "integer", "minimum": 1, "description": "The captured amount; equals the cart total. MUST be positive: a settlement exists only for a completed capture, and every mandate amount is already positive." },
+        "currency": { "type": "string", "minLength": 1, "pattern": "^[A-Za-z]{3}$", "description": "The currency of the capture: the cart's currency in the OPERATOR's canonical spelling, which MAY differ byte for byte from the spelling the assistant signed (protocol.md 11.3, 11.5). Compare it as an ISO 4217 code, never as bytes." }
+      }
+    }
+  }
+}

data/lib/kiosk/server/schemas/pow.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kiosk.tech/spec/schemas/pow.schema.json",
+  "title": "Kiosk proof-of-work",
+  "$comment": "VENDORED copy of the normative kiosk.tech schema at spec/schemas/pow.schema.json. This file is self-contained (no cross-file $ref) and must be kept in sync with the upstream normative copy.",
+  "description": "The PoW challenge object (issued in a pow_required 402) and the proof(s) an agent returns in the Kiosk-PoW request header (raw JSON) on retry.",
+  "$ref": "#/$defs/powHeader",
+  "$defs": {
+    "challenge": {
+      "type": "object",
+      "description": "A single stateless, request-bound PoW challenge.",
+      "required": ["id", "alg", "params", "salt", "exp", "sig"],
+      "properties": {
+        "id": { "type": "string", "description": "Opaque unique challenge id." },
+        "alg": { "type": "string", "description": "Algorithm name, e.g. \"equihash\"." },
+        "params": {
+          "type": "object",
+          "description": "Algorithm-specific parameters. For equihash: {n, k}.",
+          "properties": {
+            "n": { "type": "integer" },
+            "k": { "type": "integer" }
+          }
+        },
+        "salt": { "type": "string", "description": "Base64 random salt; no amortization across challenges." },
+        "exp": { "type": "integer", "description": "Unix expiry; scales with the number of requested proofs." },
+        "sig": { "type": "string", "description": "HMAC-SHA256 over the challenge fields plus a fingerprint of the exact request." }
+      }
+    },
+    "proof": {
+      "type": "object",
+      "description": "One solved challenge: the challenge echoed back verbatim plus its solution.",
+      "required": ["challenge", "nonce"],
+      "properties": {
+        "challenge": { "$ref": "#/$defs/challenge" },
+        "nonce": {
+          "$comment": "NO `type` HERE, AND THAT IS THE POINT. Typing `nonce` as the Equihash solution object outright would contradict the decision `alg` is open for: the challenge carries {alg, params} so that an operator may bring a backend of their own, and a backend brings its own solution encoding with it. A schema that admits one algorithm's `alg` string and only that algorithm's nonce shape refuses every other backend's valid proof before any verifier sees it. So the shape is stated CONDITIONALLY, in the `allOf` beside this property, keyed on `challenge.alg`.",
+          "description": "The solution to the challenge, in the shape of the algorithm that `challenge.alg` names. A verifier refuses a proof whose `alg` it does not know. For `equihash` the shape is #/$defs/equihashNonce."
+        }
+      },
+      "allOf": [
+        {
+          "$comment": "ALGORITHM-RELATIVE NONCE. `if` matches only when the echoed challenge names equihash; `then` applies the Equihash solution shape. Any other `alg` reaches no `then` and so leaves `nonce` unconstrained here -- which is the honest statement of what this specification knows about a backend it does not define.",
+          "if": {
+            "required": ["challenge"],
+            "properties": {
+              "challenge": {
+                "required": ["alg"],
+                "properties": { "alg": { "const": "equihash" } }
+              }
+            }
+          },
+          "then": {
+            "properties": { "nonce": { "$ref": "#/$defs/equihashNonce" } }
+          }
+        }
+      ]
+    },
+    "equihashNonce": {
+      "type": "object",
+      "description": "The Equihash solution -- the shape a proof's `nonce` takes when, and only when, its challenge's `alg` is \"equihash\".",
+      "required": ["indices"],
+      "properties": {
+        "indices": {
+          "type": "array",
+          "description": "u64 indices in Zcash canonical (subtree/tree) order; NOT a global ascending sort.",
+          "items": {
+            "$comment": "The upper bound is stated as an INCLUSIVE `maximum` of 2**64-1, not as `exclusiveMaximum: 2**64`. A JSON parser that reads numbers as IEEE-754 doubles rounds the largest LEGAL index, 18446744073709551615, up to exactly 2**64 -- an exclusive bound at 2**64 then REFUSES a proof the reference verifier accepts, and a bound that is wrong in the direction of rejecting valid work is the worse failure. An inclusive bound at the largest legal value survives that round-trip. The residual cost, which no JSON Schema can remove, is that such a parser also admits the handful of values between 2**64 and the next representable double; a parser with exact integers admits none of them, and the verifier refuses them all either way.",
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 18446744073709551615
+          }
+        },
+        "header_nonce": {
+          "$comment": "The bound is stated as an INCLUSIVE `maximum` of 2**32-1, matching how `indices` states its own: 4294967295 is exactly representable as an IEEE-754 double, so it survives any JSON parser, and an inclusive bound never refuses the largest legal value. Without a bound the field is unbounded on the wire while both specs call it a u32 -- and the reference verifier folds it in with `pack(\"V\")`, which truncates mod 2**32 instead of raising, so 0, 2**32 and -(2**32) seed identically and one proof has infinitely many spellings. The verifier rejects out-of-range values for the same reason; schema and verifier state one bound, not two.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 4294967295,
+          "description": "A u32 defaulting to 0. Folded into the PoW seed after the salt bytes as a little-endian u32; an extensibility point (currently always 0). A verifier reconstructs the seed as salt-bytes || header_nonce(LE u32), so a proof solved for a non-zero header_nonce MUST carry it."
+        }
+      }
+    },
+    "powHeader": {
+      "description": "The value of the Kiosk-PoW request header as raw JSON: one proof object, or an array of proofs. Repeated header lines and a comma-joined value give the same list and are not shown here.",
+      "oneOf": [
+        { "$ref": "#/$defs/proof" },
+        {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/proof" }
+        }
+      ]
+    }
+  }
+}

data/lib/kiosk/server/session_context.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Kiosk
+  module Server
+    # The identity a wire request runs as. {#open} wraps the request in a
+    # transaction and sets the principal's GUCs transaction-locally, for
+    # operators who opt into RLS.
+    class SessionContext
+      # `SET LOCAL` with bound values; the third argument `true` is LOCAL.
+      SET_GUC_SQL = 'SELECT set_config($1, $2, true)'
+
+      KEY = :kiosk_server_session_context
+
+      def self.open(connection:, identity:, &)
+        new(connection: connection, identity: identity).open(&)
+      end
+
+      def self.current = Thread.current[KEY]
+
+      def self.open? = !Thread.current[KEY].nil?
+
+      # The identity the wire resolved. Raises outside a session, where a scope
+      # built on it would otherwise match nothing.
+      def self.identity
+        return current.identity if open?
+
+        raise Errors::Unauthenticated,
+              'no Kiosk session is open. Wrap the call in ' \
+              'Kiosk::Server::SessionContext.open(connection:, identity:), or pass the principal in.'
+      end
+
+      attr_reader :connection, :identity
+
+      def initialize(connection:, identity:)
+        @connection = connection
+        @identity   = identity
+      end
+
+      def open
+        connection.transaction do
+          apply_gucs
+          previous = Thread.current[KEY]
+          Thread.current[KEY] = self
+          begin
+            yield self
+          ensure
+            Thread.current[KEY] = previous
+          end
+        end
+      end
+
+      def guc_statements
+        stmts = principal_gucs
+        return stmts unless Kiosk.configuration.enforce_db_role
+
+        stmts + [["SET LOCAL ROLE #{quote_ident(Kiosk.configuration.app_role)}", []]]
+      end
+
+      private
+
+      def apply_gucs
+        guc_statements.each { |sql, binds| connection.exec_query(sql, 'Kiosk GUC', binds) }
+      end
+
+      # One `set_config` per principal field; role and agent_id only when present.
+      def principal_gucs
+        {
+          Kiosk::GUC::USER_ID => identity.user_id,
+          Kiosk::GUC::ROLE => identity.role,
+          Kiosk::GUC::ACTOR => identity.actor,
+          Kiosk::GUC::AGENT_ID => identity.agent_id
+        }.filter_map do |field, value|
+          next if !value && [Kiosk::GUC::ROLE, Kiosk::GUC::AGENT_ID].include?(field)
+
+          guc_sql(Kiosk::GUC.for(Kiosk.configuration.guc_namespace, field), value)
+        end
+      end
+
+      def guc_sql(name, value)
+        [SET_GUC_SQL, [name.to_s, value.to_s]]
+      end
+
+      def quote_ident(name)
+        name.to_s.split('.').map { |part| %("#{part.gsub('"', '""')}") }.join('.')
+      end
+    end
+  end
+end