@voxgig/sdkgen 4.9.0 → 4.11.0

package/project/.sdk/tm/clojure/feature/secrets/voxgig/sekreto/plugins/httpjson.clj

@@ -0,0 +1,214 @@
+;; VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (clojure/plugins/voxgig/sekreto/plugins/httpjson.clj)
+;; 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 HTTP-JSON edge every plugin that speaks to a store shares - and
+;; NOTHING IN THE CORE REACHES IT.
+;;
+;; A chain of the four built-in kinds never loads this namespace, so it
+;; never loads `java.net.http` either. That is the whole point of the
+;; core/plugin split: an app whose chain is `[dotenv env]` carries no
+;; HTTP client at all (docs/design/plugin-providers.md).
+;;
+;; `uriescape` lives here rather than with sigv4 because four plugins
+;; that sign nothing need it to build a query string, and reaching it
+;; through sigv4 would make them load a hash function to escape a
+;; parameter.
+;;
+;; A port of typescript/plugins/httpjson.ts, which is canonical.
+
+(ns voxgig.sekreto.plugins.httpjson
+  (:require [voxgig.sekreto.core :as core]
+            [voxgig.sekreto.json :as json])
+  (:import [java.io ByteArrayOutputStream IOException]
+           [java.net URI]
+           [java.net.http HttpClient HttpClient$Redirect HttpClient$Version
+            HttpRequest HttpRequest$BodyPublishers HttpResponse HttpResponse$BodyHandlers]
+           [java.nio.charset StandardCharsets]
+           [java.time Duration]))
+
+;; How long any single vault round-trip may take before it is treated as
+;; unreachable. Ports carry the same bound.
+(def ^:private TIMEOUT (Duration/ofSeconds 10))
+
+;; How much of a response body will be read before the store is treated as
+;; having answered incoherently. Ports carry the same bound.
+;;
+;; Far above anything real - the largest legitimate payload this library
+;; fetches is Doppler's whole-config download, measured in kilobytes. A
+;; bound is needed because the TIMEOUT is not one: ten seconds on a loopback
+;; or datacentre link is gigabytes, and the body is accumulated in memory
+;; before it is parsed. This runs on an application's startup path, so the
+;; failure is the application never starting.
+(def ^:private MAXBODY (* 8 1024 1024))
+
+(defn firstof
+  "The first candidate that is set and non-empty, or the empty string.
+  Config first, then the environment variable the store's own ecosystem
+  already uses, is how every plugin here reads its settings."
+  [& candidates]
+  (or (some core/notempty candidates) ""))
+
+(defn trimslash [text] (core/dropsuffix text "/"))
+
+;; HTTP/1.1, explicitly.
+;;
+;; java.net.http defaults to HTTP_2, and over cleartext that means an h2c
+;; upgrade: the first request goes out with `Upgrade: h2c`, the declared
+;; Content-Length, and NO BODY, and the body follows only after the server
+;; declines. A server that checks the two against each other - Fastify does,
+;; and Infisical is Fastify - rejects that request outright with "Request
+;; body size did not match Content-Length", so every POST this port makes to
+;; such a server fails before it is even read.
+;;
+;; The mocks in test/ are Node's own http module, which does not object,
+;; which is why this survived until the same code met a real Infisical. No
+;; vault API this library speaks needs HTTP/2.
+;;
+;; Redirects are never followed: a vault API does not legitimately redirect,
+;; and a followed redirect would carry X-Vault-Token to the redirect's host
+;; (and could downgrade https to http), which checkaddr - it only validates
+;; the configured address - cannot see.
+;;
+;; A delay, so that requiring this namespace opens no resources: the client
+;; is built by the first fetch, in a process that has one to make.
+(def ^:private CLIENT
+  (delay (-> (HttpClient/newBuilder)
+             (.version HttpClient$Version/HTTP_1_1)
+             (.followRedirects HttpClient$Redirect/NEVER)
+             (.connectTimeout TIMEOUT)
+             (.build))))
+
+(defn- why
+  "What an exception has to say for itself, never the empty string."
+  [^Throwable err]
+  (or (core/notempty (.getMessage err)) (str err)))
+
+(defn bare
+  "A URL without its query string, for a message that must not leak one."
+  [url]
+  (apply str (take-while (fn [ch] (not= \? ch)) url)))
+
+(defn uriescape
+  "RFC 3986 escaping, which is stricter than the usual URL encoder: AWS
+  wants everything but unreserved characters escaped, with uppercase hex."
+  [^String text]
+  (let [out (StringBuilder.)]
+    (doseq [byte (.getBytes text StandardCharsets/UTF_8)]
+      (let [ch (bit-and (int byte) 0xff)]
+        (if (or (<= (int \A) ch (int \Z))
+                (<= (int \a) ch (int \z))
+                (<= (int \0) ch (int \9))
+                (= (int \-) ch) (= (int \_) ch) (= (int \.) ch) (= (int \~) ch))
+          (.append out (char ch))
+          (.append out (format "%%%02X" ch)))))
+    (.toString out)))
+
+(defn- hexbyte
+  "Two hex digits as a byte, or nil. The usual number reads are decimal."
+  [^String text]
+  (try (Integer/parseInt text 16) (catch NumberFormatException _ nil)))
+
+(defn uridecode
+  "Percent-decode, and nothing else: `+` stays `+`, as on the wire."
+  [^String text]
+  (let [out (ByteArrayOutputStream.)]
+    (loop [index 0]
+      (if (<= (count text) index)
+        (String. (.toByteArray out) StandardCharsets/UTF_8)
+        (let [head (.charAt text index)
+              code (when (and (= \% head) (> (count text) (+ index 2)))
+                     (hexbyte (subs text (inc index) (+ index 3))))]
+          (if (some? code)
+            (do (.write out (int code))
+                (recur (+ index 3)))
+            ;; A stray % is kept as-is, the way a browser would.
+            (do (.write out (.getBytes (str head) StandardCharsets/UTF_8))
+                (recur (inc index)))))))))
+
+(defn fetchjson
+  "One JSON round-trip: `{:status <int> :body <json>}`, where the body is
+  `json/NONE` when there was nothing readable. Network failure is always an
+  error - an unreachable store is a store that could not answer."
+  ([method url] (fetchjson method url {} nil))
+  ([method url headers] (fetchjson method url headers nil))
+  ([method url headers body]
+   (let [builder (doto (HttpRequest/newBuilder)
+                   (.uri (URI/create url))
+                   (.timeout TIMEOUT)
+                   (.method method (if (nil? body)
+                                     (HttpRequest$BodyPublishers/noBody)
+                                     (HttpRequest$BodyPublishers/ofString
+                                      body StandardCharsets/UTF_8))))
+
+         _ (doseq [[key value] headers] (.header builder key value))
+
+         ;; ofInputStream, not ofString: ofString buffers whatever arrives,
+         ;; so an endless body would be accumulated in memory until the
+         ;; deadline - which on a loopback or datacentre link is gigabytes.
+         response (try
+                    (.send ^HttpClient @CLIENT (.build builder)
+                           (HttpResponse$BodyHandlers/ofInputStream))
+                    ;; A refused connection arrives with a null message, so
+                    ;; the class name stands in - "cannot reach ...: null"
+                    ;; says nothing at all.
+                    (catch IOException err
+                      (throw (core/sekretoerror
+                              (str "sekreto: cannot reach " (bare url) ": " (why err)))))
+                    (catch InterruptedException _
+                      (.interrupt (Thread/currentThread))
+                      (throw (core/sekretoerror
+                              (str "sekreto: cannot reach " (bare url) ": interrupted")))))
+
+         ^java.io.InputStream stream (.body ^HttpResponse response)
+
+         ;; One byte over the bound is enough to know it was exceeded. An
+         ;; endless body is a store that could not answer, so this raises
+         ;; rather than returning a miss - the latter would fall through to
+         ;; a weaker store on an attacker's cue.
+         text (try
+                (let [raw (.readNBytes stream (inc MAXBODY))]
+                  (when (< MAXBODY (alength raw))
+                    (throw (core/sekretoerror (str "sekreto: oversized response from " (bare url)))))
+                  (String. raw StandardCharsets/UTF_8))
+                (catch IOException err
+                  (throw (core/sekretoerror
+                          (str "sekreto: cannot reach " (bare url) ": " (why err)))))
+                (finally (.close stream)))
+
+         parsed (json/parse text)]
+
+     ;; A success status promised JSON; a body that does not parse means the
+     ;; store could not answer coherently, and treating it as a miss would
+     ;; fall through to a weaker store. Error statuses may carry any body -
+     ;; they are decided on status alone.
+     (when (and (= 200 (.statusCode ^HttpResponse response)) (json/none? parsed))
+       (throw (core/sekretoerror (str "sekreto: malformed response from " (bare url)))))
+
+     {:status (.statusCode ^HttpResponse response) :body parsed})))
+
+(defn renewtime
+  "When a logged-in token must be renewed, from its expiry in seconds (a
+  JSON number, or a string as Azure IMDS sends it): now + max(seconds - 60,
+  1). A missing or zero expiry means never renew."
+  [expires]
+  (let [seconds (cond
+                  (json/asnum expires) (double expires)
+                  (string? expires) (or (parse-double expires) 0.0)
+                  :else 0.0)]
+    (if (or (Double/isNaN seconds) (>= 0 seconds))
+      Long/MAX_VALUE
+      (+ (System/currentTimeMillis) (long (* 1000 (max (- seconds 60) 1.0)))))))
+
+(defn withtoken
+  "The working token. `state` is an atom holding `{:token :renewat}`: a
+  configured token is kept forever, a logged-in one is renewed shortly
+  before its lease runs out - a long-running process must not keep
+  presenting a token the vault already expired. `login` answers
+  `[token renewat]`."
+  [state login]
+  (let [{:keys [token renewat]} @state]
+    (if (and (some? token) (> (or renewat Long/MAX_VALUE) (System/currentTimeMillis)))
+      token
+      (let [[fresh until] (login)]
+        (reset! state {:token fresh :renewat until})
+        fresh))))

