@voxgig/sdkgen 4.8.3 → 4.10.0

package/project/.sdk/tm/java/feature/secrets/sekreto/plugins/Httpjson.java

@@ -0,0 +1,192 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (java/plugins/com/voxgig/sekreto/plugins/Httpjson.java)
+// 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.
+// One JSON round-trip, shared by every plugin that speaks HTTP - and by
+// nothing in the core. A chain of built-ins never links this file, which
+// is the whole point of the split: an app configured from a `.env` and
+// the environment carries no HTTP client at all.
+//
+// A port of typescript/plugins/httpjson.ts.
+
+package JAVAPACKAGE.feature.secrets.sekreto.plugins;
+
+import JAVAPACKAGE.feature.secrets.sekreto.Json;
+import JAVAPACKAGE.feature.secrets.sekreto.Sekreto.SekretoError;
+import java.io.IOException;
+import java.net.URI;
+import java.net.http.HttpClient;
+import java.net.http.HttpRequest;
+import java.net.http.HttpResponse;
+import java.nio.charset.StandardCharsets;
+import java.time.Duration;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+public final class Httpjson {
+
+  private Httpjson() {}
+
+  /**
+   * How much of a response body will be read before the store is treated as
+   * having answered incoherently. Ports carry the same bound.
+   *
+   * <p>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.
+   */
+  private static final int MAXBODY = 8 * 1024 * 1024;
+
+  // 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.
+  private static final HttpClient CLIENT = HttpClient.newBuilder()
+      .version(HttpClient.Version.HTTP_1_1)
+      .connectTimeout(Duration.ofSeconds(10))
+      .build();
+
+  /** One JSON round-trip's result: the status, and the parsed body. */
+  public static final class Answer {
+    final int status;
+    final Object body;
+
+    Answer(int status, Object body) {
+      this.status = status;
+      this.body = body;
+    }
+  }
+
+  /**
+   * One JSON round-trip. Network failure is always an error - an
+   * unreachable store is a store that could not answer.
+   */
+  public static Answer fetchjson(String method, String url, Map<String, String> headers, String body) {
+    HttpRequest.Builder builder = HttpRequest.newBuilder()
+        .uri(URI.create(url))
+        .timeout(Duration.ofSeconds(10))
+        .method(method, null == body
+            ? HttpRequest.BodyPublishers.noBody()
+            : HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8));
+
+    if (null != headers) {
+      for (Map.Entry<String, String> entry : headers.entrySet()) {
+        builder.header(entry.getKey(), entry.getValue());
+      }
+    }
+
+    // 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.
+    HttpResponse<java.io.InputStream> response;
+    try {
+      response = CLIENT.send(builder.build(), HttpResponse.BodyHandlers.ofInputStream());
+    } catch (IOException err) {
+      throw new SekretoError(
+          "sekreto: cannot reach " + url.split("\\?")[0] + ": " + err.getMessage());
+    } catch (InterruptedException err) {
+      Thread.currentThread().interrupt();
+      throw new SekretoError("sekreto: cannot reach " + url.split("\\?")[0] + ": interrupted");
+    }
+
+    String text;
+    try (java.io.InputStream stream = response.body()) {
+      // 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.
+      byte[] raw = stream.readNBytes(MAXBODY + 1);
+      if (MAXBODY < raw.length) {
+        throw new SekretoError("sekreto: oversized response from " + url.split("\\?")[0]);
+      }
+      text = new String(raw, StandardCharsets.UTF_8);
+    } catch (IOException err) {
+      throw new SekretoError(
+          "sekreto: cannot reach " + url.split("\\?")[0] + ": " + err.getMessage());
+    }
+
+    // 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. (Json.parse answers
+    // null for anything unreadable, and only a literal `null` body is a
+    // genuine JSON null.)
+    Object parsed = Json.parse(text);
+    if (200 == response.statusCode() && null == parsed && !"null".equals(text.trim())) {
+      throw new SekretoError("sekreto: malformed response from " + url.split("\\?")[0]);
+    }
+
+    return new Answer(response.statusCode(), parsed);
+  }
+
+  /** A one-pair header map, the shape most requests here need. */
+  public static Map<String, String> headers(String... pairs) {
+    Map<String, String> out = new LinkedHashMap<>();
+    for (int index = 0; index + 1 < pairs.length; index += 2) {
+      out.put(pairs[index], pairs[index + 1]);
+    }
+    return out;
+  }
+
+  /** Walk nested JSON maps; null the moment a step is not there. */
+  @SuppressWarnings("unchecked")
+  public static Object dig(Object value, String... keys) {
+    for (String key : keys) {
+      if (!(value instanceof Map)) {
+        return null;
+      }
+      value = ((Map<String, Object>) value).get(key);
+    }
+    return value;
+  }
+
+  /** The first value that is set and non-empty, or empty. */
+  public static String first(String... candidates) {
+    for (String candidate : candidates) {
+      if (null != candidate && !candidate.isEmpty()) {
+        return candidate;
+      }
+    }
+    return "";
+  }
+
+  /**
+   * 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.
+   */
+  public static long renewtime(Object expires) {
+    double seconds = 0;
+    if (expires instanceof Number) {
+      seconds = ((Number) expires).doubleValue();
+    } else if (expires instanceof String) {
+      try {
+        seconds = Double.parseDouble((String) expires);
+      } catch (NumberFormatException err) {
+        seconds = 0;
+      }
+    }
+
+    if (0 >= seconds || Double.isNaN(seconds)) {
+      return Long.MAX_VALUE;
+    }
+
+    return System.currentTimeMillis() + (long) (Math.max(seconds - 60, 1) * 1000);
+  }
+
+  /** An address with any trailing slash removed. */
+  public static String trimslash(String text) {
+    return text.endsWith("/") ? text.substring(0, text.length() - 1) : text;
+  }
+}

package/project/.sdk/tm/java/feature/secrets/sekreto/plugins/Infisical.java

@@ -0,0 +1,139 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (java/plugins/com/voxgig/sekreto/plugins/Infisical.java)
+// 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, NOT PART OF THE CORE: it opens a socket, and the core reads
+// at most a local file. A chain that does not name this kind must not
+// carry it, so the calling project imports this definition and hands it
+// to Sekreto in the `plugins` option.
+// See docs/design/plugin-providers.md.
+
+package JAVAPACKAGE.feature.secrets.sekreto.plugins;
+
+import static JAVAPACKAGE.feature.secrets.sekreto.Addr.checkaddr;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.dig;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.fetchjson;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.first;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.headers;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.renewtime;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.trimslash;
+
+import JAVAPACKAGE.feature.secrets.sekreto.Json;
+import JAVAPACKAGE.feature.secrets.sekreto.Provider;
+import JAVAPACKAGE.feature.secrets.sekreto.Sekreto;
+import JAVAPACKAGE.feature.secrets.sekreto.Sekreto.SekretoError;
+import JAVAPACKAGE.feature.secrets.sekreto.Support;
+import JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.Answer;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import JAVAPACKAGE.feature.secrets.plugin.Definition;
+
+/**
+ * Infisical.
+ *
+ * <p>`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.
+ */
+public final class Infisical implements Provider {
+
+  /** The `infisical` kind: what `plugins` hands to Sekreto. */
+  public static final Definition PLUGIN = Support.providerplugin("infisical", spec ->
+      new Infisical(
+          Support.text(spec.get("addr")), Support.text(spec.get("token")),
+          Support.text(spec.get("clientid")), Support.text(spec.get("clientsecret")),
+          Support.text(spec.get("project")), Support.text(spec.get("environment")),
+          Support.text(spec.get("path"))));
+  private final String addr;
+  private final String token;
+  private final String clientid;
+  private final String clientsecret;
+  private final String project;
+  private final String environment;
+  private final String path;
+
+  // A configured token is kept forever; a universal-auth token carries
+  // expiresIn and is renewed shortly before it runs out.
+  private String livetoken;
+  private long renewat = Long.MAX_VALUE;
+
+  public Infisical(String addr, String token, String clientid, String clientsecret,
+      String project, String environment, String path) {
+    this.addr = addr;
+    this.token = token;
+    this.clientid = clientid;
+    this.clientsecret = clientsecret;
+    this.project = project;
+    this.environment = environment;
+    this.path = path;
+  }
+
+  private String login(String useaddr) {
+    if (null != token && !token.isEmpty()) {
+      return token;
+    }
+
+    if (null == clientid || clientid.isEmpty()
+        || null == clientsecret || clientsecret.isEmpty()) {
+      throw new SekretoError("sekreto: infisical: no token and no client credentials");
+    }
+
+    Map<String, Object> body = new LinkedHashMap<>();
+    body.put("clientId", clientid);
+    body.put("clientSecret", clientsecret);
+
+    Answer res = fetchjson("POST", useaddr + "/api/v1/auth/universal-auth/login",
+        headers("content-type", "application/json"), Json.stringify(body));
+
+    Object got = dig(res.body, "accessToken");
+    if (200 != res.status || null == got || String.valueOf(got).isEmpty()) {
+      throw new SekretoError("sekreto: infisical login failed: " + res.status);
+    }
+
+    renewat = renewtime(dig(res.body, "expiresIn"));
+
+    return String.valueOf(got);
+  }
+
+  @Override
+  public String lookup(String name) {
+    String useaddr = trimslash(first(addr, "https://app.infisical.com"));
+    checkaddr(useaddr);
+
+    String useproject = null == project ? "" : project;
+    String useenvironment = null == environment ? "" : environment;
+    if (useproject.isEmpty() || useenvironment.isEmpty()) {
+      throw new SekretoError("sekreto: infisical: no project/environment");
+    }
+
+    if (null == livetoken || System.currentTimeMillis() >= renewat) {
+      livetoken = login(useaddr);
+    }
+
+    String url = useaddr + "/api/v3/secrets/raw/" + Sekreto.envkey(name, null)
+        + "?workspaceId=" + Sigv4.uriescape(useproject)
+        + "&environment=" + Sigv4.uriescape(useenvironment)
+        + "&secretPath=" + Sigv4.uriescape(first(path, "/"));
+
+    Answer res = fetchjson("GET", url, headers("authorization", "Bearer " + livetoken), null);
+
+    if (404 == res.status) {
+      return null;
+    }
+
+    if (200 != res.status) {
+      throw new SekretoError("sekreto: infisical error: " + res.status);
+    }
+
+    Object value = dig(res.body, "secret", "secretValue");
+    return null == value ? null : String.valueOf(value);
+  }
+
+  @Override
+  public String describe() {
+    return "infisical:" + (null == project ? "" : project)
+        + "/" + (null == environment ? "" : environment);
+  }
+}

package/project/.sdk/tm/java/feature/secrets/sekreto/plugins/Onepassword.java

@@ -0,0 +1,143 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (java/plugins/com/voxgig/sekreto/plugins/Onepassword.java)
+// 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, NOT PART OF THE CORE: it opens a socket, and the core reads
+// at most a local file. A chain that does not name this kind must not
+// carry it, so the calling project imports this definition and hands it
+// to Sekreto in the `plugins` option.
+// See docs/design/plugin-providers.md.
+
+package JAVAPACKAGE.feature.secrets.sekreto.plugins;
+
+import static JAVAPACKAGE.feature.secrets.sekreto.Addr.checkaddr;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.dig;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.fetchjson;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.headers;
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.trimslash;
+
+import JAVAPACKAGE.feature.secrets.sekreto.Provider;
+import JAVAPACKAGE.feature.secrets.sekreto.Sekreto;
+import JAVAPACKAGE.feature.secrets.sekreto.Sekreto.SekretoError;
+import JAVAPACKAGE.feature.secrets.sekreto.Support;
+import JAVAPACKAGE.feature.secrets.sekreto.plugins.Httpjson.Answer;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+import JAVAPACKAGE.feature.secrets.plugin.Definition;
+
+/**
+ * 1Password, through a Connect server.
+ *
+ * <p>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.
+ */
+public final class Onepassword implements Provider {
+
+  /** The `onepassword` kind: what `plugins` hands to Sekreto. */
+  public static final Definition PLUGIN = Support.providerplugin("onepassword", spec ->
+      new Onepassword(
+          Support.text(spec.get("addr")), Support.text(spec.get("token")),
+          Support.text(spec.get("vault"))));
+  private final String addr;
+  private final String token;
+  private final String vault;
+
+  private String vaultid;
+
+  public Onepassword(String addr, String token, String vault) {
+    this.addr = addr;
+    this.token = token;
+    this.vault = vault;
+  }
+
+  private Map<String, String> auth() {
+    return headers("authorization", "Bearer " + (null == token ? "" : token));
+  }
+
+  private String resolvevault(String useaddr) {
+    String want = null == vault ? "" : vault;
+    if (want.isEmpty()) {
+      throw new SekretoError("sekreto: onepassword: no vault");
+    }
+
+    Answer res = fetchjson("GET", useaddr + "/v1/vaults", auth(), null);
+
+    if (200 != res.status || !(res.body instanceof List)) {
+      throw new SekretoError("sekreto: onepassword error: " + res.status + ": listing vaults");
+    }
+
+    for (Object entry : (List<?>) res.body) {
+      Object id = dig(entry, "id");
+      if (want.equals(id) || want.equals(dig(entry, "name"))) {
+        return String.valueOf(id);
+      }
+    }
+
+    throw new SekretoError("sekreto: onepassword: no vault named " + want);
+  }
+
+  @Override
+  public String lookup(String name) {
+    Sekreto.checkname(name);
+
+    String useaddr = trimslash(null == addr ? "" : addr);
+    if (useaddr.isEmpty()) {
+      throw new SekretoError("sekreto: onepassword: no addr");
+    }
+    checkaddr(useaddr);
+
+    if (null == vaultid) {
+      vaultid = resolvevault(useaddr);
+    }
+
+    String filter = Sigv4.uriescape("title eq \"" + name + "\"");
+    Answer found = fetchjson(
+        "GET", useaddr + "/v1/vaults/" + vaultid + "/items?filter=" + filter, auth(), null);
+
+    if (200 != found.status || !(found.body instanceof List)) {
+      throw new SekretoError(
+          "sekreto: onepassword error: " + found.status + ": finding " + name);
+    }
+
+    List<?> items = (List<?>) found.body;
+    if (items.isEmpty()) {
+      return null;
+    }
+
+    Answer item = fetchjson(
+        "GET", useaddr + "/v1/vaults/" + vaultid + "/items/" + dig(items.get(0), "id"),
+        auth(), null);
+
+    if (200 != item.status) {
+      throw new SekretoError(
+          "sekreto: onepassword error: " + item.status + ": reading " + name);
+    }
+
+    Object fields = dig(item.body, "fields");
+    List<?> fieldlist = fields instanceof List ? (List<?>) fields : new ArrayList<>();
+
+    for (Object field : fieldlist) {
+      if ("PASSWORD".equals(dig(field, "purpose"))) {
+        Object value = dig(field, "value");
+        return null == value ? null : String.valueOf(value);
+      }
+    }
+    for (Object field : fieldlist) {
+      if ("value".equals(dig(field, "label"))) {
+        Object value = dig(field, "value");
+        return null == value ? null : String.valueOf(value);
+      }
+    }
+
+    return null;
+  }
+
+  @Override
+  public String describe() {
+    return "onepassword:" + (null == vault ? "" : vault);
+  }
+}

package/project/.sdk/tm/java/feature/secrets/sekreto/plugins/Proc.java

@@ -0,0 +1,80 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (java/plugins/com/voxgig/sekreto/plugins/Proc.java)
+// 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 process to completion, shared by the two plugins that
+// read a secret through somebody else's CLI - boru and secretspec.
+//
+// In the core of no port: a kind that spawns a process is a plugin.
+
+package JAVAPACKAGE.feature.secrets.sekreto.plugins;
+
+import JAVAPACKAGE.feature.secrets.sekreto.Sekreto.SekretoError;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+
+public final class Proc {
+
+  private Proc() {}
+
+  /** What a finished child process left behind. */
+  public static final class Ran {
+    final String out;
+    final String why;
+    final int status;
+
+    Ran(String out, String why, int status) {
+      this.out = out;
+      this.why = why;
+      this.status = status;
+    }
+  }
+
+  /**
+   * Run a child to completion and collect both its streams.
+   *
+   * <p>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.
+   *
+   * <p>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.
+   */
+  public static Ran runcmd(ProcessBuilder builder, String command) {
+    try {
+      Process process = builder.start();
+
+      process.getOutputStream().close();
+
+      ByteArrayOutputStream errbuf = new ByteArrayOutputStream();
+      Thread drain =
+          new Thread(
+              () -> {
+                try {
+                  process.getErrorStream().transferTo(errbuf);
+                } catch (IOException err) {
+                  // The child went away mid-write; waitFor reports how.
+                }
+              });
+      drain.setDaemon(true);
+      drain.start();
+
+      String out = new String(process.getInputStream().readAllBytes(), StandardCharsets.UTF_8);
+      int status = process.waitFor();
+      drain.join();
+
+      return new Ran(out, new String(errbuf.toByteArray(), StandardCharsets.UTF_8).trim(), status);
+    } catch (IOException err) {
+      throw new SekretoError("sekreto: cannot run " + command + ": " + err.getMessage());
+    } catch (InterruptedException err) {
+      Thread.currentThread().interrupt();
+      throw new SekretoError("sekreto: interrupted running " + command);
+    }
+  }
+}

