kiosk-server 0.5.20 → 0.6.1

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

@@ -2,101 +2,297 @@
   "$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.",
+  "title": "Kiosk client registration and tokens (OAuth)",
+  "description": "The wire objects of Section 5: RFC 7591 open client registration of the AI assistant's public key, RFC 7523 client assertions signed with that key (the private_key_jwt method), and DPoP-bound access tokens from the client_credentials grant (RFC 9449). The roots are open: they state what MUST be present and the shape of each member.",
   "$defs": {
-    "challenge": {
+    "publicJwk": {
       "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"],
+      "description": "Section 5.1 -- the AI assistant's public key as an RFC 7517 JWK: an Ed25519 key (RFC 8037), or a P-256 key where the operator accepts ES256. A member that only a private key has is refused. Other members (kid, use, alg) are allowed and ignored.",
+      "required": [
+        "kty",
+        "crv",
+        "x"
+      ],
       "properties": {
-        "challenge": {
+        "kty": {
+          "enum": [
+            "OKP",
+            "EC"
+          ],
+          "description": "The key type: OKP for an Ed25519 key, which signs EdDSA; EC for a P-256 key, which signs ES256."
+        },
+        "crv": {
+          "enum": [
+            "Ed25519",
+            "P-256"
+          ],
+          "description": "The curve: Ed25519 for OKP, P-256 for EC."
+        },
+        "x": {
           "type": "string",
-          "description": "The server-issued nonce to sign. It becomes the `nonce` claim of the possession proof.",
-          "minLength": 1
+          "minLength": 1,
+          "description": "The base64url public key of an OKP key, or the base64url x coordinate of an EC key."
         },
-        "exp": {
-          "type": "integer",
-          "description": "Unix expiry of the challenge."
+        "y": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The base64url y coordinate of an EC key."
+        }
+      },
+      "if": {
+        "properties": {
+          "kty": {
+            "const": "EC"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "y"
+        ],
+        "properties": {
+          "crv": {
+            "const": "P-256"
+          }
         }
+      },
+      "else": {
+        "properties": {
+          "crv": {
+            "const": "Ed25519"
+          }
+        }
+      },
+      "not": {
+        "required": [
+          "d"
+        ]
       }
     },
-    "possessionProof": {
+    "jwks": {
       "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"],
+      "description": "Section 5.1 -- an RFC 7517 JWK Set that holds exactly one key, the AI assistant's public key.",
+      "required": [
+        "keys"
+      ],
       "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."
+        "keys": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 1,
+          "items": {
+            "$ref": "#/$defs/publicJwk"
+          }
+        }
+      }
+    },
+    "registrationRequest": {
+      "type": "object",
+      "description": "Section 5.1 -- the body of POST <endpoint>/oauth/register, an RFC 7591 open registration: no initial access token and no human. The operator ignores every member it does not know (RFC 7591 Section 2). An optional proof-of-work proof rides in the `Kiosk-PoW` request header, never in this body.",
+      "required": [
+        "jwks"
+      ],
+      "properties": {
+        "jwks": {
+          "$ref": "#/$defs/jwks"
         },
-        "jti": {
-          "type": "string",
-          "description": "A unique id."
+        "token_endpoint_auth_method": {
+          "const": "private_key_jwt",
+          "description": "The one client authentication method: a client assertion signed with the registered key (RFC 7523)."
         },
-        "pub": {
+        "grant_types": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "client_credentials",
+              "urn:ietf:params:oauth:grant-type:device_code"
+            ]
+          },
+          "description": "A subset of the grant types this origin serves. The operator registers the client for every grant type it serves and answers that list."
+        }
+      }
+    },
+    "clientInformation": {
+      "type": "object",
+      "description": "Section 5.1 -- the 201 answer to POST <endpoint>/oauth/register (RFC 7591 Section 3.2.1), and the 200 answer to POST <endpoint>/auth/rotate (Section 5.7). Registering a key that is registered already answers the same client again.",
+      "required": [
+        "client_id",
+        "jwks",
+        "token_endpoint_auth_method",
+        "grant_types",
+        "dpop_bound_access_tokens"
+      ],
+      "properties": {
+        "client_id": {
           "type": "string",
-          "description": "RFC 7638 thumbprint of the public key; verified only when present."
+          "minLength": 1,
+          "description": "The client identifier. It is also the `agent_id` of the assistant account, stable across a rotation and a rebind."
         },
-        "iat": {
+        "client_id_issued_at": {
           "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."
+          "description": "When the client was registered, in Unix seconds."
+        },
+        "jwks": {
+          "$ref": "#/$defs/jwks"
+        },
+        "token_endpoint_auth_method": {
+          "const": "private_key_jwt"
+        },
+        "grant_types": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": [
+              "client_credentials",
+              "urn:ietf:params:oauth:grant-type:device_code"
+            ]
+          },
+          "description": "`client_credentials`, and the device-code grant where the origin serves account binding."
+        },
+        "dpop_bound_access_tokens": {
+          "const": true,
+          "description": "RFC 9449 Section 5.2: every token request carries a DPoP proof."
         }
       }
     },
