@sponson/adapters 0.4.0 → 0.6.0

package/dist/recipes.js

@@ -0,0 +1,246 @@
+/**
+ * Recipes: verified `http` specs for one provider's operations, shipped as YAML in `packages/adapters/recipes/`
+ * (one file per provider), so that a plan line names an operation and fills in its typed params instead of writing
+ * request templates (ADR 0020, docs/recipes.md).
+ *
+ *   providers: { http: { cloudflare: { recipe: cloudflare } } }       # optional: the recipe's API defaults
+ *   - { id: dns, adapter: http, op: resource, recipe: cloudflare.dns_cname, zone_id: …, name: …, target: … }
+ *
+ * A recipe line expands, before anything else reads it, into the `http.resource`, `http.list_item` or `http.action` params the
+ * recipe declares, with `{ param: <name> }` values and `{<name>}` path placeholders filled from the line. Identity
+ * is never the recipe's text: the ledger records the resolved API block (base URL, credential variable names,
+ * headers, encoding) and the keys and record ids the expanded requests produce, exactly as for a hand-written
+ * line. Pure apart from reading the shipped files once.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+import { SponsonError, markerKind } from "@sponson/core";
+import { paramError } from "./common.js";
+import { isObject } from "./http.js";
+/** Where the shipped recipe files are, in the source tree and in the published package alike. */
+export const RECIPES_DIR = fileURLToPath(new URL("../recipes/", import.meta.url));
+/**
+ * The environment variables a recipe's API block reads its credential from, in the order the block names them.
+ * Empty for a recipe without an API block and for a token a command prints (`az`, `gcloud`: their own login).
+ */
+export function recipeCredentialEnv(recipe) {
+    const auth = recipe.api?.auth;
+    if (!isObject(auth))
+        return [];
+    const names = (o, keys) => (isObject(o) ? keys.flatMap((k) => (typeof o[k] === "string" ? [o[k]] : [])) : []);
+    if (Array.isArray(auth.headers))
+        return auth.headers.flatMap((h) => names(h, ["value_env"]));
+    return [
+        ...names(auth, ["bearer_env", "value_env"]),
+        ...names(auth.oauth2_client_credentials, ["client_id_env", "client_secret_env"]),
+        ...names(auth.aws_sigv4, ["access_key_id_env", "secret_access_key_env"]),
+        ...names(auth.digest, ["user_env", "password_env"]),
+        ...names(auth.basic, ["user_env", "password_env"]),
+    ];
+}
+const ADAPTER = "http";
+const cache = new Map();
+/** Recipes made known without a file (`useRecipe`), by provider. */
+const unshipped = new Map();
+/** The providers that have a recipe, sorted. */
+export function recipeNames() {
+    const files = readdirSync(RECIPES_DIR)
+        .filter((f) => f.endsWith(".yaml"))
+        .map((f) => f.slice(0, -".yaml".length));
+    return [...new Set([...files, ...unshipped.keys()])].sort();
+}
+/**
+ * Make a recipe known for this process as if it were shipped, until the returned function is called. For tests of
+ * code that recipes drive (the adapter's own tests use it for a list item recipe); not exported by the package.
+ */
+export function useRecipe(recipe) {
+    unshipped.set(recipe.provider, recipe);
+    cache.set(recipe.provider, recipe);
+    return () => {
+        unshipped.delete(recipe.provider);
+        cache.delete(recipe.provider);
+    };
+}
+/** A provider's recipe; PARAM_INVALID naming the known ones when there is none. */
+export function loadRecipe(provider, param = "recipe") {
+    const cached = cache.get(provider);
+    if (cached)
+        return cached;
+    const known = recipeNames();
+    if (!known.includes(provider))
+        throw paramError(ADAPTER, `no recipe for \`${provider}\` (known: ${known.join(", ") || "none"})`, param);
+    const recipe = parseYaml(readFileSync(`${RECIPES_DIR}${provider}.yaml`, "utf8"));
+    // A malformed shipped file is a bug of this package (packages/adapters/src/recipes.test.ts checks every one).
+    if (!isObject(recipe) || recipe.provider !== provider || !isObject(recipe.ops) || (recipe.api !== undefined && !isObject(recipe.api))) {
+        throw new SponsonError("INTERNAL", `${ADAPTER}: recipes/${provider}.yaml is malformed`, { adapter: ADAPTER, recipe: provider });
+    }
+    cache.set(provider, recipe);
+    return recipe;
+}
+/** Every shipped recipe. */
+export function loadRecipes() {
+    return recipeNames().map((p) => loadRecipe(p));
+}
+/** A line's `recipe: <provider>.<op>`, located. */
+export function recipeOp(ref) {
+    if (typeof ref !== "string" || !/^[a-z0-9][a-z0-9_-]*\.[a-z0-9_]+$/.test(ref)) {
+        throw paramError(ADAPTER, "`recipe` must be `<provider>.<op>`, e.g. `cloudflare.dns_cname` (see docs/recipes.md)", "recipe");
+    }
+    const [provider, name] = ref.split(".");
+    const recipe = loadRecipe(provider);
+    const op = recipe.ops[name];
+    if (!op)
+        throw paramError(ADAPTER, `recipe \`${provider}\` has no op \`${name}\` (known: ${Object.keys(recipe.ops).join(", ")})`, "recipe");
+    return { recipe, name, op };
+}
+/** The API a line uses: its `api`, or for a recipe line without one, the recipe's provider. */
+export function lineApi(params) {
+    if (params.api !== undefined || typeof params.recipe !== "string")
+        return params.api;
+    return params.recipe.split(".")[0];
+}
+/** Params of a recipe line that are the line's own, not the recipe's. */
+const LINE_PARAMS = ["api", "recipe", "destroy", "credential"];
+/** A value the engine fills in later or keeps as it is: a reference, a marker, an uninterpolated `${…}`. */
+function isDeferred(v) {
+    if (markerKind(v) !== null)
+        return true;
+    if (typeof v === "string")
+        return v.includes("${");
+    if (!isObject(v))
+        return false;
+    const keys = Object.keys(v);
+    return keys.length === 1 && ["from", "secret", "keep"].includes(keys[0]);
+}
+const TYPE_CHECK = {
+    string: (v) => typeof v === "string",
+    integer: (v) => Number.isInteger(v),
+    number: (v) => typeof v === "number" && Number.isFinite(v),
+    boolean: (v) => typeof v === "boolean",
+    list: (v) => Array.isArray(v),
+    map: (v) => isObject(v),
+};
+function checkValue(where, name, p, v) {
+    if (isDeferred(v))
+        return;
+    const fail = (why) => paramError(ADAPTER, `${where}: \`${name}\` ${why}`, name);
+    if (!TYPE_CHECK[p.type](v))
+        throw fail(`must be ${p.type === "integer" ? "an" : "a"} ${p.type} (${p.description})`);
+    if (p.enum && !p.enum.some((e) => e === v))
+        throw fail(`must be one of ${p.enum.map((e) => JSON.stringify(e)).join(", ")}`);
+    if (p.pattern && typeof v === "string" && !new RegExp(p.pattern).test(v))
+        throw fail(`must match ${p.pattern} (${p.description})`);
+}
+/** The value of every param the line sets or the recipe defaults, checked; PARAM_INVALID naming the param otherwise. */
+export function recipeValues(params) {
+    const { recipe, name, op } = recipeOp(params.recipe);
+    const where = `recipe ${recipe.provider}.${name}`;
+    const declared = Object.keys(op.params);
+    const extra = Object.keys(params).find((k) => !LINE_PARAMS.includes(k) && !declared.includes(k));
+    if (extra)
+        throw paramError(ADAPTER, `${where}: \`${extra}\` is not one of its params (known: ${declared.join(", ")})`, extra);
+    const values = {};
+    for (const [p, spec] of Object.entries(op.params)) {
+        const v = params[p] ?? spec.default;
+        if (v === undefined || v === null) {
+            if (spec.required)
+                throw paramError(ADAPTER, `${where}: \`${p}\` is required: ${spec.description}`, p);
+            continue;
+        }
+        checkValue(where, p, spec, v);
+        values[p] = v;
+    }
+    return values;
+}
+/** `{ param: <name> }`, the one template form of a recipe's http spec. */
+function paramRef(v) {
+    return isObject(v) && Object.keys(v).length === 1 && typeof v.param === "string" ? v.param : undefined;
+}
+/** `{ join: [ … ] }`'s parts, when `v` is one: the other template form, concatenating whole values. */
+function joinParts(v) {
+    return isObject(v) && Object.keys(v).length === 1 && Array.isArray(v.join) ? v.join : undefined;
+}
+/**
+ * `{ join: [<part>, …] }`: the parts (literal strings, numbers, or `{ param: <name> }`) as one string, such as a
+ * preview URL and a path. A part that is not known yet (a reference, a marker) stands for the whole value, so a
+ * pending URL makes the joined value pending; a param without a value removes the value. Never anything richer:
+ * a recipe stays data (ADR 0020, "Amendment").
+ */
+function join(parts, values) {
+    const filled = parts.map((p) => substitute(p, values));
+    if (filled.some((p) => p === undefined))
+        return undefined;
+    // `${ctx.*}` inside a string joins like any text; a marker or a `{ from }` the engine has not resolved does not.
+    const deferred = filled.find((p) => markerKind(p) !== null || isObject(p));
+    if (deferred !== undefined)
+        return deferred;
+    return filled.map((p) => String(p)).join("");
+}
+/**
+ * `tpl` with every `{ param: <name> }` replaced by its value (a param without one removes its map key or list
+ * item) and every `{ join: [...] }` by its parts joined.
+ */
+export function substitute(tpl, values) {
+    const ref = paramRef(tpl);
+    if (ref !== undefined)
+        return values[ref];
+    const parts = joinParts(tpl);
+    if (parts !== undefined)
+        return join(parts, values);
+    if (Array.isArray(tpl))
+        return tpl.map((x) => substitute(x, values)).filter((x) => x !== undefined);
+    if (!isObject(tpl))
+        return tpl;
+    const out = {};
+    for (const [k, v] of Object.entries(tpl)) {
+        const s = substitute(v, values);
+        if (s !== undefined)
+            out[k] = s;
+    }
+    return out;
+}
+/**
+ * A line's params as the `http.<kind>` op reads them: unchanged without `recipe`, else the recipe's spec with the
+ * line's values filled in (`vars` holds every value, for the `{<name>}` path placeholders).
+ */
+export function expandRecipe(params, kind) {
+    if (params.recipe === undefined)
+        return params;
+    const { recipe, name, op } = recipeOp(params.recipe);
+    if (op.kind !== kind)
+        throw paramError(ADAPTER, `recipe ${recipe.provider}.${name} is an \`http.${op.kind}\` recipe: write \`op: ${op.kind}\``, "recipe");
+    const values = recipeValues(params);
+    const spec = substitute(op.http, values);
+    const destroy = recipeDestroy(`recipe ${recipe.provider}.${name}`, op, params.destroy);
+    // A recipe without an API block (only `url` actions) gives the line no `api` unless it writes one.
+    const api = recipe.api ? lineApi(params) : params.api;
+    const credential = params.credential !== undefined ? { credential: params.credential } : {};
+    return { ...spec, ...(api !== undefined ? { api } : {}), vars: values, ...(destroy !== undefined ? { destroy } : {}), ...credential };
+}
+/** The line's `destroy`, or the op's default; `delete` of an op the provider cannot delete is PARAM_INVALID. */
+function recipeDestroy(where, op, line) {
+    if (op.destroy === "never" && line !== undefined && line !== "keep") {
+        throw paramError(ADAPTER, `${where}: the provider offers no way to delete what it makes, so it is always left in place: remove \`destroy\` or write \`destroy: keep\``, "destroy");
+    }
+    return line ?? (op.destroy === undefined ? undefined : "keep");
+}
+/**
+ * A `providers.http.<api>` block with `recipe:`, resolved: the recipe's API defaults, then the block's own keys
+ * over them. Blocks without `recipe:` are returned as they are. The result never names the recipe, so it (and with
+ * it the ledger identity) is the same as a hand-written block with the same values.
+ */
+export function resolveRecipeApi(block, where) {
+    if (block.recipe === undefined)
+        return block;
+    const known = recipeNames();
+    const { recipe: provider, ...overrides } = block;
+    if (typeof provider !== "string" || !known.includes(provider)) {
+        throw new SponsonError("PLAN_INVALID", `${ADAPTER}: ${where}.recipe: no recipe \`${String(provider)}\` (known: ${known.join(", ")})`, { adapter: ADAPTER, key: `${where}.recipe` });
+    }
+    const api = loadRecipe(provider).api;
+    if (!api)
+        throw new SponsonError("PLAN_INVALID", `${ADAPTER}: ${where}.recipe: recipe \`${provider}\` has no API block (its ops call the app's own URL)`, { adapter: ADAPTER, key: `${where}.recipe` });
+    return { ...api, ...overrides };
+}
+//# sourceMappingURL=recipes.js.map

