@voxgig/sdkgen 4.19.1 → 4.20.0

package/project/.sdk/tm/cpp/utility/pipeline.hpp

@@ -15,6 +15,19 @@
 
 #include "../core/types.hpp"
 
+// prepareAuth is GENERATED, not templated: WHERE the credential goes -
+// header, query or cookie, and under what name - is a fact about THIS API
+// (apidef resolves it into main.kit.info.security), and this file can only
+// hold one answer. It used to hold `authorization`, so an apiKey-in-query
+// API got a header it does not read. The component is
+// src/cmp/cpp/PrepareAuth_cpp.ts; the emitted header defines
+// `sdk::util::prepareAuth` exactly as this file used to, and register_all
+// below still binds it.
+//
+// Included HERE, outside the namespace: the generated header opens its own
+// `namespace sdk { namespace util {`.
+#include "prepare_auth.hpp"
+
 namespace sdk {
 namespace util {
 
@@ -1018,45 +1031,11 @@ inline std::string preparePath(CtxPtr ctx) {
 }
 
 // ---- prepareAuth ------------------------------------------------------
-
-inline SpecPtr prepareAuth(CtxPtr ctx) {
-  SpecPtr spec = ctx->spec;
-  if (!spec) throw ctx->makeError("auth_no_spec", "Expected context spec property to be defined.");
-
-  static const std::string HEADER_AUTH = "authorization";
-  static const std::string NOT_FOUND = "__NOTFOUND__";
-
-  Value headers = spec->headers;
-  Value options = ctx->client->optionsMap();
-
-  if (is_nullish(getp(options, "auth"))) {
-    map_remove(headers, HEADER_AUTH);
-    return spec;
-  }
-
-  Value apikey = getp(options, "apikey", Value(NOT_FOUND));
-
-  bool skip = false;
-  if (is_nullish(apikey)) {
-    skip = true;
-  } else if (apikey.is_string() && (apikey.as_string() == NOT_FOUND || apikey.as_string().empty())) {
-    skip = true;
-  }
-
-  if (skip) {
-    map_remove(headers, HEADER_AUTH);
-  } else {
-    std::string authPrefix = as_str(Struct::getpath(options, {"auth", "prefix"}));
-    std::string apikeyVal = apikey.is_string() ? apikey.as_string() : "";
-    if (authPrefix.empty()) {
-      map_put(headers, HEADER_AUTH, Value(apikeyVal));
-    } else {
-      map_put(headers, HEADER_AUTH, Value(authPrefix + " " + apikeyVal));
-    }
-  }
-
-  return spec;
-}
+//
+// GENERATED into utility/prepare_auth.hpp, included at the top of this file
+// (see the note there). `util::prepareAuth` keeps its name, its signature
+// and its binding in register_all below; only the three-way choice of WHERE
+// the credential goes moved out, because a template cannot make it.
 
 // ---- transformRequest -------------------------------------------------
 
@@ -1079,10 +1058,27 @@ inline Value transformRequest(CtxPtr ctx) {
 inline const char* OPTSPEC_JSON() {
   return "{"
     "\"apikey\": \"\","
+    // The SECOND credential, for the HTTP Basic scheme
+    // (base64(apikey:secret)). main.kit.optspec names it and this copy did
+    // not, and validate DROPS a top-level key this spec does not name - so a
+    // caller that supplied `secret` never had it reach prepareAuth.
+    "\"secret\": \"\","
     "\"base\": \"http://localhost:8000\","
     "\"prefix\": \"\","
     "\"suffix\": \"\","
-    "\"auth\": { \"prefix\": \"\" },"
+    // WHERE the credential goes and under what name, plus the HTTP Basic
+    // switch. `Struct::validate` SILENTLY DROPS a key this spec does not
+    // declare - it does not reject it - so without these three the generated
+    // config's own auth block was trimmed back to `prefix` on the way in and
+    // the SDK could not see its own scheme. MEASURED, not assumed: a client
+    // built from a Basic-scheme model reported `auth={prefix:Basic}` before
+    // this line and `auth={basic:true,in:,name:,prefix:Basic}` after, and an
+    // apiKey-in-query model now reports `in:query,name:token` where it used
+    // to report neither. '' means "take what the spec said", which is what
+    // prepare_auth was generated from. Mirrors main.kit.optspec.auth in
+    // @voxgig/sdkgen/model/sdkgen.aon.
+    "\"auth\": { \"prefix\": \"\", \"basic\": false,"
+    "          \"in\": \"\", \"name\": \"\" },"
     "\"headers\": { \"`$CHILD`\": \"`$STRING`\" },"
     "\"allow\": {"
     "  \"method\": \"GET,PUT,POST,PATCH,DELETE,OPTIONS\","

package/project/.sdk/tm/csharp/utility/MakeOptions.cs

@@ -174,10 +174,21 @@ public static partial class SdkUtility
             // `basic` and `secret`: HTTP Basic Auth needs a second credential
             // and a flag to say the pair is Basic rather than a single bearer
             // token.
+            //
+            // `in` and `name`: WHERE the credential goes and UNDER WHAT NAME.
+            // apidef resolves both from the spec's securityScheme into
+            // main.kit.info.security, and the generated config carries them
+            // whenever they differ from header/Authorization. This map is
+            // CLOSED - validate rejects any key it does not declare - so
+            // without these two an apiKey-in-query SDK fails to construct on
+            // its own config with "Unexpected keys at field auth: in, name".
+            // '' means "take what the spec said".
             ["auth"] = new Dictionary<string, object?>
             {
                 ["prefix"] = "",
                 ["basic"] = false,
+                ["in"] = "",
+                ["name"] = "",
             },
             ["headers"] = new Dictionary<string, object?>
             {

package/project/.sdk/tm/elixir/lib/projectname/utility.ex

@@ -10,6 +10,12 @@ defmodule ProjectName.Utility do
   alias Voxgig.Struct, as: S
   alias ProjectName.Helpers, as: H
   alias ProjectName.{Context, Spec, Result, Response, Operation}
+  # prepare_auth IS GENERATED, not templated: where the credential goes
+  # (header | query | cookie, and under what name) is a fact about the API,
+  # which apidef resolves into main.kit.info.security and a template cannot
+  # express. It lives in ProjectName.PrepareAuth, emitted by
+  # src/cmp/elixir/PrepareAuth_elixir.ts into lib/<app>/prepare_auth.ex.
+  alias ProjectName.PrepareAuth
 
   @default_user_agent "Mozilla/5.0 (compatible; ProjectNameSDK/1.0)"
 
@@ -41,7 +47,7 @@ defmodule ProjectName.Utility do
       {"make_spec", &make_spec_impl/1},
       {"make_url", &make_url_impl/1},
       {"param", &param_impl/2},
-      {"prepare_auth", &prepare_auth_impl/1},
+      {"prepare_auth", &PrepareAuth.prepare_auth_impl/1},
       {"prepare_body", &prepare_body_impl/1},
       {"prepare_headers", &prepare_headers_impl/1},
       {"prepare_method", &prepare_method_impl/1},
@@ -307,7 +313,18 @@ defmodule ProjectName.Utility do
         "suffix" => "",
         # `basic` and `secret`: HTTP Basic Auth needs a second credential and
         # a flag to say the pair is Basic rather than a single bearer token.
-        "auth" => %{"prefix" => "", "basic" => false},
+        #
+        # `in` and `name` say WHERE the credential goes and under what name
+        # (header | query | cookie). The generated config carries them
+        # whenever the spec's scheme is not the header/Authorization default,
+        # and this port's validate REJECTS a key the spec does not declare -
+        # so without them an apiKey-in-query SDK cannot be CONSTRUCTED at all:
+        #
+        #   ** (Voxgig.Struct.Error) Unexpected keys at field auth: in, name
+        #
+        # "" means "take what the spec said", which is what the generated
+        # prepare_auth was built from.
+        "auth" => %{"prefix" => "", "basic" => false, "in" => "", "name" => ""},
         "headers" => %{"`$CHILD`" => "`$STRING`"},
         "allow" => %{
           "method" => "GET,PUT,POST,PATCH,DELETE,OPTIONS",
@@ -1391,36 +1408,6 @@ defmodule ProjectName.Utility do
     end
   end
 
-  def prepare_auth_impl(ctx) do
-    spec = S.getprop(ctx, "spec")
-
-    if spec == nil do
-      {nil, Context.make_error(ctx, "auth_no_spec", "Expected context spec property to be defined.")}
-    else
-      headers = S.getprop(spec, "headers")
-      options = opts_map(S.getprop(ctx, "client"))
-
-      if S.getprop(options, "auth") == nil do
-        S.delprop(headers, "authorization")
-        {spec, nil}
-      else
-        apikey = S.getprop(options, "apikey", "__NOTFOUND__")
-
-        if (is_binary(apikey) and apikey == "__NOTFOUND__") or apikey == nil or apikey == "" do
-          S.delprop(headers, "authorization")
-        else
-          ap = S.getpath(options, "auth.prefix")
-          auth_prefix = if is_binary(ap), do: ap, else: ""
-          apikey_val = if is_binary(apikey), do: apikey, else: ""
-          hv = if auth_prefix != "", do: auth_prefix <> " " <> apikey_val, else: apikey_val
-          S.setprop(headers, "authorization", hv)
-        end
-
-        {spec, nil}
-      end
-    end
-  end
-
   # ---- result_* ------------------------------------------------------------
 
   def result_basic_impl(ctx) do

package/project/.sdk/tm/java/utility/MakeOptions.java

@@ -96,10 +96,22 @@ final class MakeOptions {
     Map<String, Object> optspec = (Map<String, Object>) Json.parse(
         "{"
         + "\"apikey\": \"\","
+        // The SECOND credential, for the HTTP Basic scheme
+        // (base64(apikey:secret)). Named by main.kit.optspec but missing
+        // here, and validate drops what it does not name — so a caller
+        // that supplied `secret` never had it reach prepareAuth.
+        + "\"secret\": \"\","
         + "\"base\": \"http://localhost:8000\","
         + "\"prefix\": \"\","
         + "\"suffix\": \"\","
-        + "\"auth\": { \"prefix\": \"\" },"
+        // WHERE the credential goes and under what name, plus the HTTP
+        // Basic switch. `Struct.validate` DROPS a key this spec does not
+        // name, so without these three the generated Config's auth block
+        // was trimmed back to `prefix` on the way in and the SDK could not
+        // see its own scheme. Mirrors main.kit.optspec.auth in
+        // @voxgig/sdkgen/model/sdkgen.aon, which ts builds its OPTSPEC from.
+        + "\"auth\": { \"prefix\": \"\", \"basic\": false,"
+        + "          \"in\": \"\", \"name\": \"\" },"
         + "\"headers\": { \"`$CHILD`\": \"`$STRING`\" },"
         + "\"allow\": {"
         + "  \"method\": \"GET,PUT,POST,PATCH,DELETE,OPTIONS\","

package/project/.sdk/tm/kotlin/utility/MakeOptions.kt

@@ -82,10 +82,23 @@ fun makeOptions(ctx: Context): MutableMap<String, Any?> {
   val optspec = Json.parse(
     "{" +
       "\"apikey\": \"\"," +
+      // The SECOND credential, for the HTTP Basic scheme
+      // (base64(apikey:secret)). Named by main.kit.optspec but missing here,
+      // and validate drops what it does not name - so a caller that supplied
+      // `secret` never had it reach prepareAuth.
+      "\"secret\": \"\"," +
       "\"base\": \"http://localhost:8000\"," +
       "\"prefix\": \"\"," +
       "\"suffix\": \"\"," +
-      "\"auth\": { \"prefix\": \"\" }," +
+      // WHERE the credential goes and UNDER WHAT NAME, plus the HTTP Basic
+      // switch. This map is CLOSED - Struct.validate drops, or rejects, a key
+      // it does not declare - so without these three the generated Config's
+      // auth block is trimmed back to `prefix` on the way in and an
+      // apiKey-in-query SDK cannot see its own scheme. '' means "take what
+      // the spec said". Mirrors main.kit.optspec.auth in
+      // @voxgig/sdkgen/model/sdkgen.aon, which ts builds its OPTSPEC from.
+      "\"auth\": { \"prefix\": \"\", \"basic\": false," +
+      "          \"in\": \"\", \"name\": \"\" }," +
       "\"headers\": { \"`\$CHILD`\": \"`\$STRING`\" }," +
       "\"allow\": {" +
       "  \"method\": \"GET,PUT,POST,PATCH,DELETE,OPTIONS\"," +

package/project/.sdk/tm/kotlin/utility/Prepare.kt

@@ -2,12 +2,21 @@ package KOTLINPACKAGE.utility
 
 import KOTLINPACKAGE.core.Context
 import KOTLINPACKAGE.core.Helpers
-import KOTLINPACKAGE.core.Spec
 import KOTLINPACKAGE.utility.struct.Struct
 
-private const val HEADER_AUTH = "authorization"
-private const val OPTION_APIKEY = "apikey"
-private const val NOT_FOUND = "__NOTFOUND__"
+// prepareAuth IS NOT HERE. It moved to utility/PrepareAuth.kt, which is
+// GENERATED from the model rather than copied from tm/: where the credential
+// goes (header, query parameter or cookie) and under what name are facts
+// about the API, resolved by apidef into main.kit.info.security, and a
+// template can only carry one answer. Hardcoding `authorization` here is
+// exactly why an apiKey-in-query API got a header it does not read.
+//
+// It is still a top-level function in THIS package, so nothing changed for
+// its callers: Register.kt still binds `u.prepareAuth = ::prepareAuth`.
+// See src/cmp/kotlin/PrepareAuth_kotlin.ts.
+//
+// HEADER_AUTH, OPTION_APIKEY and NOT_FOUND went with it - they were
+// file-private and nothing else in this file used them.
 
 private val METHOD_MAP: Map<String, String> = mapOf(
   "create" to "POST",
@@ -79,48 +88,6 @@ fun param(ctx: Context, paramdef: Any?): Any? {
   return v
 }
 
-fun prepareAuth(ctx: Context): Spec {
-  val spec = ctx.spec
-    ?: throw ctx.makeError("auth_no_spec", "Expected context spec property to be defined.")
-
-  val headers = spec.headers
-  val options = ctx.client!!.optionsMap()
-
-  // Public APIs that need no auth omit the options.auth block entirely.
-  if (options["auth"] == null) {
-    headers.remove(HEADER_AUTH)
-    return spec
-  }
-
-  val apikey = Struct.getprop(options, OPTION_APIKEY, NOT_FOUND)
-
-  var skip = false
-  if (apikey == null) {
-    skip = true
-  } else if (apikey is String && (NOT_FOUND == apikey || "" == apikey)) {
-    skip = true
-  }
-
-  if (skip) {
-    headers.remove(HEADER_AUTH)
-  } else {
-    var authPrefix = ""
-    val ap = Struct.getpath(options, listOf("auth", "prefix"))
-    if (ap is String) {
-      authPrefix = ap
-    }
-    val apikeyVal = if (apikey is String) apikey else ""
-    // Empty prefix (raw apiKey credential) must not add a leading space.
-    if ("" == authPrefix) {
-      headers[HEADER_AUTH] = apikeyVal
-    } else {
-      headers[HEADER_AUTH] = "$authPrefix $apikeyVal"
-    }
-  }
-
-  return spec
-}
-
 fun prepareBody(ctx: Context): Any? {
   if ("data" == ctx.op.input) {
     return ctx.utility!!.transformRequest(ctx)

package/project/.sdk/tm/ocaml/Makefile

@@ -59,8 +59,18 @@ CORPUS = ../.sdk/test/test.json
 
 # A gated feature's modules come AFTER sdk_features.ml (a feature module
 # opens it) and BEFORE sdk_config.ml (the generated factory names them).
+#
+# sdk_prepare_auth.ml is GENERATED (src/cmp/ocaml/PrepareAuth_ocaml.ts), not
+# copied from the template tree: WHERE the credential goes - a header, a query
+# parameter or a cookie, and under what name - is a fact about the API, and a
+# template can hold only one answer. Its position is STATED here because
+# ocamlc compiles a module before anything that uses it and has no link-time
+# reordering: after sdk_helpers.ml, whose client/value accessors it uses, and
+# before sdk_runtime.ml, which binds `prepare_auth_util` to it and registers
+# that in the utility record.
 RUNTIME = utility/vregex.ml utility/voxgig_struct.ml sdk_json.ml \
-  sdk_types.ml sdk_helpers.ml sdk_runtime.ml sdk_features.ml $(FEATURE_SRC)
+  sdk_types.ml sdk_helpers.ml sdk_prepare_auth.ml sdk_runtime.ml \
+  sdk_features.ml $(FEATURE_SRC)
 
 # The vendored corpus engine plus the adapter that drives it. Order matters:
 # the adapter references the vendored module.

package/project/.sdk/tm/ocaml/sdk_helpers.ml

@@ -78,6 +78,21 @@ let cu (ctx : ctx) : utility =
 let cc (ctx : ctx) : sdk_client =
   match ctx.c_client with Some c -> c | None -> failwith "context client not set"
 
+(* ----- client options -----
+ * A CLONE of the client's options, so a utility that writes into the map it
+ * is handed cannot mutate the client's own (the secrets feature relies on
+ * that: it rewrites the credential in the fetchdef, never in the shared
+ * options).
+ *
+ * Lives HERE, beside the other client accessors, rather than in Sdk_runtime
+ * where it began: the generated sdk_prepare_auth.ml reads it and is compiled
+ * BEFORE Sdk_runtime (ocamlc compiles a module before anything that uses it
+ * and has no link-time reordering), so a definition in Sdk_runtime is out of
+ * reach. Sdk_runtime opens this module, so its own call sites are unchanged.
+ *)
+let client_options_map (client : sdk_client) : value =
+  match clone client.cl_options with Map _ as m -> m | _ -> empty_map ()
+
 (* ----- per-op feature scratch ----- *)
 
 let scratch_get (ctx : ctx) (key : string) : value option =

package/project/.sdk/tm/ocaml/sdk_runtime.ml

@@ -239,9 +239,6 @@ let make_context_impl (cs : ctxspec) (basectx : ctx option) : ctx =
 (* utilities                                                           *)
 (* ------------------------------------------------------------------ *)
 
-let client_options_map (client : sdk_client) : value =
-  match clone client.cl_options with Map _ as m -> m | _ -> empty_map ()
-
 let clean_util (_ctx : ctx) (v : value) : value = v
 
 let make_error_util (ctx : ctx) (err_opt : sdk_error option) : value =
@@ -537,26 +534,24 @@ let graphql_errors_util (ctx : ctx) : bool =
         true
       end
 
-let prepare_auth_util (ctx : ctx) : (spec option * sdk_error option) =
-  match ctx.c_spec with
-  | None -> (None, Some (ctx_make_error ctx "auth_no_spec" "Expected context spec property to be defined."))
-  | Some spec ->
-    let headers = spec.sp_headers in
-    let options = client_options_map (cc ctx) in
-    (match getp options "auth" with
-     | Noval | Null -> ignore (delprop headers (Str "authorization")); (Some spec, None)
-     | _ ->
-       let apikey = getprop ~alt:(Str "__NOTFOUND__") options (Str "apikey") in
-       let is_notfound = (match apikey with Str "__NOTFOUND__" -> true | _ -> false) in
-       if is_notfound || is_noval apikey || apikey = Str "" then
-         ignore (delprop headers (Str "authorization"))
-       else begin
-         let auth_prefix = match getpath_s options "auth.prefix" with Str s -> s | _ -> "" in
-         let apikey_val = match apikey with Str s -> s | _ -> "" in
-         let authval = if auth_prefix <> "" then auth_prefix ^ " " ^ apikey_val else apikey_val in
-         setp headers "authorization" (Str authval)
-       end;
-       (Some spec, None))
+(* prepare_auth lives in its own GENERATED module, Sdk_prepare_auth
+ * (src/cmp/ocaml/PrepareAuth_ocaml.ts), and this is the binding every caller
+ * still reaches it by.
+ *
+ * WHY IT LEFT THIS FILE. WHERE the credential goes - a header, a query
+ * parameter or a cookie, and under what name - is a fact about the API, which
+ * apidef resolves into main.kit.info.security. A template can hold only one
+ * answer, so this one hardcoded an `authorization` header and an
+ * apiKey-in-query API (joplin's `?token=`) got a header it does not read and
+ * never got the parameter it does. The three placements need three different
+ * bodies, so the body is generated and the name stays here.
+ *
+ * The alias is not cosmetic: `new_utility`/`register` below bind
+ * `u_prepare_auth` to this name, make_spec_util calls it through the utility
+ * record, the secrets feature re-runs it the same way, and
+ * test/primary_utility_test.ml reaches `prepare_auth_util` by `open
+ * Sdk_runtime` to drive the shared corpus section. All of that is unchanged. *)
+let prepare_auth_util = Sdk_prepare_auth.prepare_auth_util
 
 (* ----- transforms / result helpers ----- *)
 
@@ -942,8 +937,19 @@ let opt_spec_value () : value =
     ("prefix", Str "");
     ("suffix", Str "");
     (* `basic` and `secret`: HTTP Basic Auth needs a second credential and a
-       flag to say the pair is Basic rather than a single bearer token. *)
-    ("auth", jo [("prefix", Str ""); ("basic", Bool false)]);
+       flag to say the pair is Basic rather than a single bearer token.
+
+       `in` and `name`: WHERE the credential goes and UNDER WHAT NAME -
+       header (the default, `authorization`), query or cookie. This shape is
+       CLOSED, so a config carrying a key it does not list fails validation
+       and the client cannot be constructed at all: without these two an
+       apiKey-in-query SDK could not build its options, because the generated
+       sdk_config.ml now carries them whenever the spec's scheme is not the
+       header/Authorization default. They mirror main.kit.optspec.auth in
+       @voxgig/sdkgen/model/sdkgen.aon, and '' means "whatever the spec
+       resolved", which is what the generated prepare_auth was built from. *)
+    ("auth", jo [("prefix", Str ""); ("basic", Bool false);
+                 ("in", Str ""); ("name", Str "")]);
     ("headers", jo [("`$CHILD`", Str "`$STRING`")]);
     ("allow", jo [("method", Str "GET,PUT,POST,PATCH,DELETE,OPTIONS");
                   ("op", Str "create,update,load,list,remove,command,direct,graphql")]);

package/project/.sdk/tm/ocaml/test/feature/secrets/t_secrets.ml

@@ -12,8 +12,11 @@
  *   - the client is LIVE (Sdk_client.make), so `options.system.fetch` really
  *     is the transport and the feature's wrapper sits above it - never the
  *     test-mode mock, which replaces the fetcher and hides the seam;
- *   - every assertion reads the authorization header the RECORDER received,
- *     never the options map, which this feature never writes;
+ *   - every assertion reads what the RECORDER received, never the options
+ *     map, which this feature never writes. The FEATURE writes the
+ *     authorization header (see the header-only note on placed_cred_of
+ *     below), so its cases read that; the three cases where the feature is
+ *     inactive or missed read whatever the generated prepare_auth placed;
  *   - a refusal must carry the PROVIDER'S OWN message (sekreto's wording),
  *     not any error;
  *   - beside every refusal is a CONTROL leg: the same construction with a
@@ -87,7 +90,94 @@ let api_calls (r : recorder) : value list =
 let token_calls (r : recorder) : value list =
   List.filter (fun c -> is_token (match getp c "url" with Str u -> u | _ -> "")) !(r.calls)
 
-(* The authorization header the i-th API call carried, or Noval. *)
+(* WHERE prepare_auth PUT THE CREDENTIAL, asked of the generated module
+ * rather than assumed to be a header.
+ *
+ * prepare_auth is GENERATED (Sdk_prepare_auth) from the API's own security
+ * scheme, so it is not always a header: an apiKey-in-query API - joplin's
+ * `?token=` - carries the credential in the URL, and a cookie scheme in the
+ * shared `cookie` header. Reading `authorization` outright made
+ * `inactive.apikey_option_behaves_as_before` a HEADER assertion, so it
+ * failed on a query-placement SDK that was carrying its credential
+ * perfectly well.
+ *
+ * KNOWN GAP, DELIBERATELY NOT PAPERED OVER HERE: the FEATURE'S own rewrite
+ * (secrets_feature.ml) still writes `authorization` whatever the scheme
+ * says, so a chain-resolved secret does NOT follow the placement. Every
+ * target's secrets feature does the same. The cases below that exercise the
+ * feature therefore keep reading the header - which is what the code
+ * actually does - and only the three cases where the feature is inactive or
+ * missed read the placed bag. Making the feature placement-aware is a
+ * separate change, across every target at once. *)
+
+(* Percent-decoding, because make_url escapes a query value on the way in.
+ * `+` is NOT treated as a space: that is form encoding, and a literal `+`
+ * in a token must survive. *)
+let pct_decode (s : string) : string =
+  let hex c =
+    if c >= '0' && c <= '9' then Char.code c - 48
+    else if c >= 'a' && c <= 'f' then Char.code c - 87
+    else if c >= 'A' && c <= 'F' then Char.code c - 55
+    else (-1) in
+  let n = String.length s in
+  let buf = Buffer.create n in
+  let i = ref 0 in
+  while !i < n do
+    if s.[!i] = '%' && !i + 2 < n && hex s.[!i + 1] >= 0 && hex s.[!i + 2] >= 0 then begin
+      Buffer.add_char buf (Char.chr ((hex s.[!i + 1] * 16) + hex s.[!i + 2]));
+      i := !i + 3
+    end
+    else (Buffer.add_char buf s.[!i]; incr i)
+  done;
+  Buffer.contents buf
+
+(* The first `name=` value in a `sep`-separated list, trimmed and optionally
+ * percent-decoded. Noval when the list has no such entry. *)
+let pair_value ?(decode = false) (raw : string) (sep : char) (name : string) : value =
+  let want = name ^ "=" in
+  let wl = String.length want in
+  let trim s =
+    let n = String.length s in
+    let b = ref 0 and e = ref n in
+    while !b < !e && s.[!b] = ' ' do incr b done;
+    while !e > !b && s.[!e - 1] = ' ' do decr e done;
+    String.sub s !b (!e - !b) in
+  let rec go = function
+    | [] -> Noval
+    | part :: rest ->
+      let part = trim part in
+      if String.length part >= wl && String.sub part 0 wl = want then
+        let v = String.sub part wl (String.length part - wl) in
+        Str (if decode then pct_decode v else v)
+      else go rest in
+  go (String.split_on_char sep raw)
+
+(* The credential one recorded fetchdef carried, read from the bag this
+ * SDK's generated prepare_auth places it in. *)
+let placed_cred_of (fd : value) : value =
+  let headers = getp fd "headers" in
+  if Sdk_prepare_auth.cred_where = "query" then
+    let url = match getp fd "url" with Str u -> u | _ -> "" in
+    (match String.index_opt url '?' with
+     | None -> Noval
+     | Some at ->
+       pair_value ~decode:true
+         (String.sub url (at + 1) (String.length url - at - 1)) '&'
+         Sdk_prepare_auth.cred_name)
+  else if Sdk_prepare_auth.cred_where = "cookie" then
+    (match headers with
+     | Map _ ->
+       (match Sdk_features.header_ci headers "cookie" with
+        | Str raw -> pair_value raw ';' Sdk_prepare_auth.cred_name
+        | _ -> Noval)
+     | _ -> Noval)
+  else
+    (match headers with
+     | Map _ -> Sdk_features.header_ci headers Sdk_prepare_auth.cred_name
+     | _ -> Noval)
+
+(* The AUTHORIZATION HEADER the i-th API call carried, or Noval - what the
+ * feature's own rewrite writes (see the note above). *)
 let auth_of (r : recorder) (i : int) : value =
   match List.nth_opt (api_calls r) i with
   | Some c -> (match getp (getp c "fetchdef") "headers" with
@@ -95,9 +185,18 @@ let auth_of (r : recorder) (i : int) : value =
       | _ -> Noval)
   | None -> Noval
 
-(* The Authorization header carries the SPEC's credential prefix, which a
- * TEMPLATE cannot know - so assert on the CREDENTIAL and let the prefix be
- * whatever this SDK's API declares. *)
+(* The same call read through the SCHEME'S placement, for the cases where no
+ * chain resolved anything and prepare_auth's own placement is what reached
+ * the wire. *)
+let placed_of (r : recorder) (i : int) : value =
+  match List.nth_opt (api_calls r) i with
+  | Some c -> placed_cred_of (getp c "fetchdef")
+  | None -> Noval
+
+(* A header credential carries the SPEC's prefix, which a TEMPLATE cannot
+ * know - so assert on the CREDENTIAL and let the prefix be whatever this
+ * SDK's API declares. A query parameter and a cookie carry no prefix at all,
+ * which the bare equality already covers. *)
 let credential_is (header : value) (token : string) : bool =
   match header with
   | Str s -> s = token || Sdk_features.ends_with s (" " ^ token)
@@ -105,6 +204,14 @@ let credential_is (header : value) (token : string) : bool =
 
 let absent (header : value) : bool = is_nullish header
 
+(* SUPPRESSION IS ABOUT EVERY BAG, not just the header. `auth: null` must
+ * leave nothing anywhere, so a suppression case asserts the authorization
+ * header AND the bag this API's scheme places its credential in - otherwise
+ * a query-placement SDK could leak `?token=...` and still read green,
+ * because the header it never uses was empty. *)
+let nothing_placed (r : recorder) (i : int) : bool =
+  absent (auth_of r i) && absent (placed_of r i)
+
 (* ---------------------------------------------------------------------- *)
 (* clients and paths                                                      *)
 (* ---------------------------------------------------------------------- *)
@@ -217,13 +324,17 @@ let () =
       let client = inactive ~sdkopts:[("apikey", Str "OPTKEY01")] fetch in
       check "ok" (res_ok (direct client));
       check_int "one call" (List.length (api_calls r)) 1;
-      check "carries OPTKEY01" (credential_is (auth_of r 0) "OPTKEY01"));
+      (* THE FEATURE IS INACTIVE HERE, so what reaches the wire is exactly
+         what the generated prepare_auth placed - in the bag this API's
+         scheme names, which for an apiKey-in-query SDK is the query string
+         and not a header. *)
+      check "carries OPTKEY01" (credential_is (placed_of r 0) "OPTKEY01"));
 
   test "inactive.no_apikey_no_header" (fun () ->
       let (r, fetch) = recorder () in
       let client = inactive fetch in
       check "ok" (res_ok (direct client));
-      check "no header" (absent (auth_of r 0)));
+      check "no header" (absent (placed_of r 0)));
 
   (* ---------------------------------------------------------------------- *)
   (* the chain                                                              *)
@@ -276,7 +387,9 @@ let () =
       let client = live fetch [("providers", ja [fn])] in
       check "ok" (res_ok (direct client));
       check_int "one call" (List.length (api_calls r)) 1;
-      check "no header" (absent (auth_of r 0));
+      (* NOTHING resolved, so the feature wrote nothing and the placed bag -
+         whichever this API's scheme names - is what must be empty. *)
+      check "no header" (absent (placed_of r 0));
       check_int "the chain was asked" !asked 1);
 
   test "chain.miss_falls_through_to_the_next_provider" (fun () ->
@@ -451,7 +564,7 @@ let () =
           [("providers", ja [jo [("kind", Str "env"); ("prefix", Str envprefix)]])] in
       check "ok" (res_ok (direct client));
       check_int "one call" (List.length (api_calls r)) 1;
-      check "no header, though the chain resolved" (absent (auth_of r 0));
+      check "nothing placed, though the chain resolved" (nothing_placed r 0);
       (* The suppression survives option validation as a present null. *)
       check "options.auth survives as a present null"
         (getprop_raw client.cl_options "auth" = Null));
@@ -461,7 +574,7 @@ let () =
       let client = live ~sdkopts:[("auth", Null); ("apikey", Str "OPTKEY01")] fetch
           [("providers", ja [working "CUSTOM01"])] in
       check "ok" (res_ok (direct client));
-      check "no header" (absent (auth_of r 0)));
+      check "nothing placed" (nothing_placed r 0));
 
   test "auth.null_suppresses_on_the_entity_path" (fun () ->
       let (r, fetch) = recorder () in
@@ -470,7 +583,7 @@ let () =
        | Ok () -> ()
        | Error msg -> failwith ("entity op failed: " ^ msg));
       check_int "reached the transport once" (List.length (api_calls r)) 1;
-      check "no header" (absent (auth_of r 0)));
+      check "nothing placed" (nothing_placed r 0));
 
   test "entity.carries_the_chain_resolved_credential" (fun () ->
       let (r, fetch) = recorder () in