@greenpandastudios/aug-cli 0.19.0

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

@@ -0,0 +1,264 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `authorization.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`authorize`](authorization.aug.md#symbol-authorize) handles `GET` `/provider/authorize` returning `HttpResponse<Html>`.
+- [`providerLogin`](authorization.aug.md#symbol-providerLogin) handles `POST` `/provider/login` returning `HttpResponse<Html>`.
+
+<a id="symbol-authorize"></a>
+
+## `authorize`
+
+[source](authorization.aug#L11)
+
+**Inputs**
+
+- `response_type` (`string`) — read from the HTTP query.
+- `client_id` (`string`) — read from the HTTP query.
+- `redirect_uri` (`string`) — read from the HTTP query.
+- `requestedScope` (`string`) — read from the HTTP query named `scope`.
+- `state` (`string`) — read from the HTTP query.
+- `nonce` (`string`) — read from the HTTP query.
+- `code_challenge` (`string`) — read from the HTTP query.
+- `code_challenge_method` (`string`) — read from the HTTP query.
+- `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.
+- `requests` ([`ExpiringStore<AuthorizationRequest>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
+
+Returns: `HttpResponse<Html>`.
+
+Capabilities: [`crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random), [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`requests.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put).
+
+Can fail with `LoginError`, `CryptoError`, `TimeError`, `StoreFull`, `HttpError`. Callers must catch or propagate these errors.
+
+HTTP route: `GET` `/provider/authorize`. 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: [`LoginError`](contracts.aug.md#symbol-LoginError) returns status 400; `CryptoError` returns status 503; `TimeError` returns status 503; [`StoreFull`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-StoreFull) returns status 503.
+
+**What it does**
+
+- Set `config` to call [`settings`](../common/settings.aug.md#symbol-settings).
+- If (((`client_id` does not equal `clientId` of `config`) or (`redirect_uri` does not equal `callback` of `config`)) or (`response_type` does not equal `"code"`)) or (`code_challenge_method` does not equal `"S256"`):
+  - Fail with call [`LoginError`](contracts.aug.md#symbol-LoginError). Transfer control to a matching catch or propagate the failure.
+- If (`requestedScope` does not equal `"openid"`) and (`requestedScope` does not equal `"openid profile"`):
+  - Fail with call [`LoginError`](contracts.aug.md#symbol-LoginError). Transfer control to a matching catch or propagate the failure.
+- If (not (call `isToken` on `state` with `min` = `43`; `max` = `128`) or not (call `isToken` on `nonce` with `min` = `43`; `max` = `128`)) or (call `length` on `code_challenge` does not equal `43`):
+  - Fail with call [`LoginError`](contracts.aug.md#symbol-LoginError). Transfer control to a matching catch or propagate the failure.
+- Try these operations:
+  - If call `length` on call [`Crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url) on `crypto` with `input` = `code_challenge` does not equal `32`:
+    - Fail with call [`LoginError`](contracts.aug.md#symbol-LoginError). Transfer control to a matching catch or propagate the failure.
+- If they fail with `CryptoError`, name the failure `error` and recover:
+  - Fail with call [`LoginError`](contracts.aug.md#symbol-LoginError). Transfer control to a matching catch or propagate the failure.
+- Set `requestId` 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 `browser` to call `base64url` on call [`Crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random) on `crypto` with `size` = `32`.
+- Set `csrf` 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 `now` to call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`.
+- Set `request` to call [`AuthorizationRequest`](contracts.aug.md#symbol-AuthorizationRequest) with `clientId` = `client_id`; `redirectUri` = `redirect_uri`; `state` = `state`; `nonce` = `nonce`; `challenge` = `code_challenge`; `browser` = `browser`; `csrf` = `csrf`; `expires` = (`now` plus `300`).
+- Call [`ExpiringStore.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put) on `requests` with `key` = `requestId`; `value` = `request`; `expires` = `expires` of `request`; `now` = `now`.
+- Set `headers` to call [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders); `name` = `"aug_authorize"`; `value` = `browser`; `path` = `"/provider"`; `maxAge` = `300`; `secure` = `secureCookies` of `config`.
+- Return call `HttpResponse` with `body` = call [`ProviderLogin`](views.aug.md#symbol-ProviderLogin) with `requestId` = `requestId`; `csrf` = `csrf`; `message` = `"Authorize the registered August login app."`; `submit` = a deferred HTTP form action for [`providerLogin`](authorization.aug.md#symbol-providerLogin); inputs: `1` from the checked form input supplied when the HTTP form is submitted; capture supplied values when rendering, and read form inputs when submitted; send the form to that endpoint with its declared HTTP method; `headers` = `headers`.
+
+**Author documentation**
+
+Validate the registered client before offering a login form. A malformed redirect is never followed.
+
+<a id="symbol-providerLogin"></a>
+
+## `providerLogin`
+
+[source](authorization.aug#L34)
+
+**Inputs**
+
+- `form` ([`LoginForm`](contracts.aug.md#symbol-LoginForm)) — read from the HTTP form.
+- `browser` (`optional string`) — read from the HTTP cookie named `aug_authorize`; absent value becomes null.
+- `origin` (`optional string`) — read from the HTTP header named `origin`; 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.
+- `requests` ([`ExpiringStore<AuthorizationRequest>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
+- `codes` ([`ExpiringStore<AuthorizationCode>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
+
+Returns: `HttpResponse<Html>`.
+
+Capabilities: [`crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal), [`crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random), [`crypto.passwordHash`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.passwordHash), [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`requests.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take), [`codes.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put).
+
+Can fail with `CryptoError`, `TimeError`, `StoreFull`, `HttpError`. Callers must catch or propagate these errors.
+
+HTTP route: `POST` `/provider/login`. 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:
+  - If `origin` does not equal `baseUrl` of `config`:
+    - Return call `HttpResponse` with `body` = call [`ProviderFailure`](views.aug.md#symbol-ProviderFailure) with `message` = `"The sign-in form must come from this app."`; `status` = `403`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
+  - Select the matching case for call [`ExpiringStore.take`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take) on `requests` with `key` = `request_id` of `form`; `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:
+      - Return call `HttpResponse` with `body` = call [`ProviderFailure`](views.aug.md#symbol-ProviderFailure) with `message` = `"The sign-in request expired or was already used."`; `status` = `400`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
+    - A present, non-null value, named `request`:
+      - Select the matching case for `browser`:
+        - A null value, including omitted optional input:
+          - Return call `HttpResponse` with `body` = call [`ProviderFailure`](views.aug.md#symbol-ProviderFailure) with `message` = `"The browser binding is missing."`; `status` = `403`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
+        - A present, non-null value, named `secret`:
+          - 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 `secret`; `right` = call `bytes` on `browser` of `request`) 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 `csrf` of `form`; `right` = call `bytes` on `csrf` of `request`):
+            - Return call `HttpResponse` with `body` = call [`ProviderFailure`](views.aug.md#symbol-ProviderFailure) with `message` = `"The sign-in form could not be verified."`; `status` = `403`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
+      - If not (call [`verifyCredentials`](credentials.aug.md#symbol-verifyCredentials) with `username` = `username` of `form`; `password` = `password` of `form`; inject `crypto` from `crypto`):
+        - Return call `HttpResponse` with `body` = call [`ProviderFailure`](views.aug.md#symbol-ProviderFailure) with `message` = `"The username or password was not accepted."`; `status` = `401`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
+      - Set `now` to call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`.
+      - Set `code` 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 `grant` to call [`AuthorizationCode`](contracts.aug.md#symbol-AuthorizationCode) with `clientId` = `clientId` of `request`; `redirectUri` = `redirectUri` of `request`; `challenge` = `challenge` of `request`; `nonce` = `nonce` of `request`; `subject` = `"demo-ada"`; `name` = `"Ada"`; `expires` = (`now` plus `60`).
+      - Call [`ExpiringStore.put`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put) on `codes` with `key` = `code`; `value` = `grant`; `expires` = `expires` of `grant`; `now` = `now`.
+      - Build `location` by joining these text parts without separators, in order:
+        1. `redirectUri` of `request`
+        2. `"?code="`
+        3. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `code`
+        4. `"&state="`
+        5. call [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) with `input` = `state` of `request`
+      - Set `headers` to call [`withCookie`](../common/headers.aug.md#symbol-withCookie) with `headers` = call `with` on call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) with `name` = `"location"`; `value` = `location`; `name` = `"aug_authorize"`; `value` = `""`; `path` = `"/provider"`; `maxAge` = `0`; `secure` = `secureCookies` of `config`.
+      - Return call `HttpResponse` with `body` = the HTML element `p` containing `Returning to the application.` (rendered on the server with embedded text escaped); `status` = `303`; `headers` = `headers`.
+- If they fail with `HttpError`, name the failure `error` and recover:
+  - Return call `HttpResponse` with `body` = call [`ProviderFailure`](views.aug.md#symbol-ProviderFailure) with `message` = `"The submitted form is invalid."`; `status` = `400`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
+
+**Author documentation**
+
+The browser binding and CSRF token are checked before credentials. Each form request is consumed once.
+
+## 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.passwordHash`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.passwordHash) (`password`: `Bytes`, `salt`: `Bytes`, `iterations`: `int`) → `Bytes`; can fail with `CryptoError`.
+- [`Crypto.random`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random) (`size`: `int`) → `Bytes`; can fail with `CryptoError`.
+
+### [`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`.
+
+### [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode)
+
+Function from `august.web`.
+
+- [`urlEncode`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-urlEncode) (`input`: `string`) → `string`; can fail with `HttpError`.
+
+### [`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`.
+
+### [`Settings`](../common/settings.aug.md#symbol-Settings)
+
+Record.
+
+- Read `baseUrl` (`string`).
+- Read `callback` (`string`).
+- Read `clientId` (`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).
+
+### [`AuthorizationCode`](contracts.aug.md#symbol-AuthorizationCode)
+
+Record from `contracts`.
+
+- Construct with `clientId`: `string`, `redirectUri`: `string`, `challenge`: `string`, `nonce`: `string`, `subject`: `string`, `name`: `string`, `expires`: `int` → [`AuthorizationCode`](contracts.aug.md#symbol-AuthorizationCode).
+- Read `expires` (`int`).
+
+### [`AuthorizationRequest`](contracts.aug.md#symbol-AuthorizationRequest)
+
+Record from `contracts`.
+
+- Construct with `clientId`: `string`, `redirectUri`: `string`, `state`: `string`, `nonce`: `string`, `challenge`: `string`, `browser`: `string`, `csrf`: `string`, `expires`: `int` → [`AuthorizationRequest`](contracts.aug.md#symbol-AuthorizationRequest).
+- Read `browser` (`string`).
+- Read `challenge` (`string`).
+- Read `clientId` (`string`).
+- Read `csrf` (`string`).
+- Read `expires` (`int`).
+- Read `nonce` (`string`).
+- Read `redirectUri` (`string`).
+- Read `state` (`string`).
+
+### [`LoginError`](contracts.aug.md#symbol-LoginError)
+
+Class from `contracts`.
+
+- Construct with no caller inputs → [`LoginError`](contracts.aug.md#symbol-LoginError).
+
+### [`LoginForm`](contracts.aug.md#symbol-LoginForm)
+
+Record from `contracts`.
+
+- Read `csrf` (`string`).
+- Read `password` (`string`).
+- Read `request_id` (`string`).
+- Read `username` (`string`).
+
+### [`verifyCredentials`](credentials.aug.md#symbol-verifyCredentials)
+
+Function from `credentials`.
+
+- [`verifyCredentials`](credentials.aug.md#symbol-verifyCredentials) (`username`: `string`, `password`: `string`) → `bool`; inject `crypto`: [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto); uses [`crypto.passwordHash`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.passwordHash), [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal); can fail with `CryptoError`.
+
+### [`ProviderFailure`](views.aug.md#symbol-ProviderFailure)
+
+Function from `views`.
+
+- [`ProviderFailure`](views.aug.md#symbol-ProviderFailure) (`message`: `string`) → `Html`.
+
+### [`ProviderLogin`](views.aug.md#symbol-ProviderLogin)
+
+Function from `views`.
+
+- [`ProviderLogin`](views.aug.md#symbol-ProviderLogin) (`requestId`: `string`, `csrf`: `string`, `message`: `string`, `submit`: `HttpAction`) → `Html`.
+
+## Built-in operations used by this file
+
+- `Bytes.base64url` (no inputs) → `string`: Encode immutable bytes as unpadded RFC 4648 URL-safe base64.
+- `Bytes.length` (no inputs) → `int`: Read the number of elements.
+- `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.
+- `string.isToken` (`min`: `int`, `max`: `int`) → `bool`: Require an ASCII RFC 3986 unreserved token with a bounded length.
+- `string.length` (no inputs) → `int`: Read the number of UTF-8 bytes. Unicode text is preserved losslessly.
+
+[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/contracts.aug

@@ -0,0 +1,15 @@
+/** A provider request is bound to a browser cookie, a form CSRF token, and a registered client. */
+record AuthorizationRequest(string clientId, string redirectUri, string state, string nonce, string challenge, string browser, string csrf, int expires)
+/** Codes are short-lived, single-use and bound to a redirect URI and S256 challenge. */
+record AuthorizationCode(string clientId, string redirectUri, string challenge, string nonce, string subject, string name, int expires)
+record IdClaims(string iss, string sub, string aud, int exp, int iat, string nonce, string name)
+record AccessGrant(string subject, string name, int expires)
+record TokenResponse(string token_type, string access_token, string id_token, int expires_in, string scope)
+record OAuthError(string error, string error_description)
+record TokenForm(string grant_type, string code, string redirect_uri, string client_id, string code_verifier)
+record LoginForm(string request_id, string csrf, string username, string password)
+record UserInfo(string sub, string name)
+LoginError() implements Error:
+    pass
+CodeError() implements Error:
+    pass

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

@@ -0,0 +1,193 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`AuthorizationRequest`](contracts.aug.md#symbol-AuthorizationRequest) is an immutable record.
+- [`AuthorizationCode`](contracts.aug.md#symbol-AuthorizationCode) is an immutable record.
+- [`IdClaims`](contracts.aug.md#symbol-IdClaims) is an immutable record.
+- [`AccessGrant`](contracts.aug.md#symbol-AccessGrant) is an immutable record.
+- [`TokenResponse`](contracts.aug.md#symbol-TokenResponse) is an immutable record.
+- [`OAuthError`](contracts.aug.md#symbol-OAuthError) is an immutable record.
+- [`TokenForm`](contracts.aug.md#symbol-TokenForm) is an immutable record.
+- [`LoginForm`](contracts.aug.md#symbol-LoginForm) is an immutable record.
+- [`UserInfo`](contracts.aug.md#symbol-UserInfo) is an immutable record.
+- [`LoginError`](contracts.aug.md#symbol-LoginError) is a class implementing `Error`.
+- [`CodeError`](contracts.aug.md#symbol-CodeError) is a class implementing `Error`.
+
+<a id="symbol-AuthorizationRequest"></a>
+
+## `AuthorizationRequest`
+
+[source](contracts.aug#L2)
+
+Immutable record.
+
+**Author documentation**
+
+A provider request is bound to a browser cookie, a form CSRF token, and a registered client.
+
+**Inputs**
+
+- `clientId` (`string`) — required labeled input — stored as `clientId` and read-only after initialization.
+- `redirectUri` (`string`) — required labeled input — stored as `redirectUri` and read-only after initialization.
+- `state` (`string`) — required labeled input — stored as `state` and read-only after initialization.
+- `nonce` (`string`) — required labeled input — stored as `nonce` and read-only after initialization.
+- `challenge` (`string`) — required labeled input — stored as `challenge` and read-only after initialization.
+- `browser` (`string`) — required labeled input — stored as `browser` and read-only after initialization.
+- `csrf` (`string`) — required labeled input — stored as `csrf` and read-only after initialization.
+- `expires` (`int`) — required labeled input — stored as `expires` and read-only after initialization.
+
+<a id="symbol-AuthorizationCode"></a>
+
+## `AuthorizationCode`
+
+[source](contracts.aug#L4)
+
+Immutable record.
+
+**Author documentation**
+
+Codes are short-lived, single-use and bound to a redirect URI and S256 challenge.
+
+**Inputs**
+
+- `clientId` (`string`) — required labeled input — stored as `clientId` and read-only after initialization.
+- `redirectUri` (`string`) — required labeled input — stored as `redirectUri` and read-only after initialization.
+- `challenge` (`string`) — required labeled input — stored as `challenge` and read-only after initialization.
+- `nonce` (`string`) — required labeled input — stored as `nonce` and read-only after initialization.
+- `subject` (`string`) — required labeled input — stored as `subject` and read-only after initialization.
+- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
+- `expires` (`int`) — required labeled input — stored as `expires` and read-only after initialization.
+
+<a id="symbol-IdClaims"></a>
+
+## `IdClaims`
+
+[source](contracts.aug#L5)
+
+Immutable record.
+
+**Inputs**
+
+- `iss` (`string`) — required labeled input — stored as `iss` and read-only after initialization.
+- `sub` (`string`) — required labeled input — stored as `sub` and read-only after initialization.
+- `aud` (`string`) — required labeled input — stored as `aud` and read-only after initialization.
+- `exp` (`int`) — required labeled input — stored as `exp` and read-only after initialization.
+- `iat` (`int`) — required labeled input — stored as `iat` and read-only after initialization.
+- `nonce` (`string`) — required labeled input — stored as `nonce` and read-only after initialization.
+- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
+
+<a id="symbol-AccessGrant"></a>
+
+## `AccessGrant`
+
+[source](contracts.aug#L6)
+
+Immutable record.
+
+**Inputs**
+
+- `subject` (`string`) — required labeled input — stored as `subject` and read-only after initialization.
+- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
+- `expires` (`int`) — required labeled input — stored as `expires` and read-only after initialization.
+
+<a id="symbol-TokenResponse"></a>
+
+## `TokenResponse`
+
+[source](contracts.aug#L7)
+
+Immutable record.
+
+**Inputs**
+
+- `token_type` (`string`) — required labeled input — stored as `token_type` and read-only after initialization.
+- `access_token` (`string`) — required labeled input — stored as `access_token` and read-only after initialization.
+- `id_token` (`string`) — required labeled input — stored as `id_token` and read-only after initialization.
+- `expires_in` (`int`) — required labeled input — stored as `expires_in` and read-only after initialization.
+- `scope` (`string`) — required labeled input — stored as `scope` and read-only after initialization.
+
+<a id="symbol-OAuthError"></a>
+
+## `OAuthError`
+
+[source](contracts.aug#L8)
+
+Immutable record.
+
+**Inputs**
+
+- `error` (`string`) — required labeled input — stored as `error` and read-only after initialization.
+- `error_description` (`string`) — required labeled input — stored as `error_description` and read-only after initialization.
+
+<a id="symbol-TokenForm"></a>
+
+## `TokenForm`
+
+[source](contracts.aug#L9)
+
+Immutable record.
+
+**Inputs**
+
+- `grant_type` (`string`) — required labeled input — stored as `grant_type` and read-only after initialization.
+- `code` (`string`) — required labeled input — stored as `code` and read-only after initialization.
+- `redirect_uri` (`string`) — required labeled input — stored as `redirect_uri` and read-only after initialization.
+- `client_id` (`string`) — required labeled input — stored as `client_id` and read-only after initialization.
+- `code_verifier` (`string`) — required labeled input — stored as `code_verifier` and read-only after initialization.
+
+<a id="symbol-LoginForm"></a>
+
+## `LoginForm`
+
+[source](contracts.aug#L10)
+
+Immutable record.
+
+**Inputs**
+
+- `request_id` (`string`) — required labeled input — stored as `request_id` and read-only after initialization.
+- `csrf` (`string`) — required labeled input — stored as `csrf` and read-only after initialization.
+- `username` (`string`) — required labeled input — stored as `username` and read-only after initialization.
+- `password` (`string`) — required labeled input — stored as `password` and read-only after initialization.
+
+<a id="symbol-UserInfo"></a>
+
+## `UserInfo`
+
+[source](contracts.aug#L11)
+
+Immutable record.
+
+**Inputs**
+
+- `sub` (`string`) — required labeled input — stored as `sub` and read-only after initialization.
+- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
+
+<a id="symbol-LoginError"></a>
+
+## `LoginError`
+
+[source](contracts.aug#L12)
+
+Behavioral class.
+
+Satisfies `Error`.
+
+<a id="symbol-CodeError"></a>
+
+## `CodeError`
+
+[source](contracts.aug#L14)
+
+Behavioral class.
+
+Satisfies `Error`.
+
+## 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/credentials.aug

@@ -0,0 +1,10 @@
+import Crypto from august.crypto
+/** One development account with a PBKDF2-HMAC-SHA256 verifier. Production account storage is deliberately a separate capability. */
+verifyCredentials(string username, string password, resolve Crypto crypto) returns bool uses crypto.passwordHash and crypto.decodeBase64url and crypto.equal unless CryptoError:
+    if username.length() > 64 or password.length() > 256:
+        return false
+    actual = crypto.passwordHash(password=password.bytes(), salt="August demo salt v1".bytes(), iterations=600000)
+    expected = crypto.decodeBase64url(input="s70USYF6WohPz2f7VLA9haS_ZgEtenviSf_HG0o7B_A")
+    userMatches = crypto.equal(left=username.bytes(), right="ada".bytes())
+    passwordMatches = crypto.equal(left=actual, right=expected)
+    return userMatches and passwordMatches

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

@@ -0,0 +1,64 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `credentials.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`verifyCredentials`](credentials.aug.md#symbol-verifyCredentials) is a function returning `bool`.
+
+<a id="symbol-verifyCredentials"></a>
+
+## `verifyCredentials`
+
+[source](credentials.aug#L3)
+
+**Inputs**
+
+- `username` (`string`) — required labeled input.
+- `password` (`string`) — required labeled input.
+- `crypto` ([`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)) — injected; callers omit it.
+
+Returns: `bool`.
+
+Capabilities: [`crypto.passwordHash`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.passwordHash), [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal).
+
+Can fail with `CryptoError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- If (call `length` on `username` is greater than `64`) or (call `length` on `password` is greater than `256`):
+  - Return `false`.
+- Set `actual` to call [`Crypto.passwordHash`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.passwordHash) on `crypto` with `password` = call `bytes` on `password`; `salt` = call `bytes` on `"August demo salt v1"`; `iterations` = `600000`.
+- Set `expected` to call [`Crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url) on `crypto` with `input` = `"s70USYF6WohPz2f7VLA9haS_ZgEtenviSf_HG0o7B_A"`.
+- Set `userMatches` to call [`Crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal) on `crypto` with `left` = call `bytes` on `username`; `right` = call `bytes` on `"ada"`.
+- Set `passwordMatches` to call [`Crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal) on `crypto` with `left` = `actual`; `right` = `expected`.
+- Return `userMatches` and `passwordMatches`.
+
+**Author documentation**
+
+One development account with a PBKDF2-HMAC-SHA256 verifier. Production account storage is deliberately a separate capability.
+
+## 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.passwordHash`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.passwordHash) (`password`: `Bytes`, `salt`: `Bytes`, `iterations`: `int`) → `Bytes`; can fail with `CryptoError`.
+
+## Built-in operations used by this file
+
+- `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.
+
+[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/discovery.aug

@@ -0,0 +1,13 @@
+import settings and SigningKeys and KeyError from common
+import Crypto and RsaJwks and rsaJwk from august.crypto
+
+/** Discovery advertises exactly this provider's supported authorization-code profile. */
+record Discovery(string issuer, string authorization_endpoint, string token_endpoint, string userinfo_endpoint, string jwks_uri, List<string> response_types_supported, List<string> grant_types_supported, List<string> subject_types_supported, List<string> id_token_signing_alg_values_supported, List<string> token_endpoint_auth_methods_supported, List<string> scopes_supported, List<string> claims_supported, List<string> code_challenge_methods_supported)
+endpoint GET "/provider/.well-known/openid-configuration" as discovery() returns Discovery:
+    config = settings()
+    return Discovery(issuer=config.issuer, authorization_endpoint=config.issuer + "/authorize", token_endpoint=config.issuer + "/token", userinfo_endpoint=config.issuer + "/userinfo", jwks_uri=config.issuer + "/jwks", response_types_supported=["code"], grant_types_supported=["authorization_code"], subject_types_supported=["public"], id_token_signing_alg_values_supported=["RS256"], token_endpoint_auth_methods_supported=["none"], scopes_supported=["openid", "profile"], claims_supported=["iss", "sub", "aud", "exp", "iat", "nonce", "name"], code_challenge_methods_supported=["S256"])
+
+/** Only the provider's public signing key is published. Session keys never enter this JWKS. */
+endpoint GET "/provider/jwks" as jwks(resolve Crypto crypto, resolve SigningKeys keys) returns RsaJwks uses keys.provider and crypto.publicRsa and crypto.exportRsa unless KeyError and CryptoError:
+    publicKey = crypto.publicRsa(key=keys.provider())
+    return RsaJwks(keys=[rsaJwk(publicKey=publicKey, kid="provider-1")])