@voxgig/sdkgen 4.5.3 → 4.7.0

package/project/.sdk/tm/rb/utility/make_options.rb

@@ -40,9 +40,23 @@ module ProjectNameUtilities
       end
     end
 
+    # `auth: nil` is the documented way to disable auth outright, and
+    # prepare_auth honours it before it ever reads the apikey. It cannot
+    # survive validate: depending on the struct port a stored null is either
+    # REPLACED by the optspec default - transmitting the credential the
+    # caller withheld - or REJECTED outright. Withhold the key for validate,
+    # then put the nil back. Same fix as ts/js/go make_options.
+    #
+    # Suppliedness cannot be recovered after validate, hence here, and it
+    # must tell an ABSENT auth from a present nil: only the latter is a
+    # suppression.
+    authsuppressed = options.is_a?(Hash) && options.key?('auth') && options['auth'].nil?
+
     opts = VoxgigStruct.clone(options)
     opts = {} unless opts.is_a?(Hash)
 
+    opts.delete('auth') if authsuppressed
+
     # Feature add-order. options["feature"] may be given as an ordered ARRAY of
     # { "name" => ..., "active" => ..., ... } entries (the array position IS the
     # order in which features are added), or as a { "name" => {opts} } map.
@@ -109,6 +123,9 @@ module ProjectNameUtilities
     validated = VoxgigStruct.validate(merged, optspec)
     opts = validated.is_a?(Hash) ? validated : {}
 
+    # Restore the suppression the optspec default would otherwise erase.
+    opts['auth'] = nil if authsuppressed
+
     # Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
     # Every placeholder must resolve to a non-empty value: from
     # options["server"] (user), else the config default. A placeholder that

package/project/.sdk/tm/rust/tests/common/mod.rs

@@ -93,6 +93,38 @@ pub fn is_control_skipped(kind: &str, name: &str, mode: &str) -> (bool, String)
     (false, String::new())
 }
 
+/// Extra SDK options every LIVE client is constructed with, read from
+/// sdk-test-control.json `test.client.options`.
+///
+/// The generated live client knows two things: the base URL (from the spec)
+/// and the credential (from the environment). Everything else about how a
+/// particular API wants to be talked to - which features to switch on, and
+/// with what settings - is a property of THAT API, known to the project and
+/// to nothing in the toolchain.
+///
+/// Merged UNDER the generated fields, so the suite's own base/apikey/server
+/// values win: this ADDS to the live client, it does not redirect it.
+///
+/// Reserved fields are stripped HERE rather than at each merge site: the
+/// generated map only names a field when the model calls for one, so a
+/// "base" in this block would face no competing value and would silently
+/// redirect the whole suite - credential included - to another host.
+pub const LIVE_RESERVED: [&str; 6] =
+    ["base", "prefix", "suffix", "server", "apikey", "secret"];
+
+pub fn live_client_options() -> Value {
+    let ctrl = load_test_control();
+    let out = Value::empty_map();
+    if let Value::Map(m) = get_spec(&ctrl, &["test", "client", "options"]) {
+        for (k, v) in m.borrow().iter() {
+            if !LIVE_RESERVED.contains(&k.as_str()) {
+                setp(&out, k, v.clone());
+            }
+        }
+    }
+    out
+}
+
 /// Configured per-test live delay in ms; default 500.
 pub fn live_delay_ms() -> i64 {
     let ctrl = load_test_control();

package/project/.sdk/tm/rust/utility/make_options.rs

@@ -23,8 +23,28 @@ pub fn make_options_util(ctx: &Rc<Context>) -> Value {
         }
     }
 
