@greenpandastudios/aug-cli 0.19.0

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

@@ -0,0 +1,150 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `logout.aug` specification
+
+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>`.
+
+<a id="symbol-logout"></a>
+
+## `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.
+
+- Read `baseUrl` (`string`).
+- Read `secureCookies` (`bool`).
+
+### [`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).
+
+## Built-in operations used by this file
+
+- `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.
+
+[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

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

@@ -0,0 +1,106 @@
+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
+
+/** Accept only a successful JSON response. Redirects remain explicit and are never followed by the transport. */
+responseJson(HttpResponse<Bytes> response) returns Json unless SessionError:
+    if response.status != 200:
+        throw SessionError()
+    match response.headers.get(name="content-type"):
+        when null:
+            throw SessionError()
+        when some contentType:
+            if (not contentType.startsWith(prefix="application/json")):
+                throw SessionError()
+    try:
+        return parse(input=response.body.text())
+    catch ConversionError error:
+        throw SessionError()
+    catch JsonError error:
+        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:
+    config = settings()
+    json = responseJson(response=client.request(method="GET", url=config.issuer + "/.well-known/openid-configuration"))
+    try:
+        document = json.decode<Discovery>()
+        if document.issuer != config.issuer or document.authorization_endpoint != config.issuer + "/authorize" or document.token_endpoint != config.issuer + "/token" or document.jwks_uri != config.issuer + "/jwks" or document.userinfo_endpoint != config.issuer + "/userinfo":
+            throw SessionError()
+        return document
+    catch JsonError error:
+        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:
+    config = settings()
+    if jwks.keys.length() != 1:
+        throw SessionError()
+    try:
+        jwk = jwks.keys.get(index=0)
+        if jwk.kid != "provider-1":
+            throw SessionError()
+        publicKey = importJwk(jwk)
+        claims = verifyJwt(token, publicKey, kid="provider-1", tokenType="JWT").decode<IdClaims>()
+        if claims.iss != config.issuer or claims.aud != config.clientId or claims.sub.length() == 0 or claims.sub.length() > 255:
+            throw SessionError()
+        if claims.exp <= now or claims.iat < now - 300 or claims.iat > now + 30 or claims.exp <= claims.iat or claims.exp > now + 330:
+            throw SessionError()
+        if (not crypto.equal(left=claims.nonce.bytes(), right=nonce.bytes())):
+            throw SessionError()
+        return claims
+    catch JwtError error:
+        throw SessionError()
+    catch JsonError error:
+        throw SessionError()
+    catch IndexError error:
+        throw SessionError()
+    catch CryptoError error:
+        throw SessionError()
+
+test validateIdentity:
+    when signed_identity_claims:
+        implement Crypto with GnuTlsCrypto
+        resolve Crypto to crypto
+        key = crypto.generateRsa()
+        publicKey = crypto.publicRsa(key)
+        jwks = RsaJwks(keys=[rsaJwk(publicKey, kid="provider-1")])
+        config = settings()
+        now = 1700000000
+        expectedNonce = "nnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnnn"
+
+        it accepts_valid_identity:
+            claims = IdClaims(iss=config.issuer, sub="ada", aud=config.clientId, exp=now+300, iat=now, nonce=expectedNonce, name="Ada")
+            token = signJwt(key, claims=Json(value=claims), kid="provider-1", tokenType="JWT")
+            identity = validateIdentity(token, nonce=expectedNonce, now, jwks)
+            assert(condition=identity.sub == "ada")
+
+        it rejects_signed_invalid_claims for (issuer, audience, subject, issued, expires, nonce) in [
+            ("https://wrong-issuer.invalid", config.clientId, "ada", now, now+300, expectedNonce),
+            (config.issuer, "wrong-audience", "ada", now, now+300, expectedNonce),
+            (config.issuer, config.clientId, "", now, now+300, expectedNonce),
+            (config.issuer, config.clientId, "ada", now-400, now+300, expectedNonce),
+            (config.issuer, config.clientId, "ada", now+100, now+300, expectedNonce),
+            (config.issuer, config.clientId, "ada", now, now, expectedNonce),
+            (config.issuer, config.clientId, "ada", now, now+600, expectedNonce),
+            (config.issuer, config.clientId, "ada", now, now+300, "wrong-nonce")
+        ]:
+            claims = IdClaims(iss=issuer, sub=subject, aud=audience, exp=expires, iat=issued, nonce, name="Ada")
+            token = signJwt(key, claims=Json(value=claims), kid="provider-1", tokenType="JWT")
+            try:
+                validateIdentity(token, nonce=expectedNonce, now, jwks)
+                assert(condition=false)
+            catch SessionError error:
+                assert(condition=true)
+
+        it rejects_token_context for (kid, tokenType) in [("wrong-key", "JWT"), ("provider-1", "august-session+jwt")]:
+            claims = IdClaims(iss=config.issuer, sub="ada", aud=config.clientId, exp=now+300, iat=now, nonce=expectedNonce, name="Ada")
+            token = signJwt(key, claims=Json(value=claims), kid, tokenType)
+            try:
+                validateIdentity(token, nonce=expectedNonce, now, jwks)
+                assert(condition=false)
+            catch SessionError error:
+                assert(condition=true)

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

@@ -0,0 +1,326 @@
+<!-- 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.
+
+<a id="symbol-responseJson"></a>
+
+## `responseJson`
+
+[source](protocol.aug#L9)
+
+**Inputs**
+
+- `response` (`HttpResponse<Bytes>`) — required labeled input.
+
+Returns: `Json`.
+
+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.
+
+<a id="symbol-discover"></a>
+
+## `discover`
+
+[source](protocol.aug#L26)
+
+**Inputs**
+
+- `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.
+
+<a id="symbol-validateIdentity"></a>
+
+## `validateIdentity`
+
+[source](protocol.aug#L38)
+
+**Inputs**
+
+- `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.
+
+Returns: [`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).
+
+Can fail with `SessionError`. Callers must catch or propagate these errors.
+
+**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.
+
+<a id="symbol-test validateIdentity"></a>
+
+## `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.
+
+### Group `signed_identity_claims`
+
+**Setup before each case**
+
+- 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"`.
+
+#### `accepts_valid_identity`
+
+[source](protocol.aug#L75)
+
+- 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"`).
+
+#### `rejects_signed_invalid_claims`
+
+[source](protocol.aug#L81)
+
+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`.
+
+- 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`.
+
+#### `rejects_token_context`
+
+[source](protocol.aug#L99)
+
+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`).
+
+## Built-in operations used by this file
+
+- `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.
+
+[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

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

@@ -0,0 +1,34 @@
+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
+
+/** 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:
+    match token:
+        when null:
+            throw SessionError()
+        when some value:
+            try:
+                publicKey = crypto.publicRsa(key=keys.session())
+                claims = verifyJwt(token=value, publicKey, kid="session-1", tokenType="august-session+jwt").decode<SessionClaims>()
+                config = settings()
+                now = clock.now()
+                if claims.iss != config.baseUrl + "/app" or claims.aud != "august-app" or claims.sub.length() == 0 or claims.exp <= now or claims.iat > now + 30 or claims.iat < now - config.sessionSeconds or claims.exp <= claims.iat or claims.exp > now + config.sessionSeconds + 30:
+                    throw SessionError()
+                if (not claims.jti.isToken(min=43, max=43)) or (not claims.csrf.isToken(min=43, max=43)):
+                    throw SessionError()
+                match sessions.get(key=claims.jti, now=now):
+                    when null:
+                        throw SessionError()
+                    when some saved:
+                        if saved.sub != claims.sub or saved.exp != claims.exp or (not crypto.equal(left=saved.csrf.bytes(), right=claims.csrf.bytes())):
+                            throw SessionError()
+                        return claims
+            catch CryptoError error:
+                throw SessionError()
+            catch JwtError error:
+                throw SessionError()
+            catch JsonError error:
+                throw SessionError()