@voxgig/sdkgen 4.19.1 → 4.21.0

package/project/.sdk/src/cmp/lua/Main_lua.ts

@@ -22,6 +22,8 @@ import {
 
 import { Package } from './Package_lua'
 import { Config } from './Config_lua'
+import { Schema } from './Schema_lua'
+import { PrepareAuth } from './PrepareAuth_lua'
 import { Gitignore } from './Gitignore_lua'
 import { MainEntity } from './MainEntity_lua'
 import { EntityTypes } from './EntityTypes_lua'
@@ -99,43 +101,78 @@ const Main = cmp(async function Main(props: any) {
   // syntax; the guard holds that), which the C compiler cannot read - so
   // the rule feeds the compiler from line four. Line numbers in a compiler
   // diagnostic are therefore three lower than in the file.
+  //
+  // TWO HELPERS, NOT ONE, AND THEY ARE BUILT DIFFERENTLY. The transport
+  // helper is a PROGRAM the plugins run; the mini vault's crypto is a
+  // LOADABLE MODULE the interpreter opens with package.loadlib, so it is
+  // compiled -shared -fPIC and keeps its `.so` name. Each is emitted only
+  // for the groups that actually use it: a chain of `[hashicorp]` builds
+  // no vault, and a chain of `[minivault]` opens no socket and links no
+  // TLS.
   const nativeGroups: string[] = []
+  let wantsVault = false
   each(feature, (f: any) => {
     each(f.plugin, (plugin: any) => {
       if (false === plugin.active || null == plugin.active) return
       if (0 < Object.keys(plugin.def?.lua || {}).length) {
         nativeGroups.push(f.name + '.' + plugin.name)
+        if ('minivault' === plugin.name) {
+          wantsVault = true
+        }
       }
     })
   })
 
+  // The transport helper serves every kind that reaches the network or a
+  // child process. The vault reaches neither, so a vault-only chain needs
+  // the module and not the program.
+  const wantsNet = nativeGroups.some((one) => !/\.minivault$/.test(one))
+
   if (0 < nativeGroups.length) {
     Folder({ name: 'feature' }, () => {
       Folder({ name: 'secrets' }, () => {
         File({ name: 'native.mk' }, () => {
-          Content(`# ${model.const.Name} SDK: the sekreto transport helper build.
+          Content(`# ${model.const.Name} SDK: the sekreto native helper build.
 #
 # GENERATED because a secrets plugin group is active
-# (${nativeGroups.sort().join(', ')}): the plugin provider kinds run this
-# helper for every socket and child process, since Lua 5.4 has none. An
-# SDK without an active plugin group has no such file, and its Makefile's
-# optional include of it is a no-op - nothing is compiled and OpenSSL is
-# not linked.
+# (${nativeGroups.sort().join(', ')}). Lua 5.4 has no sockets, no TLS and no
+# cryptography, so the kinds that need any of the three reach a small
+# compiled helper - and this file builds only the ones this SDK's chain
+# actually uses. An SDK without an active plugin group has no such file,
+# and its Makefile's optional include of it is a no-op: nothing is
+# compiled and nothing is linked.
 #
 # The source carries the vendoring tool's three-line provenance header in
 # lua comment syntax, which the compiler cannot read: it is fed the file
 # from line four. Compiler line numbers are therefore three lower than the
 # file's.
-NATIVE := feature/secrets/native/sekreto-net
+NATIVE := ${[
+            wantsNet ? 'feature/secrets/native/sekreto-net' : '',
+            wantsVault ? 'feature/secrets/native/sekretovault.so' : '',
+          ].filter((one) => '' !== one).join(' ')}
 
 CC ?= cc
 CFLAGS ?= -std=c11 -O2 -Wall -Wextra
 LDLIBS ?= -lssl -lcrypto
-
+${wantsNet ? `
 feature/secrets/native/sekreto-net: feature/secrets/native/sekretonet.c
 	@command -v $(CC) >/dev/null 2>&1 || { echo "secrets: a C compiler ($(CC)) is needed to build the sekreto transport helper that this SDK's plugin provider kinds run - install one, or use only the built-in provider kinds" >&2; exit 1; }
 	tail -n +4 $< | $(CC) $(CFLAGS) -x c - -o $@ $(LDLIBS)
-`)
+` : ''}${wantsVault ? `
+# The mini vault's crypto is a LOADABLE MODULE, not a program: minivault.lua
+# opens it with package.loadlib and calls luaopen_sekretovault, so it is
+# compiled -shared -fPIC and keeps the .so name that call expects. It links
+# libcrypto alone - the vault reads a file and never opens a socket, so it
+# needs no TLS.
+#
+# LUA_CFLAGS is where a consumer points the compiler at lua.h when it is not
+# on the default include path (Homebrew, a pkg-config build, a vendored Lua).
+LUA_CFLAGS ?= $(shell pkg-config --cflags lua5.4 2>/dev/null || pkg-config --cflags lua 2>/dev/null)
+
+feature/secrets/native/sekretovault.so: feature/secrets/native/sekretovault.c
+	@command -v $(CC) >/dev/null 2>&1 || { echo "secrets: a C compiler ($(CC)) is needed to build the mini vault's crypto module - install one, or use only the built-in provider kinds" >&2; exit 1; }
+	tail -n +4 $< | $(CC) $(CFLAGS) $(LUA_CFLAGS) -fPIC -shared -x c - -o $@ -lcrypto
+` : ''}`)
         })
       })
     })
@@ -193,8 +230,19 @@ self._utility.feature_hook(self._rootctx, "${name}")
   // Generate config module
   Folder({ name: '.' }, () => {
     Config({ target })
+    Schema({ target })
   })
 
+  // GENERATED, NOT COPIED. Where the credential goes is a fact about the
+  // API - header, query or cookie, under the name the spec gives - and tm/
+  // can only hold one answer. See PrepareAuth_lua.
+  //
+  // Called at the TARGET ROOT, like Config above (that Folder({name:'.'})
+  // is the root itself), because the lua tree has no src/ wrapper: the
+  // component opens the one `utility` folder that
+  // require("utility.prepare_auth") needs.
+  PrepareAuth({ target })
+
   // Generate feature factory module
   File({ name: 'features.' + target.ext }, () => {
     Content(`-- ${model.const.Name} SDK feature factory

package/project/.sdk/src/cmp/lua/Package_lua.ts

@@ -159,6 +159,7 @@ build = {
     ["config"] = "config.lua",
     ["config_shared"] = "config_shared.lua",
     ["config_plugins"] = "config_plugins.lua",
+    ["schema"] = "schema.lua",
     ["features"] = "features.lua",
 ${featureModules}  }
 }

package/project/.sdk/src/cmp/lua/PrepareAuth_lua.ts

@@ -0,0 +1,364 @@
+
+import {
+  Content,
+  File,
+  Folder,
+  cmp,
+  isAuthSuppressed,
+  isHttpBasicAuth,
+  resolveAuthIn,
+  resolveAuthName,
+  resolveAuthPrefix,
+} from '@voxgig/sdkgen'
+
+
+// WHERE THE CREDENTIAL GOES IS A FACT ABOUT THE API, so it is generated
+// rather than templated. The lua peer of PrepareAuth_ts.
+//
+// This was a static file at tm/lua/utility/prepare_auth.lua that hardcoded
+// a lower-case "authorization" HEADER. apidef has always resolved the
+// scheme's "in" and "name" into main.kit.info.security - joplin's says
+// in: "query", name: "token" - and generation dropped both. The result was
+// an SDK that sent a header the API does not read and never sent the query
+// parameter it does, so it could not authenticate at all. Four repos in
+// the cedar fleet shipped that way: joplin (token), pipedrive (api_token),
+// trello (key), lm-umbrella (apiKey).
+//
+// A template cannot fix this, because the three placements need three
+// different bodies and a template has to pick one. A component emits the
+// branch this API actually uses and nothing else - no dead query code in a
+// bearer-token SDK, and no runtime branch on a value that is fixed at
+// generation time.
+//
+// The header placement renders BYTE-FOR-BYTE what the template rendered,
+// so every header-based lua SDK regenerates with a zero diff.
+const PrepareAuth = cmp(async function PrepareAuth(props: any) {
+  const { target } = props
+  const { model } = props.ctx$
+
+  // `!isAuthSuppressed`, NOT `isAuthActive`. The latter is also false when
+  // the SPEC merely declares no security scheme (`main.kit.info.auth:
+  // false`), and those SDKs still carry a credential: optspec always
+  // declares `apikey` and makeOptions fills `options.auth` from its
+  // defaults, so the runtime guard never fired and they have always sent
+  // it. Only an explicit `main.kit.config.auth.active: false` means "no
+  // credential, ever", which is what isAuthSuppressed reads.
+  const active = !isAuthSuppressed(model)
+  const where = resolveAuthIn(model)
+  const prefix = resolveAuthPrefix(model)
+  const basic = isHttpBasicAuth(model)
+
+  // A HEADER NAME IS LOWER-CASED HERE; A QUERY OR COOKIE NAME IS NOT.
+  // Every header key the lua SDK writes is lower case (make_spec's
+  // "content-type", the secrets feature's "authorization", fetcher's
+  // lower-casing of the response headers), and HTTP header names are
+  // case-insensitive on the wire - so "Authorization" must arrive here as
+  // the "authorization" the rest of the SDK looks up. A query parameter
+  // and a cookie name are case-SENSITIVE: lm-umbrella's "apiKey" is not
+  // "apikey", and lower-casing it would break exactly the APIs this
+  // change exists to fix.
+  const cred = resolveAuthName(model)
+  const name = 'header' === where ? cred.toLowerCase() : cred
+
+  // FOLDER NESTING. Main_lua opens NO folder around this call: its
+  // Folder({name:'.'}) around Config is the target root itself, and the
+  // lua tree has no src/ wrapper (tm/lua/src holds only feature
+  // placeholders and Main's Copy excludes it). The template lived at
+  // tm/lua/utility/prepare_auth.lua, which the blanket Copy lands at
+  // <root>/utility/prepare_auth.lua - the one path
+  // require("utility.prepare_auth") in utility/register.lua resolves. So
+  // this component opens the single "utility" folder that path needs.
+  // Opening a second one would write <root>/utility/utility/, where
+  // nothing requires it.
+  Folder({ name: 'utility' }, () => {
+    File({ name: 'prepare_auth.' + target.ext }, () => {
+      Content(render({
+        project: model.const.Name,
+        active,
+        where,
+        name,
+        prefix,
+        basic,
+      }))
+    })
+  })
+})
+
+
+function render(spec: {
+  project: string, active: boolean, where: string,
+  name: string, prefix: string, basic: boolean
+}): string {
+  const head = `-- ${spec.project} SDK utility: prepare_auth\n`
+
+  // NO AUTH AT ALL. A public API's SDK gets a prepare_auth that is honest
+  // about it rather than one that deletes a header nobody set.
+  if (!spec.active) {
+    return head + `
+-- This API declares no authentication, so there is no credential to place.
+-- The function stays in the pipeline because make_spec calls it
+-- unconditionally.
+local function prepare_auth_util(ctx)
+  local spec = ctx.spec
+  if spec == nil then
+    return nil, ctx:make_error("auth_no_spec",
+      "Expected context spec property to be defined.")
+  end
+
+  return spec, nil
+end
+
+return prepare_auth_util
+`
+  }
+
+  const where = spec.where
+
+  // HTTP Basic is header-only by definition: the scheme is
+  // "Authorization: Basic base64(user:pass)". It cannot be expressed as a
+  // query parameter or a cookie, so the branch is emitted only where it
+  // can mean something.
+  const basic = spec.basic && 'header' === where
+
+  const CRED = credConst(where)
+
+  const consts =
+    `local ${CRED} = "${luastr(spec.name)}"\n` +
+    ('cookie' === where ? `local HEADER_COOKIE = "cookie"\n` : '') +
+    `local OPTION_APIKEY = "apikey"\n` +
+    (basic ? `local OPTION_SECRET = "secret"\n` : '') +
+    `local NOT_FOUND = "__NOTFOUND__"\n`
+
+  return head + `
+local vs = require("utility.struct.struct")
+
+` + consts + (basic ? BASE64 : '') + ('cookie' === where ? COOKIE_SET : '') + `
+local function prepare_auth_util(ctx)
+  local spec = ctx.spec
+  if spec == nil then
+    return nil, ctx:make_error("auth_no_spec",
+      "Expected context spec property to be defined.")
+  end
+
+${bag(where)}  local options = ctx.client:options_map()
+
+  -- Public APIs that need no auth omit the options.auth block entirely.
+  if options.auth == nil then
+${clear(where, 4)}
+    return spec, nil
+  end
+
+  local apikey = vs.getprop(options, OPTION_APIKEY, NOT_FOUND)
+` + (basic ? BASIC : '') + `
+  if apikey == nil
+    or (type(apikey) == "string" and (apikey == NOT_FOUND or apikey == ""))
+  then
+${clear(where, 4)}
+  else
+${place(where)}
+  end
+
+  return spec, nil
+end
+
+return prepare_auth_util
+`
+}
+
+
+// The constant the credential name is bound to, named for where it goes -
+// a reader of the generated file should not have to ask.
+function credConst(where: string): string {
+  return 'query' === where ? 'QUERY_AUTH' :
+    'cookie' === where ? 'COOKIE_AUTH' : 'HEADER_AUTH'
+}
+
+
+// The bag the credential lands in, per placement. A cookie rides the
+// header bag, because a cookie IS a header.
+function bag(where: string): string {
+  return 'query' === where ?
+    '  local query = spec.query\n' :
+    '  local headers = spec.headers\n'
+}
+
+
+function clear(where: string, indent: number): string {
+  const pad = ' '.repeat(indent)
+
+  if ('query' === where) {
+    return pad + 'query[QUERY_AUTH] = nil'
+  }
+
+  if ('cookie' === where) {
+    return pad + 'cookie_set(headers, nil)'
+  }
+
+  return pad + 'headers[HEADER_AUTH] = nil'
+}
+
+
+function place(where: string): string {
+  if ('query' === where) {
+    // NO PREFIX IN A QUERY STRING. "?token=Bearer%20abc" is not a thing any
+    // API reads; the prefix is a header-value convention and is dropped
+    // here deliberately rather than silently concatenated.
+    return `    -- NO PREFIX IN A QUERY STRING: "?token=Bearer%20abc" is not a thing
+    -- any API reads, so the auth.prefix a header placement space-joins is
+    -- dropped here deliberately rather than concatenated.
+    local apikey_val = ""
+    if type(apikey) == "string" then
+      apikey_val = apikey
+    end
+    query[QUERY_AUTH] = apikey_val`
+  }
+
+  if ('cookie' === where) {
+    return `    local apikey_val = ""
+    if type(apikey) == "string" then
+      apikey_val = apikey
+    end
+    -- The prefix is a header-value convention and has no meaning in a
+    -- cookie pair, so it is dropped the way a query placement drops it.
+    cookie_set(headers, apikey_val)`
+  }
+
+  // BYTE-FOR-BYTE the template's body, so a header-based SDK regenerates
+  // unchanged.
+  return `    local auth_prefix = ""
+    local ap = vs.getpath(options, "auth.prefix")
+    if type(ap) == "string" then
+      auth_prefix = ap
+    end
+    local apikey_val = ""
+    if type(apikey) == "string" then
+      apikey_val = apikey
+    end
+    -- Empty prefix (raw apiKey credential) must not add a leading space.
+    if auth_prefix == "" then
+      headers[HEADER_AUTH] = apikey_val
+    else
+      headers[HEADER_AUTH] = auth_prefix .. " " .. apikey_val
+    end`
+}
+
+
+// True HTTP Basic Auth: two credentials, base64-joined. Emitted only for a
+// header placement (see render).
+const BASIC = `
+  -- True HTTP Basic Auth needs TWO credentials, base64-joined - a single
+  -- token in the header (the branch below) can never authenticate against
+  -- an API that actually checks "Authorization: Basic base64(user:pass)".
+  if vs.getpath(options, "auth.basic") == true then
+    local secret = vs.getprop(options, OPTION_SECRET, NOT_FOUND)
+
+    if apikey == nil or secret == nil
+      or (type(apikey) == "string" and (apikey == NOT_FOUND or apikey == ""))
+      or (type(secret) == "string" and (secret == NOT_FOUND or secret == ""))
+    then
+      headers[HEADER_AUTH] = nil
+    else
+      local auth_prefix = ""
+      local ap = vs.getpath(options, "auth.prefix")
+      if type(ap) == "string" then
+        auth_prefix = ap
+      end
+      local joined = base64(tostring(apikey) .. ":" .. tostring(secret))
+      if auth_prefix == "" then
+        headers[HEADER_AUTH] = joined
+      else
+        headers[HEADER_AUTH] = auth_prefix .. " " .. joined
+      end
+    end
+
+    return spec, nil
+  end
+`
+
+
+// Lua 5.4 has no base64, and the vendored sekreto encoder lives inside the
+// OPTIONAL secrets feature - an SDK that never asked for secrets does not
+// ship it - so an HTTP Basic SDK carries its own. Emitted only in that
+// branch, so nothing else pays for it.
+const BASE64 = `
+local B64_ALPHABET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+
+
+local function base64(text)
+  local out = {}
+  local size = #text
+  local index = 1
+
+  while index <= size do
+    local rest = size - index + 1
+    local a = string.byte(text, index)
+    local b = string.byte(text, index + 1) or 0
+    local c = string.byte(text, index + 2) or 0
+    local word = (a << 16) | (b << 8) | c
+
+    local chunk = {}
+    for shift = 18, 0, -6 do
+      local at = (word >> shift) & 0x3f
+      chunk[#chunk + 1] = string.sub(B64_ALPHABET, at + 1, at + 1)
+    end
+
+    -- One trailing source byte yields two characters and "==", two yield
+    -- three and "=".
+    if rest == 1 then
+      chunk[3] = "="
+      chunk[4] = "="
+    elseif rest == 2 then
+      chunk[4] = "="
+    end
+
+    out[#out + 1] = table.concat(chunk)
+    index = index + 3
+  end
+
+  return table.concat(out)
+end
+
+`
+
+
+// A cookie header is SHARED: any other cookie the caller set rides in the
+// same string, so the credential pair is rewritten in place and everything
+// else is kept. A plain assignment would throw the caller's cookies away.
+// A nil value removes just our pair.
+const COOKIE_SET = `
+local function cookie_set(headers, value)
+  local kept = {}
+  local existing = headers[HEADER_COOKIE]
+
+  if type(existing) == "string" then
+    for pair in string.gmatch(existing, "[^;]+") do
+      local one = string.match(pair, "^%s*(.-)%s*$")
+      if one ~= "" and string.match(one, "^[^=]*") ~= COOKIE_AUTH then
+        kept[#kept + 1] = one
+      end
+    end
+  end
+
+  if value ~= nil then
+    kept[#kept + 1] = COOKIE_AUTH .. "=" .. value
+  end
+
+  if #kept == 0 then
+    headers[HEADER_COOKIE] = nil
+  else
+    headers[HEADER_COOKIE] = table.concat(kept, "; ")
+  end
+end
+
+`
+
+
+function luastr(s: string): string {
+  return String(s).replace(/\\/g, '\\\\').replace(/"/g, '\\"')
+}
+
+
+export {
+  PrepareAuth
+}

package/project/.sdk/src/cmp/lua/ReadmeExplanation_lua.ts

@@ -20,6 +20,7 @@ Use \`helpers.to_map()\` to safely validate that a value is a table.
 lua/
 ├── ${model.name}_sdk.lua    -- Main SDK module
 ├── config.lua               -- Configuration
+├── schema.lua               -- Generated option + entity specs
 ├── features.lua             -- Feature factory
 ├── core/                    -- Core types and context
 ├── entity/                  -- Entity implementations

package/project/.sdk/src/cmp/lua/Schema_lua.ts

@@ -0,0 +1,72 @@
+import {
+  Content,
+  File,
+  cmp,
+  entitySpecMap,
+  optionSpec,
+} from '@voxgig/sdkgen'
+
+
+import {
+  Model,
+} from '@voxgig/apidef'
+
+
+import {
+  luaLongString,
+} from './utility_lua'
+
+
+// THE GENERATED SCHEMA MODULE: the model's schemas, as data the SDK can run.
+//
+// The lua peer of src/cmp/ts/Schema_ts.ts. Same two exports, same source —
+// OPTSPEC from `main.kit.optspec` plus each feature's own `config.options`,
+// ENTITYSPEC from the entity field sentinels — built by the shared helpers,
+// so what lua validates against and what ts validates against cannot drift.
+//
+// EMBEDDED AS JSON IN A LONG BRACKET, PARSED AT LOAD: the mechanism
+// config.lua already uses for the model above the size threshold.
+// `luaLongString` picks a bracket level no `]]` in the content can close, so
+// the sentinels' backticks and the JSON's own quoting survive verbatim with
+// no escaping at all.
+//
+// The round-trip is exact because the spec holds only strings and booleans —
+// pinned by "strings and booleans only, so the JSON round-trip is lossless"
+// in ts/test/optspec.test.ts.
+const Schema = cmp(async function Schema(props: any) {
+  const ctx$ = props.ctx$
+  const target = props.target
+
+  const model: Model = ctx$.model
+
+  const optspec = optionSpec(model, target.name)
+  const entityspec = entitySpecMap(model, target.name) || {}
+
+  File({ name: 'schema.' + target.ext }, () => {
+    Content(`-- ${model.const.Name} ${target.Name} SDK: generated schemas. Do not edit.
+--
+-- Generated from the model: \`main.kit.optspec\` and each feature's
+-- \`config.options\` for OPTSPEC; entity \`fields[].type\` for ENTITYSPEC.
+
+local json = require("dkjson")
+
+local OPTSPEC_DATA = ${luaLongString(JSON.stringify(optspec))}
+
+local ENTITYSPEC_DATA = ${luaLongString(JSON.stringify(entityspec))}
+
+-- Parsed ONCE, at require. The spec is read on every client construction and
+-- never mutated, so a per-call parse would be pure waste — and sharing the
+-- table is safe for the same reason: make_options validates AGAINST it and
+-- writes into the options, never into the spec.
+return {
+  OPTSPEC = json.decode(OPTSPEC_DATA),
+  ENTITYSPEC = json.decode(ENTITYSPEC_DATA),
+}
+`)
+  })
+})
+
+
+export {
+  Schema
+}