-    "credentialRequest": {
+    "registrationError": {
       "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"],
+      "description": "Section 5.1 -- the 400 answer of POST <endpoint>/oauth/register (RFC 7591 Section 3.2.2). The toll on registration answers with problem documents instead (Section 10).",
+      "required": [
+        "error"
+      ],
       "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)."
+        "error": {
+          "const": "invalid_client_metadata",
+          "description": "The one registration error code: a member of the request is missing or not valid."
         },
-        "signed": {
+        "error_description": {
           "type": "string",
-          "description": "The possession proof of Section 5.2, as a compact RS256 JWS. Its decoded payload is `#/$defs/possessionProof`."
+          "description": "Human-readable detail. An AI assistant branches on `error` and never on this string."
         }
       }
     },
-    "registration": {
+    "clientAssertion": {
       "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"],
+      "description": "Section 5.2 -- the decoded payload of a client assertion (RFC 7523 Section 3), a compact JWS that the registered key signs. It is sent as `client_assertion`, with `client_assertion_type` = `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`. It is a PAYLOAD, not a request body.",
+      "required": [
+        "iss",
+        "sub",
+        "aud",
+        "exp",
+        "jti"
+      ],
       "properties": {
-        "agent_id": {
+        "iss": {
           "type": "string",
-          "description": "The acting agent id. Stable across a rebind (Section 6.3)."
+          "minLength": 1,
+          "description": "The client_id."
         },
-        "user_id": {
+        "sub": {
           "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."
+          "minLength": 1,
+          "description": "The client_id, the same value as `iss`."
         },
-        "access_token": {
+        "aud": {
+          "description": "ORIGIN-BINDING. The issuer of the origin the AI assistant dialed, as its only value (Section 15.1). A string, or an array with that one string.",
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "minItems": 1,
+              "maxItems": 1
+            }
+          ]
+        },
+        "exp": {
+          "type": "integer",
+          "description": "Expiry. The operator refuses an assertion that has expired or that expires more than 300 seconds after its clock."
+        },
+        "jti": {
           "type": "string",
-          "description": "The access token, a compact RS256 JWT. Its claims are `#/$defs/accessTokenClaims`."
+          "minLength": 1,
+          "description": "A unique id. The operator accepts each id of a client one time."
+        },
+        "iat": {
+          "type": "integer",
+          "description": "Optional: the time of signing."
         }
       }
     },
-    "token": {
+    "tokenResponse": {
       "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"],
+      "description": "Section 5.3 -- the 200 answer of POST <endpoint>/oauth/token (RFC 6749 Section 5.1), for the client_credentials grant and for the device-code grant (Section 6.1). The 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, a compact RS256 JWT. Its claims are `#/$defs/accessTokenClaims`."
+          "description": "The access token, a compact EdDSA JWT. Its claims are `#/$defs/accessTokenClaims`."
+        },
+        "token_type": {
+          "const": "DPoP",
+          "description": "Always \"DPoP\": the token is bound to the registered key (Section 5.6)."
+        },
+        "expires_in": {
+          "type": "integer",
+          "description": "Seconds until the access token expires."
+        },
+        "scope": {
+          "type": "string",
+          "description": "The role of the assistant account, as the scope that RFC 6749 Section 5.1 grants. It is present only when the account has a role, and never null. An AI assistant MUST NOT treat its absence as an error."
+        }
+      }
+    },
+    "oauthError": {
+      "type": "object",
+      "description": "Sections 5.3 and 6.1 -- the error answer of POST <endpoint>/oauth/token and POST <endpoint>/oauth/device_authorization (RFC 6749 Section 5.2). The status is 400 for every code except `invalid_client`, which is 401. The toll answers with problem documents instead (Section 6.4).",
+      "required": [
+        "error"
+      ],
+      "properties": {
+        "error": {
+          "enum": [
+            "invalid_request",
+            "invalid_client",
+            "invalid_grant",
+            "unsupported_grant_type",
+            "invalid_dpop_proof",
+            "authorization_pending",
+            "slow_down",
+            "expired_token",
+            "access_denied"
+          ],
+          "description": "The OAuth error code: four of RFC 6749 Section 5.2, `invalid_dpop_proof` of RFC 9449, and the four device-grant codes of RFC 8628 Section 3.5. A closed vocabulary: an operator MUST NOT emit a code outside it."
+        },
+        "error_description": {
+          "type": "string",
+          "description": "Human-readable detail. An AI assistant branches on `error` and never on this string."
         }
       }
     },
     "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"],
