@voxgig/sdkgen 4.9.0 → 4.10.0

package/project/.sdk/tm/kotlin/feature/secrets/sekreto/Json.kt

@@ -0,0 +1,359 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (kotlin/src/Json.kt)
+// 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.
+// Minimal JSON support for sekreto.
+//
+// sekreto adds no third-party dependencies, so it carries just enough JSON
+// to read a vault's answer and write the CLI's own line of output. It is
+// deliberately not a general-purpose library.
+//
+// A sealed class rather than plain `Any?`: a vault answering `null`, `false`,
+// `0` and "no such key" means four different things, and a sealed type keeps
+// them apart at compile time rather than by convention. `parse` returns
+// `Json?`, where a Kotlin null means "this text is not JSON" and `Json.Null`
+// means "this text is the JSON literal null" - a distinction the callers of
+// fetchjson need, since only the first is a malformed response.
+
+package KOTLINPACKAGE.feature.secrets.sekreto
+
+import kotlin.math.abs
+import kotlin.math.truncate
+
+/** Thrown while reading malformed JSON; never escapes `Json.parse`. */
+private class JsonError(message: String) : RuntimeException(message)
+
+sealed class Json {
+
+    object Null : Json()
+
+    data class Bool(val value: Boolean) : Json()
+
+    data class Num(val value: Double) : Json()
+
+    data class Str(val value: String) : Json()
+
+    data class Arr(val value: List<Json>) : Json()
+
+    data class Obj(val value: Map<String, Json>) : Json()
+
+    val asstr: String? get() = (this as? Str)?.value
+    val asnum: Double? get() = (this as? Num)?.value
+    val asarr: List<Json>? get() = (this as? Arr)?.value
+    val asobj: Map<String, Json>? get() = (this as? Obj)?.value
+
+    /** Walk nested objects; null the moment a step is not there. */
+    fun dig(vararg keys: String): Json? {
+        var at: Json = this
+
+        for (key in keys) {
+            at = (at as? Obj)?.value?.get(key) ?: return null
+        }
+
+        return at
+    }
+
+    /**
+     * This value as the text a caller would print, or null when there is no
+     * value at all. A JSON null is "no value": every provider here treats it
+     * as a miss rather than as the string "null".
+     */
+    val text: String? get() = when (this) {
+        is Null -> null
+        is Str -> value
+        is Num -> numstr(value)
+        is Bool -> if (value) "true" else "false"
+        else -> stringify(this)
+    }
+
+    companion object {
+        fun str(value: String): Json = Str(value)
+
+        fun num(value: Number): Json = Num(value.toDouble())
+
+        fun bool(value: Boolean): Json = Bool(value)
+
+        fun arr(entries: List<Json>): Json = Arr(entries)
+
+        /** An object, in the order given: a payload's field order is signed. */
+        fun obj(vararg entries: Pair<String, Json>): Json = Obj(linkedMapOf(*entries))
+
+        /**
+         * Parse JSON text. Null for anything unreadable - which the caller
+         * must tell apart from a literal `null` body, since only the first
+         * means the store could not answer coherently.
+         */
+        fun parse(text: String?): Json? {
+            if (null == text || text.isEmpty()) {
+                return null
+            }
+
+            return try {
+                val reader = Reader(text)
+                reader.skip()
+                val value = reader.value()
+                reader.skip()
+                if (!reader.done()) {
+                    throw JsonError("sekreto: json: trailing content at ${reader.at}")
+                }
+                value
+            } catch (err: RuntimeException) {
+                null
+            }
+        }
+
+        /** Render a value as compact JSON. */
+        fun stringify(value: Json): String {
+            val out = StringBuilder()
+            write(value, out)
+            return out.toString()
+        }
+
+        /** Render a string as a JSON string literal, quotes included. */
+        fun quote(text: String): String {
+            val out = StringBuilder("\"")
+
+            for (ch in text) {
+                when (ch) {
+                    '"' -> out.append("\\\"")
+                    '\\' -> out.append("\\\\")
+                    '\n' -> out.append("\\n")
+                    '\r' -> out.append("\\r")
+                    '\t' -> out.append("\\t")
+                    else ->
+                        if (0x20 > ch.code) {
+                            out.append("\\u%04x".format(ch.code))
+                        } else {
+                            out.append(ch)
+                        }
+                }
+            }
+
+            return out.append('"').toString()
+        }
+
+        private fun write(value: Json, out: StringBuilder) {
+            when (value) {
+                is Null -> out.append("null")
+                is Bool -> out.append(if (value.value) "true" else "false")
+                is Num -> out.append(numstr(value.value))
+                is Str -> out.append(quote(value.value))
+                is Arr -> {
+                    out.append('[')
+                    value.value.forEachIndexed { index, entry ->
+                        if (0 < index) {
+                            out.append(',')
+                        }
+                        write(entry, out)
+                    }
+                    out.append(']')
+                }
+                is Obj -> {
+                    out.append('{')
+                    var first = true
+                    for ((key, entry) in value.value) {
+                        if (!first) {
+                            out.append(',')
+                        }
+                        first = false
+                        out.append(quote(key)).append(':')
+                        write(entry, out)
+                    }
+                    out.append('}')
+                }
+            }
+        }
+    }
+
+    private class Reader(val text: String) {
+        var at = 0
+
+        fun done(): Boolean = at >= text.length
+
+        fun skip() {
+            while (at < text.length && text[at].isWhitespace()) {
+                at++
+            }
+        }
+
+        fun value(): Json {
+            if (done()) {
+                throw JsonError("sekreto: json: unexpected end")
+            }
+
+            return when (text[at]) {
+                '{' -> obj()
+                '[' -> arr()
+                '"' -> Str(str())
+                't' -> { word("true"); Bool(true) }
+                'f' -> { word("false"); Bool(false) }
+                'n' -> { word("null"); Null }
+                else -> num()
+            }
+        }
+
+        fun word(want: String) {
+            if (!text.startsWith(want, at)) {
+                throw JsonError("sekreto: json: bad literal at $at")
+            }
+            at += want.length
+        }
+
+        fun obj(): Json {
+            val out = LinkedHashMap<String, Json>()
+            at++ // {
+
+            skip()
+            if (!done() && '}' == text[at]) {
+                at++
+                return Obj(out)
+            }
+
+            while (true) {
+                skip()
+                val key = str()
+                skip()
+
+                if (done() || ':' != text[at]) {
+                    throw JsonError("sekreto: json: expected ':' at $at")
+                }
+                at++
+
+                skip()
+                out[key] = value()
+                skip()
+
+                if (done()) {
+                    throw JsonError("sekreto: json: unterminated object")
+                }
+                if (',' == text[at]) {
+                    at++
+                    continue
+                }
+                if ('}' == text[at]) {
+                    at++
+                    return Obj(out)
+                }
+
+                throw JsonError("sekreto: json: expected ',' or '}' at $at")
+            }
+        }
+
+        fun arr(): Json {
+            val out = mutableListOf<Json>()
+            at++ // [
+
+            skip()
+            if (!done() && ']' == text[at]) {
+                at++
+                return Arr(out)
+            }
+
+            while (true) {
+                skip()
+                out.add(value())
+                skip()
+
+                if (done()) {
+                    throw JsonError("sekreto: json: unterminated array")
+                }
+                if (',' == text[at]) {
+                    at++
+                    continue
+                }
+                if (']' == text[at]) {
+                    at++
+                    return Arr(out)
+                }
+
+                throw JsonError("sekreto: json: expected ',' or ']' at $at")
+            }
+        }
+
+        fun str(): String {
+            if (done() || '"' != text[at]) {
+                throw JsonError("sekreto: json: expected string at $at")
+            }
+            at++
+
+            val out = StringBuilder()
+
+            while (at < text.length) {
+                val ch = text[at++]
+
+                if ('"' == ch) {
+                    return out.toString()
+                }
+
+                if ('\\' != ch) {
+                    out.append(ch)
+                    continue
+                }
+
+                if (done()) {
+                    break
+                }
+
+                when (val escape = text[at++]) {
+                    '"' -> out.append('"')
+                    '\\' -> out.append('\\')
+                    '/' -> out.append('/')
+                    'b' -> out.append('\b')
+                    'f' -> out.append('')
+                    'n' -> out.append('\n')
+                    'r' -> out.append('\r')
+                    't' -> out.append('\t')
+                    'u' -> {
+                        if (at + 4 > text.length) {
+                            throw JsonError("sekreto: json: bad unicode escape")
+                        }
+                        out.append(text.substring(at, at + 4).toInt(16).toChar())
+                        at += 4
+                    }
+                    else -> throw JsonError("sekreto: json: bad escape [$escape] at $at")
+                }
+            }
+
+            throw JsonError("sekreto: json: unterminated string")
+        }
+
+        fun num(): Json {
+            val start = at
+
+            if (at < text.length && ('-' == text[at] || '+' == text[at])) {
+                at++
+            }
+
+            while (at < text.length) {
+                val ch = text[at]
+                if (ch.isDigit() || '.' == ch || 'e' == ch || 'E' == ch || '-' == ch || '+' == ch) {
+                    at++
+                } else {
+                    break
+                }
+            }
+
+            val span = text.substring(start, at)
+
+            return Num(
+                span.toDoubleOrNull()
+                    ?: throw JsonError("sekreto: json: bad number [$span] at $start"),
+            )
+        }
+    }
+}
+
+/**
+ * Render a number the way every other port does: a whole number has no
+ * fractional tail, so a JSON `1` read back and printed stays `1`.
+ */
+internal fun numstr(value: Double): String {
+    if (value.isNaN() || value.isInfinite()) {
+        return "null"
+    }
+
+    if (value == truncate(value) && 9007199254740992.0 > abs(value)) {
+        return value.toLong().toString()
+    }
+
+    return value.toString()
+}

package/project/.sdk/tm/kotlin/feature/secrets/sekreto/Provider.kt

@@ -0,0 +1,21 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (kotlin/src/Provider.kt)
+// 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 source of secrets.
+//
+// A provider answers one question: "do you have this secret?" It returns
+// the value, or null to mean "ask the next one". Nothing else about a
+// provider is visible to the caller - which is the point: an app reads
+// `api.token` and never learns whether it came from the environment, a
+// .env file, HashiCorp Vault or a boru vault.
+
+package KOTLINPACKAGE.feature.secrets.sekreto
+
+interface Provider {
+
+    /** The value, or null if this provider does not have it. */
+    fun lookup(name: String): String?
+
+    /** A short description, shown by `Sekreto.sources()`. */
+    fun describe(): String
+}

package/project/.sdk/tm/kotlin/feature/secrets/sekreto/Providers.kt

@@ -0,0 +1,308 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (kotlin/src/Providers.kt)
+// 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.
+// THE BUILT-IN PROVIDER KINDS - the same four in every port.
+//
+// A provider answers one question: "do you have this secret?" It returns
+// the value, or null to mean "ask the next one". Nothing else about a
+// provider is visible to the caller - which is the point: an app reads
+// `api.token` and never learns whether it came from the environment, a
+// .env file or a mounted secret directory.
+//
+// What makes a kind built in is that it reads AT MOST A LOCAL FILE: no
+// socket, no TLS, no crypto, no child process. These four are the floor
+// every chain stands on, and a chain that reads secrets from options, the
+// environment, a plaintext `.env` and a mounted secret directory works
+// with no plugin loaded at all. Everything else - the vault clients, the
+// cloud stores, the two CLIs, and `sigv4` with them - is a voxgig/plugin
+// definition under `plugins/`, and this file is the reason the core links
+// none of it (docs/design/plugin-providers.md).
+//
+// Two failure shapes, and they are never interchangeable. A store that does
+// not hold the secret is a MISS (null) - the chain carries on. A store that
+// could not answer - bad credentials, unreachable host, missing
+// configuration - is an ERROR: falling through there would quietly reach
+// for a weaker store.
+//
+// A port of typescript/src/provider/, which is canonical.
+
+package KOTLINPACKAGE.feature.secrets.sekreto
+
+import java.io.IOException
+import java.nio.charset.StandardCharsets
+import java.nio.file.Files
+import java.nio.file.NoSuchFileException
+import java.nio.file.Path
+import java.nio.file.Paths
+
+object Providers {
+
+    /**
+     * Does this read failure mean "no secrets here", rather than "I could not
+     * answer"?
+     *
+     * Absence is a MISS and the chain carries on; anything else - permission
+     * denied, an unreadable mount, a failing disk - is an ERROR, because
+     * returning a miss there falls silently through to a weaker store.
+     *
+     * Asked of the directory, not of the file. The obvious spelling,
+     * `!Files.exists(file)`, is wrong in exactly the case the rule exists
+     * for: `Files.exists` is "did checkAccess throw", so it answers *false*
+     * for an `AccessDeniedException` and turned a locked directory - the
+     * canonical "unreadable mount" - into a miss. A path whose parent is a
+     * plain file (ENOTDIR) really is "no secrets here", and that is what this
+     * asks. The reason string is not consulted: it comes from the C library's
+     * strerror and follows the machine's locale.
+     */
+    internal fun absent(file: Path): Boolean {
+        val dir = file.parent
+        return null != dir && !Files.isDirectory(dir)
+    }
+
+    /**
+     * An address with any userinfo replaced by `[redacted]`, for messages.
+     *
+     * Every refusal below names the address it refused, and one of them fires
+     * precisely because the address carries a credential - so printing it
+     * verbatim wrote the password to stderr and into the logs. It cannot be
+     * cleaned up afterwards either: that password was never resolved as a
+     * secret, so redact() has never seen it and never will. The host is what
+     * a reader needs to identify which chain entry is at fault; the userinfo
+     * is not.
+     */
+    internal fun safeaddr(addr: String): String {
+        val mark = addr.indexOf("://")
+        if (-1 == mark) {
+            return addr
+        }
+
+        val rest = addr.substring(mark + 3)
+        val stop = rest.indexOfFirst { it in "/?#" }
+        val authority = if (-1 == stop) rest else rest.substring(0, stop)
+
+        val at = authority.lastIndexOf('@')
+        if (-1 == at) {
+            return addr
+        }
+
+        return addr.substring(0, mark + 3) + "[redacted]" + addr.substring(mark + 3 + at)
+    }
+
+    /**
+     * Refuse to send a secret-bearing credential in the clear.
+     *
+     * A vault API is HTTPS in any real deployment; plaintext is a dev-mode
+     * convenience. Sending a token over http to anything but the local
+     * machine puts both the token and the secret it fetches on the wire for
+     * anyone on the path, so sekreto will not do it. Loopback stays allowed:
+     * that is `vault server -dev`, `boru vault serve`, and this repo's own
+     * test harness.
+     *
+     * The address is read by hand, in the same handful of steps in every
+     * port, rather than by each platform's URL parser. That is deliberate.
+     * Twelve parsers disagree about malformed input - where userinfo ends,
+     * whether `0177.0.0.1` is loopback, what an unclosed bracket means - and
+     * a check that answers differently in different ports is not a check.
+     *
+     * The rule this parse obeys, and the reason it can be trusted: it is
+     * never more permissive than the HTTP client that will dial the address.
+     * It ends the authority at `/`, `?` or `#` only, so a client that also
+     * breaks on `\` (WHATWG does) can only ever see a SHORTER host than this
+     * does. It refuses userinfo outright rather than locating its end. It
+     * compares the host literally, so a numeric form no parser here agrees
+     * on is refused rather than guessed at.
+     */
+    fun checkaddr(addr: String) {
+        val scheme = when {
+            addr.startsWith("https://") -> "https://"
+            addr.startsWith("http://") -> "http://"
+            else -> throw SekretoError("sekreto: not an http(s) address: ${safeaddr(addr)}")
+        }
+
+        val rest = addr.substring(scheme.length)
+        val end = rest.indexOfFirst { it in "/?#" }
+        val authority = if (-1 == end) rest else rest.substring(0, end)
+
+        // Userinfo is refused outright rather than parsed around, and on
+        // https as well as http. No store this library speaks authenticates
+        // by userinfo - they take a token or a signature - so an address
+        // carrying one is a mistake at best. At worst it is the attack this
+        // whole function exists to stop:
+        // `http://localhost:8200@evil.example.com/` is a request to
+        // evil.example.com that reads, to anything that splits the authority
+        // on ':', as loopback.
+        if (authority.contains("@")) {
+            throw SekretoError("sekreto: refusing an address with embedded credentials: ${safeaddr(addr)}")
+        }
+
+        // An opening bracket with no closing one is not an address at all.
+        if (authority.startsWith("[") && !authority.contains("]")) {
+            throw SekretoError("sekreto: not a valid http(s) address: ${safeaddr(addr)}")
+        }
+
+        if ("https://" == scheme) {
+            return
+        }
+
+        // A bracketed IPv6 literal keeps its brackets. Splitting the
+        // authority on the first colon yields '[', so `http://[::1]:8200`
+        // could never match - which made the '[::1]' entry below unreachable,
+        // and refused a legitimate local vault.
+        val host = (
+            if (authority.startsWith("[")) {
+                authority.substring(0, authority.indexOf("]") + 1)
+            } else {
+                authority.substringBefore(':')
+            }
+            ).lowercase()
+
+        if ("localhost" == host || "127.0.0.1" == host || "::1" == host || "[::1]" == host) {
+            return
+        }
+
+        throw SekretoError(
+            "sekreto: refusing to send a token in plaintext to ${safeaddr(addr)} (use https)",
+        )
+    }
+
+    /** Environment variables: `api.token` from `API_TOKEN`. */
+    class Env(
+        private val prefix: String? = null,
+        private val source: Map<String, String>? = null,
+    ) : Provider {
+
+        override fun lookup(name: String): String? {
+            val key = envkey(name, prefix)
+            return if (null == source) System.getenv(key) else source[key]
+        }
+
+        override fun describe(): String =
+            "env" + if (prefix.isNullOrEmpty()) "" else ":$prefix"
+    }
+
+    /** A `.env` file, read once, keyed exactly like the environment. */
+    class Dotenv(private val file: String, private val prefix: String? = null) : Provider {
+
+        private var values: Map<String, String>? = null
+
+        private fun load(): Map<String, String> {
+            values?.let { return it }
+
+            val path = Paths.get(file)
+
+            val loaded: Map<String, String> = try {
+                parsedotenv(String(Files.readAllBytes(path), StandardCharsets.UTF_8))
+            } catch (err: NoSuchFileException) {
+                // An absent file - or an absent directory - means "no secrets
+                // here", exactly like the file provider.
+                emptyMap()
+            } catch (err: IOException) {
+                if (absent(path)) {
+                    emptyMap()
+                } else {
+                    throw SekretoError(
+                        "sekreto: dotenv provider cannot read $file: ${err.message}",
+                    )
+                }
+            }
+
+            values = loaded
+            return loaded
+        }
+
+        override fun lookup(name: String): String? = load()[envkey(name, prefix)]
+
+        override fun describe(): String = "dotenv:$file"
+    }
+
+    /**
+     * Literal values, keyed like environment variables. The spec uses this
+     * to test chain behaviour without touching the outside world.
+     */
+    class Memory(
+        values: Map<String, String>? = null,
+        private val prefix: String? = null,
+    ) : Provider {
+
+        private val values: Map<String, String> = values ?: emptyMap()
+
+        override fun lookup(name: String): String? = values[envkey(name, prefix)]
+
+        override fun describe(): String =
+            "memory" + if (prefix.isNullOrEmpty()) "" else ":$prefix"
+    }
+
+    /**
+     * A directory of one-secret-per-file entries, keyed like the
+     * environment: `api.token` reads `<dir>/API_TOKEN`.
+     *
+     * This is the shape of a mounted Kubernetes Secret, a Docker or Swarm
+     * secret, and a systemd credentials directory, so those all work with no
+     * further configuration. One trailing newline is stripped - tools that
+     * write these files disagree about it, and a newline is never part of a
+     * secret on purpose.
+     */
+    class File(dir: String?, private val prefix: String? = null) : Provider {
+
+        private val dir: String = dir ?: ""
+
+        override fun lookup(name: String): String? {
+            val file = Paths.get(dir, envkey(name, prefix))
+
+            val text = try {
+                String(Files.readAllBytes(file), StandardCharsets.UTF_8)
+            } catch (err: NoSuchFileException) {
+                // An absent file - or an absent directory - means "no secrets
+                // here", exactly like a missing .env.
+                return null
+            } catch (err: IOException) {
+                if (absent(file)) {
+                    return null
+                }
+                throw SekretoError("sekreto: file provider cannot read $file: ${err.message}")
+            }
+
+            if (text.endsWith("\r\n")) {
+                return text.dropLast(2)
+            }
+            if (text.endsWith("\n")) {
+                return text.dropLast(1)
+            }
+
+            return text
+        }
+
+        override fun describe(): String = "file:$dir"
+    }
+}
+
+/**
+ * The four built-in kinds, as voxgig/plugin definitions.
+ *
+ * Every kind is made the same way, built-in or plugin, shipped or
+ * custom: one `providerplugin` call. `Sekreto` puts these into its
+ * catalog first, then whatever `plugins` handed in, so a plugin naming a
+ * built-in kind replaces it - a host substituting an implementation,
+ * never an accident, because these four names are documented.
+ */
+val BUILTINS: List<Definition> = listOf(
+    providerplugin("env") { spec -> Providers.Env(spec.prefix) },
+    providerplugin("memory") { spec -> Providers.Memory(spec.values, spec.prefix) },
+    providerplugin("dotenv") { spec -> Providers.Dotenv(spec.file ?: ".env", spec.prefix) },
+    providerplugin("file") { spec -> Providers.File(spec.dir ?: "", spec.prefix) },
+)
+
+/**
+ * Every kind this library ships, built in or as a plugin, so that a kind
+ * sekreto has never heard of can be told from one that exists as a
+ * plugin and was not passed in.
+ */
+object KINDS {
+
+    val builtin: List<String> = listOf("env", "memory", "dotenv", "file")
+
+    val plugin: List<String> = listOf(
+        "hashicorp", "boru", "awssecrets", "awsparams", "gcpsecrets",
+        "azuresecrets", "onepassword", "doppler", "infisical", "secretspec",
+    )
+}