@greenpandastudios/aug-cli 0.19.0 → 0.20.1

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

@@ -1,12 +1,13 @@
+// aug-spec: "protocol.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import SessionError from contracts
 import Discovery and IdClaims from provider
 import settings from common
-import HttpClient from august.web
-import parse from august.json
-import Crypto and GnuTlsCrypto and RsaJwks and rsaJwk and signJwt and importJwk and verifyJwt and JwtError from august.crypto
+import HttpClient from web
+import parse from json
+import Crypto and GnuTlsCrypto and RsaJwks and rsaJwk and signJwt and importJwk and verifyJwt and JwtError from crypto
 
 /** Accept only a successful JSON response. Redirects remain explicit and are never followed by the transport. */
-responseJson(HttpResponse<Bytes> response) returns Json unless SessionError:
+responseJson(HttpResponse<Bytes> response) :
     if response.status != 200:
         throw SessionError()
     match response.headers.get(name="content-type"):
@@ -23,7 +24,7 @@ responseJson(HttpResponse<Bytes> response) returns Json unless SessionError:
         throw SessionError()
 
 /** Discovery is fetched over HTTP. Every advertised URL is checked against the registered issuer before any credential is sent. */
-discover(resolve HttpClient client) returns Discovery uses client.request unless SessionError and HttpError:
+discover(resolve HttpClient client) :
     config = settings()
     json = responseJson(response=client.request(method="GET", url=config.issuer + "/.well-known/openid-configuration"))
     try:
@@ -35,7 +36,7 @@ discover(resolve HttpClient client) returns Discovery uses client.request unless
         throw SessionError()
 
 /** Validate the signed ID token using a public key from this issuer's HTTP JWKS, then validate the registered claims and one-use nonce. */
-validateIdentity(string token, string nonce, int now, RsaJwks jwks, resolve Crypto crypto) returns IdClaims uses crypto.decodeBase64url and crypto.importRsa and crypto.verifyRsa and crypto.equal unless SessionError:
+validateIdentity(string token, string nonce, int now, RsaJwks jwks, resolve Crypto crypto) :
     config = settings()
     if jwks.keys.length() != 1:
         throw SessionError()

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

