@voxgig/sdkgen 4.8.3 → 4.10.0

package/project/.sdk/tm/scala/feature/secrets/sekreto/Support.scala

@@ -0,0 +1,216 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (scala/src/Support.scala)
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// How a provider kind becomes a voxgig/plugin definition.
+//
+// This file is the whole bridge between the two libraries. A provider kind
+// is a plugin `Definition` named after the kind; its `define` reads the
+// instance's options as a `ProviderSpec`, builds the provider, and exports
+// it under the key `provider`. `Sekreto` reads it back off the host. One
+// helper makes every one of them, built-in or plugin, shipped or custom:
+//
+//     val mystore = providerplugin("mystore", spec => Mystore(spec.addr))
+//
+// A port of typescript/src/provider/support.ts, which is canonical.
+
+package com.voxgig.sekreto
+
+import scala.collection.immutable.ListMap
+
+import voxgig.plugin.Inst
+import voxgig.plugin.PluginError
+import voxgig.plugin.VMap
+import voxgig.plugin.VNum
+import voxgig.plugin.VOpaque
+import voxgig.plugin.VStr
+import voxgig.plugin.Value
+
+/** A voxgig/plugin definition, under the name a `plugins` list reads by.
+  *
+  * plugin's scala port makes a definition a CASE CLASS with typed callback
+  * fields rather than a map of `Any`, because scala's value model is a
+  * sealed hierarchy that cannot hold a function. So this is an alias and
+  * not a shape of sekreto's own: `List[Definition]` is what a consumer
+  * passes, and it is plugin's type throughout.
+  */
+type Definition = voxgig.plugin.Definition
+
+/** The export key under which a provider definition publishes the provider
+  * it built. `Sekreto` reads `<ref>/provider` off the host.
+  */
+val PROVIDER_EXPORT: String = "provider"
+
+/** The voxgig/plugin error code a SekretoError travels under when it is
+  * raised inside a definition's `define`.
+  *
+  * plugin wraps a code-less error raised by a callback as
+  * `plugin_define_failed`, and keeps one that already carries a code. A
+  * provider that refuses its own configuration - `kv: 3`, a missing project
+  * - raises a SekretoError, and the spec pins that message byte for byte,
+  * so it must come back out of the host exactly as it went in.
+  * `providerplugin` gives it this code on the way in; `Sekreto` takes it
+  * off on the way out. Nowhere else catches and rewraps.
+  */
+val ERROR_CODE: String = "sekreto_error"
+
+/** A provider kind, as a voxgig/plugin definition.
+  *
+  * Nothing runs at `activate`: a provider opens nothing until its first
+  * lookup, so there is nothing to capture - a provider that does hold a
+  * resource acquires it there and lets the instance scope unwind it.
+  */
+def providerplugin(kind: String, make: ProviderSpec => Provider): Definition =
+  val define: Inst => Unit = inst =>
+    val provider =
+      try make(specof(inst.options))
+      catch
+        case err: SekretoError =>
+          val text = Option(err.getMessage).getOrElse("")
+          throw PluginError(ERROR_CODE, text, Map("ref" -> VStr(inst.ref), "cause" -> VStr(text)))
+
+    // A provider is a live object, not data, so it crosses as plugin's own
+    // escape hatch for exactly that - the model carries numbers and strings
+    // and this is neither.
+    inst.`export`(PROVIDER_EXPORT, VOpaque(provider))
+
+  voxgig.plugin.Definition(name = kind, define = Some(define))
+
+// --- the spec across the plugin boundary -----------------------------
+//
+// plugin's options are its own value model - a sealed hierarchy of null,
+// boolean, number, string, list and map - and sekreto's spec is a typed
+// case class, so the two are written out field by field rather than
+// reflected over. `optionsof` is what `Sekreto.declare` hands to
+// `host.load`; `specof` is what a definition's `define` reads back. They
+// are inverses, and `PluginsTest`'s "a provider spec survives the plugin
+// boundary" is what says so - a field added to one and forgotten in the
+// other would otherwise be lost in silence, and only for the kinds no
+// conformance case exercises.
+
+/** The pairs that were set, as a plugin map.
+  *
+  * An absent field is ABSENT from the options rather than a present null.
+  * `specof` reads it back as None either way, but plugin's model keeps the
+  * two apart on purpose, and a spec that never mentioned a key should not
+  * gain one crossing the boundary.
+  */
+private def fields(pairs: List[(String, Option[Value])]): Value =
+  VMap(ListMap.from(pairs.collect { case (key, Some(value)) => (key, value) }))
+
+private def str(value: Option[String]): Option[Value] = value.map(VStr.apply)
+
+private def optstr(options: Value, key: String): Option[String] =
+  options.get(key).flatMap(_.asString)
+
+/** A ProviderSpec as plugin instance options. */
+def optionsof(spec: ProviderSpec): Value =
+  val auth: Option[Value] = spec.auth.map: useauth =>
+    fields(
+      List(
+        "method" -> Some(VStr(useauth.method)),
+        "mount" -> str(useauth.mount),
+        "role" -> str(useauth.role),
+        "jwt" -> str(useauth.jwt),
+        "jwtfile" -> str(useauth.jwtfile),
+        "roleid" -> str(useauth.roleid),
+        "secretid" -> str(useauth.secretid),
+      ),
+    )
+
+  val values: Option[Value] = spec.values.map: source =>
+    VMap(ListMap.from(source.map((key, value) => (key, VStr(value)))))
+
+  fields(
+    List(
+      "kind" -> Some(VStr(spec.kind)),
+      "name" -> str(spec.name),
+      "prefix" -> str(spec.prefix),
+      "file" -> str(spec.file),
+      "values" -> values,
+      "dir" -> str(spec.dir),
+      "addr" -> str(spec.addr),
+      "token" -> str(spec.token),
+      "mount" -> str(spec.mount),
+      // Every number in plugin's model is a Double, JSON's one number type.
+      "kv" -> spec.kv.map(value => VNum(value.toDouble)),
+      "vaultnamespace" -> str(spec.vaultnamespace),
+      "auth" -> auth,
+      "command" -> str(spec.command),
+      "profile" -> str(spec.profile),
+      "backend" -> str(spec.backend),
+      "reason" -> str(spec.reason),
+      "namespace" -> str(spec.namespace),
+      "home" -> str(spec.home),
+      "region" -> str(spec.region),
+      "keyid" -> str(spec.keyid),
+      "secret" -> str(spec.secret),
+      "session" -> str(spec.session),
+      "project" -> str(spec.project),
+      "vault" -> str(spec.vault),
+      "tenant" -> str(spec.tenant),
+      "clientid" -> str(spec.clientid),
+      "clientsecret" -> str(spec.clientsecret),
+      "loginaddr" -> str(spec.loginaddr),
+      "imdsaddr" -> str(spec.imdsaddr),
+      "metadataaddr" -> str(spec.metadataaddr),
+      "apiversion" -> str(spec.apiversion),
+      "config" -> str(spec.config),
+      "environment" -> str(spec.environment),
+      "path" -> str(spec.path),
+    ),
+  )
+
+/** Plugin instance options as a ProviderSpec. */
+def specof(options: Value): ProviderSpec =
+  val values = options.get("values").collect:
+    case entry: VMap =>
+      ListMap.from(entry.keys.map(key => (key, entry.at(key).asString.getOrElse(""))))
+
+  val auth = options.get("auth").collect:
+    case entry: VMap =>
+      AuthSpec(
+        method = entry.at("method").asString.getOrElse(""),
+        mount = optstr(entry, "mount"),
+        role = optstr(entry, "role"),
+        jwt = optstr(entry, "jwt"),
+        jwtfile = optstr(entry, "jwtfile"),
+        roleid = optstr(entry, "roleid"),
+        secretid = optstr(entry, "secretid"),
+      )
+
+  ProviderSpec(
+    kind = optstr(options, "kind").getOrElse(""),
+    name = optstr(options, "name"),
+    prefix = optstr(options, "prefix"),
+    file = optstr(options, "file"),
+    values = values,
+    dir = optstr(options, "dir"),
+    addr = optstr(options, "addr"),
+    token = optstr(options, "token"),
+    mount = optstr(options, "mount"),
+    kv = options.get("kv").flatMap(_.asDouble).map(_.toInt),
+    vaultnamespace = optstr(options, "vaultnamespace"),
+    auth = auth,
+    command = optstr(options, "command"),
+    profile = optstr(options, "profile"),
+    backend = optstr(options, "backend"),
+    reason = optstr(options, "reason"),
+    namespace = optstr(options, "namespace"),
+    home = optstr(options, "home"),
+    region = optstr(options, "region"),
+    keyid = optstr(options, "keyid"),
+    secret = optstr(options, "secret"),
+    session = optstr(options, "session"),
+    project = optstr(options, "project"),
+    vault = optstr(options, "vault"),
+    tenant = optstr(options, "tenant"),
+    clientid = optstr(options, "clientid"),
+    clientsecret = optstr(options, "clientsecret"),
+    loginaddr = optstr(options, "loginaddr"),
+    imdsaddr = optstr(options, "imdsaddr"),
+    metadataaddr = optstr(options, "metadataaddr"),
+    apiversion = optstr(options, "apiversion"),
+    config = optstr(options, "config"),
+    environment = optstr(options, "environment"),
+    path = optstr(options, "path"),
+  )