+      "description": "Section 5.4 -- the decoded claim set of `access_token`. A 3-part EdDSA JWT signed by the operator and verifiable statelessly against the JWKS of Section 4.4, bound to the identity's key and presented as `Authorization: DPoP` with a DPoP proof (Section 5.6).",
+      "required": [
+        "sub",
+        "agent_id",
+        "actor",
+        "iss",
+        "aud",
+        "iat",
+        "nbf",
+        "exp",
+        "jti",
+        "cnf"
+      ],
       "properties": {
         "sub": {
           "type": "string",
@@ -121,14 +317,129 @@
         "aud": {
           "description": "The operator issuer. A string, or the array spelling RFC 7519 permits.",
           "oneOf": [
-            { "type": "string" },
-            { "type": "array", "items": { "type": "string" }, "minItems": 1 }
+            {
+              "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." }
+        "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."
+        },
+        "cnf": {
+          "type": "object",
+          "description": "RFC 9449 Section 6.1 -- the key the token is bound to. Only a DPoP proof that this key signs makes the token usable.",
+          "required": [
+            "jkt"
+          ],
+          "properties": {
+            "jkt": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The RFC 7638 thumbprint of the registered key."
+            }
+          }
+        }
+      }
+    },
+    "dpopProof": {
+      "type": "object",
+      "description": "Section 5.6 -- the decoded payload of the `DPoP` request header, a compact JWS whose header carries `typ: \"dpop+jwt\"`, the `alg` of the registered key (EdDSA, or ES256) and its public `jwk`. The AI assistant signs a new one for each token request and for each request that carries an access token.",
+      "required": [
+        "jti",
+        "htm",
+        "htu",
+        "iat"
+      ],
+      "properties": {
+        "jti": {
+          "type": "string",
+          "minLength": 1,
+          "description": "A unique id for this proof."
+        },
+        "htm": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The HTTP method of the request."
+        },
+        "htu": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The URL of the request, with no query and no fragment. On the event stream it is `events_url` with `wss` written as `https`."
+        },
+        "iat": {
+          "type": "integer",
+          "description": "The time of signing. The operator refuses a proof more than 60 seconds from its clock."
+        },
+        "ath": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The base64url SHA-256 of the ASCII access token, with no padding. REQUIRED on a request that carries an access token; absent on a token request."
+        }
+      }
+    },
+    "rotationAssertion": {
+      "type": "object",
+      "description": "Section 5.7 -- the decoded payload of `client_assertion` in a rotation: a client assertion by the registered key that also names the new key.",
+      "allOf": [
+        {
+          "$ref": "#/$defs/clientAssertion"
+        }
+      ],
+      "required": [
+        "new_key"
+      ],
+      "properties": {
+        "new_key": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The RFC 7638 thumbprint of the new key in `jwks`."
+        }
+      }
+    },
+    "rotationRequest": {
+      "type": "object",
+      "description": "Section 5.7 -- the body of POST <endpoint>/auth/rotate, a Kiosk extension. The answer is `#/$defs/clientInformation` with the new key; the AI assistant then asks the token endpoint for a token with the new key.",
+      "required": [
+        "client_assertion_type",
+        "client_assertion",
+        "new_client_assertion",
+        "jwks"
+      ],
+      "properties": {
+        "client_assertion_type": {
+          "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+        },
+        "client_assertion": {
+          "type": "string",
+          "description": "A client assertion by the registered key. Its decoded payload is `#/$defs/rotationAssertion`."
+        },
+        "new_client_assertion": {
+          "type": "string",
+          "description": "A client assertion by the new key, for the same client_id. Its decoded payload is `#/$defs/clientAssertion`."
+        },
+        "jwks": {
+          "$ref": "#/$defs/jwks"
+        }
       }
     }
   }

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