package/dist/recipes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipes.js","sourceRoot":"","sources":["../src/recipes.ts"],"names":[],"mappings":"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"}

package/dist/secrets.d.ts

@@ -26,3 +26,47 @@ export declare function awsSecretsManagerSource(exec?: Exec): SecretSource;
  * so a plan never depends on whichever project the runner's gcloud happens to have configured.
  */
 export declare function gcpSecretManagerSource(exec?: Exec): SecretSource;
+/**
+ * `infisical://<projectId>/<env>/[<folder>/…/]<NAME>` → `infisical secrets get`, through the Infisical CLI
+ * (https://infisical.com/docs/cli/commands/secrets). The folders become `--path` (default `/`). Credentials come
+ * from the CLI's own conventions: `INFISICAL_TOKEN` (or `INFISICAL_UNIVERSAL_AUTH_ACCESS_TOKEN`) for a machine
+ * identity, else the CLI's login; `INFISICAL_DOMAIN` for EU Cloud or a self-hosted instance. The project id is part of
+ * the reference because a machine identity has no `.infisical.json` to take it from.
+ *
+ * JSON output, not `--plain`: with `--plain` an unknown name prints nothing at all (exit 0), indistinguishable from
+ * an empty secret; with `--output json` it prints the entry with the value `*not found*`, which is refused here.
+ */
+export declare function infisicalSecretSource(exec?: Exec): SecretSource;
+/**
+ * `azure-kv://<vault>/<name>[/<version>]` → `az keyvault secret show`, through the Azure CLI so neither the Azure SDK
+ * nor an Entra ID token flow enters the dependency tree. The CLI rather than `GET {vault}/secrets/{name}` with a token
+ * from `az account get-access-token`: one process instead of two, and the CLI already knows the vault DNS suffix of
+ * the signed-in cloud (`vault.azure.net`, `vault.azure.cn`, `vault.usgovcloudapi.net`) and every way to sign in
+ * (`az login`, a service principal, a managed identity, federated CI credentials).
+ * https://learn.microsoft.com/en-us/cli/azure/keyvault/secret#az-keyvault-secret-show
+ */
+export declare function azureKeyVaultSource(exec?: Exec): SecretSource;
+/**
+ * `bws://<secret-id>` → `bws secret get`, through the Bitwarden Secrets Manager CLI
+ * (https://bitwarden.com/help/secrets-manager-cli/). The machine account's access token comes from
+ * `BWS_ACCESS_TOKEN`, a self-hosted server from `BWS_SERVER_URL` (both read by the CLI itself: crates/bws/src/cli.rs
+ * in bitwarden/sdk-sm). `--color no`: the CLI colours its JSON whenever it believes the terminal supports colour,
+ * which `FORCE_COLOR` in CI makes it believe.
+ */
+export declare function bitwardenSecretsManagerSource(exec?: Exec): SecretSource;
+/**
+ * `vault://<mount>/<path>#<key>` → HashiCorp Vault's KV v2 "read secret version", `GET /v1/<mount>/data/<path>`
+ * (https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2), over the adapters' HTTP client, no SDK. The
+ * address is `VAULT_ADDR`, the token `VAULT_TOKEN` (sent as `X-Vault-Token`), and `VAULT_NAMESPACE`, when set, is
+ * sent as `X-Vault-Namespace` (Vault Enterprise, HCP Vault Dedicated: https://developer.hashicorp.com/vault/api-docs).
+ * The mount is the first segment; the latest version is read. `#key` picks one key of the secret's map.
+ */
+export declare const vaultSecretSource: SecretSource;
+/**
+ * `op-connect://<vault>/<item>/[<section>/]<field>` → a 1Password Connect server's REST API
+ * (https://www.1password.dev/connect/api-reference/): `GET /v1/vaults/{vault}/items/{item}`, bearer
+ * `OP_CONNECT_TOKEN`, at `OP_CONNECT_HOST` (the variables 1Password's own Connect SDKs and `op` read). Vaults and
+ * items are named by id or by name / title (looked up with `GET /v1/vaults?filter=name eq "…"` and
+ * `GET /v1/vaults/{vault}/items?filter=title eq "…"`; a name must be unique); fields by id or label.
+ */
+export declare const opConnectSecretSource: SecretSource;

