@greenpandastudios/aug-cli 0.19.0 → 0.20.1

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

@@ -1,155 +1,28 @@
 <!-- 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`.
+# `session.aug`
 
 <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**
+## `authenticate` · [source](session.aug#L9)
 
 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.
+It takes `token` as `optional string`. It gets `crypto` ([`Crypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto)), `clock` ([`Clock`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock)), `keys` ([`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys)), and `sessions` ([`ExpiringStore<SessionClaims>`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore)) from dependency injection. Omitted optional inputs are null. Failures can raise [`KeyError`](../common/keys.aug.md#symbol-KeyError), [`SessionError`](contracts.aug.md#symbol-SessionError), and `TimeError`.
 
-- Read `baseUrl` (`string`).
-- Read `sessionSeconds` (`int`).
+If `token` is null, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError). The non-null `token` becomes `value`. It sets `publicKey` to [`crypto.publicRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.publicRsa) with `key` from [`keys.session`](../common/keys.aug.md#symbol-SigningKeys.session). It sets `claims` to `decode` on [`verifyJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-verifyJwt) with `token` from `value`, `publicKey`, `kid` `"session-1"`, and `tokenType` `"august-session+jwt"` using injected `crypto` for [`SessionClaims`](contracts.aug.md#symbol-SessionClaims).
 
-### [`settings`](../common/settings.aug.md#symbol-settings)
+It gets `config` from [`settings`](../common/settings.aug.md#symbol-settings). It sets `now` to [`clock.now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now). It checks that `claims.iss` equals the text `{config.baseUrl}/app` and `claims.aud` equals `"august-app"` and the byte length of `claims.sub` does not equal `0` and `claims.exp` is greater than `now` and `claims.iat` is at most (`now` plus `30`) and `claims.iat` is at least (`now` minus `config.sessionSeconds`) and `claims.exp` is greater than `claims.iat` and `claims.exp` is at most ((`now` plus `config.sessionSeconds`) plus `30`). It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check.
 
-Function from `common`.
+It checks that `claims.jti` is a URL-safe ASCII token with `43` to `43` characters and `claims.csrf` is a URL-safe ASCII token with `43` to `43` characters. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It obtains [`sessions.get`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.get) with `key` from `claims.jti` and `now`. If no value is found, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError).
 
-- [`settings`](../common/settings.aug.md#symbol-settings) (no caller inputs) → [`Settings`](../common/settings.aug.md#symbol-Settings).
+The non-null result becomes `saved`. It checks that `saved.sub` equals `claims.sub` and `saved.exp` equals `claims.exp` and [`crypto.equal`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.equal) with `left` from the UTF-8 bytes of `saved.csrf` and `right` from the UTF-8 bytes of `claims.csrf` returns true. It raises a [`SessionError`](contracts.aug.md#symbol-SessionError) at the first failed check. It returns `claims`.
 
-## Built-in operations used by this file
+If this work raises `CryptoError`, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError). If this work raises [`JwtError`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-JwtError), it raises a [`SessionError`](contracts.aug.md#symbol-SessionError). If this work raises `JsonError`, it raises a [`SessionError`](contracts.aug.md#symbol-SessionError).
 
-- `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.
+## Dependencies
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+It uses [`ExpiringStore`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore) ([`get`](../.aug-spec/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.aug.md#symbol-ExpiringStore.get)) from `memory`. It uses [`Crypto`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto) ([`decodeBase64url`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.decodeBase64url), [`equal`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.equal), [`publicRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.publicRsa), and [`verifyRsa`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.aug.md#symbol-Crypto.verifyRsa)), [`JwtError`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-JwtError), and [`verifyJwt`](../.aug-spec/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.aug.md#symbol-verifyJwt) from `crypto`. It uses [`Clock`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock) ([`now`](../.aug-spec/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-Clock.now)) from `time`. It uses [`SessionClaims`](contracts.aug.md#symbol-SessionClaims) (`aud`, `csrf`, `exp`, `iat`, `iss`, `jti`, and `sub`) and [`SessionError`](contracts.aug.md#symbol-SessionError) from `contracts`.
 
-## Shared language rules
+It uses [`KeyError`](../common/keys.aug.md#symbol-KeyError), [`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys) ([`session`](../common/keys.aug.md#symbol-SigningKeys.session)), and [`settings`](../common/settings.aug.md#symbol-settings) from `common`. It uses [`Settings`](../common/settings.aug.md#symbol-Settings) (`baseUrl` and `sessionSeconds`).
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

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

@@ -1,15 +1,16 @@
+// aug-spec: "views.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import SessionClaims from contracts
 import Page from common
 import logout from logout
 
-LoginPage() returns Html:
+LoginPage() :
     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:
+Welcome(SessionClaims session) :
     return <Page title={"Welcome, " + session.name}>
         <p>You are signed in as <strong>{session.name}</strong>.</p>
         <p>Subject: <code>{session.sub}</code></p>

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

@@ -1,68 +1,19 @@
 <!-- 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`.
+# `views.aug`
 
 <a id="symbol-LoginPage"></a>
+## `LoginPage` · [source](views.aug#L6)
 
-## `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).
+It returns the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = `"Sign in"` containing a paragraph containing `This August app is both an OpenID Connect provider and a login client.` with escaped text, a paragraph containing a link 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` with escaped text with escaped text, a paragraph containing `The server uses authorization codes, S256 PKCE, state and nonce validation. Your session is a separate signed JWT in an HttpOnly cookie.` with escaped text with escaped text.
 
 <a id="symbol-Welcome"></a>
+## `Welcome` · [source](views.aug#L13)
 
-## `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`.
+It takes `session` as [`SessionClaims`](contracts.aug.md#symbol-SessionClaims). Failures can raise `HttpError`.
 
-- [`Page`](../common/views.aug.md#symbol-Page) (`title`: `string`, `children`: `List<Html>`) → `Html`.
+It returns the server component [`Page`](../common/views.aug.md#symbol-Page) with `title` = the text `Welcome, {session.name}` containing a paragraph containing `You are signed in as `, the HTML element `strong` containing `session.name` with escaped text, `.` with escaped text, a paragraph containing `Subject: `, the HTML element `code` containing `session.sub` with escaped text with escaped text, a paragraph containing a link with `href` = `"/me"` containing `View the protected JSON endpoint` with escaped text with escaped text, the HTML element `form` with `method` = `"post"`, `action` = `"/logout"`, `onSubmit` = a form action that sends `POST /logout` to [`logout`](logout.aug.md#symbol-logout) on submission containing the HTML element `input` with `type` = `"hidden"`, `name` = `"csrf"`, `value` = `session.csrf` with escaped text, a button with `type` = `"submit"`, `style` = `"padding:10px 18px;border-radius:10px;border:0;background:#17233a;color:white;font:inherit"` containing `Sign out` with escaped text with escaped text with escaped text.
 
-## Shared language rules
+## Dependencies
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`SessionClaims`](contracts.aug.md#symbol-SessionClaims) (`csrf`, `name`, and `sub`) from `contracts`. It uses [`logout`](logout.aug.md#symbol-logout) from `logout`. It uses [`Page`](../common/views.aug.md#symbol-Page) from `common`.

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

@@ -1,3 +1,4 @@
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export Settings from settings
 export settings from settings
 export SigningKeys from keys

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

@@ -1,33 +1,11 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `export.aug` specification
+# `export.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+## Exports
 
-## In this file
+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 `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.
+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).
 
-## 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.
+Export the declaration `withCookie` from [`headers.aug`](headers.aug.md#symbol-withCookie).

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

@@ -1,11 +1,12 @@
+// aug-spec: "headers.aug.md" explains this file. Read it before changes; refresh with aug spec.
 /** Responses containing identity data are never cached or embedded by another site. */
-securityHeaders() returns Headers unless HttpError:
+securityHeaders() :
     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:
+withCookie(Headers headers, string name, string value, string path, int maxAge, bool secure) :
     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
+import cookie from web

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

@@ -1,79 +1,21 @@
 <!-- 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`.
+# `headers.aug`
 
 <a id="symbol-securityHeaders"></a>
+## `securityHeaders` · [source](headers.aug#L3)
 
-## `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.
+Responses containing identity data are never cached or embedded by another site. Failures can raise `HttpError`. It returns headers starting with a `Headers` and adding these fields in order: `"cache-control"` to `"no-store"`, `"pragma"` to `"no-cache"`, `"x-content-type-options"` to `"nosniff"`, `"referrer-policy"` to `"no-referrer"`, and `"content-security-policy"` to `"default-src 'self'; style-src 'unsafe-inline'; script-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'"`.
 
 <a id="symbol-withCookie"></a>
+## `withCookie` · [source](headers.aug#L7)
 
-## `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
+Add a checked cookie without losing duplicate Set-Cookie response fields. It takes `headers` as `Headers`, `name`, `value`, and `path` as strings, `maxAge` as an integer, and `secure` as a boolean. Failures can raise `HttpError`.
 
-- `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`.
+It sets `result` to `headers`. For each `content` in a snapshot of `all` on [`cookie`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-cookie) with `name`, `value`, `path`, `maxAge`, and `secure` with `name` `"set-cookie"`, it sets `result` to `result` with the header `"set-cookie"` set to `content`. After the loop, it returns `result`.
 
-[Full built-in reference](https://greenpandastudios.github.io/augscript/language-constructs).
+## Dependencies
 
-## Shared language rules
+It uses [`cookie`](../.aug-spec/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.aug.md#symbol-cookie) from `web`.
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).

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

@@ -1,4 +1,5 @@
-import Crypto from august.crypto
+// aug-spec: "keys.aug.md" explains this file. Read it before changes; refresh with aug spec.
+import Crypto from crypto
 
 KeyError() implements Error:
     pass
@@ -10,20 +11,20 @@ capability SigningKeys:
 
 MemorySigningKeys() implements SigningKeys:
     Shared<Map<string, RsaPrivateKey>> _keys = Shared(value=Map<string, RsaPrivateKey>())
-    configure(RsaPrivateKey provider, RsaPrivateKey session) uses SigningKeys.configure unless KeyError:
+    configure(RsaPrivateKey provider, RsaPrivateKey session) :
         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:
+    provider() :
         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:
+    session() :
         lock _keys as keys:
             match keys.get(key="session"):
                 when null:
@@ -31,7 +32,7 @@ MemorySigningKeys() implements SigningKeys:
                 when some key:
                     return key
 
-initializeKeys(resolve Crypto crypto, resolve SigningKeys keys) uses crypto.generateRsa and keys.configure unless CryptoError and KeyError:
+initializeKeys(resolve Crypto crypto, resolve SigningKeys keys) :
     provider = crypto.generateRsa()
     session = crypto.generateRsa()
     keys.configure(provider, session)