package/project/.sdk/tm/scala/feature/secrets/sekreto/plugins/Aws.scala

@@ -0,0 +1,225 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (scala/plugins/Aws.scala)
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// AWS Secrets Manager and SSM Parameter Store, as voxgig/plugin
+// definitions - two kinds in one module, because they share the whole of
+// the signing and calling machinery below.
+
+package com.voxgig.sekreto.plugins
+
+import java.nio.charset.StandardCharsets
+import java.time.Instant
+import java.time.ZoneOffset
+import java.time.format.DateTimeFormatter
+import java.util.Base64
+import scala.collection.immutable.ListMap
+
+import com.voxgig.sekreto.*
+import com.voxgig.sekreto.Providers.checkaddr
+
+/** The `YYYYMMDDTHHMMSSZ` timestamp SigV4 wants, for now. */
+private[plugins] def awsnow(): String =
+  DateTimeFormatter
+    .ofPattern("yyyyMMdd'T'HHmmss'Z'")
+    .withZone(ZoneOffset.UTC)
+    .format(Instant.now)
+
+/** Region and credentials, resolved for one call. */
+private[plugins] case class Awsauth(
+    region: String,
+    keyid: String,
+    secret: String,
+    session: Option[String],
+)
+
+/** Region and credentials, from config first and the standard AWS_*
+  * environment variables second - those are AWS's own convention, and a
+  * pod or CI job that has them set should just work. Missing either is an
+  * error: an AWS store with no credentials could not answer.
+  */
+private[plugins] def awsauth(
+    region: Option[String],
+    keyid: Option[String],
+    secret: Option[String],
+    session: Option[String],
+): Awsauth =
+  val useregion = first(region, getenv("AWS_REGION"), getenv("AWS_DEFAULT_REGION"))
+  val usekeyid = first(keyid, getenv("AWS_ACCESS_KEY_ID"))
+  val usesecret = first(secret, getenv("AWS_SECRET_ACCESS_KEY"))
+  val usesession = first(session, getenv("AWS_SESSION_TOKEN"))
+
+  if useregion.isEmpty then
+    throw SekretoError("sekreto: aws: no region (set region or AWS_REGION)")
+
+  if usekeyid.isEmpty || usesecret.isEmpty then
+    throw SekretoError(
+      "sekreto: aws: no credentials" +
+        " (set keyid/secret or AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY)",
+    )
+
+  Awsauth(useregion, usekeyid, usesecret, Some(usesession).filter(_.nonEmpty))
+
+/** One signed call to an AWS JSON-1.1 API. */
+private[plugins] def awscall(
+    region: Option[String],
+    keyid: Option[String],
+    secret: Option[String],
+    session: Option[String],
+    addr: Option[String],
+    service: String,
+    target: String,
+    payload: String,
+): Answer =
+  val auth = awsauth(region, keyid, secret, session)
+
+  // The China partition lives under its own suffix; every other commercial
+  // region is plain amazonaws.com.
+  val suffix = if auth.region.startsWith("cn-") then ".amazonaws.com.cn" else ".amazonaws.com"
+  val useaddr = first(addr, Some(s"https://$service.${auth.region}$suffix"))
+  checkaddr(useaddr)
+
+  val url = trimslash(useaddr) + "/"
+
+  val extras = ListMap(
+    "content-type" -> "application/x-amz-json-1.1",
+    "x-amz-target" -> target,
+  )
+
+  val signed = sigv4(
+    Signing(
+      method = "POST",
+      url = url,
+      service = service,
+      region = auth.region,
+      keyid = auth.keyid,
+      secret = auth.secret,
+      datetime = awsnow(),
+      headers = extras,
+      body = payload,
+      session = auth.session,
+    ),
+  )
+
+  fetchjson("POST", url, extras ++ signed, Some(payload))
+
+/** Does this AWS error body name one of the not-found types? Those are a
+  * miss; every other failure is a store that could not answer.
+  */
+private[plugins] def awsmiss(body: Option[Json], types: String*): Boolean =
+  body.dig("__type").asstr match
+    case Some(errtype) => types.exists(errtype.contains)
+    case None          => false
+
+/** AWS Secrets Manager.
+  *
+  * `api.token` reads the secret named `api` (the vaultref path, so
+  * `db.pass.main` reads `db/pass`) and takes the `token` field of its JSON
+  * SecretString - the AWS idiom of one JSON map per secret. A SecretString
+  * that is not JSON is the value itself, under the conventional field
+  * `value`. Requests are SigV4-signed in-tree; see Sigv4.scala.
+  */
+class Awssecrets(
+    region: Option[String] = None,
+    keyid: Option[String] = None,
+    secret: Option[String] = None,
+    session: Option[String] = None,
+    addr: Option[String] = None,
+) extends Provider:
+
+  override def lookup(name: String): Option[String] =
+    val ref = vaultref(name)
+
+    val res = awscall(
+      region,
+      keyid,
+      secret,
+      session,
+      addr,
+      "secretsmanager",
+      "secretsmanager.GetSecretValue",
+      Json.stringify(Json.obj("SecretId" -> Json.str(ref.path))),
+    )
+
+    if 400 == res.status && awsmiss(res.body, "ResourceNotFoundException") then None
+    else if 200 != res.status then
+      throw SekretoError(s"sekreto: aws secretsmanager error: ${res.status}")
+    else
+      res.body.dig("SecretString").asstr match
+        case None =>
+          // A binary secret has no fields to address; only the
+          // conventional `value` field can mean "the bytes themselves".
+          val bin = res.body.dig("SecretBinary").asstr
+
+          if bin.isDefined && "value" == ref.field then
+            // decode() throws IllegalArgumentException on a bad payload,
+            // which is not a SekretoError and so escaped the library's own
+            // error type. A store that answered incoherently is an error.
+            try Some(String(Base64.getDecoder.decode(bin.get), StandardCharsets.UTF_8))
+            catch
+              case _: IllegalArgumentException =>
+                throw SekretoError("sekreto: aws secretsmanager: undecodable secret")
+          else None
+
+        case Some(text) =>
+          Json.parse(text) match
+            case Some(Json.Obj(fields)) => fields.get(ref.field).flatMap(_.text)
+            // A plain-string secret is the whole value; it has no named
+            // fields.
+            case _ => if "value" == ref.field then Some(text) else None
+
+  // Config only, never the environment: describe() feeds the spec's
+  // sources group, which must answer the same everywhere.
+  override def describe(): String = s"awssecrets:${region.getOrElse("")}"
+
+/** AWS SSM Parameter Store.
+  *
+  * `db.pass.main` reads the parameter `/db/pass/main` (under an optional
+  * prefix path), decrypted. Parameter Store carries flat strings, so there
+  * is no field indirection.
+  */
+class Awsparams(
+    region: Option[String] = None,
+    keyid: Option[String] = None,
+    secret: Option[String] = None,
+    session: Option[String] = None,
+    addr: Option[String] = None,
+    prefix: Option[String] = None,
+) extends Provider:
+
+  override def lookup(name: String): Option[String] =
+    val payload = Json.obj(
+      "Name" -> Json.str(awsparam(name, prefix)),
+      "WithDecryption" -> Json.bool(true),
+    )
+
+    val res = awscall(
+      region,
+      keyid,
+      secret,
+      session,
+      addr,
+      "ssm",
+      "AmazonSSM.GetParameter",
+      Json.stringify(payload),
+    )
+
+    if 400 == res.status && awsmiss(res.body, "ParameterNotFound") then None
+    else if 200 != res.status then throw SekretoError(s"sekreto: aws ssm error: ${res.status}")
+    else res.body.dig("Parameter", "Value").text
+
+  override def describe(): String =
+    s"awsparams:${region.getOrElse("")}${prefix.getOrElse("")}"
+
+/** The `awssecrets` provider kind, as a voxgig/plugin definition. A consumer
+  * imports this and hands it to `Sekreto`; a consumer that does not gets a
+  * `Sekreto` that cannot build a chain entry of that kind.
+  */
+val awssecrets: Definition = providerplugin("awssecrets", spec =>
+  Awssecrets(spec.region, spec.keyid, spec.secret, spec.session, spec.addr))
+
+/** The `awsparams` provider kind, as a voxgig/plugin definition. A consumer
+  * imports this and hands it to `Sekreto`; a consumer that does not gets a
+  * `Sekreto` that cannot build a chain entry of that kind.
+  */
+val awsparams: Definition = providerplugin("awsparams", spec =>
+  Awsparams(spec.region, spec.keyid, spec.secret, spec.session, spec.addr, spec.prefix))

