@penvhq/varlock-plugin 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# @penvhq/varlock-plugin
+
+A [varlock](https://varlock.dev) plugin that loads secrets from [penv.cloud](https://penv.cloud). It reads the same `@penv=org/project` header and `penv(...)` addresses as the [penv CLI](https://github.com/penvhq/penvhq), so one `.env.schema` runs under both tools.
+
+## Install
+
+```bash
+npm install -D @penvhq/varlock-plugin
+```
+
+Or load it by name and version from the schema; varlock fetches it (see varlock's [plugins guide](https://varlock.dev/guides/plugins/)):
+
+```env-spec
+# @plugin(@penvhq/varlock-plugin@0.1.0)
+```
+
+## Setup
+
+```env-spec
+# @plugin(@penvhq/varlock-plugin)
+# @penv=acme/api
+# @initPenv(environment=$APP_ENV, token=$PENV_TOKEN)
+# @currentEnv=$APP_ENV
+# ---
+
+# @type=enum(development, staging, production)
+APP_ENV=development
+
+# @type=penvToken
+PENV_TOKEN=
+```
+
+`PENV_TOKEN` is a penv.cloud machine token (`pck_…`) scoped to the environments the app reads. `penvToken` is sensitive and internal: varlock uses it and does not pass it to your app.
+
+| `@initPenv()` option | Default |
+|---|---|
+| `token` | none; required before any value is read |
+| `environment` | `development`. Pointing it at the `@currentEnv` item keeps them in step. Taken whole, so `feature/foo` is one environment |
+| `url` | `https://penv.cloud`. Any other root is used only when `PENV_URL` names the same root, so a changed schema cannot send the token elsewhere |
+| `org`, `project` | from `@penv=` |
+| `cacheTtl` | no cache. `"5m"`, `"1h"`, `"1d"` or `"forever"` keeps each environment's values in varlock's local cache for that long |
+
+## Usage
+
+```env-spec
+DATABASE_URL=penv()                                   # the item key, default environment
+STRIPE_SECRET_KEY=penv(STRIPE_KEY)                    # another key
+PROD_DATABASE_URL=penv(production/DATABASE_URL)       # another environment
+BILLING_TOKEN=penv(billing/production/API_TOKEN)      # another project
+SENTRY_DSN=penv(acme-shared/observability/production/SENTRY_DSN)   # another org
+```
+
+An environment whose name holds a `/` cannot be written in a `penv(...)` address; name it in `@initPenv(environment=...)` or `penvBulk(...)`.
+
+Bulk-load an environment:
+
+```env-spec
+# @setValuesBulk(penvBulk())
+# @setValuesBulk(penvBulk(production))
+# @setValuesBulk(penvBulk("feature/foo"))
+```
+
+## The same schema under the penv CLI
+
+```bash
+varlock run -- npm run dev    # through this plugin
+penv run -- npm run dev       # native; penv ignores @plugin and @initPenv
+```
+
+## Errors
+
+| Error | Fix |
+|---|---|
+| `penv.cloud rejected the token` | create a machine token and set `PENV_TOKEN` |
+| `the token may not read org/project/env` | give the machine identity that project and environment |
+| `org/project/env does not exist on penv.cloud` | check the names; `penv project ls` |
+| `KEY is not in org/project/env` | `penv set KEY --env env` |
+| `KEY has no stored value` | `penv set KEY --env env` |
+| `penv url … is not penv.cloud, so the token is not sent there` | set `PENV_URL` to that root, or drop `url=` |
+
+Requests are https only (`http://localhost` for tests), follow no redirects, time out after 15 seconds, and each environment is read once per load. No error prints a token or a value.
+
+## Develop
+
+```bash
+npm install
+npm test          # builds, then runs the published varlock CLI against a fake penv.cloud
+npm run typecheck
+```

package/dist/plugin.cjs

@@ -0,0 +1,330 @@
+"use strict";
+
+// src/plugin.ts
+var import_plugin_lib = require("varlock/plugin-lib");
+var import_node_crypto = require("node:crypto");
+var { SchemaError, ResolutionError } = import_plugin_lib.plugin.ERRORS;
+var PENV_ICON = "mdi:shield-key-outline";
+var DEFAULT_URL = "https://penv.cloud";
+var TIMEOUT_MS = 15e3;
+import_plugin_lib.plugin.name = "penv";
+var { debug } = import_plugin_lib.plugin;
+var VERSION = import_plugin_lib.plugin.version;
+debug("init - version =", VERSION);
+var pluginCache;
+try {
+  pluginCache = import_plugin_lib.plugin.cache;
+} catch {
+}
+import_plugin_lib.plugin.icon = PENV_ICON;
+import_plugin_lib.plugin.standardVars = {
+  initDecorator: "@initPenv",
+  params: {
+    token: { key: "PENV_TOKEN", dataType: "penvToken" }
+  }
+};
+function valuesMap() {
+  return /* @__PURE__ */ Object.create(null);
+}
+function toValues(source) {
+  const out = valuesMap();
+  if (source && typeof source === "object") {
+    for (const [name, value] of Object.entries(source)) {
+      out[name] = typeof value === "string" ? value : void 0;
+    }
+  }
+  return out;
+}
+var header;
+function checkedUrl(raw) {
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new SchemaError(`penv url "${raw}" is not a URL`);
+  }
+  const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+    throw new SchemaError(`penv url must be https (http only for localhost): ${url.origin}`);
+  }
+  if (url.username || url.password) {
+    throw new SchemaError("penv url must not carry a user name or password");
+  }
+  return url.origin + url.pathname.replace(/\/+$/, "");
+}
+function label(at) {
+  return `${at.org}/${at.project}/${at.environment}`;
+}
+var PenvInstance = class {
+  environment = "development";
+  url = DEFAULT_URL;
+  cacheTtl;
+  token;
+  org;
+  project;
+  reads = /* @__PURE__ */ new Map();
+  set(opts) {
+    if (typeof opts.environment === "string" && opts.environment) this.environment = opts.environment;
+    if (typeof opts.url === "string" && opts.url) {
+      const url = checkedUrl(opts.url);
+      const chosen = process.env.PENV_URL ? checkedUrl(process.env.PENV_URL) : void 0;
+      if (url !== DEFAULT_URL && url !== chosen) {
+        throw new SchemaError(`penv url ${url} is not penv.cloud, so the token is not sent there`, {
+          tip: `Set PENV_URL=${url} as well to send it on purpose, or remove url= to use penv.cloud`
+        });
+      }
+      this.url = url;
+    }
+    if (typeof opts.token === "string" && opts.token.trim()) this.token = opts.token.trim();
+    if (typeof opts.org === "string" && opts.org) this.org = opts.org;
+    if (typeof opts.project === "string" && opts.project) this.project = opts.project;
+  }
+  /** The org and project `@initPenv()` or `@penv=` names; `written` is only for the error. */
+  home(written) {
+    const org = this.org ?? header?.org;
+    const project = this.project ?? header?.project;
+    if (!org || !project) {
+      throw new SchemaError(`${written} needs a project`, {
+        tip: "Add # @penv=org/project to the header, or pass org and project to @initPenv()"
+      });
+    }
+    return { org, project };
+  }
+  /**
+   * `KEY`, `env/KEY`, `project/env/KEY` or `org/project/env/KEY`, as the penv CLI
+   * reads them. An environment whose name holds a `/` cannot be written here;
+   * name it in `@initPenv(environment=...)` or `penvBulk(...)`, which take it whole.
+   */
+  address(written) {
+    const parts = written.split("/").map((p) => p.trim());
+    if (parts.some((p) => !p) || parts.length > 4) {
+      throw new SchemaError(`penv(${written}) is not an address`, {
+        tip: "Write penv(), penv(KEY), penv(env/KEY), penv(project/env/KEY) or penv(org/project/env/KEY)"
+      });
+    }
+    const key = parts[parts.length - 1];
+    if (parts.length === 4) return { org: parts[0], project: parts[1], environment: parts[2], key };
+    const { org, project } = this.home(`penv(${written})`);
+    if (parts.length === 3) return { org, project: parts[0], environment: parts[1], key };
+    if (parts.length === 2) return { org, project, environment: parts[0], key };
+    return { org, project, environment: this.environment, key };
+  }
+  /** One environment of the home project, its name taken whole. */
+  environmentOf(name) {
+    return { ...this.home(`penvBulk(${name})`), environment: name };
+  }
+  /** Short hash naming the token, so a cache is never shared between credentials. */
+  scope(at) {
+    const who = (0, import_node_crypto.createHash)("sha256").update(this.token ?? "").digest("hex").slice(0, 12);
+    return `${who}:${this.url}:${label(at)}`;
+  }
+  /** Every value of one environment: once per load, and through the cache when `cacheTtl` is set. */
+  async read(at) {
+    if (this.cacheTtl !== void 0 && pluginCache) {
+      const cached = await pluginCache.getOrSet(`penv:${this.scope(at)}`, this.cacheTtl, async () => {
+        const values = await this.once(at);
+        return Object.fromEntries(Object.entries(values));
+      });
+      return toValues(cached);
+    }
+    return this.once(at);
+  }
+  once(at) {
+    const key = label(at);
+    let pending = this.reads.get(key);
+    if (!pending) {
+      pending = this.fetchEnvironment(at);
+      this.reads.set(key, pending);
+      pending.catch(() => this.reads.delete(key));
+    }
+    return pending;
+  }
+  async fetchEnvironment(at) {
+    if (!this.token) {
+      throw new SchemaError("penv token is required", {
+        tip: "Pass token=$PENV_TOKEN to @initPenv() and set PENV_TOKEN"
+      });
+    }
+    const where = label(at);
+    const path = [at.org, at.project, at.environment].map(encodeURIComponent).join("/");
+    let response;
+    try {
+      response = await fetch(`${this.url}/api/v1/envs/${path}`, {
+        headers: {
+          authorization: `Bearer ${this.token}`,
+          accept: "application/json",
+          "user-agent": `penvhq-varlock-plugin/${VERSION}`
+        },
+        // A redirect could carry the token to another host.
+        redirect: "error",
+        signal: AbortSignal.timeout(TIMEOUT_MS)
+      });
+    } catch (err) {
+      const why = err?.name === "TimeoutError" ? "timed out" : "network error or redirect";
+      throw new ResolutionError(`penv.cloud could not be read for ${where}: ${why}`, {
+        tip: `Check the network, and that ${this.url} is the right url`
+      });
+    }
+    if (response.status === 401) {
+      throw new ResolutionError(`penv.cloud rejected the token for ${where}`, {
+        tip: "Create a machine token in the penv.cloud console and set PENV_TOKEN"
+      });
+    }
+    if (response.status === 403) {
+      throw new ResolutionError(`the token may not read ${where}`, {
+        tip: "Give the machine identity this project and environment in the penv.cloud console"
+      });
+    }
+    if (response.status === 404) {
+      throw new ResolutionError(`${where} does not exist on penv.cloud`, {
+        tip: "Check the org, project and environment names; `penv project ls` lists them"
+      });
+    }
+    if (!response.ok) {
+      throw new ResolutionError(`penv.cloud answered ${response.status} for ${where}`);
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new ResolutionError(`penv.cloud answered ${where} with something that is not JSON`);
+    }
+    const values = valuesMap();
+    for (const key of Array.isArray(body?.keys) ? body.keys : []) {
+      if (!key || key.path || typeof key.name !== "string") continue;
+      values[key.name] = typeof key.value === "string" ? key.value : void 0;
+    }
+    debug(`read ${Object.keys(values).length} keys from ${where}`);
+    return values;
+  }
+  async value(at) {
+    const values = await this.read(at);
+    const where = label(at);
+    if (!Object.hasOwn(values, at.key)) {
+      throw new ResolutionError(`${at.key} is not in ${where}`, {
+        tip: `Add it with: penv set ${at.key} --env ${at.environment}`
+      });
+    }
+    const value = values[at.key];
+    if (value === void 0) {
+      throw new ResolutionError(`${at.key} has no stored value in ${where}`, {
+        tip: `Set one with: penv set ${at.key} --env ${at.environment}`
+      });
+    }
+    return value;
+  }
+  /** Every stored value, as the JSON `@setValuesBulk` reads. */
+  async bulk(environment) {
+    const values = await this.read(this.environmentOf(environment));
+    return JSON.stringify(Object.fromEntries(Object.entries(values).filter(([, v]) => v !== void 0)));
+  }
+};
+var instance = new PenvInstance();
+var initialised = false;
+import_plugin_lib.plugin.registerRootDecorator({
+  name: "penv",
+  description: "The penv.cloud org and project this schema reads: org/project",
+  process(decVal) {
+    if (!decVal.isStatic || typeof decVal.staticValue !== "string") {
+      throw new SchemaError("@penv= takes a static org/project");
+    }
+    let value = decVal.staticValue.trim();
+    const colon = value.indexOf(":");
+    if (colon !== -1) {
+      const provider = value.slice(0, colon);
+      if (provider !== "penv") {
+        throw new SchemaError(`@penv=${value} names provider "${provider}"; this plugin reads penv.cloud only`);
+      }
+      value = value.slice(colon + 1);
+    }
+    const [org, project, ...rest] = value.split("/");
+    if (!org || !project || rest.length) {
+      throw new SchemaError(`@penv=${value} is not org/project`);
+    }
+    header = { org, project };
+    return {};
+  }
+});
+import_plugin_lib.plugin.registerRootDecorator({
+  name: "initPenv",
+  description: "Configure penv.cloud access for penv() and penvBulk()",
+  isFunction: true,
+  async process(argsVal) {
+    if (initialised) throw new SchemaError("@initPenv() is already set");
+    initialised = true;
+    const objArgs = argsVal.objArgs ?? {};
+    return {
+      environmentResolver: objArgs.environment,
+      tokenResolver: objArgs.token,
+      urlResolver: objArgs.url,
+      orgResolver: objArgs.org,
+      projectResolver: objArgs.project,
+      cacheTtlResolver: objArgs.cacheTtl
+    };
+  },
+  async execute({
+    environmentResolver,
+    tokenResolver,
+    urlResolver,
+    orgResolver,
+    projectResolver,
+    cacheTtlResolver
+  }) {
+    instance.set({
+      environment: await environmentResolver?.resolve(),
+      token: await tokenResolver?.resolve(),
+      url: await urlResolver?.resolve(),
+      org: await orgResolver?.resolve(),
+      project: await projectResolver?.resolve()
+    });
+    const cacheTtl = await (0, import_plugin_lib.resolveCacheTtl)(cacheTtlResolver);
+    if (cacheTtl !== void 0) instance.cacheTtl = cacheTtl;
+  }
+});
+import_plugin_lib.plugin.registerDataType({
+  name: "penvToken",
+  sensitive: true,
+  internal: true,
+  typeDescription: "penv.cloud machine token (pck_...)",
+  icon: PENV_ICON,
+  docs: [{ description: "penv.cloud API", url: "https://github.com/penvhq/penvhq/blob/main/docs/Cloud-API.md" }]
+});
+import_plugin_lib.plugin.registerResolverFunction({
+  name: "penv",
+  label: "Read a value from penv.cloud",
+  icon: PENV_ICON,
+  argsSchema: { type: "array", arrayMinLength: 0, arrayMaxLength: 1 },
+  process() {
+    let written;
+    let itemKey;
+    if (this.arrArgs?.length) {
+      written = this.arrArgs[0];
+    } else {
+      const parent = this.parent;
+      if (!parent || typeof parent.key !== "string") {
+        throw new SchemaError("penv() with no argument reads the key it is on, so it must be on a config item");
+      }
+      itemKey = parent.key;
+    }
+    return { written, itemKey };
+  },
+  async resolve({ written, itemKey }) {
+    const address = written ? await written.resolve() : itemKey;
+    if (typeof address !== "string") throw new SchemaError("penv() takes an address written as text");
+    return instance.value(instance.address(address));
+  }
+});
+import_plugin_lib.plugin.registerResolverFunction({
+  name: "penvBulk",
+  label: "Load every value of a penv.cloud environment",
+  icon: PENV_ICON,
+  argsSchema: { type: "array", arrayMaxLength: 1 },
+  process() {
+    return { environment: this.arrArgs?.[0] };
+  },
+  async resolve({ environment }) {
+    const name = environment ? await environment.resolve() : instance.environment;
+    if (typeof name !== "string" || !name) throw new SchemaError("penvBulk() takes an environment name");
+    return instance.bulk(name);
+  }
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@penvhq/varlock-plugin",
+  "version": "0.1.0",
+  "description": "varlock plugin that loads secrets from penv.cloud",
+  "type": "module",
+  "homepage": "https://github.com/penvhq/penvhq/tree/main/packages/varlock-plugin#readme",
+  "bugs": "https://github.com/penvhq/penvhq/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/penvhq/penvhq.git",
+    "directory": "packages/varlock-plugin"
+  },
+  "license": "MIT",
+  "exports": {
+    "./plugin": "./dist/plugin.cjs"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "esbuild src/plugin.ts --bundle --platform=node --format=cjs --target=node22 --external:varlock --outfile=dist/plugin.cjs",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/plugin.test.mjs"
+  },
+  "keywords": ["varlock", "varlock-plugin", "penv", "penv.cloud", "secrets", "env", ".env"],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "varlock": ">=1.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.9.0",
+    "varlock": "1.20.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}