@greenpandastudios/aug-cli 0.19.0 → 0.20.1

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

@@ -1,161 +1,29 @@
 <!-- Generated by aug spec. Edit the August source, then regenerate. -->
 
-# `endpoints.aug` specification
+# `endpoints.aug`
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
-
-## In this file
-
-- [`home`](endpoints.aug.md#symbol-home) handles `GET` `/` returning `HttpResponse<Html>`.
-- [`me`](endpoints.aug.md#symbol-me) handles `GET` `/me` returning `HttpResponse<UserInfo>`.
+Plain handler results default to HTTP 200 unless another status is declared. HttpResponse values choose their own status. Unhandled request failures return HTTP 500 and cancel the request tasks.
 
 <a id="symbol-home"></a>
+## `home` · [source](endpoints.aug#L12)
 
-## `home`
-
-[source](endpoints.aug#L11)
-
-**Inputs**
-
-- `token` (`optional string`) — read from the HTTP cookie named `aug_session`; absent value 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: `HttpResponse<Html>`.
-
-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 `KeyError`, `TimeError`, `HttpError`. Callers must catch or propagate these errors.
+`home` handles `GET /`. The app renders a verified session or offers its OIDC login flow. No token claims are displayed before verification.
 
-HTTP route: `GET` `/`. 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.
+It takes `token` as `optional string` from the HTTP cookie `aug_session`. 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. It can also raise `HttpError`, `KeyError`, and `TimeError`.
 
-**What it does**
-
-- Try these operations:
-  - Set `session` to call [`authenticate`](session.aug.md#symbol-authenticate) with `token` = `token`; inject `crypto` from `crypto`, `clock` from `clock`, `keys` from `keys`, `sessions` from `sessions`.
-  - Return call `HttpResponse` with `body` = call [`Welcome`](views.aug.md#symbol-Welcome) with `session` = `session`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
-- If they fail with [`SessionError`](contracts.aug.md#symbol-SessionError), name the failure `error` and recover:
-  - Return call `HttpResponse` with `body` = call [`LoginPage`](views.aug.md#symbol-LoginPage); `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
-
-**Author documentation**
-
-The app renders a verified session or offers its OIDC login flow. No token claims are displayed before verification.
+It tries to set `session` to [`authenticate`](session.aug.md#symbol-authenticate) with `token` using injected `crypto`, `clock`, `keys`, and `sessions`, then return HTTP 200 with [`Welcome`](views.aug.md#symbol-Welcome) with `session` and [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) headers. If this work raises [`SessionError`](contracts.aug.md#symbol-SessionError), it returns HTTP 200 with [`LoginPage`](views.aug.md#symbol-LoginPage) and [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) headers.
 
 <a id="symbol-me"></a>
+## `me` · [source](endpoints.aug#L20)
 
-## `me`
-
-[source](endpoints.aug#L19)
-
-**Inputs**
-
-- `token` (`optional string`) — read from the HTTP cookie named `aug_session`; absent value 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: `HttpResponse<UserInfo>`.
-
-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`, `HttpError`. Callers must catch or propagate these errors.
-
-HTTP route: `GET` `/me`. 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.aug.md#symbol-SessionError) returns status 401.
-
-**What it does**
-
-- Set `session` to call [`authenticate`](session.aug.md#symbol-authenticate) with `token` = `token`; inject `crypto` from `crypto`, `clock` from `clock`, `keys` from `keys`, `sessions` from `sessions`.
-- Return call `HttpResponse` with `body` = call [`UserInfo`](../provider/contracts.aug.md#symbol-UserInfo) with `sub` = `sub` of `session`; `name` = `name` of `session`; `headers` = call [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders).
-
-**Author documentation**
-
-A protected JSON resource accepts only a live, verified application session.
-
-## Dependencies used by this file
-
-Only referenced types and operations appear here. Each name links to its complete specification.
-
-### [`Crypto`](../.aug-spec/august/0.19.0/crypto/contracts.aug.md#symbol-Crypto)
-
-Capability interface from `august.crypto`.
-
-- [`Crypto.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`.
-
-### [`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 `name` (`string`).
-- Read `sub` (`string`).
-
-### [`SessionError`](contracts.aug.md#symbol-SessionError)
-
-Class from `contracts`.
-
-Used as a type or provider.
-
-### [`authenticate`](session.aug.md#symbol-authenticate)
-
-Function from `session`.
-
-- [`authenticate`](session.aug.md#symbol-authenticate) (`token`: `optional string`) → [`SessionClaims`](contracts.aug.md#symbol-SessionClaims); 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); can fail with `SessionError`, `KeyError`, `TimeError`.
-
-### [`LoginPage`](views.aug.md#symbol-LoginPage)
-
-Function from `views`.
-
-- [`LoginPage`](views.aug.md#symbol-LoginPage) (no caller inputs) → `Html`.
-
-### [`Welcome`](views.aug.md#symbol-Welcome)
-
-Function from `views`.
-
-- [`Welcome`](views.aug.md#symbol-Welcome) (`session`: [`SessionClaims`](contracts.aug.md#symbol-SessionClaims)) → `Html`; can fail with `HttpError`.
-
-### [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders)
-
-Function from `common`.
-
-- [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) (no caller inputs) → `Headers`; can fail with `HttpError`.
-
-### [`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`.
+`me` handles `GET /me`. A protected JSON resource accepts only a live, verified application session.
 
-### [`UserInfo`](../provider/contracts.aug.md#symbol-UserInfo)
+It takes `token` as `optional string` from the HTTP cookie `aug_session`. 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. The handler responds with HTTP 401 for [`SessionError`](contracts.aug.md#symbol-SessionError).
 
-Record from `provider`.
+It can also raise `HttpError`, `KeyError`, and `TimeError`. It sets `session` to [`authenticate`](session.aug.md#symbol-authenticate) with `token` using injected `crypto`, `clock`, `keys`, and `sessions`. It returns HTTP 200 with an [`UserInfo`](../provider/contracts.aug.md#symbol-UserInfo) with `session.sub` and `session.name` and [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders) headers.
 
-- Construct with `sub`: `string`, `name`: `string` → [`UserInfo`](../provider/contracts.aug.md#symbol-UserInfo).
+## Dependencies
 
-## Shared language rules
+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)) 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) (`name` and `sub`) and [`SessionError`](contracts.aug.md#symbol-SessionError) from `contracts`.
 
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+It uses [`authenticate`](session.aug.md#symbol-authenticate) from `session`. It uses [`LoginPage`](views.aug.md#symbol-LoginPage) and [`Welcome`](views.aug.md#symbol-Welcome) from `views`. It uses [`securityHeaders`](../common/headers.aug.md#symbol-securityHeaders), [`KeyError`](../common/keys.aug.md#symbol-KeyError), and [`SigningKeys`](../common/keys.aug.md#symbol-SigningKeys) ([`session`](../common/keys.aug.md#symbol-SigningKeys.session)) from `common`. It uses [`UserInfo`](../provider/contracts.aug.md#symbol-UserInfo) from `provider`.

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

@@ -1,3 +1,4 @@
+// aug-spec: "export.aug.md" explains this file. Read it before changes; refresh with aug spec.
 export LoginTransaction from contracts
 export SessionClaims from contracts
 export home from endpoints

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

@@ -1,29 +1,9 @@
 <!-- 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 `LoginTransaction` from [`contracts.aug`](contracts.aug.md#symbol-LoginTransaction). Export the declaration `SessionClaims` from [`contracts.aug`](contracts.aug.md#symbol-SessionClaims). Export the declaration `home` from [`endpoints.aug`](endpoints.aug.md#symbol-home). Export the declaration `me` from [`endpoints.aug`](endpoints.aug.md#symbol-me).
 
-- Export `LoginTransaction` from this folder.
-- Export `SessionClaims` from this folder.
-- Export `home` from this folder.
-- Export `me` from this folder.
-- Export `logout` from this folder.
-- Export `startLogin` from this folder.
-- Export `loginCallback` from this folder.
-
-## Folder exports
-
-- Export the declaration `LoginTransaction` from [`contracts.aug`](contracts.aug.md#symbol-LoginTransaction).
-- Export the declaration `SessionClaims` from [`contracts.aug`](contracts.aug.md#symbol-SessionClaims).
-- Export the declaration `home` from [`endpoints.aug`](endpoints.aug.md#symbol-home).
-- Export the declaration `me` from [`endpoints.aug`](endpoints.aug.md#symbol-me).
-- Export the declaration `logout` from [`logout.aug`](logout.aug.md#symbol-logout).
-- Export the declaration `startLogin` from [`login.aug`](login.aug.md#symbol-startLogin).
-- Export the declaration `loginCallback` from [`login.aug`](login.aug.md#symbol-loginCallback).
-
-## Shared language rules
-
-See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.
+Export the declaration `logout` from [`logout.aug`](logout.aug.md#symbol-logout). Export the declaration `startLogin` from [`login.aug`](login.aug.md#symbol-startLogin). Export the declaration `loginCallback` from [`login.aug`](login.aug.md#symbol-loginCallback).

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

@@ -1,14 +1,15 @@
+// aug-spec: "login.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import LoginTransaction and SessionClaims and SessionError from contracts
 import discover and responseJson and validateIdentity from protocol
 import TokenResponse and UserInfo from provider
 import settings and SigningKeys and KeyError and securityHeaders and withCookie from common
-import Crypto and RsaJwks and signJwt and JwtError from august.crypto
-import Clock from august.time
-import HttpClient and urlEncode from august.web
-import ExpiringStore and StoreFull from august.memory
+import Crypto and RsaJwks and signJwt and JwtError from crypto
+import Clock from time
+import HttpClient and urlEncode from web
+import ExpiringStore and StoreFull from memory
 
 /** Start a browser-bound, short-lived transaction. The PKCE verifier stays on the server. */
-endpoint GET "/login/start" as startLogin(resolve Crypto crypto, resolve Clock clock, resolve HttpClient client, resolve ExpiringStore<LoginTransaction> transactions) returns HttpResponse<Html> uses crypto.random and crypto.sha256 and clock.now and client.request and transactions.put unless SessionError with status 502 and CryptoError with status 503 and TimeError with status 503 and StoreFull with status 503 and HttpError:
+endpoint GET "/login/start" as startLogin(resolve Crypto crypto, resolve Clock clock, resolve HttpClient client, resolve ExpiringStore<LoginTransaction> transactions) unless SessionError with status 502 and CryptoError with status 503 and TimeError with status 503 and StoreFull with status 503 and HttpError:
     config = settings()
     document = discover()
     browser = crypto.random(size=32).base64url()
@@ -23,7 +24,7 @@ endpoint GET "/login/start" as startLogin(resolve Crypto crypto, resolve Clock c
     return HttpResponse(body=<p>Opening the identity provider.</p>, status=303, headers=headers)
 
 /** Exchange a one-use code over HTTP, verify the provider JWT/JWKS and UserInfo subject, then issue a distinct app-session JWT. */
-endpoint GET "/login/callback" as loginCallback(string code from query, string state from query, optional string browser from cookie "aug_login", resolve Crypto crypto, resolve Clock clock, resolve HttpClient client, resolve SigningKeys keys, resolve ExpiringStore<LoginTransaction> transactions, resolve ExpiringStore<SessionClaims> sessions) returns HttpResponse<Html> uses crypto.equal and crypto.random and crypto.signRsa and crypto.decodeBase64url and crypto.importRsa and crypto.verifyRsa and clock.now and client.request and keys.session and transactions.take and sessions.put unless SessionError with status 400 and CryptoError with status 503 and TimeError with status 503 and KeyError and StoreFull with status 503 and JwtError and JsonError and HttpError:
+endpoint GET "/login/callback" as loginCallback(string code from query, string state from query, optional string browser from cookie "aug_login", resolve Crypto crypto, resolve Clock clock, resolve HttpClient client, resolve SigningKeys keys, resolve ExpiringStore<LoginTransaction> transactions, resolve ExpiringStore<SessionClaims> sessions) unless SessionError with status 400 and CryptoError with status 503 and TimeError with status 503 and KeyError and StoreFull with status 503 and JwtError and JsonError and HttpError:
     if (not code.isToken(min=43, max=43)) or (not state.isToken(min=43, max=43)):
         throw SessionError()
     match browser: