Authorization: guard and vault

Authorization is the one thing the client must control. guard in the manifest describes only how the credential is sent in requests. Sign-in, sign-out and refresh are expressed through general actions (grant / revoke / web_signin) and server-driven pages — there is no dedicated section for them.

guard.attach

"guard": {
  "attach": {
    "in": "header",
    "name": "Authorization",
    "scheme": "Bearer",
    "use": "access"
  }
}

• If guard is absent — default: the access token from the vault is sent as Authorization: Bearer on the origin only.
• attach is needed only for non-standard transport (X-API-Key, query, another scheme).

Transport descriptor

The object { "in", "name", "scheme" } is reused in attach and in grant.refresh.send.

Vault — isolated credential store

• Never interpolated — not in {…}, not in source, not in a request body.
• The contract can only write (grant) and clear (revoke), never read.
• access — in session memory; refresh and static keys — in the Keychain (never UserDefaults).
• Read exclusively by attach — and only to send to the origin.

Guard policy (enforced by the client)

• The credential is sent on the origin only, stripped on cross-origin redirects.
• On 401 the client redeems refresh from the vault (via grant.refresh) and retries the request once.

Sign-in — server-driven, no special section

For an unauthenticated request the server returns a sign-in page: either 200 with the sign-in page, or 401 whose body the client renders. The sign-in form is a regular page with field + submit, the submit carrying grant. After grant/revoke the client reloads the current page.

{
  "type": "submit",
  "endpoint": "/auth/login",
  "fields": [
    "u",
    "p"
  ],
  "grant": {
    "access": "access_token",
    "refresh": {
      "path": "refresh_token",
      "redeem": "/auth/refresh",
      "send": {
        "in": "body",
        "name": "refresh_token"
      }
    }
  }
}

• Path source: the response body (submit) or a query callback (web_signin).
• Local variant without network (basic / api_key): "grant": { "from": "fields", "access": "{api_key}" } — value from the form fields (for Basic — a base64 transform).

Sign-out — submit with revoke: true: on 2xx it clears the vault.

{
  "type": "submit",
  "endpoint": "/auth/logout",
  "revoke": true
}

Details of the grant / revoke / web_signin actions — in the Actions section.