@hubble-ventures/infisicml 1.2.1

package/CHANGELOG.md

@@ -0,0 +1,103 @@
+# Changelog
+
+All notable changes to `infisicml` are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres
+to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.1] - 2026-07-17
+
+### Changed (BREAKING)
+
+- **Renamed the package, CLI, repo, and config from `infiscml` to `infisicml`**
+  (a typo fix — the name is derived from *Infisical*). This is a hard break with
+  **no compatibility shims** — consumers must migrate all references when they
+  adopt the new package:
+  - **npm package**: install `@hubble-ventures/infisicml`; the old
+    `@hubble-ventures/infiscml` package is deprecated and receives no updates.
+  - **CLI binary**: `infisicml` (the old `infiscml` binary is gone — update any
+    scripts, `package.json` commands, and `node_modules/.bin` references).
+  - **Config file**: only `infisicml.config.{json,mjs,js}` is discovered —
+    rename `infiscml.config.*` to `infisicml.config.*`.
+  - **Composite action input**: `infisicml-version` (the old `infiscml-version`
+    input no longer exists).
+  - **Exported type**: `InfisicmlConfig` (was `InfiscmlConfig`).
+  - **Repository**: [`hubble-ventures/infisicml`](https://github.com/hubble-ventures/infisicml)
+    (GitHub redirects the old URL).
+
+## [1.2.0] - 2026-07-16
+
+### Added
+
+- **Least-privilege fetch (`fetch: "keys"`).** A new per-manifest `fetch` field
+  (default `"folder"`) controls how secrets are read. In `"keys"` mode infisicml
+  emits **only** the keys `include` resolves to. In **CI** this is enforced at
+  the wire: each key is fetched with the single-secret REST endpoint
+  (`GET /api/v3/secrets/raw/{name}`), so the vault never transmits the other
+  keys in a folder — contrast folder mode, where `include` is a post-fetch
+  filter and excluded values still travel over the wire. **Locally** the
+  `infisical` CLI has no single-secret server read, so infisicml fetches each
+  folder once and selects the keys (narrowing what's written, not what's
+  transmitted). `include` names the final (post-alias) keys, so key mode
+  **reverse-maps** each alias target to its canonical vault source before
+  fetching, and import-surfaced keys still resolve. Everything after the fetch
+  (aliases, `include` filtering,
+  unknown-key enforcement, `optionalKeys`) is unchanged, so the emitted output
+  matches folder mode. `fetch: "keys"` **requires** an `include` allowlist
+  (enforced by `validate` and the pull / CI step). A per-profile `fetch`
+  replaces the root one (same replace-not-merge as `paths` / `include`). Honored
+  by `pull` and `export-gha`; surfaced by `list`, `paths`, and `validate`.
+  Published in the exported JSON Schema. Omitting `fetch` is byte-for-byte
+  backward compatible.
+
+## [1.1.0] - 2026-07-16
+
+### Added
+
+- **Key-level `include` allowlist.** `secrets.json` can now emit only a chosen
+  subset of the keys a folder yields (default-deny key selection), so a client
+  package can pull a shared vendor folder but keep server secrets out of client
+  builds and `GITHUB_ENV`. Add `include` at the manifest root and/or per profile
+  (a profile's `include` replaces the root one). Applied **after** `aliases`, to
+  the final set of names. An `include` key that no folder produced fails the pull
+  / CI step unless it's listed in `environments.<slug>.optionalKeys` (downgraded
+  to a `::notice::`). Honored by `pull`, `export-gha`, `list`, `paths`, and
+  `validate`. Omitting `include` is fully backward compatible — every key is
+  emitted, as before. Published in the exported JSON Schema.
+
+## [1.0.0] - 2026-07-16
+
+First public release. The `secrets.json` manifest contract and the
+`infisicml.config` surface are now considered stable under semver — breaking
+changes to either ship only in a new major.
+
+### Added
+
+- **Published to npm as a public scoped package** (`npm i -D @hubble-ventures/infisicml`,
+  `npx --yes @hubble-ventures/infisicml@latest`). Released via npm **trusted publishing**
+  (OIDC) with build provenance — no long-lived tokens.
+- **Stable action ref.** `hubble-ventures/infisicml/action@v1` is a floating major
+  tag that tracks the latest `v1.x`; consumers may also pin a release SHA.
+- **CLI**: `pull`, `export-gha`, `list`, `validate`, `paths`, `run`.
+- **Two auth lanes, one per environment.** Local dev uses the Infisical CLI user
+  session (`infisical login`); CI uses **GitHub OIDC → Infisical machine
+  identity** over the REST API, with no Infisical CLI in the runner.
+- **Multi-target aliases.** One canonical vault key can be copied to several
+  prefixed names in a single output (e.g. `GOOGLE_MAPS_API_KEY` →
+  `EXPO_PUBLIC_GOOGLE_MAPS_API_KEY` **and** `VITE_GOOGLE_MAPS_API_KEY`). Real
+  secrets of a target name always win; the operation is idempotent.
+- **Per-package output filename.** `output` sets the written filename (e.g.
+  `.env.local`, `.env`) next to each manifest.
+- **Profiles** for deploy-only credentials — profile paths replace base paths, so
+  release-time creds (e.g. `fly`) never leak into runtime output.
+- **`advertiseKeys` hooks** publish runtime key *names* (never values) to
+  `GITHUB_ENV` for deploy forwarding.
+- **CI skip/stub** (`ci.skipWhenEnv`, `ci.stubInCi`) and **optional keys**
+  (`environments.<slug>.optionalKeys`) that downgrade a missing key to a
+  `::notice::` instead of failing CI.
+- **Published JSON Schema** for `secrets.json`, served from
+  `https://cdn.jsdelivr.net/npm/@hubble-ventures/infisicml@1/schema/secrets.schema.json`.
+
+[1.2.1]: https://github.com/hubble-ventures/infisicml/releases/tag/v1.2.1
+[1.2.0]: https://github.com/hubble-ventures/infisicml/releases/tag/v1.2.0
+[1.1.0]: https://github.com/hubble-ventures/infisicml/releases/tag/v1.1.0
+[1.0.0]: https://github.com/hubble-ventures/infisicml/releases/tag/v1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hubble Ventures
+
+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,316 @@
+# infisicml
+
+**Infisical Secret Orchestration** — federated, per-package secret manifests for monorepos, unified across local development and CI.
+
+[Infisical](https://infisical.com) gives you a vault and the primitives to read from it (a CLI, a REST API, machine-identity auth, a GitHub Action). All of those operate on **one folder / one environment / one process at a time**. Infisicml is the layer above that: it lets each package in a monorepo declare which vault folders it needs in a committed `secrets.json`, then materializes those secrets **the same way** whether you're a developer running a local pull or a CI job exporting into `GITHUB_ENV`.
+
+> Infisicml orchestrates Infisical. It stores no secrets and never sees your vault contents at rest — the vault, auth, and secret values stay in Infisical.
+
+## Why
+
+| Problem | Native Infisical | Infisicml |
+|---|---|---|
+| N packages each need a different slice of the vault | Hand-write export commands per app×folder | One committed `secrets.json` per package, auto-discovered |
+| Dev uses the CLI, CI uses the API | Two integrations kept in sync by hand | One `SecretsProvider` abstraction; identical downstream logic |
+| Vault names a secret once, but Vite wants `VITE_*` and Next wants `NEXT_PUBLIC_*` | Each workflow re-derives the prefixed copy | Declare `aliases` once; applied in dev **and** CI |
+| Skip the pull in CI when vars are already injected | Bash guards in every workflow | `ci.skipWhenEnv` / `ci.stubInCi` policy |
+| A deploy needs exactly the runtime keys, not the deploy creds | Hand-maintained allowlist | `profiles` + `advertiseKeys` hook — `secrets.json` is the source of truth |
+| A client must read a shared vendor folder without ever receiving its server secrets | Split the vault or accept over-fetch | `fetch: "keys"` requests only the named keys — the vault never transmits the rest |
+
+## Install
+
+```bash
+npm i -D @hubble-ventures/infisicml    # or pnpm add -D @hubble-ventures/infisicml
+```
+
+Requires the [`infisical` CLI](https://infisical.com/docs/cli/overview) for local pulls (`infisical login` once). CI needs no CLI — it uses the REST API.
+
+## Quick start
+
+1. Add an `infisicml.config.ts` (or `.json`) at your monorepo root — this file marks the repo root:
+
+   ```ts
+   import { defineConfig } from "@hubble-ventures/infisicml";
+
+   export default defineConfig({
+     projectIdEnvFile: ".env.infisical", // provides INFISICAL_PROJECT_ID
+     discovery: { roots: ["apps", "services"], packages: [{ id: "postgres", dir: "infra/postgres" }] },
+     auth: { oidcAudience: "https://github.com/your-org" },
+     hooks: { advertiseKeys: [{ envVar: "INFISCML_FLY_KEYS", scope: "runtime" }] },
+   });
+   ```
+
+2. Add a `secrets.json` next to each package:
+
+   ```jsonc
+   {
+     "$schema": "https://cdn.jsdelivr.net/npm/@hubble-ventures/infisicml@1/schema/secrets.schema.json",
+     "paths": ["clerk", "posthog"],
+     "output": ".env", // written next to this manifest; defaults to .env.secrets
+     "aliases": {
+       // One canonical vault key → several prefixed copies in a single output.
+       "GOOGLE_MAPS_API_KEY": [
+         "EXPO_PUBLIC_GOOGLE_MAPS_API_KEY",
+         "VITE_GOOGLE_MAPS_API_KEY"
+       ],
+       // A single target is also fine (string form).
+       "CLERK_PUBLISHABLE_KEY": "VITE_CLERK_PUBLISHABLE_KEY"
+     }
+   }
+   ```
+
+3. Pull secrets into gitignored `.env.secrets` files:
+
+   ```bash
+   npx infisicml pull                 # every package
+   npx infisicml pull web api --force # specific ids, bypass the exists-check
+   npx infisicml validate             # check every secrets.json against the schema
+   ```
+
+See [`examples/`](./examples) for a fuller config and manifest.
+
+## CLI
+
+| Command | Purpose |
+|---|---|
+| `pull [ids...]` | Write `.env.secrets` locally (uses `infisical export`) |
+| `export-gha <id>` | Mask + append secrets to `GITHUB_ENV` (REST API + GitHub OIDC) |
+| `list` | Show every manifest and its Infisical paths |
+| `validate` | Validate every `secrets.json` against the schema |
+| `paths <id>` | Print resolved paths (`--comma` for scripting) |
+| `run <id> -- <cmd...>` | Thin `infisical run` wrapper (prefer `pull` + `.env.secrets`) |
+
+Common flags: `--env`, `--profile`, `--force`, `--here` (pull the cwd package), `--turbo` (always write, for Turbo caching).
+
+## Authentication
+
+Infisicml supports exactly one auth lane per environment — no secrets to rotate, no fallbacks to reason about:
+
+| Where | How | Requires |
+|---|---|---|
+| **Local dev** | Infisical CLI **user login** (`infisical login`) | `infisical` CLI, logged in as you |
+| **CI (GitHub Actions)** | **GitHub OIDC** → Infisical machine identity | `permissions: id-token: write` + an Infisical machine identity with a GitHub OIDC auth method |
+
+There is no client-id/secret (universal-auth) path and no long-lived token anywhere.
+
+## GitHub Actions
+
+Use the bundled composite action (runs `infisicml export-gha` via `npx`). The calling job **must** grant `id-token: write` so the runner can mint an OIDC token:
+
+```yaml
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # REQUIRED — OIDC is the only CI auth lane
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: hubble-ventures/infisicml/action@v1
+        with:
+          package-id: api
+          environment: production
+          project-slug: ${{ vars.INFISICAL_PROJECT_SLUG }}
+          identity-id: ${{ vars.INFISICAL_IDENTITY_ID }}
+          oidc-audience: ${{ vars.INFISICAL_OIDC_AUDIENCE }} # optional
+```
+
+Secrets are masked and appended to `GITHUB_ENV` for subsequent steps. Any configured `advertiseKeys` hook writes a plain, comma-separated list of runtime key **names** so a deploy step can forward exactly those. A full CI + deploy example is in [`examples/github-actions.yml`](./examples/github-actions.yml).
+
+**Pinning the action.** `@v1` is a floating major tag that always points at the latest `v1.x` release — it moves forward on each release but never across a breaking major. For a fully immutable pin, use a release SHA instead: `uses: hubble-ventures/infisicml/action@<sha>`. The action shells out to `npx --yes @hubble-ventures/infisicml@latest`; pin the package too by passing `infisicml-version:` (e.g. the same `1.x` version) if you want the CLI locked as well.
+
+## Local development
+
+Log in once as yourself; infisicml shells out to `infisical export` under your session:
+
+```bash
+infisical login          # authenticate as you
+npx infisicml pull          # write .env.secrets next to every secrets.json
+```
+
+Load `.env.secrets` however your dev runtime already loads env files. See [`examples/local-dev.md`](./examples/local-dev.md) for package-script and task-runner wiring.
+
+## Concepts
+
+- **Manifest (`secrets.json`)** — per package: `paths` (vault folders), optional `profiles`, `aliases`, `include`, `fetch`, `ci`, `environments`, `output`.
+- **Output file** — `output` sets the written filename (default `.env.secrets`), placed **next to the manifest**. Because each package owns its own `secrets.json`, this gives a distinct file per package: a root manifest with `"output": ".env.local"` writes the repo-root `.env.local`; a manifest in `apps/backend` with `"output": ".env"` writes `apps/backend/.env`. `output` is a filename only (no path separators) — to target a different directory, place the manifest in that directory.
+- **Profiles** — named path sets that *replace* base `paths` when `--profile` is set. Base paths are runtime secrets; profile-only paths (e.g. `fly`) are deploy/release credentials.
+- **Aliases** — copy a canonical secret to extra tool-specific names. Each source maps to **one target (string) or many (array)**, so a single vault key can fan out to every framework prefix (`EXPO_PUBLIC_*`, `VITE_*`, `NEXT_PUBLIC_*`) in one output. Real secrets of a target name always win; the operation is idempotent and never overwrites.
+- **Include (key allowlist)** — `include` emits **only** the listed keys from whatever the folders yielded (default-deny key selection). Omit it and every key is emitted (unchanged). See [Key selection](#key-selection-include) below.
+- **Fetch mode** — `fetch: "keys"` requests only the keys `include` resolves to, so the vault never transmits the rest (wire-level least privilege). Default `"folder"` reads whole folders and filters locally. See [Wire-level least privilege](#wire-level-least-privilege-fetch-keys) below.
+- **CI skip/stub** — `ci.skipWhenEnv` skips the pull when all listed vars are already set in CI; `ci.stubInCi` always stubs in CI. Both write a `.env.secrets` from `process.env` instead of calling Infisical.
+- **Optional keys** — `environments.<slug>.optionalKeys` downgrade a missing key to a `::notice::` in `export-gha` instead of a failure.
+- **Advertise-keys hooks** — publish runtime key *names* (never values) to `GITHUB_ENV` for deploy forwarding.
+
+### Key selection (`include`)
+
+Vaults are often organized by **vendor, not by access scope** — a single `/stripe` folder
+holds both a server secret and a client-public key:
+
+```
+/stripe → STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY
+```
+
+A web/mobile client needs **only** the publishable key. With folder-only selection it would
+be forced to pull the whole folder — writing `STRIPE_SECRET_KEY` into a Vite/Expo client
+build's env (and, via the CI action, into `GITHUB_ENV` for jobs that shouldn't see it).
+
+`include` is a **default-deny allowlist**: only the listed env var names are emitted.
+
+```jsonc
+// apps/web/secrets.json — a client package
+{
+  "paths": ["stripe", "google", "vercel"],
+  "aliases": {
+    "STRIPE_PUBLISHABLE_KEY": ["EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY"],
+    "GOOGLE_MAPS_API_KEY": ["EXPO_PUBLIC_GOOGLE_MAPS_API_KEY"]
+  },
+  "include": [
+    "EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY",
+    "EXPO_PUBLIC_GOOGLE_MAPS_API_KEY",
+    "EXPO_PUBLIC_VERCEL_AUTOMATION_BYPASS_SECRET"
+  ]
+}
+```
+
+The written `.env.secrets` (and, in CI, `GITHUB_ENV`) contains **only** those three keys —
+server secrets in the same folders are never emitted.
+
+- **Ordering** — folders are pulled, then `aliases` are applied, then `include` filters the
+  **final** set of names. So aliasing a canonical key to a public name and listing only the
+  public name in `include` drops the canonical key (and every other folder key). An alias
+  whose source isn't in `include` still emits its target.
+- **Names, not paths** — `include` is a flat list of env var names; key names must be unique
+  across a package's folders.
+- **Unknown keys** — a name in `include` that no folder produced is an error (fail the pull /
+  CI step), **unless** it's also in `environments.<slug>.optionalKeys`, which downgrades it to
+  a `::notice::`. Enforced the same way in `pull` and `export-gha`.
+- **Profiles** — a profile may set its own `include`, which **replaces** the root `include`
+  for that profile (like `profiles.<name>.paths`). A profile without `include` inherits the
+  root one.
+- **Backward compatible** — omit `include` and behavior is unchanged (every key is emitted).
+
+### Wire-level least privilege (`fetch: "keys"`)
+
+`include` on its own is a **post-fetch filter**: infisicml pulls each whole folder, then drops
+the unwanted keys before writing the output. The excluded values still travel over the wire
+into your machine / the CI runner — they're just never written to `.env` or `GITHUB_ENV`. For
+most setups that's fine. When you need the vault to **not even transmit** the secrets you
+don't use, set `fetch: "keys"`:
+
+```jsonc
+// apps/web/secrets.json — client package, strict wire-level least privilege
+{
+  "paths": ["stripe", "google"],
+  "fetch": "keys",
+  "aliases": {
+    "STRIPE_PUBLISHABLE_KEY": ["EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY"]
+  },
+  "include": [
+    "EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY",
+    "GOOGLE_MAPS_API_KEY"
+  ]
+}
+```
+
+In `keys` mode infisicml emits **only** the keys `include` resolves to. Where the guarantee
+bites depends on the lane:
+
+- **CI (`export-gha`)** — true **wire-level** least privilege: each key is fetched with the
+  single-secret REST endpoint (`GET /api/v3/secrets/raw/{name}`), so the other keys in
+  `/stripe` and `/google` are **never sent by the vault**. This is the security-critical lane
+  (shared runners, `GITHUB_ENV`).
+- **Local (`pull`)** — the `infisical` CLI has no single-secret *server* read (`secrets get`
+  pulls the whole folder and filters client-side), so locally infisicml fetches each folder
+  once and selects the keys. It narrows what's **written to disk**, not what the vault
+  transmits — on your own machine, where folder mode already lands.
+
+- **Requires `include`** — key mode fetches exactly what `include` names, so an allowlist is
+  mandatory (root or the active profile). `validate` and the pull/CI step both enforce this.
+- **Aliases are reverse-mapped** — `include` names the *final* (post-alias) keys, so infisicml
+  fetches the canonical vault source behind each alias target. Above, listing
+  `EXPO_PUBLIC_STRIPE_PUBLISHABLE_KEY` fetches the canonical `STRIPE_PUBLISHABLE_KEY`.
+- **Imports still resolve** — a key surfaced into a `paths` folder via an Infisical import is
+  fetched in `keys` mode too (the per-key read follows imports but returns only that one
+  secret), so enabling `keys` never silently drops an import-backed key.
+- **Same emit result** — everything after the fetch (aliases, `include` filtering, unknown-key
+  enforcement, `optionalKeys`) is identical to folder mode; only what's read narrows.
+- **Cost** — in CI, one request **per key** instead of one per folder; the `paths` list becomes
+  advisory (`infisicml paths` notes this).
+- **Profiles** — a profile may set its own `fetch`, which **replaces** the root value (like
+  `paths` / `include`). A deploy profile can stay in `folder` mode while the runtime default
+  is `keys`, or vice versa.
+- **Backward compatible** — omit `fetch` (or set `"folder"`) and behavior is byte-for-byte
+  unchanged.
+
+### Non-secret defaults (`.env.sample`)
+
+Infisicml writes **only the secret slice** it pulls from Infisical — it does not merge a
+committed base file. If a package keeps non-secret defaults and structure in a
+`.env.sample`, keep both files and load them together at runtime, secrets last so they
+win:
+
+```bash
+# node — later --env-file overrides earlier ones
+node --env-file=.env.sample --env-file=.env.secrets server.js
+```
+
+```jsonc
+// package.json
+{ "scripts": { "dev": "infisicml --here pull && node --env-file=.env.sample --env-file=.env.secrets server.js" } }
+```
+
+Point `output` at whatever filename your loader expects (e.g. `.env` layered over a
+committed `.env.example`). Do **not** overwrite a committed sample with the pulled file
+— they are separate inputs, and losing the sample's defaults would break local dev.
+
+## Programmatic API
+
+```ts
+import { loadConfig, discoverManifests, pullManifest, LocalProvider } from "@hubble-ventures/infisicml";
+
+const config = await loadConfig();
+const provider = new LocalProvider({ projectId: config.projectId });
+for (const manifest of discoverManifests(config)) {
+  await pullManifest({ manifest, provider, repoRoot: config.repoRoot, envName: "development" });
+}
+```
+
+## Releasing
+
+Releases are cut by pushing a semver tag; [`.github/workflows/release.yml`](./.github/workflows/release.yml) does the rest:
+
+```bash
+npm version 1.2.3 --no-git-tag-version
+git commit -am "release: v1.2.3"
+git tag v1.2.3 && git push origin main --tags
+```
+
+The workflow builds + tests the tagged commit, publishes to npm via **trusted
+publishing** (OIDC — no `NPM_TOKEN` secret, provenance attached automatically),
+creates a GitHub Release from the matching [`CHANGELOG.md`](./CHANGELOG.md) section, and
+moves the floating `v1` tag to the release commit. The publish step is idempotent — a
+version already on npm is skipped.
+
+> **First publish (one time).** The `@hubble-ventures` npm **organization** must exist,
+> and npm trusted publishing can only be configured against an *existing* package — so
+> the very first publish is done locally, by a member of the org with publish rights, to
+> create the package:
+>
+> ```bash
+> npm publish --access public   # scoped packages default to private; --access public is required
+> ```
+>
+> (`publishConfig.access: public` in `package.json` enforces this even if the flag is
+> omitted.) Then, in the package's npm settings, add a **trusted publisher** for
+> `hubble-ventures/infisicml` → workflow `release.yml`, with **no environment** (the release
+> job sets none — the OIDC claims must match). Every subsequent tag push publishes
+> automatically with no token.
+
+## Design
+
+Everything repo-specific lives in `infisicml.config` — package discovery, the project-id source, the OIDC audience, and deploy-time key advertisement are all configuration, so nothing about one repo's layout is baked into the tool. The manifest contract (`secrets.json`) is the stable public interface, versioned via the [published JSON Schema](./schema/secrets.schema.json).
+
+## License
+
+MIT © Hubble Ventures

package/dist/aliases.d.ts

@@ -0,0 +1,20 @@
+import type { SecretsManifest } from "./manifest.js";
+export type ResolvedAlias = {
+    source: string;
+    targets: string[];
+};
+/** Normalize the manifest's alias map to a list of {source, targets[]}. */
+export declare function resolveAliases(manifest: SecretsManifest): ResolvedAlias[];
+/**
+ * Copy each aliased source secret's value to its target env var name(s).
+ *
+ * Used wherever the CLI materializes secrets (CI `export-gha`, local
+ * `.env.secrets` pull) so the conventional, tool-specific name each deployment
+ * expects is always present — see the `aliases` doc in manifest.ts.
+ *
+ * Returns a new object. An absent source is skipped, and an existing target (a
+ * real secret of that name) is never overwritten, so real values win over
+ * aliases and the operation is idempotent.
+ */
+export declare function applyAliases(merged: Record<string, string>, manifest: SecretsManifest): Record<string, string>;
+//# sourceMappingURL=aliases.d.ts.map

package/dist/aliases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.d.ts","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,MAAM,MAAM,aAAa,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAElE,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa,EAAE,CAOzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,QAAQ,EAAE,eAAe,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUxB"}

package/dist/aliases.js

@@ -0,0 +1,35 @@
+/** Normalize the manifest's alias map to a list of {source, targets[]}. */
+export function resolveAliases(manifest) {
+    const aliases = manifest.aliases;
+    if (!aliases)
+        return [];
+    return Object.entries(aliases).map(([source, value]) => ({
+        source,
+        targets: Array.isArray(value) ? value : [value],
+    }));
+}
+/**
+ * Copy each aliased source secret's value to its target env var name(s).
+ *
+ * Used wherever the CLI materializes secrets (CI `export-gha`, local
+ * `.env.secrets` pull) so the conventional, tool-specific name each deployment
+ * expects is always present — see the `aliases` doc in manifest.ts.
+ *
+ * Returns a new object. An absent source is skipped, and an existing target (a
+ * real secret of that name) is never overwritten, so real values win over
+ * aliases and the operation is idempotent.
+ */
+export function applyAliases(merged, manifest) {
+    const out = { ...merged };
+    for (const { source, targets } of resolveAliases(manifest)) {
+        const value = merged[source];
+        if (value === undefined)
+            continue;
+        for (const target of targets) {
+            if (out[target] === undefined)
+                out[target] = value;
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=aliases.js.map

package/dist/aliases.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aliases.js","sourceRoot":"","sources":["../src/aliases.ts"],"names":[],"mappings":"AAIA,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,QAAyB;IACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;IACjC,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACxB,OAAO,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;QACvD,MAAM;QACN,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;KAChD,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,YAAY,CAC1B,MAA8B,EAC9B,QAAyB;IAEzB,MAAM,GAAG,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC;IAC1B,KAAK,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,cAAc,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3D,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS;YAAE,SAAS;QAClC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,SAAS;gBAAE,GAAG,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;QACrD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/ci-skip.d.ts

@@ -0,0 +1,27 @@
+import { type SecretsManifest } from "./manifest.js";
+import type { SecretsProvider } from "./providers/types.js";
+export type { SecretsProvider };
+export declare function mergeFolderSecrets(chunks: Record<string, string>[]): Record<string, string>;
+export declare function fetchSecretsForPaths(provider: SecretsProvider, envName: string, paths: string[]): Promise<Record<string, string>>;
+/**
+ * `fetch: "keys"` counterpart to {@link fetchSecretsForPaths}: request only the
+ * given canonical keys from each folder and merge. A key absent from one folder
+ * is simply not returned by that folder; the merge (last folder wins, matching
+ * the folder path) collects it from whichever folder holds it.
+ */
+export declare function fetchSecretsForKeys(provider: SecretsProvider, envName: string, paths: string[], keys: string[]): Promise<Record<string, string>>;
+/**
+ * Fetch a manifest's secrets for the given folder set, honoring its resolved
+ * `fetch` mode: `keys` requests only the canonical keys `include` resolves to
+ * (least privilege at the wire), `folder` reads whole folders. `keys` requires
+ * an `include` allowlist — the whole point is to name exactly what to fetch.
+ *
+ * Callers pass an explicit `paths` subset (export-gha splits runtime vs
+ * deploy-only) rather than re-deriving it, so the runtime/deploy provenance the
+ * caller already computed is preserved.
+ */
+export declare function fetchManifestSecrets(provider: SecretsProvider, envName: string, paths: string[], manifest: SecretsManifest, profile?: string): Promise<Record<string, string>>;
+export declare function isCi(): boolean;
+export declare function shouldSkipInfisicalPull(manifest: SecretsManifest, force: boolean): boolean;
+export declare function keysForCiStub(manifest: SecretsManifest): string[];
+//# sourceMappingURL=ci-skip.d.ts.map

package/dist/ci-skip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ci-skip.d.ts","sourceRoot":"","sources":["../src/ci-skip.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE5D,YAAY,EAAE,eAAe,EAAE,CAAC;AAEhC,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAC/B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAMxB;AAED,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,GACd,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMjC;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,EACf,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAMjC;AAED;;;;;;;;;GASG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,eAAe,EACzB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EAAE,EACf,QAAQ,EAAE,eAAe,EACzB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAuBjC;AAED,wBAAgB,IAAI,IAAI,OAAO,CAG9B;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,eAAe,EACzB,KAAK,EAAE,OAAO,GACb,OAAO,CAgBT;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,EAAE,CAEjE"}

package/dist/ci-skip.js

@@ -0,0 +1,82 @@
+import { resolveFetchKeys } from "./include.js";
+import { resolveFetchMode, resolveInclude, } from "./manifest.js";
+export function mergeFolderSecrets(chunks) {
+    const merged = {};
+    for (const chunk of chunks) {
+        Object.assign(merged, chunk);
+    }
+    return merged;
+}
+export async function fetchSecretsForPaths(provider, envName, paths) {
+    const chunks = [];
+    for (const folder of paths) {
+        chunks.push(await provider.exportFolder(envName, folder));
+    }
+    return mergeFolderSecrets(chunks);
+}
+/**
+ * `fetch: "keys"` counterpart to {@link fetchSecretsForPaths}: request only the
+ * given canonical keys from each folder and merge. A key absent from one folder
+ * is simply not returned by that folder; the merge (last folder wins, matching
+ * the folder path) collects it from whichever folder holds it.
+ */
+export async function fetchSecretsForKeys(provider, envName, paths, keys) {
+    const chunks = [];
+    for (const folder of paths) {
+        chunks.push(await provider.exportKeys(envName, folder, keys));
+    }
+    return mergeFolderSecrets(chunks);
+}
+/**
+ * Fetch a manifest's secrets for the given folder set, honoring its resolved
+ * `fetch` mode: `keys` requests only the canonical keys `include` resolves to
+ * (least privilege at the wire), `folder` reads whole folders. `keys` requires
+ * an `include` allowlist — the whole point is to name exactly what to fetch.
+ *
+ * Callers pass an explicit `paths` subset (export-gha splits runtime vs
+ * deploy-only) rather than re-deriving it, so the runtime/deploy provenance the
+ * caller already computed is preserved.
+ */
+export async function fetchManifestSecrets(provider, envName, paths, manifest, profile) {
+    if (resolveFetchMode(manifest, profile) === "keys") {
+        const include = resolveInclude(manifest, profile);
+        if (!include) {
+            // resolveInclude already checked the profile then the root, so name the
+            // exact place(s) that need an `include` rather than a vague "root or
+            // profile" — the user should add it to whichever they're running.
+            const where = profile
+                ? `neither profile "${profile}" nor the manifest root defines one`
+                : "the manifest root does not define one";
+            throw new Error(`fetch: "keys" requires an include allowlist, but ${where}. ` +
+                "Add `include: [...]` naming exactly which keys to request from the vault.");
+        }
+        return fetchSecretsForKeys(provider, envName, paths, resolveFetchKeys(include, manifest));
+    }
+    return fetchSecretsForPaths(provider, envName, paths);
+}
+export function isCi() {
+    const ci = process.env.CI;
+    return ci === "true" || ci === "1";
+}
+export function shouldSkipInfisicalPull(manifest, force) {
+    if (force)
+        return false;
+    if (!isCi())
+        return false;
+    const ci = manifest.ci;
+    if (!ci)
+        return false;
+    if (ci.stubInCi)
+        return true;
+    const keys = ci.skipWhenEnv ?? [];
+    if (keys.length === 0)
+        return false;
+    return keys.every((key) => {
+        const value = process.env[key];
+        return value !== undefined && value !== "";
+    });
+}
+export function keysForCiStub(manifest) {
+    return manifest.ci?.skipWhenEnv ?? [];
+}
+//# sourceMappingURL=ci-skip.js.map

package/dist/ci-skip.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}