passcontrol 1.3.0 → 1.5.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.
@@ -0,0 +1,84 @@
1
+ // The sidecar's journal: the user's own list of the receipt ids their calls produced.
2
+ //
3
+ // WHY IT EXISTS. A session seal (`passcontrol verify session`) proves the issuer
4
+ // committed to a set of receipts. The journal is what lets the user check that set
5
+ // against an INDEPENDENT record: every id here must be in the seal's bundle, so a
6
+ // call left out of the seal is caught. Without it a seal is no stronger than a
7
+ // statement (sdk/verify.ts, verifySession).
8
+ //
9
+ // WHAT IT HOLDS: one JSON line per relayed call — `{ id, t, s }`, the receipt id,
10
+ // the time in epoch milliseconds, and the HTTP status. Nothing else, ever: no
11
+ // prompt, no model, no header, no body. The id is already shown to the client in
12
+ // `x-passcontrol-receipt-id`; the journal only keeps it.
13
+ //
14
+ // One file per sidecar run, named by start time and run id, owner-only (0600 in a
15
+ // 0700 directory). Created on the first call that returns a receipt, so a sidecar
16
+ // that relays nothing leaves nothing behind. On by default; `--no-journal` turns it
17
+ // off (D3, 2026-10-08).
18
+ //
19
+ // A journal failure NEVER breaks a call: the call has already happened, and the
20
+ // worst a lost line can do is make a later seal check report that receipt as
21
+ // "in the seal, not in your journal", which is never a failure. It warns once.
22
+ import fs from "node:fs";
23
+ import path from "node:path";
24
+ import { globalConfigPath } from "./config.mjs";
25
+
26
+ const RECEIPT_ID = /^[A-Za-z0-9._:-]{1,128}$/;
27
+
28
+ /** `<config dir>/journal`, beside the CLI's own config file. */
29
+ export function defaultJournalDir(env = process.env) {
30
+ return path.join(path.dirname(globalConfigPath(env)), "journal");
31
+ }
32
+
33
+ /** `2026-10-08T03-21-00Z`: sortable, and legal in a filename on every platform. */
34
+ function stamp(ms) {
35
+ return new Date(ms).toISOString().replace(/\.\d{3}Z$/, "Z").replace(/:/g, "-");
36
+ }
37
+
38
+ export function openJournal({ dir = defaultJournalDir(), runId, now = Date.now, onError = () => {} }) {
39
+ const file = path.join(dir, `${stamp(now())}-${runId}.jsonl`);
40
+ let fd = null;
41
+ let broken = false;
42
+
43
+ function ensureOpen() {
44
+ if (fd !== null) return fd;
45
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
46
+ // mkdir's mode is filtered by the umask, and an existing directory keeps
47
+ // whatever it had. This one holds a record of the user's calls: owner-only.
48
+ fs.chmodSync(dir, 0o700);
49
+ fd = fs.openSync(file, "a", 0o600);
50
+ fs.fchmodSync(fd, 0o600);
51
+ return fd;
52
+ }
53
+
54
+ return {
55
+ path: file,
56
+ /**
57
+ * Record one relayed call. Never throws. `session` is the session the call
58
+ * declared (cli/declared-session.mjs): one sidecar run serves many sessions, and
59
+ * a seal is checked against its own session's lines only.
60
+ */
61
+ record(id, status, session) {
62
+ if (broken || typeof id !== "string" || !RECEIPT_ID.test(id)) return;
63
+ try {
64
+ const entry = { id, t: now(), s: Number.isInteger(status) ? status : 0 };
65
+ if (typeof session === "string" && RECEIPT_ID.test(session)) entry.ses = session;
66
+ const line = JSON.stringify(entry) + "\n";
67
+ fs.writeSync(ensureOpen(), line);
68
+ } catch (e) {
69
+ broken = true;
70
+ onError(e);
71
+ }
72
+ },
73
+ close() {
74
+ if (fd !== null) {
75
+ try {
76
+ fs.closeSync(fd);
77
+ } catch {
78
+ // Already closed, or the process is exiting: nothing to keep.
79
+ }
80
+ fd = null;
81
+ }
82
+ },
83
+ };
84
+ }
package/cli/mcp/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # PassControl MCP server
2
2
 
