@seekrit/proxy 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +56 -0
  2. package/dist/index.js +195 -0
  3. package/package.json +30 -0
package/README.md ADDED
@@ -0,0 +1,56 @@
1
+ # @seekrit/proxy
2
+
3
+ An `npx`-able launcher for [`seekrit-proxy`](https://seekrit.dev/docs/guides/agent-proxy),
4
+ seekrit's egress proxy for untrusted workloads: the workload sends
5
+ `{{seekrit:NAME}}` placeholders, the proxy swaps in the real decrypted value on
6
+ the way to an **allowlisted** upstream. The agent never holds the key.
7
+
8
+ ```bash
9
+ SEEKRIT_TOKEN=skt_… npx -y @seekrit/proxy --config seekrit-proxy.toml
10
+ ```
11
+
12
+ The proxy itself is a Rust binary. This package downloads the released build for
13
+ your platform, verifies its SHA-256 against the checksum published beside it,
14
+ and runs it with the arguments you passed. It interprets no flags of its own —
15
+ `--help` shows the proxy's help — and adds no defaults.
16
+
17
+ ## Don't have a config yet?
18
+
19
+ The [seekrit CLI](https://www.npmjs.com/package/@seekrit/cli) generates one, and
20
+ can run the proxy in one step without writing a file:
21
+
22
+ ```bash
23
+ npx -y @seekrit/cli proxy run --preset openai # nothing written
24
+ npx -y @seekrit/cli proxy init --preset openai # a reviewable seekrit-proxy.toml
25
+ npx -y @seekrit/cli proxy init --agent nova # from published policy
26
+ ```
27
+
28
+ ## Environment
29
+
30
+ | Variable | Default | Purpose |
31
+ | --- | --- | --- |
32
+ | `SEEKRIT_TOKEN` | — | Service token the proxy resolves with. **Required** — it fails closed without one. |
33
+ | `SEEKRIT_PROXY_BIN` | — | Path to a binary you already have. Skips the download entirely. |
34
+ | `SEEKRIT_PROXY_VERSION` | this package's version | Binary version to fetch. |
35
+ | `SEEKRIT_PROXY_BASE_URL` | `https://proxy.seekrit.dev` | Where artifacts are fetched from. |
36
+
37
+ Downloads are cached under `$XDG_CACHE_HOME/seekrit/proxy` (or
38
+ `~/.cache/seekrit/proxy`), keyed by version and target, so the fetch happens once
39
+ per version.
40
+
41
+ The package version tracks the binary version it fetches, so
42
+ `npx @seekrit/proxy@0.7.0` runs proxy `0.7.0`.
43
+
44
+ ## Other ways to install
45
+
46
+ - **A binary on your PATH** — `curl -fsSL https://proxy.seekrit.dev/install.sh | sh`
47
+ - **A container** — `docker run seekritdev/proxy` (multi-arch, static musl on `scratch`)
48
+ - **From source** — `cargo build --release` in `apps/proxy`
49
+
50
+ ## Security
51
+
52
+ `SEEKRIT_TOKEN` must not be readable by the workload the proxy exists to
53
+ constrain: anything that can read it can call `/v1/resolve` itself and skip the
54
+ proxy. Run the proxy as a separate OS user, or in its own container. See
55
+ [the guide's honest limits](https://seekrit.dev/docs/guides/agent-proxy) for the
56
+ full discussion.
package/dist/index.js ADDED
@@ -0,0 +1,195 @@
1
+ #!/usr/bin/env node
2
+ import { spawn } from "node:child_process";
3
+ import { createHash } from "node:crypto";
4
+ import { chmodSync, existsSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
5
+ import { arch, homedir, platform } from "node:os";
6
+ import { dirname, join } from "node:path";
7
+ //#region ../cli/src/cache.ts
8
+ /**
9
+ * `$XDG_CACHE_HOME/seekrit`, else `~/.cache/seekrit` — beside the config
10
+ * directory holding the credential, never a shared temp directory.
11
+ */
12
+ function defaultCacheDir() {
13
+ return join(process.env.XDG_CACHE_HOME || join(homedir(), ".cache"), "seekrit");
14
+ }
15
+ const BIN = "seekrit-proxy";
16
+ /**
17
+ * Host → Rust target triple.
18
+ *
19
+ * Linux always resolves to **musl**: that build is statically linked, so one
20
+ * artifact covers glibc, musl, alpine, and distroless, and there is no libc
21
+ * detection to get wrong on a machine where `ldd` says something unexpected.
22
+ */
23
+ function detectTarget(os = platform(), cpu = arch()) {
24
+ const machine = cpu === "x64" ? "x86_64" : cpu === "arm64" ? "aarch64" : null;
25
+ if (!machine) throw new Error(`unsupported architecture "${cpu}" — build from source (apps/proxy) or set SEEKRIT_PROXY_BIN`);
26
+ switch (os) {
27
+ case "linux": return {
28
+ target: `${machine}-unknown-linux-musl`,
29
+ exe: ""
30
+ };
31
+ case "darwin": return {
32
+ target: `${machine}-apple-darwin`,
33
+ exe: ""
34
+ };
35
+ case "win32":
36
+ if (machine !== "x86_64") throw new Error(`no prebuilt seekrit-proxy for ${machine} Windows — set SEEKRIT_PROXY_BIN to a binary you built`);
37
+ return {
38
+ target: "x86_64-pc-windows-msvc",
39
+ exe: ".exe"
40
+ };
41
+ default: throw new Error(`unsupported platform "${os}" — build from source (apps/proxy) or set SEEKRIT_PROXY_BIN`);
42
+ }
43
+ }
44
+ /** `latest` stays `latest`; everything else is normalized to `v<x.y.z>`. */
45
+ function versionPrefix(version) {
46
+ if (version === "latest") return "latest";
47
+ return version.startsWith("v") ? version : `v${version}`;
48
+ }
49
+ function resolveVersion(explicit) {
50
+ return explicit ?? process.env.SEEKRIT_PROXY_VERSION ?? "0.7.0";
51
+ }
52
+ function resolveBaseUrl(explicit) {
53
+ return (explicit ?? process.env.SEEKRIT_PROXY_BASE_URL ?? "https://proxy.seekrit.dev").replace(/\/+$/, "");
54
+ }
55
+ /** Where a resolved binary is kept, keyed so versions and targets never collide. */
56
+ function proxyBinaryPath(version, target, exe) {
57
+ return join(defaultCacheDir(), "proxy", versionPrefix(version), target, `${BIN}${exe}`);
58
+ }
59
+ async function fetchBytes(url) {
60
+ const res = await fetch(url);
61
+ if (!res.ok) throw new Error(`GET ${url} → ${res.status} ${res.statusText}`);
62
+ return new Uint8Array(await res.arrayBuffer());
63
+ }
64
+ /**
65
+ * Ensure a `seekrit-proxy` binary exists locally and return its path.
66
+ *
67
+ * Order: an explicit `SEEKRIT_PROXY_BIN`, then a cached download for this
68
+ * version+target, then a fresh download. A binary already on `PATH` is
69
+ * deliberately *not* used — silently running a different version than the one
70
+ * this CLI pins is the kind of surprise that costs an afternoon.
71
+ */
72
+ async function resolveProxyBinary(options = {}) {
73
+ const override = process.env.SEEKRIT_PROXY_BIN;
74
+ if (override) {
75
+ if (!existsSync(override)) throw new Error(`SEEKRIT_PROXY_BIN points at ${override}, which does not exist`);
76
+ return override;
77
+ }
78
+ const version = resolveVersion(options.version);
79
+ const { target, exe } = detectTarget();
80
+ const dest = proxyBinaryPath(version, target, exe);
81
+ if (!options.force && version !== "latest" && existsSync(dest)) return dest;
82
+ const baseUrl = resolveBaseUrl(options.baseUrl);
83
+ const prefix = versionPrefix(version);
84
+ const name = `${BIN}-${target}${exe}`;
85
+ const binUrl = `${baseUrl}/${prefix}/bin/${name}`;
86
+ const sumUrl = `${binUrl}.sha256`;
87
+ if (!options.quiet) process.stderr.write(`seekrit: fetching ${BIN} ${prefix} (${target})…\n`);
88
+ let bytes;
89
+ let expected;
90
+ try {
91
+ [bytes, expected] = await Promise.all([fetchBytes(binUrl), fetchBytes(sumUrl).then((b) => Buffer.from(b).toString("utf8").trim().split(/\s+/)[0] ?? "")]);
92
+ } catch (err) {
93
+ const message = err instanceof Error ? err.message : String(err);
94
+ throw new Error(`could not download ${BIN} ${prefix} for ${target}: ${message}\n Set SEEKRIT_PROXY_BIN to a binary you already have, or build it from apps/proxy.`);
95
+ }
96
+ const actual = createHash("sha256").update(bytes).digest("hex");
97
+ if (!expected || actual !== expected.toLowerCase()) throw new Error(`checksum mismatch for ${name}: expected ${expected || "(none published)"}, got ${actual}. Refusing to run it.`);
98
+ const dir = dirname(dest);
99
+ mkdirSync(dir, { recursive: true });
100
+ const staging = join(dir, `.${BIN}-${process.pid}-${actual.slice(0, 12)}${exe}`);
101
+ try {
102
+ writeFileSync(staging, bytes, { mode: 493 });
103
+ renameSync(staging, dest);
104
+ } catch (err) {
105
+ rmSync(staging, { force: true });
106
+ throw err;
107
+ }
108
+ chmodSync(dest, 493);
109
+ return dest;
110
+ }
111
+ /**
112
+ * Run the proxy, forwarding stdio, signals, and its exit status.
113
+ *
114
+ * The proxy is a long-lived foreground process, so this wrapper has to be
115
+ * transparent: Node cannot exec-replace itself, and without relaying signals
116
+ * Node's default SIGINT handler would kill *this* process on Ctrl-C and leave
117
+ * the proxy running, holding decrypted secrets, with the shell prompt back.
118
+ */
119
+ async function runProxyBinary(argv, options = {}) {
120
+ const bin = await resolveProxyBinary(options);
121
+ const child = spawn(bin, argv, {
122
+ stdio: "inherit",
123
+ env: {
124
+ ...process.env,
125
+ ...options.env
126
+ }
127
+ });
128
+ const signals = [
129
+ "SIGINT",
130
+ "SIGTERM",
131
+ "SIGHUP",
132
+ "SIGQUIT"
133
+ ];
134
+ const forward = (signal) => {
135
+ if (child.exitCode !== null || child.signalCode !== null) return;
136
+ child.kill(signal);
137
+ };
138
+ for (const signal of signals) process.on(signal, forward);
139
+ return new Promise((resolve, reject) => {
140
+ child.on("error", (err) => {
141
+ for (const s of signals) process.off(s, forward);
142
+ reject(/* @__PURE__ */ new Error(`could not start ${bin}: ${err.message}\n If this is a fresh download, the platform may not match — set SEEKRIT_PROXY_BIN.`));
143
+ });
144
+ child.on("exit", (code, signal) => {
145
+ for (const s of signals) process.off(s, forward);
146
+ resolve(signal ? 128 + signalNumber(signal) : code ?? 0);
147
+ });
148
+ });
149
+ }
150
+ /** Signal name → number, for the 128+n exit convention. */
151
+ function signalNumber(signal) {
152
+ return {
153
+ SIGHUP: 1,
154
+ SIGINT: 2,
155
+ SIGQUIT: 3,
156
+ SIGKILL: 9,
157
+ SIGTERM: 15
158
+ }[signal] ?? 0;
159
+ }
160
+ //#endregion
161
+ //#region src/index.ts
162
+ /**
163
+ * `@seekrit/proxy` — an `npx`-able launcher for `seekrit-proxy`.
164
+ *
165
+ * The proxy is a Rust binary, which made the one component that keeps a
166
+ * decrypted secret *entirely* out of an untrusted workload also the one nobody
167
+ * tried: `cargo build` before you learn anything. This package removes that
168
+ * step. It downloads the released binary for the host platform, verifies its
169
+ * SHA-256 against the checksum published beside it, and execs it with whatever
170
+ * arguments you passed:
171
+ *
172
+ * SEEKRIT_TOKEN=skt_… npx -y @seekrit/proxy --config seekrit-proxy.toml
173
+ *
174
+ * Everything else is the proxy's own behaviour, unchanged — the arguments, the
175
+ * config file, the fail-closed startup, the allowlist. This is a launcher, not a
176
+ * wrapper: it adds no defaults and reads no config of its own.
177
+ *
178
+ * The package version tracks the binary version it fetches (release-please bumps
179
+ * both in one commit), so `npx @seekrit/proxy@0.7.0` runs proxy 0.7.0. Override
180
+ * with `SEEKRIT_PROXY_VERSION`, or skip the download entirely by pointing
181
+ * `SEEKRIT_PROXY_BIN` at a binary you already have.
182
+ *
183
+ * The download/verify/exec logic lives in `@seekrit/cli` and is shared with the
184
+ * `seekrit proxy run` subcommand; tsdown bundles it in at build time, the same
185
+ * arrangement `@seekrit/mcp` uses for the MCP server.
186
+ */
187
+ runProxyBinary(process.argv.slice(2), { version: "0.7.0" }).then((code) => {
188
+ process.exitCode = code;
189
+ }).catch((err) => {
190
+ const message = err instanceof Error ? err.message : String(err);
191
+ process.stderr.write(`seekrit-proxy: ${message}\n`);
192
+ process.exit(1);
193
+ });
194
+ //#endregion
195
+ export {};
package/package.json ADDED
@@ -0,0 +1,30 @@
1
+ {
2
+ "name": "@seekrit/proxy",
3
+ "version": "0.7.0",
4
+ "description": "npx-able launcher for seekrit-proxy — swap {{seekrit:NAME}} placeholders in outbound requests for decrypted secrets, so an agent never holds the key.",
5
+ "type": "module",
6
+ "publishConfig": {
7
+ "access": "public"
8
+ },
9
+ "bin": {
10
+ "seekrit-proxy": "./dist/index.js"
11
+ },
12
+ "files": [
13
+ "dist"
14
+ ],
15
+ "engines": {
16
+ "node": ">=20"
17
+ },
18
+ "scripts": {
19
+ "build": "tsdown",
20
+ "dev": "tsdown --watch",
21
+ "test": "vitest run",
22
+ "typecheck": "tsc --noEmit"
23
+ },
24
+ "devDependencies": {
25
+ "@seekrit/cli": "workspace:*",
26
+ "@types/node": "^26.1.0",
27
+ "tsdown": "^0.22.3",
28
+ "vitest": "^4.1.9"
29
+ }
30
+ }