+    // `auth: null` is the documented way to disable auth outright, and
+    // prepare_auth honours it before it ever reads the apikey. It cannot
+    // survive validate: depending on the struct port a stored null is either
+    // REPLACED by the optspec default - transmitting the credential the
+    // caller withheld - or REJECTED outright. Withhold the key for validate,
+    // then put the null back. Same fix as ts/js/go make_options.
+    //
+    // Read the map DIRECTLY rather than through get_prop: get_prop applies
+    // the Group A rule and returns the alt for a stored null, so it cannot
+    // tell an absent auth from a suppressed one - and only the latter is a
+    // suppression.
+    let auth_suppressed = match &options {
+        Value::Map(m) => matches!(m.borrow().get("auth"), Some(Value::Null)),
+        _ => false,
+    };
+
     let mut opts = vs::clone(&options);
 
+    if auth_suppressed {
+        opts = vs::del_prop(opts, &Value::str("auth"));
+    }
+
     // Feature add-order. `options.feature` may be an ordered List of
     // { name, active, ...opts } entries (the List position IS the order in
     // which features are added), or a { name: {opts} } map. Normalize a List
@@ -58,7 +78,7 @@ pub fn make_options_util(ctx: &Rc<Context>) -> Value {
         ("base", Value::str("http://localhost:8000")),
         ("prefix", Value::str("")),
         ("suffix", Value::str("")),
-        ("auth", jo(vec![("prefix", Value::str(""))])),
+        ("auth", jo(vec![("prefix", Value::str("")), ("basic", Value::Bool(false))])),
         ("headers", jo(vec![("`$CHILD`", Value::str("`$STRING`"))])),
         (
             "allow",
@@ -120,6 +140,11 @@ pub fn make_options_util(ctx: &Rc<Context>) -> Value {
         }
     }
 
+    // Restore the suppression the optspec default would otherwise erase.
+    if auth_suppressed {
+        setp(&opts, "auth", Value::Null);
+    }
+
     // Resolve a templated base URL (e.g. https://{tenant_id}.hanko.io).
     // Every placeholder must resolve to a non-empty value: from options.server
     // (user), else the Config default. A placeholder that resolves to "" is a

package/project/.sdk/tm/scala/utility/Make.scala

@@ -254,8 +254,22 @@ object MakeOptions {
       }
     }
 
+    // `auth: null` is the documented way to suppress auth outright, and
+    // prepareAuth honours it before it ever reads the apikey. It cannot survive
+    // validate: a stored null reads as "no value", so the optspec `auth`
+    // default fires and the suppression becomes "use the default auth" -
+    // transmitting the credential the caller withheld. Withhold the key for
+    // validate, then put the null back. Same fix as ts/js/go/java makeOptions.
+    //
+    // Suppliedness cannot be recovered after validate, hence here, and it must
+    // tell an ABSENT auth from a present null: containsKey rather than a get()
+    // null check, which cannot distinguish them.
+    val authSuppressed = options.containsKey("auth") && null == options.get("auth")
+
     var opts = Struct.clone(options).asInstanceOf[JMap[String, Object]]
 
+    if (authSuppressed) opts.remove("auth")
+
     // Feature add-order. options.feature may be given as an ordered LIST of
     // { name, active, ...opts } entries (the list position IS the order in
     // which features are added), or as a { name: {opts} } map. Normalize a