3
- `passcontrol mcp` starts a local stdio MCP server with `chat` and `list_models`.
3
+ `passcontrol mcp` starts a local stdio MCP server with `chat`, `list_models` and `budget`.
4
4
  It reads the same environment, nearest `.passcontrol`, and global
5
5
  `~/.config/passcontrol/config` sources as the rest of the CLI. MCP client setup requires a
6
6
  passport in the global profile so clients can launch from any working directory without
@@ -65,6 +65,9 @@ config contains a passport secret or provider key.
65
65
  `chat` sends a bearer visa, without a sender proof. Required sender-proof mode
66
66
  therefore refuses it; use off/observe for this client. `list_models` reads model patterns
67
67
  from the visa scope, not a live upstream model catalog; a wildcard is not a callable model.
68
+ `budget` reads the agent's own limits from the gateway (`GET /api/v1/self`): what is used,
69
+ what is left, and when a daily or monthly limit resets. It spends nothing and writes no log
70
+ row; like `chat`, it sends a bearer visa, so required sender-proof mode refuses it.
68
71
  Providers: OpenAI, Anthropic, Groq, Mistral, Together, DeepSeek, and Gemini (OpenAI-compatible).
69
72
  The global profile can use the CLI OS credential store (`passcontrol key status`) rather
70
73
  than containing the Passport secret. Custody declarations do not prove storage.
@@ -156,5 +156,18 @@ export function createGatewayClient({
156
156
  async listModels() {
157
157
  return modelsFromVisa(await visas.getVisa());
158
158
  },
159
+
160
+ /** The agent's own scope and limits (GET /api/v1/self). Reads; spends nothing. */
161
+ async self() {
162
+ const response = await visas.fetchWithVisa((visa) =>
163
+ fetchImpl(`${baseUrl}/api/v1/self`, { method: "GET", headers: { authorization: `Bearer ${visa}` } })
164
+ );
165
+ if (!response.ok) throw new Error(proxyError(response.status, await response.text()));
166
+ try {
167
+ return await response.json();
168
+ } catch {
169
+ throw new Error("Gateway returned a non-JSON answer for the agent's limits.");
170
+ }
171
+ },
159
172
  };
160
173
  }
@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
2
2
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
3
3
  import { z } from "zod/v4";
4
4
  import { PACKAGE_VERSION, PROVIDERS } from "../config.mjs";
5
+ import { budgetLines } from "../budget-format.mjs";
5
6
  import { createGatewayClient } from "./gateway.mjs";
6
7
 
7
8
  const messageSchema = z.object({
@@ -104,6 +105,32 @@ export function createMcpServer(options) {
104
105
  }
105
106
  );
106
107
 
108
+ server.registerTool(
109
+ "budget",
110
+ {
111
+ title: "Budget and limits",
112
+ description:
113
+ "Read this agent's own spending and token limits: what is used, what is left, and when a daily or monthly limit resets. Check it before an expensive call; a cheaper model may fit where this one would be refused.",
114
+ annotations: {
115
+ readOnlyHint: true,
116
+ destructiveHint: false,
117
+ idempotentHint: true,
118
+ openWorldHint: false,
119
+ },
120
+ },
121
+ async () => {
122
+ try {
123
+ const self = await gateway.self();
124
+ return {
125
+ content: [{ type: "text", text: budgetLines(self).join("\n") }],
126
+ structuredContent: self,
127
+ };
128
+ } catch (error) {
129
+ return toolError(error);
130
+ }
131
+ }
132
+ );
133
+
107
134
  return server;
108
135
  }
109
136
 
