@greenpandastudios/aug-cli 0.19.0

package/examples/oidc-login/.aug-spec/august/0.19.0/web/contracts.aug.md

@@ -0,0 +1,420 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`Principal`](contracts.aug.md#symbol-Principal) is an immutable record.
+- [`Authentication`](contracts.aug.md#symbol-Authentication) is a capability interface.
+- [`Authorization`](contracts.aug.md#symbol-Authorization) is a capability interface.
+- [`RequestLogger`](contracts.aug.md#symbol-RequestLogger) is a capability interface.
+- [`_aug_http_log`](contracts.aug.md#symbol-_aug_http_log) is a function.
+- [`WebRequestLogger`](contracts.aug.md#symbol-WebRequestLogger) is a class implementing `RequestLogger`.
+- [`HttpClient`](contracts.aug.md#symbol-HttpClient) is a capability interface.
+- [`_aug_http_request`](contracts.aug.md#symbol-_aug_http_request) is a function returning `HttpResponse<Bytes>`.
+- [`WebHttpClient`](contracts.aug.md#symbol-WebHttpClient) is a class implementing `HttpClient`.
+- [`redirect`](contracts.aug.md#symbol-redirect) is a function returning `HttpResponse<string>`.
+- [`_aug_http_url_encode`](contracts.aug.md#symbol-_aug_http_url_encode) is a function returning `string`.
+- [`urlEncode`](contracts.aug.md#symbol-urlEncode) is a function returning `string`.
+- [`_aug_http_cookie`](contracts.aug.md#symbol-_aug_http_cookie) is a function returning `Headers`.
+- [`cookie`](contracts.aug.md#symbol-cookie) is a function returning `Headers`.
+
+<a id="symbol-Principal"></a>
+
+## `Principal`
+
+[source](contracts.aug#L3)
+
+Immutable record.
+
+**Author documentation**
+
+Immutable identity returned by an explicitly injected authentication adapter.
+
+**Inputs**
+
+- `subject` (`string`) — required labeled input — stored as `subject` and read-only after initialization.
+- `permissions` (`List<string>`) — required labeled input — stored as `permissions` and read-only after initialization.
+
+<a id="symbol-Authentication"></a>
+
+## `Authentication`
+
+[source](contracts.aug#L6)
+
+Capability interface.
+
+**Author documentation**
+
+Verify the request's credentials. null means unauthenticated; adapter failures raise HttpError.
+
+<a id="symbol-Authentication.authenticate"></a>
+
+### `Authentication.authenticate`
+
+[source](contracts.aug#L7)
+
+**Inputs**
+
+- `request` (`HttpRequest`) — required labeled input.
+
+Returns: [`optional Principal`](contracts.aug.md#symbol-Principal).
+
+Capabilities: [`Authentication.authenticate`](contracts.aug.md#symbol-Authentication.authenticate).
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-Authorization"></a>
+
+## `Authorization`
+
+[source](contracts.aug#L10)
+
+Capability interface.
+
+**Author documentation**
+
+Decide whether a verified identity has one named permission.
+
+<a id="symbol-Authorization.authorize"></a>
+
+### `Authorization.authorize`
+
+[source](contracts.aug#L11)
+
+**Inputs**
+
+- `identity` ([`Principal`](contracts.aug.md#symbol-Principal)) — required labeled input.
+- `permission` (`string`) — required labeled input.
+
+Returns: `bool`.
+
+Capabilities: [`Authorization.authorize`](contracts.aug.md#symbol-Authorization.authorize).
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-RequestLogger"></a>
+
+## `RequestLogger`
+
+[source](contracts.aug#L14)
+
+Capability interface.
+
+**Author documentation**
+
+Observe a completed HTTP exchange, including failures and disconnects.
+
+<a id="symbol-RequestLogger.complete"></a>
+
+### `RequestLogger.complete`
+
+[source](contracts.aug#L15)
+
+**Inputs**
+
+- `method` (`string`) — required labeled input.
+- `path` (`string`) — required labeled input.
+- `status` (`int`) — required labeled input.
+- `milliseconds` (`int`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`RequestLogger.complete`](contracts.aug.md#symbol-RequestLogger.complete).
+
+Interface contract. A selected implementation supplies the behavior.
+
+<a id="symbol-WebRequestLogger"></a>
+
+## `WebRequestLogger`
+
+[source](contracts.aug#L19)
+
+Behavioral class.
+
+Satisfies [`RequestLogger`](contracts.aug.md#symbol-RequestLogger).
+
+**Author documentation**
+
+Emit escaped JSON request metadata to standard error. Credentials and query strings are excluded.
+
+<a id="symbol-WebRequestLogger.complete"></a>
+
+### `WebRequestLogger.complete`
+
+[source](contracts.aug#L20)
+
+**Inputs**
+
+- `method` (`string`) — required labeled input.
+- `path` (`string`) — required labeled input.
+- `status` (`int`) — required labeled input.
+- `milliseconds` (`int`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`RequestLogger.complete`](contracts.aug.md#symbol-RequestLogger.complete).
+
+**What it does**
+
+- Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:
+  - Call [`_aug_http_log`](contracts.aug.md#symbol-_aug_http_log) with `method` = `method`; `path` = `path`; `status` = `status`; `milliseconds` = `milliseconds`.
+
+<a id="symbol-HttpClient"></a>
+
+## `HttpClient`
+
+[source](contracts.aug#L25)
+
+Capability interface.
+
+**Author documentation**
+
+An explicit outbound network capability. TLS verifies the peer and redirects are returned to the caller.
+
+<a id="symbol-HttpClient.request"></a>
+
+### `HttpClient.request`
+
+[source](contracts.aug#L27)
+
+**Inputs**
+
+- `method` (`string`) — required labeled input.
+- `url` (`string`) — required labeled input.
+- `headers` (`optional Headers`) — optional labeled input; omission becomes null.
+- `body` (`optional Bytes`) — optional labeled input; omission becomes null.
+
+Returns: `HttpResponse<Bytes>`.
+
+Capabilities: [`HttpClient.request`](contracts.aug.md#symbol-HttpClient.request).
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+Interface contract. A selected implementation supplies the behavior.
+
+**Author documentation**
+
+Perform an HTTP request with bounded bytes. Inside a task, waiting suspends the task's C stack.
+
+<a id="symbol-WebHttpClient"></a>
+
+## `WebHttpClient`
+
+[source](contracts.aug#L32)
+
+Behavioral class.
+
+Satisfies [`HttpClient`](contracts.aug.md#symbol-HttpClient).
+
+**Author documentation**
+
+Native libwebsockets transport. No socket is opened by construction.
+
+<a id="symbol-WebHttpClient.request"></a>
+
+### `WebHttpClient.request`
+
+[source](contracts.aug#L33)
+
+**Inputs**
+
+- `method` (`string`) — required labeled input.
+- `url` (`string`) — required labeled input.
+- `headers` (`optional Headers`) — optional labeled input; omission becomes null.
+- `body` (`optional Bytes`) — optional labeled input; omission becomes null.
+
+Returns: `HttpResponse<Bytes>`.
+
+Capabilities: [`HttpClient.request`](contracts.aug.md#symbol-HttpClient.request).
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:
+  - Return call [`_aug_http_request`](contracts.aug.md#symbol-_aug_http_request) with `method` = `method`; `url` = `url`; `headers` = `headers`; `body` = `body`.
+
+**Author documentation**
+
+Perform an HTTP request with bounded bytes. Inside a task, waiting suspends the task's C stack.
+
+<a id="symbol-redirect"></a>
+
+## `redirect`
+
+[source](contracts.aug#L38)
+
+**Inputs**
+
+- `location` (`string`) — required labeled input.
+- `status` (`optional int`) — optional labeled input; omission becomes null.
+
+Returns: `HttpResponse<string>`.
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Set `code` to `303`.
+- Select the matching case for `status`:
+  - A null value, including omitted optional input:
+    - Continue without another operation.
+  - A present, non-null value, named `value`:
+    - Set `code` to `value`.
+- Set `headers` to call `with` on call `Headers` with `name` = `"location"`; `value` = `location`.
+- Return call `HttpResponse` with `body` = `""`; `status` = `code`; `headers` = `headers`.
+
+**Author documentation**
+
+Return a redirect with an explicit status. Location is checked as a header value.
+
+<a id="symbol-urlEncode"></a>
+
+## `urlEncode`
+
+[source](contracts.aug#L50)
+
+**Inputs**
+
+- `input` (`string`) — required labeled input.
+
+Returns: `string`.
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+**What it does**
+
+- Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:
+  - Return call [`_aug_http_url_encode`](contracts.aug.md#symbol-_aug_http_url_encode) with `input` = `input`.
+
+**Author documentation**
+
+Encode a UTF-8 value as one URL query or form component using RFC 3986 unreserved characters.
+
+<a id="symbol-cookie"></a>
+
+## `cookie`
+
+[source](contracts.aug#L56)
+
+**Inputs**
+
+- `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**
+
+- Enter an unsafe boundary. Native calls use their declared contracts; their foreign implementation is outside this specification:
+  - Return call [`_aug_http_cookie`](contracts.aug.md#symbol-_aug_http_cookie) with `name` = `name`; `value` = `value`; `path` = `path`; `maxAge` = `maxAge`; `secure` = `secure`.
+
+**Author documentation**
+
+Construct an HttpOnly, SameSite=Lax session cookie. Secure defaults are chosen explicitly at the call site. Values and paths reject delimiters and controls. maxAge=0 clears the cookie.
+
+<a id="symbol-_aug_http_log"></a>
+
+## `_aug_http_log`
+
+[source](contracts.aug#L17)
+
+Private to its defining scope.
+
+**Inputs**
+
+- `method` (`string`) — required labeled input.
+- `path` (`string`) — required labeled input.
+- `status` (`int`) — required labeled input.
+- `milliseconds` (`int`) — required labeled input.
+
+Returns: no value.
+
+Capabilities: [`RequestLogger.complete`](contracts.aug.md#symbol-RequestLogger.complete).
+
+Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.
+
+<a id="symbol-_aug_http_request"></a>
+
+## `_aug_http_request`
+
+[source](contracts.aug#L29)
+
+Private to its defining scope.
+
+**Inputs**
+
+- `method` (`string`) — required labeled input.
+- `url` (`string`) — required labeled input.
+- `headers` (`optional Headers`) — optional labeled input; omission becomes null.
+- `body` (`optional Bytes`) — optional labeled input; omission becomes null.
+
+Returns: `HttpResponse<Bytes>`.
+
+Capabilities: [`HttpClient.request`](contracts.aug.md#symbol-HttpClient.request).
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.
+
+<a id="symbol-_aug_http_url_encode"></a>
+
+## `_aug_http_url_encode`
+
+[source](contracts.aug#L48)
+
+Private to its defining scope.
+
+**Inputs**
+
+- `input` (`string`) — required labeled input.
+
+Returns: `string`.
+
+Can fail with `HttpError`. Callers must catch or propagate these errors.
+
+Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.
+
+<a id="symbol-_aug_http_cookie"></a>
+
+## `_aug_http_cookie`
+
+[source](contracts.aug#L54)
+
+Private to its defining scope.
+
+**Inputs**
+
+- `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.
+
+Native C operation. Its declared inputs, result, effects, and errors are the visible contract. The C implementation is outside this specification.
+
+## 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`.
+
+[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/examples/oidc-login/.aug-spec/manifest.json

@@ -0,0 +1,40 @@
+{
+  "format": 1,
+  "files": [
+    ".aug-spec/august/0.19.0/crypto/contracts.aug",
+    ".aug-spec/august/0.19.0/crypto/contracts.aug.md",
+    ".aug-spec/august/0.19.0/crypto/jose.aug",
+    ".aug-spec/august/0.19.0/crypto/jose.aug.md",
+    ".aug-spec/august/0.19.0/json/contracts.aug",
+    ".aug-spec/august/0.19.0/json/contracts.aug.md",
+    ".aug-spec/august/0.19.0/memory/store.aug",
+    ".aug-spec/august/0.19.0/memory/store.aug.md",
+    ".aug-spec/august/0.19.0/time/contracts.aug",
+    ".aug-spec/august/0.19.0/time/contracts.aug.md",
+    ".aug-spec/august/0.19.0/web/contracts.aug",
+    ".aug-spec/august/0.19.0/web/contracts.aug.md",
+    "client/contracts.aug.md",
+    "client/endpoints.aug.md",
+    "client/export.aug.md",
+    "client/login.aug.md",
+    "client/logout.aug.md",
+    "client/protocol.aug.md",
+    "client/session.aug.md",
+    "client/views.aug.md",
+    "common/export.aug.md",
+    "common/headers.aug.md",
+    "common/keys.aug.md",
+    "common/settings.aug.md",
+    "common/views.aug.md",
+    "main.aug.md",
+    "provider/authorization.aug.md",
+    "provider/contracts.aug.md",
+    "provider/credentials.aug.md",
+    "provider/discovery.aug.md",
+    "provider/export.aug.md",
+    "provider/token.aug.md",
+    "provider/userinfo.aug.md",
+    "provider/views.aug.md"
+  ],
+  "digest": "21ab7e44109d4b6f126220d3aece959d724d2d71cf1e07dd5aa214f18e87e2fd"
+}

package/examples/oidc-login/README.md

@@ -0,0 +1,29 @@
+# Same-app OpenID Connect login
+
+The provider and its client are August modules in one native executable. The client uses the real discovery, token, JWKS and UserInfo HTTP endpoints hosted by that executable.
+
+```sh
+node scripts/bootstrap-native.mjs
+node bin/aug.mjs run examples/oidc-login
+```
+
+Open `http://127.0.0.1:8787`. Sign in with username **ada** and password **august-demo**. API contracts and an interactive explorer are at `/openapi.json` and `/docs`.
+
+## Flow
+
+1. `/login/start` fetches discovery and creates a browser-bound transaction with random state, nonce and PKCE verifier.
+2. `/provider/authorize` checks the registered client, exact callback and S256 challenge, then renders an August login component.
+3. `/provider/login` checks the browser cookie, Origin, CSRF token and PBKDF2 password verifier before issuing a short-lived authorization code.
+4. `/login/callback` consumes its transaction and exchanges that code over HTTP. `/provider/token` consumes the code and checks PKCE, expiry and client/redirect binding.
+5. The client fetches JWKS, verifies the RS256 ID token, validates issuer/audience/time/nonce, and checks the UserInfo subject. It then creates a separately signed application-session JWT.
+6. `/me` verifies the session JWT and its live registry entry. POST `/logout` checks Origin and CSRF and revokes that entry.
+
+All imports, bindings, capabilities, effects and checked errors are visible in the August modules. Native code supplies transport, cryptographic primitives, time and serialization.
+
+## Development profile
+
+This example explicitly binds to loopback HTTP. Its one documented demo account, signing keys and bounded stores are process-local. Restarting invalidates codes and sessions. External deployments need HTTPS settings, Secure cookies, persistent account/password management, signing-key rotation and shared revocation storage. This is an implemented authorization-code profile, not a certified identity provider.
+
+Protocol rules are grounded in [OpenID Connect Core](https://openid.net/specs/openid-connect-core-1_0.html#IDTokenValidation), [S256 PKCE](https://datatracker.ietf.org/doc/html/rfc7636) and [JWT validation guidance](https://www.rfc-editor.org/rfc/rfc8725.html). The current client accepts the configured single-audience RS256 profile; broader providers need additional supported claim and JOSE variants.
+
+`tests/oidc-login.test.mjs` runs the browser flow, verifies the provider signature with Node's independent JWK/RSA implementation, and checks replay, PKCE, tampering, token-context separation and revocation. See `docs/web-library-gaps.md` for remaining language and library work.

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

@@ -0,0 +1,7 @@
+/** Browser-bound client state, nonce and PKCE verifier, consumed by the callback. */
+record LoginTransaction(string state, string nonce, string verifier, int expires)
+/** Sessions require their own issuer, audience, key and JWT type, plus a live registry entry. */
+record SessionClaims(string iss, string sub, string aud, int exp, int iat, string jti, string csrf, string name)
+record LogoutForm(string csrf)
+SessionError() implements Error:
+    pass

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

@@ -0,0 +1,80 @@
+<!-- Generated by aug spec. Edit the August source, then regenerate. -->
+
+# `contracts.aug` specification
+
+August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+
+## In this file
+
+- [`LoginTransaction`](contracts.aug.md#symbol-LoginTransaction) is an immutable record.
+- [`SessionClaims`](contracts.aug.md#symbol-SessionClaims) is an immutable record.
+- [`LogoutForm`](contracts.aug.md#symbol-LogoutForm) is an immutable record.
+- [`SessionError`](contracts.aug.md#symbol-SessionError) is a class implementing `Error`.
+
+<a id="symbol-LoginTransaction"></a>
+
+## `LoginTransaction`
+
+[source](contracts.aug#L2)
+
+Immutable record.
+
+**Author documentation**
+
+Browser-bound client state, nonce and PKCE verifier, consumed by the callback.
+
+**Inputs**
+
+- `state` (`string`) — required labeled input — stored as `state` and read-only after initialization.
+- `nonce` (`string`) — required labeled input — stored as `nonce` and read-only after initialization.
+- `verifier` (`string`) — required labeled input — stored as `verifier` and read-only after initialization.
+- `expires` (`int`) — required labeled input — stored as `expires` and read-only after initialization.
+
+<a id="symbol-SessionClaims"></a>
+
+## `SessionClaims`
+
+[source](contracts.aug#L4)
+
+Immutable record.
+
+**Author documentation**
+
+Sessions require their own issuer, audience, key and JWT type, plus a live registry entry.
+
+**Inputs**
+
+- `iss` (`string`) — required labeled input — stored as `iss` and read-only after initialization.
+- `sub` (`string`) — required labeled input — stored as `sub` and read-only after initialization.
+- `aud` (`string`) — required labeled input — stored as `aud` and read-only after initialization.
+- `exp` (`int`) — required labeled input — stored as `exp` and read-only after initialization.
+- `iat` (`int`) — required labeled input — stored as `iat` and read-only after initialization.
+- `jti` (`string`) — required labeled input — stored as `jti` and read-only after initialization.
+- `csrf` (`string`) — required labeled input — stored as `csrf` and read-only after initialization.
+- `name` (`string`) — required labeled input — stored as `name` and read-only after initialization.
+
+<a id="symbol-LogoutForm"></a>
+
+## `LogoutForm`
+
+[source](contracts.aug#L5)
+
+Immutable record.
+
+**Inputs**
+
+- `csrf` (`string`) — required labeled input — stored as `csrf` and read-only after initialization.
+
+<a id="symbol-SessionError"></a>
+
+## `SessionError`
+
+[source](contracts.aug#L6)
+
+Behavioral class.
+
+Satisfies `Error`.
+
+## Shared language rules
+
+See the [language reference](https://greenpandastudios.github.io/augscript/reference) for numeric, equality, ownership, and task rules.

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

@@ -0,0 +1,21 @@
+import SessionClaims and SessionError from contracts
+import authenticate from session
+import LoginPage and Welcome from views
+import UserInfo from provider
+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
+
+/** The app renders a verified session or offers its OIDC login flow. No token claims are displayed before verification. */
+endpoint GET "/" as home(optional string token from cookie "aug_session", 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 unless KeyError and TimeError and HttpError:
+    try:
+        session = authenticate(token)
+        return HttpResponse(body=Welcome(session), headers=securityHeaders())
+    catch SessionError error:
+        return HttpResponse(body=LoginPage(), headers=securityHeaders())
+
+/** A protected JSON resource accepts only a live, verified application session. */
+endpoint GET "/me" as me(optional string token from cookie "aug_session", resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<SessionClaims> sessions) returns HttpResponse<UserInfo> uses crypto.publicRsa and crypto.decodeBase64url and crypto.verifyRsa and crypto.equal and clock.now and keys.session and sessions.get unless SessionError with status 401 and KeyError and TimeError and HttpError:
+    session = authenticate(token)
+    return HttpResponse(body=UserInfo(sub=session.sub, name=session.name), headers=securityHeaders())