@greenpandastudios/aug-cli 0.19.0 → 0.21.0

package/docs/examples/oidc-login/provider/token.md

@@ -49,88 +49,196 @@ pageClass: aug-example-page
 ::: code-group
 
 ```aug [Indentation]
+// aug-spec: "token.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import AuthorizationCode and AccessGrant and TokenForm and TokenResponse and OAuthError and IdClaims from contracts
 import settings and SigningKeys and KeyError and securityHeaders from common
-import Crypto and signJwt and JwtError from august.crypto
-import Clock from august.time
-import ExpiringStore and StoreFull from august.memory
-_oauthError(string code, string description) returns HttpResponse<Json> unless HttpError:
-    return HttpResponse(body=Json(value=OAuthError(error=code, error_description=description)), status=400, headers=securityHeaders())
+import Crypto and signJwt and JwtError from crypto
+import Clock from time
+import ExpiringStore and StoreFull from memory
+_oauthError(string code, string description):
+    return HttpResponse(
+        body=Json(value=OAuthError(error=code, error_description=description)),
+        status=400,
+        headers=securityHeaders()
+    )
 /** A real OAuth token endpoint. Exact client/redirect binding, S256 PKCE, expiry and one-use codes are enforced. Errors use OAuth JSON. */
-endpoint POST "/provider/token" as token(HttpRequest http from request, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<AuthorizationCode> codes, resolve ExpiringStore<AccessGrant> access) returns HttpResponse<Json> uses crypto.sha256 and crypto.equal and crypto.random and crypto.signRsa and clock.now and keys.provider and codes.take and access.put unless CryptoError with status 503 and TimeError with status 503 and KeyError and JwtError and StoreFull with status 503 and HttpError:
+endpoint POST "/provider/token" as token(HttpRequest http from request, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<AuthorizationCode> codes, resolve ExpiringStore<AccessGrant> access) unless CryptoError with status 503 and TimeError with status 503 and KeyError and JwtError and StoreFull with status 503 and HttpError:
     config = settings()
     try:
         form = http.form<TokenForm>()
         if form.grant_type != "authorization_code":
-            return _oauthError(code="unsupported_grant_type", description="Only authorization_code is supported.")
+            return _oauthError(
+                code="unsupported_grant_type",
+                description="Only authorization_code is supported."
+            )
         if form.client_id != config.clientId:
-            return _oauthError(code="invalid_client", description="The registered client is required.")
+            return _oauthError(
+                code="invalid_client",
+                description="The registered client is required."
+            )
         if not form.code.isToken(min=43, max=43) or not form.code_verifier.isToken(min=43, max=128):
-            return _oauthError(code="invalid_grant", description="The authorization grant is invalid.")
+            return _oauthError(
+                code="invalid_grant",
+                description="The authorization grant is invalid."
+            )
         now = clock.now()
         match codes.take(key=form.code, now=now):
             when null:
-                return _oauthError(code="invalid_grant", description="The authorization grant is invalid.")
+                return _oauthError(
+                    code="invalid_grant",
+                    description="The authorization grant is invalid."
+                )
             when some grant:
                 challenge = crypto.sha256(input=form.code_verifier.bytes()).base64url()
-                if grant.clientId != form.client_id or grant.redirectUri != form.redirect_uri or not crypto.equal(left=challenge.bytes(), right=grant.challenge.bytes()):
-                    return _oauthError(code="invalid_grant", description="The authorization grant is invalid.")
-                claims = IdClaims(iss=config.issuer, sub=grant.subject, aud=grant.clientId, exp=now + 300, iat=now, nonce=grant.nonce, name=grant.name)
-                idToken = signJwt(key=keys.provider(), claims=Json(value=claims), kid="provider-1", tokenType="JWT")
+                if grant.clientId != form.client_id or grant.redirectUri != form.redirect_uri or not crypto.equal(
+                    left=challenge.bytes(),
+                    right=grant.challenge.bytes()
+                ):
+                    return _oauthError(
+                        code="invalid_grant",
+                        description="The authorization grant is invalid."
+                    )
+                claims = IdClaims(
+                    iss=config.issuer,
+                    sub=grant.subject,
+                    aud=grant.clientId,
+                    exp=now + 300,
+                    iat=now,
+                    nonce=grant.nonce,
+                    name=grant.name
+                )
+                idToken = signJwt(
+                    key=keys.provider(),
+                    claims=Json(value=claims),
+                    kid="provider-1",
+                    tokenType="JWT"
+                )
                 accessToken = crypto.random(size=32).base64url()
-                value = AccessGrant(subject=grant.subject, name=grant.name, expires=now + 300)
-                access.put(key=accessToken, value=value, expires=value.expires, now=now)
-                body = TokenResponse(token_type="Bearer", access_token=accessToken, id_token=idToken, expires_in=300, scope="openid profile")
+                value = AccessGrant(
+                    subject=grant.subject,
+                    name=grant.name,
+                    expires=now + 300
+                )
+                access.put(
+                    key=accessToken,
+                    value=value,
+                    expires=value.expires,
+                    now=now
+                )
+                body = TokenResponse(
+                    token_type="Bearer",
+                    access_token=accessToken,
+                    id_token=idToken,
+                    expires_in=300,
+                    scope="openid profile"
+                )
                 return HttpResponse(body=Json(value=body), headers=securityHeaders())
     catch HttpError error:
-        return _oauthError(code="invalid_request", description="Submit the required URL-encoded token fields once each.")
+        return _oauthError(
+            code="invalid_request",
+            description="Submit the required URL-encoded token fields once each."
+        )
 ```
 
 ```aug [Braces]
+// aug-spec: "token.aug.md" explains this file. Read it before changes; refresh with aug spec.
 import AuthorizationCode and AccessGrant and TokenForm and TokenResponse and OAuthError and IdClaims from contracts
 import settings and SigningKeys and KeyError and securityHeaders from common
-import Crypto and signJwt and JwtError from august.crypto
-import Clock from august.time
-import ExpiringStore and StoreFull from august.memory
-_oauthError(string code, string description) returns HttpResponse<Json> unless HttpError {
-    return HttpResponse(body=Json(value=OAuthError(error=code, error_description=description)), status=400, headers=securityHeaders())
+import Crypto and signJwt and JwtError from crypto
+import Clock from time
+import ExpiringStore and StoreFull from memory
+_oauthError(string code, string description) {
+    return HttpResponse(
+        body=Json(value=OAuthError(error=code, error_description=description)),
+        status=400,
+        headers=securityHeaders()
+    )
 }
 /** A real OAuth token endpoint. Exact client/redirect binding, S256 PKCE, expiry and one-use codes are enforced. Errors use OAuth JSON. */
-endpoint POST "/provider/token" as token(HttpRequest http from request, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<AuthorizationCode> codes, resolve ExpiringStore<AccessGrant> access) returns HttpResponse<Json> uses crypto.sha256 and crypto.equal and crypto.random and crypto.signRsa and clock.now and keys.provider and codes.take and access.put unless CryptoError with status 503 and TimeError with status 503 and KeyError and JwtError and StoreFull with status 503 and HttpError {
+endpoint POST "/provider/token" as token(HttpRequest http from request, resolve Crypto crypto, resolve Clock clock, resolve SigningKeys keys, resolve ExpiringStore<AuthorizationCode> codes, resolve ExpiringStore<AccessGrant> access) unless CryptoError with status 503 and TimeError with status 503 and KeyError and JwtError and StoreFull with status 503 and HttpError {
     config = settings()
     try {
         form = http.form<TokenForm>()
         if form.grant_type != "authorization_code" {
-            return _oauthError(code="unsupported_grant_type", description="Only authorization_code is supported.")
+            return _oauthError(
+                code="unsupported_grant_type",
+                description="Only authorization_code is supported."
+            )
         }
         if form.client_id != config.clientId {
-            return _oauthError(code="invalid_client", description="The registered client is required.")
+            return _oauthError(
+                code="invalid_client",
+                description="The registered client is required."
+            )
         }
         if not form.code.isToken(min=43, max=43) or not form.code_verifier.isToken(min=43, max=128) {
-            return _oauthError(code="invalid_grant", description="The authorization grant is invalid.")
+            return _oauthError(
+                code="invalid_grant",
+                description="The authorization grant is invalid."
+            )
         }
         now = clock.now()
         match codes.take(key=form.code, now=now) {
             when null {
-                return _oauthError(code="invalid_grant", description="The authorization grant is invalid.")
+                return _oauthError(
+                    code="invalid_grant",
+                    description="The authorization grant is invalid."
+                )
             }
             when some grant {
                 challenge = crypto.sha256(input=form.code_verifier.bytes()).base64url()
-                if grant.clientId != form.client_id or grant.redirectUri != form.redirect_uri or not crypto.equal(left=challenge.bytes(), right=grant.challenge.bytes()) {
-                    return _oauthError(code="invalid_grant", description="The authorization grant is invalid.")
+                if grant.clientId != form.client_id or grant.redirectUri != form.redirect_uri or not crypto.equal(
+                    left=challenge.bytes(),
+                    right=grant.challenge.bytes()
+                ) {
+                    return _oauthError(
+                        code="invalid_grant",
+                        description="The authorization grant is invalid."
+                    )
                 }
-                claims = IdClaims(iss=config.issuer, sub=grant.subject, aud=grant.clientId, exp=now + 300, iat=now, nonce=grant.nonce, name=grant.name)
-                idToken = signJwt(key=keys.provider(), claims=Json(value=claims), kid="provider-1", tokenType="JWT")
+                claims = IdClaims(
+                    iss=config.issuer,
+                    sub=grant.subject,
+                    aud=grant.clientId,
+                    exp=now + 300,
+                    iat=now,
+                    nonce=grant.nonce,
+                    name=grant.name
+                )
+                idToken = signJwt(
+                    key=keys.provider(),
+                    claims=Json(value=claims),
+                    kid="provider-1",
+                    tokenType="JWT"
+                )
                 accessToken = crypto.random(size=32).base64url()
-                value = AccessGrant(subject=grant.subject, name=grant.name, expires=now + 300)
-                access.put(key=accessToken, value=value, expires=value.expires, now=now)
-                body = TokenResponse(token_type="Bearer", access_token=accessToken, id_token=idToken, expires_in=300, scope="openid profile")
+                value = AccessGrant(
+                    subject=grant.subject,
+                    name=grant.name,
+                    expires=now + 300
+                )
+                access.put(
+                    key=accessToken,
+                    value=value,
+                    expires=value.expires,
+                    now=now
+                )
+                body = TokenResponse(
+                    token_type="Bearer",
+                    access_token=accessToken,
+                    id_token=idToken,
+                    expires_in=300,
+                    scope="openid profile"
+                )
                 return HttpResponse(body=Json(value=body), headers=securityHeaders())
             }
         }
     }
     catch HttpError error {
-        return _oauthError(code="invalid_request", description="Submit the required URL-encoded token fields once each.")
+        return _oauthError(
+            code="invalid_request",
+            description="Submit the required URL-encoded token fields once each."
+        )
     }
 }
 ```