package/cli/menu.mjs CHANGED
@@ -144,6 +144,8 @@ export const GROUPS = [
144
144
  // sender proof in 0.9, so a workspace in required mode refuses this client
145
145
  // while the sidecar keeps working. Most people never run it by hand —
146
146
  // `configure <client> --write` wires it into the client's own config.
147
+ // A board that holds the terminal until q, so the same terms as the two servers.
148
+ command({ id: "watch", label: "Watch the sidecar's calls live", run: ["watch"], detail: "watch --port 8788", description: "Read-only board: each call, its sub-agent, model, outcome and time.", effect: "long_running", network: "gateway", keywords: ["board", "live", "subagent", "tail"], needsArgs: true, returnToMenu: true }),
147
149
  command({ id: "mcp", label: "Serve MCP to desktop agent clients", run: ["mcp"], detail: "mcp", description: "Stdio server for MCP clients. Its chat sends no sender proof in 0.9.", effect: "long_running", network: "provider", keywords: ["stdio", "claude", "cursor", "desktop"], needsArgs: true, returnToMenu: true }),
148
150
  ],
149
151
  },
@@ -157,6 +159,7 @@ export const GROUPS = [
157
159
  command({ id: "agent-suspend", label: "Suspend an agent", run: ["agent", "suspend"], detail: "agent suspend <id>", description: "Temporarily refuse every new call from one active agent.", effect: "tenant_write", network: "gateway", guide: "suspend", needsArgs: true }),
158
160
  command({ id: "agent-resume", label: "Resume an agent", run: ["agent", "resume"], detail: "agent resume <id>", description: "Allow a suspended agent to authenticate again.", effect: "tenant_write", network: "gateway", guide: "resume", needsArgs: true }),
159
161
  command({ id: "kill", label: "Tenant kill switch", run: ["kill"], detail: "kill on|off", description: "Arm or disarm the workspace-wide emergency stop.", effect: "tenant_write", network: "gateway", guide: "kill", needsArgs: true, current: currentFrom("kill") }),
162
+ command({ id: "profile-list", label: "List coding-tool profiles", run: ["profile", "list"], detail: "profile list", description: "Show each coding tool's own agent: its passport and sidecar port.", keywords: ["profile", "claude code", "codex", "identity"] }),
160
163
  ],
161
164
  },
162
165
  {
@@ -171,6 +174,7 @@ export const GROUPS = [
171
174
  // reading of it is a money question. Verifying somebody ELSE's statement
172
175
  // is the evidence question, and that one sits with the other verifiers.
173
176
  command({ id: "statements", label: "Signed spend statements", run: ["statements"], detail: "statements", description: "Show the daily chain committing to every receipt in each window.", network: "gateway" }),
177
+ command({ id: "sessions", label: "Coding sessions", run: ["sessions"], detail: "sessions", description: "Claude Code and Codex sessions: sub-agents and spend, as declared.", network: "gateway" }),
174
178
  ],
175
179
  },
