@earthlink/dotvault 0.13.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EarthLink Network
+
+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,229 @@
+# @earthlink/dotvault
+
+dotvault — sync `.env` / `.npmrc` / `.gitconfig` and any config file across
+machines and CI/CD. No AWS account required.
+
+[![npm version](https://img.shields.io/npm/v/@earthlink/dotvault)](https://www.npmjs.com/package/@earthlink/dotvault)
+[![license](https://img.shields.io/npm/l/@earthlink/dotvault)](../../LICENSE)
+
+## Install
+
+```bash
+npm i -g @earthlink/dotvault
+# or as a project devDependency
+npm i -D @earthlink/dotvault
+```
+
+Requires Node >= 20.
+
+> Upgrading from `@earthlink/env-sync`? The `env-sync` command keeps working
+> as an alias — see [Compatibility alias](#compatibility-alias-env-sync)
+> below.
+
+## Quick start
+
+```bash
+# 1. Create project-config.json (first time, if not already in repo)
+dotvault init
+
+# 2. Log in — stores tokens in OS keychain (Keychain / libsecret / Credential Manager)
+dotvault login -e you@example.com
+
+# 3. Pull all synced files to local disk
+dotvault pull
+
+# 4. (Optional) Inject secrets into a dev server without writing any file
+dotvault run -- npm run dev
+```
+
+## Common workflows
+
+| Workflow                               | Commands                                                      |
+| -------------------------------------- | ------------------------------------------------------------- |
+| First-time setup                       | `dotvault init` → `dotvault login` → `dotvault pull`          |
+| Join existing project (config in repo) | `dotvault login` → `dotvault pull`                            |
+| Local dev (no .env on disk)            | `dotvault run -- npm run dev`                                 |
+| CI/CD (service token)                  | set `DOTVAULT_TOKEN=est_…` → `dotvault pull --env production` |
+| Audit history                          | `dotvault versions DATABASE_URL`                              |
+| Roll back a secret                     | `dotvault rollback DATABASE_URL --to 4`                       |
+| Add a file to sync                     | `dotvault push .npmrc`                                        |
+| Detect committed secrets               | `dotvault scan .`                                             |
+| Share a key org-wide                   | `dotvault global keys` → `dotvault global use <KEY>`          |
+
+## All commands
+
+```
+dotvault init                     # create project-config.json
+dotvault login                    # email + password auth (Cognito)
+dotvault pull                     # write .env / .npmrc etc. to local disk
+dotvault run -- <cmd>             # inject secrets into child process (no file written)
+dotvault set KEY=value            # set one or more secrets
+dotvault delete KEY               # delete a secret
+dotvault import .env.production   # bulk-import from a .env file
+dotvault versions KEY             # show version history of a key
+dotvault rollback KEY --to N      # restore a key to version N
+dotvault list                     # list (env, file) inventory for this project
+dotvault push .npmrc              # add any file to the sync set
+dotvault files                    # list synced files
+dotvault scan .                   # detect committed secrets (offline)
+dotvault global keys              # list the org's global key-pool inventory
+dotvault global set K=v [-E env]  # set a global-pool value (omit -E for the common value)
+dotvault global delete K [-E env] # delete a global-pool value
+dotvault global use K [--as N]    # bind a global key into this project's pull
+dotvault global drop K            # unbind a global key from this project
+dotvault global status            # show this project's active global-key bindings
+dotvault project create --name X  # create a project (headless — ADR-0018)
+dotvault token list --org ID      # list service tokens
+dotvault token create --org ID …  # mint a service token (shown once)
+dotvault token revoke --org ID …  # revoke a service token
+dotvault logout                   # remove tokens from keychain
+dotvault whoami                   # report active identity (interactive user OR service token)
+```
+
+Run `dotvault <command> --help` for per-command flags and examples.
+
+## Init options
+
+```bash
+dotvault init [options]
+```
+
+| Option              | Default                      | Description                              |
+| ------------------- | ---------------------------- | ---------------------------------------- |
+| `-n, --name <name>` | `basename(cwd)`              | Project name                             |
+| `--api <url>`       | `https://api.dotvault.io/v1` | API base URL                             |
+| `-f, --force`       | —                            | Overwrite existing `project-config.json` |
+
+**Success output:**
+
+```
+Created project-config.json (project=my-app). Next: dotvault login && dotvault pull
+```
+
+## Pull options
+
+```bash
+dotvault pull --project my-app --env staging --file .env.local
+```
+
+| Option                 | Description                                                                                                                |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `-p, --project <name>` | Override project name from `project-config.json`                                                                           |
+| `-E, --env <env>`      | `development` \| `staging` \| `production`, or any custom env the project has declared (Settings → Environments, ADR-0024) |
+| `-f, --file <file>`    | Pull only this file                                                                                                        |
+
+**Success output (one line per file, then a summary; colors/progress bar
+on a TTY only):**
+
+```
+✓ Wrote 12 keys to .env.local (project=my-app, env=development, file=env.local). Markers preserved.
+✔ 1 file synced, 0 excluded, 12 keys total
+```
+
+## Project config
+
+The CLI reads `project-config.json` in the working directory root (generated by `dotvault init`, schema 2.7.0):
+
+```json
+{
+  "name": "my-app",
+  "setup": {
+    "bootstrap": {
+      "proxy": {
+        "apiUrl": "https://api.dotvault.io/v1"
+      }
+    },
+    "envSync": {
+      "enabled": true,
+      "files": [".env"],
+      "defaultEnv": "development"
+    }
+  }
+}
+```
+
+Commit this file to your repository — it contains no secrets. The `apiUrl` field is the only value that must match the hosted platform.
+
+## Authentication
+
+Token resolution order for each CLI invocation (applies to `pull`, `run`, `set`, `delete`, `import`, `versions`, `rollback`, `list`, `push`, `files`, `whoami`):
+
+1. `DOTVAULT_TOKEN` environment variable (or legacy `ENV_SYNC_TOKEN`) — `est_…` service tokens (CI/CD/Lambda)
+2. OS keychain — set by `dotvault login` (interactive user)
+
+`dotvault whoami` will tell you which mode is active without making a network call:
+
+```bash
+$ DOTVAULT_TOKEN=est_ci_secret_abcdefghij dotvault whoami
+Service token (DOTVAULT_TOKEN=est_ci_secre…) — CI / Lambda mode
+
+$ dotvault whoami
+you@example.com (token expires in 2847s)
+```
+
+### Service tokens (`dotvault token …`)
+
+Org admins can manage service tokens entirely from the CLI:
+
+```bash
+# List
+dotvault token list --org org_abc
+
+# Mint (the secret is shown ONCE — save it immediately)
+dotvault token create --org org_abc --name ci-prod --role viewer
+# Optional: --ttl <seconds>, --project <id>
+
+# Revoke
+dotvault token revoke --org org_abc --token-id est_meta_a1b2c3d4
+```
+
+Admin UI alternative: [app.dotvault.io](https://app.dotvault.io) → your org → Service Tokens.
+
+### Headless project creation (`dotvault project create`)
+
+Create a project without the admin web console — the piece that lets Claude
+Code / CI onboard a repo unattended (ADR-0018). Mint a `provisioner` token once,
+then create projects with no interactive login:
+
+```bash
+# one-time (org admin): mint a provisioner token — creates projects, cannot
+# read or write any secret, cannot mint tokens
+dotvault token create --org org_abc --name claude-provision --role provisioner
+
+# thereafter (headless): org is taken from the token, so --org is optional
+DOTVAULT_ADMIN_TOKEN=est_… dotvault project create --name myapp
+```
+
+Credential precedence for `project create`: `DOTVAULT_ADMIN_TOKEN` (or legacy `ENV_SYNC_ADMIN_TOKEN`) →
+`DOTVAULT_TOKEN` (or legacy `ENV_SYNC_TOKEN`) → keychain login. See the
+[Claude Code onboarding runbook](https://github.com/EarthLinkNetwork/dotvault/blob/main/docs/runbooks/claude-code-onboarding.md).
+
+## Compatibility alias (`env-sync`)
+
+The package still installs an `env-sync` binary alongside `dotvault` — every
+command works identically under either name. Invoking any command via
+`env-sync` prints a one-line stderr notice:
+
+```
+env-sync is now dotvault — the env-sync command keeps working as an alias.
+```
+
+Legacy `ENV_SYNC_*` environment variables (`ENV_SYNC_TOKEN`,
+`ENV_SYNC_ADMIN_TOKEN`, `ENV_SYNC_API_URL`) are still read as a fallback when
+the corresponding `DOTVAULT_*` variable is unset — there is no forced
+migration deadline.
+
+## Links
+
+- Admin console: <https://app.dotvault.io>
+- Help & FAQ: <https://app.dotvault.io/admin/help>
+- Full documentation: <https://github.com/EarthLinkNetwork/dotvault#readme>
+- Source: <https://github.com/EarthLinkNetwork/dotvault>
+
+## Access
+
+The Lambda proxy backend is operated by EarthLink Network. Without a Cognito account in the operator's user pool you cannot fetch secrets — this package is intentionally distributable on npm but operationally private to its tenant.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+
+declare const PACKAGE_VERSION: string;
+declare function buildProgram(): Command;
+declare function renameNoticeFor(argv1: string | undefined): string | null;
+declare function main(argv: readonly string[], argv1?: string | undefined): Promise<number>;
+
+export { PACKAGE_VERSION, buildProgram, main, renameNoticeFor };