@greenpandastudios/aug-cli 0.19.0

package/examples/oidc-login/common/settings.aug.md

@@ -0,0 +1,47 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `settings.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Settings`](settings.aug.md#symbol-Settings) is an immutable record.
+- [`settings`](settings.aug.md#symbol-settings) is a function returning `Settings`.
+
+<a id="symbol-Settings"></a>
+
+## `Settings`
+
+[source](settings.aug#L2)
+
+Immutable record.
+
+**Author documentation**
+
+Explicit loopback development settings. The provider accepts one registered client and its exact callback URI.
+
+**Inputs**
+
+- `baseUrl` (`string`) — required labeled input — stored as `baseUrl` and read-only after initialization.
+- `issuer` (`string`) — required labeled input — stored as `issuer` and read-only after initialization.
+- `clientId` (`string`) — required labeled input — stored as `clientId` and read-only after initialization.
+- `callback` (`string`) — required labeled input — stored as `callback` and read-only after initialization.
+- `sessionSeconds` (`int`) — required labeled input — stored as `sessionSeconds` and read-only after initialization.
+- `secureCookies` (`bool`) — required labeled input — stored as `secureCookies` and read-only after initialization.
+
+<a id="symbol-settings"></a>
+
+## `settings`
+
+[source](settings.aug#L3)
+
+Returns: [`Settings`](settings.aug.md#symbol-Settings).
+
+**What it does**
+
+- Return call [`Settings`](settings.aug.md#symbol-Settings) with `baseUrl` = `"http://127.0.0.1:8787"`; `issuer` = `"http://127.0.0.1:8787/provider"`; `clientId` = `"august-login-app"`; `callback` = `"http://127.0.0.1:8787/login/callback"`; `sessionSeconds` = `900`; `secureCookies` = `false`.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/oidc-login/common/views.aug

@@ -0,0 +1,16 @@
+/** Small server components keep each page's behavior and dependencies visible. */
+Page(string title, List<Html> children) returns Html:
+    return <html lang="en">
+        <head>
+            <meta charset="utf-8" />
+            <meta name="viewport" content="width=device-width, initial-scale=1" />
+            <title>{title} — August</title>
+        </head>
+        <body style="margin:0;background:#f3f5f9;color:#17233a;font:17px system-ui,sans-serif;line-height:1.6">
+            <main style="max-width:640px;margin:48px auto;padding:28px;background:white;border-radius:20px;box-shadow:0 12px 48px #17233a12">
+                <nav><a href="/" style="color:#4852d7;font-weight:750;text-decoration:none">August · OpenID Connect</a></nav>
+                <h1>{title}</h1>
+                {children}
+            </main>
+        </body>
+    </html>

package/examples/oidc-login/common/views.aug.md

@@ -0,0 +1,34 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `views.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Page`](views.aug.md#symbol-Page) is a function returning `Html`.
+
+<a id="symbol-Page"></a>
+
+## `Page`
+
+[source](views.aug#L2)
+
+**Inputs**
+
+- `title` (`string`) — required labeled input.
+- `children` (`List<Html>`) — required labeled input.
+
+Returns: `Html`.
+
+**What it does**
+
+- Return the HTML element `html` with `lang` = `"en"` containing the HTML element `head` containing the HTML element `meta` with `charset` = `"utf-8"` (rendered on the server with embedded text escaped), the HTML element `meta` with `name` = `"viewport"`, `content` = `"width=device-width, initial-scale=1"` (rendered on the server with embedded text escaped), the HTML element `title` containing `title`, ` — August` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `body` with `style` = `"margin:0;background:#f3f5f9;color:#17233a;font:17px system-ui,sans-serif;line-height:1.6"` containing the HTML element `main` with `style` = `"max-width:640px;margin:48px auto;padding:28px;background:white;border-radius:20px;box-shadow:0 12px 48px #17233a12"` containing the HTML element `nav` containing the HTML element `a` with `href` = `"/"`, `style` = `"color:#4852d7;font-weight:750;text-decoration:none"` containing `August · OpenID Connect` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `h1` containing `title` (rendered on the server with embedded text escaped), `children` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped).
+
+**Author documentation**
+
+Small server components keep each page's behavior and dependencies visible.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

package/examples/oidc-login/main.aug

@@ -0,0 +1,39 @@
+import Crypto and GnuTlsCrypto from august.crypto
+import Clock and SystemClock from august.time
+import HttpClient and WebHttpClient from august.web
+import ExpiringStore and MemoryStore from august.memory
+import LoginTransaction and SessionClaims and home and me and logout and startLogin and loginCallback from client
+import AuthorizationRequest and AuthorizationCode and AccessGrant and discovery and jwks and authorize and providerLogin and token and userinfo from provider
+import SigningKeys and MemorySigningKeys and initializeKeys and KeyError from common
+
+implement Crypto with GnuTlsCrypto
+implement Clock with SystemClock
+implement HttpClient with WebHttpClient
+implement SigningKeys with MemorySigningKeys shared mutable
+implement ExpiringStore<LoginTransaction> with MemoryStore<LoginTransaction> shared mutable
+implement ExpiringStore<AuthorizationRequest> with MemoryStore<AuthorizationRequest> shared mutable
+implement ExpiringStore<AuthorizationCode> with MemoryStore<AuthorizationCode> shared mutable
+implement ExpiringStore<SessionClaims> with MemoryStore<SessionClaims> shared mutable
+implement ExpiringStore<AccessGrant> with MemoryStore<AccessGrant> shared mutable
+
+try:
+    initializeKeys()
+catch CryptoError error:
+    print(value="Cryptographic initialization failed")
+    exit(status=1)
+catch KeyError error:
+    print(value="Signing keys could not be initialized")
+    exit(status=1)
+
+serve   home
+and     me
+and     logout
+and     startLogin
+and     loginCallback
+and     discovery
+and     jwks
+and     authorize
+and     providerLogin
+and     token
+and     userinfo
+on port 8787

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

@@ -0,0 +1,166 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `main.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- Register 9 dependency providers before startup.
+- Run startup operations with checked error recovery.
+- Serve 11 HTTP routes.
+
+## HTTP configuration
+
+Listen on `127.0.0.1`. Limit request bodies to 16384 bytes and buffered responses to 1048576 bytes.
+
+Serve the OpenAPI document at `/openapi.json` and API documentation at `/docs`.
+
+## Dependency providers
+
+Register these providers before startup. Their declaration order does not set initialization order; shared instances initialize in dependency order.
+
+- Provide [`GnuTlsCrypto`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-GnuTlsCrypto) when `Crypto` is requested. Reuse one instance.
+- Provide [`SystemClock`](.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-SystemClock) when `Clock` is requested. Reuse one instance.
+- Provide [`WebHttpClient`](.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-WebHttpClient) when `HttpClient` is requested. Reuse one instance.
+- Provide [`MemorySigningKeys`](common/keys.aug.md#symbol-MemorySigningKeys) when `SigningKeys` is requested. Reuse one instance. Permit explicit shared mutation.
+- Provide [`MemoryStore<LoginTransaction>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-MemoryStore) when `ExpiringStore<LoginTransaction>` is requested. Reuse one instance. Permit explicit shared mutation.
+- Provide [`MemoryStore<AuthorizationRequest>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-MemoryStore) when `ExpiringStore<AuthorizationRequest>` is requested. Reuse one instance. Permit explicit shared mutation.
+- Provide [`MemoryStore<AuthorizationCode>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-MemoryStore) when `ExpiringStore<AuthorizationCode>` is requested. Reuse one instance. Permit explicit shared mutation.
+- Provide [`MemoryStore<SessionClaims>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-MemoryStore) when `ExpiringStore<SessionClaims>` is requested. Reuse one instance. Permit explicit shared mutation.
+- Provide [`MemoryStore<AccessGrant>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-MemoryStore) when `ExpiringStore<AccessGrant>` is requested. Reuse one instance. Permit explicit shared mutation.
+
+## Startup, in source order
+
+- Try these operations:
+  - Call [`initializeKeys`](common/keys.aug.md#symbol-initializeKeys); inject `crypto` from `Crypto`, `keys` from `SigningKeys`.
+- If they fail with `CryptoError`, name the failure `error` and recover:
+  - Call `print` with `value` = `"Cryptographic initialization failed"`.
+  - Call `exit` with `status` = `1`.
+- If they fail with [`KeyError`](common/keys.aug.md#symbol-KeyError), name the failure `error` and recover:
+  - Call `print` with `value` = `"Signing keys could not be initialized"`.
+  - Call `exit` with `status` = `1`.
+- Serve [`home`](client/endpoints.aug.md#symbol-home), [`me`](client/endpoints.aug.md#symbol-me), [`logout`](client/logout.aug.md#symbol-logout), [`startLogin`](client/login.aug.md#symbol-startLogin), [`loginCallback`](client/login.aug.md#symbol-loginCallback), [`discovery`](provider/discovery.aug.md#symbol-discovery), [`jwks`](provider/discovery.aug.md#symbol-jwks), [`authorize`](provider/authorization.aug.md#symbol-authorize), [`providerLogin`](provider/authorization.aug.md#symbol-providerLogin), [`token`](provider/token.aug.md#symbol-token), [`userinfo`](provider/userinfo.aug.md#symbol-userinfo) on port `8787`.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`GnuTlsCrypto`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-GnuTlsCrypto)
+
+Class from `august.crypto`.
+
+Used as a type or provider.
+
+### [`MemoryStore`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-MemoryStore)
+
+Class from `august.memory`.
+
+Used as a type or provider.
+
+### [`SystemClock`](.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-SystemClock)
+
+Class from `august.time`.
+
+Used as a type or provider.
+
+### [`WebHttpClient`](.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-WebHttpClient)
+
+Class from `august.web`.
+
+Used as a type or provider.
+
+### [`home`](client/endpoints.aug.md#symbol-home)
+
+Function from `client`.
+
+- [`home`](client/endpoints.aug.md#symbol-home) (`token`: `optional string` from HTTP cookie `aug_session`) → `HttpResponse<Html>`; 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 `KeyError`, `TimeError`, `HttpError`.
+
+### [`me`](client/endpoints.aug.md#symbol-me)
+
+Function from `client`.
+
+- [`me`](client/endpoints.aug.md#symbol-me) (`token`: `optional string` from HTTP cookie `aug_session`) → `HttpResponse<UserInfo>`; 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`, `HttpError`.
+
+### [`loginCallback`](client/login.aug.md#symbol-loginCallback)
+
+Function from `client`.
+
+- [`loginCallback`](client/login.aug.md#symbol-loginCallback) (`code`: `string` from HTTP query, `state`: `string` from HTTP query, `browser`: `optional string` from HTTP cookie `aug_login`) → `HttpResponse<Html>`; 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), `client`: [`HttpClient`](.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient), `keys`: [`SigningKeys`](common/keys.aug.md#symbol-SigningKeys), `transactions`: [`ExpiringStore<LoginTransaction>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore), `sessions`: [`ExpiringStore<SessionClaims>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore); uses [`crypto.equal`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal), [`crypto.random`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random), [`crypto.signRsa`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.signRsa), [`crypto.decodeBase64url`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`crypto.importRsa`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.importRsa), [`crypto.verifyRsa`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa), [`clock.now`](.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`client.request`](.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request), [`keys.session`](common/keys.aug.md#symbol-SigningKeys.session), [`transactions.take`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take), [`sessions.put`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put); can fail with `SessionError`, `CryptoError`, `TimeError`, `KeyError`, `StoreFull`, `JwtError`, `JsonError`, `HttpError`.
+
+### [`startLogin`](client/login.aug.md#symbol-startLogin)
+
+Function from `client`.
+
+- [`startLogin`](client/login.aug.md#symbol-startLogin) (no caller inputs) → `HttpResponse<Html>`; 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), `client`: [`HttpClient`](.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient), `transactions`: [`ExpiringStore<LoginTransaction>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore); uses [`crypto.random`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.random), [`crypto.sha256`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.sha256), [`clock.now`](.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`client.request`](.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-HttpClient.request), [`transactions.put`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.put); can fail with `SessionError`, `CryptoError`, `TimeError`, `StoreFull`, `HttpError`.
+
+### [`logout`](client/logout.aug.md#symbol-logout)
+
+Function from `client`.
+
+- [`logout`](client/logout.aug.md#symbol-logout) (`input`: [`LogoutForm`](client/contracts.aug.md#symbol-LogoutForm) from HTTP form, `token`: `optional string` from HTTP cookie `aug_session`, `origin`: `optional string` from HTTP header) → `HttpResponse<Html>`; 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), [`sessions.take`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.take); can fail with `SessionError`, `KeyError`, `TimeError`, `CryptoError`, `HttpError`.
+
+### [`KeyError`](common/keys.aug.md#symbol-KeyError)
+
+Class from `common`.
+
+Used as a type or provider.
+
+### [`MemorySigningKeys`](common/keys.aug.md#symbol-MemorySigningKeys)
+
+Class from `common`.
+
+Used as a type or provider.
+
+### [`initializeKeys`](common/keys.aug.md#symbol-initializeKeys)
+
+Function from `common`.
+
+- [`initializeKeys`](common/keys.aug.md#symbol-initializeKeys) (no caller inputs) → `void`; inject `crypto`: [`Crypto`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto), `keys`: [`SigningKeys`](common/keys.aug.md#symbol-SigningKeys); uses [`crypto.generateRsa`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.generateRsa), [`keys.configure`](common/keys.aug.md#symbol-SigningKeys.configure); can fail with `CryptoError`, `KeyError`.
+
+### [`authorize`](provider/authorization.aug.md#symbol-authorize)
+
+Function from `provider`.
+
+- [`authorize`](provider/authorization.aug.md#symbol-authorize) (`response_type`: `string` from HTTP query, `client_id`: `string` from HTTP query, `redirect_uri`: `string` from HTTP query, `requestedScope`: `string` from HTTP query `scope`, `state`: `string` from HTTP query, `nonce`: `string` from HTTP query, `code_challenge`: `string` from HTTP query, `code_challenge_method`: `string` from HTTP query) → `HttpResponse<Html>`; 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), `requests`: [`ExpiringStore<AuthorizationRequest>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore); uses [`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`.
+
+### [`providerLogin`](provider/authorization.aug.md#symbol-providerLogin)
+
+Function from `provider`.
+
+- [`providerLogin`](provider/authorization.aug.md#symbol-providerLogin) (`form`: [`LoginForm`](provider/contracts.aug.md#symbol-LoginForm) from HTTP form, `browser`: `optional string` from HTTP cookie `aug_authorize`, `origin`: `optional string` from HTTP header `origin`) → `HttpResponse<Html>`; 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), `requests`: [`ExpiringStore<AuthorizationRequest>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore), `codes`: [`ExpiringStore<AuthorizationCode>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore); uses [`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`.
+
+### [`discovery`](provider/discovery.aug.md#symbol-discovery)
+
+Function from `provider`.
+
+- [`discovery`](provider/discovery.aug.md#symbol-discovery) (no caller inputs) → [`Discovery`](provider/discovery.aug.md#symbol-Discovery).
+
+### [`jwks`](provider/discovery.aug.md#symbol-jwks)
+
+Function from `provider`.
+
+- [`jwks`](provider/discovery.aug.md#symbol-jwks) (no caller inputs) → [`RsaJwks`](.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-RsaJwks); inject `crypto`: [`Crypto`](.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto), `keys`: [`SigningKeys`](common/keys.aug.md#symbol-SigningKeys); uses [`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`.
+
+### [`token`](provider/token.aug.md#symbol-token)
+
+Function from `provider`.
+
+- [`token`](provider/token.aug.md#symbol-token) (`http`: `HttpRequest` from HTTP request) → `HttpResponse<Json>`; 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), `codes`: [`ExpiringStore<AuthorizationCode>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore), `access`: [`ExpiringStore<AccessGrant>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore); uses [`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`.
+
+### [`userinfo`](provider/userinfo.aug.md#symbol-userinfo)
+
+Function from `provider`.
+
+- [`userinfo`](provider/userinfo.aug.md#symbol-userinfo) (`authorization`: `optional string` from HTTP header) → `HttpResponse<Json>`; inject `clock`: [`Clock`](.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock), `access`: [`ExpiringStore<AccessGrant>`](.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore); uses [`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`.
+
+## Built-in operations used by this file
+
+- `exit` (`status`: `int`) → `void`: Exit from main with a status from 0 to 255 after cancellation and cleanup.
+- `print` (`value`: `any`) → `void`: Composition and test output. Other callables receive Console and declare uses console.write.
+
+[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/main.yaml

@@ -0,0 +1,12 @@
+block_style: indent
+web:
+  host: 127.0.0.1
+  body_limit: 16384
+  response_limit: 1048576
+openapi:
+  enabled: true
+  title: August OpenID Connect demo
+  version: 0.1.0
+  path: /openapi.json
+  docs: /docs
+  output: .aug-build/openapi.json

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

@@ -0,0 +1,59 @@
+import AuthorizationRequest and AuthorizationCode and LoginForm and LoginError from contracts
+import ProviderLogin and ProviderFailure from views
+import verifyCredentials from credentials
+import settings and securityHeaders and withCookie from common
+import Crypto from august.crypto
+import Clock from august.time
+import ExpiringStore and StoreFull from august.memory
+import urlEncode from august.web
+
+/** Validate the registered client before offering a login form. A malformed redirect is never followed. */
+endpoint GET "/provider/authorize" as authorize(string response_type from query, string client_id from query, string redirect_uri from query, string requestedScope from query "scope", string state from query, string nonce from query, string code_challenge from query, string code_challenge_method from query, resolve Crypto crypto, resolve Clock clock, resolve ExpiringStore<AuthorizationRequest> requests) returns HttpResponse<Html> uses crypto.random and crypto.decodeBase64url and clock.now and requests.put unless LoginError with status 400 and CryptoError with status 503 and TimeError with status 503 and StoreFull with status 503 and HttpError:
+    config = settings()
+    if client_id != config.clientId or redirect_uri != config.callback or response_type != "code" or code_challenge_method != "S256":
+        throw LoginError()
+    if requestedScope != "openid" and requestedScope != "openid profile":
+        throw LoginError()
+    if (not state.isToken(min=43, max=128)) or (not nonce.isToken(min=43, max=128)) or code_challenge.length() != 43:
+        throw LoginError()
+    try:
+        if crypto.decodeBase64url(input=code_challenge).length() != 32:
+            throw LoginError()
+    catch CryptoError error:
+        throw LoginError()
+    requestId = crypto.random(size=32).base64url()
+    browser = crypto.random(size=32).base64url()
+    csrf = crypto.random(size=32).base64url()
+    now = clock.now()
+    request = AuthorizationRequest(clientId=client_id, redirectUri=redirect_uri, state=state, nonce=nonce, challenge=code_challenge, browser=browser, csrf=csrf, expires=now + 300)
+    requests.put(key=requestId, value=request, expires=request.expires, now=now)
+    headers = withCookie(headers=securityHeaders(), name="aug_authorize", value=browser, path="/provider", maxAge=300, secure=config.secureCookies)
+    return HttpResponse(body=ProviderLogin(requestId, csrf, message="Authorize the registered August login app.", submit=handle providerLogin(input from form)), headers=headers)
+
+/** The browser binding and CSRF token are checked before credentials. Each form request is consumed once. */
+endpoint POST "/provider/login" as providerLogin(LoginForm form from form, optional string browser from cookie "aug_authorize", optional string origin from header "origin", resolve Crypto crypto, resolve Clock clock, resolve ExpiringStore<AuthorizationRequest> requests, resolve ExpiringStore<AuthorizationCode> codes) returns HttpResponse<Html> uses crypto.equal and crypto.random and crypto.passwordHash and crypto.decodeBase64url and clock.now and requests.take and codes.put unless CryptoError with status 503 and TimeError with status 503 and StoreFull with status 503 and HttpError:
+    config = settings()
+    try:
+        if origin != config.baseUrl:
+            return HttpResponse(body=ProviderFailure(message="The sign-in form must come from this app."), status=403, headers=securityHeaders())
+        match requests.take(key=form.request_id, now=clock.now()):
+            when null:
+                return HttpResponse(body=ProviderFailure(message="The sign-in request expired or was already used."), status=400, headers=securityHeaders())
+            when some request:
+                match browser:
+                    when null:
+                        return HttpResponse(body=ProviderFailure(message="The browser binding is missing."), status=403, headers=securityHeaders())
+                    when some secret:
+                        if (not crypto.equal(left=secret.bytes(), right=request.browser.bytes())) or (not crypto.equal(left=form.csrf.bytes(), right=request.csrf.bytes())):
+                            return HttpResponse(body=ProviderFailure(message="The sign-in form could not be verified."), status=403, headers=securityHeaders())
+                if (not verifyCredentials(username=form.username, password=form.password)):
+                    return HttpResponse(body=ProviderFailure(message="The username or password was not accepted."), status=401, headers=securityHeaders())
+                now = clock.now()
+                code = crypto.random(size=32).base64url()
+                grant = AuthorizationCode(clientId=request.clientId, redirectUri=request.redirectUri, challenge=request.challenge, nonce=request.nonce, subject="demo-ada", name="Ada", expires=now + 60)
+                codes.put(key=code, value=grant, expires=grant.expires, now=now)
+                location = request.redirectUri + "?code=" + urlEncode(input=code) + "&state=" + urlEncode(input=request.state)
+                headers = withCookie(headers=securityHeaders().with(name="location", value=location), name="aug_authorize", value="", path="/provider", maxAge=0, secure=config.secureCookies)
+                return HttpResponse(body=<p>Returning to the application.</p>, status=303, headers=headers)
+    catch HttpError error:
+        return HttpResponse(body=ProviderFailure(message="The submitted form is invalid."), status=400, headers=securityHeaders())