T080, 16.3: the credential stays a reference, and a raw key is refused (plan 034)

[brettheap]

Lane: openxfactory-4 (openXfactory-4-openDox_extraction)

Arc: neutral-product-standalone-operability

Plan 034, phase-3 slice P3-B, task T080. The plan was read at openxFactory main e369cb25, from specs/034-opendox-standalone-operation/tasks.md, and read again at main 2140f5a7 and, after T063 landed, at main a883bbf6 (see the box below). The slice is claimed on openxFactory#656, comment 5875729625.

This was drafted ahead, and T063 has now landed. Brett's phase-3 word, as the holder recorded it (2026-09-28, ~18:00Z), was "Only the independent ones (Recommended)". Every phase-3 task comes after T063, which landed as openxFactory#1218 → a883bbf6 and closes phase 2. T078 landed as #61 → 8a98e317 and T079 as #62 → 2fc714d2, so this PR may go READY. Its READY line is the holder's to post.

Important

Dependencies: After: T079, T007 (batches H and K). Both batches have landed, and so have T063 and T079 (#62).

• Batch H, openxFactory#1206 → f99a2097: 16.3's addendum for the built-in resolver and the auth kind none (R1Q17 (b), R1Q18 (a)). This PR carries it out.
• Batch K, openxFactory#1210 → 39f19145: the dated note in requirement 17's body in #1144's spec delta, with a pointer after 16.3's batch H addendum (5916000030, item 1). See Ruled below.
• Read at openxFactory main 2140f5a7, and again at a883bbf6, where it is unchanged. Plan 034's T080 entry records the loopback rule, batch K and openDox-code#64, and its After: line names both batches. F16.1's block is unchanged.

One PR per task, stacked. T078 (#61) and T079 (#62) have landed, and this PR is based on main. #64, the broker hardening, is based on this branch, so retarget #64 to main before this branch is deleted, because a merge with --delete-branch closes the PR stacked on it.

What changes

A key inside the endpoint URL is refused when the binding is declared. Two checks ask. One is the product's own detector, runtime/local_git_adapter.carries_a_credential, imported where it is asked, as authoring.py does. The other is a raw key's shape anywhere in the URL, its path and fragment included (the adversarial review's M5, below). Both run before the scheme check, and every refusal of an endpoint is a fixed sentence, the scheme's too (M3), so no refusal repeats the URL. The key's refusal is ENDPOINT_CARRIES_A_CREDENTIAL, because the URL it refuses carries the key, and through the console the refusal can reach a browser. A key in an extra field is refused as an unknown key, as it always was.

An endpoint longer than the product's URL bound is refused before the detector is asked. The bound is runtime/config.MAX_REMOTE_URL_CHARS (2048), which the repository act applies to a remote for the same reason: the detector is quadratic in a parameter name's length. It is read when the binding is declared, and its refusal, ENDPOINT_TOO_LONG, repeats nothing of the endpoint.

A reference is never a raw key (the adversarial review's M2, below). A reference is held to the same length bound (CREDENTIAL_REF_TOO_LONG), and then refused if the detector flags it or it has a raw key's shape (CREDENTIAL_REF_IS_A_RAW_KEY). Both sentences are fixed. A reference a broker hands back at intake meets the same rule.

Each record now has ONE resolver, and credential_source() names it:

the record	its resolver	broker_argv	credential_ref
any other reference	the broker it names, as before	required	required
env:NAME or keyring:SERVICE/USERNAME	the built-in resolver (R1Q17 (b))	not needed; one given is refused	the reference
auth kind none (R1Q18 (a))	nothing: no credential is presented	forbidden	forbidden

The built-in resolver is doxbench_provider.resolve_credential_reference, inside doxbench_provider.py only.

• It reads the reference at call time, once per request, and keeps nothing. There is no mint, no ledger event, and no credential on the port between turns, so a rotated key is the one the next request presents. The resolved value travels as Authorization: Bearer <value> and nowhere else.
• The resolved value must be non-empty printable ASCII with no whitespace, which is what a bearer credential is by its grammar. A value that is unset, or is anything else, refuses with the fixed DIAG_REFERENCE_UNRESOLVED, before any provider is contacted. A keyring that cannot be read refuses with DIAG_KEYRING_UNAVAILABLE. That refusal is raised after the backend's error has been handled, so it has no cause and no context: neither the backend's words nor its frames travel with it. FIXED_DIAGNOSTICS goes from eight to eleven: these two, and DIAG_PROVIDER_REDIRECTED below.
• A 401 without a broker is DIAG_PROVIDER_REFUSED with no retry. The 2026-08-26 ruling's re-mint is for a minted token, and a second read of a reference names the same value.

A credential the built-in resolver reads travels only by a private route: https://, or http:// to 127.0.0.1, ::1 or localhost. This is Brett's ruling of 2026-09-28, openxFactory#656 comment 5880893901, which batch K's note to #1144's requirement 17 records (see Ruled below).

• doxbench_binding.is_a_private_route is the one predicate. It matches the endpoint as written, case-blind: https://, or http:// followed by exactly one of LOOPBACK_HOSTS (the IPv6 literal bracketed), an optional port, and then /, ?, # or the end.
• It does not use a URL parser's reading of the host, because the parser and the HTTP client disagree. For http://evil.example\@localhost/, urllib.parse reads the host as localhost, while the HTTP client reads the whole authority.
• The record refuses a built-in reference on any other route when it is declared, whether through the constructor, a stored record or the operator door. The refusal is one fixed sentence, ENDPOINT_NOT_PRIVATE, and it comes before any resolution, because no binding exists to resolve.
• The resolver asks the same predicate before its first read. No declared binding reaches that check, so a binding-shaped object that does gets an AssertionError with nothing read, as a broker's reference already does.
• The broker path's route is unchanged, as the ruling says. So is none's, since it presents no credential. The one change this PR makes to the broker path is L4's mapping in the shared transport (below).

A request that carries a built-in credential keeps it on that route. This came out of Copilot's later rounds, below.

• It follows no redirect. urllib's default opener re-sends the credential header to any Location, whatever its host or scheme. The redirect is declined, and the turn refuses with the fixed DIAG_PROVIDER_REDIRECTED.
• Over plain http:// it uses no proxy, because a proxy would carry a loopback request off this host. An https:// request may still use one, since a proxy reaches it only by CONNECT and the credential stays inside TLS.
• No frame a refusal keeps holds the raw credential. The credential travels as _PresentedCredential, whose repr says nothing, on both paths. A refusal of such a request is raised with no cause and no context, so no traceback reaches urllib's own frames, whose locals hold the headers.

none joins AUTH_KINDS after api_key and oauth, so F16.1's AUTH_KINDS[0] is unchanged. Its requests carry no authorization header.

Around them:

• The record parses a reference's form once, for both sides (built_in_reference_parts), and reads nothing a reference names. Both forms parse to one shape, BuiltInReference(form, name, user).
• The env: and keyring: forms are reserved for the built-in resolver. So a broker whose intake answer names a reference in one of them is refused as malformed (DIAG_BROKER_MALFORMED), which both entry points already catch.
  • Otherwise the record would be declared again with two resolvers.
  • The console's intake route builds that record outside the handler that catches a refused binding (serve_workbench.py, which is left alone), so there the refusal would have gone uncaught.
• A stored record may leave out the fields its own resolver forbids or does not need.
• Each read-back and each removal states the custody sentence that is true of its resolver.
• The operator door takes --auth-kind none, an omitted --credential-ref, and an empty broker invocation.
• set-credential refuses a binding no broker answers, without reading its standard input.
• broker_operation_argv treats such a binding as a programming error, since its empty base invocation would run the subcommand as a program.
• http.client.HTTPException joins the errors the transport maps. A response http.client cannot read, or a path it cannot send, lands on DIAG_PROVIDER_UNREACHABLE (the adversarial review's L4, below). The transport is shared, so this changes the broker path's failure too: a broker's turn now lands on that sentence where it escaped before. Raising it afresh there, with no token in a kept frame, is Broker-path credential hardening (follows T080): a minted token keeps a built-in credential's rules (plan 034) #64's (Copilot at 44582f8f).
• A keyring package that fails as it is imported, with anything other than an ImportError, refuses with DIAG_KEYRING_UNAVAILABLE, raised with no context, as a failed read already does (Copilot at 82ec9a20).

Files: src/opendox/doxbench_binding.py, src/opendox/doxbench_provider.py, src/opendox/cli_model_binding.py and tests/test_model_provider_broker.py, all inside P3-B's row. One docstring outside the row, doxbench_intake.auth_kind_disclosure's, now says which kinds the console flow offers (see Review remarks). pyproject.toml is untouched.

Realizes: 16.3. Ruled: R1Q22 (a), 5817152735; R1Q17 (b) and R1Q18 (a), 5850003126; and the loopback rule, 5880893901, with batch K's note to requirement 17, 5916000030, item 1 (see Ruled below).

Readings Brett let stand

Brett's word, relayed by the holder on 2026-09-28: the readings below stand.

1. A broker_argv given beside a built-in reference is refused. This is the plan's fail-closed reading (analyze round 2, V2-21), which openxFactory#656 comment 5851950767 records as standing, not overruled. That such a record needs no broker at all follows from R1Q17 (b). One test holds both halves: test_a_built_in_reference_needs_no_broker_and_refuses_one_beside_it.
2. Where the plan is silent, this PR chose:
   • the reference syntax: env: plus a portable variable name, and keyring:SERVICE/USERNAME, split at the last / so a service may contain one;
   • the OS keyring through the keyring package, imported at call time and not declared as a dependency. Without it, a keyring reference refuses with the fixed sentence. pyproject.toml is outside this slice, and T072 owns its local extra, so declaring it is a holder decision;
   • the resolved value presented as a bearer credential for either kind that takes one. Refreshing an OAuth grant stays a broker's job.

The falsifier: F16.1's three refusals, and tests of the resolver and of none

This is F16.1's record block, extracted verbatim from #1144's tasks.md at openxFactory e369cb25, and unchanged at main 2140f5a7 after batches H and K and at main a883bbf6 after T063 (sha256 8af3001b5f5fb885…), with the control record and the three raw keys:

rec = {f: "stand-in" for f in b.BINDING_FIELDS}
rec.update(auth_kind=b.AUTH_KINDS[0], dialect="openai-chat-v1", endpoint="http://127.0.0.1:9/v1/chat/completions")
if "broker_argv" in rec:
    rec["broker_argv"] = ["stand-in-broker"]
b.ModelProviderBinding.from_record(rec)               # the control: a clean record is accepted
for bad in (dict(rec, endpoint="https://user:sk-stand-in@api.example.invalid/v1"),
            dict(rec, endpoint="https://api.example.invalid/v1?api_key=sk-stand-in"),
            dict(rec, api_key="sk-stand-in")):
    ...
print("dialect and model declared; a raw key is refused in a field and in the URL")

At T079's head b04a3a95 it stops with FAIL: a raw key was accepted in ['endpoint']. At this head 05cb1c70, as at 4948e6dd, the whole block passes:

dialect and model declared; a raw key is refused in a field and in the URL

The named tests are in tests/test_model_provider_broker.py:

• test_f16_1_a_raw_key_is_refused_in_a_field_and_in_the_url (the block above, as a test) and test_f16_1_the_first_auth_kind_still_takes_a_credential;
• the URL detector over eight keyed shapes, with none repeated in its refusal; four clean endpoints accepted; extra fields refused;
• the URL bound: an endpoint past it refused without the detector being asked, and nothing of it repeated; one at it accepted; the number read from runtime/config at declaration;
• the private route (32 cases; each declaration case runs with an env: and a keyring: reference):
  • accepted: https://, 127.0.0.1, [::1] (IPv6 loopback), localhost, LOCALHOST and a bare http://localhost;
  • refused, by the constructor and from a stored record: another host, localhost.evil.com, 127.0.0.1.evil.com, localhost only in the path, 127.0.0.2, [0:0:0:0:0:0:0:1], localhost., localhost%2eevil.com (the HTTP client decodes it) and 0.0.0.0;
  • mixed-case schemes, read by the predicate: HTTP:// to another host and Http://localhost.evil.com are not private, while hTTp://127.0.0.1, HTTP://[::1], HTTPS:// and hTtPs:// are. Also not private: the backslash case, a leading space and another scheme;
  • the resolver reads nothing, from the environment or the keyring, for four routes that are not private, one of them in mixed case. It does read for IPv6 loopback;
  • the operator door refuses an env: binding over http:// to another host and stores nothing, while a none binding to that host is declared. A broker binding and a none binding keep their route;
• the transport (9 cases, over real sockets unless noted):
  • a 301, 302, 303, 307 or 308 declined, with the second server hearing nothing;
  • a stand-in proxy hearing nothing;
  • three walks of every frame a refusal keeps, through its causes and contexts, finding no local that holds the secret. One is a real refused socket, one is an unpresentable value, and one, with a stand-in opener, is the broker path's provider-call frame;
• none: forbids both fields, round-trips, may leave both out, sends no authorization header, spawns no broker (over a real loopback socket too), and refuses a 401 without a retry;
• the resolver: env: read at call time and rotated between turns; production reading os.environ; eleven unusable values refused before any request, and every printable ASCII character but the space presented unchanged; a value outside latin-1 refused over a real socket with nothing chained; availability restored after a success; the keyring read per request at the last-/ split; an absent entry and three unusable keyring answers; a failing backend (fixed sentence, no cause and no context); the keyring package absent; the production import path; the bearer over a real socket; no trace of the resolved value in answers, notices, the ledger, the port's state or on disk; and the refusal mapping onto the seam's fixed model_failed;
• the reference forms: one parse and one shape for both; fourteen malformed references refused without being repeated, two of them variable names of another script (\w is held to ASCII); a broker's answer in either built-in form refused as malformed, through two real broker scripts;
• the resolver is in doxbench_provider.py alone: the record reads no environment and no keyring, and get_password and import keyring appear in no other module of the package;
• the operator door: each resolver declared, two-resolver and no-reference records refused, a keyed URL refused and nothing stored, set-credential refusing a binding no broker answers.

F16.1's other blocks are later tasks'. tests/test_provider_boundary.py is T083's, and it passes here: 24 passed. The no-model block is T081's, and it still fails as #1144 records (['omp-local']), untouched here. tests/test_chat_model_configuration.py is T081's and T082's, and does not exist yet.

The repository's own suite

Local runs of the whole suite, as CI runs it (python -m pytest -q), use a PostgreSQL 16 service for tests_runtime and LANG=C.UTF-8, as on the runner:

tree	passed	skipped	failed
main 9a490405 (T081 landed)	3262	11	0
this head 05cb1c70	3475	11	0

Along the way this round, abbb05d4 read 3361, 93660ec9 (the merge of main 2fc714d2) 3418, 82ec9a20 3419 and 44582f8f 3420. Before this round, main 047bb4fa, T079's b04a3a95 and this branch's 4948e6dd read 3044, 3083 and 3206. Before phase 2 landed, the same three read 2468 (2d116415), 2507 (053e207a) and 2630 (3f14bb96).

CI's validate at this head (run 37086697677) reads selected=3486 passed=3475 skipped=11 failures=0 errors=0, against the pins 2476, 2465 and exactly 11.

The +213 cases are in tests/test_model_provider_broker.py: 64 at the first push (e9ef9514, 2571 passed), 16 in the fix commit f92fca47, 1 in 146b5a22, 32 in the ruling's commit 4abc6d4d, 9 in the three transport commits (5167084c, 1b0fb3f4 and 286655f3), 1 in 3f14bb96, 82 in the adversarial review's commit 645280ac, 1 in 82ec9a20, 1 in 44582f8f and 6 in 47c9da9a. None skips, because the keyring is always a stand-in. Skipped stays at the pinned 11.

This round's commits, and its merges (05cb1c70)

In order:

• 645280ac fixes the adversarial review's four findings (next section).
• 03fb7791 merges T079's cb059d5d. That commit merges openDox-code main 8a98e317: T078's squash (T078, 16.1: the OpenAI-compatible dialect joins DIALECTS (plan 034) #61), with T085 (T085, the standalone doxBench defaults for T027's seams, and T058's two workbench rules move into opendox.validator (plan 034) #71), T088 (T088, the lens's two seed actions are offered only where a binding answers them (R1Q19 (a)) (plan 034) #65) and T071 (T071, 13.2 and 13.3: load_settings refuses a non-PostgreSQL DSN and a collapsed DSN pair (plan 034) #60) landed before it. None of those landings changes a file this PR changes, and the merge had no conflict.
• abbb05d4 merges T079's e7f3a7b3, a docstring fix in doxbench_intake.py that Copilot asked for on T079, 16.2: a model field the provider receives (plan 034) #62. This PR's own edit to that file is a different docstring, and the merge had no conflict.
• 93660ec9 merges main 2fc714d2, which is T079's squash (T079, 16.2: a model field the provider receives (plan 034) #62), after T070 (T070, 13.4-13.6: OPENDOX_INSTALL_MODE and generate-and-open --local (plan 034) #67). This branch carried T079's own commits, so the five files T079 changed met its squash on main:
  • main's copy of each equals T079's head e7f3a7b3.
  • Four of them conflicted only where this branch changes T079's lines. Each is resolved to this branch's side.
  • So the merge adds exactly what main gained beyond T079: git diff abbb05d4 93660ec9 is git diff e7f3a7b3 2fc714d2, T070's thirteen files.
• 82ec9a20 makes the scheme refusal route-neutral (Copilot at abbb05d4).
• 67d00617 fixes SonarCloud's five findings at 82ec9a20.
• 44582f8f makes a failing keyring import refuse like a failed read (Copilot at 82ec9a20).
• 47c9da9a runs the L4 case for a broker's turn too (Copilot at 44582f8f).
• 05cb1c70 merges main 9a490405, T081 (T081, 16.4: "no model configured" is a state, shown before any turn (plan 034) #74). T081 changes tests/test_model_provider_broker.py at cases this PR does not change, and the merge had no conflict. Its changed lines in that file are T081's exactly, and every other file it touches equals main's.

The suite above is this head's. Before this round, 4948e6dd merged T079's b04a3a95, which carried T078's merge of main 047bb4fa (phase 2's nine landings). SonarCloud at this head: 0 issues, 0 hotspots to review, quality gate OK.

The adversarial review at 4948e6dd: M2, M3, M5 and L4

An adversarial reviewer read this PR at 4948e6dd, and the holder forwarded four confirmed findings. 645280ac fixes all four. Every new case fails at 4948e6dd, and every mutant of the new checks is killed.

• M2 (medium): a raw key given as --credential-ref was taken as a broker's reference. It was stored in the file the module calls safe to commit, and list printed it. Each mint then put it in the broker's argv, where /proc/<pid>/cmdline shows it to every local user.
  • The record now asks two questions of every reference, inside the built-in forms too: the product's detector, and a raw key's shape (has_a_raw_key_shape, below). A reference that fails either is refused with one fixed sentence, CREDENTIAL_REF_IS_A_RAW_KEY.
  • The reference a broker hands back at intake is held to the same rule. One that breaks it is a malformed answer (DIAG_BROKER_MALFORMED), which both entry points already catch.
  • No grammar is declared for a broker's references. #1144 box 16.3 says only that a reference is never a raw key. So this is the floor the holder named: the detector, plus a shape check.
• M3 (medium): the scheme refusal repeated the endpoint. So --endpoint <key>, ftp://<key> and " https://…?q=<key>" printed the key to the terminal, to startup's standard error (doxbench_install.py:322) and, through the console's intake route, to a browser (serve_workbench.py:1110). It is now one fixed sentence, ENDPOINT_SCHEME_REFUSED, built from ENDPOINT_SCHEMES alone. A short key that no shape rule knows is not repeated either. Since 82ec9a20 it also says nothing about hosts, because every resolver meets it and only a built-in credential is held to a private route (Copilot at abbb05d4).
• M5 (medium): a key in the endpoint's path or fragment was accepted. The detector reads only a URL's userinfo and its parameters' names. The endpoint is now checked for the same shape, before the scheme check, and refused with ENDPOINT_CARRIES_A_CREDENTIAL. That covers a key used as a path segment, glued to a path word (bot<key>), placed in the fragment, put in a parameter with an innocent name, or given in place of the URL.
• L4 (low): http.client.HTTPException escaped dispatch. http.client raises it when it cannot read a status line, a protocol, a header line or a body, or cannot send a path. It is no OSError, so it escaped, and its traceback kept do_open's frame, whose headers hold the key.
  • The transport now maps it to the fixed DIAG_PROVIDER_UNREACHABLE. The built-in path raises that afresh, with no cause and no context, as it does every refusal.
  • There is one case per subclass, over a real loopback server: BadStatusLine, UnknownProtocol, LineTooLong, HTTPException (more than 100 headers), IncompleteRead, and InvalidURL (a path with a space, which the record accepts).
  • Each case first checks that urllib alone raises exactly that class. Each runs for a built-in credential, for none and, since 47c9da9a, for a broker's turn with a real fake broker's mint. For a broker's turn it pins the sentence only. Broker-path credential hardening (follows T080): a minted token keeps a built-in credential's rules (plan 034) #64 raises it afresh there and pins that.

The shape, and where it stops. A key has no grammar, so the rule is a shape, and it errs toward refusing. A text has a raw key's shape if it holds any of these:

• a run of 32 or more letters and digits that mixes upper case, lower case and digits;
• a run of 40 or more that mixes two of the three;
• a widely used key prefix (sk-, ghp_, xoxb-, hf_ and the rest of _KEY_PREFIXED) with 16 or more key characters after it. Those characters must mix all three classes, or two where the prefix begins a word, so bot glued to a key is still refused, while a word that only ends in a prefix, as benchmark- ends in rk-, is not;
• a Google API key, an AWS access key id, or a JSON Web Token.

The rule passes this product's opref- references, UUIDs, model and deployment names under 32 characters, and the 32-character lowercase hex ids that gateways put in their paths and key vaults put in their secrets' versions. The tests hold both sides at each rule's edge.

It cannot see a key that uses only one class, a two-class key under 40 characters with no known prefix at the start of a word (that is the shape of a gateway's account id), or a format it does not list. Every refusal around it repeats nothing, so a key it misses still reaches no message.

A length bound on the reference, which is new and accepted. Asking the detector about a reference means running a quadratic check on a value that had no bound. Measured locally, an opref- reference of 65,536 characters took the detector 4.3 s. So a reference is held to the endpoint's bound first (MAX_REMOTE_URL_CHARS), with its own fixed sentence, CREDENTIAL_REF_TOO_LONG, and carries_a_raw_key never asks the detector about a longer text. The holder accepted the cap. Brett's "Leave unbounded (Recommended)" (openxFactory#656 comment 5916000030, item 5) is about a TIME limit on reading the operator's key. It does not reach the size of a reference field.

Not in this PR: M4, and the execution of broker_argv from a served repository's bindings file. Both belong to T100, another writer's PR stacked on #64, and neither is touched here.

Failing first. The 82 new cases were run against 4948e6dd's sources. 67 fail, and the 15 that pass are controls. Each failure is the case's own: DID NOT RAISE where a key was accepted, the scheme refusal's echo, and each http.client subclass escaping. Each later case fails without its fix: 82ec9a20's with 93660ec9's record, 44582f8f's with 82ec9a20's import, and 47c9da9a's six with 4948e6dd's transport.

30 mutants, each run against the whole broker module, and each killed:

mutant	killed by
B1 no 3-class run rule	9: the base62 run, as a reference and in seven endpoint places
B2 no 2-class run-of-40 rule	2: the 40-character hex run
B3 the run of 40 widened to 41	2: the 40-character hex run
B4 the run of 40 narrowed to 32	5: the 32- and 39-character hex controls, the gateway's account id
B5 the run of 32 widened to 33	8: the 32-character base62 run
B6 the run of 32 narrowed to 31	2: the 31-character control
B7 no prefix rule	8: the four prefixed shapes
B8 a prefix always needs 3 classes	6: a prefix with a two-class tail, at a word start
B9 a prefix always needs 2 classes	2: benchmark-runner-…, a word that ends in a prefix
B10 the prefix's tail of 16 widened to 17	2: a tail of exactly 16
B11 the prefix's tail of 16 narrowed to 15	2: the 15-character tail control
B12, B13, B14 no Google, AWS or JSON Web Token format	2 each: that format
B15 digits not a class	18
B16 no bound floor in carries_a_raw_key	2: the predicate's floor, and a broker's reference past the bound
B17 carries_a_raw_key without the shape	35
B18 carries_a_raw_key without the detector	2: F16.1's keyed URLs, and the reference at the bound
B19 the endpoint asks the detector alone (4948e6dd)	14: every endpoint place, both keys
B20 no length check on the reference	1: the bound case
B21 no raw-key check on the reference	12
B22 the scheme checked before the key	7
B23 the scheme refusal repeats the endpoint (4948e6dd)	5: every scheme case
B24 a prefix at the start of the text begins no word	6
B25 the scheme refusal's host advice restored (93660ec9)	1: test_the_scheme_refusal_is_route_neutral
P1 no http.client.HTTPException in the transport's tuple	18: every subclass, for a built-in credential, none and a broker's turn
P2 a broker's reference not held to the record's rule	2: both intake cases
P3 a built-in refusal re-raised with its cause	7: the six subclasses and the refused connection, built-in
K1 a keyring import that catches only ImportError (82ec9a20)	1: test_a_keyring_package_that_fails_as_it_is_imported_refuses_the_same_way
K2 that refusal raised inside the handler	1: the same case, on its context

Review remarks, answered at 4948e6dd

Copilot's overview (review 5343397205, at e9ef9514) asked to "address the endpoint-size handling and credential encoding validation findings". It posted no inline threads. Both remarks were valid, and both were measured before they were fixed:

1. Endpoint size. The endpoint reached the detector unbounded, from the command line or from the console's intake route. Measured locally over two runs, the detector takes about 0.002 s on a 2,048-character parameter name, about 0.1 s on 16,384 characters, and 1.4 to 2.2 s on 65,536. The bound now comes first (see What changes).

2. Credential encoding. The resolver refused only CR, LF and NUL. Measured against urllib:

   • a character outside latin-1 failed while the header was encoded. That refusal read DIAG_PROVIDER_UNREACHABLE, which names the wrong party, and the UnicodeEncodeError chained to it held the whole header, credential included;
   • any other non-ASCII character, and an embedded space, was sent.

   Both now refuse with DIAG_REFERENCE_UNRESOLVED. With the old check restored, test_a_value_outside_latin_1_is_refused_before_any_header_is_built fails over a real socket with the provider-unreachable sentence.

SonarCloud (13 findings at e9ef9514):

• in source: S8495 (the parser returned tuples of two lengths, now one named tuple), S6353 ([A-Za-z_]\w* under re.ASCII) and S7632 (a bare # noqa: BLE001, with the reason on the line above);
• in tests: S5778 ×8 (one throwing call per pytest.raises block) and S9073 ×2 (composite assertions split).

All 13 are fixed in f92fca47. Its own analysis found one more, S8997 on the new real-socket test, which reset the stand-in handler's record by assignment. 68b6e412 resets it through monkeypatch. At 4abc6d4d it found S3776: the binding's __post_init__ reached a cognitive complexity of 17, where 15 is allowed. d240fd50 moves the endpoint's own checks into _require_a_declarable_endpoint and the loopback rule into _require_a_private_route. Every check keeps its order.

Five mutants of the fix, each killed by a named test:

mutant	test that fails
re.ASCII dropped	…malformed_built_in_reference…[env:NAMÉ]
the old CR/LF/NUL check restored	eight cases, including …outside_latin_1… over the socket
no length bound	test_an_endpoint_past_the_url_bound_is_refused_before_the_detector
the bound checked after the detector	the same test
the bound copied as 2048	test_the_url_bound_is_the_products_own_read_when_it_is_asked

Copilot's later rounds. Each inline thread is answered with evidence and resolved.

review at	verdict	threads	answered in
146b5a22	Copilot reported an error	none
4abc6d4d	Changes recommended	redirects forward the credential (high); the console's kinds are not derived from AUTH_KINDS (low)	5167084c; the pin test, with evidence and no code change
d240fd50	Changes recommended	the raw credential in frame locals (high)	1b0fb3f4
5167084c	Needs a closer look	none new
1b0fb3f4	Needs a closer look	environment proxies carry a loopback request off the host	286655f3
286655f3	Changes recommended	the header sends six asterisks (high): not reproduced, since the review's secret filter masks the Bearer expression	evidence, three real-socket tests; no code change
286655f3, re-run	Needs a closer look	none; its summary named a broker's reserved-form reference and the keyring refusal's context	3f14bb96
3f14bb96	Needs a closer look	none; its summary names the draft's upstream dependencies, which is the flag at the top
4948e6dd, the merge of main	Needs a closer look	none; its summary names the upstream dependencies and asks for a human review of the security-sensitive change
4948e6dd, asked again through the reviewer API	Needs a closer look	none; its summary asks for a final human review of the credential and transport changes
abbb05d4, the adversarial review's fixes and T079's merges	Changes recommended	the scheme refusal's advice, "an http:// one on this host", was false for a broker's binding and a none binding, which may name an http:// endpoint on another host (moderate)	82ec9a20: the sentence names the schemes alone; reply 4171022804
82ec9a20	Needs a closer look	none; its summary named a keyring package whose import fails with something other than an ImportError	44582f8f
44582f8f	Needs a closer look	none; its summary named the shared transport's L4 mapping as a change to the broker path that the description did not state	47c9da9a, and this description
05cb1c70, the merge of main 9a490405	Needs a closer look	none; see the two unposted notes below

Copilot's run at abbb05d4 (Actions run 37082414121) also stored notes it did not post. Its summary reads "Three unresolved moderate findings remain in diagnostics, malformed endpoint handling, and bearer-header construction", and its log gives each note by location only:

• the diagnostics are the scheme refusal, doxbench_binding.py:290-293, posted as the one thread above;
• the bearer header's construction, doxbench_provider.py:905, was dropped as a duplicate of the resolved six asterisks thread;
• doxbench_provider.py:995-1000, where the request is built from the declared endpoint, passed the duplicate check but was not posted, and its text is not in the log. This PR's reading, an inference, is an endpoint that http.client cannot send, such as one with a space in its path. The record accepts it, and the turn refuses it with the unreachable sentence (L4's InvalidURL case). Refusing such an endpoint when it is declared would be a new rule, so it is left for the holder.

Copilot's run at 05cb1c70 (Actions run 37086706082) stored two notes and posted neither. Its summary reads "Update catalog privacy metadata for none and locally resolved credentials, and clarify the endpoint diagnostic for none." Its log gives the notes by location:

• doxbench_provider.py:1217-1221, where a binding no broker answers takes _dispatch_without_a_broker. This is the catalog's data-handling sentence, which For the holder below records as outside this PR.
• doxbench_binding.py:276-280, a nit: ENDPOINT_CARRIES_A_CREDENTIAL advises naming the credential by its reference in credential_ref, which a none binding may not declare. The sentence still repeats nothing, and it is left as it is.

SonarCloud at 82ec9a20 found five issues, all in this round's code. S5713: urllib.error.URLError is an OSError, so the transport's tuple named one class twice. S5778 ×4: four new cases built an argument inside their pytest.raises block. 67d00617 fixes all five, and no behaviour moves.

Before that, Copilot's run at f92fca47 posted nothing, but its log recorded three notes by location only. 146b5a22 answered two of them: a spelling note, and the console flow's kinds. Its security note later became the frame-locals thread.

Six mutants of the transport fixes, each killed:

mutant	tests that fail
the redirect-declining opener not used	5: every redirect code
the redirect declined silently	5: the diagnostic
the wrapper's repr disclosing	2: the real refused socket and the broker path's frame
the chained cause kept	1: the real refused socket
the unpresentable value kept	1
the proxy bypass removed	1: the stand-in proxy answered the turn

Two mutants of 3f14bb96, each killed:

mutant	test that fails
the keyring refusal raised inside the handler, keeping the backend's error as its context	test_a_keyring_that_cannot_be_read_refuses_and_says_nothing_of_its_own
a broker's reference in a built-in form accepted	test_a_broker_reference_in_a_built_in_form_is_malformed

Ruled: a built-in credential travels only by a private route

Brett Heap ruled on this PR's question on 2026-09-28, choosing "Refuse unless loopback (Recommended)". It is recorded at openxFactory#656 comment 5880893901:

A credential resolved by openDox's built-in resolver (env:/keyring: reference) is sent only over https://, or over http:// to 127.0.0.1, [::1] or localhost; any other http:// endpoint is refused (ENDPOINT_NOT_PRIVATE). The broker path is unchanged in this task.

Batch K records it in #1144 (openxFactory#1210 → 39f19145). Brett Heap's word for the batch is 5916000030, item 1: "Yes, amendment batch K (Recommended)".

• The amendment is a dated note in requirement 17's body in #1144's spec delta, after its SHALL paragraph and above its scenarios. #1144's tasks.md points to it after 16.3's batch H addendum.
• The note narrows requirement 17's and scenario 17.1's "any endpoint" in one respect only: the route a credential travels by. It covers a credential the built-in resolver resolves (5880893901) and a token a broker mints (5890601202). It rewrites no ratified text.
• This PR carries out the built-in resolver's half. openDox-code#64, stacked on this branch, carries out the broker's.
• F16.1 stands, as the pointer says. Its control record names a broker reference on a loopback endpoint, which the rule accepts, and its three raw-key refusals are unchanged.

Until 5880893901 was posted, this body quoted the holder's in-session relay of the same ruling.

4abc6d4d realizes it, and d240fd50 answers SonarCloud's complexity note on it. 5167084c and 286655f3 complete it on the wire, because a followed redirect or an environment proxy would have sent the credential by another route. See What changes for the rule and The falsifier for the cases.

Seven mutants of the rule, each killed by the named tests:

mutant	tests that fail
the declaration check removed	10: every refused route, and the operator door
a case-sensitive test for "is this http?"	5, including HTTP:// to another host and Http://localhost.evil.com
the host matched as a prefix	6, including localhost.evil.com and 127.0.0.1.evil.com
::1 dropped from LOOPBACK_HOSTS	3, including the IPv6 declaration and the resolver's IPv6 control
the resolver's own check removed	4: every route the resolver must read nothing for
a case-sensitive match	6, including LOCALHOST and hTTp://127.0.0.1
a URL parser's reading of the host	3: the backslash case, in the predicate and in the resolver, and a leading space

Readings, for Brett to overrule if he wishes:

• The three hosts count only as the ruling spells them. 127.0.0.2, [0:0:0:0:0:0:0:1] and localhost. are refused, which fails closed. Widening to all of 127.0.0.0/8 would change one constant.
• The scheme check is case-sensitive and unchanged from main, so it refuses a mixed-case scheme at declaration before this rule is asked. The predicate's case-blind reading is what the resolver's own check relies on.
• The reference forms are case-sensitive, so ENV:NAME or Keyring:… is a broker's reference, which needs its broker. Copilot's run at 5167084c left an unposted note at that check.
• 3f14bb96 refuses a broker's intake answer in a built-in form. That is the broker's enrolment answer, not its token's route, so this PR reads the ruling's "leave the broker path as it is today" as still met. The token is presented exactly as at main.

For the holder: downstream, none of it edited here

• openXdox-code tests/test_doxchat_model_intake.py asserts, in two places, that the intake flow's served kinds equal list(doxbench_binding.AUTH_KINDS). With none appended, both fail at T086's pin.
  • The flow is right to offer only the two kinds a broker enrols, so those assertions need to name them: openDox now pins that relation in test_the_console_flow_offers_every_kind_a_broker_enrols.
  • The file sits in openXdox-code's declared exclusion (doc_health). For T086.
• openxFactory cli-help-tree.golden.txt changes at T094's pin: --auth-kind {api_key,oauth,none}, an optional --credential-ref, and an optional broker invocation.
• doxbench_install.brokered_catalog's data_handling says "leaves this host: … a short-lived token the credential broker minted". That is false for a none binding to a local server and for a built-in one. doxbench_install.py is P3-D's file. T081 has since landed (T081, 16.4: "no model configured" is a state, shown before any turn (plan 034) #74) and moved the sentence into BROKERED_DATA_HANDLING, unchanged, so the item stands for that file's owner. Copilot's summary at 05cb1c70 names it too.
• The console's intake route enrols broker bindings only. For a none kind sent through it, the binding it would build is refused, and the route answers with that reason. test_the_consoles_intake_shaped_binding_still_builds holds the refusal. Enrolling env:, keyring or none bindings from the console would be a feature of its own.
• A gap that Broker-path credential hardening (follows T080): a minted token keeps a built-in credential's rules (plan 034) #64 closes, found by Copilot there at e1a6cb0f. At this head, a provider answer nested past the recursion limit escapes the shared parse in _post_to_provider as a RecursionError, on every path, as it does on main's broker path.
  • Measured at 4948e6dd on the built-in path: the RecursionError escapes dispatch, and its traceback keeps _post_to_provider's frame. That frame's request holds the key in its Authorization header (_post_to_provider.request.Authorization).
  • No kept local discloses the key by its repr, which is what this PR's frame tests measure.
  • openDox-code#64 refuses such an answer as DIAG_PROVIDER_MALFORMED at that parse (da9e639a, then a271d307), with a case for each credential source.
  • The holder decided it stays in Broker-path credential hardening (follows T080): a minted token keeps a built-in credential's rules (plan 034) #64 (2026-10-02). T080, 16.3: the credential stays a reference, and a raw key is refused (plan 034) #63 and Broker-path credential hardening (follows T080): a minted token keeps a built-in credential's rules (plan 034) #64 land back to back after T063, so the window is short, and the fix changes the broker path's failure too, which T080's ruling leaves to Broker-path credential hardening (follows T080): a minted token keeps a built-in credential's rules (plan 034) #64.

The broker path's pre-existing gaps, left here as the ruling says, and closed by #64

Each of these is at main, and only item 3 moves here, as noted. This PR asked whether the broker path should follow the built-in path's pattern. Brett Heap answered "Yes, separate phase-3 draft (Recommended)", openxFactory#656 comment 5890601202. openDox-code#64, stacked on this branch, closes all four, and T080's scope is unchanged.

1. The token is presented over plain http:// to any host. test_the_loopback_rule_is_the_built_in_resolvers_alone pins that scope.
2. The default opener follows redirects, and the environment's proxies, with the token on the request.
3. A provider-unreachable refusal chains urllib's error, and that error's frames hold the token in their locals. Measured: do_open.headers, _send_request.headers and send.data. Since 645280ac, an http.client.HTTPException on a broker's turn lands on that refusal too, where it escaped before, so this item covers it as well.
4. The token is not checked for presentability, so one outside latin-1 fails in urllib as DIAG_PROVIDER_UNREACHABLE.

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

This PR makes credential references the only persisted credential representation: binding validation rejects raw keys and keyed URLs, records select exactly one broker, built-in, or no-credential resolver, and provider dispatch resolves built-in references at request time or sends no credential for none bindings. CLI behavior, custody messaging, broker safeguards, and extensive regression tests are updated accordingly.

Sequence diagram for built-in credential resolution per provider request

sequenceDiagram
    participant Client
    participant Port as BrokeredProviderPort
    participant Resolver as resolve_credential_reference
    participant EnvOrKeyring as Environment_or_OS_Keyring
    participant Provider

    Client->>Port: dispatch(prompt_envelope)
    Port->>Resolver: resolve_credential_reference(binding)
    Resolver->>EnvOrKeyring: Read referenced value at call time
    EnvOrKeyring-->>Resolver: credential value
    Resolver-->>Port: credential
    Port->>Provider: POST request with Authorization Bearer credential
    Provider-->>Port: response
    Port-->>Client: assistant response

Loading

Sequence diagram for none-auth provider dispatch

sequenceDiagram
    participant Client
    participant Port as BrokeredProviderPort
    participant Provider

    Client->>Port: dispatch(prompt_envelope)
    Port->>Provider: POST request without Authorization header
    Provider-->>Port: response
    Port-->>Client: assistant response
    Note over Port,Provider: A 401 becomes DIAG_PROVIDER_REFUSED with no retry

Loading

Flow diagram for credential resolver selection and validation

flowchart TD
    A[Declare model provider binding] --> B{Endpoint carries a credential?}
    B -- Yes --> X[Refuse with ENDPOINT_CARRIES_A_CREDENTIAL]
    B -- No --> C{auth_kind is none?}
    C -- Yes --> D{credential_ref and broker_argv absent?}
    D -- No --> Y[Refuse binding]
    D -- Yes --> N[NO_CREDENTIAL]
    C -- No --> E{credential_ref uses env: or keyring:?}
    E -- Yes --> F{broker_argv absent?}
    F -- No --> Y
    F -- Yes --> G[CREDENTIAL_FROM_BUILT_IN_RESOLVER]
    E -- No --> H{broker_argv present?}
    H -- No --> Y
    H -- Yes --> I[CREDENTIAL_FROM_BROKER]

Loading

File-Level Changes

Change	Details	Files
Enforce credential references and reject raw credentials at binding declaration.	Reuse the product URL credential detector before scheme validation with a fixed non-leaking diagnostic. Reject credential-shaped extra fields and validate built-in reference syntax without reading referenced values. Allow resolver-specific omissions while preserving broker requirements for ordinary references.	src/opendox/doxbench_binding.py src/opendox/cli_model_binding.py
Add resolver selection for brokered, built-in, and credential-free bindings.	Add the explicit none authentication kind and enforce exactly one resolver per record. Classify env: and keyring: references as built-in-resolver bindings, rejecting a broker alongside them. Expose resolver-specific custody and removal notices and normalize optional stored fields.	src/opendox/doxbench_binding.py src/opendox/cli_model_binding.py
Implement call-time built-in credential resolution and no-broker provider dispatch.	Resolve environment and OS keyring references per request with fixed diagnostics for unusable values, missing dependencies, and backend failures. Present resolved credentials only as bearer authorization headers, with no caching, ledger entries, retries, or persistence. Send none bindings without authorization, refuse 401s without retry, and prevent broker operations for non-broker bindings.	src/opendox/doxbench_provider.py
Expand coverage for credential safety, resolver behavior, none bindings, and operator workflows.	Test URL and field refusal, resolver parsing and rotation, keyring failure handling, secret non-disclosure, and fixed diagnostic reachability. Test none request behavior, record round trips, custody messaging, CLI declaration/list/remove flows, and set-credential refusal without reading input. Verify the resolver implementation remains isolated to the provider module.	tests/test_model_provider_broker.py

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Address the endpoint-size handling and credential encoding validation findings.

Review effort: Lite
Findings: None

What changed in this PR

Adds credential-reference resolution and unauthenticated model-provider bindings while rejecting raw credentials.

Changes:

• Rejects credential-bearing URLs and unknown secret fields.
• Supports environment/keyring references and auth_kind=none.
• Updates CLI behavior and expands provider tests.

File	Summary
tests/​test_model_provider_broker.py	Tests credential refusal, resolution, unauthenticated behavior, and CLI handling.
src/​opendox/​doxbench_provider.py	Resolves references and dispatches provider requests.
src/​opendox/​doxbench_binding.py	Validates binding credentials and resolver combinations.
src/​opendox/​cli_model_binding.py	Supports resolver-specific and brokerless bindings.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot review overview

🟡 Changes recommended

Credentialed redirects may forward secrets to another host, and endpoint validation has unresolved scheme and authority issues.

Review effort: Lite
Findings: 1 · 1

Open (2)

• Redirects can leak credentials to untrusted endpoints · New
• Auth kind disclosure is not derived from supported kinds · New

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical credential exposure and additional endpoint, redirect, and disclosure issues remain.

Review effort: Lite
Findings: 2 · 1

Open (3)

• Raw credentials leak through exception tracebacks · New
• Redirects can leak credentials to untrusted endpoints
• Auth kind disclosure is not derived from supported kinds

[Copilot]

Copilot review overview

🔵 Needs a closer look

A shared HTTP exception handler alters broker-backed behavior contrary to the stated contract; scope it or update the contract and tests.

Review effort: Lite
Findings: None

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[Copilot]

Copilot review overview

🔵 Needs a closer look

Update catalog privacy metadata for none and locally resolved credentials, and clarify the endpoint diagnostic for none.

Review effort: Lite
Findings: None

[brettheap]

READY at 05cb1c7 — phase 3 is open (T063 landed, #1218 → a883bbf6); T079 (#62) landed as 2fc714d; Brett: draft phase 3 ahead, land in plan order when green. The holder checked: validate and SonarCloud green (0 issues), Copilot's latest review has no findings, 0 unresolved threads; adversarial-review M2/M3/M5/L4 folded in; dependent #64 retargeted to main and not READY. Lane: openxfactory-4 (openXfactory-4-openDox_extraction)

[sourcery-ai]

Sorry @brettheap, your pull request is larger than the review limit of 150,000 diff characters

[brettheap]

Lane: openxfactory-4 (openXfactory-4-openDox_extraction)

LANDED — lane openxfactory-4, 2026-10-03T01:48:01Z, PR #63 → 1130e99 (opensoft/openDox-code main; plain gate)

Brett: land phase 1 / phase 2 PRs when green