package/dist/secrets.js

@@ -1,5 +1,6 @@
 import { execFile } from "node:child_process";
 import { SponsonError } from "@sponson/core";
+import { apiClient, isProviderError } from "./http.js";
 /**
  * Runs the real binary from PATH; rejects with its stderr when it fails. A binary that cannot be started keeps the
  * system error's `code` (`ENOENT`, `EACCES`), so the caller can say what is wrong instead of echoing it.
@@ -183,6 +184,284 @@ export function gcpSecretManagerSource(exec = defaultExec) {
         },
     };
 }
+const INFISICAL_FORM = "expected infisical://<projectId>/<env>/<NAME> or infisical://<projectId>/<env>/<folder>/…/<NAME>";
+/**
+ * What `infisical secrets get` prints for a name the folder does not hold, in place of a value (Infisical CLI,
+ * packages/cmd/secrets.go `getSecretsByNames`). It exits 0 with it, so it must be recognised here, never passed on.
+ */
+const INFISICAL_NOT_FOUND = "*not found*";
+/**
+ * `infisical://<projectId>/<env>/[<folder>/…/]<NAME>` → `infisical secrets get`, through the Infisical CLI
+ * (https://infisical.com/docs/cli/commands/secrets). The folders become `--path` (default `/`). Credentials come
+ * from the CLI's own conventions: `INFISICAL_TOKEN` (or `INFISICAL_UNIVERSAL_AUTH_ACCESS_TOKEN`) for a machine
+ * identity, else the CLI's login; `INFISICAL_DOMAIN` for EU Cloud or a self-hosted instance. The project id is part of
+ * the reference because a machine identity has no `.infisical.json` to take it from.
+ *
+ * JSON output, not `--plain`: with `--plain` an unknown name prints nothing at all (exit 0), indistinguishable from
+ * an empty secret; with `--output json` it prints the entry with the value `*not found*`, which is refused here.
+ */
+export function infisicalSecretSource(exec = defaultExec) {
+    return {
+        scheme: "infisical",
+        form: "`infisical://projectId/env/NAME` or `infisical://projectId/env/folder/…/NAME`",
+        resolvedBy: "`infisical secrets get NAME --projectId projectId --env env --path /folder/… --output json --silent` (Infisical CLI; credentials from `INFISICAL_TOKEN` or the CLI's login, the instance from `INFISICAL_DOMAIN`). A name the folder does not hold is `SECRET_UNRESOLVED`, never a value.",
+        async resolve(ref, env) {
+            const parts = stripScheme(ref, "infisical").split("/");
+            if (parts.length < 3 || parts.some((p) => p === ""))
+                throw unresolved(ref, INFISICAL_FORM);
+            const [projectId, environment, ...rest] = parts;
+            const name = rest.pop();
+            const path = `/${rest.join("/")}`;
+            const args = ["secrets", "get", name, "--projectId", projectId, "--env", environment, "--path", path, "--output", "json", "--silent"];
+            const out = await runCli(exec, ref, "infisical", args, env, [name, projectId, environment, ...rest]);
+            // Never echo the output (or a fragment of it) in these messages: it holds the value.
+            const entries = parseJson(out);
+            const entry = Array.isArray(entries) ? entries.find((e) => isRecord(e) && e.secretKey === name) : undefined;
+            const value = isRecord(entry) ? entry.secretValue : undefined;
+            if (entry === undefined || value === INFISICAL_NOT_FOUND)
+                throw unresolved(ref, `no secret ${name} in environment ${environment} at ${path}`);
+            if (typeof value !== "string")
+                throw unresolved(ref, "the Infisical CLI returned no value");
+            return value;
+        },
+    };
+}
+const AZURE_KV_FORM = "expected azure-kv://<vault>/<name> or azure-kv://<vault>/<name>/<version>";
+/** Key Vault's own rules: vault names 3-24 of 0-9 a-z A-Z and non-consecutive `-`; secret names 1-127 of 0-9 a-z A-Z `-`; versions 32 characters. */
+const AZURE_VAULT = /^(?!.*--)[A-Za-z0-9-]{3,24}$/;
+const AZURE_SECRET = /^[A-Za-z0-9-]{1,127}$/;
+const AZURE_VERSION = /^[A-Za-z0-9]{32}$/;
+/**
+ * `azure-kv://<vault>/<name>[/<version>]` → `az keyvault secret show`, through the Azure CLI so neither the Azure SDK
+ * nor an Entra ID token flow enters the dependency tree. The CLI rather than `GET {vault}/secrets/{name}` with a token
+ * from `az account get-access-token`: one process instead of two, and the CLI already knows the vault DNS suffix of
+ * the signed-in cloud (`vault.azure.net`, `vault.azure.cn`, `vault.usgovcloudapi.net`) and every way to sign in
+ * (`az login`, a service principal, a managed identity, federated CI credentials).
+ * https://learn.microsoft.com/en-us/cli/azure/keyvault/secret#az-keyvault-secret-show
+ */
+export function azureKeyVaultSource(exec = defaultExec) {
+    return {
+        scheme: "azure-kv",
+        form: "`azure-kv://vault/name` or `azure-kv://vault/name/version`",
+        resolvedBy: "`az keyvault secret show --vault-name vault --name name [--version version] --query value --output json` (Azure CLI; credentials and cloud from `az login` and the CLI's other conventions). The version defaults to the latest.",
+        async resolve(ref, env) {
+            const parts = stripScheme(ref, "azure-kv").split("/");
+            if (parts.length < 2 || parts.length > 3)
+                throw unresolved(ref, AZURE_KV_FORM);
+            const [vault, name, version] = parts;
+            if (!AZURE_VAULT.test(vault) || !AZURE_SECRET.test(name) || (version !== undefined && !AZURE_VERSION.test(version)))
+                throw unresolved(ref, AZURE_KV_FORM);
+            const pinned = version === undefined ? [] : [version];
+            // JSON, not `-o tsv`: tsv cannot tell a value's own trailing newline from the one the CLI ends its output with.
+            const args = ["keyvault", "secret", "show", "--vault-name", vault, "--name", name, ...pinned.flatMap((v) => ["--version", v]), "--query", "value", "--output", "json"];
+            const value = parseJson(await runCli(exec, ref, "az", args, env, [vault, name, ...pinned]));
+            if (typeof value !== "string")
+                throw unresolved(ref, "the secret has no value");
+            return value;
+        },
+    };
+}
+/** Bitwarden secret ids are UUIDs (`bws secret get` parses its argument as one). */
+const BWS_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * `bws://<secret-id>` → `bws secret get`, through the Bitwarden Secrets Manager CLI
+ * (https://bitwarden.com/help/secrets-manager-cli/). The machine account's access token comes from
+ * `BWS_ACCESS_TOKEN`, a self-hosted server from `BWS_SERVER_URL` (both read by the CLI itself: crates/bws/src/cli.rs
+ * in bitwarden/sdk-sm). `--color no`: the CLI colours its JSON whenever it believes the terminal supports colour,
+ * which `FORCE_COLOR` in CI makes it believe.
+ */
+export function bitwardenSecretsManagerSource(exec = defaultExec) {
+    return {
+        scheme: "bws",
+        form: "`bws://secret-id`",
+        resolvedBy: "`bws secret get secret-id --output json --color no` (Bitwarden Secrets Manager CLI; the machine account's token from `BWS_ACCESS_TOKEN`, a self-hosted server from `BWS_SERVER_URL`). `secret-id` is the secret's UUID.",
+        async resolve(ref, env) {
+            const id = stripScheme(ref, "bws");
+            if (!BWS_ID.test(id))
+                throw unresolved(ref, "expected bws://<secret-id>, the secret's UUID");
+            const response = parseJson(await runCli(exec, ref, "bws", ["secret", "get", id, "--output", "json", "--color", "no"], env, [id]));
+            // Never echo the response (or a fragment of it) in these messages: it holds the value.
+            const value = isRecord(response) ? response.value : undefined;
+            if (typeof value !== "string")
+                throw unresolved(ref, "the Bitwarden CLI returned no value");
+            return value;
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// HTTP-backed sources: HashiCorp Vault, 1Password Connect
+// ---------------------------------------------------------------------------
+/** A variable the source cannot work without; unset or empty is SECRET_UNRESOLVED naming it. */
+function requiredVar(ref, env, name) {
+    const v = env[name];
+    if (v === undefined || v === "")
+        throw unresolved(ref, `${name} is not set`, { variable: name });
+    return v;
+}
+/** A server address from the environment: an absolute http(s) URL. */
+function requiredUrl(ref, env, name) {
+    const v = requiredVar(ref, env, name);
+    let url;
+    try {
+        url = new URL(v);
+    }
+    catch {
+        url = undefined;
+    }
+    if (url?.protocol !== "http:" && url?.protocol !== "https:")
+        throw unresolved(ref, `${name} is not an http(s) URL`, { variable: name });
+    return v;
+}
+/**
+ * The adapters' HTTP client for a secret service: its timeout (SPONSON_HTTP_TIMEOUT_MS), its retries of a 5xx or a
+ * dropped connection (SPONSON_HTTP_RETRIES), and the token masked in any error text it builds.
+ */
+function secretClient(service, baseUrl, token, authHeader, headers, env) {
+    return apiClient({ adapter: service, baseUrl, token, authHeader, headers, env, redact: (s) => s.split(token).join("***") });
+}
+/**
+ * GET a path; any failure is SECRET_UNRESOLVED. A 404 reads as `notFound`. An answer that is not JSON is reported
+ * without its text, which is where the value would be; every other failure keeps the client's message (method,
+ * path, status and the service's own error, which never holds the value; the token is masked).
+ */
+async function httpRead(ref, api, path, notFound) {
+    try {
+        return await api.get(path);
+    }
+    catch (e) {
+        if (isProviderError(e, "PROVIDER_NOT_FOUND"))
+            throw unresolved(ref, notFound, { status: 404 });
+        if (isProviderError(e, "PROVIDER_RESPONSE"))
+            throw unresolved(ref, `${api.adapter}: GET ${path} answered with something that is not JSON`);
+        if (isProviderError(e))
+            throw unresolved(ref, e.message, e.details.status === undefined ? {} : { status: e.details.status });
+        throw unresolved(ref, e.message);
+    }
+}
+const VAULT_FORM = "expected vault://<mount>/<path>#<key>";
+/** `vault://<mount>/<path>#<key>`, split; `.` and `..` segments are refused so a reference cannot climb out of the mount. */
+function vaultRef(ref) {
+    const body = stripScheme(ref, "vault");
+    const hash = body.indexOf("#");
+    const segments = (hash < 0 ? body : body.slice(0, hash)).split("/");
+    const key = hash < 0 ? "" : body.slice(hash + 1);
+    if (key === "" || segments.length < 2 || segments.some((s) => s === "" || s === "." || s === ".."))
+        throw unresolved(ref, VAULT_FORM);
+    const [mount, ...path] = segments;
+    return { mount, path, key };
+}
+/**
+ * `vault://<mount>/<path>#<key>` → HashiCorp Vault's KV v2 "read secret version", `GET /v1/<mount>/data/<path>`
+ * (https://developer.hashicorp.com/vault/api-docs/secret/kv/kv-v2), over the adapters' HTTP client, no SDK. The
+ * address is `VAULT_ADDR`, the token `VAULT_TOKEN` (sent as `X-Vault-Token`), and `VAULT_NAMESPACE`, when set, is
+ * sent as `X-Vault-Namespace` (Vault Enterprise, HCP Vault Dedicated: https://developer.hashicorp.com/vault/api-docs).
+ * The mount is the first segment; the latest version is read. `#key` picks one key of the secret's map.
+ */
+export const vaultSecretSource = {
+    scheme: "vault",
+    form: "`vault://mount/path#KEY`",
+    resolvedBy: "HashiCorp Vault KV v2, `GET $VAULT_ADDR/v1/mount/data/path` with `X-Vault-Token: $VAULT_TOKEN` (and `X-Vault-Namespace: $VAULT_NAMESPACE` when set); the latest version's `KEY`. The mount is the first segment.",
+    async resolve(ref, env) {
+        const { mount, path, key } = vaultRef(ref);
+        const addr = requiredUrl(ref, env, "VAULT_ADDR");
+        const token = requiredVar(ref, env, "VAULT_TOKEN");
+        const namespace = env.VAULT_NAMESPACE;
+        const api = secretClient("vault", addr, token, "header:X-Vault-Token", namespace ? { "X-Vault-Namespace": namespace } : {}, env);
+        const url = `/v1/${encodeURIComponent(mount)}/data/${path.map(encodeURIComponent).join("/")}`;
+        const where = `${mount}/${path.join("/")}`;
+        // Vault answers 404 both for a path that does not exist and for one the token may not see.
+        const body = await httpRead(ref, api, url, `no secret at ${where} (or the token may not read it; a KV v1 mount is not supported)`);
+        // Never echo the body (or a fragment of it) in these messages: it holds the values.
+        const data = isRecord(body) && isRecord(body.data) ? body.data.data : undefined;
+        if (!isRecord(data))
+            throw unresolved(ref, `the latest version of ${where} is deleted or destroyed, or the answer is not a KV v2 secret`);
+        return scalarField(ref, data, key, where);
+    },
+};
+/** One key of a secret's map as a string; numbers and booleans are written as JSON writes them. */
+function scalarField(ref, fields, key, where) {
+    const v = fields[key];
+    if (v === undefined)
+        throw unresolved(ref, `${where} has no key ${key}`);
+    if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean")
+        throw unresolved(ref, `key ${key} of ${where} is not a string, number or boolean`);
+    return String(v);
+}
+const OP_CONNECT_FORM = "expected op-connect://<vault>/<item>/<field> or op-connect://<vault>/<item>/<section>/<field>";
+/** Vault and item ids as Connect shows them (`ytrfte14kw1uex5txaore1emkz`); anything else is looked up by name. */
+const OP_ID = /^[a-z0-9]{26}$/;
+function opConnectRef(ref) {
+    const parts = stripScheme(ref, "op-connect").split("/");
+    if (parts.length < 3 || parts.length > 4 || parts.some((p) => p === ""))
+        throw unresolved(ref, OP_CONNECT_FORM);
+    const [vault, item] = parts;
+    return parts.length === 4 ? { vault, item, section: parts[2], field: parts[3] } : { vault, item, field: parts[2] };
+}
+/** A filter value in Connect's SCIM-style `filter` (`name eq "Demo Vault"`), quotes and backslashes escaped. */
+function scimString(s) {
+    return `"${s.replace(/[\\"]/g, (c) => `\\${c}`)}"`;
+}
+/**
+ * The id of the one vault (`attr` = `name`) or item (`title`) called `name`. The filter narrows the list; the exact
+ * comparison here decides, so a server that ignored the filter would not change the answer.
+ */
+async function opConnectFind(ref, api, list, attr, name, what) {
+    const body = await httpRead(ref, api, `${list}?filter=${encodeURIComponent(`${attr} eq ${scimString(name)}`)}`, `no ${what} named ${name}`);
+    const found = (Array.isArray(body) ? body : []).filter((e) => isRecord(e) && e[attr] === name && typeof e.id === "string");
+    if (found.length === 0)
+        throw unresolved(ref, `no ${what} named ${name}`);
+    if (found.length > 1)
+        throw unresolved(ref, `${found.length} ${what}s are named ${name}; use the id instead`);
+    return found[0].id;
+}
+/** The fields of an item's section, matched by the section's id or label. */
+function inSection(ref, item, fields, section) {
+    const sections = (Array.isArray(item.sections) ? item.sections : []).filter(isRecord);
+    const ids = new Set(sections.filter((s) => s.id === section || s.label === section).map((s) => s.id));
+    if (ids.size === 0)
+        throw unresolved(ref, `the item has no section ${section}`);
+    return fields.filter((f) => isRecord(f.section) && ids.has(f.section.id));
+}
+/** The value of the one field matched by id, else by label, as `op read` matches them. */
+function opConnectField(ref, item, r) {
+    if (!isRecord(item) || !Array.isArray(item.fields))
+        throw unresolved(ref, "the item has no fields");
+    let fields = item.fields.filter(isRecord);
+    if (r.section !== undefined)
+        fields = inSection(ref, item, fields, r.section);
+    const byId = fields.filter((f) => f.id === r.field);
+    const matches = byId.length > 0 ? byId : fields.filter((f) => f.label === r.field);
+    if (matches.length === 0)
+        throw unresolved(ref, `the item has no field ${r.field}`);
+    if (matches.length > 1)
+        throw unresolved(ref, `${matches.length} fields of the item are labelled ${r.field}; name its section or use the field id`);
+    // Never echo the value (or a fragment of it) in these messages.
+    const value = matches[0].value;
+    if (typeof value !== "string" || value === "")
+        throw unresolved(ref, `field ${r.field} has no value`);
+    return value;
+}
+/**
+ * `op-connect://<vault>/<item>/[<section>/]<field>` → a 1Password Connect server's REST API
+ * (https://www.1password.dev/connect/api-reference/): `GET /v1/vaults/{vault}/items/{item}`, bearer
+ * `OP_CONNECT_TOKEN`, at `OP_CONNECT_HOST` (the variables 1Password's own Connect SDKs and `op` read). Vaults and
+ * items are named by id or by name / title (looked up with `GET /v1/vaults?filter=name eq "…"` and
+ * `GET /v1/vaults/{vault}/items?filter=title eq "…"`; a name must be unique); fields by id or label.
+ */
+export const opConnectSecretSource = {
+    scheme: "op-connect",
+    form: "`op-connect://vault/item/field` or `op-connect://vault/item/section/field`",
+    resolvedBy: "a 1Password Connect server, `GET $OP_CONNECT_HOST/v1/vaults/vault/items/item` with `Authorization: Bearer $OP_CONNECT_TOKEN`. `vault` and `item` are ids or unique names (looked up with `?filter=`); `section` and `field` are ids or labels.",
+    async resolve(ref, env) {
+        const r = opConnectRef(ref);
+        const host = requiredUrl(ref, env, "OP_CONNECT_HOST");
+        const api = secretClient("1password-connect", host, requiredVar(ref, env, "OP_CONNECT_TOKEN"), "bearer", {}, env);
+        const vaultId = OP_ID.test(r.vault) ? r.vault : await opConnectFind(ref, api, "/v1/vaults", "name", r.vault, "vault");
+        const itemId = OP_ID.test(r.item) ? r.item : await opConnectFind(ref, api, `/v1/vaults/${vaultId}/items`, "title", r.item, "item");
+        const item = await httpRead(ref, api, `/v1/vaults/${vaultId}/items/${itemId}`, `no item ${r.item} in vault ${r.vault} (or the token may not read it)`);
+        return opConnectField(ref, item, r);
+    },
+};
 function isRecord(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }