@vaultic-dev/gateway

Outbound-only relay process for Vaultic provider-assisted rotation. Run it inside a private network (a locked-down VPC, an on-prem network behind NAT) so rotation can reach a database or API the Vaultic server itself has no route to. It pairs with a workspace, then polls the server for rotation commands scoped to it and runs them locally, using the same rotation-executor logic the server runs in-process for a non-Gateway-routed rotation.

This repo holds the Gateway only. The server, web app, and the rest of Vaultic live in the main vaultic-dev/open-vaultic repo.

Install & run

VAULTIC_SERVER_URL=https://your-vaultic-server \
npx @vaultic-dev/gateway

Requires Node.js >= 20. On first run it has no credential yet, so it prints a pairing code:

This Gateway is not yet paired with a Vaultic workspace.
Enter this code in the Vaultic web app (Settings -> Gateways -> Register new Gateway):

    LTHS-M6WE

Waiting for approval (expires in 10 min)...

Enter that code (and a name for the Gateway) in Settings → Gateways in the Vaultic web app; the process picks up its credential within a few seconds of approval and starts polling for work. See the Gateway docs for the full flow — pairing, scoping to a project/environment, and how routing works.

Config

| Env var | Required | Purpose | |---|---|---| | VAULTIC_SERVER_URL | Yes | Base URL of the Vaultic server to pair with and poll | | VAULTIC_GATEWAY_TOKEN | No | Skip pairing and use this credential directly (e.g. injected by your orchestrator) | | VAULTIC_GATEWAY_TOKEN_FILE | No | Where to read/persist the paired credential — lets a restart skip re-pairing without needing VAULTIC_GATEWAY_TOKEN set explicitly | | ROTATION_ALLOWED_HOSTS | No | SSRF allowlist for outbound rotation targets — set on the Gateway's own process, since it's the Gateway that opens the connection | | GATEWAY_POLL_INTERVAL_MS | No | How often to poll for pending commands (default 3000) |

What it needs network access to

Outbound only, to exactly one place: VAULTIC_SERVER_URL, plus whatever rotation targets it's scoped to reach (a database host, a cloud API endpoint). It never listens on any port, so it works behind an egress-only firewall/NAT with zero inbound rules to configure. It holds no KMS key material and never decrypts anything itself — the server decrypts a rotation command's payload before handing it to the Gateway over HTTPS, so the plaintext crosses the wire exactly once, the same way it would for an in-process rotation's API response.

Development

npm install
npm run dev      # tsx watch src/cli.ts
npm run typecheck
npm test
npm run build     # tsup -> dist/

src/rotation-executors/ is a vendored copy of the main monorepo's packages/rotation-executors — deliberately Fastify/Prisma-free rotation provider logic shared between the server (in-process) and this Gateway (relayed). It's bundled into dist/ at build time rather than pulled in as an npm dependency, so this package builds and publishes standalone. If you're fixing a provider bug here, port the fix back to the canonical copy in vaultic-dev/open-vaultic's packages/rotation-executors.

License

Apache-2.0 — see LICENSE.