@greenpandastudios/aug-cli 0.19.0 → 0.20.1

package/examples/oidc-login/client/login.aug.md

@@ -1,331 +1,53 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `login.aug` specification
+# `login.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`startLogin`](login.aug.md#symbol-startLogin) handles `GET` `/login/start` returning `HttpResponse<Html>`.
-- [`loginCallback`](login.aug.md#symbol-loginCallback) handles `GET` `/login/callback` returning `HttpResponse<Html>`.
+Plain handler results default to HTTP 200 unless another status is declared. HttpResponse values choose their own status. Unhandled request failures return HTTP 500 and cancel the request tasks.
 
 <a id="symbol-startLogin"></a>
+## `startLogin` · [source](login.aug#L12)
 
-## `startLogin`
-
-[source](login.aug#L11)
-
-**Inputs**
-
-- `crypto` ([`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)) — injected; callers omit it.
-- `clock` ([`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock)) — injected; callers omit it.
-- `client` ([`HttpClient`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient)) — injected; callers omit it.
-- `transactions` ([`ExpiringStore<LoginTransaction>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
-
-Returns: `HttpResponse<Html>`.
+`startLogin` handles `GET /login/start`. Start a browser-bound, short-lived transaction. The PKCE verifier stays on the server. It gets `crypto` ([`Crypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto)), `clock` ([`Clock`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock)), `client` ([`HttpClient`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-HttpClient)), and `transactions` ([`ExpiringStore<LoginTransaction>`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore)) from dependency injection.
 
-Capabilities: [`crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random), [`crypto.sha256`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.sha256), [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`client.request`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request), [`transactions.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put).
+The handler responds with HTTP 502 for [`SessionError`](contracts.aug.md#symbol-SessionError), HTTP 503 for `CryptoError`, HTTP 503 for `TimeError`, and HTTP 503 for [`StoreFull`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-StoreFull). It can also raise `HttpError`.
 
-Can fail with `SessionError`, `CryptoError`, `TimeError`, `StoreFull`, `HttpError`. Callers must catch or propagate these errors.
+It gets `config` from [`settings`](../common/settings.aug.md#symbol-settings). It gets `document` from [`discover`](protocol.aug.md#symbol-discover) using injected `client`. It sets `browser`, `state`, `nonce`, and `verifier` separately, each to the URL-safe base64 encoding of [`crypto.random`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.random) with `size` `32`. It sets `transaction` to a [`LoginTransaction`](contracts.aug.md#symbol-LoginTransaction) with `state`, `nonce`, `verifier`, and `expires` from [`clock.now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now) plus `300`.
 
-HTTP route: `GET` `/login/start`. Use status 200 when the handler returns a body; a returned HttpResponse can set its own status. An unhandled request failure returns status 500 and cancels its request tasks.
+It calls [`transactions.put`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.put) with `key` from `browser`, `value` from `transaction`, `transaction.expires`, and `now` from [`clock.now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now). It sets `challenge` to the URL-safe base64 encoding of [`crypto.sha256`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.sha256) with `input` from the UTF-8 bytes of `verifier`. It builds `location` as the text `{document.authorization_endpoint}?response_type=code&client_id={urlEncode with input from config.clientId}&redirect_uri={urlEncode with input from config.callback}&scope=openid%20profile&state={urlEncode with input from state}&nonce={urlEncode with input from nonce}&code_challenge={urlEncode with input from challenge}&code_challenge_method=S256`. It sets `headers` to [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` from [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with the header `"location"` set to `location`, `name` `"aug_login"`, `value` from `browser`, `path` `"/login"`, `maxAge` `300`, and `secure` from `config.secureCookies`.
 
-Declared HTTP failures: [`SessionError`](contracts.aug.md#symbol-SessionError) returns status 502; `CryptoError` returns status 503; `TimeError` returns status 503; [`StoreFull`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-StoreFull) returns status 503.
-
-**What it does**
-
-- Set `config` to call [`settings`](../common/settings.aug.md#symbol-settings).
-- Set `document` to call [`discover`](protocol.aug.md#symbol-discover); inject `client` from `client`.
-- Set `browser` to call `base64url` on call [`Crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random) on `crypto` with `size` = `32`.
-- Set `state` to call `base64url` on call [`Crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random) on `crypto` with `size` = `32`.
-- Set `nonce` to call `base64url` on call [`Crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random) on `crypto` with `size` = `32`.
-- Set `verifier` to call `base64url` on call [`Crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random) on `crypto` with `size` = `32`.
-- Set `transaction` to call [`LoginTransaction`](contracts.aug.md#symbol-LoginTransaction) with `state` = `state`; `nonce` = `nonce`; `verifier` = `verifier`; `expires` = (call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock` plus `300`).
-- Call [`ExpiringStore.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put) on `transactions` with `key` = `browser`; `value` = `transaction`; `expires` = `expires` of `transaction`; `now` = call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`.
-- Set `challenge` to call `base64url` on call [`Crypto.sha256`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.sha256) on `crypto` with `input` = call `bytes` on `verifier`.
-- Build `location` by joining these text parts without separators, in order:
-  1. `authorization_endpoint` of `document`
-  2. `"?response_type=code&client_id="`
-  3. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `clientId` of `config`
-  4. `"&redirect_uri="`
-  5. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `callback` of `config`
-  6. `"&scope=openid%20profile&state="`
-  7. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `state`
-  8. `"&nonce="`
-  9. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `nonce`
-  10. `"&code_challenge="`
-  11. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `challenge`
-  12. `"&code_challenge_method=S256"`
-- Set `headers` to call [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` = call `with` on call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with `name` = `"location"`; `value` = `location`; `name` = `"aug_login"`; `value` = `browser`; `path` = `"/login"`; `maxAge` = `300`; `secure` = `secureCookies` of `config`.
-- Return call `HttpResponse` with `body` = the HTML element `p` containing `Opening the identity provider.` (rendered on the server with embedded text escaped); `status` = `303`; `headers` = `headers`.
-
-**Author documentation**
-
-Start a browser-bound, short-lived transaction. The PKCE verifier stays on the server.
+It returns HTTP 303 with a paragraph containing `Opening the identity provider.` with escaped text and `headers` headers.
 
 <a id="symbol-loginCallback"></a>
+## `loginCallback` · [source](login.aug#L27)
 
-## `loginCallback`
-
-[source](login.aug#L26)
-
-**Inputs**
-
-- `code` (`string`) — read from the HTTP query.
-- `state` (`string`) — read from the HTTP query.
-- `browser` (`optional string`) — read from the HTTP cookie named `aug_login`; absent value becomes null.
-- `crypto` ([`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)) — injected; callers omit it.
-- `clock` ([`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock)) — injected; callers omit it.
-- `client` ([`HttpClient`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient)) — injected; callers omit it.
-- `keys` ([`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)) — injected; callers omit it.
-- `transactions` ([`ExpiringStore<LoginTransaction>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
-- `sessions` ([`ExpiringStore<SessionClaims>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
-
-Returns: `HttpResponse<Html>`.
-
-Capabilities: [`crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal), [`crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random), [`crypto.signRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.signRsa), [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`crypto.importRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.importRsa), [`crypto.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa), [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`client.request`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request), [`keys.session`](../common/keys.aug.md#symbol-SigningKeys.session), [`transactions.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take), [`sessions.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put).
-
-Can fail with `SessionError`, `CryptoError`, `TimeError`, `KeyError`, `StoreFull`, `JwtError`, `JsonError`, `HttpError`. Callers must catch or propagate these errors.
-
-HTTP route: `GET` `/login/callback`. Use status 200 when the handler returns a body; a returned HttpResponse can set its own status. An unhandled request failure returns status 500 and cancels its request tasks.
-
-Declared HTTP failures: [`SessionError`](contracts.aug.md#symbol-SessionError) returns status 400; `CryptoError` returns status 503; `TimeError` returns status 503; [`StoreFull`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-StoreFull) returns status 503.
-
-**What it does**
-
-- If not (call `isToken` on `code` with `min` = `43`; `max` = `43`) or not (call `isToken` on `state` with `min` = `43`; `max` = `43`):
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- Select the matching case for `browser`:
-  - A null value, including omitted optional input:
-    - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-  - A present, non-null value, named `secret`:
-    - Select the matching case for call [`ExpiringStore.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take) on `transactions` with `key` = `secret`; `now` = call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`:
-      - A null value, including omitted optional input:
-        - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-      - A present, non-null value, named `transaction`:
-        - If not (call [`Crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal) on `crypto` with `left` = call `bytes` on `state` of `transaction`; `right` = call `bytes` on `state`):
-          - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-        - Set `config` to call [`settings`](../common/settings.aug.md#symbol-settings).
-        - Set `document` to call [`discover`](protocol.aug.md#symbol-discover); inject `client` from `client`.
-        - Build `body` by joining these text parts without separators, in order:
-          1. `"grant_type=authorization_code&code="`
-          2. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `code`
-          3. `"&redirect_uri="`
-          4. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `callback` of `config`
-          5. `"&client_id="`
-          6. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `clientId` of `config`
-          7. `"&code_verifier="`
-          8. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `verifier` of `transaction`
-        - Set `headers` to call `with` on call `Headers` with `name` = `"content-type"`; `value` = `"application/x-www-form-urlencoded"`.
-        - Set `tokens` to call `decode` on call [`responseJson`](protocol.aug.md#symbol-responseJson) with `response` = call [`HttpClient.request`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request) on `client` with `method` = `"POST"`; `url` = `token_endpoint` of `document`; `headers` = `headers`; `body` = call `bytes` on `body` with type arguments [`TokenResponse`](../provider/contracts.aug.md#symbol-TokenResponse).
-        - If ((`token_type` of `tokens` does not equal `"Bearer"`) or not (call `isToken` on `access_token` of `tokens` with `min` = `43`; `max` = `43`)) or (`expires_in` of `tokens` is at most `0`):
-          - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-        - Set `jwks` to call `decode` on call [`responseJson`](protocol.aug.md#symbol-responseJson) with `response` = call [`HttpClient.request`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request) on `client` with `method` = `"GET"`; `url` = `jwks_uri` of `document` with type arguments [`RsaJwks`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwks).
-        - Set `identity` to call [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) with `token` = `id_token` of `tokens`; `nonce` = `nonce` of `transaction`; `now` = call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`; `jwks` = `jwks`; inject `crypto` from `crypto`.
-        - Set `authHeaders` to call `with` on call `Headers` with `name` = `"authorization"`; `value` = (`"Bearer "` plus `access_token` of `tokens`).
-        - Set `user` to call `decode` on call [`responseJson`](protocol.aug.md#symbol-responseJson) with `response` = call [`HttpClient.request`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request) on `client` with `method` = `"GET"`; `url` = `userinfo_endpoint` of `document`; `headers` = `authHeaders` with type arguments [`UserInfo`](../provider/contracts.aug.md#symbol-UserInfo).
-        - If `sub` of `user` does not equal `sub` of `identity`:
-          - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-        - Set `now` to call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`.
-        - Set `session` to call [`SessionClaims`](contracts.aug.md#symbol-SessionClaims) with `iss` = (`baseUrl` of `config` plus `"/app"`); `sub` = `sub` of `identity`; `aud` = `"august-app"`; `exp` = (`now` plus `sessionSeconds` of `config`); `iat` = `now`; `jti` = call `base64url` on call [`Crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random) on `crypto` with `size` = `32`; `csrf` = call `base64url` on call [`Crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random) on `crypto` with `size` = `32`; `name` = `name` of `user`.
-        - Set `jwt` to call [`signJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-signJwt) with `key` = call [`SigningKeys.session`](../common/keys.aug.md#symbol-SigningKeys.session) on `keys`; `claims` = call `Json` with `value` = `session`; `kid` = `"session-1"`; `tokenType` = `"august-session+jwt"`; inject `crypto` from `crypto`.
-        - Call [`ExpiringStore.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put) on `sessions` with `key` = `jti` of `session`; `value` = `session`; `expires` = `exp` of `session`; `now` = `now`.
-        - Set `responseHeaders` to call [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` = call `with` on call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with `name` = `"location"`; `value` = `"/"`; `name` = `"aug_session"`; `value` = `jwt`; `path` = `"/"`; `maxAge` = `sessionSeconds` of `config`; `secure` = `secureCookies` of `config`.
-        - Set `responseHeaders` to call [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` = `responseHeaders`; `name` = `"aug_login"`; `value` = `""`; `path` = `"/login"`; `maxAge` = `0`; `secure` = `secureCookies` of `config`.
-        - Return call `HttpResponse` with `body` = the HTML element `p` containing `Signed in.` (rendered on the server with embedded text escaped); `status` = `303`; `headers` = `responseHeaders`.
-
-**Author documentation**
-
-Exchange a one-use code over HTTP, verify the provider JWT/JWKS and UserInfo subject, then issue a distinct app-session JWT.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)
-
-Capability interface from `august.crypto`.
-
-- [`Crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url) (`input`: `string`) → `Bytes`; can fail with `CryptoError`.
-- [`Crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal) (`left`: `Bytes`, `right`: `Bytes`) → `bool`.
-- [`Crypto.importRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.importRsa) (`modulus`: `Bytes`, `exponent`: `Bytes`) → `RsaPublicKey`; can fail with `CryptoError`.
-- [`Crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random) (`size`: `int`) → `Bytes`; can fail with `CryptoError`.
-- [`Crypto.sha256`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.sha256) (`input`: `Bytes`) → `Bytes`; can fail with `CryptoError`.
-- [`Crypto.signRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.signRsa) (`key`: `RsaPrivateKey`, `input`: `Bytes`) → `Bytes`; can fail with `CryptoError`.
-- [`Crypto.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa) (`publicKey`: `RsaPublicKey`, `input`: `Bytes`, `signature`: `Bytes`) → `bool`; can fail with `CryptoError`.
-
-### [`JwtError`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-JwtError)
-
-Class from `august.crypto`.
-
-Used as a type or provider.
-
-### [`RsaJwks`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwks)
-
-Record from `august.crypto`.
-
-Used as a type or provider.
-
-### [`signJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-signJwt)
-
-Function from `august.crypto`.
-
-- [`signJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-signJwt) (`key`: `RsaPrivateKey`, `claims`: `Json`, `kid`: `string`, `tokenType`: `string`) → `string`; inject `crypto`: [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto); uses [`crypto.signRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.signRsa); can fail with `JwtError`.
-
-### [`ExpiringStore`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)
-
-Capability interface from `august.memory`.
-
-- [`ExpiringStore.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put) (`key`: `string`, `value`: `T`, `expires`: `int`, `now`: `int`) → `void`; can fail with `StoreFull`.
-- [`ExpiringStore.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take) (`key`: `string`, `now`: `int`) → `optional T`.
-
-### [`StoreFull`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-StoreFull)
-
-Class from `august.memory`.
-
-Used as a type or provider.
-
-### [`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock)
-
-Capability interface from `august.time`.
-
-- [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) (no caller inputs) → `int`; can fail with `TimeError`.
-
-### [`HttpClient`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient)
-
-Capability interface from `august.web`.
-
-- [`HttpClient.request`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request) (`method`: `string`, `url`: `string`, `headers`: `optional Headers`, `body`: `optional Bytes`) → `HttpResponse<Bytes>`; can fail with `HttpError`.
-
-### [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode)
-
-Function from `august.web`.
-
-- [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) (`input`: `string`) → `string`; can fail with `HttpError`.
-
-### [`LoginTransaction`](contracts.aug.md#symbol-LoginTransaction)
-
-Record from `contracts`.
-
-- Construct with `state`: `string`, `nonce`: `string`, `verifier`: `string`, `expires`: `int` → [`LoginTransaction`](contracts.aug.md#symbol-LoginTransaction).
-- Read `expires` (`int`).
-- Read `nonce` (`string`).
-- Read `state` (`string`).
-- Read `verifier` (`string`).
-
-### [`SessionClaims`](contracts.aug.md#symbol-SessionClaims)
-
-Record from `contracts`.
-
-- Construct with `iss`: `string`, `sub`: `string`, `aud`: `string`, `exp`: `int`, `iat`: `int`, `jti`: `string`, `csrf`: `string`, `name`: `string` → [`SessionClaims`](contracts.aug.md#symbol-SessionClaims).
-- Read `exp` (`int`).
-- Read `jti` (`string`).
-
-### [`SessionError`](contracts.aug.md#symbol-SessionError)
-
-Class from `contracts`.
-
-- Construct with no caller inputs → [`SessionError`](contracts.aug.md#symbol-SessionError).
-
-### [`discover`](protocol.aug.md#symbol-discover)
-
-Function from `protocol`.
-
-- [`discover`](protocol.aug.md#symbol-discover) (no caller inputs) → [`Discovery`](../provider/discovery.aug.md#symbol-Discovery); inject `client`: [`HttpClient`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient); uses [`client.request`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request); can fail with `SessionError`, `HttpError`.
-
-### [`responseJson`](protocol.aug.md#symbol-responseJson)
-
-Function from `protocol`.
-
-- [`responseJson`](protocol.aug.md#symbol-responseJson) (`response`: `HttpResponse<Bytes>`) → `Json`; can fail with `SessionError`.
-
-### [`validateIdentity`](protocol.aug.md#symbol-validateIdentity)
-
-Function from `protocol`.
-
-- [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) (`token`: `string`, `nonce`: `string`, `now`: `int`, `jwks`: [`RsaJwks`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwks)) → [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims); inject `crypto`: [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto); uses [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`crypto.importRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.importRsa), [`crypto.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa), [`crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal); can fail with `SessionError`.
-
-### [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders)
-
-Function from `common`.
-
-- [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) (no caller inputs) → `Headers`; can fail with `HttpError`.
-
-### [`withCookie`](../common/headers.aug.md#symbol-withCookie)
-
-Function from `common`.
-
-- [`withCookie`](../common/headers.aug.md#symbol-withCookie) (`headers`: `Headers`, `name`: `string`, `value`: `string`, `path`: `string`, `maxAge`: `int`, `secure`: `bool`) → `Headers`; can fail with `HttpError`.
-
-### [`KeyError`](../common/keys.aug.md#symbol-KeyError)
-
-Class from `common`.
-
-Used as a type or provider.
-
-### [`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)
-
-Capability interface from `common`.
-
-- [`SigningKeys.session`](../common/keys.aug.md#symbol-SigningKeys.session) (no caller inputs) → `RsaPrivateKey`; can fail with `KeyError`.
-
-### [`Settings`](../common/settings.aug.md#symbol-Settings)
-
-Record.
-
-- Read `baseUrl` (`string`).
-- Read `callback` (`string`).
-- Read `clientId` (`string`).
-- Read `secureCookies` (`bool`).
-- Read `sessionSeconds` (`int`).
-
-### [`settings`](../common/settings.aug.md#symbol-settings)
-
-Function from `common`.
-
-- [`settings`](../common/settings.aug.md#symbol-settings) (no caller inputs) → [`Settings`](../common/settings.aug.md#symbol-Settings).
-
-### [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims)
-
-Record.
+`loginCallback` handles `GET /login/callback`. Exchange a one-use code over HTTP, verify the provider JWT/JWKS and UserInfo subject, then issue a distinct app-session JWT.
 
-- Read `sub` (`string`).
+It takes `code` and `state` as strings from the HTTP query and `browser` as `optional string` from the HTTP cookie `aug_login`. It gets `crypto` ([`Crypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto)), `clock` ([`Clock`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock)), `client` ([`HttpClient`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-HttpClient)), `keys` ([`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)), `transactions` ([`ExpiringStore<LoginTransaction>`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore)), and `sessions` ([`ExpiringStore<SessionClaims>`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore)) from dependency injection. Omitted optional inputs are null. The handler responds with HTTP 400 for [`SessionError`](contracts.aug.md#symbol-SessionError), HTTP 503 for `CryptoError`, HTTP 503 for `TimeError`, and HTTP 503 for [`StoreFull`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-StoreFull).
 
-### [`TokenResponse`](../provider/contracts.aug.md#symbol-TokenResponse)
+It can also raise `HttpError`, `JsonError`, `JwtError`, and `KeyError`.
 
-Record from `provider`.
+It checks that `code` is a URL-safe ASCII token with `43` to `43` characters and `state` is a URL-safe ASCII token with `43` to `43` characters. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. If `browser` is null, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError). The non-null `browser` becomes `secret`.
 
-- Read `access_token` (`string`).
-- Read `expires_in` (`int`).
-- Read `id_token` (`string`).
-- Read `token_type` (`string`).
+It obtains [`transactions.take`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.take) with `key` from `secret` and `now` from [`clock.now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now). If no value is found, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError). The non-null result becomes `transaction`.
 
-### [`UserInfo`](../provider/contracts.aug.md#symbol-UserInfo)
+It checks that [`crypto.equal`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.equal) with `left` from the UTF-8 bytes of `transaction.state` and `right` from the UTF-8 bytes of `state` returns true. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It gets `config` from [`settings`](../common/settings.aug.md#symbol-settings). It gets `document` from [`discover`](protocol.aug.md#symbol-discover) using injected `client`.
 
-Record from `provider`.
+It builds `body` as the text `grant_type=authorization_code&code={urlEncode with input from code}&redirect_uri={urlEncode with input from config.callback}&client_id={urlEncode with input from config.clientId}&code_verifier={urlEncode with input from transaction.verifier}`. It sets `headers` to a `Headers` with the header `"content-type"` set to `"application/x-www-form-urlencoded"`. It sets `tokens` to `decode` on [`responseJson`](protocol.aug.md#symbol-responseJson) with `response` from [`client.request`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-HttpClient.request) with `method` `"POST"`, `url` from `document.token_endpoint`, `headers`, and `body` from the UTF-8 bytes of `body` for [`TokenResponse`](../provider/contracts.aug.md#symbol-TokenResponse).
 
-- Read `name` (`string`).
-- Read `sub` (`string`).
+It checks that `tokens.token_type` equals `"Bearer"` and `tokens.access_token` is a URL-safe ASCII token with `43` to `43` characters and `tokens.expires_in` is greater than `0`. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It sets `jwks` to `decode` on [`responseJson`](protocol.aug.md#symbol-responseJson) with `response` from [`client.request`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-HttpClient.request) with `method` `"GET"` and `url` from `document.jwks_uri` for [`RsaJwks`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-RsaJwks). It sets `identity` to [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) with `token` from `tokens.id_token`, `transaction.nonce`, `now` from [`clock.now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now), and `jwks` using injected `crypto`.
 
-### [`Discovery`](../provider/discovery.aug.md#symbol-Discovery)
+It sets `authHeaders` to a `Headers` with the header `"authorization"` set to the text `Bearer {tokens.access_token}`. It sets `user` to `decode` on [`responseJson`](protocol.aug.md#symbol-responseJson) with `response` from [`client.request`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-HttpClient.request) with `method` `"GET"`, `url` from `document.userinfo_endpoint`, and `headers` from `authHeaders` for [`UserInfo`](../provider/contracts.aug.md#symbol-UserInfo). It checks that `user.sub` equals `identity.sub`. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check.
 
-Record.
+It sets `now` to [`clock.now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now). It sets `session` to a [`SessionClaims`](contracts.aug.md#symbol-SessionClaims) with `iss` from the text `{config.baseUrl}/app`, `identity.sub`, `aud` `"august-app"`, `exp` from `now` plus `config.sessionSeconds`, `iat` from `now`, `jti` from the URL-safe base64 encoding of [`crypto.random`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.random) with `size` `32`, `csrf` from the URL-safe base64 encoding of [`crypto.random`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.random) with `size` `32`, and `user.name`. It sets `jwt` to [`signJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-signJwt) with `key` from [`keys.session`](../common/keys.aug.md#symbol-SigningKeys.session), `claims` from a `Json` with `value` from `session`, `kid` `"session-1"`, and `tokenType` `"august-session+jwt"` using injected `crypto`. It calls [`sessions.put`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.put) with `key` from `session.jti`, `value` from `session`, `expires` from `session.exp`, and `now`.
 
-- Read `authorization_endpoint` (`string`).
-- Read `jwks_uri` (`string`).
-- Read `token_endpoint` (`string`).
-- Read `userinfo_endpoint` (`string`).
+It sets `responseHeaders` to [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` from [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with the header `"location"` set to `"/"`, `name` `"aug_session"`, `value` from `jwt`, `path` `"/"`, `maxAge` from `config.sessionSeconds`, and `secure` from `config.secureCookies`. It sets `responseHeaders` to [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` from `responseHeaders`, `name` `"aug_login"`, `value` `""`, `path` `"/login"`, `maxAge` `0`, and `secure` from `config.secureCookies`. It returns HTTP 303 with a paragraph containing `Signed in.` with escaped text and `responseHeaders` headers.
 
-## Built-in operations used by this file
+## Dependencies
 
-- `Bytes.base64url` (no inputs) → `string`: Encode immutable bytes as unpadded RFC 4648 URL-safe base64.
-- `Headers.with` (`name`: `string`, `value`: `string`) → `Headers`: Return new headers with one additional validated field. Header names ignore case; duplicate values remain separate. Can fail with `HttpError`.
-- `Json.decode` (no inputs) → `UserInfo`: Decode a checked record or data type: json.decode<Profile>(). Unknown fields, type mismatches, and validation errors are rejected. Can fail with `JsonError`.
-- `string.bytes` (no inputs) → `Bytes`: Encode this string as immutable UTF-8 bytes.
-- `string.isToken` (`min`: `int`, `max`: `int`) → `bool`: Require an ASCII RFC 3986 unreserved token with a bounded length.
+It uses [`ExpiringStore`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore) ([`put`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.put) and [`take`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.take)) and [`StoreFull`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-StoreFull) from `memory`. It uses [`HttpClient`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-HttpClient) ([`request`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-HttpClient.request)) and [`urlEncode`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-urlEncode) from `web`. It uses [`Crypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto) ([`decodeBase64url`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.decodeBase64url), [`equal`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.equal), [`importRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.importRsa), [`random`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.random), [`sha256`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.sha256), [`signRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.signRsa), and [`verifyRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.verifyRsa)), [`JwtError`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-JwtError), [`RsaJwks`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-RsaJwks), and [`signJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-signJwt) from `crypto`. It uses [`Clock`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock) ([`now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now)) from `time`.
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+It uses [`LoginTransaction`](contracts.aug.md#symbol-LoginTransaction) (`expires`, `nonce`, `state`, and `verifier`), [`SessionClaims`](contracts.aug.md#symbol-SessionClaims) (`exp` and `jti`), and [`SessionError`](contracts.aug.md#symbol-SessionError) from `contracts`. It uses [`discover`](protocol.aug.md#symbol-discover), [`responseJson`](protocol.aug.md#symbol-responseJson), and [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) from `protocol`. It uses [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders), [`withCookie`](../common/headers.aug.md#symbol-withCookie), [`KeyError`](../common/keys.aug.md#symbol-KeyError), [`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys) ([`session`](../common/keys.aug.md#symbol-SigningKeys.session)), and [`settings`](../common/settings.aug.md#symbol-settings) from `common`. It uses [`Settings`](../common/settings.aug.md#symbol-Settings) (`baseUrl`, `callback`, `clientId`, `secureCookies`, and `sessionSeconds`), [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims) (`sub`), and [`Discovery`](../provider/discovery.aug.md#symbol-Discovery) (`authorization_endpoint`, `jwks_uri`, `token_endpoint`, and `userinfo_endpoint`).
 
-## Shared language rules
+It uses [`TokenResponse`](../provider/contracts.aug.md#symbol-TokenResponse) (`access_token`, `expires_in`, `id_token`, and `token_type`) and [`UserInfo`](../provider/contracts.aug.md#symbol-UserInfo) (`name` and `sub`) from `provider`.
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

package/examples/oidc-login/client/logout.aug

@@ -1,12 +1,13 @@
+// aug-spec: "logout.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import SessionClaims and SessionError and LogoutForm from contracts
 import authenticate from session
 import settings and SigningKeys and KeyError and securityHeaders and withCookie from common
-import Crypto from august.crypto
-import Clock from august.time
-import ExpiringStore from august.memory
+import Crypto from crypto
+import Clock from time
+import ExpiringStore from memory
 
 /** POST logout checks the origin and session-bound CSRF value, then removes the live registry entry before clearing the cookie. */
-endpoint POST "/logout" as logout(LogoutForm input from form, optional string token from cookie "aug_session", optional string origin from header, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) returns HttpResponse<Html> uses crypto.publicRsa and crypto.decodeBase64url and crypto.verifyRsa and crypto.equal and clock.now and keys.session and sessions.get and sessions.take unless SessionError with status 403 and KeyError and TimeError and CryptoError and HttpError:
+endpoint POST "/logout" as logout(LogoutForm input from form, optional string token from cookie "aug_session", optional string origin from header, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) unless SessionError with status 403 and KeyError and TimeError and CryptoError and HttpError:
     config = settings()
     if origin != config.baseUrl:
         throw SessionError()

package/examples/oidc-login/client/logout.aug.md

@@ -1,150 +1,28 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `logout.aug` specification
+# `logout.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`logout`](logout.aug.md#symbol-logout) handles `POST` `/logout` returning `HttpResponse<Html>`.
+Plain handler results default to HTTP 200 unless another status is declared. HttpResponse values choose their own status. Unhandled request failures return HTTP 500 and cancel the request tasks.
 
 <a id="symbol-logout"></a>
+## `logout` · [source](logout.aug#L10)
 
-## `logout`
-
-[source](logout.aug#L9)
-
-**Inputs**
-
-- `input` ([`LogoutForm`](contracts.aug.md#symbol-LogoutForm)) — read from the HTTP form.
-- `token` (`optional string`) — read from the HTTP cookie named `aug_session`; absent value becomes null.
-- `origin` (`optional string`) — read from the HTTP header; absent value becomes null.
-- `crypto` ([`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)) — injected; callers omit it.
-- `clock` ([`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock)) — injected; callers omit it.
-- `keys` ([`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)) — injected; callers omit it.
-- `sessions` ([`ExpiringStore<SessionClaims>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
-
-Returns: `HttpResponse<Html>`.
-
-Capabilities: [`crypto.publicRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.publicRsa), [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`crypto.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa), [`crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal), [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`keys.session`](../common/keys.aug.md#symbol-SigningKeys.session), [`sessions.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get), [`sessions.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take).
-
-Can fail with `SessionError`, `KeyError`, `TimeError`, `CryptoError`, `HttpError`. Callers must catch or propagate these errors.
-
-HTTP route: `POST` `/logout`. Use status 200 when the handler returns a body; a returned HttpResponse can set its own status. An unhandled request failure returns status 500 and cancels its request tasks.
-
-Declared HTTP failures: [`SessionError`](contracts.aug.md#symbol-SessionError) returns status 403.
-
-**What it does**
-
-- Set `config` to call [`settings`](../common/settings.aug.md#symbol-settings).
-- If `origin` does not equal `baseUrl` of `config`:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- Set `session` to call [`authenticate`](session.aug.md#symbol-authenticate) with `token` = `token`; inject `crypto` from `crypto`, `clock` from `clock`, `keys` from `keys`, `sessions` from `sessions`.
-- If not (call [`Crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal) on `crypto` with `left` = call `bytes` on `csrf` of `input`; `right` = call `bytes` on `csrf` of `session`):
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- Call [`ExpiringStore.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take) on `sessions` with `key` = `jti` of `session`; `now` = call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`.
-- Set `headers` to call [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` = call `with` on call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with `name` = `"location"`; `value` = `"/"`; `name` = `"aug_session"`; `value` = `""`; `path` = `"/"`; `maxAge` = `0`; `secure` = `secureCookies` of `config`.
-- Return call `HttpResponse` with `body` = the HTML element `p` containing `Signed out.` (rendered on the server with embedded text escaped); `status` = `303`; `headers` = `headers`.
-
-**Author documentation**
-
-POST logout checks the origin and session-bound CSRF value, then removes the live registry entry before clearing the cookie.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)
-
-Capability interface from `august.crypto`.
-
-- [`Crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url) (`input`: `string`) → `Bytes`; can fail with `CryptoError`.
-- [`Crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal) (`left`: `Bytes`, `right`: `Bytes`) → `bool`.
-- [`Crypto.publicRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.publicRsa) (`key`: `RsaPrivateKey`) → `RsaPublicKey`; can fail with `CryptoError`.
-- [`Crypto.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa) (`publicKey`: `RsaPublicKey`, `input`: `Bytes`, `signature`: `Bytes`) → `bool`; can fail with `CryptoError`.
-
-### [`ExpiringStore`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)
-
-Capability interface from `august.memory`.
-
-- [`ExpiringStore.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get) (`key`: `string`, `now`: `int`) → `optional T`.
-- [`ExpiringStore.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take) (`key`: `string`, `now`: `int`) → `optional T`.
-
-### [`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock)
-
-Capability interface from `august.time`.
-
-- [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) (no caller inputs) → `int`; can fail with `TimeError`.
-
-### [`LogoutForm`](contracts.aug.md#symbol-LogoutForm)
-
-Record from `contracts`.
-
-- Read `csrf` (`string`).
-
-### [`SessionClaims`](contracts.aug.md#symbol-SessionClaims)
-
-Record from `contracts`.
-
-- Read `csrf` (`string`).
-- Read `jti` (`string`).
-
-### [`SessionError`](contracts.aug.md#symbol-SessionError)
-
-Class from `contracts`.
-
-- Construct with no caller inputs → [`SessionError`](contracts.aug.md#symbol-SessionError).
-
-### [`authenticate`](session.aug.md#symbol-authenticate)
-
-Function from `session`.
-
-- [`authenticate`](session.aug.md#symbol-authenticate) (`token`: `optional string`) → [`SessionClaims`](contracts.aug.md#symbol-SessionClaims); inject `crypto`: [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto), `clock`: [`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock), `keys`: [`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys), `sessions`: [`ExpiringStore<SessionClaims>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore); uses [`crypto.publicRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.publicRsa), [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`crypto.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa), [`crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal), [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`keys.session`](../common/keys.aug.md#symbol-SigningKeys.session), [`sessions.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get); can fail with `SessionError`, `KeyError`, `TimeError`.
-
-### [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders)
-
-Function from `common`.
-
-- [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) (no caller inputs) → `Headers`; can fail with `HttpError`.
-
-### [`withCookie`](../common/headers.aug.md#symbol-withCookie)
-
-Function from `common`.
-
-- [`withCookie`](../common/headers.aug.md#symbol-withCookie) (`headers`: `Headers`, `name`: `string`, `value`: `string`, `path`: `string`, `maxAge`: `int`, `secure`: `bool`) → `Headers`; can fail with `HttpError`.
-
-### [`KeyError`](../common/keys.aug.md#symbol-KeyError)
-
-Class from `common`.
-
-Used as a type or provider.
-
-### [`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)
-
-Capability interface from `common`.
-
-- [`SigningKeys.session`](../common/keys.aug.md#symbol-SigningKeys.session) (no caller inputs) → `RsaPrivateKey`; can fail with `KeyError`.
-
-### [`Settings`](../common/settings.aug.md#symbol-Settings)
-
-Record.
+`logout` handles `POST /logout`. POST logout checks the origin and session-bound CSRF value, then removes the live registry entry before clearing the cookie.
 
-- Read `baseUrl` (`string`).
-- Read `secureCookies` (`bool`).
+It takes `input` as [`LogoutForm`](contracts.aug.md#symbol-LogoutForm) from the HTTP form, `token` as `optional string` from the HTTP cookie `aug_session`, and `origin` as `optional string` from the HTTP header. It gets `crypto` ([`Crypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto)), `clock` ([`Clock`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock)), `keys` ([`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)), and `sessions` ([`ExpiringStore<SessionClaims>`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore)) from dependency injection. Omitted optional inputs are null. The handler responds with HTTP 403 for [`SessionError`](contracts.aug.md#symbol-SessionError).
 
-### [`settings`](../common/settings.aug.md#symbol-settings)
+It can also raise `CryptoError`, `HttpError`, `KeyError`, and `TimeError`.
 
-Function from `common`.
+It gets `config` from [`settings`](../common/settings.aug.md#symbol-settings). It checks that `origin` equals `config.baseUrl`. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It sets `session` to [`authenticate`](session.aug.md#symbol-authenticate) with `token` using injected `crypto`, `clock`, `keys`, and `sessions`.
 
-- [`settings`](../common/settings.aug.md#symbol-settings) (no caller inputs) → [`Settings`](../common/settings.aug.md#symbol-Settings).
+It checks that [`crypto.equal`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.equal) with `left` from the UTF-8 bytes of `input.csrf` and `right` from the UTF-8 bytes of `session.csrf` returns true. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It calls [`sessions.take`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.take) with `key` from `session.jti` and `now` from [`clock.now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now). It sets `headers` to [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` from [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with the header `"location"` set to `"/"`, `name` `"aug_session"`, `value` `""`, `path` `"/"`, `maxAge` `0`, and `secure` from `config.secureCookies`.
 
-## Built-in operations used by this file
+It returns HTTP 303 with a paragraph containing `Signed out.` with escaped text and `headers` headers.
 
-- `Headers.with` (`name`: `string`, `value`: `string`) → `Headers`: Return new headers with one additional validated field. Header names ignore case; duplicate values remain separate. Can fail with `HttpError`.
-- `string.bytes` (no inputs) → `Bytes`: Encode this string as immutable UTF-8 bytes.
+## Dependencies
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+It uses [`ExpiringStore`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore) ([`get`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.get) and [`take`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.take)) from `memory`. It uses [`Crypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto) ([`decodeBase64url`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.decodeBase64url), [`equal`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.equal), [`publicRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.publicRsa), and [`verifyRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.verifyRsa)) from `crypto`. It uses [`Clock`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock) ([`now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now)) from `time`. It uses [`LogoutForm`](contracts.aug.md#symbol-LogoutForm) (`csrf`), [`SessionClaims`](contracts.aug.md#symbol-SessionClaims) (`csrf` and `jti`), and [`SessionError`](contracts.aug.md#symbol-SessionError) from `contracts`.
 
-## Shared language rules
+It uses [`authenticate`](session.aug.md#symbol-authenticate) from `session`. It uses [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders), [`withCookie`](../common/headers.aug.md#symbol-withCookie), [`KeyError`](../common/keys.aug.md#symbol-KeyError), [`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys) ([`session`](../common/keys.aug.md#symbol-SigningKeys.session)), and [`settings`](../common/settings.aug.md#symbol-settings) from `common`. It uses [`Settings`](../common/settings.aug.md#symbol-Settings) (`baseUrl` and `secureCookies`).
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).