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/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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "passcontrol",
3
- "version": "0.9.5",
3
+ "version": "1.1.0",
4
4
  "description": "Identity, scope and budget controls for AI agents while provider keys stay server-side.",
5
5
  "license": "BUSL-1.1",
6
6
  "homepage": "https://passcontrol.vertias.eu",
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@0.9.1 openai
12
- # or: npm install passcontrol@0.9.1 @anthropic-ai/sdk
13
+ npm install passcontrol openai
14
+ # or: npm install passcontrol @anthropic-ai/sdk
13
15
  ```
14
16
 
15
- Dependencies: only [`@noble/curves`](https://github.com/paulmillr/noble-curves) and the
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 developer API (`/api/control/v1`), authenticated with a `pc_` API key.
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
- ## 0.9.0 compatibility and assurance
158
+ ## Compatibility and assurance
157
159
 
158
160
  `clientOptions` accepts `openai`, `anthropic`, `groq`, `mistral`, `together`, `deepseek`,
159
- and `gemini`. OpenAI POST Responses works through `pc.fetch`/the OpenAI SDK as well as
160
- Chat Completions. Gemini uses Google's OpenAI-compatible endpoint; native
161
- `generateContent` is not supported. See [accepted paths](https://github.com/Vertias3u/PassControl/blob/main/DOCUMENTATION.md#data-plane--proxy-a-model-call).
162
-
163
- The TypeScript SDK **does not attach sender proofs in 0.9.0**. Its provider requests use
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` drops SDK housekeeping (startup model-listing probes),
121
- * `housekeeping` returns only those. The limit is applied before the
122
- * filter, so a filtered page can be shorter than the limit asked for.
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` drops SDK housekeeping (startup model-listing probes),
99
- * `housekeeping` returns only those. The limit is applied before the
100
- * filter, so a filtered page can be shorter than the limit asked for.
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 }),
@@ -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