package/project/.sdk/tm/clojure/feature/secrets/voxgig/sekreto/plugins/infisical.clj

@@ -0,0 +1,80 @@
+;; VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (clojure/plugins/voxgig/sekreto/plugins/infisical.clj)
+;; 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.
+;; Infisical, as a voxgig/plugin definition.
+;;
+;; A plugin rather than a built-in kind because it opens a socket
+;; (docs/design/plugin-providers.md).
+;;
+;; A port of typescript/plugins/infisical.ts, which is canonical.
+
+(ns voxgig.sekreto.plugins.infisical
+  (:require [voxgig.sekreto.core :as core]
+            [voxgig.sekreto.addr :refer [checkaddr]]
+            [voxgig.sekreto.json :as json]
+            [voxgig.sekreto.provider :as provider]
+            [voxgig.sekreto.providers :as providers]
+            [voxgig.sekreto.plugins.httpjson :as http]))
+
+(defrecord Infisical [addr token clientid clientsecret project environment path state]
+  provider/Provider
+
+  ;; Infisical.
+  ;;
+  ;; `api.token` reads the secret keyed `API_TOKEN` (Infisical's own
+  ;; convention is environment-style keys) at a secret path in one
+  ;; environment of a project. Auth is a token, or a universal-auth (machine
+  ;; identity) login with clientid/clientsecret.
+  (lookup [_ name]
+    (let [useaddr (http/trimslash (http/firstof addr "https://app.infisical.com"))
+          _ (checkaddr useaddr)
+
+          _ (when (or (= "" (or project "")) (= "" (or environment "")))
+              (throw (core/sekretoerror "sekreto: infisical: no project/environment")))
+
+          login (fn []
+                  (if (core/notempty token)
+                    [token Long/MAX_VALUE]
+                    (do
+                      (when (or (nil? (core/notempty clientid))
+                                (nil? (core/notempty clientsecret)))
+                        (throw (core/sekretoerror
+                                "sekreto: infisical: no token and no client credentials")))
+
+                      (let [body (json/omap [["clientId" clientid] ["clientSecret" clientsecret]])
+                            res (http/fetchjson "POST"
+                                           (str useaddr "/api/v1/auth/universal-auth/login")
+                                           {"content-type" "application/json"}
+                                           (json/stringify body))
+                            got (json/astext (json/dig (:body res) "accessToken"))]
+
+                        (when (or (not= 200 (:status res)) (nil? (core/notempty got)))
+                          (throw (core/sekretoerror
+                                  (str "sekreto: infisical login failed: " (:status res)))))
+
+                        [got (http/renewtime (json/dig (:body res) "expiresIn"))]))))
+
+          live (http/withtoken state login)
+          url (str useaddr "/api/v3/secrets/raw/" (core/envkey name)
+                   "?workspaceId=" (http/uriescape project)
+                   "&environment=" (http/uriescape environment)
+                   "&secretPath=" (http/uriescape (http/firstof path "/")))
+          res (http/fetchjson "GET" url {"authorization" (str "Bearer " (or live ""))})]
+
+      (cond
+        (= 404 (:status res)) nil
+
+        (not= 200 (:status res))
+        (throw (core/sekretoerror (str "sekreto: infisical error: " (:status res))))
+
+        :else (json/astext (json/dig (:body res) "secret" "secretValue")))))
+
+  (describe [_] (str "infisical:" (or project "") "/" (or environment ""))))
+
+(def infisical
+  "The `infisical` provider kind."
+  (providers/providerplugin
+   "infisical"
+   (fn [{:keys [addr token clientid clientsecret project environment path]}]
+     (->Infisical addr token clientid clientsecret project environment path
+                  (atom {:token nil :renewat Long/MAX_VALUE})))))

package/project/.sdk/tm/clojure/feature/secrets/voxgig/sekreto/plugins/onepassword.clj

@@ -0,0 +1,93 @@
+;; VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (clojure/plugins/voxgig/sekreto/plugins/onepassword.clj)
+;; 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.
+;; 1Password through a Connect server, as a voxgig/plugin definition.
+;;
+;; A plugin rather than a built-in kind because it opens a socket
+;; (docs/design/plugin-providers.md).
+;;
+;; A port of typescript/plugins/onepassword.ts, which is canonical.
+
+(ns voxgig.sekreto.plugins.onepassword
+  (:require [voxgig.sekreto.core :as core]
+            [voxgig.sekreto.addr :refer [checkaddr]]
+            [voxgig.sekreto.json :as json]
+            [voxgig.sekreto.provider :as provider]
+            [voxgig.sekreto.providers :as providers]
+            [voxgig.sekreto.plugins.httpjson :as http]))
+
+(defrecord Onepassword [addr token vault vaultid]
+  provider/Provider
+
+  ;; 1Password, through a Connect server.
+  ;;
+  ;; The item titled `api.token` (titles keep their dots), in the named
+  ;; vault. The value is the field with purpose PASSWORD, or the field
+  ;; labelled `value`. A vault that cannot be found is an error - config
+  ;; names it, so its absence is a broken store, not a missing secret.
+  (lookup [_ name]
+    (core/checkname name)
+
+    (let [useaddr (http/trimslash (or addr ""))
+          _ (when (= "" useaddr)
+              (throw (core/sekretoerror "sekreto: onepassword: no addr")))
+          _ (checkaddr useaddr)
+
+          auth {"authorization" (str "Bearer " (or token ""))}
+
+          id (or @vaultid
+                 (reset! vaultid
+                         (let [want (or vault "")]
+                           (when (= "" want)
+                             (throw (core/sekretoerror "sekreto: onepassword: no vault")))
+
+                           (let [res (http/fetchjson "GET" (str useaddr "/v1/vaults") auth)
+                                 list (json/asarr (:body res))]
+                             (when (or (not= 200 (:status res)) (nil? list))
+                               (throw (core/sekretoerror
+                                       (str "sekreto: onepassword error: " (:status res)
+                                            ": listing vaults"))))
+
+                             (let [found (some (fn [entry]
+                                                 (when (or (= want (json/astext (json/dig entry "id")))
+                                                           (= want (json/astext (json/dig entry "name"))))
+                                                   entry))
+                                               list)]
+                               (when (nil? found)
+                                 (throw (core/sekretoerror
+                                         (str "sekreto: onepassword: no vault named " want))))
+
+                               (or (json/astext (json/dig found "id")) ""))))))
+
+          filter (http/uriescape (str "title eq \"" name "\""))
+          found (http/fetchjson "GET" (str useaddr "/v1/vaults/" id "/items?filter=" filter) auth)
+          items (json/asarr (:body found))]
+
+      (when (or (not= 200 (:status found)) (nil? items))
+        (throw (core/sekretoerror
+                (str "sekreto: onepassword error: " (:status found) ": finding " name))))
+
+      (when (seq items)
+        (let [itemid (or (json/astext (json/dig (first items) "id")) "")
+              item (http/fetchjson "GET" (str useaddr "/v1/vaults/" id "/items/" itemid) auth)]
+
+          (when (not= 200 (:status item))
+            (throw (core/sekretoerror
+                    (str "sekreto: onepassword error: " (:status item) ": reading " name))))
+
+          (let [fields (or (json/asarr (json/dig (:body item) "fields")) [])
+                pick (fn [key want]
+                       (some (fn [field]
+                               (when (= want (json/asstr (json/dig field key))) field))
+                             fields))]
+            (json/astext (json/dig (or (pick "purpose" "PASSWORD") (pick "label" "value"))
+                                   "value")))))))
+
+  (describe [_] (str "onepassword:" (or vault ""))))
+
+(def onepassword
+  "The `onepassword` provider kind."
+  (providers/providerplugin
+   "onepassword"
+   (fn [{:keys [addr token vault]}]
+     (->Onepassword addr token vault (atom nil)))))

