@greenpandastudios/aug-cli 0.19.0

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

@@ -0,0 +1,162 @@
+---
+title: "common/headers.aug · OpenID Connect login application"
+generated: true
+source: "examples/oidc-login/common/headers.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `common/headers.aug`
+
+[OpenID Connect login application](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](../main.md)
+- [`client/contracts.aug`](../client/contracts.md)
+- [`client/endpoints.aug`](../client/endpoints.md)
+- [`client/export.aug`](../client/export.md)
+- [`client/login.aug`](../client/login.md)
+- [`client/logout.aug`](../client/logout.md)
+- [`client/protocol.aug`](../client/protocol.md)
+- [`client/session.aug`](../client/session.md)
+- [`client/views.aug`](../client/views.md)
+- [`common/export.aug`](export.md)
+- [`common/headers.aug`](headers.md)
+- [`common/keys.aug`](keys.md)
+- [`common/settings.aug`](settings.md)
+- [`common/views.aug`](views.md)
+- [`provider/authorization.aug`](../provider/authorization.md)
+- [`provider/contracts.aug`](../provider/contracts.md)
+- [`provider/credentials.aug`](../provider/credentials.md)
+- [`provider/discovery.aug`](../provider/discovery.md)
+- [`provider/export.aug`](../provider/export.md)
+- [`provider/token.aug`](../provider/token.md)
+- [`provider/userinfo.aug`](../provider/userinfo.md)
+- [`provider/views.aug`](../provider/views.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+/** 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
+```
+
+```aug [Braces]
+/** 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
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## 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
+
+- [`securityHeaders`](headers.md#symbol-securityHeaders) is a function returning `Headers`.
+- [`withCookie`](headers.md#symbol-withCookie) is a function returning `Headers`.
+
+### `securityHeaders` {#symbol-securityHeaders}
+
+[source](headers.md#code)
+
+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.
+
+### `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.
+
+::::
+
+:::::

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

@@ -0,0 +1,336 @@
+---
+title: "common/keys.aug · OpenID Connect login application"
+generated: true
+source: "examples/oidc-login/common/keys.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `common/keys.aug`
+
+[OpenID Connect login application](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](../main.md)
+- [`client/contracts.aug`](../client/contracts.md)
+- [`client/endpoints.aug`](../client/endpoints.md)
+- [`client/export.aug`](../client/export.md)
+- [`client/login.aug`](../client/login.md)
+- [`client/logout.aug`](../client/logout.md)
+- [`client/protocol.aug`](../client/protocol.md)
+- [`client/session.aug`](../client/session.md)
+- [`client/views.aug`](../client/views.md)
+- [`common/export.aug`](export.md)
+- [`common/headers.aug`](headers.md)
+- [`common/keys.aug`](keys.md)
+- [`common/settings.aug`](settings.md)
+- [`common/views.aug`](views.md)
+- [`provider/authorization.aug`](../provider/authorization.md)
+- [`provider/contracts.aug`](../provider/contracts.md)
+- [`provider/credentials.aug`](../provider/credentials.md)
+- [`provider/discovery.aug`](../provider/discovery.md)
+- [`provider/export.aug`](../provider/export.md)
+- [`provider/token.aug`](../provider/token.md)
+- [`provider/userinfo.aug`](../provider/userinfo.md)
+- [`provider/views.aug`](../provider/views.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+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)
+```
+
+```aug [Braces]
+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)
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## 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
+
+- [`KeyError`](keys.md#symbol-KeyError) is a class implementing `Error`.
+- [`SigningKeys`](keys.md#symbol-SigningKeys) is a capability interface.
+- [`MemorySigningKeys`](keys.md#symbol-MemorySigningKeys) is a class implementing `SigningKeys`.
+- [`initializeKeys`](keys.md#symbol-initializeKeys) is a function.
+
+### `KeyError` {#symbol-KeyError}
+
+[source](keys.md#code)
+
+Behavioral class.
+
+Satisfies `Error`.
+
+### `SigningKeys` {#symbol-SigningKeys}
+
+[source](keys.md#code)
+
+Capability interface.
+
+**Author documentation**
+
+Keys are initialized explicitly in main and expose distinct provider and session roles.
+
+#### `SigningKeys.configure` {#symbol-SigningKeys.configure}
+
+[source](keys.md#code)
+
+**Inputs**
+
+- `provider` (`RsaPrivateKey`) — required labeled input.
+- `session` (`RsaPrivateKey`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`SigningKeys.configure`](keys.md#symbol-SigningKeys.configure).
+
+Can fail with `KeyError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+#### `SigningKeys.provider` {#symbol-SigningKeys.provider}
+
+[source](keys.md#code)
+
+Returns: `RsaPrivateKey`.
+
+Capabilities: [`SigningKeys.provider`](keys.md#symbol-SigningKeys.provider).
+
+Can fail with `KeyError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+#### `SigningKeys.session` {#symbol-SigningKeys.session}
+
+[source](keys.md#code)
+
+Returns: `RsaPrivateKey`.
+
+Capabilities: [`SigningKeys.session`](keys.md#symbol-SigningKeys.session).
+
+Can fail with `KeyError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+### `MemorySigningKeys` {#symbol-MemorySigningKeys}
+
+[source](keys.md#code)
+
+Behavioral class.
+
+Satisfies [`SigningKeys`](keys.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.
+
+#### `MemorySigningKeys.configure` {#symbol-MemorySigningKeys.configure}
+
+[source](keys.md#code)
+
+**Inputs**
+
+- `provider` (`RsaPrivateKey`) — required labeled input.
+- `session` (`RsaPrivateKey`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`SigningKeys.configure`](keys.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.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`.
+
+#### `MemorySigningKeys.provider` {#symbol-MemorySigningKeys.provider}
+
+[source](keys.md#code)
+
+Returns: `RsaPrivateKey`.
+
+Capabilities: [`SigningKeys.provider`](keys.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.md#symbol-KeyError). Transfer control to a matching catch or propagate the failure.
+    - A present, non-null value, named `key`:
+      - Return `key`.
+
+#### `MemorySigningKeys.session` {#symbol-MemorySigningKeys.session}
+
+[source](keys.md#code)
+
+Returns: `RsaPrivateKey`.
+
+Capabilities: [`SigningKeys.session`](keys.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.md#symbol-KeyError). Transfer control to a matching catch or propagate the failure.
+    - A present, non-null value, named `key`:
+      - Return `key`.
+
+### `initializeKeys` {#symbol-initializeKeys}
+
+[source](keys.md#code)
+
+**Inputs**
+
+- `crypto` ([`Crypto`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto)) — injected; callers omit it.
+- `keys` ([`SigningKeys`](keys.md#symbol-SigningKeys)) — injected; callers omit it.
+
+Returns: no value.
+
+Capabilities: [`crypto.generateRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.generateRsa), [`keys.configure`](keys.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`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.generateRsa) on `crypto`.
+- Set `session` to call [`Crypto.generateRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.generateRsa) on `crypto`.
+- Call [`SigningKeys.configure`](keys.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`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto)
+
+Capability interface from `august.crypto`.
+
+- [`Crypto.generateRsa`](../dependencies/august/0.19.0/crypto/contracts.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/docs/examples/oidc-login/common/settings.md

@@ -0,0 +1,116 @@
+---
+title: "common/settings.aug · OpenID Connect login application"
+generated: true
+source: "examples/oidc-login/common/settings.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `common/settings.aug`
+
+[OpenID Connect login application](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](../main.md)
+- [`client/contracts.aug`](../client/contracts.md)
+- [`client/endpoints.aug`](../client/endpoints.md)
+- [`client/export.aug`](../client/export.md)
+- [`client/login.aug`](../client/login.md)
+- [`client/logout.aug`](../client/logout.md)
+- [`client/protocol.aug`](../client/protocol.md)
+- [`client/session.aug`](../client/session.md)
+- [`client/views.aug`](../client/views.md)
+- [`common/export.aug`](export.md)
+- [`common/headers.aug`](headers.md)
+- [`common/keys.aug`](keys.md)
+- [`common/settings.aug`](settings.md)
+- [`common/views.aug`](views.md)
+- [`provider/authorization.aug`](../provider/authorization.md)
+- [`provider/contracts.aug`](../provider/contracts.md)
+- [`provider/credentials.aug`](../provider/credentials.md)
+- [`provider/discovery.aug`](../provider/discovery.md)
+- [`provider/export.aug`](../provider/export.md)
+- [`provider/token.aug`](../provider/token.md)
+- [`provider/userinfo.aug`](../provider/userinfo.md)
+- [`provider/views.aug`](../provider/views.md)
+
+:::
+
+::::: example-compare
+
+:::: example-code
+
+## Code {#code}
+
+::: code-group
+
+```aug [Indentation]
+/** 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)
+```
+
+```aug [Braces]
+/** 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)
+}
+```
+
+:::
+
+::::
+
+:::: example-spec
+
+## 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
+
+- [`Settings`](settings.md#symbol-Settings) is an immutable record.
+- [`settings`](settings.md#symbol-settings) is a function returning `Settings`.
+
+### `Settings` {#symbol-Settings}
+
+[source](settings.md#code)
+
+Immutable record.
+
+**Author documentation**
+
+Explicit loopback development settings. The provider accepts one registered client and its exact callback URI.
+
+**Inputs**
+
+- `baseUrl` (`string`) — required labeled input — stored as `baseUrl` and read-only after initialization.
+- `issuer` (`string`) — required labeled input — stored as `issuer` and read-only after initialization.
+- `clientId` (`string`) — required labeled input — stored as `clientId` and read-only after initialization.
+- `callback` (`string`) — required labeled input — stored as `callback` and read-only after initialization.
+- `sessionSeconds` (`int`) — required labeled input — stored as `sessionSeconds` and read-only after initialization.
+- `secureCookies` (`bool`) — required labeled input — stored as `secureCookies` and read-only after initialization.
+
+### `settings` {#symbol-settings}
+
+[source](settings.md#code)
+
+Returns: [`Settings`](settings.md#symbol-Settings).
+
+**What it does**
+
+- Return call [`Settings`](settings.md#symbol-Settings) with `baseUrl` = `"http://127.0.0.1:8787"`; `issuer` = `"http://127.0.0.1:8787/provider"`; `clientId` = `"august-login-app"`; `callback` = `"http://127.0.0.1:8787/login/callback"`; `sessionSeconds` = `900`; `secureCookies` = `false`.
+
+### Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+
+::::
+
+:::::