@@ -3,7 +3,7 @@
   "$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.",
+  "description": "The wire objects of Section 6, the one-time ceremonies that bind a registered AI assistant to an existing operator account: claim, an RFC 8628 device grant, and link. Both need the human's approval and a client assertion by the registered key. The two /oauth/* requests are form-encoded and have no schema here; their answers are in auth.schema.json.",
   "$defs": {
     "deviceAuthorization": {
       "type": "object",
@@ -46,56 +46,20 @@
       }
     },
     "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."
-        }
-      }
+      "$ref": "https://kiosk.tech/spec/schemas/auth.schema.json#/$defs/tokenResponse",
+      "description": "Section 6.1 step 3: the success answer to the device-code poll of POST <endpoint>/oauth/token. `scope` is the approving human's role."
     },
     "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."
-        }
-      }
+      "$ref": "https://kiosk.tech/spec/schemas/auth.schema.json#/$defs/oauthError",
+      "description": "Section 6.1: the error answer of both /oauth/* endpoints, the one error shape on this wire that is not an RFC 9457 problem document."
     },
     "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"],
+      "required": [
+        "link_code",
+        "expires_in"
+      ],
       "properties": {
         "link_code": {
           "type": "string",
@@ -109,35 +73,36 @@
     },
     "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"],
+      "description": "Section 6.2 -- the body of POST <endpoint>/auth/claim, which redeems a link code. The client assertion is REQUIRED, so a leaked code alone can never bind a key its holder does not control. The answer is 204 No Content; the AI assistant then asks the token endpoint for a token under the human's account.",
+      "required": [
+        "code",
+        "client_assertion_type",
+        "client_assertion"
+      ],
       "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."
+        "client_assertion_type": {
+          "const": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
         },
-        "signed": {
+        "client_assertion": {
           "type": "string",
-          "description": "The possession proof of Section 5.2, as a compact RS256 JWS."
+          "description": "A client assertion by the registered key (auth.schema.json#/$defs/clientAssertion)."
         }
       }
     },
-    "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"],
+      "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)."
+          "description": "The bound AI assistant (its client_id) to deactivate. Its tokens stop verifying and the token endpoint answers it `invalid_client` (Section 15.4)."
         }
       }
     }