# oauthkit BACKLOG
Single project ledger for the standalone `oauthkit` OAuth SDK. Rows follow the project pattern: `number | affected files | problem | acceptance criteria` with `status` and `tags` for drain tracking.
| number | affected files | problem | acceptance criteria | status | tags |
|--------|----------------|---------|---------------------|--------|------|
| 1 | `crates/oauthkit` (source), `libs/runtime/oauthkit` (target), `software/veyyon/veyyon-code/crates/Cargo.toml`, `software/veyyon/veyyon-code/crates/tui/Cargo.toml` | `oauthkit` is currently embedded inside `veyyon-code` as `crates/oauthkit`; it is meant to be a general-purpose library consumed by `veyyon-code` and others. | `oauthkit` is moved to `libs/runtime/oauthkit` as a standalone non-workspace crate; `veyyon-code` removes `oauthkit` from its workspace and consumes it via `workspace.dependencies` path; `cargo test` in `libs/runtime/oauthkit` and `cargo check -p veyyon-tui` in `veyyon-code` pass. | completed | A:Organization, D:Macro |
| 2 | `libs/runtime/oauthkit/Cargo.toml` | `oauthkit/Cargo.toml` uses `workspace = true` for every dependency and is only valid inside the `veyyon-code` workspace. | All dependencies are concrete versions with the same feature sets; `anyhow` is removed; no `workspace` references remain; `cargo test` passes. | completed | A:Architecture, D:Macro |
| 3 | `libs/runtime/oauthkit/LICENSE`, `CHANGELOG.md`, `SPEC.md`, `deny.toml`, `rust-toolchain.toml`, `Cargo.toml` | A standalone crate needs license, changelog, spec, and audit metadata. | Apache-2.0 license and `CHANGELOG.md` exist; `deny.toml` configures license/advisories; `rust-toolchain.toml` matches the 2024 edition requirement; `Cargo.toml` metadata is complete. | completed | D:Release/Evidence, C:Documentation |
| 4 | `libs/runtime/oauthkit/README.md`, `libs/runtime/oauthkit/src/lib.rs` | README and lib.rs doc examples use an OAuth flow that does not exist in the built-in registry. | Examples use only methods present in the built-in registry; docs honestly state that OAuth provider data is caller-supplied; `cargo test --doc` and `cargo test` pass. | completed | C:Documentation integrity, A:Product |
| 5 | `libs/runtime/oauthkit/src/flow/authorization_code.rs` | Fixed `redirect_uri` with port 0 binds to an ephemeral port but the authorize URL still contains port 0; callback path matching is hardcoded to `/callback` and `/`, so a custom redirect path returns 404 and the flow hangs. | `accept_code` uses the path from the configured `redirect_uri`; the actual bound port replaces any port 0 in the authorize URL; tests cover fixed port 0, custom path, and root path. | completed | B:Correctness, A:Architecture |
| 6 | `libs/runtime/oauthkit/BUILD.bazel` (new), `libs/runtime/oauthkit/rules/providers.toml` | `oauthkit` is in workspace `Cargo.toml` but has no Bazel `BUILD` file; `include_str!("../rules/providers.toml")` needs `compile_data` under Bazel. | `bazel build //crates/oauthkit` succeeds; `bazel test //crates/oauthkit:all` runs unit tests; `providers.toml` is declared as `compile_data`. | wontfix (obsolete: oauthkit is now a standalone Cargo crate at libs/runtime/oauthkit, outside the veyyon-code workspace, so the `//crates/oauthkit` Bazel target no longer exists. It ships to crates.io and is consumed via Cargo; a Bazel consumer gets a generated BUILD file from crate_universe. A hand-written BUILD.bazel would be unused maintenance rot — Law 1) | D:Fleet/Process, A:Organization |
| 7 | `libs/runtime/oauthkit/src/credentials.rs`, `libs/runtime/oauthkit/src/lib.rs`, `libs/runtime/oauthkit/src/tests.rs` | `Credential` is an open union with `access_token`, `refresh_token`, and `api_key` all as `Option<String>`; `CredentialKind` is separate so the type system does not enforce a valid shape. | `Credential` is an enum with `OAuth` and `ApiKey` variants; getters enforce shape; `secret()` and `Debug` redaction remain; `serde` tag preserves backward-compatible serialization; `cargo test` passes. | completed | A:Architecture, B:Correctness, testing.architecture |
| 8 | `libs/runtime/oauthkit/src/flow/mod.rs`, `libs/runtime/oauthkit/src/flow/device_code.rs`, `libs/runtime/oauthkit/src/flow/authorization_code.rs` | The `reqwest` client has no connect/read/write timeout; `post_token_form` does not parse OAuth error bodies for non-2xx device authorization; token errors may not surface structured `error_description` in all paths. | `http_client` has explicit timeouts or a configurable timeout; `device_code::request` reuses `TokenErrorResponse` on failure; tests cover timeout, OAuth error parsing, and malformed body. | completed | B:Reliability/Operability, C:DX/API |
| 9 | `libs/runtime/oauthkit/src/tests.rs` | No full integration tests for the authorization-code flow (mock loopback redirect plus token exchange) or device-code polling (mock device endpoint plus token endpoint). | Add contract tests with `wiremock` and `tiny_http` that drive the full flow, including state mismatch, timeout, `slow_down`, `access_denied`, and custom redirect path. | completed | B:Testing.contract, B:Testing.adversarial |
| 10 | `libs/runtime/oauthkit/src/provider.rs`, `libs/runtime/oauthkit/src/tests.rs` | Registry validation only checks non-empty strings, not URL validity, `redirect_uri` scheme, or `loopback_port` versus `redirect_uri` conflict. | `validate` rejects malformed `authorize_url`/`token_url`/`device_authorization_url`/`redirect_uri` and conflicting `loopback_port`/`redirect_uri` with clear errors; tests assert these rejections. | completed | B:Correctness/Conformance, C:DX/API |
| 11 | `libs/runtime/oauthkit/src/lib.rs`, `libs/runtime/oauthkit/src/tests.rs`, `libs/runtime/oauthkit/README.md` | `AuthClient` exposes `begin_device` but no `complete_device` helper; callers must manually call `DeviceAuthorization::poll`; there is no method dispatch helper. | Add `AuthClient::complete_device(provider_id, device_auth, max_wait)` or `AuthClient::sign_in_with_method(provider_id, method)` that dispatches and completes; update docs and tests. | completed | C:API/DX, A:Product |
| 12 | `libs/runtime/oauthkit/src/flow/mod.rs`, `libs/runtime/oauthkit/src/credentials.rs` | `TokenResponse` treats `token_type` as optional, but RFC 6749 section 5.1 requires it; lenient parsing may produce a `Credential` with no `token_type` and no error. | Either make `token_type` required and test failure when missing, or document and test the lenient behavior; `Credential` docs explain what `token_type` means. | completed | B:Conformance, C:Documentation |
| 13 | `libs/runtime/oauthkit/src/provider.rs`, `libs/runtime/oauthkit/src/lib.rs`, `libs/runtime/oauthkit/README.md` | `Provider::oauth()`, `device()`, and `api_key()` return the first matching method; a provider with two OAuth methods silently ignores the second. | `Registry::validate` rejects more than one method of the same kind per provider; `first-match` is now documented as a fallback for a valid, already-unique set; tests cover duplicate rejection. | completed | B:Correctness, C:Contract |
| 14 | `libs/runtime/oauthkit/Cargo.toml` | `anyhow` is declared but never used; the `tokio` `sync` feature is not used in `src` or tests; unused dependencies and features increase the build surface. | Remove `anyhow` dependency; remove `tokio` `sync` feature from `[dependencies]` and `[dev-dependencies]` if unused; `cargo test` still passes; `cargo check` and `cargo clippy` are clean. | completed | D:Macro/Process, A:Wiring |
| 15 | `libs/runtime/oauthkit/src/flow/mod.rs`, `libs/runtime/oauthkit/src/flow/authorization_code.rs`, `libs/runtime/oauthkit/src/flow/device_code.rs`, `libs/runtime/oauthkit/src/tests.rs`, `libs/runtime/oauthkit/Cargo.toml` | No tracing or instrumentation for async OAuth flows; failures are hard to observe in production. | Add `tracing` at `info`/`debug` for flow start, token request, error, and completion; use `#[tracing::instrument]` on async functions; tests confirm spans do not leak secrets. | completed | B:Operability, C:Observability |
| 16 | `libs/runtime/oauthkit/README.md` | OAuth provider data is not in the built-in registry; common model providers (Anthropic, OpenAI, Google) only have API-key entries, but the SDK is designed for OAuth. | Add real public OAuth provider parameters for at least the major providers that publish them, or document how a caller merges them; validate via registry tests and doc examples. | completed (documented the caller-merge path: BYO client_id TOML + OIDC discovery; fabricating public client_ids would violate product truth since providers do not publish universal ones) | A:Product, C:Documentation |
| 17 | `libs/runtime/oauthkit/src/credentials.rs`, `libs/runtime/oauthkit/src/lib.rs` | `CredentialStore` is `Send + Sync` but does not require `Clone`; `MemoryStore` is not `Clone`; some callers may want to share a store behind an `Arc`. | `MemoryStore` is `Clone`; `AuthClient<S: Clone + CredentialStore>` is `Clone`; tests confirm cloned stores are independent. | completed | C:API/DX, A:Architecture |
| 18 | `libs/runtime/oauthkit/src/pkce.rs` | PKCE verifier generation uses 64 random bytes, which is within the 43-128 range, but there is no test asserting verifier length or challenge derivation. | Add adversarial tests for verifier length, challenge derivation, and URL-safe base64 without padding. | completed | B:Testing.unit, B:Testing.adversarial |
| 19 | `libs/runtime/oauthkit/src/discovery.rs` (new), `libs/runtime/oauthkit/src/lib.rs`, `libs/runtime/oauthkit/src/tests.rs` | No support for OIDC discovery from `.well-known/openid-configuration`. | Add optional OIDC discovery that fetches `authorization_endpoint`, `token_endpoint`, and `revocation_endpoint` and builds an `OAuthConfig`; tests cover success and malformed discovery. | completed | A:Innovation, C:API/DX |
| 20 | `libs/runtime/oauthkit/src/encrypted_store.rs` (new), `libs/runtime/oauthkit/src/lib.rs`, `libs/runtime/oauthkit/Cargo.toml`, `libs/runtime/oauthkit/README.md`, `libs/runtime/oauthkit/src/tests.rs` | No guidance or integration for encrypting credentials at rest; `MemoryStore` is the only built-in store. | Document keyring integration or add a `keyring-store` feature; add an example store that encrypts with a user-provided key; tests prove redaction. | completed (opt-in `encrypted-store` feature: `EncryptedStore` seals credentials with ChaCha20-Poly1305 under a caller key; public `seal`/`open` for disk/keyring backing; tests prove ciphertext hides the secret, wrong key/tamper fail closed, fresh nonces) | A:Product, B:Security |
| 21 | `libs/runtime/oauthkit/README.md`, `libs/runtime/oauthkit/src/lib.rs` | README is hand-written and may drift from `lib.rs` doc examples. | Add `cargo-rdme` or equivalent so README is generated from `lib.rs` docs; CI enforces it; `README.md` and docs match. | completed (equivalent: README compiled as doctests via `#[doc = include_str!("../README.md")] #[cfg(doctest)]`, so every README example must compile against the real public API; enforced by `cargo test --doc` in CI. Locally verifiable, unlike cargo-rdme which would overwrite the richer hand-written README) | D:Release/Evidence, C:Documentation |
| 22 | `libs/runtime/oauthkit/.github/workflows/ci.yml` (new) | `oauthkit` has no dedicated testforge or CI entry; it is only tested through `veyyon-code` today. | Add `testforge` conformance tests and a CI job that runs `cargo test`, `cargo clippy`, `cargo deny`, and `cargo fmt` for the standalone crate. | completed (GitHub Actions CI: fmt --check, clippy -D warnings, test --all-features, doc tests, a 1.86 MSRV --lib build, and cargo-deny; all gates verified green locally) | B:Testing.conform, D:Macro |
| 23 | `libs/runtime/oauthkit/Cargo.toml`, `santhreal/oauthkit` | `oauthkit` is not published and has no remote repository configured for the standalone crate. | `Cargo.toml` declares `repository` and `publish = true`; `santhreal/oauthkit` is the canonical remote; release artifacts flow to `crates.io` and the Santh mirror. | DONE (user-authorized 2026-07-14): PUBLISHED oauthkit v0.1.0 to crates.io (verified via registry API). Canonical remote created at github.com/santhreal/oauthkit (owner is `santhreal`, not `santhreal` — the latter is a stale name with no matching org; existing tool repos live under santhreal/, e.g. santhreal/keyhog) with the source pushed. Cargo.toml/CHANGELOG repository+homepage URLs corrected to santhreal/oauthkit before publish. UPDATE 2026-07-14: v0.2.0 PREPARED (API-hardening: `OAuthConfig` is now `#[non_exhaustive]` + derives `Default` + gains `OAuthConfig::new(authorize_url, token_url, client_id)` so the config can grow via compatible releases — Law 1; CHANGELOG/Cargo.toml bumped to 0.2.0; README documents `new`; new constructor test; all gates green: 50 tests + 5 doctests, clippy -D warnings, fmt, cargo-deny; `publish --dry-run` clean, packaged 26 files). PUBLISHED 0.2.0 (2026-07-14): `cargo publish` from libs/runtime/oauthkit succeeded — "Published oauthkit v0.2.0 at registry crates-io", exit 0. ROOT CAUSE of the earlier 403 was MISDIAGNOSED as an expired/scoped token: it was env-var SHADOWING. The publish command sourced `CARGO_REGISTRY_TOKEN` from /credentials/.env (stale, mtime Jun 5), and that env var OVERRIDES ~/.cargo/credentials.toml — where the user had refreshed the token via `cargo login` (mtime Jul 13). Fix: `unset CARGO_REGISTRY_TOKEN` before publish so cargo uses the fresh credentials.toml token. Lesson: never source /credentials/.env for cargo publish unless its token is known-current; prefer the credentials.toml token. /credentials/.env still holds the OLD token (offer to sync it to the fresh value to prevent recurrence) | D:Release/Evidence, A:Product |
| 24 | `libs/runtime/oauthkit/src/provider.rs`, `libs/runtime/oauthkit/src/flow/authorization_code.rs`, `libs/runtime/oauthkit/src/tests.rs` | `OAuthConfig` uses `extra_authorize_params: Vec<(String, String)>` for common fields like `audience` and `prompt`. | Add typed optional fields for `audience`, `prompt`, `login_hint`, etc., and merge them into the authorize URL; keep `extra_authorize_params` for truly custom fields; tests cover. | completed | C:API/DX, A:Architecture |
| 25 | `libs/runtime/oauthkit` (all) | After extraction and refinement, the standalone crate, docs, tests, and `veyyon-code` consumer must stay coherent. | `cargo test` in `libs/runtime/oauthkit` passes; `cargo check -p veyyon-tui` in `veyyon-code` passes; `BACKLOG.md` rows are drained or flipped; README, SPEC, and code agree. | completed (all gates green on 1.88: fmt, clippy -D warnings, 49 tests + 4 doctests, deny; MSRV 1.86 --lib builds; `cargo check -p veyyon-tui` green against the updated crate; README/SPEC/CHANGELOG re-exports and API list reconciled; no stale version refs) | D:Macro, B:Testing.conform, C:Documentation |
| 26 | `libs/runtime/oauthkit/src/flow/authorization_code.rs`, `src/tests.rs`, `Cargo.toml`, `CHANGELOG.md` | Testing-contract gap: 50 example tests but ZERO property/fuzz coverage on the pure builders/crypto. Writing an authorize-URL property test surfaced a real robustness gap: `build_authorize_url` deduped `extra_authorize_params` only against oauthkit's OWN reserved keys, so TWO custom extras with the same key both emitted → a DUPLICATE query key (which some providers reject). | Add property tests (proptest) that fuzz the hostile-input surfaces with exact invariants (never !is_empty). FIX the dedup to drop any extra whose key collides with a protocol/typed param OR an earlier extra (first-wins). | DONE: build_authorize_url now tracks a `seen: HashSet<&str>` and skips any duplicate key (extras-vs-reserved AND extras-vs-extras); made `pub(crate)` for direct fuzzing. Added `mod property` (proptest dev-dep): (1) `authorize_url_is_wellformed_and_deduped_for_arbitrary_config` — arbitrary client_id/scopes/audience/prompt/login_hint + hostile extras with `&`/`=`/`%`/`+`/space keys+values → asserts valid URL, NO duplicate query key, required protocol params exact, typed values round-trip through percent-encoding; (2) `generated_pkce_always_satisfies_rfc7636` (4096 cases) — verifier 43..=128 unreserved chars, challenge == BASE64URL-NOPAD(SHA256(verifier)); (3) `encrypted_store_roundtrips_and_fails_closed_for_arbitrary_input` (feature-gated) — arbitrary 32-byte key + credential → seal/open roundtrips exactly, wrong key + single-byte tamper both fail closed. CHANGELOG collision bullet updated (folded into unpublished 0.2.0, no version bump needed). Existing `typed_authorize_params_are_merged_and_win_over_colliding_extras` still green (stricter dedup is a superset) | B:Testing.property, A:Robustness |
| 27 | `libs/runtime/oauthkit/src/flow/mod.rs`, `src/tests.rs`, `CHANGELOG.md` | Hostile-input overflow (validate-at-boundary / fail-closed): `expiry_from_expires_in` computed `now + expires_in` with an unchecked add, but `expires_in: Option<i64>` is parsed straight from the untrusted token response. A malicious/buggy provider sending `i64::MAX` (or `i64::MIN`) overflows → debug PANIC / release silent wraparound to a nonsensical expiry (a token could read as never-expiring or already-expired). | Compute the absolute expiry with a checked/saturating add; add an adversarial regression test for `i64::MAX`/`i64::MIN` that asserts no panic and a sane bound. | DONE: `Some(now.saturating_add(expires_in))` — `i64::MAX` saturates to `i64::MAX` ("never expires"), a large negative yields an already-past (negative) expiry so the credential reads expired (fail-safe). Regression test `expiry_from_expires_in_saturates_on_hostile_values` asserts both. CHANGELOG Fixed bullet added (folded into unpublished 0.2.0). 54 tests + 5 doctests, clippy -D warnings, fmt all green | B:Testing.adversarial, B:Security/Robustness |
| 28 | `libs/runtime/oauthkit/src/flow/device_code.rs`, `src/tests.rs`, `CHANGELOG.md` | Device-code `poll` violated its `max_wait` contract: the deadline was only checked at the top of the loop, then `tokio::time::sleep(interval)` slept the FULL server-provided `interval` unconditionally. A hostile/buggy provider returning a huge `interval` (or any `interval` > remaining time) made `poll` hang far past `max_wait` (a slow-loris style DoS on the sign-in). | Bound each sleep to the time left until the deadline so `max_wait` is always honored, regardless of the advertised interval; regression test with a huge interval + tiny max_wait asserting a prompt `Timeout`. | DONE: loop now computes `remaining = deadline.saturating_duration_since(now)`, returns `Timeout` when zero, and sleeps `interval.min(remaining)` — the server interval still paces normal polling but can never extend the wait beyond `max_wait`. Regression test `device_poll_honors_max_wait_despite_a_huge_server_interval` (interval=1_000_000s, max_wait=200ms → times out in <30s). Existing pending/slow_down/success poll test unaffected (large remaining → sleep == interval). CHANGELOG Fixed bullet folded into unpublished 0.2.0 | B:Testing.adversarial, B:Security/Robustness |
| 29 | `libs/runtime/oauthkit/src/flow/authorization_code.rs`, `src/tests.rs`, `CHANGELOG.md` | Loopback redirect robustness: `accept_code` aborted the whole sign-in with `StateMismatch` on ANY request carrying a `state` query param — even one with NO authorization code. The ephemeral loopback port is reachable by any local process, so a stray probe like `/callback?state=x` (not a real redirect) could abort a legitimate in-progress sign-in. A genuine redirect always carries a code; the anti-CSRF check should only fire when a code is present. | Only treat a callback as a state mismatch when it carries a code with a non-matching state; ignore code-less requests (stray probes) and keep waiting. CSRF defense must stay intact (a code with a forged state still fails loud). Adversarial test with a wrong-path probe + a code-less `state` request before the real redirect. | DONE: match arm changed from `(_, Some(_))` to `(Some(_), Some(_))` for the StateMismatch case — a code + wrong/mismatched state still fails loud (existing `authorization_code_rejects_a_state_mismatch` still green), but a code-less request now falls through to "ignore and keep waiting". New test `authorization_code_ignores_stray_loopback_requests_before_the_redirect` drives a favicon probe + a code-less `?state=` request, then the real redirect succeeds. Exactly one behavior case changed (no-code + state: abort → ignore); CSRF-relevant cases unchanged. CHANGELOG Fixed bullet folded into unpublished 0.2.0 | B:Security/Robustness, B:Testing.adversarial || 30 | `libs/runtime/oauthkit/src/flow/authorization_code.rs:62-84`, `src/provider.rs:349-356`, `src/tests.rs` | Robustness / IPv4-IPv6 coherence: the FIXED-redirect branch of `begin` binds `tiny_http::Server::http(("127.0.0.1", port))` (line 71) HARDCODED, ignoring the redirect URI's actual host — but `validate_loopback_redirect_uri` (provider.rs:349-356) explicitly PERMITS host `localhost`. On an IPv6-preferring host where `localhost` resolves to `::1` first, the browser is redirected to `http://localhost:port/callback` → connects to `[::1]:port`, but the listener is only on `127.0.0.1:port` → connection refused / the sign-in hangs until `wait`'s timeout. The loopback (`None`) branch already handles this correctly via `bind_loopback`'s v4→v6 fallback + host coherence (94-96); the fixed branch has NEITHER fallback NOR host coherence, so the two paths have asymmetric, silently-divergent robustness. | In the fixed-redirect branch, bind the family that matches the redirect host (resolve `localhost`, or bind both families / fall back like `bind_loopback`) and keep the bound family coherent with the host in `redirect_uri`; alternatively narrow `validate_loopback_redirect_uri` to reject `localhost` in favor of an explicit `127.0.0.1`/`[::1]`. Proving test: a provider with fixed redirect `http://localhost:0/cb` (or `[::1]`) yields a listener the browser can actually reach on the family the host resolves to. | OPEN |
| 31 | `libs/runtime/oauthkit/src/flow/authorization_code.rs:172-177` | Silent fallback (Law 10): `build_authorize_url` drops any caller-provided `extra_authorize_params` entry whose key collides with a protocol/typed param or an earlier extra (`if !seen.insert(key) { continue; }`) with ZERO signal. Task 26 fixed the duplicate-key EMISSION bug, but the resolution is silent: a caller who deliberately sets an extra param that happens to collide with a reserved key (`scope`, `state`, `redirect_uri`, ...) has their explicit intent silently discarded, and will debug a "missing param" with no clue oauthkit ate it. A silent drop of caller input is exactly the class Law 10 bans. | Surface dropped collisions: for an extra colliding with a PROTOCOL/typed key, return an `Error::Malformed` (the caller is misusing the API — reserved keys are owned by the flow); for an extra colliding with an earlier extra, at minimum `tracing::warn!` the dropped key. Never discard caller input with no record. Proving test: an extra param keyed `state` (or `redirect_uri`) errors rather than being silently ignored. | OPEN |
| 32 | `libs/runtime/oauthkit/src/flow/authorization_code.rs:280`, `Cargo.toml` | Non-constant-time secret comparison: the anti-CSRF `state` is validated with `state == expected_state` (short-circuiting byte compare); the crate pulls in NO constant-time primitive (`rg subtle` = none). `state` (and, at token exchange, the PKCE `code_verifier`) are security-sensitive equality checks in a published OAuth SDK. The leak is marginal here (state is single-use, local-loopback, 256-bit high-entropy), so this is defense-in-depth, not an exploitable hole — but an OAuth crate held up as a reference should ct-compare secret equality on principle. | Add `subtle` (or `constant_time_eq`) and compare `state`/any secret-equality with `ct_eq`; document why. Keep it in ONE helper so every secret comparison in the crate routes through it. Proving test asserts the helper is used (grep-gate) and returns correct equality for equal/unequal/length-differing inputs. | OPEN |