@@ -330,6 +344,9 @@ object MakeOptions {
     val validated = Struct.validate(merged, optspec, vopts)
     opts = validated.asInstanceOf[JMap[String, Object]]
 
+    // Restore the suppression the optspec default would otherwise erase.
+    if (authSuppressed) opts.put("auth", null)
+
     // Restore system.fetch.
     if (sysFetch != null) {
       val sys = Helpers.toMapAny(opts.get("system"))

package/project/.sdk/tm/swift/Sources/ProjectNameSDK/utility/MakeOptions.swift

@@ -85,8 +85,24 @@ func makeOptionsUtil(_ ctx: Context) -> VMap {
     }
   }
 
+  // `auth: .null` is the documented way to disable auth outright, and
+  // prepareAuth honours it before it ever reads the apikey. It cannot survive
+  // validate: depending on the struct port a stored null is either REPLACED
+  // by the optspec default - transmitting the credential the caller withheld
+  // - or REJECTED outright. Withhold the key for validate, then put the null
+  // back. Same fix as ts/js/go makeOptions.
+  //
+  // `isNull` rather than `isNil`: the latter is also true for Noval, so it
+  // cannot tell an ABSENT auth from a suppressed one, and only the latter is
+  // a suppression.
+  let authSuppressed = options.entries["auth"]?.isNull ?? false
+
   let opts = clone(.map(options)).asMap ?? VMap()
 
+  if authSuppressed {
+    opts.entries.removeValue(forKey: "auth")
+  }
+
   // Feature add-order. options.feature may be given as an ordered LIST of
   // { name, active, ...opts } entries (the list position IS the order in which
   // features are added), or as a { name: {opts} } map. Normalize a list to a
@@ -124,6 +140,11 @@ func makeOptionsUtil(_ ctx: Context) -> VMap {
   let validated = validate(merged, optspec)
   let result = validated.asMap ?? VMap()
 
+  // Restore the suppression the optspec default would otherwise erase.
+  if authSuppressed {
+    result.entries["auth"] = .null
+  }
+
   // Restore system.fetch.
   if !isNil(sysFetch) {
     if let sm = gp(result, "system").asMap {

package/project/.sdk/tm/ts/src/feature/secrets/SecretsFeature.ts

@@ -0,0 +1,419 @@
+import type { Context, FeatureOptions } from '../../types'
+
+import { BaseFeature } from '../base/BaseFeature'
+import { Sekreto, envkey } from './sekreto'
+
+
+// Secret access via a vendored @voxgig/sekreto provider chain, and the
+// access-token exchange some APIs require on top of it.
+//
+// The SDK's `apikey` option keeps exactly its old meaning: an explicit
+// credential given in code. This feature makes it ONE SOURCE among several
+// rather than the only one: when active, the apikey is resolved through a
+// sekreto chain in which the explicit option (when set) is the FIRST
+// provider — a `memory` store named `options` — so an explicit value always
+// wins, by sekreto's own first-hit rule rather than by special-case logic.
+// When the option is unset, the remaining providers (env, dotenv, a vault)
+// are asked in order, and moving a credential from code to a vault becomes
+// a configuration change.
+//
+// SOME APIs will not take a long-lived credential at all. What the chain
+// resolves is then a REFRESH token, which buys a short-lived ACCESS token
+// from a token endpoint; the access token is what every request carries,
+// and it expires. `exchange.active` turns that round trip on: the resolved
+// secret is POSTed to `exchange.path` (relative to options.base), the
+// access token from the response is written to options.apikey, and a
+// response in `exchange.statuses` (401) buys another and retries once.
+//
+// That last part is why this feature wraps the transport. Expiry is only
+// ever discovered from a RESPONSE, and the transport is the one place a
+// response can be seen before the operation pipeline turns it into a
+// result. With the exchange off, nothing is wrapped.
+//
+// Resolution is ASYNC (providers may do IO), but the auth header is built
+// by the synchronous prepareAuth inside makeSpec. The bridge is the
+// feature hook pipeline: every entity op awaits featureHook('PreSpec')
+// before calling makeSpec, so the PreSpec hook below resolves the secret
+// once and writes it into the live options where prepareAuth already
+// looks. prepareAuth itself is untouched. SolardemoSDK.prepare() bypasses
+// feature hooks entirely, so it awaits client._secrets.resolve() itself.
+class SecretsFeature extends BaseFeature {
+  version = '0.1.0'
+  name = 'secrets'
+
+  _client: any
+  _sekreto?: Sekreto
+  _secretname: string = 'apikey'
+  _resolving?: Promise<void>
+  _cache: boolean = true
+
+  // Exchange state. `_exchange` is the resolved config (null when off),
+  // `_refresh` the credential the chain gave us, and `_buying` the single
+  // in-flight token purchase concurrent callers share.
+  _exchange: any = null
+  _refresh?: string
+  _buying?: Promise<string>
+
+
+  // Sync by contract (the constructor cannot await): build the chain only,
+  // never look anything up here.
+  init(ctx: Context, fopts: FeatureOptions): void {
+    const client = ctx.client
+    const options = ctx.options
+
+    this._client = client
+    this._secretname = 'string' === typeof (fopts as any).name &&
+      '' !== (fopts as any).name ? (fopts as any).name : 'apikey'
+
+    // Exchange config, normalised once. Null when off, so every later
+    // decision is a null check rather than a repeated `true === ...active`.
+    const xopts = (fopts as any).exchange
+    this._exchange = (null != xopts && true === xopts.active) ? {
+      path: 'string' === typeof xopts.path ? xopts.path : 'auth/token',
+      method: 'string' === typeof xopts.method ? xopts.method : 'POST',
+      request: 'string' === typeof xopts.request ? xopts.request : 'refresh_token',
+      response: 'string' === typeof xopts.response ? xopts.response : 'access_token',
+      statuses: Array.isArray(xopts.statuses) ? xopts.statuses : [401],
+      retries: 'number' === typeof xopts.retries ? xopts.retries : 1,
+    } : null
+
+    const providers: any[] = []
+
+    // The explicit credential, when set, is the first store in the chain.
+    //
+    // WHICH option that is depends on the exchange. Without one, the secret
+    // being resolved IS the credential the transport sends, so `apikey` is
+    // it. With one, the secret is a REFRESH token and `apikey` means the
+    // opposite thing — an access token the caller already holds — so the
+    // explicit seat belongs to `exchange.refresh`, and apikey is left alone
+    // to serve as the starting access token (see resolve below).
+    const explicit = null == this._exchange ?
+      options.apikey :
+      (null == xopts ? undefined : xopts.refresh)
+
+    if ('string' === typeof explicit && '' !== explicit) {
+      providers.push({
+        kind: 'memory',
+        name: 'options',
+        values: { [envkey(this._secretname)]: explicit },
+      })
+    }
+
+    for (const p of ((fopts as any).providers || [])) {
+      providers.push(p)
+    }
+
+    this._cache = false !== (fopts as any).cache
+
+    this._sekreto = new Sekreto({
+      providers,
+      cache: this._cache,
+    })
+
+    // Seam for ProjectNameSDK.prepare() (no feature hooks on that path)
+    // and for the public secrets() accessor.
+    //
+    // Cast, because `_secrets` is emitted on the SDK class only when this
+    // feature is active, while this file is copied into the target tree by
+    // Main's blanket copy whether or not the model declares the feature.
+    // Typing the assignment would make the SDK fail to compile in exactly
+    // the case the feature is switched off.
+    ;(client as any)._secrets = this
+
+    // Wrap the transport ONLY when there is an exchange to defend. A spent
+    // access token is discovered from the response, and this is the one
+    // place a response can be seen and the request tried again.
+    if (null != this._exchange) {
+      const self = this
+      const utility = ctx.utility
+      const inner = utility.fetcher
+
+      utility.fetcher = async function (ctx2: any, url: string, fetchdef: any) {
+        return self._withRefresh(ctx2, url, fetchdef, inner)
+      }
+    }
+  }
+
+
+  // The LIVE Sekreto instance, for the SDK's secrets() accessor and for
+  // callers who want arbitrary secrets or redaction:
+  //
+  //   await sdk.secrets().get('db.password')
+  //   sdk.secrets().redact(logline)
+  //
+  // Public, so the accessor does not have to reach into a private field.
+  // Never a clone: sekreto holds provider state (caches, vault leases)
+  // that has to stay live to be worth anything.
+  sekreto(): any {
+    return this._sekreto
+  }
+
+
+  PreSpec(_ctx: Context) {
+    return this.resolve()
+  }
+
+
+  // Resolve the apikey before the first request. Concurrent ops share the
+  // one IN-FLIGHT promise; a settled one is not reused unless caching is
+  // on. A provider ERROR (unreachable vault, bad creds) rejects and fails
+  // the op — sekreto's miss-vs-error rule: never fall through to an
+  // unauthenticated request because a store was broken.
+  //
+  // The promise is cleared on REJECTION, and after success when caching is
+  // off. Holding a settled promise forever would mean a transient vault
+  // outage poisoned the client permanently — every later operation failing
+  // with the original error long after the vault recovered — and it would
+  // make the documented `cache: false` a lie, since the chain would never
+  // be asked a second time.
+  resolve(): Promise<void> {
+    if (null == this._resolving) {
+      const inflight = this._resolveonce()
+        .then(
+          () => {
+            if (!this._cache) {
+              this._resolving = undefined
+            }
+          },
+          (err: any) => {
+            this._resolving = undefined
+            throw err
+          })
+
+      this._resolving = inflight
+    }
+
+    return this._resolving
+  }
+
+
+  private async _resolveonce(): Promise<void> {
+    if (null == this._sekreto) {
+      return
+    }
+
+    const found = await this._sekreto.try(this._secretname)
+
+    if (null == this._exchange) {
+      if (undefined !== found) {
+        // The same live-mutation seam TestFeature uses for the transport:
+        // prepareAuth reads client.options() (a clone of _options), so the
+        // resolved value lands where the sync auth path already looks.
+        this._client._options.apikey = found
+      }
+      return
+    }
+
+    // Exchanging: what the chain resolved is the REFRESH token, kept for
+    // every later purchase. A miss is not fatal here — an explicit
+    // `apikey` may already hold a usable access token, and the API is
+    // what gets to say whether it does.
+    this._refresh = undefined === found ? undefined : String(found)
+
+    const apikey = this._client._options.apikey
+    if ('string' === typeof apikey && '' !== apikey) {
+      // A starting access token was supplied. Spend it: if it is stale the
+      // API answers 401 and the transport wrapper buys another, which is
+      // the same path expiry takes anyway.
+      return
+    }
+
+    this._client._options.apikey = await this._buy()
+  }
+
+
+  // Buy an access token with the refresh token.
+  //
+  // Concurrent callers share the ONE in-flight purchase: a client running
+  // four operations at once must not open four token requests, and three of
+  // the four tokens would be wasted. The promise is cleared once settled,
+  // so the next expiry buys a fresh one rather than replaying this result.
+  private _buy(): Promise<string> {
+    // TEST MODE BUYS NOTHING.
+    //
+    // The test feature replaces the transport so that no request leaves the
+    // process; an exchange here would be the one HTTP call it could not
+    // stop, and it would need a live token endpoint for a suite whose whole
+    // point is not needing one. So test mode gets a deterministic,
+    // obviously-fake token instead — the same answer makeOptions gives a
+    // required server variable, for the same reason.
+    if ('live' !== this._client._mode) {
+      return Promise.resolve('test-' + this._exchange.response)
+    }
+
+    if (null != this._buying) {
+      return this._buying
+    }
+
+    const buying = this._buyonce()
+      .then(
+        (token: string) => {
+          this._buying = undefined
+          return token
+        },
+        (err: any) => {
+          this._buying = undefined
+          throw err
+        })
+
+    this._buying = buying
+
+    return buying
+  }
+
+
+  private async _buyonce(): Promise<string> {
+    const x = this._exchange
+
+    if (null == this._refresh || "" === this._refresh) {
+      throw new Error(
+        "secrets: no refresh token: the provider chain has no '" +
+        this._secretname + "', and feature.secrets.exchange.refresh is unset")
+    }
+
+    const options = this._client.options()
+
+    // The token endpoint is RELATIVE to the base, which already carries
+    // whatever account or tenant segment the server URL declares.
+    const base = String(options.base || "").replace(/\/+$/, "")
+    const url = base + "/" + String(x.path).replace(/^\/+/, "")
+
+    const fetch = options.system && options.system.fetch
+
+    if ("function" !== typeof fetch) {
+      throw new Error("secrets: no fetch implementation for the token exchange")
+    }
+
+    // Deliberately NOT the SDK transport. The transport is what this
+    // feature wraps, and sending the token request back through it would
+    // recurse on the first 401 — and would route the exchange through the
+    // test mock, which knows nothing about it.
+    const res = await fetch(url, {
+      method: x.method,
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ [x.request]: this._refresh }),
+    })
+
+    const status = null == res ? 0 : res.status
+
+    if (200 > status || 300 <= status) {
+      throw new Error(
+        "secrets: token exchange failed: " + status + " from " + url)
+    }
+
+    const body = "function" === typeof res.json ? await res.json() : res.body
+    const token = null == body ? undefined : body[x.response]
+
+    if ("string" !== typeof token || "" === token) {
+      throw new Error(
+        "secrets: token exchange returned no '" + x.response + "' field from " + url)
+    }
+
+    return token
+  }
+
+
+  // Buy a token and try the request again when the API says the current one
+  // is spent. Wraps the transport; installed only when exchanging.
+  //
+  // The retry rewrites the Authorization header IN PLACE on the fetchdef,
+  // because the header was built by the synchronous prepareAuth before this
+  // request left, and it carries the token that just failed. Rebuilt the
+  // way prepareAuth builds it, from the same options.auth.prefix, so the
+  // two cannot drift.
+  async _withRefresh(
+    this: any, ctx: any, url: string, fetchdef: any, inner: any
+  ): Promise<any> {
+    const x = this._exchange
+    const max = null == x ? 0 : x.retries
+
+    // `auth: null` is the documented way to send NO credential, and
+    // prepareAuth honours it by removing the header. A refusal of a
+    // deliberately unauthenticated request is not an expired token and
+    // cannot be fixed by buying one — retrying would transmit exactly the
+    // credential the caller suppressed.
+    if (null == this._client.options().auth) {
+      return inner(ctx, url, fetchdef)
+    }
+
+    let attempt = 0
+
+    for (; ;) {
+      // The credential THIS attempt goes out with, captured before it
+      // leaves: it is what tells a stale refusal apart from a fresh one.
+      const used = this._client._options.apikey
+
+      const res = await inner(ctx, url, fetchdef)
+
+      if (attempt >= max || !this._spent(res)) {
+        return res
+      }
+
+      // Another request may have bought a token while this one was in
+      // flight. Concurrent 401s share the in-flight purchase, but
+      // STAGGERED ones do not: the first finishes and clears it, and the
+      // second would then buy again — a second exchange for a token that
+      // is already current, and on a provider that invalidates the
+      // previous credential on issuance, one that breaks the first
+      // request's own retry. So spend what is current before buying.
+      const current = this._client._options.apikey
+      let token: string
+
+      if ('string' === typeof current && '' !== current && current !== used) {
+        token = current
+      }
+      else {
+        try {
+          token = await this._buy()
+        }
+        catch (err: any) {
+          // The purchase failed: answer with the API's own refusal rather
+          // than this one. The caller asked for data, and the 401 is the
+          // more useful of the two — the exchange error is a symptom.
+          return res
+        }
+
+        this._client._options.apikey = token
+      }
+
+      this._reauth(fetchdef, token)
+
+      attempt++
+    }
+  }
+
+
+  _spent(this: any, res: any): boolean {
+    if (null == res || res instanceof Error) {
+      return false
+    }
+    const statuses = this._exchange.statuses
+    return statuses.indexOf(res.status) >= 0
+  }
+
+
+  _reauth(this: any, fetchdef: any, token: string) {
+    if (null == fetchdef || null == fetchdef.headers) {
+      return
+    }
+
+    const auth = this._client.options().auth
+
+    // Suppressed auth means NO header, the same answer prepareAuth gives.
+    // Reached defensively - _withRefresh does not retry at all when auth
+    // is null - but this is the function that writes the credential, so
+    // it is where the rule has to hold.
+    if (null == auth) {
+      delete fetchdef.headers.authorization
+      return
+    }
+
+    const prefix = auth.prefix
+    fetchdef.headers.authorization = prefix ? prefix + " " + token : token
+  }
+}
+
+
+export {
+  SecretsFeature
+}