package/project/.sdk/tm/java/feature/secrets/sekreto/plugins/Secretspec.java

@@ -0,0 +1,138 @@
+// VENDORED: @voxgig/sekreto sdk-20260908-1556-0 (java/plugins/com/voxgig/sekreto/plugins/Secretspec.java)
+// 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, NOT PART OF THE CORE: it spawns a process, and the core
+// reads at most a local file. A chain that does not name this kind must
+// not carry it, so the calling project imports this definition and hands
+// it to Sekreto in the `plugins` option.
+// See docs/design/plugin-providers.md.
+
+package JAVAPACKAGE.feature.secrets.sekreto.plugins;
+
+import static JAVAPACKAGE.feature.secrets.sekreto.plugins.Proc.runcmd;
+
+import JAVAPACKAGE.feature.secrets.sekreto.Provider;
+import JAVAPACKAGE.feature.secrets.sekreto.Sekreto;
+import JAVAPACKAGE.feature.secrets.sekreto.Sekreto.SekretoError;
+import JAVAPACKAGE.feature.secrets.sekreto.Support;
+import JAVAPACKAGE.feature.secrets.sekreto.plugins.Proc.Ran;
+import java.util.ArrayList;
+import java.util.List;
+import JAVAPACKAGE.feature.secrets.plugin.Definition;
+
+/**
+ * SecretSpec (https://secretspec.dev).
+ *
+ * <p>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.
+ *
+ * <p>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.
+ *
+ * <p>`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.
+ *
+ * <p>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.
+ */
+public final class Secretspec implements Provider {
+
+  /** The `secretspec` kind: what `plugins` hands to Sekreto. */
+  public static final Definition PLUGIN = Support.providerplugin("secretspec", spec ->
+      new Secretspec(
+          Support.text(spec.get("command")), Support.text(spec.get("file")),
+          Support.text(spec.get("profile")), Support.text(spec.get("backend")),
+          Support.text(spec.get("reason")), Support.text(spec.get("prefix"))));
+  private final String command;
+  private final String file;
+  private final String profile;
+  private final String backend;
+  private final String reason;
+  private final String prefix;
+
+  public Secretspec(String command, String file, String profile,
+      String backend, String reason, String prefix) {
+    this.command = null == command || command.isEmpty() ? "secretspec" : command;
+    this.file = file;
+    this.profile = profile;
+    this.backend = backend;
+    this.reason = reason;
+    this.prefix = prefix;
+  }
+
+  @Override
+  public String lookup(String name) {
+    String key = Sekreto.envkey(name, prefix);
+
+    List<String> args = new ArrayList<>();
+    args.add(command);
+    if (null != file && !file.isEmpty()) {
+      args.add("--file");
+      args.add(file);
+    }
+    args.add("get");
+    args.add(key);
+    if (null != backend && !backend.isEmpty()) {
+      args.add("--provider");
+      args.add(backend);
+    }
+    if (null != profile && !profile.isEmpty()) {
+      args.add("--profile");
+      args.add(profile);
+    }
+    args.add("--reason");
+    args.add(null == reason || reason.isEmpty() ? "sekreto" : reason);
+
+    Ran ran = runcmd(new ProcessBuilder(args), command);
+    String out = ran.out;
+    String why = ran.why;
+    int status = ran.status;
+
+    if (0 == status) {
+      // The value and one newline, and nothing else.
+      return out.endsWith("\n") ? out.substring(0, out.length() - 1) : out;
+    }
+
+    if (secretspecmiss(why, key)) {
+      return null;
+    }
+
+    throw new SekretoError(
+        "sekreto: secretspec error: " + (why.isEmpty() ? "exit " + status : why));
+  }
+
+  @Override
+  public String describe() {
+    return "secretspec" + (null == backend || backend.isEmpty() ? "" : ":" + backend);
+  }
+
+  /**
+   * Does this SecretSpec failure mean "no such secret" rather than "I could
+   * not answer"?
+   *
+   * <p>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.
+   *
+   * <p>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.
+   */
+  static boolean secretspecmiss(String why, String key) {
+    return why.contains("Secret '" + key + "' not found");
+  }
+}