@theholocron/holocron-plugin-infisical 2.0.0-alpha.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+<!-- editorconfig-checker-disable-file -->
+
+# `@theholocron/holocron-plugin-infisical`
+
+Infisical plugin for [Holocron](../cli). Implements the `vault`
+capability against [Infisical's REST API](https://infisical.com/docs/api-reference/overview/introduction),
+plus exports `verifyToken` + `AUTH_HINT` for use by `holocron auth`.
+
+## One of several vault providers
+
+`vault` is a REQUIRED capability but Infisical is one of several
+providers you can pick. Peer plugins:
+
+- **[`@theholocron/holocron-plugin-doppler`](../holocron-plugin-doppler)**
+  — this repo's own default vault since `2.0.0-alpha.4`.
+- **[`@theholocron/holocron-plugin-1password`](../holocron-plugin-1password)**
+  — for teams already invested in 1Password's biometric UX.
+- **This plugin** — for teams that want an open-source vault they
+  can self-host later if desired.
+
+Switch by editing `holocron.config.json`.
+
+### When to choose Infisical
+
+- You want an open-source vault with a clear path to self-hosting
+  (the plugin's `baseUrl` option points at cloud today; swap it for
+  your self-hosted URL later, no code changes).
+- Machine-identity + Universal Auth token model matches your
+  security posture better than dashboard-generated Personal Tokens.
+- Your team already uses Infisical for other projects.
+
+## Install
+
+```bash
+pnpm add -D @theholocron/holocron-plugin-infisical@alpha
+```
+
+## Auth
+
+Token resolution order (matches the standard 4-step precedence set
+by `.notes/tech-auth-bootstrap.spec.md`):
+
+1. `--token <TOKEN>` flag on the holocron invocation
+2. `HOLOCRON_INFISICAL_TOKEN` env var (preferred — explicit intent)
+3. `INFISICAL_TOKEN` env var (Infisical-native, works in CI)
+4. **Keyring** — `com.theholocron.cli` service, account `infisical`
+5. `AuthError` naming all four options + the bootstrap hint
+
+## Setup
+
+**Important**: this plugin sends the stored value as
+`Authorization: Bearer <token>` directly. That means you need a token
+that IS a bearer, not a credential-pair that needs an exchange.
+
+Two token types work out of the box:
+
+- **Personal API Token** — inherits your user permissions, simplest
+  path.
+- **Token Auth** on a machine identity — long-lived, single-string
+  token. In Infisical: **organization access control → identities →
+  your identity → add auth method → Token Auth → create token**.
+
+**Universal Auth's Client Secret does NOT work directly** —
+Universal Auth is a two-step flow (client id + client secret → login
+endpoint → short-lived access token). Support for that exchange is
+tracked as a follow-up; for now, use one of the two above.
+
+```bash
+# 1. Generate the token per the note above.
+# 2. Hand it off to holocron's keyring (one-shot):
+holocron auth set infisical <TOKEN>
+# 3. Verify (calls GET /v1/workspace and reports accessible workspaces):
+holocron auth check infisical
+```
+
+**If you have a machine identity that's Universal-Auth-only**: add a
+Token Auth authentication method to the SAME identity — you don't
+have to create a new identity. Machine identities can have multiple
+auth methods attached.
+
+**CI**: the keyring is not available in headless containers. Expose
+the token as a GitHub Actions secret and set `HOLOCRON_INFISICAL_TOKEN`
+(or `INFISICAL_TOKEN`) in the workflow env. Steps 1–3 of the auth
+precedence still work; step 4 quietly falls through.
+
+## Config
+
+```jsonc
+{
+	"providers": {
+		"vault": ["infisical", { "workspace": "<workspace-id>", "environment": "dev" }],
+	},
+}
+```
+
+- `workspace` (required) — Infisical workspace (project) id. Find via
+  the workspace URL or the API. **Not the workspace slug** — Infisical's
+  API rejects slug in this position ([Infisical#1894](https://github.com/Infisical/infisical/issues/1894)).
+- `environment` (required) — Environment slug (usually `dev`, `stg`,
+  or `prd`). `list()` reads secrets from this environment.
+
+Individual `read` / `write` calls take a fully-qualified reference:
+
+```
+infisical://<workspaceId>/<environment>/<name>
+```
+
+The default `workspace` + `environment` in options apply to `list()`,
+`environments()`, and `readEnvironment()` where a three-part reference
+doesn't make sense.
+
+## What's implemented
+
+| Method              | Behavior                                                                                                             |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `read`              | `GET /v3/secrets/raw/{name}?workspaceId&environment&secretPath=/`.                                                   |
+| `write`             | `POST /v3/secrets/raw/{name}` (create); falls back to `PATCH` on "already exists" body for upsert semantics.         |
+| `list`              | `GET /v3/secrets/raw` at the default `workspace + environment + secretPath=/`.                                       |
+| `environments`      | `GET /v1/workspace/{workspaceId}`, returns each environment's `slug`.                                                |
+| `readEnvironment`   | `GET /v3/secrets/raw?workspaceId&environment=<id>` — bulk KEY=VALUE dump for `holocron secrets sync`.                |
+| `ensureProject`     | `POST /v2/workspace` with `{ projectName, slug }`. Treats 400/409/422 "already exists" as idempotent no-op.          |
+| `ensureEnvironment` | `POST /v1/workspace/{project}/environments` with `{ environmentName, environmentSlug }`. Same idempotency semantics. |
+
+Plugin-level exports (not capability methods, per the auth-bootstrap
+convention):
+
+| Export        | Purpose                                                                                                                                                                           |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `verifyToken` | `GET /v1/workspace` — returns `{ok: true, subject: "<n> workspaces · first: …"}` or `{ok: false, message}`. Works for both Personal Tokens and Universal Auth machine identities. |
+| `AUTH_HINT`   | Points at Infisical's docs for token generation (rather than a specific click path — dashboard UI shifts).                                                                        |
+
+## Self-hosted Infisical
+
+Set the `baseUrl` option in `holocron.config.json`:
+
+```jsonc
+{
+	"providers": {
+		"vault": [
+			"infisical",
+			{
+				"workspace": "<id>",
+				"environment": "dev",
+				"baseUrl": "https://infisical.internal.example.com/api",
+			},
+		],
+	},
+}
+```
+
+## Status
+
+**`v2.0.0-alpha.1`** — scaffolded via `holocron plugin create` (see
+`.notes/tool-plugin-create.spec.md` — this is the first real
+production use of that command, doubling as its acceptance test in
+a live scenario). Not yet published on npm; capability methods are
+implemented but not yet validated against a live Infisical account.
+APIs may still shift before stable v2.0.0.

package/dist/index.d.mts

@@ -0,0 +1,181 @@
+import { EnsureResult, Vault } from "@theholocron/cli";
+
+//#region src/auth.d.ts
+/**
+ * Token resolution for the Infisical plugin.
+ *
+ * Resolution order (matches the standard 4-step precedence set by
+ * `.notes/tech-auth-bootstrap.spec.md`):
+ *   1. explicit `cliToken` argument (from `--token` flag)
+ *   2. HOLOCRON_INFISICAL_TOKEN env var (preferred — explicit intent)
+ *   3. INFISICAL_TOKEN env var (vendor-native)
+ *   4. keyring (com.theholocron.cli / "infisical")
+ *   5. AuthError naming all four options + the bootstrap hint
+ */
+declare class AuthError extends Error {
+  name: string;
+}
+interface ResolveTokenInput {
+  /** From `--token` CLI flag. */
+  cliToken?: string;
+  /** Env vars; passed in for testability. Defaults to `process.env`. */
+  env?: NodeJS.ProcessEnv;
+  /** Keyring lookup fn; passed in for testability. Defaults to `getToken(provider)`. */
+  keyring?: (provider: string) => string | null;
+}
+declare function resolveToken(input?: ResolveTokenInput): string;
+//#endregion
+//#region src/rest.d.ts
+/**
+ * Thin REST wrapper around https://app.infisical.com/api.
+ *
+ * Bearer auth, JSON-only bodies, transport-failure wrapping with
+ * `status: 0` so orchestrator soft-skip paths see a clear message
+ * instead of a generic `TypeError: fetch failed`.
+ */
+interface RestClientOptions {
+  token: string;
+  fetch?: typeof fetch;
+  baseUrl?: string;
+}
+interface RequestOptions {
+  method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+  body?: unknown;
+  query?: Record<string, string>;
+  /** Treat this response as void even if 200 is returned. */
+  expectNoContent?: boolean;
+}
+declare class InfisicalRestClient {
+  private readonly token;
+  private readonly fetchImpl;
+  readonly baseUrl: string;
+  constructor(opts: RestClientOptions);
+  request<T>(path: string, opts?: RequestOptions): Promise<T>;
+}
+//#endregion
+//#region src/capabilities/vault.d.ts
+interface InfisicalVaultOptions {
+  /** Default workspace (project) id — read/list/etc. operate here unless overridden. */
+  workspace: string;
+  /** Default environment slug — e.g., "dev", "stg", "prd". */
+  environment: string;
+}
+declare class InfisicalVault implements Vault {
+  private readonly rest;
+  readonly key: "vault";
+  readonly providerName = "infisical";
+  private readonly workspace;
+  private readonly environment;
+  /**
+   * Cache of resolved workspace name/slug → id. `ensureEnvironment`
+   * is called once per environment during `holocron setup` (dev / stg
+   * / prd), so a single \`GET /v1/workspace\` lookup covers all three
+   * calls in the same run.
+   */
+  private readonly workspaceIdCache;
+  constructor(rest: InfisicalRestClient, opts: InfisicalVaultOptions);
+  read(reference: string): Promise<string>;
+  write(reference: string, value: string): Promise<void>;
+  list(): Promise<string[]>;
+  environments(): Promise<string[]>;
+  readEnvironment(environmentId: string): Promise<Record<string, string>>;
+  ensureProject(name: string): Promise<EnsureResult>;
+  ensureEnvironment(project: string, name: string): Promise<EnsureResult>;
+  /**
+   * Resolve a workspace name / slug to its Infisical workspace id.
+   *
+   * `runSetup` calls `ensureEnvironment(config.project.name, envName)`
+   * — for Doppler that's directly the API's input, but Infisical's
+   * environments endpoint takes the workspace **id** (UUID/nanoid),
+   * not the name. This helper does the translation via
+   * `GET /v1/workspace` (which the token needs org-level list scope
+   * to call).
+   *
+   * Graceful degrade: for workspace-scoped tokens that 403 on the
+   * org-level list, we fall back to treating the input as an id
+   * directly. If the operator's `holocron.config.json` names a real
+   * id, the subsequent POST works. If they named a slug, the POST
+   * 404s and the operator gets a clear "workspace not found" error
+   * from the API — better than swallowing the 403 silently.
+   *
+   * Results are cached per-instance so the 3 back-to-back
+   * `ensureEnvironment` calls in `runSetup` share one lookup.
+   */
+  private resolveWorkspaceId;
+}
+//#endregion
+//#region src/verify-token.d.ts
+/**
+ * `verifyToken` — plugin-level export used by `holocron auth set` +
+ * `holocron auth check`. Hits `GET /v1/workspace` and interprets the
+ * response permissively:
+ *
+ *   - 200 → token is valid AND has workspace-list scope; report the
+ *     workspace count + first workspace name.
+ *   - 403 → token is valid (authenticated) but doesn't have scope
+ *     to list workspaces at the org level. This is normal for
+ *     Universal Auth machine-identity tokens that are scoped to a
+ *     specific workspace rather than org-wide. Return ok with a
+ *     "scope-limited" subject — the operator's `holocron.config.json`
+ *     will name the specific workspace + environment the token
+ *     actually has access to.
+ *   - 401 or other → token is invalid.
+ *
+ * The distinction matters: verifyToken answers "is this a real
+ * Infisical token?", not "does it have every possible permission?"
+ * — per-capability permission failures surface at the actual read /
+ * write / list call sites.
+ *
+ * Kept as a standalone function (not a capability method) so the auth
+ * command can call it without initializing the full plugin — plugin
+ * construction requires an already-resolved token, which is exactly
+ * what we don't have yet at bootstrap time.
+ */
+interface VerifyTokenSuccess {
+  ok: true;
+  subject: string;
+}
+interface VerifyTokenFailure {
+  ok: false;
+  message: string;
+}
+type VerifyTokenResult = VerifyTokenSuccess | VerifyTokenFailure;
+interface VerifyTokenOptions {
+  baseUrl?: string;
+  fetch?: typeof fetch;
+}
+declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<VerifyTokenResult>;
+//#endregion
+//#region src/index.d.ts
+interface InfisicalPluginOptions extends ResolveTokenInput, InfisicalVaultOptions {
+  /** Override base URL for tests (or self-hosted Infisical). */
+  baseUrl?: string;
+  /** Override `fetch` for tests. */
+  fetch?: typeof fetch;
+}
+interface PluginContext {
+  options: InfisicalPluginOptions;
+  rest: InfisicalRestClient;
+}
+declare function createContext(options: InfisicalPluginOptions): PluginContext;
+declare function vault(ctx: PluginContext): Vault;
+declare function createPlugin(options: InfisicalPluginOptions): {
+  name: string;
+  capabilities: {
+    vault: () => Vault;
+  };
+};
+/**
+ * One-line hint printed by `holocron auth set infisical` when no
+ * token is supplied or the supplied token is rejected.
+ *
+ * IMPORTANT — the token must be usable as a `Authorization: Bearer`
+ * directly. Two token types work: **Personal API Token** (inherits
+ * user perms) or a **Token Auth** token on a machine identity (a
+ * single long-lived string). Universal Auth's Client Secret is NOT
+ * a bearer — it needs a `/v1/auth/universal-auth/login` exchange
+ * step this plugin doesn't yet do (Phase 2 follow-up).
+ */
+declare const AUTH_HINT: string;
+//#endregion
+export { AUTH_HINT, AuthError, InfisicalPluginOptions, InfisicalRestClient, InfisicalVault, PluginContext, ResolveTokenInput, type VerifyTokenFailure, type VerifyTokenResult, type VerifyTokenSuccess, createContext, createPlugin, resolveToken, vault, verifyToken };

package/dist/index.mjs

@@ -0,0 +1,366 @@
+import { ProviderApiError, getToken } from "@theholocron/cli";
+//#region src/auth.ts
+/**
+* Token resolution for the Infisical plugin.
+*
+* Resolution order (matches the standard 4-step precedence set by
+* `.notes/tech-auth-bootstrap.spec.md`):
+*   1. explicit `cliToken` argument (from `--token` flag)
+*   2. HOLOCRON_INFISICAL_TOKEN env var (preferred — explicit intent)
+*   3. INFISICAL_TOKEN env var (vendor-native)
+*   4. keyring (com.theholocron.cli / "infisical")
+*   5. AuthError naming all four options + the bootstrap hint
+*/
+var AuthError = class extends Error {
+	name = "AuthError";
+};
+function resolveToken(input = {}) {
+	const env = input.env ?? process.env;
+	const keyring = input.keyring ?? getToken;
+	const token = input.cliToken || env["HOLOCRON_INFISICAL_TOKEN"] || env["INFISICAL_TOKEN"] || keyring("infisical");
+	if (!token) throw new AuthError("no Infisical token found. Pass --token <TOKEN>, set HOLOCRON_INFISICAL_TOKEN / INFISICAL_TOKEN, or run: holocron auth set infisical <TOKEN>");
+	return token;
+}
+//#endregion
+//#region src/capabilities/vault.ts
+/**
+* `vault` capability for Infisical.
+*
+* Reference format: `infisical://<workspaceId>/<environment>/<name>`
+* — three parts, mirrors Doppler's `doppler://<project>/<config>/<name>`.
+* The plugin options carry a default `workspace` (workspace id) +
+* `environment` (slug, typically `dev`/`stg`/`prd`) so `list()` /
+* `environments()` / `readEnvironment()` don't need a three-part ref.
+*
+* Infisical's data model:
+*   - Workspace (aka project) — top-level container
+*   - Environments — dev / stg / prd, scoped to a workspace
+*   - Secrets — scoped to a workspace + environment, with a path
+*     (defaults to root `/` in this plugin; a `secretPath` option
+*     would extend it but Phase 1 keeps it flat)
+*
+* Write semantics: Infisical's REST API separates CREATE (`POST`) and
+* UPDATE (`PATCH`). We attempt POST first; on the vendor's "already
+* exists" response we PATCH to upsert. The isConflict helper follows
+* the same pattern as the Doppler plugin.
+*
+* Bootstrap semantics: `ensureProject` / `ensureEnvironment` treat
+* "already exists" as success. Both use the standard Infisical
+* workspace / environment create endpoints.
+*/
+var InfisicalVault = class {
+	rest;
+	key = "vault";
+	providerName = "infisical";
+	workspace;
+	environment;
+	/**
+	* Cache of resolved workspace name/slug → id. `ensureEnvironment`
+	* is called once per environment during `holocron setup` (dev / stg
+	* / prd), so a single \`GET /v1/workspace\` lookup covers all three
+	* calls in the same run.
+	*/
+	workspaceIdCache = /* @__PURE__ */ new Map();
+	constructor(rest, opts) {
+		this.rest = rest;
+		if (!opts.workspace) throw new Error("InfisicalVault requires `workspace` in options");
+		if (!opts.environment) throw new Error("InfisicalVault requires `environment` in options");
+		this.workspace = opts.workspace;
+		this.environment = opts.environment;
+	}
+	async read(reference) {
+		const parsed = parseReference(reference);
+		return (await this.rest.request(`/v3/secrets/raw/${encodeURIComponent(parsed.name)}`, { query: {
+			workspaceId: parsed.workspace,
+			environment: parsed.environment,
+			secretPath: "/"
+		} })).secret?.secretValue ?? "";
+	}
+	async write(reference, value) {
+		const parsed = parseReference(reference);
+		const scope = {
+			workspaceId: parsed.workspace,
+			environment: parsed.environment,
+			secretPath: "/",
+			secretValue: value
+		};
+		try {
+			await this.rest.request(`/v3/secrets/raw/${encodeURIComponent(parsed.name)}`, {
+				method: "POST",
+				body: {
+					...scope,
+					type: "shared"
+				}
+			});
+			return;
+		} catch (err) {
+			if (!isConflict(err)) throw err;
+			await this.rest.request(`/v3/secrets/raw/${encodeURIComponent(parsed.name)}`, {
+				method: "PATCH",
+				body: scope
+			});
+		}
+	}
+	async list() {
+		return ((await this.rest.request("/v3/secrets/raw", { query: {
+			workspaceId: this.workspace,
+			environment: this.environment,
+			secretPath: "/"
+		} })).secrets ?? []).map((s) => s.secretKey ?? "").filter(Boolean);
+	}
+	async environments() {
+		return ((await this.rest.request(`/v1/workspace/${encodeURIComponent(this.workspace)}`)).workspace?.environments ?? []).map((e) => e.slug ?? e.name ?? "").filter(Boolean);
+	}
+	async readEnvironment(environmentId) {
+		const res = await this.rest.request("/v3/secrets/raw", { query: {
+			workspaceId: this.workspace,
+			environment: environmentId,
+			secretPath: "/"
+		} });
+		const out = {};
+		for (const s of res.secrets ?? []) if (s.secretKey && typeof s.secretValue === "string") out[s.secretKey] = s.secretValue;
+		return out;
+	}
+	async ensureProject(name) {
+		try {
+			await this.rest.request("/v2/workspace", {
+				method: "POST",
+				body: {
+					projectName: name,
+					slug: name
+				}
+			});
+			return { alreadyExists: false };
+		} catch (err) {
+			if (isConflict(err)) return { alreadyExists: true };
+			throw err;
+		}
+	}
+	async ensureEnvironment(project, name) {
+		const workspaceId = await this.resolveWorkspaceId(project);
+		try {
+			await this.rest.request(`/v1/workspace/${encodeURIComponent(workspaceId)}/environments`, {
+				method: "POST",
+				body: {
+					environmentName: name,
+					environmentSlug: name
+				}
+			});
+			return { alreadyExists: false };
+		} catch (err) {
+			if (isConflict(err)) return { alreadyExists: true };
+			throw err;
+		}
+	}
+	/**
+	* Resolve a workspace name / slug to its Infisical workspace id.
+	*
+	* `runSetup` calls `ensureEnvironment(config.project.name, envName)`
+	* — for Doppler that's directly the API's input, but Infisical's
+	* environments endpoint takes the workspace **id** (UUID/nanoid),
+	* not the name. This helper does the translation via
+	* `GET /v1/workspace` (which the token needs org-level list scope
+	* to call).
+	*
+	* Graceful degrade: for workspace-scoped tokens that 403 on the
+	* org-level list, we fall back to treating the input as an id
+	* directly. If the operator's `holocron.config.json` names a real
+	* id, the subsequent POST works. If they named a slug, the POST
+	* 404s and the operator gets a clear "workspace not found" error
+	* from the API — better than swallowing the 403 silently.
+	*
+	* Results are cached per-instance so the 3 back-to-back
+	* `ensureEnvironment` calls in `runSetup` share one lookup.
+	*/
+	async resolveWorkspaceId(nameOrId) {
+		const cached = this.workspaceIdCache.get(nameOrId);
+		if (cached) return cached;
+		try {
+			const match = ((await this.rest.request("/v1/workspace"))?.workspaces ?? []).find((w) => w.name === nameOrId || w.slug === nameOrId);
+			const resolvedId = match?._id ?? match?.id;
+			if (resolvedId) {
+				this.workspaceIdCache.set(nameOrId, resolvedId);
+				return resolvedId;
+			}
+		} catch (err) {
+			if (!(err instanceof ProviderApiError) || err.status !== 403) throw err;
+		}
+		return nameOrId;
+	}
+};
+/**
+* Parse `infisical://<workspaceId>/<environment>/<name>` into its
+* parts. Throws when the shape doesn't match.
+*/
+function parseReference(reference) {
+	if (!reference.startsWith("infisical://")) throw new ProviderApiError(`Infisical references must start with "infisical://": got "${reference}"`, 400, void 0);
+	const parts = reference.slice(12).split("/");
+	if (parts.length < 3) throw new ProviderApiError(`Infisical reference "${reference}" missing parts; expected infisical://<workspaceId>/<environment>/<name>`, 400, void 0);
+	const [workspace, environment, ...nameParts] = parts;
+	return {
+		workspace,
+		environment,
+		name: nameParts.join("/")
+	};
+}
+/**
+* Infisical returns duplicate-create errors as 400 or 409 depending
+* on the endpoint, with a body message that includes "already exists"
+* (paraphrased). The REST client wraps both as ProviderApiError. We
+* accept 409 outright and treat 400/422 with an "already exists" body
+* as idempotent conflict — same pattern as the Doppler plugin.
+*/
+function isConflict(err) {
+	if (!(err instanceof ProviderApiError)) return false;
+	if (err.status === 409) return true;
+	if ((err.status === 400 || err.status === 422) && hasAlreadyExistsBody(err.details)) return true;
+	return false;
+}
+function hasAlreadyExistsBody(details) {
+	if (typeof details !== "string") return false;
+	return /already exists|duplicate/i.test(details);
+}
+//#endregion
+//#region src/rest.ts
+/**
+* Thin REST wrapper around https://app.infisical.com/api.
+*
+* Bearer auth, JSON-only bodies, transport-failure wrapping with
+* `status: 0` so orchestrator soft-skip paths see a clear message
+* instead of a generic `TypeError: fetch failed`.
+*/
+var InfisicalRestClient = class {
+	token;
+	fetchImpl;
+	baseUrl;
+	constructor(opts) {
+		this.token = opts.token;
+		this.fetchImpl = opts.fetch ?? globalThis.fetch;
+		let url = opts.baseUrl ?? "https://app.infisical.com/api";
+		while (url.endsWith("/")) url = url.slice(0, -1);
+		this.baseUrl = url;
+	}
+	async request(path, opts = {}) {
+		const url = new URL(`${this.baseUrl}${path.startsWith("/") ? path : "/" + path}`);
+		for (const [k, v] of Object.entries(opts.query ?? {})) url.searchParams.set(k, v);
+		const fullUrl = url.toString();
+		const headers = {
+			authorization: `Bearer ${this.token}`,
+			accept: "application/json"
+		};
+		const init = {
+			method: opts.method ?? "GET",
+			headers
+		};
+		if (opts.body !== void 0) {
+			headers["content-type"] = "application/json";
+			init.body = JSON.stringify(opts.body);
+		}
+		let res;
+		try {
+			res = await this.fetchImpl(fullUrl, init);
+		} catch (err) {
+			const detail = err instanceof Error ? `${err.name}: ${err.message}` : String(err);
+			throw new ProviderApiError(`Infisical ${init.method} ${path} failed: ${detail}`, 0, void 0);
+		}
+		if (!res.ok) {
+			const body = await res.text().catch(() => "");
+			throw new ProviderApiError(`Infisical ${init.method} ${path} → ${res.status}`, res.status, body);
+		}
+		if (opts.expectNoContent || res.status === 204) return void 0;
+		const text = await res.text();
+		if (!text) return void 0;
+		return JSON.parse(text);
+	}
+};
+//#endregion
+//#region src/verify-token.ts
+/**
+* `verifyToken` — plugin-level export used by `holocron auth set` +
+* `holocron auth check`. Hits `GET /v1/workspace` and interprets the
+* response permissively:
+*
+*   - 200 → token is valid AND has workspace-list scope; report the
+*     workspace count + first workspace name.
+*   - 403 → token is valid (authenticated) but doesn't have scope
+*     to list workspaces at the org level. This is normal for
+*     Universal Auth machine-identity tokens that are scoped to a
+*     specific workspace rather than org-wide. Return ok with a
+*     "scope-limited" subject — the operator's `holocron.config.json`
+*     will name the specific workspace + environment the token
+*     actually has access to.
+*   - 401 or other → token is invalid.
+*
+* The distinction matters: verifyToken answers "is this a real
+* Infisical token?", not "does it have every possible permission?"
+* — per-capability permission failures surface at the actual read /
+* write / list call sites.
+*
+* Kept as a standalone function (not a capability method) so the auth
+* command can call it without initializing the full plugin — plugin
+* construction requires an already-resolved token, which is exactly
+* what we don't have yet at bootstrap time.
+*/
+async function verifyToken(token, opts = {}) {
+	const restOpts = { token };
+	if (opts.baseUrl !== void 0) restOpts.baseUrl = opts.baseUrl;
+	if (opts.fetch !== void 0) restOpts.fetch = opts.fetch;
+	const rest = new InfisicalRestClient(restOpts);
+	try {
+		const res = await rest.request("/v1/workspace");
+		const count = res?.workspaces?.length ?? 0;
+		const first = res?.workspaces?.[0];
+		const label = first?.name ?? first?.slug ?? "no accessible workspaces";
+		return {
+			ok: true,
+			subject: `${count} workspace${count === 1 ? "" : "s"} · first: ${label}`
+		};
+	} catch (err) {
+		if (err instanceof ProviderApiError && err.status === 403) return {
+			ok: true,
+			subject: "scope-limited (token valid, can't list workspaces at org level)"
+		};
+		return {
+			ok: false,
+			message: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
+function createContext(options) {
+	const restOpts = { token: resolveToken(options) };
+	if (options.baseUrl !== void 0) restOpts.baseUrl = options.baseUrl;
+	if (options.fetch !== void 0) restOpts.fetch = options.fetch;
+	return {
+		options,
+		rest: new InfisicalRestClient(restOpts)
+	};
+}
+function vault(ctx) {
+	return new InfisicalVault(ctx.rest, {
+		workspace: ctx.options.workspace,
+		environment: ctx.options.environment
+	});
+}
+function createPlugin(options) {
+	const ctx = createContext(options);
+	return {
+		name: "@theholocron/holocron-plugin-infisical",
+		capabilities: { vault: () => vault(ctx) }
+	};
+}
+/**
+* One-line hint printed by `holocron auth set infisical` when no
+* token is supplied or the supplied token is rejected.
+*
+* IMPORTANT — the token must be usable as a `Authorization: Bearer`
+* directly. Two token types work: **Personal API Token** (inherits
+* user perms) or a **Token Auth** token on a machine identity (a
+* single long-lived string). Universal Auth's Client Secret is NOT
+* a bearer — it needs a `/v1/auth/universal-auth/login` exchange
+* step this plugin doesn't yet do (Phase 2 follow-up).
+*/
+const AUTH_HINT = "generate a Token Auth token on your machine identity (organization → access control → identities → your identity → add auth method → Token Auth → create token) OR a Personal API Token, then: holocron auth set infisical <TOKEN>. NOT Universal Auth's Client Secret — that needs a login exchange this plugin doesn't do yet.";
+//#endregion
+export { AUTH_HINT, AuthError, InfisicalRestClient, InfisicalVault, createContext, createPlugin, resolveToken, vault, verifyToken };

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@theholocron/holocron-plugin-infisical",
+  "version": "2.0.0-alpha.5",
+  "description": "Holocron plugin for Infisical. Implements the vault capability against Infisical's REST API, plus exports verifyToken + AUTH_HINT for `holocron auth`.",
+  "homepage": "https://github.com/theholocron/holocron/tree/main/packages/holocron-plugin-infisical#readme",
+  "bugs": "https://github.com/theholocron/holocron/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theholocron/holocron.git",
+    "directory": "packages/holocron-plugin-infisical"
+  },
+  "license": "MIT",
+  "author": "Newton Koumantzelis",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "peerDependencies": {
+    "@theholocron/cli": "2.0.0-alpha.5"
+  },
+  "devDependencies": {
+    "@theholocron/tsconfig": "^4.1.0",
+    "@tsconfig/node-lts": "^24.0.0",
+    "@vitest/coverage-v8": "^3.2.6",
+    "eslint": "^9.36.0",
+    "globals": "^16.5.0",
+    "tsdown": "^0.22.3",
+    "tsx": "^4.22.4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.6",
+    "@theholocron/cli": "2.0.0-alpha.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "validate": "tsx scripts/validate.mjs"
+  },
+  "types": "./dist/index.d.mts"
+}