@greenpandastudios/aug-cli 0.19.0

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

@@ -0,0 +1,249 @@
+---
+title: "client/logout.aug · OpenID Connect login application"
+generated: true
+source: "examples/oidc-login/client/logout.aug"
+editLink: false
+prev: false
+next: false
+outline: [2, 3]
+pageClass: aug-example-page
+---
+
+# `client/logout.aug`
+
+[OpenID Connect login application](../index.md) · Source and specification
+
+::: details Files in this project
+
+- [`main.aug`](../main.md)
+- [`client/contracts.aug`](contracts.md)
+- [`client/endpoints.aug`](endpoints.md)
+- [`client/export.aug`](export.md)
+- [`client/login.aug`](login.md)
+- [`client/logout.aug`](logout.md)
+- [`client/protocol.aug`](protocol.md)
+- [`client/session.aug`](session.md)
+- [`client/views.aug`](views.md)
+- [`common/export.aug`](../common/export.md)
+- [`common/headers.aug`](../common/headers.md)
+- [`common/keys.aug`](../common/keys.md)
+- [`common/settings.aug`](../common/settings.md)
+- [`common/views.aug`](../common/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 SessionClaims and SessionError and LogoutForm from contracts
+import authenticate from session
+import settings and SigningKeys and KeyError and securityHeaders and withCookie from common
+import Crypto from august.crypto
+import Clock from august.time
+import ExpiringStore from august.memory
+/** POST logout checks the origin and session-bound CSRF value, then removes the live registry entry before clearing the cookie. */
+endpoint POST "/logout" as logout(LogoutForm input from form, optional string token from cookie "aug_session", optional string origin from header, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) returns HttpResponse<Html> uses crypto.publicRsa and crypto.decodeBase64url and crypto.verifyRsa and crypto.equal and clock.now and keys.session and sessions.get and sessions.take unless SessionError with status 403 and KeyError and TimeError and CryptoError and HttpError:
+    config = settings()
+    if origin != config.baseUrl:
+        throw SessionError()
+    session = authenticate(token)
+    if not crypto.equal(left=input.csrf.bytes(), right=session.csrf.bytes()):
+        throw SessionError()
+    sessions.take(key=session.jti, now=clock.now())
+    headers = withCookie(headers=securityHeaders().with(name="location", value="/"), name="aug_session", value="", path="/", maxAge=0, secure=config.secureCookies)
+    return HttpResponse(body=<p>Signed out.</p>, status=303, headers=headers)
+```
+
+```aug [Braces]
+import SessionClaims and SessionError and LogoutForm from contracts
+import authenticate from session
+import settings and SigningKeys and KeyError and securityHeaders and withCookie from common
+import Crypto from august.crypto
+import Clock from august.time
+import ExpiringStore from august.memory
+/** POST logout checks the origin and session-bound CSRF value, then removes the live registry entry before clearing the cookie. */
+endpoint POST "/logout" as logout(LogoutForm input from form, optional string token from cookie "aug_session", optional string origin from header, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) returns HttpResponse<Html> uses crypto.publicRsa and crypto.decodeBase64url and crypto.verifyRsa and crypto.equal and clock.now and keys.session and sessions.get and sessions.take unless SessionError with status 403 and KeyError and TimeError and CryptoError and HttpError {
+    config = settings()
+    if origin != config.baseUrl {
+        throw SessionError()
+    }
+    session = authenticate(token)
+    if not crypto.equal(left=input.csrf.bytes(), right=session.csrf.bytes()) {
+        throw SessionError()
+    }
+    sessions.take(key=session.jti, now=clock.now())
+    headers = withCookie(headers=securityHeaders().with(name="location", value="/"), name="aug_session", value="", path="/", maxAge=0, secure=config.secureCookies)
+    return HttpResponse(body=<p>Signed out.</p>, status=303, headers=headers)
+}
+```
+
+:::
+
+::::
+
+:::: 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
+
+- [`logout`](logout.md#symbol-logout) handles `POST` `/logout` returning `HttpResponse<Html>`.
+
+### `logout` {#symbol-logout}
+
+[source](logout.md#code)
+
+**Inputs**
+
+- `input` ([`LogoutForm`](contracts.md#symbol-LogoutForm)) — read from the HTTP form.
+- `token` (`optional string`) — read from the HTTP cookie named `aug_session`; absent value becomes null.
+- `origin` (`optional string`) — read from the HTTP header; absent value 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: `HttpResponse<Html>`.
+
+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), [`sessions.take`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.take).
+
+Can fail with `SessionError`, `KeyError`, `TimeError`, `CryptoError`, `HttpError`. Callers must catch or propagate these errors.
+
+HTTP route: `POST` `/logout`. Use status 200 when the handler returns a body; a returned HttpResponse can set its own status. An unhandled request failure returns status 500 and cancels its request tasks.
+
+Declared HTTP failures: [`SessionError`](contracts.md#symbol-SessionError) returns status 403.
+
+**What it does**
+
+- Set `config` to call [`settings`](../common/settings.md#symbol-settings).
+- If `origin` does not equal `baseUrl` of `config`:
+  - Fail with call [`SessionError`](contracts.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+- Set `session` to call [`authenticate`](session.md#symbol-authenticate) with `token` = `token`; inject `crypto` from `crypto`, `clock` from `clock`, `keys` from `keys`, `sessions` from `sessions`.
+- If not (call [`Crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal) on `crypto` with `left` = call `bytes` on `csrf` of `input`; `right` = call `bytes` on `csrf` of `session`):
+  - Fail with call [`SessionError`](contracts.md#symbol-SessionError). Transfer control to a matching catch or propagate the failure.
+- Call [`ExpiringStore.take`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.take) on `sessions` with `key` = `jti` of `session`; `now` = call [`Clock.now`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock.now) on `clock`.
+- Set `headers` to call [`withCookie`](../common/headers.md#symbol-withCookie) with `headers` = call `with` on call [`securityHeaders`](../common/headers.md#symbol-securityHeaders) with `name` = `"location"`; `value` = `"/"`; `name` = `"aug_session"`; `value` = `""`; `path` = `"/"`; `maxAge` = `0`; `secure` = `secureCookies` of `config`.
+- Return call `HttpResponse` with `body` = the HTML element `p` containing `Signed out.` (rendered on the server with embedded text escaped); `status` = `303`; `headers` = `headers`.
+
+**Author documentation**
+
+POST logout checks the origin and session-bound CSRF value, then removes the live registry entry before clearing the cookie.
+
+### 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`.
+
+#### [`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`.
+- [`ExpiringStore.take`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.take) (`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`.
+
+#### [`LogoutForm`](contracts.md#symbol-LogoutForm)
+
+Record from `contracts`.
+
+- Read `csrf` (`string`).
+
+#### [`SessionClaims`](contracts.md#symbol-SessionClaims)
+
+Record from `contracts`.
+
+- Read `csrf` (`string`).
+- Read `jti` (`string`).
+
+#### [`SessionError`](contracts.md#symbol-SessionError)
+
+Class from `contracts`.
+
+- Construct with no caller inputs → [`SessionError`](contracts.md#symbol-SessionError).
+
+#### [`authenticate`](session.md#symbol-authenticate)
+
+Function from `session`.
+
+- [`authenticate`](session.md#symbol-authenticate) (`token`: `optional string`) → [`SessionClaims`](contracts.md#symbol-SessionClaims); 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); can fail with `SessionError`, `KeyError`, `TimeError`.
+
+#### [`securityHeaders`](../common/headers.md#symbol-securityHeaders)
+
+Function from `common`.
+
+- [`securityHeaders`](../common/headers.md#symbol-securityHeaders) (no caller inputs) → `Headers`; can fail with `HttpError`.
+
+#### [`withCookie`](../common/headers.md#symbol-withCookie)
+
+Function from `common`.
+
+- [`withCookie`](../common/headers.md#symbol-withCookie) (`headers`: `Headers`, `name`: `string`, `value`: `string`, `path`: `string`, `maxAge`: `int`, `secure`: `bool`) → `Headers`; can fail with `HttpError`.
+
+#### [`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.
+
+- Read `baseUrl` (`string`).
+- Read `secureCookies` (`bool`).
+
+#### [`settings`](../common/settings.md#symbol-settings)
+
+Function from `common`.
+
+- [`settings`](../common/settings.md#symbol-settings) (no caller inputs) → [`Settings`](../common/settings.md#symbol-Settings).
+
+### Built-in operations used by this file
+
+- `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`.
+- `string.bytes` (no inputs) → `Bytes`: Encode this string as immutable UTF-8 bytes.
+
+[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.
+
+::::
+
+:::::