@@ -143,221 +251,35 @@ endpoint POST "/provider/token" as token(HttpRequest http from request, resolve
 
 ## Compiled specification {#specification}
 
-August 0.19.0. This document is compiled from checked code with deterministic wording guided by Simplified Technical English.
+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.
 
-### In this file
+### `token` · [source](token.md#code) {#symbol-token}
 
-- [`_oauthError`](token.md#symbol-_oauthError) is a function returning `HttpResponse<Json>`.
-- [`token`](token.md#symbol-token) handles `POST` `/provider/token` returning `HttpResponse<Json>`.
+`token` handles `POST /provider/token`. A real OAuth token endpoint. Exact client/redirect binding, S256 PKCE, expiry and one-use codes are enforced. Errors use OAuth JSON.
 
-### `token` {#symbol-token}
+It takes `http` as `HttpRequest` from the HTTP request. 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)), `codes` ([`ExpiringStore<AuthorizationCode>`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore)), and `access` ([`ExpiringStore<AccessGrant>`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore)) from dependency injection. The handler responds with HTTP 503 for `CryptoError`, HTTP 503 for `TimeError`, and HTTP 503 for [`StoreFull`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-StoreFull). It can also raise `HttpError`, `JwtError`, and `KeyError`.
 
-[source](token.md#code)
+It gets `config` from [`settings`](../common/settings.md#symbol-settings). It sets `form` to `http.form` for [`TokenForm`](contracts.md#symbol-TokenForm). If `form.grant_type` does not equal `"authorization_code"`, it returns [`_oauthError`](token.md#symbol-_oauthError) with `code` `"unsupported_grant_type"` and `description` `"Only authorization_code is supported."`. If `form.client_id` does not equal `config.clientId`, it returns [`_oauthError`](token.md#symbol-_oauthError) with `code` `"invalid_client"` and `description` `"The registered client is required."`.
 
-**Inputs**
+If `form.code` is not a URL-safe ASCII token with `43` to `43` characters or `form.code_verifier` is not a URL-safe ASCII token with `43` to `128` characters, it returns [`_oauthError`](token.md#symbol-_oauthError) with `code` `"invalid_grant"` and `description` `"The authorization grant is invalid."`. It sets `now` to [`clock.now`](../dependencies/packages/%40git/url_c092cd151499c4e1d8a1/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/contracts.md#symbol-Clock.now). It obtains [`codes.take`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore.take) with `key` from `form.code` and `now`. If no value is found, it returns [`_oauthError`](token.md#symbol-_oauthError) with `code` `"invalid_grant"` and `description` `"The authorization grant is invalid."`.
 
-- `http` (`HttpRequest`) — read from the HTTP request.
-- `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.
-- `codes` ([`ExpiringStore<AuthorizationCode>`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore)) — injected; callers omit it.
-- `access` ([`ExpiringStore<AccessGrant>`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore)) — injected; callers omit it.
+The non-null result becomes `grant`. It sets `challenge` to the URL-safe base64 encoding of [`crypto.sha256`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.sha256) with `input` from the UTF-8 bytes of `form.code_verifier`. If `grant.clientId` does not equal `form.client_id` or `grant.redirectUri` does not equal `form.redirect_uri` or [`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 `challenge` and `right` from the UTF-8 bytes of `grant.challenge` returns false, it returns [`_oauthError`](token.md#symbol-_oauthError) with `code` `"invalid_grant"` and `description` `"The authorization grant is invalid."`. It sets `claims` to an [`IdClaims`](contracts.md#symbol-IdClaims) with `iss` from `config.issuer`, `sub` from `grant.subject`, `aud` from `grant.clientId`, `exp` from `now` plus `300`, `iat` from `now`, `grant.nonce`, and `grant.name`.
 
-Returns: `HttpResponse<Json>`.
+It sets `idToken` to [`signJwt`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-signJwt) with `key` from [`keys.provider`](../common/keys.md#symbol-SigningKeys.provider), `claims` from a `Json` with `value` from `claims`, `kid` `"provider-1"`, and `tokenType` `"JWT"` using injected `crypto`. It sets `accessToken` to the URL-safe base64 encoding of [`crypto.random`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.random) with `size` `32`. It sets `value` to an [`AccessGrant`](contracts.md#symbol-AccessGrant) with `grant.subject`, `grant.name`, and `expires` from `now` plus `300`. It calls [`access.put`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore.put) with `key` from `accessToken`, `value`, `value.expires`, and `now`.
 
-Capabilities: [`crypto.sha256`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.sha256), [`crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal), [`crypto.random`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.random), [`crypto.signRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.signRsa), [`clock.now`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock.now), [`keys.provider`](../common/keys.md#symbol-SigningKeys.provider), [`codes.take`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.take), [`access.put`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.put).
+It sets `body` to a [`TokenResponse`](contracts.md#symbol-TokenResponse) with `token_type` `"Bearer"`, `access_token` from `accessToken`, `id_token` from `idToken`, `expires_in` `300`, and `scope` `"openid profile"`. It returns HTTP 200 with a `Json` with `value` from `body` and [`securityHeaders`](../common/headers.md#symbol-securityHeaders) headers. If this work raises `HttpError`, it returns [`_oauthError`](token.md#symbol-_oauthError) with `code` `"invalid_request"` and `description` `"Submit the required URL-encoded token fields once each."`.
 
-Can fail with `CryptoError`, `TimeError`, `KeyError`, `JwtError`, `StoreFull`, `HttpError`. Callers must catch or propagate these errors.
+### `_oauthError` · [source](token.md#code) {#symbol-_oauthError}
 
-HTTP route: `POST` `/provider/token`. 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 is private to its defining scope. It takes `code` and `description` as strings. Failures can raise `HttpError`. It returns HTTP 400 with a `Json` with `value` from an [`OAuthError`](contracts.md#symbol-OAuthError) with `error` from `code` and `error_description` from `description` and [`securityHeaders`](../common/headers.md#symbol-securityHeaders) headers.
 
-Declared HTTP failures: `CryptoError` returns status 503; `TimeError` returns status 503; [`StoreFull`](../dependencies/august/0.19.0/memory/store.md#symbol-StoreFull) returns status 503.
+### Dependencies
 
-**What it does**
+It uses [`ExpiringStore`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore) ([`put`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore.put) and [`take`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-ExpiringStore.take)) and [`StoreFull`](../dependencies/packages/%40git/url_0eb7c89453c87681ed15/0.0.0-git.a39fc582565d4fca40be4f75fa304d71adc69301/store.md#symbol-StoreFull) from `memory`. It uses [`Crypto`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto) ([`equal`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.equal), [`random`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.random), [`sha256`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.sha256), and [`signRsa`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/contracts.md#symbol-Crypto.signRsa)), [`JwtError`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-JwtError), and [`signJwt`](../dependencies/packages/%40git/url_9ef654c66d34ab8f5527/0.0.0-git.b14a0f9aa41f1ce58bd51133bcdc424033e40d40/jose.md#symbol-signJwt) 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 [`securityHeaders`](../common/headers.md#symbol-securityHeaders), [`KeyError`](../common/keys.md#symbol-KeyError), [`SigningKeys`](../common/keys.md#symbol-SigningKeys) ([`provider`](../common/keys.md#symbol-SigningKeys.provider)), and [`settings`](../common/settings.md#symbol-settings) from `common`.
 
-- Set `config` to call [`settings`](../common/settings.md#symbol-settings).
-- Try these operations:
-  - Set `form` to call `form` on `http` with type arguments [`TokenForm`](contracts.md#symbol-TokenForm).
-  - If `grant_type` of `form` does not equal `"authorization_code"`:
-    - Return call [`_oauthError`](token.md#symbol-_oauthError) with `code` = `"unsupported_grant_type"`; `description` = `"Only authorization_code is supported."`.
-  - If `client_id` of `form` does not equal `clientId` of `config`:
-    - Return call [`_oauthError`](token.md#symbol-_oauthError) with `code` = `"invalid_client"`; `description` = `"The registered client is required."`.
-  - If not (call `isToken` on `code` of `form` with `min` = `43`; `max` = `43`) or not (call `isToken` on `code_verifier` of `form` with `min` = `43`; `max` = `128`):
-    - Return call [`_oauthError`](token.md#symbol-_oauthError) with `code` = `"invalid_grant"`; `description` = `"The authorization grant is invalid."`.
-  - Set `now` to call [`Clock.now`](../dependencies/august/0.19.0/time/contracts.md#symbol-Clock.now) on `clock`.
-  - Select the matching case for call [`ExpiringStore.take`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.take) on `codes` with `key` = `code` of `form`; `now` = `now`:
-    - A null value, including omitted optional input:
-      - Return call [`_oauthError`](token.md#symbol-_oauthError) with `code` = `"invalid_grant"`; `description` = `"The authorization grant is invalid."`.
-    - A present, non-null value, named `grant`:
-      - Set `challenge` to call `base64url` on call [`Crypto.sha256`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.sha256) on `crypto` with `input` = call `bytes` on `code_verifier` of `form`.
-      - If ((`clientId` of `grant` does not equal `client_id` of `form`) or (`redirectUri` of `grant` does not equal `redirect_uri` of `form`)) or not (call [`Crypto.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal) on `crypto` with `left` = call `bytes` on `challenge`; `right` = call `bytes` on `challenge` of `grant`):
-        - Return call [`_oauthError`](token.md#symbol-_oauthError) with `code` = `"invalid_grant"`; `description` = `"The authorization grant is invalid."`.
-      - Set `claims` to call [`IdClaims`](contracts.md#symbol-IdClaims) with `iss` = `issuer` of `config`; `sub` = `subject` of `grant`; `aud` = `clientId` of `grant`; `exp` = (`now` plus `300`); `iat` = `now`; `nonce` = `nonce` of `grant`; `name` = `name` of `grant`.
-      - Set `idToken` to call [`signJwt`](../dependencies/august/0.19.0/crypto/jose.md#symbol-signJwt) with `key` = call [`SigningKeys.provider`](../common/keys.md#symbol-SigningKeys.provider) on `keys`; `claims` = call `Json` with `value` = `claims`; `kid` = `"provider-1"`; `tokenType` = `"JWT"`; inject `crypto` from `crypto`.
-      - Set `accessToken` to call `base64url` on call [`Crypto.random`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.random) on `crypto` with `size` = `32`.
-      - Set `value` to call [`AccessGrant`](contracts.md#symbol-AccessGrant) with `subject` = `subject` of `grant`; `name` = `name` of `grant`; `expires` = (`now` plus `300`).
-      - Call [`ExpiringStore.put`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.put) on `access` with `key` = `accessToken`; `value` = `value`; `expires` = `expires` of `value`; `now` = `now`.
-      - Set `body` to call [`TokenResponse`](contracts.md#symbol-TokenResponse) with `token_type` = `"Bearer"`; `access_token` = `accessToken`; `id_token` = `idToken`; `expires_in` = `300`; `scope` = `"openid profile"`.
-      - Return call `HttpResponse` with `body` = call `Json` with `value` = `body`; `headers` = call [`securityHeaders`](../common/headers.md#symbol-securityHeaders).
-- If they fail with `HttpError`, name the failure `error` and recover:
-  - Return call [`_oauthError`](token.md#symbol-_oauthError) with `code` = `"invalid_request"`; `description` = `"Submit the required URL-encoded token fields once each."`.
+It uses [`Settings`](../common/settings.md#symbol-Settings) (`clientId` and `issuer`). It uses [`AccessGrant`](contracts.md#symbol-AccessGrant) (`expires`), [`AuthorizationCode`](contracts.md#symbol-AuthorizationCode) (`challenge`, `clientId`, `name`, `nonce`, `redirectUri`, and `subject`), [`IdClaims`](contracts.md#symbol-IdClaims), [`OAuthError`](contracts.md#symbol-OAuthError), [`TokenForm`](contracts.md#symbol-TokenForm) (`client_id`, `code`, `code_verifier`, `grant_type`, and `redirect_uri`), and [`TokenResponse`](contracts.md#symbol-TokenResponse) from `contracts`.
 
-**Author documentation**
-
-A real OAuth token endpoint. Exact client/redirect binding, S256 PKCE, expiry and one-use codes are enforced. Errors use OAuth JSON.
-
-### `_oauthError` {#symbol-_oauthError}
-
-[source](token.md#code)
-
-Private to its defining scope.
-
-**Inputs**
-
-- `code` (`string`) — required labeled input.
-- `description` (`string`) — required labeled input.
-
-Returns: `HttpResponse<Json>`.
-
-Can fail with `HttpError`. Callers must catch or propagate these errors.
-
-**What it does**
-
-- Return call `HttpResponse` with `body` = call `Json` with `value` = call [`OAuthError`](contracts.md#symbol-OAuthError) with `error` = `code`; `error_description` = `description`; `status` = `400`; `headers` = call [`securityHeaders`](../common/headers.md#symbol-securityHeaders).
-
-### 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.equal`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.equal) (`left`: `Bytes`, `right`: `Bytes`) → `bool`.
-- [`Crypto.random`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.random) (`size`: `int`) → `Bytes`; can fail with `CryptoError`.
-- [`Crypto.sha256`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.sha256) (`input`: `Bytes`) → `Bytes`; can fail with `CryptoError`.
-- [`Crypto.signRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.signRsa) (`key`: `RsaPrivateKey`, `input`: `Bytes`) → `Bytes`; 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.
-
-#### [`signJwt`](../dependencies/august/0.19.0/crypto/jose.md#symbol-signJwt)
-
-Function from `august.crypto`.
-
-- [`signJwt`](../dependencies/august/0.19.0/crypto/jose.md#symbol-signJwt) (`key`: `RsaPrivateKey`, `claims`: `Json`, `kid`: `string`, `tokenType`: `string`) → `string`; inject `crypto`: [`Crypto`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto); uses [`crypto.signRsa`](../dependencies/august/0.19.0/crypto/contracts.md#symbol-Crypto.signRsa); can fail with `JwtError`.
-
-#### [`ExpiringStore`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore)
-
-Capability interface from `august.memory`.
-
-- [`ExpiringStore.put`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.put) (`key`: `string`, `value`: `T`, `expires`: `int`, `now`: `int`) → `void`; can fail with `StoreFull`.
-- [`ExpiringStore.take`](../dependencies/august/0.19.0/memory/store.md#symbol-ExpiringStore.take) (`key`: `string`, `now`: `int`) → `optional T`.
-
-#### [`StoreFull`](../dependencies/august/0.19.0/memory/store.md#symbol-StoreFull)
-
-Class from `august.memory`.
-
-Used as a type or provider.
-
-#### [`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`.
-
-#### [`securityHeaders`](../common/headers.md#symbol-securityHeaders)
-
-Function from `common`.
-
-- [`securityHeaders`](../common/headers.md#symbol-securityHeaders) (no caller inputs) → `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.provider`](../common/keys.md#symbol-SigningKeys.provider) (no caller inputs) → `RsaPrivateKey`; can fail with `KeyError`.
-
-#### [`Settings`](../common/settings.md#symbol-Settings)
-
-Record.
-
-- Read `clientId` (`string`).
-- Read `issuer` (`string`).
-
-#### [`settings`](../common/settings.md#symbol-settings)
-
-Function from `common`.
-
-- [`settings`](../common/settings.md#symbol-settings) (no caller inputs) → [`Settings`](../common/settings.md#symbol-Settings).
-
-#### [`AccessGrant`](contracts.md#symbol-AccessGrant)
-
-Record from `contracts`.
-
-- Construct with `subject`: `string`, `name`: `string`, `expires`: `int` → [`AccessGrant`](contracts.md#symbol-AccessGrant).
-- Read `expires` (`int`).
-
-#### [`AuthorizationCode`](contracts.md#symbol-AuthorizationCode)
-
-Record from `contracts`.
-
-- Read `challenge` (`string`).
-- Read `clientId` (`string`).
-- Read `name` (`string`).
-- Read `nonce` (`string`).
-- Read `redirectUri` (`string`).
-- Read `subject` (`string`).
-
-#### [`IdClaims`](contracts.md#symbol-IdClaims)
-
-Record from `contracts`.
-
-- Construct with `iss`: `string`, `sub`: `string`, `aud`: `string`, `exp`: `int`, `iat`: `int`, `nonce`: `string`, `name`: `string` → [`IdClaims`](contracts.md#symbol-IdClaims).
-
-#### [`OAuthError`](contracts.md#symbol-OAuthError)
-
-Record from `contracts`.
-
-- Construct with `error`: `string`, `error_description`: `string` → [`OAuthError`](contracts.md#symbol-OAuthError).
-
-#### [`TokenForm`](contracts.md#symbol-TokenForm)
-
-Record from `contracts`.
-
-- Read `client_id` (`string`).
-- Read `code` (`string`).
-- Read `code_verifier` (`string`).
-- Read `grant_type` (`string`).
-- Read `redirect_uri` (`string`).
-
-#### [`TokenResponse`](contracts.md#symbol-TokenResponse)
-
-Record from `contracts`.
-
-- Construct with `token_type`: `string`, `access_token`: `string`, `id_token`: `string`, `expires_in`: `int`, `scope`: `string` → [`TokenResponse`](contracts.md#symbol-TokenResponse).
-
-### Built-in operations used by this file
-
-- `Bytes.base64url` (no inputs) → `string`: Encode immutable bytes as unpadded RFC 4648 URL-safe base64.
-- `HttpRequest.form` (no inputs) → `TokenForm`: Decode a form record inside a handler so protocol-specific error responses can be returned. Can fail with `HttpError`.
-- `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.
-
-[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).
 
 ::::