skills,schema: collapse http-api-{basic,bearer,key} into single http-api pattern with auth-shape + one/two-step sub-dimensions

Author: petrsnd

.agents/schemas/evidence.schema.json

@@ -118,13 +118,11 @@
       "properties": {
         "preferredPattern": {
           "type": "string",
-          "description": "If probing strongly suggests one of the six authoring patterns, name it here. Otherwise omit.",
+          "description": "If probing strongly suggests one of the four authoring patterns, name it here. Otherwise omit.",
           "enum": [
             "ssh-interactive",
             "ssh-batch",
-            "http-api-basic",
-            "http-api-bearer",
-            "http-api-key",
+            "http-api",
             "http-form-fill"
           ]
         },

.agents/skills/script-authoring/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: script-authoring
 description: >-
-  Use when drafting or revising the custom-platform JSON itself. Six
-  pattern recipes (ssh-interactive, ssh-batch, http-api-basic,
-  http-api-bearer, http-api-key, http-form-fill) cite schema, samples,
-  and templates and cover Do blocks, status messages, custom parameters,
-  and reserved variables. Mandates the fast inner loop: local schema
-  validation against schema/ before any appliance round-trip. SchemaOnly
-  green is necessary but not sufficient — cross-reference samples for
-  analogous patterns before declaring ready.
+  Use when drafting or revising the custom-platform JSON itself. Four
+  pattern recipes (ssh-interactive, ssh-batch, http-api, http-form-fill)
+  cite schema, samples, and templates and cover Do blocks, status
+  messages, custom parameters, and reserved variables. The http-api
+  recipe spans every auth shape the API documents — Basic/Digest via
+  HttpAuth, or Bearer / custom Authorization scheme / custom-header API
+  key via script-built Headers — plus one-step vs two-step token fetch.
+  Mandates the fast inner loop: local schema validation against schema/
+  before any appliance round-trip. SchemaOnly green is necessary but not
+  sufficient — cross-reference samples for analogous patterns before
+  declaring ready.
 ---
 
 # script-authoring
@@ -19,13 +22,11 @@ Before drafting or revising any platform JSON, consult [`AGENTS.md`](../../../AG
 
 ## Scope
 
-Six pattern sub-recipes cover the supported transports:
+Four pattern sub-recipes cover the supported transports:
 
 - [`ssh-interactive`](#ssh-interactive)
 - [`ssh-batch`](#ssh-batch)
-- [`http-api-basic`](#http-api-basic)
-- [`http-api-bearer`](#http-api-bearer)
-- [`http-api-key`](#http-api-key)
+- [`http-api`](#http-api)
 - [`http-form-fill`](#http-form-fill)
 
 Telnet/TN3270 is out of scope (`agent-skills-plan.md` §2). The recipes below are starting points; pick one based on [`strategy-selection`](../strategy-selection/SKILL.md) output and adapt it.
@@ -63,7 +64,7 @@ A green local schema check proves the JSON parses and conforms to the schema. It
 
 Before declaring a draft "ready to import," cross-reference an analogous sample from `samples-index.md`. If a sample uses a construct your draft does not (e.g., a `Try`/`Catch` around `Disconnect`, a `Receive` flush of the login banner, a `Headers` block before `HttpAuth`), surface that divergence to the operator rather than silently omitting it. The `agent-skills-plan.md` §5 rule is explicit: *"if a sample uses a construct the draft doesn't, surface the divergence."*
 
-## Conventions all six patterns share
+## Conventions all four patterns share
 
 - **Top-level shape.** `Id`, `BackEnd: "Scriptable"`, optional `Meta`, optional `Imports`, then one object per operation (`CheckSystem`, `CheckPassword`, `ChangePassword`, …). Operation objects contain `Parameters` (array of single-key objects) and `Do` (array of command objects). See [`schema/custom-platform-script.schema.json`](../../../schema/custom-platform-script.schema.json) lines 14–80 for the top-level fields, and [`docs/reference/script-structure.md`](../../../docs/reference/script-structure.md) for prose.
 - **Reserved parameters** are not declared by the script — SPP injects them. Custom parameters are declared in `Parameters` and addressed as `%Name%`. See [`docs/reference/reserved-parameters.md`](../../../docs/reference/reserved-parameters.md) and [`docs/reference/custom-parameters.md`](../../../docs/reference/custom-parameters.md).
@@ -144,15 +145,22 @@ Reference: [`docs/guides/ssh-platforms.md`](../../../docs/guides/ssh-platforms.m
 
 Reference: [`docs/guides/ssh-platforms.md`](../../../docs/guides/ssh-platforms.md) ("Batch mode" section), [`docs/reference/commands/execute-command.md`](../../../docs/reference/commands/execute-command.md).
 
-### http-api-basic
+### http-api
 
-**Use when** vendor docs or a `WWW-Authenticate: Basic …` response indicate HTTP Basic on every call.
+**Use when** the target exposes a documented HTTP/REST API and the script presents a credential the operator already holds (token, password, API key, anything else).
 
-**Starter:** [`templates/Pattern-GenericRestApiBasicAuth.json`](../../../templates/Pattern-GenericRestApiBasicAuth.json).
+The script shape is the same regardless of auth scheme: `BaseAddress` → `NewHttpRequest` → (auth setup) → `Request` → `ExtractJsonObject` → `Status`. What varies is two orthogonal choices the recipe makes you spell out: **auth shape** and **one-step vs two-step**.
 
-**Closest production sample:** [`samples/http/wordpress/WordPressHttp.json`](../../../samples/http/wordpress/WordPressHttp.json). The pattern is `BaseAddress` → `NewHttpRequest` → `HttpAuth` → `Request`; verified at lines 33–40 and again at 78–82, 128–132 of that sample.
+#### Auth shape — pick a bucket, then a specific scheme
 
-**Key shapes (verified in the sample):**
+The first decision is *who handles the auth dance*:
+
+| Bucket | What the script does | Auth schemes |
+| --- | --- | --- |
+| **HttpAuth-managed** | Hand SPP a username/password and an auth `Type`; the runtime builds the header. | `Basic`, `Digest` |
+| **Script-managed header** | Build the header value yourself and attach it via `Headers`/`AddHeaders`. | `Authorization: Bearer <token>`, custom `Authorization` schemes (`PVEAPIToken=…`, `Token …`, vendor-specific), custom-header API keys (`X-API-Key`, `X-Vault-Token`, `X-Auth-Token`, …) |
+
+**HttpAuth-managed (Basic, Digest).** Set per-request, not once globally; this matches the existing samples and avoids leaking the service-account credential into requests that should target the managed account.
 
 ```jsonc
 { "HttpAuth": {
@@ -161,49 +169,35 @@ Reference: [`docs/guides/ssh-platforms.md`](../../../docs/guides/ssh-platforms.m
     "Credentials": { "Login": "%FuncUsername%", "Password": "%FuncPassword%" } } }
 ```
 
-Set Basic auth per-request, not once globally. This matches the sample and avoids leaking the service-account credential into requests that should target the managed account.
-
-Reference: [`docs/guides/http-platforms.md`](../../../docs/guides/http-platforms.md), [`docs/reference/commands/http-auth.md`](../../../docs/reference/commands/http-auth.md), [`docs/reference/commands/http-setup.md`](../../../docs/reference/commands/http-setup.md), [`docs/reference/commands/request.md`](../../../docs/reference/commands/request.md).
-
-### http-api-bearer
-
-**Use when** vendor docs describe an OAuth2 / token-exchange endpoint and subsequent calls send `Authorization: Bearer …`.
-
-**Starter:** [`templates/Pattern-GenericRestApiBearerToken.json`](../../../templates/Pattern-GenericRestApiBearerToken.json).
-
-**Closest production sample:** [`samples/http/onelogin-jit/OneLogin_GRC_JIT_addon.json`](../../../samples/http/onelogin-jit/OneLogin_GRC_JIT_addon.json). It interleaves `HttpAuth Basic` (when calling the token endpoint with client credentials, lines 2275–2278) with `Authorization: Bearer %AccessToken%` headers on subsequent calls (lines 1228, 1361, 1510, 1672, 1834, 2002, 2135).
-
-**Key shapes:**
-
-- POST to the token endpoint (often `HttpAuth` `Basic` with client id/secret, sometimes form-encoded body).
-- Parse the response with `ExtractJsonObject` to capture `AccessToken` (or vendor-specific field).
-- Build a fresh `NewHttpRequest` for each subsequent call; attach `Authorization: Bearer %AccessToken%` via the `Headers.AddHeaders` map.
+Closest production sample for Basic: [`samples/http/wordpress/WordPressHttp.json`](../../../samples/http/wordpress/WordPressHttp.json) (lines 33–40, 78–82, 128–132). Starter template: [`templates/Pattern-GenericRestApiBasicAuth.json`](../../../templates/Pattern-GenericRestApiBasicAuth.json). For Digest the shape is identical with `Type: "Digest"`; clean self-hostable Digest targets are rare in 2025, so verify the runtime supports the scheme against the deployed appliance version before committing.
 
-Do not reuse the same `RequestObjectName` for token-fetch and operation calls — Basic auth and Bearer auth have different `HttpAuth`/`Headers` configurations and crossing them is a common source of 401s.
-
-Reference: [`docs/guides/http-platforms.md`](../../../docs/guides/http-platforms.md) ("Bearer/OAuth2" section), [`docs/reference/commands/http-auth.md`](../../../docs/reference/commands/http-auth.md), [`docs/reference/commands/json.md`](../../../docs/reference/commands/json.md).
-
-### http-api-key
-
-**Use when** the API takes a static key in a custom header (e.g., `X-API-Key`, `X-Auth-Token`) instead of `Authorization`.
-
-**Starter:** [`templates/Pattern-GenericRestApiKeyRotation.json`](../../../templates/Pattern-GenericRestApiKeyRotation.json) — also covers the `CheckApiKey` / `ChangeApiKey` operation pair. The custom-header shape lives at lines 184–190 of that file:
+**Script-managed header (Bearer, custom Authorization scheme, custom-header API key).** Use `Headers`/`AddHeaders`, not `HttpAuth`. There is no `HttpAuth` `Type` for arbitrary header shapes.
 
 ```jsonc
 { "Headers": {
-    "RequestObjectName": "CheckApiKeyRequest",
+    "RequestObjectName": "CheckRequest",
     "AddHeaders": {
       "Accept": "application/json",
-      "X-API-Key": "%ApiKey%" } } }
+      "Authorization": "Bearer %AccessToken%" } } }
 ```
 
-**Key shapes:**
+Swap `Authorization: Bearer <token>` for whatever the vendor actually uses. Two common variants:
+
+- **Bearer or custom `Authorization` scheme** (`Authorization: Bearer <token>`, `Authorization: PVEAPIToken=user@realm!tokenid=UUID`, `Authorization: Token …`). Closest production sample: [`samples/http/onelogin-jit/OneLogin_GRC_JIT_addon.json`](../../../samples/http/onelogin-jit/OneLogin_GRC_JIT_addon.json) (Bearer header at lines 1228, 1361, 1510, 1672, 1834, 2002, 2135). Starter template: [`templates/Pattern-GenericRestApiBearerToken.json`](../../../templates/Pattern-GenericRestApiBearerToken.json).
+- **Custom-header API key** (`X-API-Key: %ApiKey%`, `X-Vault-Token: %Token%`, `X-Auth-Token: …`). See lines 184–190 of [`templates/Pattern-GenericRestApiKeyRotation.json`](../../../templates/Pattern-GenericRestApiKeyRotation.json). That template also covers the `CheckApiKey` / `ChangeApiKey` operation pair for when the script must rotate the key itself; pair with [`docs/guides/api-key-management.md`](../../../docs/guides/api-key-management.md).
+
+Whichever bucket you're in, declare the credential as `Type: "Secret"` in `Parameters` so SPP redacts it in task logs.
+
+#### One-step vs two-step
+
+Orthogonal to the bucket above:
+
+- **One-step** — the operator already holds the credential the script presents on every operation call. HttpAuth-managed shapes are almost always one-step. Script-managed-header shapes are one-step when the credential is a long-lived API key or PAT.
+- **Two-step** — the script POSTs credentials (often HttpAuth-managed `Basic` with client id/secret, sometimes form-encoded) to a token endpoint, parses the response with `ExtractJsonObject` to capture an access token, then attaches that token via script-managed `Headers` on every subsequent operation call. The `samples/http/onelogin-jit/` sample is the canonical example, interleaving `HttpAuth Basic` on the token call (lines 2275–2278) with `Authorization: Bearer %AccessToken%` on the operation calls.
 
-- Use `Headers` / `AddHeaders` rather than `HttpAuth` — there is no `HttpAuth` type for arbitrary header schemes.
-- Declare the key as `Type: "Secret"` in `Parameters` so SPP redacts it in task logs.
-- For rotation, pair with [`docs/guides/api-key-management.md`](../../../docs/guides/api-key-management.md) — the script must implement `CheckApiKey` + `ChangeApiKey`, and the operations the platform exposes change accordingly.
+Two-step gotcha: do **not** reuse the same `RequestObjectName` for the token-fetch and the operation calls. The two have different `HttpAuth`/`Headers` configurations and crossing them is a common source of 401s. Build a fresh `NewHttpRequest` for each.
 
-Reference: [`docs/guides/api-key-management.md`](../../../docs/guides/api-key-management.md), [`docs/reference/commands/http-setup.md`](../../../docs/reference/commands/http-setup.md).
+Reference: [`docs/guides/http-platforms.md`](../../../docs/guides/http-platforms.md), [`docs/reference/commands/http-auth.md`](../../../docs/reference/commands/http-auth.md), [`docs/reference/commands/http-setup.md`](../../../docs/reference/commands/http-setup.md), [`docs/reference/commands/request.md`](../../../docs/reference/commands/request.md), [`docs/reference/commands/json.md`](../../../docs/reference/commands/json.md), [`docs/guides/api-key-management.md`](../../../docs/guides/api-key-management.md).
 
 ### http-form-fill
 

.agents/skills/strategy-selection/SKILL.md

@@ -4,8 +4,11 @@ description: >-
   Use to decide the implementation approach for a custom platform from
   protocol, vendor documentation, and probe evidence. Maps inputs to a
   recommendation across SSH (interactive vs batch) and HTTP (form-fill
-  vs API; basic / bearer / api-key; password vs key vs API key;
-  self-managed vs service-account). Accepts both fetched URLs and
+  vs api). For http-api, also picks the auth shape — HttpAuth-managed
+  (Basic, Digest) vs script-managed header (Bearer, custom Authorization
+  scheme, custom-header API key) — and one-step vs two-step token fetch.
+  Plus credential intent (password / SSH key / API key / bearer token)
+  and self-managed vs service-account. Accepts both fetched URLs and
   vendor-doc excerpts the user pasted into the conversation.
 ---
 
@@ -17,16 +20,20 @@ Before recommending a pattern, consult [`AGENTS.md`](../../../AGENTS.md) for the
 
 ## Scope
 
-Map `(protocol, vendor docs, probe evidence)` to one of the six authoring patterns covered by [`script-authoring`](../script-authoring/SKILL.md):
+Map `(protocol, vendor docs, probe evidence)` to one of the four authoring patterns covered by [`script-authoring`](../script-authoring/SKILL.md):
 
 - `ssh-interactive`
 - `ssh-batch`
-- `http-api-basic`
-- `http-api-bearer`
-- `http-api-key`
+- `http-api`
 - `http-form-fill`
 
-Plus two orthogonal dimensions: **credential intent** (password / SSH key / API key / bearer token) and **self-managed vs service-account**.
+When `http-api` is the recommendation, also pick:
+
+- **Auth shape bucket.** *HttpAuth-managed* (Basic, Digest) vs *script-managed header* (Bearer, custom `Authorization` scheme, custom-header API key).
+- **Specific scheme** within the bucket (e.g., `Bearer` vs `PVEAPIToken=…` vs `X-API-Key`).
+- **One-step vs two-step** — does the operator already hold the credential the script presents on every call (one-step), or must the script POST credentials to a token endpoint first (two-step)?
+
+Plus two orthogonal dimensions that apply to every pattern: **credential intent** (password / SSH key / API key / bearer token) and **self-managed vs service-account**.
 
 ## Modes
 
@@ -80,17 +87,18 @@ The detailed rules per branch are in the decision tree. The skill-level meta-rul
 
 ## Self-managed vs service-account
 
-Orthogonal to the six patterns. Decide based on vendor docs and probe evidence, not assumption (see the "Self-managed vs service-account" section of the decision tree). When in doubt, ask the operator which mode the deployment will use — the answer changes which operations the script must implement and may bring `service-account` parameters (like a separate `FuncUsername`/`FuncPassword`) into scope.
+Orthogonal to the four patterns. Decide based on vendor docs and probe evidence, not assumption (see the "Self-managed vs service-account" section of the decision tree). When in doubt, ask the operator which mode the deployment will use — the answer changes which operations the script must implement and may bring `service-account` parameters (like a separate `FuncUsername`/`FuncPassword`) into scope.
 
 ## Output
 
 The skill emits a short structured recommendation to whichever caller asked, typically `script-authoring` next:
 
-- **Recommended pattern** — one of the six.
+- **Recommended pattern** — one of the four.
+- **For `http-api`:** auth shape bucket + specific scheme + one-step vs two-step.
 - **Credential intent** — one of the schema-defined kinds.
 - **Self-managed vs service-account** — pick or "ask operator".
 - **Citations** — the decision-tree row that drove the choice, the vendor-doc record, and the relevant `probeRecord.id`s from the evidence artifact.
 - **Open questions** — anything the agent could not decide with the available evidence. Surface these to the operator before authoring rather than after.
 
-When evidence is incomplete, the recommendation is allowed to be conditional ("`http-api-bearer` if vendor confirms the token endpoint at `/oauth/token`; otherwise re-probe and revisit"). A conditional recommendation is preferable to a confident guess.
+When evidence is incomplete, the recommendation is allowed to be conditional ("`http-api` with two-step Bearer if vendor confirms the token endpoint at `/oauth/token`; otherwise re-probe and revisit"). A conditional recommendation is preferable to a confident guess.
 

.agents/skills/target-probing/SKILL.md

@@ -50,7 +50,7 @@ Every probing session produces one evidence artifact, conforming to [`.agents/sc
 
 Protocol-specific findings live under `sshFindings` or `httpFindings`. The v0 schema marks the internal shapes of these as TODO and intentionally permissive; this skill is the first consumer to populate them. When the playbooks below settle on a final shape, propose a schema bump as a follow-up — do not silently invent fields the schema rejects.
 
-`strategyHints` is optional. Use it sparingly: it signals to `strategy-selection` that probing strongly favours one of the six authoring patterns. The `rationale` must cite a specific `probeRecord.id`, not a generic statement.
+`strategyHints` is optional. Use it sparingly: it signals to `strategy-selection` that probing strongly favours one of the four authoring patterns. The `rationale` must cite a specific `probeRecord.id`, not a generic statement.
 
 ## Pre-flight echo template
 

.agents/skills/task-log-analysis/SKILL.md

@@ -92,7 +92,7 @@ Hand the result back to the right skill:
 
 - `connect` failures with host-key / SSL mismatches → re-run probes via [`target-probing`](../target-probing/SKILL.md) to capture the new fingerprint, then update the script.
 - `connect` / `auth` failures with credential issues → confirm the seed credential with the operator before any further appliance call. Do not retry blindly (credential lockout risk; the probe-safety contract in [`target-probing`](../target-probing/SKILL.md) applies even outside probing).
-- `auth` failures with HTTP 401 after a token exchange → revisit [`script-authoring`](../script-authoring/SKILL.md) for `http-api-bearer` token-handling shape; common cause is reusing a single `RequestObjectName` across token-fetch and operation calls.
+- `auth` failures with HTTP 401 after a token exchange → revisit [`script-authoring`](../script-authoring/SKILL.md) for the `http-api` two-step token-handling shape; common cause is reusing a single `RequestObjectName` across token-fetch and operation calls.
 - `parse` failures → revisit `script-authoring`; cross-reference the failing `Receive`/regex against the analogous sample.
 - `operation` failures (target accepted but state did not change) → revisit [`strategy-selection`](../strategy-selection/SKILL.md). The wrong pattern may have been chosen (e.g., interactive `passwd` over batch SSH succeeds visibly but does not actually rotate).
 - `unknown` → stop and ask.