package/project/.sdk/tm/clojure/feature/secrets/voxgig/sekreto/plugins/proc.clj

@@ -0,0 +1,63 @@
+;; VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (clojure/plugins/voxgig/sekreto/plugins/proc.clj)
+;; 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.
+;; Running a child to completion, for the two kinds that read a secret
+;; through somebody else's CLI - boru and secretspec.
+;;
+;; OUTSIDE THE CORE, because spawning a process is one of the three things
+;; that make a kind a plugin. A chain of built-ins never loads this
+;; namespace and so never reaches `ProcessBuilder`
+;; (docs/design/plugin-providers.md).
+;;
+;; A port of java/plugins/com/voxgig/sekreto/plugins/Proc.java, which
+;; carries the same two-stream rule.
+
+(ns voxgig.sekreto.plugins.proc
+  (:require [clojure.string :as string]
+            [voxgig.sekreto.core :as core])
+  (:import [java.io ByteArrayOutputStream IOException]
+           [java.nio.charset StandardCharsets]))
+
+(defn runcmd
+  "Run a child to completion and collect both its streams.
+
+  The two streams are drained CONCURRENTLY. Reading stdout to EOF and only
+  then reading stderr deadlocks the moment the child writes more than one
+  pipe buffer (64 KiB on Linux) to stderr: the parent is blocked waiting for
+  stdout, the child is blocked waiting for room on stderr, and neither can
+  move. Nothing in this library sets a timeout, so that hang is permanent -
+  `get` simply never returns. secretspec's diagnostics are box-drawn and
+  reach that size easily.
+
+  The child's stdin is closed rather than left open on a pipe nobody writes
+  to, so a CLI that reads it - one prompting for a passphrase when its
+  environment variable is absent - sees EOF and gives up instead of waiting
+  forever."
+  [^ProcessBuilder builder command]
+  (try
+    (let [process (.start builder)]
+      (.close (.getOutputStream process))
+
+      (let [errbuf (ByteArrayOutputStream.)
+            pump (fn []
+                   (try
+                     (.transferTo (.getErrorStream process) errbuf)
+                     ;; The child went away mid-write; waitFor reports how.
+                     (catch IOException _ nil)))
+            drain (doto (Thread. ^Runnable pump) (.setDaemon true) (.start))
+            out (String. (.readAllBytes (.getInputStream process)) StandardCharsets/UTF_8)
+            status (.waitFor process)]
+        (.join drain)
+        {:out out
+         :why (string/trim (String. (.toByteArray errbuf) StandardCharsets/UTF_8))
+         :status status}))
+    (catch IOException err
+      (throw (core/sekretoerror (str "sekreto: cannot run " command ": " (.getMessage err)))))
+    (catch InterruptedException _
+      (.interrupt (Thread/currentThread))
+      (throw (core/sekretoerror (str "sekreto: interrupted running " command))))))
+
+(defn command
+  "A ProcessBuilder for an argument vector."
+  ^ProcessBuilder [args]
+  (ProcessBuilder. ^"[Ljava.lang.String;" (into-array String args)))