package/project/.sdk/tm/scala/feature/secrets/sekreto/plugins/Azuresecrets.scala

@@ -0,0 +1,124 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (scala/plugins/Azuresecrets.scala)
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// Azure Key Vault, as a voxgig/plugin definition.
+
+package com.voxgig.sekreto.plugins
+
+import com.voxgig.sekreto.*
+import com.voxgig.sekreto.Providers.checkaddr
+
+/** The Key Vault audience an Azure token is minted for. */
+private val RESOURCE = "https://vault.azure.net"
+
+/** Azure Key Vault.
+  *
+  * `api.token` reads secret `api-token` (dots flattened to `-`; Key Vault
+  * names allow nothing else), current version. The token comes from
+  * config, then a client-credentials login when tenant/clientid/
+  * clientsecret are given, then the IMDS managed-identity endpoint - so on
+  * Azure's own platform no credential configuration is needed.
+  *
+  * As with GCP, the IMDS call is plain http to a link-local host by
+  * platform design and carries no credential; the login and vault
+  * addresses are `checkaddr`-guarded.
+  */
+class Azuresecrets(
+    vault: Option[String] = None,
+    token: Option[String] = None,
+    tenant: Option[String] = None,
+    clientid: Option[String] = None,
+    clientsecret: Option[String] = None,
+    loginaddr: Option[String] = None,
+    imdsaddr: Option[String] = None,
+    apiversion: Option[String] = None,
+) extends Provider:
+
+  // A configured token is kept forever; logged-in and IMDS tokens carry
+  // expires_in and are renewed shortly before they run out.
+  private var livetoken: Option[String] = None
+  private var renewat: Long = Long.MaxValue
+
+  private def login(): String =
+    if token.exists(_.nonEmpty) then token.get
+    else if tenant.exists(_.nonEmpty) &&
+      clientid.exists(_.nonEmpty) &&
+      clientsecret.exists(_.nonEmpty)
+    then
+      val useloginaddr = first(loginaddr, Some("https://login.microsoftonline.com"))
+      checkaddr(useloginaddr)
+
+      val url = trimslash(useloginaddr) + "/" + tenant.get + "/oauth2/v2.0/token"
+      val form = "grant_type=client_credentials&client_id=" + uriescape(clientid.get) +
+        "&client_secret=" + uriescape(clientsecret.get) +
+        "&scope=" + uriescape(s"$RESOURCE/.default")
+
+      val res = fetchjson(
+        "POST",
+        url,
+        Map("content-type" -> "application/x-www-form-urlencoded"),
+        Some(form),
+      )
+
+      val got = res.body.dig("access_token").text
+      if 200 != res.status || !got.exists(_.nonEmpty) then
+        throw SekretoError(s"sekreto: azure login failed: ${res.status}")
+
+      renewat = renewtime(res.body.dig("expires_in"))
+      got.get
+    else
+      val imds = trimslash(first(imdsaddr, Some("http://169.254.169.254"))) +
+        "/metadata/identity/oauth2/token?api-version=2018-02-01&resource=" +
+        uriescape(RESOURCE)
+
+      val res = fetchjson("GET", imds, Map("Metadata" -> "true"))
+
+      val got = res.body.dig("access_token").text
+      if 200 != res.status || !got.exists(_.nonEmpty) then
+        throw SekretoError(
+          "sekreto: azure: no token, no client credentials, and IMDS did not answer",
+        )
+
+      renewat = renewtime(res.body.dig("expires_in"))
+      got.get
+
+  override def lookup(name: String): Option[String] =
+    val usevault = vault.getOrElse("")
+    if usevault.isEmpty then throw SekretoError("sekreto: azure: no vault")
+
+    // Only an explicit scheme is a URL; a vault NAMED httpvault must still
+    // become https://httpvault.vault.azure.net.
+    val vaulturl =
+      if usevault.startsWith("http://") || usevault.startsWith("https://") then usevault
+      else s"https://$usevault.vault.azure.net"
+    checkaddr(vaulturl)
+
+    if livetoken.isEmpty || System.currentTimeMillis >= renewat then livetoken = Some(login())
+
+    val url = trimslash(vaulturl) + "/secrets/" + flatname(name, "-") +
+      "?api-version=" + first(apiversion, Some("7.4"))
+
+    val res = fetchjson("GET", url, Map("authorization" -> s"Bearer ${livetoken.getOrElse("")}"))
+
+    if 404 == res.status then None
+    else if 200 != res.status then
+      throw SekretoError(s"sekreto: azure error: ${res.status}: ${bare(url)}")
+    else res.body.dig("value").text
+
+  override def describe(): String = s"azuresecrets:${vault.getOrElse("")}"
+
+/** The `azuresecrets` provider kind, as a voxgig/plugin definition. A consumer
+  * imports this and hands it to `Sekreto`; a consumer that does not gets a
+  * `Sekreto` that cannot build a chain entry of that kind.
+  */
+val azuresecrets: Definition = providerplugin("azuresecrets", spec =>
+  Azuresecrets(
+    spec.vault,
+    spec.token,
+    spec.tenant,
+    spec.clientid,
+    spec.clientsecret,
+    spec.loginaddr,
+    spec.imdsaddr,
+    spec.apiversion,
+  ))