176
180
  {
@@ -238,6 +242,7 @@ export const GROUPS = [
238
242
  hint: "revoke, rotate or destroy",
239
243
  items: [
240
244
  command({ id: "agent-rotate", label: "Rotate a passport key", run: ["agent", "rotate"], detail: "agent rotate <id>", description: "Replace an agent passport and reveal a new private key once.", effect: "irreversible", network: "gateway", needsArgs: true }),
245
+ command({ id: "agent-revoke-delegation", label: "Revoke a delegation", run: ["agent", "revoke-delegation"], detail: "agent revoke-delegation <id>", description: "Permanently stop one delegation, or every one an agent issued before now.", effect: "irreversible", network: "gateway", needsArgs: true }),
241
246
  command({ id: "agent-revoke", label: "Revoke an agent permanently", run: ["agent", "revoke"], detail: "agent revoke <id>", description: "Permanently prevent an agent from authenticating again.", effect: "irreversible", network: "gateway", needsArgs: true }),
242
247
  command({ id: "keygen-instance", label: "Create a receipt-signing key", run: ["keygen", "instance"], detail: "keygen instance", description: "Reveal a new instance signing seed; replacing a live key requires a rotation plan.", effect: "irreversible", needsArgs: true }),
243
248
  command({ id: "reset", label: "Destroy and recreate the local stack", run: ["reset"], detail: "reset --local --confirm RESET", description: "Delete and recreate local stack state after an explicit typed confirmation.", effect: "irreversible", needsArgs: true }),
@@ -261,6 +266,8 @@ export const HIDDEN = {
261
266
  keygen: "reached through its `instance` subcommand under Trust",
262
267
  verify: "reached through its subcommands under Evidence",
263
268
  try: "kept as an explanatory compatibility error, but no longer performs an operation",
269
+ seal: "needs a session and an agent, both named by `sessions`, which is listed under Money",
270
+ statusline: "Claude Code runs it, not a person; `configure claude-code --statusline` installs it",
264
271
  };
265
272
 
266
273
  /** Every top-level command name the menu can reach, flattened. */
@@ -0,0 +1,92 @@
1
+ // Named profiles: one identity per coding tool (1.4.0 candidate 4, owner 2026-10-10;
2
+ // design plans/one-identity-per-tool.md).
3
+ //
4
+ // A profile is a config file at <config dir>/profiles/<name>, in the global config's
5
+ // format, holding a passport and the sidecar port it serves. It holds a passport
6
+ // SECRET, so it gets the same protection: a 0700 directory, a 0600 file, and nothing
7
+ // in this module ever prints a value.
8
+ import fs from "node:fs";
9
+ import os from "node:os";
10
+ import path from "node:path";
11
+
12
+ export const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9-]{0,31}$/;
13
+
14
+ /** The port each coding tool's dedicated sidecar serves. 8788 stays the shared default. */
15
+ export const TOOL_PROFILE_PORTS = { "claude-code": 8790, codex: 8791 };
16
+
17
+ export function profilesDir(env = process.env) {
18
+ const base = env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
19
+ return path.join(base, "passcontrol", "profiles");
20
+ }
21
+
22
+ export function profilePath(name, env = process.env) {
23
+ if (typeof name !== "string" || !PROFILE_NAME_RE.test(name)) {
24
+ throw new Error(`Invalid profile name ${JSON.stringify(String(name)).slice(0, 48)}: use lowercase letters, digits and dashes (up to 32).`);
25
+ }
26
+ return path.join(profilesDir(env), name);
27
+ }
28
+
29
+ function parse(text) {
30
+ const values = {};
31
+ for (const raw of text.split("\n")) {
32
+ const line = raw.trim();
33
+ if (!line || line.startsWith("#")) continue;
34
+ const eq = line.indexOf("=");
35
+ if (eq <= 0) continue;
36
+ values[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
37
+ }
38
+ return values;
39
+ }
40
+
41
+ /** The profile's values, or null when it does not exist. */
42
+ export function readProfile(name, env = process.env) {
43
+ const file = profilePath(name, env);
44
+ if (!fs.existsSync(file)) return null;
45
+ return parse(fs.readFileSync(file, "utf8"));
46
+ }
47
+
48
+ /** Merge values into a profile, creating it (and its directory) owner-only. */
49
+ export function writeProfile(name, values, env = process.env) {
50
+ const file = profilePath(name, env);
51
+ fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
52
+ fs.chmodSync(path.dirname(file), 0o700);
53
+ const merged = { ...(readProfile(name, env) ?? {}), ...values };
54
+ const body =
55
+ "# PassControl profile. Keep this file private: it holds a passport secret.\n" +
56
+ Object.entries(merged)
57
+ .map(([k, v]) => `${k}=${v}`)
58
+ .join("\n") +
59
+ "\n";
60
+ fs.writeFileSync(file, body, { mode: 0o600 });
61
+ fs.chmodSync(file, 0o600);
62
+ return file;
63
+ }
64
+
65
+ /** Every profile's name, passport id and port; never a secret. */
66
+ export function listProfiles(env = process.env) {
67
+ const dir = profilesDir(env);
68
+ if (!fs.existsSync(dir)) return [];
69
+ return fs
70
+ .readdirSync(dir)
71
+ .filter((name) => PROFILE_NAME_RE.test(name))
72
+ .sort()
73
+ .map((name) => {
74
+ const v = readProfile(name, env) ?? {};
75
+ return { name, passportId: v.PASSPORT_ID ?? "", port: v.SIDECAR_PORT ?? "" };
76
+ });
77
+ }
78
+
79
+ /**
80
+ * The profile this process was asked to use: `--profile <name>` on the command line,
81
+ * or PASSCONTROL_PROFILE from the OPERATOR's shell. Read before any config file is
82
+ * merged into the environment, so a project's `.passcontrol` cannot choose which
83
+ * identity this machine speaks as.
84
+ */
85
+ export function selectedProfile(argv = process.argv, env = process.env) {
86
+ for (let i = 0; i < argv.length; i++) {
87
+ const arg = argv[i];
88
+ if (arg === "--profile") return argv[i + 1] ?? "";
89
+ if (arg.startsWith("--profile=")) return arg.slice("--profile=".length);
90
+ }
91
+ return env.PASSCONTROL_PROFILE ?? null;
92
+ }
@@ -11,6 +11,8 @@ export const WORKSPACE_EXPORT_PROTOCOL: ProtocolRange;
11
11
  // Signed spend statements. Its own version line, and part of CLIENT_PROTOCOLS
12
12
  // since the format was published — see the note in protocols.mjs.
13
13
  export const STATEMENT_PROTOCOL: ProtocolRange;
14
+ // Session seals. Its own line; in CLIENT_PROTOCOLS since the seal route shipped.
15
+ export const SESSION_PROTOCOL: ProtocolRange;
14
16
  export const CLIENT_PROTOCOLS: Readonly<Record<string, ProtocolRange>>;
15
17
  export function compareProtocolRanges(client: ProtocolRange, server: unknown): "compatible" | "partial" | "update-required" | "unavailable";
16
18
  export function compareProtocolSets(serverProtocols: unknown): {
package/cli/protocols.mjs CHANGED
@@ -3,7 +3,9 @@
3
3
  // runtime source; its declaration lets Edge TypeScript import the same values.
4
4
  export const CONTROL_API_PROTOCOL = { minimum: 1, maximum: 1 };
5
5
  export const GATEWAY_API_PROTOCOL = { minimum: 1, maximum: 1 };
6
- export const RECEIPT_PROTOCOL = { minimum: 1, maximum: 2 };
6
+ // 3 (Bet D, 2026-10-10): a WORKER's receipt, auth.kind "delegated". Moved so a verifier
7
+ // that predates delegation refuses it as too new instead of rendering it as passport-signed.
8
+ export const RECEIPT_PROTOCOL = { minimum: 1, maximum: 3 };
7
9
  export const AGENT_TOKEN_PROTOCOL = { minimum: 1, maximum: 1 };
8
10
  export const WORKSPACE_EXPORT_PROTOCOL = { minimum: 1, maximum: 1 };
9
11
 
@@ -29,6 +31,19 @@ export const WORKSPACE_EXPORT_PROTOCOL = { minimum: 1, maximum: 1 };
29
31
  */
30
32
  export const STATEMENT_PROTOCOL = { minimum: 1, maximum: 1 };
31
33
 
34
+ /**
35
+ * Session seals (`passcontrol-session+jws`): one signed commitment over every
36
+ * receipt in one working session. Its own version line for the statement's
37
+ * reason: a seal carries `v`, and gating it on another artifact's maximum would
38
+ * let a newer seal through a verifier that only understands v1.
39
+ *
40
+ * In CLIENT_PROTOCOLS since the seal route (/api/control/v1/sessions/{id}/seal)
41
+ * shipped with it. KNOWN CONSEQUENCE, the statement's: this CLI reports a gateway
42
+ * that predates seals as "unavailable", which is true — `verify session` has
43
+ * nothing to verify there — and the release note must say so.
44
+ */
45
+ export const SESSION_PROTOCOL = { minimum: 1, maximum: 1 };
46
+
32
47
  export const CLIENT_PROTOCOLS = Object.freeze({
33
48
  control_api: CONTROL_API_PROTOCOL,
34
49
  gateway_api: GATEWAY_API_PROTOCOL,
@@ -36,6 +51,7 @@ export const CLIENT_PROTOCOLS = Object.freeze({
36
51
  agent_token: AGENT_TOKEN_PROTOCOL,
37
52
  workspace_export: WORKSPACE_EXPORT_PROTOCOL,
38
53
  statement: STATEMENT_PROTOCOL,
54
+ session: SESSION_PROTOCOL,
39
55
  });
40
56
 
41
57
  const validRange = (value) =>