package/project/.sdk/tm/clojure/feature/secrets/voxgig/sekreto/plugins/secretspec.clj

@@ -0,0 +1,99 @@
+;; VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (clojure/plugins/voxgig/sekreto/plugins/secretspec.clj)
+;; 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.
+;; SecretSpec, as a voxgig/plugin definition.
+;;
+;; A plugin rather than a built-in kind because it spawns a child process,
+;; and a built-in kind reads at most a local file
+;; (docs/design/plugin-providers.md).
+;;
+;; IT IS THE ONE PLUGIN THAT REACHES NO SOCKET, and it requires no HTTP
+;; helper either: reaching `httpjson` for the one-line `reason` default
+;; would load `java.net.http` into a process that only ever spawns a
+;; child. The default is spelled out here instead, the way every other
+;; port spells it.
+;;
+;; A port of typescript/plugins/secretspec.ts, which is canonical.
+
+(ns voxgig.sekreto.plugins.secretspec
+  (:require [clojure.string :as string]
+            [voxgig.sekreto.core :as core]
+            [voxgig.sekreto.provider :as provider]
+            [voxgig.sekreto.providers :as providers]
+            [voxgig.sekreto.plugins.proc :as proc]))
+
+(defn secretspecmiss?
+  "Does this SecretSpec failure mean \"no such secret\" rather than \"I
+  could not answer\"?
+
+  SecretSpec says `Secret 'API_TOKEN' not found` for both a name it does not
+  declare and one declared with no value, and both are misses: this store
+  does not hold it, so the chain carries on.
+
+  MATCHED ON THE WHOLE PHRASE, NOT ON \"not found\". SecretSpec also says
+  `Provider backend 'keyring' not found`, which is a store that could not
+  answer at all - and reading that as a miss is the worst failure this
+  library has, because the chain then falls through to a weaker store
+  without saying so. The key is required to appear, so the two cannot be
+  confused."
+  [why key]
+  (string/includes? why (str "Secret '" key "' not found")))
+
+(defrecord Secretspec [command file profile backend reason prefix]
+  provider/Provider
+
+  ;; SecretSpec (https://secretspec.dev).
+  ;;
+  ;; SecretSpec is a declaration - a `secretspec.toml` naming the secrets a
+  ;; project needs - plus a chain of its own backends to satisfy them from.
+  ;; That makes it the same shape as sekreto one level down, and the reason
+  ;; to support it is the same reason sekreto exists: a project that has
+  ;; already declared its secrets there should not have to declare them
+  ;; again here.
+  ;;
+  ;; Read through its CLI, as boru is, because that is the interface it
+  ;; offers a program in another language: `secretspec get API_TOKEN` prints
+  ;; the value on stdout and nothing else. A sekreto name maps to a
+  ;; SecretSpec key exactly as it maps to an environment variable -
+  ;; `api.token` is `API_TOKEN` - which is the convention SecretSpec's own
+  ;; examples use.
+  ;;
+  ;; `backend` selects one of SecretSpec's backends (`--provider`, e.g.
+  ;; `keyring` or `dotenv://.env`) and is called `backend` here only because
+  ;; `provider` already means something else in this library.
+  ;;
+  ;; A reason is required, not optional: SecretSpec records every read in an
+  ;; audit log and refuses to read at all without one. sekreto sends
+  ;; `sekreto` unless told otherwise, so the audit trail says which tool
+  ;; asked.
+  (lookup [_ name]
+    (let [key (core/envkey name prefix)
+          args (cond-> [command]
+                 (core/notempty file) (conj "--file" file)
+                 true (conj "get" key)
+                 (core/notempty backend) (conj "--provider" backend)
+                 (core/notempty profile) (conj "--profile" profile)
+                 true (conj "--reason" (or (core/notempty reason) "sekreto")))
+          ran (proc/runcmd (proc/command args) command)]
+
+      (cond
+        ;; The value and one newline, and nothing else.
+        (= 0 (:status ran)) (core/dropsuffix (:out ran) "\n")
+
+        (secretspecmiss? (:why ran) key) nil
+
+        :else
+        (throw (core/sekretoerror
+                (str "sekreto: secretspec error: "
+                     (if (= "" (:why ran)) (str "exit " (:status ran)) (:why ran))))))))
+
+  (describe [_]
+    (str "secretspec" (when (core/notempty backend) (str ":" backend)))))
+
+(def secretspec
+  "The `secretspec` provider kind."
+  (providers/providerplugin
+   "secretspec"
+   (fn [{:keys [command file profile backend reason prefix]}]
+     (->Secretspec (or (core/notempty command) "secretspec")
+                   file profile backend reason prefix))))