package/project/.sdk/tm/scala/feature/secrets/sekreto/plugins/Boru.scala

@@ -0,0 +1,104 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (scala/plugins/Boru.scala)
+// Source: https://github.com/voxgig/sekreto @ 1267ee2e5f49566bc92695bc9eb3a60ef4924998  [tag: sdk-20260908-1556-0]
+// License: MIT (c) voxgig - see repository LICENSE. Do not edit: resync from upstream.
+// A boru vault, as a voxgig/plugin definition.
+
+package com.voxgig.sekreto.plugins
+
+import com.voxgig.sekreto.*
+import com.voxgig.sekreto.Providers.checkaddr
+
+/** A boru vault (https://github.com/boru-lang/boru).
+  *
+  * Two ways in, both boru's own.
+  *
+  * With no `addr`, the CLI: `boru vault get --reveal <alias>` prints the
+  * secret on stdout and nothing else. The passphrase is read by boru
+  * itself from `BORU_VAULT_PASSPHRASE`; sekreto never accepts it as config
+  * and never puts it on a command line, where it would show up in the
+  * process table.
+  *
+  * With an `addr`, boru's wire protocol: `boru vault serve` publishes a
+  * read-only, HashiCorp-shaped provision API (boru's
+  * design/VAULT-WIRE-PROTOCOL.0.md), authenticated by a capability token
+  * from `boru vault grant`. A sekreto name is already a valid boru alias,
+  * and boru aliases keep their dots, so `api.token` is the single path
+  * segment `api.token` - not the `api`/`token` split a HashiCorp KV gets.
+  * The value is the `value` field. A 404 is a miss; anything else the
+  * server refuses (a revoked capability, a sealed vault) is an error.
+  *
+  * boru's `vault proxy` and `vault mcp` remain out of bounds: they are a
+  * credential *broker*, built precisely so the caller never receives the
+  * credential. `vault serve` is the provision endpoint, built to hand the
+  * value back - that is the one sekreto uses.
+  */
+class Boru(
+    commandgiven: Option[String] = None,
+    namespace: Option[String] = None,
+    home: Option[String] = None,
+    addrgiven: Option[String] = None,
+    tokengiven: Option[String] = None,
+    mountgiven: Option[String] = None,
+) extends Provider:
+
+  private val command: String = commandgiven.filter(_.nonEmpty).getOrElse("boru")
+  private val addr: String = addrgiven.map(trimslash).getOrElse("")
+  private val token: String = tokengiven.getOrElse("")
+  private val mount: String = mountgiven.filter(_.nonEmpty).getOrElse("secret")
+
+  override def lookup(name: String): Option[String] =
+    checkname(name)
+
+    if addr.nonEmpty then wirelookup(name)
+    else
+      val alias = namespace.filter(_.nonEmpty).map(space => s"$space:$name").getOrElse(name)
+
+      val builder = ProcessBuilder(command, "vault", "get", "--reveal", alias)
+
+      home.filter(_.nonEmpty).foreach(value => builder.environment().put("BORU_HOME", value))
+
+      val ran = runcmd(builder, command)
+
+      if 0 == ran.status then
+        // boru prints the value and one newline, and nothing else.
+        Some(dropsuffix(ran.out, "\n"))
+      // "no alias named" is boru saying it does not hold this secret,
+      // which is a miss: the chain carries on to the next provider. A
+      // locked vault or a wrong passphrase is not a miss - treating it as
+      // one would fall through to a weaker store without saying so.
+      else if borumiss(ran.why) then None
+      else
+        throw SekretoError(
+          "sekreto: boru vault error: " +
+            (if ran.why.isEmpty then s"exit ${ran.status}" else ran.why),
+        )
+
+  private def wirelookup(name: String): Option[String] =
+    checkaddr(addr)
+
+    // The dotted name stays one path segment: boru aliases keep dots.
+    val alias = namespace.filter(_.nonEmpty).map(space => s"$space/$name").getOrElse(name)
+    val url = s"$addr/v1/$mount/data/$alias"
+
+    val res = fetchjson("GET", url, Map("X-Vault-Token" -> token))
+
+    if 404 == res.status then None
+    else if 200 != res.status then
+      throw SekretoError(s"sekreto: boru serve error: ${res.status}: $url")
+    else res.body.dig("data", "data", "value").text
+
+  override def describe(): String =
+    if addr.nonEmpty then s"boru:$addr"
+    else "boru" + (if namespace.exists(_.nonEmpty) then s":${namespace.get}" else "")
+
+/** Does this boru failure mean "no such secret" rather than "I could not
+  * answer"? Matched on boru's own wording for a missing alias.
+  */
+private[plugins] def borumiss(why: String): Boolean = why.contains("no alias named")
+
+/** The `boru` provider kind, as a voxgig/plugin definition. A consumer
+  * imports this and hands it to `Sekreto`; a consumer that does not gets a
+  * `Sekreto` that cannot build a chain entry of that kind.
+  */
+val boru: Definition = providerplugin("boru", spec =>
+  Boru(spec.command, spec.namespace, spec.home, spec.addr, spec.token, spec.mount))