@greenpandastudios/aug-cli 0.19.0 → 0.21.0

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

@@ -49,20 +49,26 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "session.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import SessionClaims and SessionError from contracts
 import settings and SigningKeys and KeyError from common
-import Crypto and verifyJwt and JwtError from august.crypto
-import Clock from august.time
-import ExpiringStore from august.memory
+import Crypto and verifyJwt and JwtError from crypto
+import Clock from time
+import ExpiringStore from memory
 /** 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. */
-authenticate(optional string token, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) returns SessionClaims uses crypto.publicRsa and crypto.decodeBase64url and crypto.verifyRsa and crypto.equal and clock.now and keys.session and sessions.get unless SessionError and KeyError and TimeError:
+authenticate(optional string token, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions):
     match token:
         when null:
             throw SessionError()
         when some value:
             try:
                 publicKey = crypto.publicRsa(key=keys.session())
-                claims = verifyJwt(token=value, publicKey, kid="session-1", tokenType="august-session+jwt").decode<SessionClaims>()
+                claims = verifyJwt(
+                    token=value,
+                    publicKey,
+                    kid="session-1",
+                    tokenType="august-session+jwt"
+                ).decode<SessionClaims>()
                 config = settings()
                 now = clock.now()
                 if claims.iss != config.baseUrl + "/app" or claims.aud != "august-app" or claims.sub.length() == 0 or claims.exp <= now or claims.iat > now + 30 or claims.iat < now - config.sessionSeconds or claims.exp <= claims.iat or claims.exp > now + config.sessionSeconds + 30:
@@ -73,7 +79,10 @@ authenticate(optional string token, resolve Crypto crypto, resolve Clock clock,
                     when null:
                         throw SessionError()
                     when some saved:
-                        if saved.sub != claims.sub or saved.exp != claims.exp or not crypto.equal(left=saved.csrf.bytes(), right=claims.csrf.bytes()):
+                        if saved.sub != claims.sub or saved.exp != claims.exp or not crypto.equal(
+                            left=saved.csrf.bytes(),
+                            right=claims.csrf.bytes()
+                        ):
                             throw SessionError()
                         return claims
             catch CryptoError error:
@@ -85,13 +94,14 @@ authenticate(optional string token, resolve Crypto crypto, resolve Clock clock,
 ```
 
 ```aug [Braces]
+// aug-spec: "session.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import SessionClaims and SessionError from contracts
 import settings and SigningKeys and KeyError from common
-import Crypto and verifyJwt and JwtError from august.crypto
-import Clock from august.time
-import ExpiringStore from august.memory
+import Crypto and verifyJwt and JwtError from crypto
+import Clock from time
+import ExpiringStore from memory
 /** 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. */
-authenticate(optional string token, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) returns SessionClaims uses crypto.publicRsa and crypto.decodeBase64url and crypto.verifyRsa and crypto.equal and clock.now and keys.session and sessions.get unless SessionError and KeyError and TimeError {
+authenticate(optional string token, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) {
     match token {
         when null {
             throw SessionError()
@@ -99,7 +109,12 @@ authenticate(optional string token, resolve Crypto crypto, resolve Clock clock,
         when some value {
             try {
                 publicKey = crypto.publicRsa(key=keys.session())
-                claims = verifyJwt(token=value, publicKey, kid="session-1", tokenType="august-session+jwt").decode<SessionClaims>()
+                claims = verifyJwt(
+                    token=value,
+                    publicKey,
+                    kid="session-1",
+                    tokenType="august-session+jwt"
+                ).decode<SessionClaims>()
                 config = settings()
                 now = clock.now()
                 if claims.iss != config.baseUrl + "/app" or claims.aud != "august-app" or claims.sub.length() == 0 or claims.exp <= now or claims.iat > now + 30 or claims.iat < now - config.sessionSeconds or claims.exp <= claims.iat or claims.exp > now + config.sessionSeconds + 30 {
@@ -113,7 +128,10 @@ authenticate(optional string token, resolve Crypto crypto, resolve Clock clock,
                         throw SessionError()
                     }
                     when some saved {
-                        if saved.sub != claims.sub or saved.exp != claims.exp or not crypto.equal(left=saved.csrf.bytes(), right=claims.csrf.bytes()) {
+                        if saved.sub != claims.sub or saved.exp != claims.exp or not crypto.equal(
+                            left=saved.csrf.bytes(),
+                            right=claims.csrf.bytes()
+                        ) {
                             throw SessionError()
                         }
                         return claims
@@ -142,155 +160,29 @@ authenticate(optional string token, resolve Crypto crypto, resolve Clock clock,
 
 ## Compiled specification {#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.md#symbol-authenticate) is a function returning `SessionClaims`.
-
-### `authenticate` {#symbol-authenticate}
-
-[source](session.md#code)
-
-**Inputs**
-
-- `token` (`optional string`) — optional labeled input; omission becomes null.
-- `crypto` ([`Crypto`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto)) — injected; callers omit it.
-- `clock` ([`Clock`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock)) — injected; callers omit it.
-- `keys` ([`SigningKeys`](../common/keys.md#symbol-SigningKeys)) — injected; callers omit it.
-- `sessions` ([`ExpiringStore<SessionClaims>`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore)) — injected; callers omit it.
-
-Returns: [`SessionClaims`](contracts.md#symbol-SessionClaims).
-
-Capabilities: [`crypto.publicRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.publicRsa), [`crypto.decodeBase64url`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.decodeBase64url), [`crypto.verifyRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.verifyRsa), [`crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal), [`clock.now`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock.now), [`keys.session`](../common/keys.md#symbol-SigningKeys.session), [`sessions.get`](../dependencies/august/0.19.0/memory/store.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.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`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.publicRsa) on `crypto` with `key` = call [`SigningKeys.session`](../common/keys.md#symbol-SigningKeys.session) on `keys`.
-      - Set `claims` to call `decode` on call [`verifyJwt`](../dependencies/august/0.19.0/crypto/jose.md#symbol-verifyJwt) with `token` = `value`; `publicKey` = `publicKey`; `kid` = `"session-1"`; `tokenType` = `"august-session+jwt"`; inject `crypto` from `crypto` with type arguments [`SessionClaims`](contracts.md#symbol-SessionClaims).
-      - Set `config` to call [`settings`](../common/settings.md#symbol-settings).
-      - Set `now` to call [`Clock.now`](../dependencies/august/0.19.0/time/contracts.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.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.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-      - Select the matching case for call [`ExpiringStore.get`](../dependencies/august/0.19.0/memory/store.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.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`](../dependencies/august/0.19.0/crypto/contracts.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.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.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-    - If they fail with [`JwtError`](../dependencies/august/0.19.0/crypto/jose.md#symbol-JwtError), name the failure `error` and recover:
-      - Fail with call [`SessionError`](contracts.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.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
-
-**Author documentation**
+### `authenticate` · [source](session.md#code) {#symbol-authenticate}
 
 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`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto)
-
-Capability interface from `august.crypto`.
-
-- [`Crypto.decodeBase64url`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.decodeBase64url) (`input`: `string`) → `Bytes`; can fail with `CryptoError`.
-- [`Crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal) (`left`: `Bytes`, `right`: `Bytes`) → `bool`.
-- [`Crypto.publicRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.publicRsa) (`key`: `RsaPrivateKey`) → `RsaPublicKey`; can fail with `CryptoError`.
-- [`Crypto.verifyRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.verifyRsa) (`publicKey`: `RsaPublicKey`, `input`: `Bytes`, `signature`: `Bytes`) → `bool`; can fail with `CryptoError`.
-
-#### [`JwtError`](../dependencies/august/0.19.0/crypto/jose.md#symbol-JwtError)
-
-Class from `august.crypto`.
-
-Used as a type or provider.
-
-#### [`verifyJwt`](../dependencies/august/0.19.0/crypto/jose.md#symbol-verifyJwt)
-
-Function from `august.crypto`.
-
-- [`verifyJwt`](../dependencies/august/0.19.0/crypto/jose.md#symbol-verifyJwt) (`token`: `string`, `publicKey`: `RsaPublicKey`, `kid`: `string`, `tokenType`: `string`) → `Json`; inject `crypto`: [`Crypto`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto); uses [`crypto.decodeBase64url`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.decodeBase64url), [`crypto.verifyRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.verifyRsa); can fail with `JwtError`.
-
-#### [`ExpiringStore`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore)
-
-Capability interface from `august.memory`.
-
-- [`ExpiringStore.get`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.get) (`key`: `string`, `now`: `int`) → `optional T`.
-
-#### [`Clock`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock)
-
-Capability interface from `august.time`.
-
-- [`Clock.now`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock.now) (no caller inputs) → `int`; can fail with `TimeError`.
-
-#### [`SessionClaims`](contracts.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.md#symbol-SessionError)
-
-Class from `contracts`.
-
-- Construct with no caller inputs → [`SessionError`](contracts.md#symbol-SessionError).
-
-#### [`KeyError`](../common/keys.md#symbol-KeyError)
-
-Class from `common`.
-
-Used as a type or provider.
-
-#### [`SigningKeys`](../common/keys.md#symbol-SigningKeys)
-
-Capability interface from `common`.
-
-- [`SigningKeys.session`](../common/keys.md#symbol-SigningKeys.session) (no caller inputs) → `RsaPrivateKey`; can fail with `KeyError`.
-
-#### [`Settings`](../common/settings.md#symbol-Settings)
-
-Record.
+It takes `token` as `optional string`. It gets `crypto` ([`Crypto`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto)), `clock` ([`Clock`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-Clock)), `keys` ([`SigningKeys`](../common/keys.md#symbol-SigningKeys)), and `sessions` ([`ExpiringStore<SessionClaims>`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore)) from dependency injection. Omitted optional inputs are null. Failures can raise [`KeyError`](../common/keys.md#symbol-KeyError), [`SessionError`](contracts.md#symbol-SessionError), and `TimeError`.
 
-- Read `baseUrl` (`string`).
-- Read `sessionSeconds` (`int`).
+If `token` is null, it raises a [`SessionError`](contracts.md#symbol-SessionError). The non-null `token` becomes `value`. It sets `publicKey` to [`crypto.publicRsa`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.publicRsa) with `key` from [`keys.session`](../common/keys.md#symbol-SigningKeys.session). It sets `claims` to `decode` on [`verifyJwt`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-verifyJwt) with `token` from `value`, `publicKey`, `kid` `"session-1"`, and `tokenType` `"august-session+jwt"` using injected `crypto` for [`SessionClaims`](contracts.md#symbol-SessionClaims).
 
-#### [`settings`](../common/settings.md#symbol-settings)
+It gets `config` from [`settings`](../common/settings.md#symbol-settings). It sets `now` to [`clock.now`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.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.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.md#symbol-SessionError) at the first failed check. It obtains [`sessions.get`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore.get) with `key` from `claims.jti` and `now`. If no value is found, it raises a [`SessionError`](contracts.md#symbol-SessionError).
 
-- [`settings`](../common/settings.md#symbol-settings) (no caller inputs) → [`Settings`](../common/settings.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`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.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.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.md#symbol-SessionError). If this work raises [`JwtError`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-JwtError), it raises a [`SessionError`](contracts.md#symbol-SessionError). If this work raises `JsonError`, it raises a [`SessionError`](contracts.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`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore) ([`get`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore.get)) from `memory`. It uses [`Crypto`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto) ([`decodeBase64url`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.decodeBase64url), [`equal`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.equal), [`publicRsa`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.publicRsa), and [`verifyRsa`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.verifyRsa)), [`JwtError`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-JwtError), and [`verifyJwt`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-verifyJwt) from `crypto`. It uses [`Clock`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-Clock) ([`now`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-Clock.now)) from `time`. It uses [`SessionClaims`](contracts.md#symbol-SessionClaims) (`aud`, `csrf`, `exp`, `iat`, `iss`, `jti`, and `sub`) and [`SessionError`](contracts.md#symbol-SessionError) from `contracts`.
 
-### Shared language rules
+It uses [`KeyError`](../common/keys.md#symbol-KeyError), [`SigningKeys`](../common/keys.md#symbol-SigningKeys) ([`session`](../common/keys.md#symbol-SigningKeys.session)), and [`settings`](../common/settings.md#symbol-settings) from `common`. It uses [`Settings`](../common/settings.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/docs/examples/oidc-login/client/views.md

@@ -49,23 +49,25 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// 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><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>
 ```
 
 ```aug [Braces]
+// 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><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>
 }
 ```
@@ -78,66 +80,19 @@ Welcome(SessionClaims session) returns Html unless HttpError {
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `LoginPage` · [source](views.md#code) {#symbol-LoginPage}
 
-### In this file
+It returns the server component [`Page`](../common/views.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.
 
-- [`LoginPage`](views.md#symbol-LoginPage) is a function returning `Html`.
-- [`Welcome`](views.md#symbol-Welcome) is a function returning `Html`.
+### `Welcome` · [source](views.md#code) {#symbol-Welcome}
 
-### `LoginPage` {#symbol-LoginPage}
+It takes `session` as [`SessionClaims`](contracts.md#symbol-SessionClaims). Failures can raise `HttpError`.
 
-[source](views.md#code)
+It returns the server component [`Page`](../common/views.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.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.
 
-Returns: `Html`.
+### Dependencies
 
-**What it does**
-
-- Return the server component [`Page`](../common/views.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).
-
-### `Welcome` {#symbol-Welcome}
-
-[source](views.md#code)
-
-**Inputs**
-
-- `session` ([`SessionClaims`](contracts.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.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.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.md#symbol-SessionClaims)
-
-Record from `contracts`.
-
-- Read `csrf` (`string`).
-- Read `name` (`string`).
-- Read `sub` (`string`).
-
-#### [`logout`](logout.md#symbol-logout)
-
-Function from `logout`.
-
-- [`logout`](logout.md#symbol-logout) (`input`: [`LogoutForm`](contracts.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`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto), `clock`: [`Clock`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock), `keys`: [`SigningKeys`](../common/keys.md#symbol-SigningKeys), `sessions`: [`ExpiringStore<SessionClaims>`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore); uses [`crypto.publicRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.publicRsa), [`crypto.decodeBase64url`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.decodeBase64url), [`crypto.verifyRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.verifyRsa), [`crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal), [`clock.now`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock.now), [`keys.session`](../common/keys.md#symbol-SigningKeys.session), [`sessions.get`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.get), [`sessions.take`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.take); can fail with `SessionError`, `KeyError`, `TimeError`, `CryptoError`, `HttpError`.
-
-#### [`Page`](../common/views.md#symbol-Page)
-
-Function from `common`.
-
-- [`Page`](../common/views.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.
+It uses [`SessionClaims`](contracts.md#symbol-SessionClaims) (`csrf`, `name`, and `sub`) from `contracts`. It uses [`logout`](logout.md#symbol-logout) from `logout`. It uses [`Page`](../common/views.md#symbol-Page) from `common`.
 
 ::::
 

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

@@ -49,6 +49,7 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// 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
@@ -61,6 +62,7 @@ export withCookie from headers
 ```
 
 ```aug [Braces]
+// 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
@@ -80,35 +82,13 @@ export withCookie from headers
 
 ## Compiled specification {#specification}
 
-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.md#symbol-Settings). Export the declaration `settings` from [`settings.aug`](settings.md#symbol-settings). Export the declaration `SigningKeys` from [`keys.aug`](keys.md#symbol-SigningKeys). Export the declaration `MemorySigningKeys` from [`keys.aug`](keys.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.md#symbol-initializeKeys). Export the declaration `KeyError` from [`keys.aug`](keys.md#symbol-KeyError). Export the declaration `Page` from [`views.aug`](views.md#symbol-Page). Export the declaration `securityHeaders` from [`headers.aug`](headers.md#symbol-securityHeaders).
 
-### Folder exports
-
-- Export the declaration `Settings` from [`settings.aug`](settings.md#symbol-Settings).
-- Export the declaration `settings` from [`settings.aug`](settings.md#symbol-settings).
-- Export the declaration `SigningKeys` from [`keys.aug`](keys.md#symbol-SigningKeys).
-- Export the declaration `MemorySigningKeys` from [`keys.aug`](keys.md#symbol-MemorySigningKeys).
-- Export the declaration `initializeKeys` from [`keys.aug`](keys.md#symbol-initializeKeys).
-- Export the declaration `KeyError` from [`keys.aug`](keys.md#symbol-KeyError).
-- Export the declaration `Page` from [`views.aug`](views.md#symbol-Page).
-- Export the declaration `securityHeaders` from [`headers.aug`](headers.md#symbol-securityHeaders).
-- Export the declaration `withCookie` from [`headers.aug`](headers.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.md#symbol-withCookie).
 
 ::::
 

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

@@ -49,32 +49,58 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// 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:
-    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'")
+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
 ```
 
 ```aug [Braces]
+// 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 {
-    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'")
+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
 ```
 
 :::
@@ -85,77 +111,21 @@ import cookie from august.web
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+### `securityHeaders` · [source](headers.md#code) {#symbol-securityHeaders}
 
-### In this file
+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'"`.
 
-- [`securityHeaders`](headers.md#symbol-securityHeaders) is a function returning `Headers`.
-- [`withCookie`](headers.md#symbol-withCookie) is a function returning `Headers`.
+### `withCookie` · [source](headers.md#code) {#symbol-withCookie}
 
-### `securityHeaders` {#symbol-securityHeaders}
+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`.
 
-[source](headers.md#code)
+It sets `result` to `headers`. For each `content` in a snapshot of `all` on [`cookie`](../dependencies/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.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`.
 
-Returns: `Headers`.
+### Dependencies
 
-Can fail with `HttpError`. Callers must catch or propagate these errors.
+It uses [`cookie`](../dependencies/packages/%40git/url_897efafd565158fc4908/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-cookie) from `web`.
 
-**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.
-
-### `withCookie` {#symbol-withCookie}
-
-[source](headers.md#code)
-
-**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`](../dependencies/august/0.19.0/web/contracts.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`](../dependencies/august/0.19.0/web/contracts.md#symbol-cookie)
-
-Function from `august.web`.
-
-- [`cookie`](../dependencies/august/0.19.0/web/contracts.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.
+Built-in operations follow the [language reference](https://greenpandastudios.github.io/augscript/language-constructs).
 
 ::::