fix(tasks): keep resolved credentials out of queued job payloads, add credential schemes

[sroussey]

Fixes the two remaining defects in FetchUrlTask's credential handling. The broader credential subsystem (ICredentialStore, the stores, CREDENTIAL_STORE, the format: "credential" resolver path, AI credential resolution) was already shipped and is unchanged here — see the now-closed #238.

Security defect (#673)

FetchUrlTask resolved credential_key into the real secret and wrote it as an Authorization header onto the same object that was then handed to the queue:

jobInput = { ...rest, headers: { ...input.headers, Authorization: `Bearer ${credential}` } };
// ...
const handle = await registeredQueue.client.send(jobInput as Input, { ... });

A source comment claimed the credential was stripped "so the secret is not persisted to queue storage". It stripped the credential_key field but not the header it had just written. Queue bodies are persisted durably (SQLite / Postgres / SQS), so the bearer token was written to storage.

Scope: the opt-in queued path only (config.queue truthy). The default inline path (queue ?? false) never reached the queue and was not affected.

Behavior chosen

The queued path now refuses to run when a credential is present, raising a TaskConfigurationError:

FetchUrlTask: credential_key cannot be combined with the queued path (config.queue),
because queued job payloads are persisted to durable storage. Remove config.queue to
run inline, or have the queue worker supply the credential itself.

Explicit refusal rather than a silent downgrade to the inline path — a downgrade would quietly drop the per-domain rate limiting that is the whole reason a caller asks for a queue. Resolving the credential inside FetchUrlJob.execute() was rejected as the alternative: run-fns execute in workers with a separate globalServiceRegistry, so touching a credential store there violates the worker-isolation rule in CLAUDE.md.

All three credential ports are now stripped from the job input unconditionally, so a resolved secret only ever exists as an in-process request header. The misleading comment is replaced with the real invariant.

Credential schemes (#674)

Authorization: Bearer was hard-coded, so non-OAuth APIs could not use credential references. Added two plain non-secret config ports (only credential_key carries format: "credential"):

Field	Type	Default
credential_scheme	bearer | basic | header | none	bearer
credential_header	string	Authorization

bearer remains the default, so this is not a breaking change. basic sends the secret verbatim as a pre-encoded user:pass base64 blob — no splitting or encoding is invented here. header places the raw secret in credential_header for API-key style services.

credential_header is validated as a bare header token (1–64 chars of letters, digits, hyphens); anything else raises a TaskConfigurationError. This rejects the CR/LF, colon and whitespace that would otherwise permit header injection. Validation runs even for schemes that ignore the field, so a malformed name is reported rather than silently discarded.

Placement logic is extracted into the exported pure function applyCredentialToHeaders() (packages/tasks/src/task/FetchUrlCredentials.ts) so it is unit-testable directly.

Precedence decision: a resolved credential overwrites a same-named header supplied in headers. The credential store is authoritative, and letting a hard-coded header shadow it would silently defeat the configured credential. This matches the previous behavior and is now asserted and documented.

Docs (#673)

docs/technical/15-credential-management.md claimed that on a store miss "the resolver returns the original string unchanged". The code deliberately returns undefined — echoing the id would thread the credential's name through as its value, sending the key name to the remote host in an Authorization header and masking the misconfiguration. The doc now matches the code, and gains a section covering the new fields and the queue interaction.

Tests

packages/test/src/test/task/FetchTask.test.ts had zero credential coverage. Added 12 tests using InMemoryCredentialStore on a ServiceRegistry scoped to its own Container, plus direct unit tests of the pure function.

Verification

The G1 regression test was written first and confirmed failing on unmodified main. The failure shows the secret verbatim inside the persisted queue row:

FAIL  FetchUrlTask > credentials > refuses the queued path when a credential is present, and persists no secret
AssertionError: expected '[{"queue":"credential-leak-queue","in…' not to contain 'sk-super-secret-value-1234567890'

Received: "[{"queue":"credential-leak-queue","input":{"method":"GET",
"headers":{"Authorization":"Bearer sk-super-secret-value-1234567890"},
"response_type":null,"url":"https://api.example.com/data"},...,"status":"COMPLETED",...}]"

 ❯ packages/test/src/test/task/FetchTask.test.ts:915:31

After the fix:

$ npx vitest run packages/test/src/test/task/FetchTask.test.ts
 Test Files  1 passed (1)
      Tests  56 passed (56)

$ bun run build
 Tasks:    84 successful, 84 total

$ bun scripts/test.ts task vitest
 Test Files  72 passed (72)
      Tests  1152 passed | 24 skipped (1176)

$ bun run build:types
 Tasks:    41 successful, 41 total

$ npx vitest run packages/test/src/test/util/CredentialStore.test.ts packages/test/src/test/task/FetchUrlSsrf.test.ts
 Test Files  2 passed (2)
      Tests  89 passed (89)

Not in scope

AWS Secrets Manager / HashiCorp Vault / GCP Secret Manager adapters are tracked separately in #675 and are not attempted here — three heavyweight SDKs with three auth models, untestable in CI, and no consumer in this repo currently needs them.

Closes #673
Closes #674

🤖 Generated with Claude Code

https://claude.ai/code/session_01PwyJuFrJnibKvrrk8Fa4Fn

---

Generated by Claude Code

[sroussey]

test-vitest-ai-provider-hft failed on 24b3093 for an external reason, not this diff.

ZeroShotTasks.integration.test.ts downloads model configs from the Hub at test time, and the Hub returned HTTP 429:

PermanentJobError: Provider HF_TRANSFORMERS_ONNX failed for ImageClassificationTask:
Error (429) occurred while trying to load file:
"https://huggingface.co/Xenova/clip-vit-base-patch32/resolve/main/config.json"

Same for Xenova/owlvit-base-patch32 in the ObjectDetectionTask cases. Every failure in the job is a 429 on a Hub fetch; there are no assertion failures.

This PR touches packages/tasks/src/task/FetchUrlTask.ts, a new FetchUrlCredentials.ts, its tests, and one doc — nothing in the HFT provider or its model loading. The same shard passed on #672 and #676, which share this PR's base commit.

Likely cause is contention: several PRs from this triage pass had CI running concurrently, each pulling the same models from the Hub. I'll re-run the failed job once the run finishes (GitHub refuses a re-run while it is still in progress). If it reproduces after a clean re-run I'll investigate further rather than assume flakiness.

---

Generated by Claude Code

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	64.41%	31783 / 49343
🔵	Statements	64.21%	32885 / 51208
🔵	Functions	65.49%	5983 / 9135
🔵	Branches	53.43%	16401 / 30694

File Coverage

No changed files found.

Generated in workflow #2895 for commit 6181ed4 by the Vitest Coverage Report Action