@@ -1,326 +1,79 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `protocol.aug` specification
-
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`responseJson`](protocol.aug.md#symbol-responseJson) is a function returning `Json`.
-- [`discover`](protocol.aug.md#symbol-discover) is a function returning `Discovery`.
-- [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) is a function returning `IdClaims`.
-- [`test validateIdentity`](protocol.aug.md#symbol-test%20validateIdentity) is a same-file test suite.
+# `protocol.aug`
 
 <a id="symbol-responseJson"></a>
+## `responseJson` · [source](protocol.aug#L10)
 
-## `responseJson`
-
-[source](protocol.aug#L9)
-
-**Inputs**
+Accept only a successful JSON response. Redirects remain explicit and are never followed by the transport. It takes `response` as `HttpResponse<Bytes>`. Failures can raise [`SessionError`](contracts.aug.md#symbol-SessionError).
 
-- `response` (`HttpResponse<Bytes>`) — required labeled input.
+It checks that `response.status` equals `200`. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It obtains `response.headers.get` with `name` `"content-type"`. If no value is found, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError).
 
-Returns: `Json`.
+The non-null result becomes `contentType`. It checks that `contentType.startsWith` with `prefix` `"application/json"` returns true. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check.
 
-Can fail with `SessionError`. Callers must catch or propagate these errors.
-
-**What it does**
-
-- If `status` of `response` does not equal `200`:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- Select the matching case for call `get` on `headers` of `response` with `name` = `"content-type"`:
-  - 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 `contentType`:
-    - If not (call `startsWith` on `contentType` with `prefix` = `"application/json"`):
-      - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- Try these operations:
-  - Return call [`parse`](../.aug-spec/august/0.19.0/json/contracts.aug.md#symbol-parse) with `input` = call `text` on `body` of `response`.
-- If they fail with `ConversionError`, name the failure `error` and recover:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- If they fail with `JsonError`, name the failure `error` and recover:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-
-**Author documentation**
-
-Accept only a successful JSON response. Redirects remain explicit and are never followed by the transport.
+It tries to return [`parse`](../.aug-spec/packages/%40git/url_2d3c37c690c0fa115be1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-parse) with `input` from `response.body.text`. If this work raises `ConversionError`, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError). If this work raises `JsonError`, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError).
 
 <a id="symbol-discover"></a>
+## `discover` · [source](protocol.aug#L27)
 
-## `discover`
-
-[source](protocol.aug#L26)
+Discovery is fetched over HTTP. Every advertised URL is checked against the registered issuer before any credential is sent. It gets `client` ([`HttpClient`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-HttpClient)) from dependency injection. Failures can raise `HttpError` and [`SessionError`](contracts.aug.md#symbol-SessionError).
 
-**Inputs**
+It gets `config` from [`settings`](../common/settings.aug.md#symbol-settings). It sets `json` to [`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 the text `{config.issuer}/.well-known/openid-configuration`. It sets `document` to `json.decode` for [`Discovery`](../provider/discovery.aug.md#symbol-Discovery).
 
-- `client` ([`HttpClient`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient)) — injected; callers omit it.
-
-Returns: [`Discovery`](../provider/discovery.aug.md#symbol-Discovery).
-
-Capabilities: [`client.request`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request).
-
-Can fail with `SessionError`, `HttpError`. Callers must catch or propagate these errors.
-
-**What it does**
-
-- Set `config` to call [`settings`](../common/settings.aug.md#symbol-settings).
-- Set `json` to 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` = (`issuer` of `config` plus `"/.well-known/openid-configuration"`).
-- Try these operations:
-  - Set `document` to call `decode` on `json` with type arguments [`Discovery`](../provider/discovery.aug.md#symbol-Discovery).
-  - If ((((`issuer` of `document` does not equal `issuer` of `config`) or (`authorization_endpoint` of `document` does not equal (`issuer` of `config` plus `"/authorize"`))) or (`token_endpoint` of `document` does not equal (`issuer` of `config` plus `"/token"`))) or (`jwks_uri` of `document` does not equal (`issuer` of `config` plus `"/jwks"`))) or (`userinfo_endpoint` of `document` does not equal (`issuer` of `config` plus `"/userinfo"`)):
-    - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-  - Return `document`.
-- If they fail with `JsonError`, name the failure `error` and recover:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-
-**Author documentation**
-
-Discovery is fetched over HTTP. Every advertised URL is checked against the registered issuer before any credential is sent.
+It checks that `document.issuer` equals `config.issuer` and `document.authorization_endpoint` equals the text `{config.issuer}/authorize` and `document.token_endpoint` equals the text `{config.issuer}/token` and `document.jwks_uri` equals the text `{config.issuer}/jwks` and `document.userinfo_endpoint` equals the text `{config.issuer}/userinfo`. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It returns `document`. If this work raises `JsonError`, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError).
 
 <a id="symbol-validateIdentity"></a>
+## `validateIdentity` · [source](protocol.aug#L39)
 
-## `validateIdentity`
-
-[source](protocol.aug#L38)
-
-**Inputs**
+Validate the signed ID token using a public key from this issuer's HTTP JWKS, then validate the registered claims and one-use nonce. It takes `token` and `nonce` as strings, `now` as an integer, and `jwks` as [`RsaJwks`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-RsaJwks). It gets `crypto` ([`Crypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto)) from dependency injection. Failures can raise [`SessionError`](contracts.aug.md#symbol-SessionError).
 
-- `token` (`string`) — required labeled input.
-- `nonce` (`string`) — required labeled input.
-- `now` (`int`) — required labeled input.
-- `jwks` ([`RsaJwks`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwks)) — required labeled input.
-- `crypto` ([`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)) — injected; callers omit it.
+It gets `config` from [`settings`](../common/settings.aug.md#symbol-settings). It checks that the number of elements in `jwks.keys` equals `1`. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It sets `jwk` to the item at index `0` in `jwks.keys`.
 
-Returns: [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims).
+It checks that `jwk.kid` equals `"provider-1"`. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It sets `publicKey` to [`importJwk`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-importJwk) with `jwk` using injected `crypto`. It sets `claims` to `decode` on [`verifyJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-verifyJwt) with `token`, `publicKey`, `kid` `"provider-1"`, and `tokenType` `"JWT"` using injected `crypto` for [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims).
 
-Capabilities: [`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).
+It checks that `claims.iss` equals `config.issuer` and `claims.aud` equals `config.clientId` and the byte length of `claims.sub` does not equal `0` and the byte length of `claims.sub` is at most `255` and `claims.exp` is greater than `now` and `claims.iat` is at least (`now` minus `300`) and `claims.iat` is at most (`now` plus `30`) and `claims.exp` is greater than `claims.iat` and `claims.exp` is at most (`now` plus `330`). It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. 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 `claims.nonce` and `right` from the UTF-8 bytes of `nonce` returns true. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check.
 
-Can fail with `SessionError`. Callers must catch or propagate these errors.
+It returns `claims`. If this work raises [`JwtError`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-JwtError), it raises a [`SessionError`](contracts.aug.md#symbol-SessionError). If this work raises `JsonError`, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError). If this work raises `IndexError`, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError).
 
-**What it does**
-
-- Set `config` to call [`settings`](../common/settings.aug.md#symbol-settings).
-- If call `length` on `keys` of `jwks` does not equal `1`:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- Try these operations:
-  - Set `jwk` to call `get` on `keys` of `jwks` with `index` = `0`.
-  - If `kid` of `jwk` does not equal `"provider-1"`:
-    - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-  - Set `publicKey` to call [`importJwk`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-importJwk) with `jwk` = `jwk`; inject `crypto` from `crypto`.
-  - Set `claims` to call `decode` on call [`verifyJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-verifyJwt) with `token` = `token`; `publicKey` = `publicKey`; `kid` = `"provider-1"`; `tokenType` = `"JWT"`; inject `crypto` from `crypto` with type arguments [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims).
-  - If (((`iss` of `claims` does not equal `issuer` of `config`) or (`aud` of `claims` does not equal `clientId` of `config`)) or (call `length` on `sub` of `claims` equals `0`)) or (call `length` on `sub` of `claims` is greater than `255`):
-    - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-  - If ((((`exp` of `claims` is at most `now`) or (`iat` of `claims` is less than (`now` minus `300`))) or (`iat` of `claims` is greater than (`now` plus `30`))) or (`exp` of `claims` is at most `iat` of `claims`)) or (`exp` of `claims` is greater than (`now` plus `330`)):
-    - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-  - 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 `nonce` of `claims`; `right` = call `bytes` on `nonce`):
-    - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-  - Return `claims`.
-- If they fail with [`JwtError`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-JwtError), name the failure `error` and recover:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- If they fail with `JsonError`, name the failure `error` and recover:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- If they fail with `IndexError`, name the failure `error` and recover:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-- If they fail with `CryptoError`, name the failure `error` and recover:
-  - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-
-**Author documentation**
-
-Validate the signed ID token using a public key from this issuer's HTTP JWKS, then validate the registered claims and one-use nonce.
+If this work raises `CryptoError`, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError).
 
 <a id="symbol-test validateIdentity"></a>
+## `test validateIdentity` · [source](protocol.aug#L65)
 
-## `test validateIdentity`
-
-[source](protocol.aug#L64)
-
-Same-file function tests for [`validateIdentity`](protocol.aug.md#symbol-validateIdentity). Each case gets isolated setup and dependency bindings.
+Tests [`validateIdentity`](protocol.aug.md#symbol-validateIdentity). Each case gets fresh setup and dependencies.
 
-### Group `signed_identity_claims`
+### `signed_identity_claims`
 
-**Setup before each case**
+Setup for each case: `Crypto` is provided by [`GnuTlsCrypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-GnuTlsCrypto). Stateless instances are reused; stateful instances are created for each resolve. It sets `crypto` to the instance provided for `Crypto`. It sets `key` to [`crypto.generateRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.generateRsa).
 
-- Provide [`GnuTlsCrypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-GnuTlsCrypto) when `Crypto` is requested. Use a fresh instance when this provider retains state; otherwise reuse one instance.
-- Set `crypto` to the instance provided for `Crypto`.
-- Set `key` to call [`Crypto.generateRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.generateRsa) on `crypto`.
-- Set `publicKey` to call [`Crypto.publicRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.publicRsa) on `crypto` with `key` = `key`.
-- Set `jwks` to call [`RsaJwks`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwks) with `keys` = a list containing call [`rsaJwk`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-rsaJwk) with `publicKey` = `publicKey`; `kid` = `"provider-1"`; inject `crypto` from `Crypto`.
-- Set `config` to call [`settings`](../common/settings.aug.md#symbol-settings).
-- Set `now` to `1700000000`.
-- Set `expectedNonce` to `"nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn"`.
+It sets `publicKey` to [`crypto.publicRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.publicRsa) with `key`. It sets `jwks` to a [`RsaJwks`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-RsaJwks) with `keys` from a list containing [`rsaJwk`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-rsaJwk) with `publicKey` and `kid` `"provider-1"` using injected `Crypto` for `crypto`. It gets `config` from [`settings`](../common/settings.aug.md#symbol-settings). It sets `now` to `1700000000`.
 
-#### `accepts_valid_identity`
+It sets `expectedNonce` to `"nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn"`.
 
-[source](protocol.aug#L75)
+#### `accepts_valid_identity` · [source](protocol.aug#L76)
 
-- Set `claims` to call [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims) with `iss` = `issuer` of `config`; `sub` = `"ada"`; `aud` = `clientId` of `config`; `exp` = (`now` plus `300`); `iat` = `now`; `nonce` = `expectedNonce`; `name` = `"Ada"`.
-- Set `token` to call [`signJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-signJwt) with `key` = `key`; `claims` = call `Json` with `value` = `claims`; `kid` = `"provider-1"`; `tokenType` = `"JWT"`; inject `crypto` from `Crypto`.
-- Set `identity` to call [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) with `token` = `token`; `nonce` = `expectedNonce`; `now` = `now`; `jwks` = `jwks`; inject `crypto` from `Crypto`.
-- Call `assert` with `condition` = (`sub` of `identity` equals `"ada"`).
+It sets `claims` to an [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims) with `iss` from `config.issuer`, `sub` `"ada"`, `aud` from `config.clientId`, `exp` from `now` plus `300`, `iat` from `now`, `nonce` from `expectedNonce`, and `name` `"Ada"`. It sets `token` to [`signJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-signJwt) with `key`, `claims` from a `Json` with `value` from `claims`, `kid` `"provider-1"`, and `tokenType` `"JWT"` using injected `Crypto` for `crypto`. It sets `identity` to [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) with `token`, `nonce` from `expectedNonce`, `now`, and `jwks` using injected `Crypto` for `crypto`. The test requires `identity.sub` equals `"ada"`.
 
-#### `rejects_signed_invalid_claims`
+#### `rejects_signed_invalid_claims` · [source](protocol.aug#L82)
 
-[source](protocol.aug#L81)
+Run once for each row of a tuple containing `"https://wrong-issuer.invalid"`, `config.clientId`, `"ada"`, `now`, `now` plus `300`, `expectedNonce`; a tuple containing `config.issuer`, `"wrong-audience"`, `"ada"`, `now`, `now` plus `300`, `expectedNonce`; a tuple containing `config.issuer`, `config.clientId`, `""`, `now`, `now` plus `300`, `expectedNonce`; a tuple containing `config.issuer`, `config.clientId`, `"ada"`, `now` minus `400`, `now` plus `300`, `expectedNonce`; a tuple containing `config.issuer`, `config.clientId`, `"ada"`, `now` plus `100`, `now` plus `300`, `expectedNonce`; a tuple containing `config.issuer`, `config.clientId`, `"ada"`, `now`, `now`, `expectedNonce`; a tuple containing `config.issuer`, `config.clientId`, `"ada"`, `now`, `now` plus `600`, `expectedNonce`; a tuple containing `config.issuer`, `config.clientId`, `"ada"`, `now`, `now` plus `300`, `"wrong-nonce"`. Bind row positions to `issuer`, `audience`, `subject`, `issued`, `expires`, `nonce`.
 
-Run once for each row of a tuple containing `"https://wrong-issuer.invalid"`, `clientId` of `config`, `"ada"`, `now`, `now` plus `300`, `expectedNonce`; a tuple containing `issuer` of `config`, `"wrong-audience"`, `"ada"`, `now`, `now` plus `300`, `expectedNonce`; a tuple containing `issuer` of `config`, `clientId` of `config`, `""`, `now`, `now` plus `300`, `expectedNonce`; a tuple containing `issuer` of `config`, `clientId` of `config`, `"ada"`, `now` minus `400`, `now` plus `300`, `expectedNonce`; a tuple containing `issuer` of `config`, `clientId` of `config`, `"ada"`, `now` plus `100`, `now` plus `300`, `expectedNonce`; a tuple containing `issuer` of `config`, `clientId` of `config`, `"ada"`, `now`, `now`, `expectedNonce`; a tuple containing `issuer` of `config`, `clientId` of `config`, `"ada"`, `now`, `now` plus `600`, `expectedNonce`; a tuple containing `issuer` of `config`, `clientId` of `config`, `"ada"`, `now`, `now` plus `300`, `"wrong-nonce"`. Bind row positions to `issuer`, `audience`, `subject`, `issued`, `expires`, `nonce`.
+It sets `claims` to an [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims) with `iss` from `issuer`, `sub` from `subject`, `aud` from `audience`, `exp` from `expires`, `iat` from `issued`, `nonce`, and `name` `"Ada"`. It sets `token` to [`signJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-signJwt) with `key`, `claims` from a `Json` with `value` from `claims`, `kid` `"provider-1"`, and `tokenType` `"JWT"` using injected `Crypto` for `crypto`. It calls [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) with `token`, `nonce` from `expectedNonce`, `now`, and `jwks` using injected `Crypto` for `crypto`. The test requires `false` is true.
 
-- Set `claims` to call [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims) with `iss` = `issuer`; `sub` = `subject`; `aud` = `audience`; `exp` = `expires`; `iat` = `issued`; `nonce` = `nonce`; `name` = `"Ada"`.
-- Set `token` to call [`signJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-signJwt) with `key` = `key`; `claims` = call `Json` with `value` = `claims`; `kid` = `"provider-1"`; `tokenType` = `"JWT"`; inject `crypto` from `Crypto`.
-- Try these operations:
-  - Call [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) with `token` = `token`; `nonce` = `expectedNonce`; `now` = `now`; `jwks` = `jwks`; inject `crypto` from `Crypto`.
-  - Call `assert` with `condition` = `false`.
-- If they fail with [`SessionError`](contracts.aug.md#symbol-SessionError), name the failure `error` and recover:
-  - Call `assert` with `condition` = `true`.
+If this work raises [`SessionError`](contracts.aug.md#symbol-SessionError), it the test requires `true` is true.
 
-#### `rejects_token_context`
-
-[source](protocol.aug#L99)
+#### `rejects_token_context` · [source](protocol.aug#L100)
 
 Run once for each row of a tuple containing `"wrong-key"`, `"JWT"`; a tuple containing `"provider-1"`, `"august-session+jwt"`. Bind row positions to `kid`, `tokenType`.
 
-- Set `claims` to call [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims) with `iss` = `issuer` of `config`; `sub` = `"ada"`; `aud` = `clientId` of `config`; `exp` = (`now` plus `300`); `iat` = `now`; `nonce` = `expectedNonce`; `name` = `"Ada"`.
-- Set `token` to call [`signJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-signJwt) with `key` = `key`; `claims` = call `Json` with `value` = `claims`; `kid` = `kid`; `tokenType` = `tokenType`; inject `crypto` from `Crypto`.
-- Try these operations:
-  - Call [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) with `token` = `token`; `nonce` = `expectedNonce`; `now` = `now`; `jwks` = `jwks`; inject `crypto` from `Crypto`.
-  - Call `assert` with `condition` = `false`.
-- If they fail with [`SessionError`](contracts.aug.md#symbol-SessionError), name the failure `error` and recover:
-  - Call `assert` with `condition` = `true`.
-
-## 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.generateRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.generateRsa) (no caller inputs) → `RsaPrivateKey`; can fail with `CryptoError`.
-- [`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.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`.
-
-### [`GnuTlsCrypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-GnuTlsCrypto)
-
-Class from `august.crypto`.
-
-Used as a type or provider.
-
-### [`JwtError`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-JwtError)
-
-Class from `august.crypto`.
-
-Used as a type or provider.
-
-### [`RsaJwk`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwk)
-
-Record.
-
-- Read `kid` (`string`).
-
-### [`RsaJwks`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwks)
-
-Record from `august.crypto`.
-
-- Construct with `keys`: `List<RsaJwk>` → [`RsaJwks`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwks).
-- Read `keys` (`List<RsaJwk>`).
-
-### [`importJwk`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-importJwk)
-
-Function from `august.crypto`.
-
-- [`importJwk`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-importJwk) (`jwk`: [`RsaJwk`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwk)) → `RsaPublicKey`; 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); can fail with `JwtError`.
-
-### [`rsaJwk`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-rsaJwk)
-
-Function from `august.crypto`.
-
-- [`rsaJwk`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-rsaJwk) (`publicKey`: `RsaPublicKey`, `kid`: `string`) → [`RsaJwk`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwk); inject `crypto`: [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto); uses [`crypto.exportRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.exportRsa); can fail with `CryptoError`.
-
-### [`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`.
-
-### [`verifyJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-verifyJwt)
-
-Function from `august.crypto`.
-
-- [`verifyJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-verifyJwt) (`token`: `string`, `publicKey`: `RsaPublicKey`, `kid`: `string`, `tokenType`: `string`) → `Json`; 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.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa); can fail with `JwtError`.
-
-### [`parse`](../.aug-spec/august/0.19.0/json/contracts.aug.md#symbol-parse)
-
-Function from `august.json`.
-
-- [`parse`](../.aug-spec/august/0.19.0/json/contracts.aug.md#symbol-parse) (`input`: `string`) → `Json`; can fail with `JsonError`.
-
-### [`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`.
-
-### [`SessionError`](contracts.aug.md#symbol-SessionError)
-
-Class from `contracts`.
-
-- Construct with no caller inputs → [`SessionError`](contracts.aug.md#symbol-SessionError).
-
-### [`Settings`](../common/settings.aug.md#symbol-Settings)
-
-Record.
-
-- Read `clientId` (`string`).
-- Read `issuer` (`string`).
-
-### [`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 from `provider`.
-
-- Construct with `iss`: `string`, `sub`: `string`, `aud`: `string`, `exp`: `int`, `iat`: `int`, `nonce`: `string`, `name`: `string` → [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims).
-- Read `aud` (`string`).
-- Read `exp` (`int`).
-- Read `iat` (`int`).
-- Read `iss` (`string`).
-- Read `nonce` (`string`).
-- Read `sub` (`string`).
-
-### [`Discovery`](../provider/discovery.aug.md#symbol-Discovery)
-
-Record from `provider`.
-
-- Read `authorization_endpoint` (`string`).
-- Read `issuer` (`string`).
-- Read `jwks_uri` (`string`).
-- Read `token_endpoint` (`string`).
-- Read `userinfo_endpoint` (`string`).
+It sets `claims` to an [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims) with `iss` from `config.issuer`, `sub` `"ada"`, `aud` from `config.clientId`, `exp` from `now` plus `300`, `iat` from `now`, `nonce` from `expectedNonce`, and `name` `"Ada"`. It sets `token` to [`signJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-signJwt) with `key`, `claims` from a `Json` with `value` from `claims`, `kid`, and `tokenType` using injected `Crypto` for `crypto`. It calls [`validateIdentity`](protocol.aug.md#symbol-validateIdentity) with `token`, `nonce` from `expectedNonce`, `now`, and `jwks` using injected `Crypto` for `crypto`. The test requires `false` is true.
 
-## Built-in operations used by this file
+If this work raises [`SessionError`](contracts.aug.md#symbol-SessionError), it the test requires `true` is true.
 
-- `HttpResponse.body` (`Bytes`): The typed response body.
-- `HttpResponse.headers` (`Headers`): Immutable response headers. Duplicate Set-Cookie values are preserved.
-- `HttpResponse.status` (`int`): HTTP response status.
-- `Bytes.text` (no inputs) → `string`: Decode UTF-8 strictly. Invalid input raises ConversionError; embedded NUL is preserved. Can fail with `ConversionError`.
-- `Headers.get` (`name`: `string`) → `optional string`: Read the first case-insensitive header value, or null.
-- `Json.decode` (no inputs) → `IdClaims`: Decode a checked record or data type: json.decode<Profile>(). Unknown fields, type mismatches, and validation errors are rejected. Can fail with `JsonError`.
-- `List<RsaJwk>.get` (`index`: `int`) → `RsaJwk`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
-- `List<RsaJwk>.length` (no inputs) → `int`: Read the number of elements.
-- `assert` (`condition`: `bool`) → `void`: Assert a bool in a test case or its setup. Catching an assertion failure cannot make the case pass; every case must execute an assertion.
-- `string.bytes` (no inputs) → `Bytes`: Encode this string as immutable UTF-8 bytes.
-- `string.length` (no inputs) → `int`: Read the number of UTF-8 bytes. Unicode text is preserved losslessly.
-- `string.startsWith` (`prefix`: `string`) → `bool`: Test an exact prefix.
+## Dependencies
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+It uses [`parse`](../.aug-spec/packages/%40git/url_2d3c37c690c0fa115be1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-parse) from `json`. 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)) 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), [`generateRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.generateRsa), [`importRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.importRsa), [`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)), [`GnuTlsCrypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-GnuTlsCrypto), [`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) (`keys`), [`importJwk`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-importJwk), [`rsaJwk`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-rsaJwk), [`signJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-signJwt), and [`verifyJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-verifyJwt) from `crypto`. It uses [`RsaJwk`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-RsaJwk) (`kid`) and [`Settings`](../common/settings.aug.md#symbol-Settings) (`clientId` and `issuer`).
 
-## Shared language rules
+It uses [`SessionError`](contracts.aug.md#symbol-SessionError) from `contracts`. It uses [`settings`](../common/settings.aug.md#symbol-settings) from `common`. It uses [`IdClaims`](../provider/contracts.aug.md#symbol-IdClaims) (`aud`, `exp`, `iat`, `iss`, `nonce`, and `sub`) and [`Discovery`](../provider/discovery.aug.md#symbol-Discovery) (`authorization_endpoint`, `issuer`, `jwks_uri`, `token_endpoint`, and `userinfo_endpoint`) 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/session.aug

@@ -1,11 +1,12 @@
+// aug-spec: "session.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import SessionClaims and SessionError from contracts
 import settings and SigningKeys and KeyError from common
-import Crypto and verifyJwt and JwtError from august.crypto
-import Clock from august.time
-import ExpiringStore from august.memory
+import Crypto and verifyJwt and JwtError from crypto
+import Clock from time
+import ExpiringStore from memory
 
 /** An app session has its own key, issuer, audience and token type. A live registry entry is required so logout revokes a signed token immediately. */
-authenticate(optional string token, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) returns SessionClaims uses crypto.publicRsa and crypto.decodeBase64url and crypto.verifyRsa and crypto.equal and clock.now and keys.session and sessions.get unless SessionError and KeyError and TimeError:
+authenticate(optional string token, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) :
     match token:
         when null:
             throw SessionError()