package/project/.sdk/src/cmp/ocaml/Config_ocaml.ts

@@ -8,6 +8,8 @@ import {
   each,
   isAuthActive,
   isConfigData,
+  resolveAuthIn,
+  resolveAuthName,
   resolveAuthPrefix,
   targetFeatures,
 } from '@voxgig/sdkgen'
@@ -60,6 +62,14 @@ type SecretsBuild = {
   groups: string[],
   tlsGroups: string[],
   tls: boolean,
+  // C stubs an active group brings with it, keyed by the group that
+  // brought them, in the order the groups sort. tls_stubs.c is NOT here:
+  // it belongs to the tls HELPER, which no group owns - these are stubs a
+  // KIND owns, declared in its own `path` list. The mini vault is the
+  // first, and the shape is general: a kind whose implementation needs C
+  // says so by listing a .c file, and the build compiles what it lists.
+  stubs: string[],
+  stubGroups: string[],
   plugin: string[],
   core: string[],
   helpers: string[],
@@ -91,6 +101,8 @@ function secretsBuild(model: Model, target: any): SecretsBuild | null {
 
   const groups: string[] = []
   const tlsGroups: string[] = []
+  const stubGroups: string[] = []
+  const stubs = new Set<string>()
   const syms = new Set<string>()
   const kinds = new Set<string>()
 
@@ -103,6 +115,17 @@ function secretsBuild(model: Model, target: any): SecretsBuild | null {
     if (0 === Object.keys(defs).length) return
     groups.push(plugin.name)
     if (true === plugin.needs?.fetch) tlsGroups.push(plugin.name)
+
+    // `stub`, keyed by TARGET - not a filter over `path`, which is one flat
+    // list across every target: ocaml's minivault_stubs.c sits beside c's
+    // boru.c and hashicorp.c, and a prefix filter handed this build both of
+    // them. Declared per target, so what ocaml compiles is what the model
+    // says ocaml compiles.
+    const own = (plugin.stub?.[target.name] || []).map((one: any) => String(one))
+    if (0 < own.length) {
+      stubGroups.push(plugin.name)
+      for (const one of own) stubs.add(one)
+    }
     for (const [sym, path] of Object.entries(defs)) {
       syms.add(sym)
       kinds.add(String(path))
@@ -114,6 +137,8 @@ function secretsBuild(model: Model, target: any): SecretsBuild | null {
     groups: groups.sort(),
     tlsGroups: tlsGroups.sort(),
     tls,
+    stubs: Array.from(stubs).sort(),
+    stubGroups: stubGroups.sort(),
     plugin: SECRETS_PLUGIN_MODULES,
     core: SECRETS_CORE_MODULES,
     helpers: [
@@ -148,7 +173,35 @@ const Config = cmp(async function Config(props: any) {
   // server-variable defaults), which the hand-rolled build here omitted.
   // Passing target.name opts this target into the main slug/version/target
   // identity fields (read by station's descriptor - see configDefinition).
-  const { def: config, json: configJson } = configDefinition(model, target.name)
+  const { def: config } = configDefinition(model, target.name)
+
+  // `in` and `name` TRAVEL WITH THE PREFIX NOW. apidef resolved both from the
+  // spec's securityScheme all along and generation dropped them, so an
+  // apiKey-in-query API got an `authorization` header it does not read.
+  //
+  // Added to the shared `def` here rather than in configDefinition, so this
+  // change moves ocaml and nothing else - and both representations below
+  // render from the SAME object, which is why the JSON is stringified AFTER
+  // this rather than taken from configDefinition: the data rung and the
+  // literal rung must not be able to describe different configs.
+  //
+  // ONLY WHEN THEY DIFFER from the header/Authorization default, so every
+  // header-based SDK's sdk_config.ml is byte-identical to what it generated
+  // before. `options.auth` is absent entirely when auth is inactive
+  // (configDefinition's own gate), and there is nothing to qualify then.
+  const authIn = resolveAuthIn(model)
+  const authName = resolveAuthName(model)
+  const authOpts = (config as any).options?.auth
+  if (null != authOpts) {
+    if ('header' !== authIn) {
+      authOpts.in = authIn
+    }
+    if ('Authorization' !== authName) {
+      authOpts.name = authName
+    }
+  }
+
+  const configJson = JSON.stringify(config)
   const asData = isConfigData(configJson, configReprSetting(model))
 
   File({ name: 'sdk_config.' + target.ext }, () => {
@@ -278,7 +331,7 @@ let make_feature (name : string) : feature =
     const OCAML_FEATURES = [
       'audit', 'cache', 'clienttrack', 'cost', 'debug', 'idempotency', 'log',
       'metrics', 'netsim', 'paging', 'proxy', 'ratelimit', 'rbac',
-      'retry', 'streaming', 'telemetry', 'test', 'timeout',
+      'retry', 'streaming', 'telemetry', 'test', 'timeout', 'validate',
     ]
 
     each(feature, (f: any) => {