@greenpandastudios/aug-cli 0.19.0

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

@@ -0,0 +1,155 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `session.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`authenticate`](session.aug.md#symbol-authenticate) is a function returning `SessionClaims`.
+
+<a id="symbol-authenticate"></a>
+
+## `authenticate`
+
+[source](session.aug#L8)
+
+**Inputs**
+
+- `token` (`optional string`) — optional labeled input; omission becomes null.
+- `crypto` ([`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)) — injected; callers omit it.
+- `clock` ([`Clock`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock)) — injected; callers omit it.
+- `keys` ([`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)) — injected; callers omit it.
+- `sessions` ([`ExpiringStore<SessionClaims>`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore)) — injected; callers omit it.
+
+Returns: [`SessionClaims`](contracts.aug.md#symbol-SessionClaims).
+
+Capabilities: [`crypto.publicRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.publicRsa), [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`crypto.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa), [`crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal), [`clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now), [`keys.session`](../common/keys.aug.md#symbol-SigningKeys.session), [`sessions.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get).
+
+Can fail with `SessionError`, `KeyError`, `TimeError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Select the matching case for `token`:
+  - A null value, including omitted optional input:
+    - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+  - A present, non-null value, named `value`:
+    - Try these operations:
+      - 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.session`](../common/keys.aug.md#symbol-SigningKeys.session) on `keys`.
+      - Set `claims` to call `decode` on call [`verifyJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-verifyJwt) with `token` = `value`; `publicKey` = `publicKey`; `kid` = `"session-1"`; `tokenType` = `"august-session+jwt"`; inject `crypto` from `crypto` with type arguments [`SessionClaims`](contracts.aug.md#symbol-SessionClaims).
+      - Set `config` to call [`settings`](../common/settings.aug.md#symbol-settings).
+      - Set `now` to call [`Clock.now`](../.aug-spec/august/0.19.0/time/contracts.aug.md#symbol-Clock.now) on `clock`.
+      - If (((((((`iss` of `claims` does not equal (`baseUrl` of `config` plus `"/app"`)) or (`aud` of `claims` does not equal `"august-app"`)) or (call `length` on `sub` of `claims` equals `0`)) or (`exp` of `claims` is at most `now`)) or (`iat` of `claims` is greater than (`now` plus `30`))) or (`iat` of `claims` is less than (`now` minus `sessionSeconds` of `config`))) or (`exp` of `claims` is at most `iat` of `claims`)) or (`exp` of `claims` is greater than ((`now` plus `sessionSeconds` of `config`) plus `30`)):
+        - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+      - If not (call `isToken` on `jti` of `claims` with `min` = `43`; `max` = `43`) or not (call `isToken` on `csrf` of `claims` with `min` = `43`; `max` = `43`):
+        - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+      - Select the matching case for call [`ExpiringStore.get`](../.aug-spec/august/0.19.0/memory/store.aug.md#symbol-ExpiringStore.get) on `sessions` with `key` = `jti` of `claims`; `now` = `now`:
+        - A null value, including omitted optional input:
+          - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+        - A present, non-null value, named `saved`:
+          - If ((`sub` of `saved` does not equal `sub` of `claims`) or (`exp` of `saved` does not equal `exp` of `claims`)) 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 `saved`; `right` = call `bytes` on `csrf` of `claims`):
+            - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+          - Return `claims`.
+    - If they fail with `CryptoError`, name the failure `error` and recover:
+      - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+    - If they fail with [`JwtError`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-JwtError), name the failure `error` and recover:
+      - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+    - If they fail with `JsonError`, name the failure `error` and recover:
+      - Fail with call [`SessionError`](contracts.aug.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+
+**Author documentation**
+
+An app session has its own key, issuer, audience and token type. A live registry entry is required so logout revokes a signed token immediately.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)
+
+Capability interface from `august.crypto`.
+
+- [`Crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url) (`input`: `string`) → `Bytes`; can fail with `CryptoError`.
+- [`Crypto.equal`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.equal) (`left`: `Bytes`, `right`: `Bytes`) → `bool`.
+- [`Crypto.publicRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.publicRsa) (`key`: `RsaPrivateKey`) → `RsaPublicKey`; can fail with `CryptoError`.
+- [`Crypto.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa) (`publicKey`: `RsaPublicKey`, `input`: `Bytes`, `signature`: `Bytes`) → `bool`; can fail with `CryptoError`.
+
+### [`JwtError`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-JwtError)
+
+Class from `august.crypto`.
+
+Used as a type or provider.
+
+### [`verifyJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-verifyJwt)
+
+Function from `august.crypto`.
+
+- [`verifyJwt`](../.aug-spec/august/0.19.0/crypto/jose.aug.md#symbol-verifyJwt) (`token`: `string`, `publicKey`: `RsaPublicKey`, `kid`: `string`, `tokenType`: `string`) → `Json`; inject `crypto`: [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto); uses [`crypto.decodeBase64url`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.decodeBase64url), [`crypto.verifyRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.verifyRsa); can fail with `JwtError`.
+
+### [`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`.
+
+### [`SessionClaims`](contracts.aug.md#symbol-SessionClaims)
+
+Record from `contracts`.
+
+- Read `aud` (`string`).
+- Read `csrf` (`string`).
+- Read `exp` (`int`).
+- Read `iat` (`int`).
+- Read `iss` (`string`).
+- Read `jti` (`string`).
+- Read `sub` (`string`).
+
+### [`SessionError`](contracts.aug.md#symbol-SessionError)
+
+Class from `contracts`.
+
+- Construct with no caller inputs → [`SessionError`](contracts.aug.md#symbol-SessionError).
+
+### [`KeyError`](../common/keys.aug.md#symbol-KeyError)
+
+Class from `common`.
+
+Used as a type or provider.
+
+### [`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)
+
+Capability interface from `common`.
+
+- [`SigningKeys.session`](../common/keys.aug.md#symbol-SigningKeys.session) (no caller inputs) → `RsaPrivateKey`; can fail with `KeyError`.
+
+### [`Settings`](../common/settings.aug.md#symbol-Settings)
+
+Record.
+
+- Read `baseUrl` (`string`).
+- Read `sessionSeconds` (`int`).
+
+### [`settings`](../common/settings.aug.md#symbol-settings)
+
+Function from `common`.
+
+- [`settings`](../common/settings.aug.md#symbol-settings) (no caller inputs) → [`Settings`](../common/settings.aug.md#symbol-Settings).
+
+## Built-in operations used by this file
+
+- `Json.decode` (no inputs) → `SessionClaims`: Decode a checked record or data type: json.decode<Profile>(). Unknown fields, type mismatches, and validation errors are rejected. Can fail with `JsonError`.
+- `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/client/views.aug

@@ -0,0 +1,21 @@
+import SessionClaims from contracts
+import Page from common
+import logout from logout
+
+LoginPage() returns Html:
+    return <Page title="Sign in">
+        <p>This August app is both an OpenID Connect provider and a login client.</p>
+        <p><a href="/login/start" style="display:inline-block;padding:12px 20px;border-radius:10px;background:#4852d7;color:white;text-decoration:none">Sign in with OpenID Connect</a></p>
+        <p>The server uses authorization codes, S256 PKCE, state and nonce validation. Your session is a separate signed JWT in an HttpOnly cookie.</p>
+    </Page>
+
+Welcome(SessionClaims session) returns Html unless HttpError:
+    return <Page title={"Welcome, " + session.name}>
+        <p>You are signed in as <strong>{session.name}</strong>.</p>
+        <p>Subject: <code>{session.sub}</code></p>
+        <p><a href="/me">View the protected JSON endpoint</a></p>
+        <form method="post" action="/logout" onSubmit={handle logout(input from form)}>
+            <input type="hidden" name="csrf" value={session.csrf} />
+            <button type="submit" style="padding:10px 18px;border-radius:10px;border:0;background:#17233a;color:white;font:inherit">Sign out</button>
+        </form>
+    </Page>

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

@@ -0,0 +1,68 @@
+<!-- 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
+
+- [`LoginPage`](views.aug.md#symbol-LoginPage) is a function returning `Html`.
+- [`Welcome`](views.aug.md#symbol-Welcome) is a function returning `Html`.
+
+<a id="symbol-LoginPage"></a>
+
+## `LoginPage`
+
+[source](views.aug#L5)
+
+Returns: `Html`.
+
+**What it does**
+
+- Return the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = `"Sign in"` containing the HTML element `p` containing `This August app is both an OpenID Connect provider and a login client.` (rendered on the server with embedded text escaped), the HTML element `p` containing the HTML element `a` with `href` = `"/login/start"`, `style` = `"display:inline-block;padding:12px 20px;border-radius:10px;background:#4852d7;color:white;text-decoration:none"` containing `Sign in with OpenID Connect` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `p` containing `The server uses authorization codes, S256 PKCE, state and nonce validation. Your session is a separate signed JWT in an HttpOnly cookie.` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped).
+
+<a id="symbol-Welcome"></a>
+
+## `Welcome`
+
+[source](views.aug#L12)
+
+**Inputs**
+
+- `session` ([`SessionClaims`](contracts.aug.md#symbol-SessionClaims)) — required labeled input.
+
+Returns: `Html`.
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Return the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = `"Welcome, "` plus `name` of `session` containing the HTML element `p` containing `You are signed in as `, the HTML element `strong` containing `name` of `session` (rendered on the server with embedded text escaped), `.` (rendered on the server with embedded text escaped), the HTML element `p` containing `Subject: `, the HTML element `code` containing `sub` of `session` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `p` containing the HTML element `a` with `href` = `"/me"` containing `View the protected JSON endpoint` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped), the HTML element `form` with `method` = `"post"`, `action` = `"/logout"`, `onSubmit` = a deferred HTTP form action for [`logout`](logout.aug.md#symbol-logout); 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 containing the HTML element `input` with `type` = `"hidden"`, `name` = `"csrf"`, `value` = `csrf` of `session` (rendered on the server with embedded text escaped), the HTML element `button` with `type` = `"submit"`, `style` = `"padding:10px 18px;border-radius:10px;border:0;background:#17233a;color:white;font:inherit"` containing `Sign out` (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped) (rendered on the server with embedded text escaped).
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`SessionClaims`](contracts.aug.md#symbol-SessionClaims)
+
+Record from `contracts`.
+
+- Read `csrf` (`string`).
+- Read `name` (`string`).
+- Read `sub` (`string`).
+
+### [`logout`](logout.aug.md#symbol-logout)
+
+Function from `logout`.
+
+- [`logout`](logout.aug.md#symbol-logout) (`input`: [`LogoutForm`](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`.
+
+### [`Page`](../common/views.aug.md#symbol-Page)
+
+Function from `common`.
+
+- [`Page`](../common/views.aug.md#symbol-Page) (`title`: `string`, `children`: `List<Html>`) → `Html`.
+
+## 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/export.aug

@@ -0,0 +1,9 @@
+export Settings from settings
+export settings from settings
+export SigningKeys from keys
+export MemorySigningKeys from keys
+export initializeKeys from keys
+export KeyError from keys
+export Page from views
+export securityHeaders from headers
+export withCookie from headers

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

@@ -0,0 +1,33 @@
+<!-- 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 `Settings` from this folder.
+- Export `settings` from this folder.
+- Export `SigningKeys` from this folder.
+- Export `MemorySigningKeys` from this folder.
+- Export `initializeKeys` from this folder.
+- Export `KeyError` from this folder.
+- Export `Page` from this folder.
+- Export `securityHeaders` from this folder.
+- Export `withCookie` from this folder.
+
+## Folder exports
+
+- Export the declaration `Settings` from [`settings.aug`](settings.aug.md#symbol-Settings).
+- Export the declaration `settings` from [`settings.aug`](settings.aug.md#symbol-settings).
+- Export the declaration `SigningKeys` from [`keys.aug`](keys.aug.md#symbol-SigningKeys).
+- Export the declaration `MemorySigningKeys` from [`keys.aug`](keys.aug.md#symbol-MemorySigningKeys).
+- Export the declaration `initializeKeys` from [`keys.aug`](keys.aug.md#symbol-initializeKeys).
+- Export the declaration `KeyError` from [`keys.aug`](keys.aug.md#symbol-KeyError).
+- Export the declaration `Page` from [`views.aug`](views.aug.md#symbol-Page).
+- Export the declaration `securityHeaders` from [`headers.aug`](headers.aug.md#symbol-securityHeaders).
+- Export the declaration `withCookie` from [`headers.aug`](headers.aug.md#symbol-withCookie).
+
+## 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/headers.aug

@@ -0,0 +1,11 @@
+/** Responses containing identity data are never cached or embedded by another site. */
+securityHeaders() returns Headers unless HttpError:
+    return Headers().with(name="cache-control", value="no-store").with(name="pragma", value="no-cache").with(name="x-content-type-options", value="nosniff").with(name="referrer-policy", value="no-referrer").with(name="content-security-policy", value="default-src 'self'; style-src 'unsafe-inline'; script-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'")
+
+/** Add a checked cookie without losing duplicate Set-Cookie response fields. */
+withCookie(Headers headers, string name, string value, string path, int maxAge, bool secure) returns Headers unless HttpError:
+    result = headers
+    for content in cookie(name, value, path, maxAge, secure).all(name="set-cookie"):
+        result = result.with(name="set-cookie", value=content)
+    return result
+import cookie from august.web

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

@@ -0,0 +1,79 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `headers.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`securityHeaders`](headers.aug.md#symbol-securityHeaders) is a function returning `Headers`.
+- [`withCookie`](headers.aug.md#symbol-withCookie) is a function returning `Headers`.
+
+<a id="symbol-securityHeaders"></a>
+
+## `securityHeaders`
+
+[source](headers.aug#L2)
+
+Returns: `Headers`.
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Return call `with` on call `with` on call `with` on call `with` on call `with` on call `Headers` with `name` = `"cache-control"`; `value` = `"no-store"` with `name` = `"pragma"`; `value` = `"no-cache"` with `name` = `"x-content-type-options"`; `value` = `"nosniff"` with `name` = `"referrer-policy"`; `value` = `"no-referrer"` with `name` = `"content-security-policy"`; `value` = `"default-src 'self'; style-src 'unsafe-inline'; script-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'"`.
+
+**Author documentation**
+
+Responses containing identity data are never cached or embedded by another site.
+
+<a id="symbol-withCookie"></a>
+
+## `withCookie`
+
+[source](headers.aug#L6)
+
+**Inputs**
+
+- `headers` (`Headers`) — required labeled input.
+- `name` (`string`) — required labeled input.
+- `value` (`string`) — required labeled input.
+- `path` (`string`) — required labeled input.
+- `maxAge` (`int`) — required labeled input.
+- `secure` (`bool`) — required labeled input.
+
+Returns: `Headers`.
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Set `result` to `headers`.
+- For each `content` in a snapshot of call `all` on call [`cookie`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-cookie) with `name` = `name`; `value` = `value`; `path` = `path`; `maxAge` = `maxAge`; `secure` = `secure` with `name` = `"set-cookie"`, in iteration order:
+  - Set `result` to call `with` on `result` with `name` = `"set-cookie"`; `value` = `content`.
+- Return `result`.
+
+**Author documentation**
+
+Add a checked cookie without losing duplicate Set-Cookie response fields.
+
+## Dependencies used by this file
+
+Only referenced types and operations appear here. Each name links to its complete specification.
+
+### [`cookie`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-cookie)
+
+Function from `august.web`.
+
+- [`cookie`](../.aug-spec/august/0.19.0/web/contracts.aug.md#symbol-cookie) (`name`: `string`, `value`: `string`, `path`: `string`, `maxAge`: `int`, `secure`: `bool`) → `Headers`; can fail with `HttpError`.
+
+## Built-in operations used by this file
+
+- `Headers.all` (`name`: `string`) → `List<string>`: Read every value of this header in wire order.
+- `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`.
+
+[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/common/keys.aug

@@ -0,0 +1,37 @@
+import Crypto from august.crypto
+
+KeyError() implements Error:
+    pass
+/** Keys are initialized explicitly in main and expose distinct provider and session roles. */
+capability SigningKeys:
+    configure(RsaPrivateKey provider, RsaPrivateKey session) uses SigningKeys.configure unless KeyError
+    provider() returns RsaPrivateKey uses SigningKeys.provider unless KeyError
+    session() returns RsaPrivateKey uses SigningKeys.session unless KeyError
+
+MemorySigningKeys() implements SigningKeys:
+    Shared<Map<string, RsaPrivateKey>> _keys = Shared(value=Map<string, RsaPrivateKey>())
+    configure(RsaPrivateKey provider, RsaPrivateKey session) uses SigningKeys.configure unless KeyError:
+        lock _keys as keys:
+            if keys.length() != 0:
+                throw KeyError()
+            keys.set(key="provider", value=provider)
+            keys.set(key="session", value=session)
+    provider() returns RsaPrivateKey uses SigningKeys.provider unless KeyError:
+        lock _keys as keys:
+            match keys.get(key="provider"):
+                when null:
+                    throw KeyError()
+                when some key:
+                    return key
+    session() returns RsaPrivateKey uses SigningKeys.session unless KeyError:
+        lock _keys as keys:
+            match keys.get(key="session"):
+                when null:
+                    throw KeyError()
+                when some key:
+                    return key
+
+initializeKeys(resolve Crypto crypto, resolve SigningKeys keys) uses crypto.generateRsa and keys.configure unless CryptoError and KeyError:
+    provider = crypto.generateRsa()
+    session = crypto.generateRsa()
+    keys.configure(provider, session)

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

@@ -0,0 +1,207 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `keys.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`KeyError`](keys.aug.md#symbol-KeyError) is a class implementing `Error`.
+- [`SigningKeys`](keys.aug.md#symbol-SigningKeys) is a capability interface.
+- [`MemorySigningKeys`](keys.aug.md#symbol-MemorySigningKeys) is a class implementing `SigningKeys`.
+- [`initializeKeys`](keys.aug.md#symbol-initializeKeys) is a function.
+
+<a id="symbol-KeyError"></a>
+
+## `KeyError`
+
+[source](keys.aug#L3)
+
+Behavioral class.
+
+Satisfies `Error`.
+
+<a id="symbol-SigningKeys"></a>
+
+## `SigningKeys`
+
+[source](keys.aug#L6)
+
+Capability interface.
+
+**Author documentation**
+
+Keys are initialized explicitly in main and expose distinct provider and session roles.
+
+<a id="symbol-SigningKeys.configure"></a>
+
+### `SigningKeys.configure`
+
+[source](keys.aug#L7)
+
+**Inputs**
+
+- `provider` (`RsaPrivateKey`) — required labeled input.
+- `session` (`RsaPrivateKey`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`SigningKeys.configure`](keys.aug.md#symbol-SigningKeys.configure).
+
+Can fail with `KeyError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-SigningKeys.provider"></a>
+
+### `SigningKeys.provider`
+
+[source](keys.aug#L8)
+
+Returns: `RsaPrivateKey`.
+
+Capabilities: [`SigningKeys.provider`](keys.aug.md#symbol-SigningKeys.provider).
+
+Can fail with `KeyError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-SigningKeys.session"></a>
+
+### `SigningKeys.session`
+
+[source](keys.aug#L9)
+
+Returns: `RsaPrivateKey`.
+
+Capabilities: [`SigningKeys.session`](keys.aug.md#symbol-SigningKeys.session).
+
+Can fail with `KeyError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-MemorySigningKeys"></a>
+
+## `MemorySigningKeys`
+
+[source](keys.aug#L11)
+
+Behavioral class.
+
+Satisfies [`SigningKeys`](keys.aug.md#symbol-SigningKeys).
+
+**Field initialization**
+
+- Initialize `_keys` of type `Shared<Map<string,RsaPrivateKey>>` to call `Shared` with `value` = an empty map from `string` to `RsaPrivateKey`. Read-only storage, private to this class.
+
+<a id="symbol-MemorySigningKeys.configure"></a>
+
+### `MemorySigningKeys.configure`
+
+[source](keys.aug#L13)
+
+**Inputs**
+
+- `provider` (`RsaPrivateKey`) — required labeled input.
+- `session` (`RsaPrivateKey`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`SigningKeys.configure`](keys.aug.md#symbol-SigningKeys.configure).
+
+Can fail with `KeyError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Lock `_keys`, expose its mutable value as `keys`, and release the lock on every exit:
+  - If call `length` on `keys` does not equal `0`:
+    - Fail with call [`KeyError`](keys.aug.md#symbol-KeyError). Transfer control to a matching catch or propagate the failure.
+  - Call `set` on `keys` with `key` = `"provider"`; `value` = `provider`.
+  - Call `set` on `keys` with `key` = `"session"`; `value` = `session`.
+
+<a id="symbol-MemorySigningKeys.provider"></a>
+
+### `MemorySigningKeys.provider`
+
+[source](keys.aug#L19)
+
+Returns: `RsaPrivateKey`.
+
+Capabilities: [`SigningKeys.provider`](keys.aug.md#symbol-SigningKeys.provider).
+
+Can fail with `KeyError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Lock `_keys`, expose its mutable value as `keys`, and release the lock on every exit:
+  - Select the matching case for call `get` on `keys` with `key` = `"provider"`:
+    - A null value, including omitted optional input:
+      - Fail with call [`KeyError`](keys.aug.md#symbol-KeyError). Transfer control to a matching catch or propagate the failure.
+    - A present, non-null value, named `key`:
+      - Return `key`.
+
+<a id="symbol-MemorySigningKeys.session"></a>
+
+### `MemorySigningKeys.session`
+
+[source](keys.aug#L26)
+
+Returns: `RsaPrivateKey`.
+
+Capabilities: [`SigningKeys.session`](keys.aug.md#symbol-SigningKeys.session).
+
+Can fail with `KeyError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Lock `_keys`, expose its mutable value as `keys`, and release the lock on every exit:
+  - Select the matching case for call `get` on `keys` with `key` = `"session"`:
+    - A null value, including omitted optional input:
+      - Fail with call [`KeyError`](keys.aug.md#symbol-KeyError). Transfer control to a matching catch or propagate the failure.
+    - A present, non-null value, named `key`:
+      - Return `key`.
+
+<a id="symbol-initializeKeys"></a>
+
+## `initializeKeys`
+
+[source](keys.aug#L34)
+
+**Inputs**
+
+- `crypto` ([`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)) — injected; callers omit it.
+- `keys` ([`SigningKeys`](keys.aug.md#symbol-SigningKeys)) — injected; callers omit it.
+
+Returns: no value.
+
+Capabilities: [`crypto.generateRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.generateRsa), [`keys.configure`](keys.aug.md#symbol-SigningKeys.configure).
+
+Can fail with `CryptoError`, `KeyError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Set `provider` to call [`Crypto.generateRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.generateRsa) on `crypto`.
+- Set `session` to call [`Crypto.generateRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.generateRsa) on `crypto`.
+- Call [`SigningKeys.configure`](keys.aug.md#symbol-SigningKeys.configure) on `keys` with `provider` = `provider`; `session` = `session`.
+
+## 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.generateRsa`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto.generateRsa) (no caller inputs) → `RsaPrivateKey`; can fail with `CryptoError`.
+
+## Built-in operations used by this file
+
+- `Map<string, RsaPrivateKey>.get` (`key`: `string`) → `optional RsaPrivateKey`: Read a value by key; an absent key returns null. contains distinguishes an absent key from a stored null.
+- `Map<string, RsaPrivateKey>.length` (no inputs) → `int`: Read the number of elements.
+- `Map<string, RsaPrivateKey>.set` (`key`: `string`, `value`: `RsaPrivateKey`) → `void`: Insert or replace an entry with exclusive mutable access. Changes the receiver.
+
+[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/common/settings.aug

@@ -0,0 +1,4 @@
+/** Explicit loopback development settings. The provider accepts one registered client and its exact callback URI. */
+record Settings(string baseUrl, string issuer, string clientId, string callback, int sessionSeconds, bool secureCookies)
+settings() returns Settings:
+    return Settings(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)