passcontrol 0.9.5 → 1.1.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.
- package/README.md +251 -140
- package/bin/passcontrol.mjs +377 -34
- package/cli/config.mjs +88 -5
- package/cli/gateway-probe.mjs +56 -0
- package/cli/integration-defaults.d.mts +3 -1
- package/cli/integration-defaults.mjs +16 -5
- package/cli/local-stack.mjs +20 -0
- package/cli/mcp/README.md +2 -0
- package/cli/menu-session.mjs +8 -2
- package/cli/menu.mjs +1 -0
- package/cli/presets.mjs +12 -0
- package/cli/proxy-policy.mjs +49 -8
- package/cli/selftest.mjs +11 -1
- package/cli/sidecar.mjs +10 -1
- package/cli/update-check.mjs +7 -3
- package/cli/update.mjs +214 -0
- package/package.json +1 -1
- package/sdk/README.md +15 -10
- package/sdk/control.d.ts +10 -5
- package/sdk/control.js +5 -3
- package/sdk/passcontrol.d.ts +1 -1
package/cli/update.mjs
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
// `passcontrol update` — the decisions, kept pure so every one of them is tested
|
|
2
|
+
// before it touches someone's install. bin/passcontrol.mjs does the mutating
|
|
3
|
+
// half (npm, git, the local stack) and asks this module what to do.
|
|
4
|
+
//
|
|
5
|
+
// Two things get updated, and they fail differently:
|
|
6
|
+
//
|
|
7
|
+
// * The CLI. Only an npm global install is updated in place, pinned to the
|
|
8
|
+
// exact version just read from the registry (not `@latest`, so a release
|
|
9
|
+
// published mid-update cannot slip in). npx, pnpm, yarn, bun, volta and a
|
|
10
|
+
// source checkout each get the right command PRINTED: guessing another
|
|
11
|
+
// package manager's layout is how a tool ends up installed twice.
|
|
12
|
+
// * The self-host app checkout `setup` made — a clone of the PUBLIC repo only.
|
|
13
|
+
// Fast-forward, never merge; refuse on local edits, a diverged branch, or a
|
|
14
|
+
// checkout that is not the public repo (a private or forked checkout is its
|
|
15
|
+
// owner's to update). Migrations only go forward, so the plan names them.
|
|
16
|
+
import fs from "node:fs";
|
|
17
|
+
import os from "node:os";
|
|
18
|
+
import path from "node:path";
|
|
19
|
+
|
|
20
|
+
import { isNewer } from "./update-check.mjs";
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* How this CLI was installed, and how to update it.
|
|
24
|
+
*
|
|
25
|
+
* `command` is non-null only when running it is safe: an npm global install
|
|
26
|
+
* whose prefix can be read off the script's own path. Everything else gets a
|
|
27
|
+
* `manual` line to print.
|
|
28
|
+
*/
|
|
29
|
+
export function detectInstall({ scriptPath, platform = process.platform, isSourceCheckout = false, version }) {
|
|
30
|
+
const spec = `passcontrol@${version}`;
|
|
31
|
+
const p = String(scriptPath ?? "");
|
|
32
|
+
const has = (fragment) => p.replace(/\\/gu, "/").includes(fragment);
|
|
33
|
+
if (isSourceCheckout) {
|
|
34
|
+
return { method: "source", command: null, manual: "This CLI runs from a source checkout: update it with `git pull` there." };
|
|
35
|
+
}
|
|
36
|
+
if (has("/_npx/")) return { method: "npx", command: null, manual: `npx passcontrol@${version} (npx runs a fresh copy; nothing to install)` };
|
|
37
|
+
if (has("/pnpm/") || has("/.pnpm/")) return { method: "pnpm", command: null, manual: `pnpm add -g ${spec}` };
|
|
38
|
+
if (has("/yarn/global/") || has("/.yarn/")) return { method: "yarn", command: null, manual: `yarn global add ${spec}` };
|
|
39
|
+
if (has("/.bun/")) return { method: "bun", command: null, manual: `bun add -g ${spec}` };
|
|
40
|
+
if (has("/.volta/")) return { method: "volta", command: null, manual: `volta install ${spec}` };
|
|
41
|
+
|
|
42
|
+
const windows = platform === "win32";
|
|
43
|
+
const match = windows
|
|
44
|
+
? /^(.*)\\node_modules\\passcontrol\\bin\\passcontrol\.mjs$/iu.exec(p)
|
|
45
|
+
: /^(.*)\/lib\/node_modules\/passcontrol\/bin\/passcontrol\.mjs$/u.exec(p);
|
|
46
|
+
if (match && match[1]) {
|
|
47
|
+
const prefix = match[1];
|
|
48
|
+
return {
|
|
49
|
+
method: "npm-global",
|
|
50
|
+
prefix,
|
|
51
|
+
command: [windows ? "npm.cmd" : "npm", "install", "-g", "--prefix", prefix, spec],
|
|
52
|
+
manual: `npm install -g --prefix ${prefix} ${spec}`,
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
return { method: "unknown", command: null, manual: `npm install -g ${spec}` };
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** `github.com/owner/repo`, lowercased, from any of the forms git accepts. */
|
|
59
|
+
function normalizeRepoUrl(url) {
|
|
60
|
+
let s = String(url ?? "").trim().toLowerCase();
|
|
61
|
+
s = s.replace(/^git@([^:]+):/u, "$1/");
|
|
62
|
+
s = s.replace(/^[a-z+]+:\/\//u, "");
|
|
63
|
+
s = s.replace(/^[^@/]+@/u, "");
|
|
64
|
+
s = s.replace(/\/+$/u, "").replace(/\.git$/u, "");
|
|
65
|
+
return s;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Exact host, owner and repo — never a prefix or substring match. */
|
|
69
|
+
export function isPublicRepoUrl(url, publicUrl) {
|
|
70
|
+
const a = normalizeRepoUrl(url);
|
|
71
|
+
return a !== "" && a === normalizeRepoUrl(publicUrl);
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Tracked files with local changes that must stop an update.
|
|
76
|
+
*
|
|
77
|
+
* `package-lock.json` is tolerated: `npm install` rewrites it (the 0.9.5 mirror
|
|
78
|
+
* shipped a stale root version, so every setup checkout shows it modified), it
|
|
79
|
+
* is npm's output rather than anyone's work, and the update restores it and
|
|
80
|
+
* then runs `npm ci`. Untracked files are left to the fast-forward, which names
|
|
81
|
+
* any real collision itself.
|
|
82
|
+
*/
|
|
83
|
+
export function dirtyBlockers(porcelain) {
|
|
84
|
+
const files = [];
|
|
85
|
+
for (const raw of String(porcelain ?? "").split("\n")) {
|
|
86
|
+
const line = raw.replace(/\r$/u, "");
|
|
87
|
+
if (!line.trim()) continue;
|
|
88
|
+
// Two status columns, a space, the path. A caller that trimmed git's output
|
|
89
|
+
// leaves the FIRST line with one column (" M x" → "M x"), so accept that
|
|
90
|
+
// too rather than reading columns by position (which once saw "ackage-lock.json").
|
|
91
|
+
const match = /^([ MADRCUT?!]{2}) (.+)$/u.exec(line) ?? /^([MADRCUT?!]) (.+)$/u.exec(line);
|
|
92
|
+
if (!match) continue;
|
|
93
|
+
const status = match[1].trim();
|
|
94
|
+
if (status === "??" || status === "!!") continue;
|
|
95
|
+
if (match[2] !== "package-lock.json") files.push(match[2]);
|
|
96
|
+
}
|
|
97
|
+
return files;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
/**
|
|
101
|
+
* The project id and port offset `setup` baked into supabase/config.toml, or
|
|
102
|
+
* null. Read back rather than re-derived, because re-running the stack with a
|
|
103
|
+
* different offset or id brings up a FRESH, EMPTY Supabase project — which
|
|
104
|
+
* looks exactly like data loss.
|
|
105
|
+
*/
|
|
106
|
+
export function stackFromConfig(configText) {
|
|
107
|
+
const text = String(configText ?? "");
|
|
108
|
+
const projectId = /^project_id\s*=\s*"([^"]+)"\s*$/mu.exec(text)?.[1];
|
|
109
|
+
const api = /^\[api\]\s*\n(?:[^[]*?\n)?port\s*=\s*(\d+)/mu.exec(text)?.[1];
|
|
110
|
+
if (!projectId || !api) return null;
|
|
111
|
+
const offset = Number(api) - 54321;
|
|
112
|
+
if (!Number.isInteger(offset) || offset < 0 || offset > 10000) return null;
|
|
113
|
+
return { projectId, offset };
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** The id scripts/dev-stack.sh will compute for this directory and offset. */
|
|
117
|
+
export function expectedProjectId(dirName, offset) {
|
|
118
|
+
return offset === 0 ? dirName : `${dirName}-${offset}`;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* What an update would do. `app.status` is one of:
|
|
123
|
+
* none — no self-host checkout on this machine (a Cloud user)
|
|
124
|
+
* current — at the public repo's tip
|
|
125
|
+
* behind — fast-forwardable; `behind`, `from`, `to`, `migrations`
|
|
126
|
+
* refuse — `reason` says why this checkout is left alone
|
|
127
|
+
* `app.resume` is set when an earlier update stopped part way.
|
|
128
|
+
*/
|
|
129
|
+
export function planUpdate({ current, latest, install, app }) {
|
|
130
|
+
const cli = {
|
|
131
|
+
reachable: typeof latest === "string",
|
|
132
|
+
needed: typeof latest === "string" && isNewer(latest, current),
|
|
133
|
+
from: current,
|
|
134
|
+
to: latest ?? null,
|
|
135
|
+
command: install?.command ?? null,
|
|
136
|
+
manual: install?.manual ?? "",
|
|
137
|
+
method: install?.method ?? "unknown",
|
|
138
|
+
};
|
|
139
|
+
const appWork = app?.status === "behind" || Boolean(app?.resume);
|
|
140
|
+
return { cli, app: app ?? { status: "none" }, nothingToDo: !cli.needed && !appWork };
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** The plan as lines for a terminal. */
|
|
144
|
+
export function formatPlan(plan) {
|
|
145
|
+
const lines = [];
|
|
146
|
+
const { cli, app } = plan;
|
|
147
|
+
if (!cli.reachable) {
|
|
148
|
+
lines.push("CLI: could not reach the npm registry, so it is not known whether a newer version exists.");
|
|
149
|
+
} else if (cli.needed) {
|
|
150
|
+
lines.push(`CLI: ${cli.from} → ${cli.to}`);
|
|
151
|
+
lines.push(cli.command ? ` runs: ${cli.command.join(" ")}` : ` run it yourself: ${cli.manual}`);
|
|
152
|
+
} else {
|
|
153
|
+
lines.push(`CLI: ${cli.from}, nothing newer on npm (latest published: ${cli.to}).`);
|
|
154
|
+
}
|
|
155
|
+
switch (app.status) {
|
|
156
|
+
case "none":
|
|
157
|
+
lines.push("App: no self-host checkout on this machine.");
|
|
158
|
+
break;
|
|
159
|
+
case "refuse":
|
|
160
|
+
lines.push(`App: left alone — ${app.reason}`);
|
|
161
|
+
break;
|
|
162
|
+
case "current":
|
|
163
|
+
lines.push(app.resume ? "App: at the latest commit, but an earlier update was interrupted; it will finish install, migrations and restart." : "App: up to date.");
|
|
164
|
+
break;
|
|
165
|
+
case "behind": {
|
|
166
|
+
lines.push(`App: ${app.behind} new commit(s), ${app.from} → ${app.to}`);
|
|
167
|
+
const migrations = app.migrations ?? [];
|
|
168
|
+
lines.push(
|
|
169
|
+
migrations.length
|
|
170
|
+
? ` new database migrations (they only go forward): ${migrations.map((m) => path.basename(m)).join(", ")}`
|
|
171
|
+
: " no new database migrations"
|
|
172
|
+
);
|
|
173
|
+
lines.push(" steps: stop the dashboard, fast-forward, npm ci, apply migrations, start the dashboard again if it was running");
|
|
174
|
+
break;
|
|
175
|
+
}
|
|
176
|
+
default:
|
|
177
|
+
break;
|
|
178
|
+
}
|
|
179
|
+
return lines;
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
// ── Resume marker ─────────────────────────────────────────────────────────────
|
|
183
|
+
//
|
|
184
|
+
// Written before the first change to the checkout and cleared on success. After
|
|
185
|
+
// a fast-forward HEAD already equals the target, so without it a failed
|
|
186
|
+
// `npm ci` or migration would read as "up to date" on the next run.
|
|
187
|
+
|
|
188
|
+
export function markerPath(env = process.env) {
|
|
189
|
+
const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
|
|
190
|
+
return path.join(base, "passcontrol", "update-in-progress.json");
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
export function readMarker(env = process.env) {
|
|
194
|
+
try {
|
|
195
|
+
const value = JSON.parse(fs.readFileSync(markerPath(env), "utf8"));
|
|
196
|
+
return value && typeof value.appRoot === "string" ? value : null;
|
|
197
|
+
} catch {
|
|
198
|
+
return null;
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
export function writeMarker(marker, env = process.env) {
|
|
203
|
+
const file = markerPath(env);
|
|
204
|
+
fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
|
|
205
|
+
fs.writeFileSync(file, `${JSON.stringify(marker)}\n`, { mode: 0o600 });
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
export function clearMarker(env = process.env) {
|
|
209
|
+
try {
|
|
210
|
+
fs.rmSync(markerPath(env), { force: true });
|
|
211
|
+
} catch {
|
|
212
|
+
// Nothing to clear.
|
|
213
|
+
}
|
|
214
|
+
}
|
package/package.json
CHANGED
package/sdk/README.md
CHANGED
|
@@ -7,12 +7,14 @@ your existing OpenAI/Anthropic SDK, **not rewriting the agent**.
|
|
|
7
7
|
|
|
8
8
|
Install it beside the provider SDK used by your agent:
|
|
9
9
|
|
|
10
|
+
On Windows, run these shell commands in PowerShell. Replace placeholders before running.
|
|
11
|
+
|
|
10
12
|
```bash
|
|
11
|
-
npm install passcontrol
|
|
12
|
-
# or: npm install passcontrol
|
|
13
|
+
npm install passcontrol openai
|
|
14
|
+
# or: npm install passcontrol @anthropic-ai/sdk
|
|
13
15
|
```
|
|
14
16
|
|
|
15
|
-
Dependencies:
|
|
17
|
+
Dependencies: [`@noble/curves`](https://github.com/paulmillr/noble-curves), `@noble/hashes`, and the
|
|
16
18
|
platform `fetch`/`crypto`. Runs on Node 18+ and edge/server runtimes.
|
|
17
19
|
|
|
18
20
|
> Keep `passportSecret` in the trusted agent runtime and out of source control, logs,
|
|
@@ -105,7 +107,7 @@ const res = await pc.fetch(`${gateway}/api/v1/anthropic/v1/messages`, {
|
|
|
105
107
|
## Control-plane SDK (manage your fleet)
|
|
106
108
|
|
|
107
109
|
Separate from the data-plane client above: `ControlClient` (in `./control`) is a typed
|
|
108
|
-
wrapper over the
|
|
110
|
+
wrapper over the workspace control API (`/api/control/v1`), authenticated with a `pc_` API key.
|
|
109
111
|
It mirrors the REST resources, unwraps the `{ data }` envelope, and throws
|
|
110
112
|
`ControlApiError` (with `status`, `code`, `requestId`) on failure.
|
|
111
113
|
|
|
@@ -153,14 +155,17 @@ The full reference lives in [the public OpenAPI document](https://github.com/Ver
|
|
|
153
155
|
the gateway only ever sees the public key and the signature.
|
|
154
156
|
|
|
155
157
|
|
|
156
|
-
##
|
|
158
|
+
## Compatibility and assurance
|
|
157
159
|
|
|
158
160
|
`clientOptions` accepts `openai`, `anthropic`, `groq`, `mistral`, `together`, `deepseek`,
|
|
159
|
-
and `
|
|
160
|
-
Chat Completions.
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
161
|
+
`gemini`, `xai` and `azure`. OpenAI POST Responses works through `pc.fetch`/the OpenAI SDK as well as
|
|
162
|
+
Chat Completions. xAI is served through its Responses API only (`client.responses.create`);
|
|
163
|
+
its legacy Chat Completions endpoint is refused. Gemini uses Google's OpenAI-compatible endpoint; native
|
|
164
|
+
`generateContent` is not supported. Azure OpenAI takes the plain OpenAI client (not
|
|
165
|
+
`AzureOpenAI`), with `model` set to your deployment name; the gateway sends the call to the
|
|
166
|
+
resource address stored with your Azure key. See [accepted paths](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md#data-plane--proxy-a-model-call).
|
|
167
|
+
|
|
168
|
+
The TypeScript SDK **does not attach sender proofs**. Its provider requests use
|
|
164
169
|
bearer visas: they work with sender-proof mode off/observe, but required mode refuses
|
|
165
170
|
them without an additional correct proof implementation. The current sidecar attaches
|
|
166
171
|
proofs. A valid mint signature is not a signature over each provider request.
|
package/sdk/control.d.ts
CHANGED
|
@@ -95,6 +95,9 @@ export declare class ControlClient {
|
|
|
95
95
|
}[];
|
|
96
96
|
budget_tokens?: number | null;
|
|
97
97
|
budget_cents?: number | null;
|
|
98
|
+
/** Periodic spend limit: send both, or both null to remove it. */
|
|
99
|
+
budget_period?: "day" | "month" | null;
|
|
100
|
+
budget_period_cents?: number | null;
|
|
98
101
|
}, opts?: WriteOpts) => Promise<{
|
|
99
102
|
id: string;
|
|
100
103
|
}>;
|
|
@@ -117,21 +120,23 @@ export declare class ControlClient {
|
|
|
117
120
|
readonly logs: {
|
|
118
121
|
/**
|
|
119
122
|
* `class` selects a view, never a different record: omitted returns every
|
|
120
|
-
* call, `inference`
|
|
121
|
-
*
|
|
122
|
-
*
|
|
123
|
+
* call, `inference` returns model calls only (no SDK housekeeping — startup
|
|
124
|
+
* model-listing probes — and no service calls), `housekeeping` returns only
|
|
125
|
+
* those probes, and `service` returns only calls to a non-LLM API such as
|
|
126
|
+
* GitHub. The limit is applied before the filter, so a filtered page can be
|
|
127
|
+
* shorter than the limit asked for.
|
|
123
128
|
*/
|
|
124
129
|
list: (params?: {
|
|
125
130
|
agent_id?: string;
|
|
126
131
|
status?: string;
|
|
127
|
-
class?: "inference" | "housekeeping";
|
|
132
|
+
class?: "inference" | "housekeeping" | "service";
|
|
128
133
|
limit?: number;
|
|
129
134
|
cursor?: string;
|
|
130
135
|
}) => Promise<any[]>;
|
|
131
136
|
page: (params?: {
|
|
132
137
|
agent_id?: string;
|
|
133
138
|
status?: string;
|
|
134
|
-
class?: "inference" | "housekeeping";
|
|
139
|
+
class?: "inference" | "housekeeping" | "service";
|
|
135
140
|
limit?: number;
|
|
136
141
|
cursor?: string;
|
|
137
142
|
}) => Promise<{
|
package/sdk/control.js
CHANGED
|
@@ -95,9 +95,11 @@ export class ControlClient {
|
|
|
95
95
|
logs = {
|
|
96
96
|
/**
|
|
97
97
|
* `class` selects a view, never a different record: omitted returns every
|
|
98
|
-
* call, `inference`
|
|
99
|
-
*
|
|
100
|
-
*
|
|
98
|
+
* call, `inference` returns model calls only (no SDK housekeeping — startup
|
|
99
|
+
* model-listing probes — and no service calls), `housekeeping` returns only
|
|
100
|
+
* those probes, and `service` returns only calls to a non-LLM API such as
|
|
101
|
+
* GitHub. The limit is applied before the filter, so a filtered page can be
|
|
102
|
+
* shorter than the limit asked for.
|
|
101
103
|
*/
|
|
102
104
|
list: (params) => this.req("GET", "/logs", { query: params }),
|
|
103
105
|
page: (params) => this.request("GET", "/logs", { query: params }),
|
package/sdk/passcontrol.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type ProviderId = "openai" | "anthropic" | "groq" | "mistral" | "together" | "deepseek" | "gemini";
|
|
1
|
+
export type ProviderId = "openai" | "anthropic" | "groq" | "mistral" | "together" | "deepseek" | "gemini" | "xai" | "azure";
|
|
2
2
|
export interface PassControlOptions {
|
|
3
3
|
/**
|
|
4
4
|
* Gateway origin, e.g. https://passcontrol.example.com — scheme, host and
|