@greenpandastudios/aug-cli 0.19.0

package/examples/oidc-login/provider/discovery.aug.md

@@ -0,0 +1,133 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `discovery.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Discovery`](discovery.aug.md#symbol-Discovery) is an immutable record.
+- [`discovery`](discovery.aug.md#symbol-discovery) handles `GET` `/provider/.well-known/openid-configuration` returning `Discovery`.
+- [`jwks`](discovery.aug.md#symbol-jwks) handles `GET` `/provider/jwks` returning `RsaJwks`.
+
+<a id="symbol-Discovery"></a>
+
+## `Discovery`
+
+[source](discovery.aug#L5)
+
+Immutable record.
+
+**Author documentation**
+
+Discovery advertises exactly this provider's supported authorization-code profile.
+
+**Inputs**
+
+- `issuer` (`string`) — required labeled input — stored as `issuer` and read-only after initialization.
+- `authorization_endpoint` (`string`) — required labeled input — stored as `authorization_endpoint` and read-only after initialization.
+- `token_endpoint` (`string`) — required labeled input — stored as `token_endpoint` and read-only after initialization.
+- `userinfo_endpoint` (`string`) — required labeled input — stored as `userinfo_endpoint` and read-only after initialization.
+- `jwks_uri` (`string`) — required labeled input — stored as `jwks_uri` and read-only after initialization.
+- `response_types_supported` (`List<string>`) — required labeled input — stored as `response_types_supported` and read-only after initialization.
+- `grant_types_supported` (`List<string>`) — required labeled input — stored as `grant_types_supported` and read-only after initialization.
+- `subject_types_supported` (`List<string>`) — required labeled input — stored as `subject_types_supported` and read-only after initialization.
+- `id_token_signing_alg_values_supported` (`List<string>`) — required labeled input — stored as `id_token_signing_alg_values_supported` and read-only after initialization.
+- `token_endpoint_auth_methods_supported` (`List<string>`) — required labeled input — stored as `token_endpoint_auth_methods_supported` and read-only after initialization.
+- `scopes_supported` (`List<string>`) — required labeled input — stored as `scopes_supported` and read-only after initialization.
+- `claims_supported` (`List<string>`) — required labeled input — stored as `claims_supported` and read-only after initialization.
+- `code_challenge_methods_supported` (`List<string>`) — required labeled input — stored as `code_challenge_methods_supported` and read-only after initialization.
+
+<a id="symbol-discovery"></a>
+
+## `discovery`
+
+[source](discovery.aug#L6)
+
+Returns: [`Discovery`](discovery.aug.md#symbol-Discovery).
+
+HTTP route: `GET` `/provider/.well-known/openid-configuration`. 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.
+
+**What it does**
+
+- Set `config` to call [`settings`](../common/settings.aug.md#symbol-settings).
+- Return call [`Discovery`](discovery.aug.md#symbol-Discovery) with `issuer` = `issuer` of `config`; `authorization_endpoint` = (`issuer` of `config` plus `"/authorize"`); `token_endpoint` = (`issuer` of `config` plus `"/token"`); `userinfo_endpoint` = (`issuer` of `config` plus `"/userinfo"`); `jwks_uri` = (`issuer` of `config` plus `"/jwks"`); `response_types_supported` = a list containing `"code"`; `grant_types_supported` = a list containing `"authorization_code"`; `subject_types_supported` = a list containing `"public"`; `id_token_signing_alg_values_supported` = a list containing `"RS256"`; `token_endpoint_auth_methods_supported` = a list containing `"none"`; `scopes_supported` = a list containing `"openid"`, `"profile"`; `claims_supported` = a list containing `"iss"`, `"sub"`, `"aud"`, `"exp"`, `"iat"`, `"nonce"`, `"name"`; `code_challenge_methods_supported` = a list containing `"S256"`.
+
+<a id="symbol-jwks"></a>
+
+## `jwks`
+
+[source](discovery.aug#L11)
+
+**Inputs**
+
+- `crypto` ([`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)) — injected; callers omit it.
+- `keys` ([`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)) — injected; callers omit it.
+
+Returns: [`RsaJwks`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwks).
+
+Capabilities: [`keys.provider`](../common/keys.aug.md#symbol-SigningKeys.provider), [`crypto.publicRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.publicRsa), [`crypto.exportRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.exportRsa).
+
+Can fail with `KeyError`, `CryptoError`. Callers must catch or propagate these errors.
+
+HTTP route: `GET` `/provider/jwks`. 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.
+
+**What it does**
+
+- Set `publicKey` to call [`Crypto.publicRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.publicRsa) on `crypto` with `key` = call [`SigningKeys.provider`](../common/keys.aug.md#symbol-SigningKeys.provider) on `keys`.
+- Return 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`.
+
+**Author documentation**
+
+Only the provider's public signing key is published. Session keys never enter this JWKS.
+
+## 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.exportRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.exportRsa) (`publicKey`: `RsaPublicKey`) → `Tuple<Bytes,Bytes>`; 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`.
+
+### [`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).
+
+### [`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`.
+
+### [`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.provider`](../common/keys.aug.md#symbol-SigningKeys.provider) (no caller inputs) → `RsaPrivateKey`; can fail with `KeyError`.
+
+### [`Settings`](../common/settings.aug.md#symbol-Settings)
+
+Record.
+
+- 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).
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/oidc-login/provider/export.aug

@@ -0,0 +1,13 @@
+export AuthorizationRequest from contracts
+export AuthorizationCode from contracts
+export AccessGrant from contracts
+export IdClaims from contracts
+export TokenResponse from contracts
+export UserInfo from contracts
+export Discovery from discovery
+export discovery from discovery
+export jwks from discovery
+export authorize from authorization
+export providerLogin from authorization
+export token from token
+export userinfo from userinfo

package/examples/oidc-login/provider/export.aug.md

@@ -0,0 +1,41 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `export.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- Export `AuthorizationRequest` from this folder.
+- Export `AuthorizationCode` from this folder.
+- Export `AccessGrant` from this folder.
+- Export `IdClaims` from this folder.
+- Export `TokenResponse` from this folder.
+- Export `UserInfo` from this folder.
+- Export `Discovery` from this folder.
+- Export `discovery` from this folder.
+- Export `jwks` from this folder.
+- Export `authorize` from this folder.
+- Export `providerLogin` from this folder.
+- Export `token` from this folder.
+- Export `userinfo` from this folder.
+
+## Folder exports
+
+- Export the declaration `AuthorizationRequest` from [`contracts.aug`](contracts.aug.md#symbol-AuthorizationRequest).
+- Export the declaration `AuthorizationCode` from [`contracts.aug`](contracts.aug.md#symbol-AuthorizationCode).
+- Export the declaration `AccessGrant` from [`contracts.aug`](contracts.aug.md#symbol-AccessGrant).
+- Export the declaration `IdClaims` from [`contracts.aug`](contracts.aug.md#symbol-IdClaims).
+- Export the declaration `TokenResponse` from [`contracts.aug`](contracts.aug.md#symbol-TokenResponse).
+- Export the declaration `UserInfo` from [`contracts.aug`](contracts.aug.md#symbol-UserInfo).
+- Export the declaration `Discovery` from [`discovery.aug`](discovery.aug.md#symbol-Discovery).
+- Export the declaration `discovery` from [`discovery.aug`](discovery.aug.md#symbol-discovery).
+- Export the declaration `jwks` from [`discovery.aug`](discovery.aug.md#symbol-jwks).
+- Export the declaration `authorize` from [`authorization.aug`](authorization.aug.md#symbol-authorize).
+- Export the declaration `providerLogin` from [`authorization.aug`](authorization.aug.md#symbol-providerLogin).
+- Export the declaration `token` from [`token.aug`](token.aug.md#symbol-token).
+- Export the declaration `userinfo` from [`userinfo.aug`](userinfo.aug.md#symbol-userinfo).
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/oidc-login/provider/token.aug

@@ -0,0 +1,37 @@
+import AuthorizationCode and AccessGrant and TokenForm and TokenResponse and OAuthError and IdClaims from contracts
+import settings and SigningKeys and KeyError and securityHeaders from common
+import Crypto and signJwt and JwtError from august.crypto
+import Clock from august.time
+import ExpiringStore and StoreFull from august.memory
+
+_oauthError(string code, string description) returns HttpResponse<Json> unless HttpError:
+    return HttpResponse(body=Json(value=OAuthError(error=code, error_description=description)), status=400, headers=securityHeaders())
+
+/** A real OAuth token endpoint. Exact client/redirect binding, S256 PKCE, expiry and one-use codes are enforced. Errors use OAuth JSON. */
+endpoint POST "/provider/token" as token(HttpRequest http from request, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<AuthorizationCode> codes, resolve ExpiringStore<AccessGrant> access) returns HttpResponse<Json> uses crypto.sha256 and crypto.equal and crypto.random and crypto.signRsa and clock.now and keys.provider and codes.take and access.put unless CryptoError with status 503 and TimeError with status 503 and KeyError and JwtError and StoreFull with status 503 and HttpError:
+    config = settings()
+    try:
+        form = http.form<TokenForm>()
+        if form.grant_type != "authorization_code":
+            return _oauthError(code="unsupported_grant_type", description="Only authorization_code is supported.")
+        if form.client_id != config.clientId:
+            return _oauthError(code="invalid_client", description="The registered client is required.")
+        if (not form.code.isToken(min=43, max=43)) or (not form.code_verifier.isToken(min=43, max=128)):
+            return _oauthError(code="invalid_grant", description="The authorization grant is invalid.")
+        now = clock.now()
+        match codes.take(key=form.code, now=now):
+            when null:
+                return _oauthError(code="invalid_grant", description="The authorization grant is invalid.")
+            when some grant:
+                challenge = crypto.sha256(input=form.code_verifier.bytes()).base64url()
+                if grant.clientId != form.client_id or grant.redirectUri != form.redirect_uri or (not crypto.equal(left=challenge.bytes(), right=grant.challenge.bytes())):
+                    return _oauthError(code="invalid_grant", description="The authorization grant is invalid.")
+                claims = IdClaims(iss=config.issuer, sub=grant.subject, aud=grant.clientId, exp=now + 300, iat=now, nonce=grant.nonce, name=grant.name)
+                idToken = signJwt(key=keys.provider(), claims=Json(value=claims), kid="provider-1", tokenType="JWT")
+                accessToken = crypto.random(size=32).base64url()
+                value = AccessGrant(subject=grant.subject, name=grant.name, expires=now + 300)
+                access.put(key=accessToken, value=value, expires=value.expires, now=now)
+                body = TokenResponse(token_type="Bearer", access_token=accessToken, id_token=idToken, expires_in=300, scope="openid profile")
+                return HttpResponse(body=Json(value=body), headers=securityHeaders())
+    catch HttpError error:
+        return _oauthError(code="invalid_request", description="Submit the required URL-encoded token fields once each.")

package/examples/oidc-login/provider/token.aug.md

@@ -0,0 +1,223 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `token.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`_oauthError`](token.aug.md#symbol-_oauthError) is a function returning `HttpResponse<Json>`.
+- [`token`](token.aug.md#symbol-token) handles `POST` `/provider/token` returning `HttpResponse<Json>`.
+
+<a id="symbol-token"></a>
+
+## `token`
+
+[source](token.aug#L11)
+
+**Inputs**
+
+- `http` (`HttpRequest`) — read from the HTTP request.
+- `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.
+- `codes` ([`ExpiringStore<AuthorizationCode>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
+- `access` ([`ExpiringStore<AccessGrant>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
+
+Returns: `HttpResponse<Json>`.
+
+Capabilities: [`crypto.sha256`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.sha256), [`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), [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`keys.provider`](../common/keys.aug.md#symbol-SigningKeys.provider), [`codes.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take), [`access.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put).
+
+Can fail with `CryptoError`, `TimeError`, `KeyError`, `JwtError`, `StoreFull`, `HttpError`. Callers must catch or propagate these errors.
+
+HTTP route: `POST` `/provider/token`. 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: `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).
+- Try these operations:
+  - Set `form` to call `form` on `http` with type arguments [`TokenForm`](contracts.aug.md#symbol-TokenForm).
+  - If `grant_type` of `form` does not equal `"authorization_code"`:
+    - Return call [`_oauthError`](token.aug.md#symbol-_oauthError) with `code` = `"unsupported_grant_type"`; `description` = `"Only authorization_code is supported."`.
+  - If `client_id` of `form` does not equal `clientId` of `config`:
+    - Return call [`_oauthError`](token.aug.md#symbol-_oauthError) with `code` = `"invalid_client"`; `description` = `"The registered client is required."`.
+  - If not (call `isToken` on `code` of `form` with `min` = `43`; `max` = `43`) or not (call `isToken` on `code_verifier` of `form` with `min` = `43`; `max` = `128`):
+    - Return call [`_oauthError`](token.aug.md#symbol-_oauthError) with `code` = `"invalid_grant"`; `description` = `"The authorization grant is invalid."`.
+  - Set `now` to call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`.
+  - Select the matching case for call [`ExpiringStore.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take) on `codes` with `key` = `code` of `form`; `now` = `now`:
+    - A null value, including omitted optional input:
+      - Return call [`_oauthError`](token.aug.md#symbol-_oauthError) with `code` = `"invalid_grant"`; `description` = `"The authorization grant is invalid."`.
+    - A present, non-null value, named `grant`:
+      - 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 `code_verifier` of `form`.
+      - If ((`clientId` of `grant` does not equal `client_id` of `form`) or (`redirectUri` of `grant` does not equal `redirect_uri` of `form`)) or not (call [`Crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal) on `crypto` with `left` = call `bytes` on `challenge`; `right` = call `bytes` on `challenge` of `grant`):
+        - Return call [`_oauthError`](token.aug.md#symbol-_oauthError) with `code` = `"invalid_grant"`; `description` = `"The authorization grant is invalid."`.
+      - Set `claims` to call [`IdClaims`](contracts.aug.md#symbol-IdClaims) with `iss` = `issuer` of `config`; `sub` = `subject` of `grant`; `aud` = `clientId` of `grant`; `exp` = (`now` plus `300`); `iat` = `now`; `nonce` = `nonce` of `grant`; `name` = `name` of `grant`.
+      - Set `idToken` to call [`signJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-signJwt) with `key` = call [`SigningKeys.provider`](../common/keys.aug.md#symbol-SigningKeys.provider) on `keys`; `claims` = call `Json` with `value` = `claims`; `kid` = `"provider-1"`; `tokenType` = `"JWT"`; inject `crypto` from `crypto`.
+      - Set `accessToken` 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 `value` to call [`AccessGrant`](contracts.aug.md#symbol-AccessGrant) with `subject` = `subject` of `grant`; `name` = `name` of `grant`; `expires` = (`now` plus `300`).
+      - Call [`ExpiringStore.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put) on `access` with `key` = `accessToken`; `value` = `value`; `expires` = `expires` of `value`; `now` = `now`.
+      - Set `body` to call [`TokenResponse`](contracts.aug.md#symbol-TokenResponse) with `token_type` = `"Bearer"`; `access_token` = `accessToken`; `id_token` = `idToken`; `expires_in` = `300`; `scope` = `"openid profile"`.
+      - Return call `HttpResponse` with `body` = call `Json` with `value` = `body`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
+- If they fail with `HttpError`, name the failure `error` and recover:
+  - Return call [`_oauthError`](token.aug.md#symbol-_oauthError) with `code` = `"invalid_request"`; `description` = `"Submit the required URL-encoded token fields once each."`.
+
+**Author documentation**
+
+A real OAuth token endpoint. Exact client/redirect binding, S256 PKCE, expiry and one-use codes are enforced. Errors use OAuth JSON.
+
+<a id="symbol-_oauthError"></a>
+
+## `_oauthError`
+
+[source](token.aug#L7)
+
+Private to its defining scope.
+
+**Inputs**
+
+- `code` (`string`) — required labeled input.
+- `description` (`string`) — required labeled input.
+
+Returns: `HttpResponse<Json>`.
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Return call `HttpResponse` with `body` = call `Json` with `value` = call [`OAuthError`](contracts.aug.md#symbol-OAuthError) with `error` = `code`; `error_description` = `description`; `status` = `400`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
+
+## 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.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal) (`left`: `Bytes`, `right`: `Bytes`) → `bool`.
+- [`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`.
+
+### [`JwtError`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-JwtError)
+
+Class 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`.
+
+### [`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`.
+
+### [`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.provider`](../common/keys.aug.md#symbol-SigningKeys.provider) (no caller inputs) → `RsaPrivateKey`; can fail with `KeyError`.
+
+### [`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).
+
+### [`AccessGrant`](contracts.aug.md#symbol-AccessGrant)
+
+Record from `contracts`.
+
+- Construct with `subject`: `string`, `name`: `string`, `expires`: `int` → [`AccessGrant`](contracts.aug.md#symbol-AccessGrant).
+- Read `expires` (`int`).
+
+### [`AuthorizationCode`](contracts.aug.md#symbol-AuthorizationCode)
+
+Record from `contracts`.
+
+- Read `challenge` (`string`).
+- Read `clientId` (`string`).
+- Read `name` (`string`).
+- Read `nonce` (`string`).
+- Read `redirectUri` (`string`).
+- Read `subject` (`string`).
+
+### [`IdClaims`](contracts.aug.md#symbol-IdClaims)
+
+Record from `contracts`.
+
+- Construct with `iss`: `string`, `sub`: `string`, `aud`: `string`, `exp`: `int`, `iat`: `int`, `nonce`: `string`, `name`: `string` → [`IdClaims`](contracts.aug.md#symbol-IdClaims).
+
+### [`OAuthError`](contracts.aug.md#symbol-OAuthError)
+
+Record from `contracts`.
+
+- Construct with `error`: `string`, `error_description`: `string` → [`OAuthError`](contracts.aug.md#symbol-OAuthError).
+
+### [`TokenForm`](contracts.aug.md#symbol-TokenForm)
+
+Record from `contracts`.
+
+- Read `client_id` (`string`).
+- Read `code` (`string`).
+- Read `code_verifier` (`string`).
+- Read `grant_type` (`string`).
+- Read `redirect_uri` (`string`).
+
+### [`TokenResponse`](contracts.aug.md#symbol-TokenResponse)
+
+Record from `contracts`.
+
+- Construct with `token_type`: `string`, `access_token`: `string`, `id_token`: `string`, `expires_in`: `int`, `scope`: `string` → [`TokenResponse`](contracts.aug.md#symbol-TokenResponse).
+
+## Built-in operations used by this file
+
+- `Bytes.base64url` (no inputs) → `string`: Encode immutable bytes as unpadded RFC 4648 URL-safe base64.
+- `HttpRequest.form` (no inputs) → `TokenForm`: Decode a form record inside a handler so protocol-specific error responses can be returned. Can fail with `HttpError`.
+- `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.
+
+[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/provider/userinfo.aug

@@ -0,0 +1,26 @@
+import UserInfo and AccessGrant from contracts
+import securityHeaders from common
+import Clock from august.time
+import ExpiringStore from august.memory
+
+/** The opaque access token is valid only at this provider. Missing, expired and malformed credentials receive the same response. */
+endpoint GET "/provider/userinfo" as userinfo(optional string authorization from header, resolve Clock clock, resolve ExpiringStore<AccessGrant> access) returns HttpResponse<Json> uses clock.now and access.get unless TimeError and HttpError:
+    match authorization:
+        when null:
+            pass
+        when some header:
+            parts = header.split(separator=" ")
+            if parts.length() == 2:
+                try:
+                    if parts.get(index=0) == "Bearer":
+                        token = parts.get(index=1)
+                        if token.isToken(min=43, max=43):
+                            match access.get(key=token, now=clock.now()):
+                                when null:
+                                    pass
+                                when some grant:
+                                    return HttpResponse(body=Json(value=UserInfo(sub=grant.subject, name=grant.name)), headers=securityHeaders())
+                catch IndexError error:
+                    pass
+    headers = securityHeaders().with(name="www-authenticate", value="Bearer error=\"invalid_token\"")
+    return HttpResponse(body=Json(value={"error": "invalid_token"}), status=401, headers=headers)

package/examples/oidc-login/provider/userinfo.aug.md

@@ -0,0 +1,104 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `userinfo.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`userinfo`](userinfo.aug.md#symbol-userinfo) handles `GET` `/provider/userinfo` returning `HttpResponse<Json>`.
+
+<a id="symbol-userinfo"></a>
+
+## `userinfo`
+
+[source](userinfo.aug#L7)
+
+**Inputs**
+
+- `authorization` (`optional string`) — read from the HTTP header; absent value becomes null.
+- `clock` ([`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock)) — injected; callers omit it.
+- `access` ([`ExpiringStore<AccessGrant>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
+
+Returns: `HttpResponse<Json>`.
+
+Capabilities: [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`access.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get).
+
+Can fail with `TimeError`, `HttpError`. Callers must catch or propagate these errors.
+
+HTTP route: `GET` `/provider/userinfo`. 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.
+
+**What it does**
+
+- Select the matching case for `authorization`:
+  - A null value, including omitted optional input:
+    - Continue without another operation.
+  - A present, non-null value, named `header`:
+    - Set `parts` to call `split` on `header` with `separator` = `" "`.
+    - If call `length` on `parts` equals `2`:
+      - Try these operations:
+        - If call `get` on `parts` with `index` = `0` equals `"Bearer"`:
+          - Set `token` to call `get` on `parts` with `index` = `1`.
+          - If call `isToken` on `token` with `min` = `43`; `max` = `43` is true:
+            - Select the matching case for call [`ExpiringStore.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get) on `access` with `key` = `token`; `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:
+                - Continue without another operation.
+              - A present, non-null value, named `grant`:
+                - Return call `HttpResponse` with `body` = call `Json` with `value` = call [`UserInfo`](contracts.aug.md#symbol-UserInfo) with `sub` = `subject` of `grant`; `name` = `name` of `grant`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
+      - If they fail with `IndexError`, name the failure `error` and recover:
+        - Continue without another operation.
+- Set `headers` to call `with` on call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with `name` = `"www-authenticate"`; `value` = `"Bearer error=\"invalid_token\""`.
+- Return call `HttpResponse` with `body` = call `Json` with `value` = a map with `"error"` mapped to `"invalid_token"`; `status` = `401`; `headers` = `headers`.
+
+**Author documentation**
+
+The opaque access token is valid only at this provider. Missing, expired and malformed credentials receive the same response.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`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`.
+
+### [`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`.
+
+### [`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`.
+
+### [`AccessGrant`](contracts.aug.md#symbol-AccessGrant)
+
+Record from `contracts`.
+
+- Read `name` (`string`).
+- Read `subject` (`string`).
+
+### [`UserInfo`](contracts.aug.md#symbol-UserInfo)
+
+Record from `contracts`.
+
+- Construct with `sub`: `string`, `name`: `string` → [`UserInfo`](contracts.aug.md#symbol-UserInfo).
+
+## 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`.
+- `List<string>.get` (`index`: `int`) → `string`: Read a zero-based position. An invalid index raises checked IndexError. Reference results grant reading. Can fail with `IndexError`.
+- `List<string>.length` (no inputs) → `int`: Read the number of elements.
+- `string.isToken` (`min`: `int`, `max`: `int`) → `bool`: Require an ASCII RFC 3986 unreserved token with a bounded length.
+- `string.split` (`separator`: `string`) → `List<string>`: Split at an exact separator, preserving empty parts.
+
+[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/provider/views.aug

@@ -0,0 +1,18 @@
+import Page from common
+/** A server form with a checked HTTP action. The browser submits to the provider endpoint. */
+ProviderLogin(string requestId, string csrf, string message, HttpAction submit) returns Html:
+    return <Page title="Sign in with the August provider">
+        <p>{message}</p>
+        <p style="background:#f3f5f9;padding:12px;border-radius:8px">Demo account: <strong>ada</strong> · password <strong>august-demo</strong></p>
+        <form method="post" action="/provider/login" onSubmit={submit}>
+            <input type="hidden" name="request_id" value={requestId} />
+            <input type="hidden" name="csrf" value={csrf} />
+            <p><label for="username">Username</label><br /><input id="username" name="username" autocomplete="username" value="ada" maxlength="64" required style="padding:10px;width:90%" /></p>
+            <p><label for="password">Password</label><br /><input id="password" type="password" name="password" autocomplete="current-password" maxlength="256" required style="padding:10px;width:90%" /></p>
+            <button type="submit" style="padding:12px 20px;border:0;border-radius:9px;background:#4852d7;color:white;font:inherit">Sign in and return to the app</button>
+        </form>
+        <p style="font-size:14px;color:#677189">The provider and app run in the same executable. Authorization codes still travel through the OpenID Connect protocol.</p>
+    </Page>
+
+ProviderFailure(string message) returns Html:
+    return <Page title="Sign-in could not continue"><p>{message}</p><a href="/login/start">Start a new sign-in</a></Page>