@veda-hq/niyam 0.6.26 → 0.7.1

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 CHANGED
@@ -157,6 +157,13 @@ In auto mode the classifier refuses those calls unless the repo's
157
157
  `mcp__ccd_pr__get_status` and `mcp__ccd_pr__set_monitor` to its
158
158
  `permissions.allow`, and `doctor` warns under "This repo" (`▲`) about each
159
159
  one an onboarded repo's file lacks. They reach the app only, not GitHub.
160
+ Claude Code applies deny before allow, so where the file's
161
+ `permissions.deny` matches one of the tools (by its name, `mcp__ccd_pr`,
162
+ `mcp__ccd_pr__*` or another glob after `mcp__ccd_pr__`, `mcp__*` or `*`),
163
+ `onboard` adds no rule for it and says so in its plan, and `doctor` marks it
164
+ denied on purpose (`✓`). A group denied whole leaves nothing to fix; in a
165
+ group denied in part, `doctor` still warns (`▲`) about each other rule the
166
+ file lacks.
160
167
 
161
168
  Before each Bash command, the client's PreToolUse hook runs `niyam
162
169
  guard`: a command running `gh` or a git command that reaches a remote (push,
@@ -187,7 +194,10 @@ allows it, so `onboard` adds `mcp__claude-artifacts__publish_version`,
187
194
  `mcp__claude-artifacts__edit_version` to its `permissions.allow` (none
188
195
  where `mcp__claude-artifacts` or `mcp__claude-artifacts__*` allows the whole
189
196
  server), and `doctor` warns (`▲`) about each one an onboarded repo's file
190
- lacks. A new page is private to its owner; a republish to a page already
197
+ lacks. A repo that publishes its pages another way may deny the artifacts
198
+ server on purpose. Where the file's `permissions.deny` matches one of the
199
+ three, as for the Auto-fix rules above, `onboard` adds no rule for it and
200
+ its plan says so, and `doctor` marks it denied on purpose (`✓`). A new page is private to its owner; a republish to a page already
191
201
  shared changes what its readers see, with no prompt. A body the guard cannot read in full
192
202
  (a variable, a command substitution other than `cat`) is judged by what it
193
203
  spells out; where that asks the owner, or the body opens with the unknown
@@ -431,7 +441,8 @@ on any platform without a token store, `niyam env` prints the lock alone.
431
441
  `mcp__claude-artifacts__publish_version`, `publish_files` and
432
442
  `edit_version`, which publish the page an ask to the owner links (a
433
443
  rerun adds only the ones missing; a file allowing a whole server gets
434
- none of its rules), and
444
+ none of its rules, and a rule the file's `permissions.deny` overrides is
445
+ left out, the plan saying so), and
435
446
  writes `.github/workflows/niyam.yml`, which calls this repository's
436
447
  shared checks (`.github/workflows/checks.yml`) from two jobs: `niyam`
437
448
  on pull requests and pushes, read-only, and `niyam-weekly` on the
@@ -446,14 +457,18 @@ on any platform without a token store, `niyam env` prints the lock alone.
446
457
  GitHub as the agent, once per claude.ai account. When the agent has no
447
458
  signing key on GitHub titled `niyam cloud signing`, the plan's Claude
448
459
  cloud group also lists one, "signing key for AGENT, on the clipboard":
449
- as its last step, after the pull request opens, `onboard` makes it as
460
+ as its last step, after the pull request opens, `onboard` registers it as
450
461
  `niyam cloud-key` does (below), and "By hand:" starts with the paste
451
- into each cloud environment's variables. The key is the agent's, not the
452
- repository's, so onboarding a second repository finds it and says nothing
453
- about it. A key that fails only warns, leaving the pull request and every
454
- step before it in place, and "By hand:" names `niyam cloud-key <agent>`
455
- instead; so does a run where `cloud-key` would refuse, in a Claude Code
456
- or cloud session. A dry run plans no key. Where the
462
+ into each cloud environment's variables. It makes the key in memory when
463
+ it plans, so the pull request's `.github/niyam.json` pins the key's
464
+ public half among the agent's cloud signing keys, which cloud sessions
465
+ check theirs against (see Claude cloud sessions below). The key is the
466
+ agent's, not the repository's, so onboarding a second repository finds
467
+ it, pins it there and makes none. A key that fails only warns, leaving
468
+ the pull request and every step before it in place; no environment holds
469
+ the key it pins. "By hand:" then names `niyam cloud-key <agent>` and
470
+ another `onboard` run instead; so does a run where `cloud-key` would
471
+ refuse, in a Claude Code or cloud session. A dry run plans no key. Where the
457
472
  repo still has `.github/process-rules/cloud-setup.sh`, which releases up
458
473
  to 0.6.10 wrote beside it, the pull request deletes it, but only where it
459
474
  leaves `.github/niyam/cloud-setup.sh` (one the run could not write, as
@@ -1375,7 +1390,7 @@ address and signed with that key.
1375
1390
  Once `session-start` confirms the login as the agent, it does four things:
1376
1391
 
1377
1392
  - reads the account's id from the same GitHub answer;
1378
- - writes the key to the agent's key file (`~/.ssh/<agent>_signing`, mode 0600) and checks GitHub lists its public half as one of the agent's signing keys;
1393
+ - checks its public half is one of the agent's cloud signing keys the repo's `.github/niyam.json` pins, then writes the key to the agent's key file (`~/.ssh/<agent>_signing`, mode 0600);
1379
1394
  - makes a probe commit object, on no branch, with exactly the settings the session will get;
1380
1395
  - checks that its signature verifies as that key's.
1381
1396
 
@@ -1390,20 +1405,43 @@ makes. `niyam ssh-sign` only signs, so `git log --show-signature` in the
1390
1405
  session cannot check signatures; GitHub does. It also unsets the key's
1391
1406
  variable there, so commands do not carry it in their environment.
1392
1407
 
1408
+ **The pin.** A cloud session cannot ask GitHub which signing keys the agent
1409
+ has: the proxy refuses every `users/…` path, and the session's API calls
1410
+ can reach only the repositories attached to it (veda-hq/niyam#447). So
1411
+ `onboard`, run on your Mac, asks GitHub instead. It writes the agent's
1412
+ cloud signing keys, those titled `niyam cloud signing`, into the settings
1413
+ as `"cloudSigningKeys"`, by agent, without their comments:
1414
+
1415
+ ```json
1416
+ { "owner": "example-owner", "agent": "ExampleBot",
1417
+ "cloudSigningKeys": { "ExampleBot": ["ssh-ed25519 AAAA…"] } }
1418
+ ```
1419
+
1420
+ `session-start` checks the session's key against that list. Each
1421
+ `onboard` run writes it again from GitHub's list, so a key made or deleted
1422
+ since then needs an `onboard` run in each repository the agent works in.
1423
+ The plan names the change ("pin AGENT's cloud signing key"), and a run
1424
+ whose list GitHub does not give leaves the pin as it is. A key the pin
1425
+ still names after it was deleted from GitHub is caught only after the
1426
+ push: its commits fail PR identity until `onboard` runs again.
1427
+
1393
1428
  When any step fails, nothing is set and the commits stay Claude's, which PR
1394
1429
  identity passes. Steps that can fail: no key, one that is not an OpenSSH
1395
- private key or not an ed25519 one with no passphrase, a key GitHub does not
1396
- list, a lookup the proxy refuses, or a probe that does not verify. The
1430
+ private key or not an ed25519 one with no passphrase, settings that pin no
1431
+ cloud signing key for the agent, a key they do not pin, or a probe that
1432
+ does not verify. The
1397
1433
  session's line says why and the session works on as the agent. A commit
1398
1434
  claiming the agent without the agent's signature would fail PR identity, so
1399
1435
  it is all or nothing. Nothing is installed: signing needs no `ssh-keygen`, no
1400
1436
  network and no root, so no Setup script line either.
1401
1437
 
1402
1438
  `niyam onboard` makes the key the first time it runs for an agent that has
1403
- none (see Adopting above), so all that is left is the paste. To make one
1404
- yourself, as when the line was lost, run `niyam cloud-key [agent]` in your own
1405
- terminal on the Mac `niyam machine` set up for the agent (`--yes` skips its
1406
- one question). One line serves every cloud environment the agent works in.
1439
+ none (see Adopting above), and its pull request pins it, so all that is
1440
+ left is the paste. To make one yourself, as when the line was lost, run
1441
+ `niyam cloud-key [agent]` in your own terminal on the Mac `niyam machine`
1442
+ set up for the agent (`--yes` skips its one question), then `niyam onboard`
1443
+ in each repository the agent works in, which pins it; `cloud-key` says so.
1444
+ One line serves every cloud environment the agent works in.
1407
1445
  `onboard` and `cloud-key` make the key alike, in three steps:
1408
1446
 
1409
1447
  - makes a new ed25519 key in memory, with niyam's own code rather than `ssh-keygen`, never writing it to disk; it is for the agent's cloud sessions alone, apart from the Mac's signing key, so it can be revoked on its own;
@@ -1428,7 +1466,8 @@ command its sessions run. Claude's settings warn against keeping secrets
1428
1466
  there. Whoever holds the key can sign commits that GitHub shows as Verified
1429
1467
  for the agent, though pushing still needs the agent's GitHub connection,
1430
1468
  which PR identity checks. To revoke the key, delete it from the agent's
1431
- signing keys.
1469
+ signing keys, then run `niyam onboard` in each repository, which drops it
1470
+ from the pin.
1432
1471
 
1433
1472
  **Trailers and hooks.** The cloud image's git config sets Claude's identity
1434
1473
  and signing and nothing else: no `core.hooksPath`, no hooks, no trailers.
@@ -1624,7 +1663,7 @@ tag and the commit. Install the attached package on each machine with pnpm,
1624
1663
  once; nothing is built on install:
1625
1664
 
1626
1665
  ```bash
1627
- pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.6.26/veda-hq-niyam-0.6.26.tgz
1666
+ pnpm add -g https://github.com/veda-hq/niyam/releases/download/v0.7.1/veda-hq-niyam-0.7.1.tgz
1628
1667
  ```
1629
1668
 
1630
1669
  The package puts one command on `PATH`, `niyam`. Since P-57 a release
package/dist/agent.js CHANGED
@@ -49,14 +49,25 @@ export function anyLogin(logins, login) {
49
49
  export function either(logins) {
50
50
  return logins.length < 2 ? (logins[0] ?? '') : `${logins.slice(0, -1).join(', ')} or ${logins.at(-1)}`;
51
51
  }
52
+ /** The settings' key for each agent's pinned cloud signing keys. */
53
+ export const CLOUD_SIGNING_KEYS = 'cloudSigningKeys';
54
+ /** The cloud signing keys `settings` pin for `login`, any case; none when they pin none. */
55
+ export function pinnedCloudKeys(settings, login) {
56
+ const pins = settings.cloudSigningKeys ?? {};
57
+ return Object.entries(pins).find(([agent]) => sameLogin(login, agent))?.[1] ?? [];
58
+ }
52
59
  /** Reads and checks the settings file at `root`; throws with the reason. */
53
60
  export function loadSettings(sys, root) {
54
- const name = SETTINGS_PATH;
55
- const path = `${root}/${name}`;
61
+ const path = `${root}/${SETTINGS_PATH}`;
56
62
  if (!sys.exists(path)) {
57
63
  throw new Error(`${SETTINGS_PATH} not found in ${root}`);
58
64
  }
59
- const raw = JSON.parse(sys.read(path));
65
+ return settingsIn(sys.read(path));
66
+ }
67
+ /** Reads and checks the settings file's text, `text`; throws with the reason. */
68
+ export function settingsIn(text) {
69
+ const name = SETTINGS_PATH;
70
+ const raw = JSON.parse(text);
60
71
  const owners = logins(raw, 'owner', name);
61
72
  const agents = logins(raw, 'agent', name);
62
73
  const both = owners.find((owner) => anyLogin(agents, owner));
@@ -64,7 +75,28 @@ export function loadSettings(sys, root) {
64
75
  throw new Error(`${name}: ${both} is named as both owner and agent; they must be different accounts`);
65
76
  }
66
77
  const approvals = approvalsIn(raw, name);
67
- return { owners, agents, ...(approvals === undefined ? {} : { approvals }) };
78
+ const cloudSigningKeys = cloudSigningKeysIn(raw, name);
79
+ return { owners, agents, ...(approvals === undefined ? {} : { approvals }), ...(cloudSigningKeys === undefined ? {} : { cloudSigningKeys }) };
80
+ }
81
+ /** An OpenSSH public key as "type body", as `onboard` pins one. */
82
+ const PUBLIC_KEY = /^(?:ssh-ed25519|ssh-rsa|ecdsa-sha2-nistp(?:256|384|521)|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com) [A-Za-z0-9+/]+={0,2}$/;
83
+ /** The cloud signing keys the settings pin, by agent, or undefined when they pin none; anything else is refused. */
84
+ function cloudSigningKeysIn(raw, file) {
85
+ const value = typeof raw === 'object' && raw !== null ? raw[CLOUD_SIGNING_KEYS] : undefined;
86
+ if (value === undefined)
87
+ return undefined;
88
+ const refused = `${file}: "${CLOUD_SIGNING_KEYS}" must map each agent's login to a list of OpenSSH public keys, "type body", as niyam onboard writes it`;
89
+ if (typeof value !== 'object' || value === null || Array.isArray(value))
90
+ throw new Error(refused);
91
+ const entries = Object.entries(value);
92
+ if (!entries.every(([login, keys]) => LOGIN.test(login) && Array.isArray(keys) && keys.every((key) => typeof key === 'string' && PUBLIC_KEY.test(key)))) {
93
+ throw new Error(refused);
94
+ }
95
+ // Logins are case-insensitive: one agent named twice would leave which pin counts to the file's order.
96
+ const twice = entries.find(([login], i) => entries.findIndex(([other]) => sameLogin(login, other)) !== i);
97
+ if (twice)
98
+ throw new Error(`${file}: "${CLOUD_SIGNING_KEYS}" names ${twice[0]} twice, in any case; keep one entry for each agent`);
99
+ return Object.fromEntries(entries);
68
100
  }
69
101
  /** The Approvals issue the settings name as `"approvals": N`, or undefined when they name none; anything but an issue number is refused. */
70
102
  function approvalsIn(raw, file) {
package/dist/cloud-key.js CHANGED
@@ -1,4 +1,4 @@
1
- import { API, account, agentFrom, checkToken, keyBody, signingKeys, tokenInfo } from './agent.js';
1
+ import { API, SETTINGS_PATH, account, agentFrom, checkToken, keyBody, signingKeys, tokenInfo } from './agent.js';
2
2
  import { SIGNING_KEY_VAR } from './cloud.js';
3
3
  import { CLAUDE_CODE_WEB } from './onboard.js';
4
4
  import { agentSession } from './push-identity.js';
@@ -75,7 +75,18 @@ export async function cloudKey(sys, io, args = []) {
75
75
  return 1;
76
76
  }
77
77
  }
78
- return makeCloudKey(sys, io, agent, token, { others, paste: true });
78
+ const made = await makeCloudKey(sys, io, agent, token, { others, paste: true });
79
+ if (made === 0)
80
+ io.out(` ${repinLine(agent)}`);
81
+ return made;
82
+ }
83
+ /**
84
+ * What a key made outside onboard still needs: a cloud session checks the key
85
+ * against the ones the repo's settings pin, since its proxy cannot read the
86
+ * agent's list on GitHub (#447), and onboard writes the pin.
87
+ */
88
+ export function repinLine(agent) {
89
+ return `Then run niyam onboard in each repository ${agent} works in: it pins the key in ${SETTINGS_PATH}, which cloud sessions check it against.`;
79
90
  }
80
91
  /**
81
92
  * Why cloud-key cannot run here, or undefined: in an agent session or a cloud
@@ -100,25 +111,25 @@ export function pasteLines(agent, where = "the cloud environment's") {
100
111
  * one line, the key never printed. A Ctrl-C once it is registered deletes it
101
112
  * from GitHub again. `others` are the agent's cloud signing keys GitHub
102
113
  * already lists, named for the owner to delete once unused; `paste` says what
103
- * to do with the line, for a caller that does not say it itself. 0 once the
104
- * line is on the clipboard.
114
+ * to do with the line, for a caller that does not say it itself. `key` is
115
+ * one made already, as onboard makes it to pin it in the pull request before
116
+ * it is registered (#447). 0 once the line is on the clipboard.
105
117
  */
106
- export async function makeCloudKey(sys, io, agent, token, { others = [], paste = false } = {}) {
118
+ export async function makeCloudKey(sys, io, agent, token, { others = [], paste = false, key = newKey() } = {}) {
107
119
  let interrupted = false;
108
120
  const off = sys.onInterrupt(() => {
109
121
  interrupted = true;
110
122
  });
111
123
  try {
112
- return await makeAndRegister(sys, io, { agent, token, others, paste }, () => interrupted);
124
+ return await makeAndRegister(sys, io, { agent, token, others, paste, key }, () => interrupted);
113
125
  }
114
126
  finally {
115
127
  off();
116
128
  }
117
129
  }
118
130
  /** Makes the key, registers it, and puts it on the clipboard; each step one line. */
119
- async function makeAndRegister(sys, io, { agent, token, others, paste }, interrupted) {
131
+ async function makeAndRegister(sys, io, { agent, token, others, paste, key }, interrupted) {
120
132
  const comment = `${agent} cloud signing`;
121
- const key = newKey();
122
133
  const publicKey = `${publicLine(key)} ${comment}`;
123
134
  const line = `${SIGNING_KEY_VAR}=${Buffer.from(privateKeyText(key, comment)).toString('base64')}`;
124
135
  const posted = await sys.http(`${API}/user/ssh_signing_keys`, { method: 'POST', token, body: { title: CLOUD_KEY_TITLE, key: publicKey } });
@@ -177,8 +188,10 @@ export async function listedKeys(sys, agent, token) {
177
188
  return { problem: `GitHub answered HTTP ${status} when asked for ${agent}'s signing keys` };
178
189
  return {
179
190
  keys: json.flatMap((entry) => {
180
- const { id, title, created_at: created } = (entry ?? {});
181
- return typeof id === 'number' ? [{ id, title: typeof title === 'string' ? title : '', created: typeof created === 'string' ? created : '' }] : [];
191
+ const { id, title, created_at: created, key } = (entry ?? {});
192
+ return typeof id === 'number'
193
+ ? [{ id, title: typeof title === 'string' ? title : '', created: typeof created === 'string' ? created : '', key: typeof key === 'string' ? keyBody(key) : '' }]
194
+ : [];
182
195
  }),
183
196
  };
184
197
  }
package/dist/cloud.js CHANGED
@@ -1,4 +1,4 @@
1
- import { API, BASE_ENV, authorVars, configVars, isNoToken, keyBody, pathsFor, signingConfig } from './agent.js';
1
+ import { API, BASE_ENV, CLOUD_SIGNING_KEYS, SETTINGS_PATH, authorVars, configVars, isNoToken, pathsFor, signingConfig } from './agent.js';
2
2
  import { SSH_SIGN, signerScript } from './ssh-sign.js';
3
3
  import { commitSignature, publicLine, readPrivateKey, signatureProblem } from './sshsig.js';
4
4
  import { CLAUDE_CODE_WEB, SETUP_FIRST, workflowPins } from './onboard.js';
@@ -51,13 +51,16 @@ const PROBE_MESSAGE = 'niyam: a probe of the agent\'s signing, never on a branch
51
51
  * ssh-keygen, #425, and installing one costs every session time and needs the
52
52
  * network). All of them or none, since a commit that claims the agent
53
53
  * must be Verified as the agent (PR identity) and a signing setup that fails
54
- * breaks every commit: each is given only when the key is one GitHub lists
55
- * for the agent and a probe commit signed with exactly these settings, in
56
- * the clone at `root`, verifies as that key's. The probe is an object on no
57
- * branch, which git's housekeeping drops. Otherwise why not, and the session
58
- * keeps the cloud image's identity.
54
+ * breaks every commit: each is given only when the key is one of `pinned`,
55
+ * the agent's cloud signing keys the repo's settings pin, and a probe commit
56
+ * signed with exactly these settings, in the clone at `root`, verifies as
57
+ * that key's. The pin stands in for GitHub's list of the agent's signing
58
+ * keys, which `onboard` read on the owner's Mac: the session's proxy refuses
59
+ * every `users/…` path (#447). The probe is an object on no branch, which
60
+ * git's housekeeping drops. Otherwise why not, and the session keeps the
61
+ * cloud image's identity.
59
62
  */
60
- export async function cloudSigning(sys, root, login, id) {
63
+ export function cloudSigning(sys, root, login, id, pinned) {
61
64
  const given = sys.env[SIGNING_KEY_VAR]?.trim();
62
65
  if (!given)
63
66
  return { problem: `the cloud environment's variables have no ${SIGNING_KEY_VAR}, ${login}'s cloud signing key (niyam's README, "Claude cloud sessions", says how to add one)` };
@@ -71,11 +74,12 @@ export async function cloudSigning(sys, root, login, id) {
71
74
  if ('problem' in parsed)
72
75
  return { problem: `${SIGNING_KEY_VAR} cannot be used: ${parsed.problem}` };
73
76
  const body = publicLine(parsed);
74
- const listed = await listedSigningKeys(sys, login);
75
- if ('problem' in listed)
76
- return listed;
77
- if (!listed.keys.includes(body))
78
- return { problem: `GitHub does not list ${SIGNING_KEY_VAR}'s public half as one of ${login}'s signing keys` };
77
+ const pin = `${SETTINGS_PATH}'s "${CLOUD_SIGNING_KEYS}"`;
78
+ const repin = `niyam onboard on the owner's Mac pins the ones GitHub lists`;
79
+ if (pinned.length === 0)
80
+ return { problem: `${pin} pins no cloud signing key for ${login}, and this session cannot ask GitHub for ${login}'s signing keys; ${repin}` };
81
+ if (!pinned.includes(body))
82
+ return { problem: `${SIGNING_KEY_VAR}'s public half is not one of the cloud signing keys ${pin} pins for ${login}; ${repin}` };
79
83
  const { dir, key } = pathsFor(sys.home, login);
80
84
  const pub = `${key}.pub`;
81
85
  const signer = `${dir}/${SSH_SIGN}`;
@@ -96,25 +100,6 @@ export async function cloudSigning(sys, root, login, id) {
96
100
  }
97
101
  const PEM_BEGIN = '-----BEGIN OPENSSH PRIVATE KEY-----';
98
102
  const PEM_END = '-----END OPENSSH PRIVATE KEY-----';
99
- /** The signing keys GitHub's public list names for `login`, asked through the proxy, or why they cannot be had. */
100
- async function listedSigningKeys(sys, login) {
101
- let answer;
102
- try {
103
- answer = await sys.http(`${API}/users/${encodeURIComponent(login)}/ssh_signing_keys?per_page=100`, { token: cloudToken(sys) });
104
- }
105
- catch (error) {
106
- // fail-open: the session keeps the image's identity, which PR identity passes, and says why.
107
- return { problem: `GitHub could not be asked for ${login}'s signing keys (${messageOf(error)})` };
108
- }
109
- if (answer.status !== 200 || !Array.isArray(answer.json))
110
- return { problem: `GitHub answered HTTP ${answer.status} when asked for ${login}'s signing keys` };
111
- return {
112
- keys: answer.json.flatMap((entry) => {
113
- const key = entry?.key;
114
- return typeof key === 'string' ? [keyBody(key)] : [];
115
- }),
116
- };
117
- }
118
103
  /**
119
104
  * Makes a commit object on no branch with the environment `vars` give, and
120
105
  * checks its signature is the agent key's, `publicKey`, in git's namespace,
package/dist/doctor.js CHANGED
@@ -8,7 +8,7 @@ import { closing, findingLines, heading, painter, tilde } from './layout.js';
8
8
  import { exposure, exposureFindings, movedFindings, readDeclined, setAside } from './lockout.js';
9
9
  import { CLOUD_SETUP_PATH, HOOKS_PATH, SARATHI_PATH } from './onboard-pull.js';
10
10
  import { leftoverDir, leftoverToken } from './machine.js';
11
- import { BOARD_SECRETS, GUARD_COMMAND, HOOK_COMMAND, OLDER_GUARD_COMMANDS, OLDER_HOOK_COMMANDS, missingArtifactRules, missingAutoFixRules, sarathiRunner } from './onboard.js';
11
+ import { BOARD_SECRETS, GUARD_COMMAND, HOOK_COMMAND, OLDER_GUARD_COMMANDS, OLDER_HOOK_COMMANDS, ARTIFACT_RULES, AUTO_FIX_RULES, artifactRuleNeeds, autoFixRuleNeeds, sarathiRunner } from './onboard.js';
12
12
  import { secretNames } from './secrets.js';
13
13
  import { isOrganisation } from './owner-login.js';
14
14
  import { leftBehind } from './owner-step.js';
@@ -264,7 +264,8 @@ function twiceFindings(sys) {
264
264
  * Which of onboard's Auto-fix and artifact rules the repo's
265
265
  * `.claude/settings.json` lacks, so the auto-mode classifier refuses an agent
266
266
  * session turning Auto-fix on, or publishing the page an ask to the owner
267
- * links: checked in an onboarded repo whose file doctor can read.
267
+ * links: checked in an onboarded repo whose file doctor can read. A rule the
268
+ * file's `permissions.deny` overrides is denied on purpose, not missing.
268
269
  */
269
270
  function allowFindings(sys) {
270
271
  let settings;
@@ -279,11 +280,22 @@ function allowFindings(sys) {
279
280
  // Outside a clone, or a file doctor cannot read: onboard says what is wrong with it.
280
281
  return [];
281
282
  }
282
- const missing = missingAutoFixRules(settings);
283
- const unpublished = missingArtifactRules(settings);
284
283
  return [
285
- ...(missing.length === 0 ? [] : [{ mark: '▲', text: `${HOOKS_PATH} does not allow ${missing.join(', ')}, so agent sessions cannot turn Auto-fix on`, fix: ONBOARD }]),
286
- ...(unpublished.length === 0 ? [] : [{ mark: '▲', text: `${HOOKS_PATH} does not allow ${unpublished.join(', ')}, so agent sessions cannot publish the page an ask to the owner links`, fix: ONBOARD }]),
284
+ ...groupFindings(autoFixRuleNeeds(settings), AUTO_FIX_RULES, 'agent sessions cannot turn Auto-fix on', 'agent sessions do not turn Auto-fix on'),
285
+ ...groupFindings(artifactRuleNeeds(settings), ARTIFACT_RULES, 'agent sessions cannot publish the page an ask to the owner links', 'agent sessions do not publish pages'),
286
+ ];
287
+ }
288
+ /**
289
+ * One group's findings: ▲ for the rules it lacks, and ✓ for those its deny
290
+ * rules override, which the owner chose and onboard leaves out, so nothing
291
+ * there is to fix. A whole group denied says what sessions then do not do;
292
+ * a part of one names the tools denied, since the others still work.
293
+ */
294
+ function groupFindings(needs, rules, cannot, chosen) {
295
+ const so = needs.denied.length === rules.length ? chosen : `agent sessions do not use ${needs.denied.join(', ')}`;
296
+ return [
297
+ ...(needs.missing.length === 0 ? [] : [{ mark: '▲', text: `${HOOKS_PATH} does not allow ${needs.missing.join(', ')}, so ${cannot}`, fix: ONBOARD }]),
298
+ ...(needs.denied.length === 0 ? [] : [{ mark: '✓', text: `${HOOKS_PATH} denies ${needs.deniedBy.join(', ')} on purpose, so ${so}` }]),
287
299
  ];
288
300
  }
289
301
  /** Prints the findings, grouped, and closes; exit 1 when any is broken. */
package/dist/onboard.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { AGENT_VAR, CLI, CONFIG_DIR, PRODUCT } from './names.js';
2
- import { API, BASE_ENV, SETTINGS_PATH, account, agentHere, agentIn, agentsSetUp, anyLogin, checkToken, either, isLogin, keyPairProblem, loadSettings, pathsFor, readToken, repoAt, sameLogin, sessionEnv, tokenInfo, } from './agent.js';
2
+ import { API, BASE_ENV, CLOUD_SIGNING_KEYS, SETTINGS_PATH, account, agentHere, agentIn, agentsSetUp, anyLogin, checkToken, either, isLogin, keyPairProblem, loadSettings, pathsFor, readToken, repoAt, sameLogin, sessionEnv, settingsIn, tokenInfo, } from './agent.js';
3
3
  import { setUpBoard } from './board.js';
4
4
  import { BOARD_SECRETS, boardAppSteps, setUpBoardApp } from './board-app.js';
5
5
  import { agentSession } from './push-identity.js';
@@ -11,6 +11,7 @@ import { DEFAULT_SCHEDULE, FEATURES, FIGMA_FILE_KEY, NEEDS_ISSUE_TYPES, features
11
11
  import { CLOUD_SETUP_PATH, HOOKS_PATH, LEFTOVER_CLOUD_SETUP_PATH, ONBOARD_BRANCH, SARATHI_PATH, WORKFLOW_PATH, autoMerge, mergeQueue, openPull, remoteFile, } from './onboard-pull.js';
12
12
  import { SIGNING_KEY_VAR, cloudRepoScript, cloudScriptVersion, releaseSha256 } from './cloud.js';
13
13
  import { CLOUD_KEY_TITLE, cloudKeyRefusal, listedKeys, makeCloudKey, pasteLines } from './cloud-key.js';
14
+ import { newKey, publicLine } from './sshsig.js';
14
15
  import { detail } from './doc-numbers.js';
15
16
  import { tagOnMain } from './release-tag.js';
16
17
  import { secretNames, setSecret } from './secrets.js';
@@ -224,22 +225,61 @@ export const ARTIFACT_RULES = ['mcp__claude-artifacts__publish_version', 'mcp__c
224
225
  /** The rules that allow every tool of the artifacts server, ARTIFACT_RULES among them. */
225
226
  const ARTIFACT_SERVER_RULES = ['mcp__claude-artifacts', 'mcp__claude-artifacts__*'];
226
227
  /**
227
- * Which of `rules` a settings file's `permissions.allow` lacks, in their
228
- * order: none when it allows the whole server, by one of `server`.
228
+ * Whether deny rule `by` matches MCP tool `tool` of the server named `bare`
229
+ * (`mcp__<server>`), as Claude Code's permissions page says rules match: the
230
+ * tool's own name, the bare server, `*` and `mcp__*` (every tool, every MCP
231
+ * tool), and a glob in the tool name after a literal `mcp__<server>__`, such
232
+ * as `mcp__<server>__*` or `mcp__<server>__publish_*`. A glob in the server's
233
+ * own name the page does not describe, so it matches nothing here.
229
234
  */
230
- function missingRules(settings, rules, server) {
231
- const allow = settings?.permissions?.allow;
232
- if (Array.isArray(allow) && allow.some((rule) => server.includes(rule)))
233
- return [];
234
- return rules.filter((rule) => !Array.isArray(allow) || !allow.includes(rule));
235
+ function deniesTool(by, tool, bare) {
236
+ if (by === tool || by === bare || by === '*' || by === 'mcp__*')
237
+ return true;
238
+ const prefix = `${bare}__`;
239
+ if (!by.startsWith(prefix) || !by.includes('*') || !tool.startsWith(prefix))
240
+ return false;
241
+ const glob = by.slice(prefix.length).split('*').map((part) => part.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('.*');
242
+ return new RegExp(`^${glob}$`).test(tool.slice(prefix.length));
235
243
  }
236
- /** Which of AUTO_FIX_RULES a settings file's `permissions.allow` lacks. */
237
- export function missingAutoFixRules(settings) {
238
- return missingRules(settings, AUTO_FIX_RULES, PR_SERVER_RULES);
244
+ /**
245
+ * Which of `rules` a settings file lacks, in their order: none lacks when
246
+ * its `permissions.allow` allows the whole server, by one of `server`. Claude
247
+ * Code applies deny before allow, so a rule that `permissions.deny` overrides
248
+ * (`deniesTool`) is denied, not missing: an allow rule for it would do
249
+ * nothing. A deny or allow that is not an array names nothing.
250
+ */
251
+ function ruleNeeds(settings, rules, server) {
252
+ const permissions = settings?.permissions;
253
+ const listed = (value) => (Array.isArray(value) ? value.filter((rule) => typeof rule === 'string') : []);
254
+ const allow = listed(permissions?.allow);
255
+ const deny = listed(permissions?.deny);
256
+ const bare = server[0];
257
+ const deniedBy = deny.filter((by) => rules.some((rule) => deniesTool(by, rule, bare)));
258
+ const denied = rules.filter((rule) => deny.some((by) => deniesTool(by, rule, bare)));
259
+ if (allow.some((rule) => server.includes(rule)))
260
+ return { missing: [], denied, leftOut: [], deniedBy, leftOutBy: [] };
261
+ const lacking = rules.filter((rule) => !allow.includes(rule));
262
+ const leftOut = lacking.filter((rule) => denied.includes(rule));
263
+ const leftOutBy = deniedBy.filter((by) => leftOut.some((rule) => deniesTool(by, rule, bare)));
264
+ return { missing: lacking.filter((rule) => !denied.includes(rule)), denied, leftOut, deniedBy, leftOutBy };
239
265
  }
240
- /** Which of ARTIFACT_RULES a settings file's `permissions.allow` lacks. */
241
- export function missingArtifactRules(settings) {
242
- return missingRules(settings, ARTIFACT_RULES, ARTIFACT_SERVER_RULES);
266
+ /** Which of AUTO_FIX_RULES a settings file lacks, and which its deny rules override. */
267
+ export function autoFixRuleNeeds(settings) {
268
+ return ruleNeeds(settings, AUTO_FIX_RULES, PR_SERVER_RULES);
269
+ }
270
+ /** Which of ARTIFACT_RULES a settings file lacks, and which its deny rules override. */
271
+ export function artifactRuleNeeds(settings) {
272
+ return ruleNeeds(settings, ARTIFACT_RULES, ARTIFACT_SERVER_RULES);
273
+ }
274
+ /**
275
+ * What a group's left-out rules come to, in a line for onboard's plan: the
276
+ * group's name when the deny leaves all of it out, else the rules it does.
277
+ * A denied rule the file allows already is not left out, and goes unsaid.
278
+ */
279
+ function deniedLines(needs, rules, group) {
280
+ if (needs.leftOut.length === 0)
281
+ return [];
282
+ return [`${needs.leftOut.length === rules.length ? group : needs.leftOut.join(', ')} left out: ${HOOKS_PATH} denies ${needs.leftOutBy.join(', ')}`];
243
283
  }
244
284
  /** The hook commands older releases wrote, which onboard replaces with this release's. */
245
285
  export const OLDER_HOOK_COMMANDS = [
@@ -832,6 +872,8 @@ function handlersOf(sarathi, event) {
832
872
  * entry an older release wrote swapped where it stands, a missing one added,
833
873
  * the lock's variables set in `env`, and REVIEW_THREAD_RULE, AUTO_FIX_RULES and ARTIFACT_RULES allowed. Every edit is made in the text, so
834
874
  * the rest of the file keeps its layout. Says what changed, for the question.
875
+ * A rule the file's `permissions.deny` overrides is not allowed, since the
876
+ * allow would do nothing; `denied` says which, for the plan, only when any is.
835
877
  *
836
878
  * Where the project keeps `.claude/sarathi.json` (`sarathiBefore`) and the
837
879
  * settings run sarathi for an event, with a matcher that lets niyam's hook
@@ -849,6 +891,7 @@ export function claudeSettings(before, sarathiBefore) {
849
891
  let moved = false;
850
892
  let timed = false;
851
893
  const labels = [];
894
+ const denied = [];
852
895
  const parsed = () => JSON.parse(text);
853
896
  const first = parsed();
854
897
  if (typeof first !== 'object' || first === null || Array.isArray(first))
@@ -984,18 +1027,22 @@ export function claudeSettings(before, sarathiBefore) {
984
1027
  text = appendToArray(text, ['permissions'], 'allow', REVIEW_THREAD_RULE);
985
1028
  changes.push('allow niyam review-thread without a prompt, so agent sessions answer review threads on their own pull requests');
986
1029
  }
987
- const lacking = missingAutoFixRules(parsed());
1030
+ const autoFix = autoFixRuleNeeds(parsed());
1031
+ const lacking = autoFix.missing;
988
1032
  for (const rule of lacking)
989
1033
  text = appendToArray(text, ['permissions'], 'allow', rule);
990
1034
  if (lacking.length > 0) {
991
1035
  changes.push(`allow ${lacking.join(', ')} without a prompt, so agent sessions turn Auto-fix on for their own pull requests`);
992
1036
  }
993
- const unpublished = missingArtifactRules(parsed());
1037
+ const artifacts = artifactRuleNeeds(parsed());
1038
+ const unpublished = artifacts.missing;
994
1039
  for (const rule of unpublished)
995
1040
  text = appendToArray(text, ['permissions'], 'allow', rule);
996
1041
  if (unpublished.length > 0) {
997
1042
  changes.push(`allow ${unpublished.join(', ')} without a prompt, so agent sessions publish the page an ask to the owner links`);
998
1043
  }
1044
+ // A rule the file denies is the owner's choice: an allow rule for it would do nothing, so the plan says so instead.
1045
+ denied.push(...deniedLines(autoFix, AUTO_FIX_RULES, 'Auto-fix rules'), ...deniedLines(artifacts, ARTIFACT_RULES, 'artifact rules'));
999
1046
  // One group's own word, or one word for several, so the plan's line stays short.
1000
1047
  const groups = [review || renamed.replaced > 0 ? 'review rule' : '', lacking.length > 0 ? 'Auto-fix rules' : '', unpublished.length > 0 ? 'artifact rules' : ''].filter(Boolean);
1001
1048
  if (groups.length > 0)
@@ -1004,14 +1051,15 @@ export function claudeSettings(before, sarathiBefore) {
1004
1051
  catch (error) {
1005
1052
  throw new Error(`${HOOKS_PATH}: ${error.message}`);
1006
1053
  }
1054
+ const said = denied.length > 0 ? { denied } : {};
1007
1055
  if (sarathi !== undefined && sarathi.changes.length > 0) {
1008
1056
  if (handlersChanged)
1009
1057
  sarathi.labels.push(`hooks ${handlersChanged}`);
1010
1058
  if (handlersTimed)
1011
1059
  sarathi.labels.push('timeout');
1012
- return { text, changes, labels, sarathi };
1060
+ return { text, changes, labels, ...said, sarathi };
1013
1061
  }
1014
- return { text, changes, labels };
1062
+ return { text, changes, labels, ...said };
1015
1063
  }
1016
1064
  /** Who the run's sign-in is, the owner's likely login; undefined when it failed. */
1017
1065
  async function signedInLogin(signIn) {
@@ -1369,6 +1417,7 @@ export async function onboard(sys, io, args = []) {
1369
1417
  const existing = fileAt(HOOKS_PATH);
1370
1418
  // Worked out before the plan, so a file onboard cannot edit is refused before any question.
1371
1419
  const claude = claudeSettings(existing, fileAt(SARATHI_PATH));
1420
+ warnings.push(...(claude.denied ?? []));
1372
1421
  if (claude.changes.length > 0) {
1373
1422
  pull.push({ label: 'settings.json', detail: existing === undefined ? 'new' : claude.labels.join(', ') });
1374
1423
  change(HOOKS_PATH, claude.text, claude.changes.join('; '));
@@ -1597,7 +1646,7 @@ export async function onboard(sys, io, args = []) {
1597
1646
  // The agent's cloud signing key (#417) is the agent's, not the repository's: one line serves every cloud
1598
1647
  // environment it works in, so onboard makes one only when the agent's own list holds none, and the second repo
1599
1648
  // onboarded leaves it alone. Where cloud-key would refuse, the owner runs it instead.
1600
- const keyByHand = `Once for ${agent}: in your own terminal on your Mac, run niyam cloud-key ${agent}, and paste the line it puts on the clipboard into each Claude cloud environment's variables.`;
1649
+ const keyByHand = `Once for ${agent}: in your own terminal on your Mac, run niyam cloud-key ${agent}, paste the line it puts on the clipboard into each Claude cloud environment's variables, then run niyam onboard here again, which pins the key in ${SETTINGS_PATH}.`;
1601
1650
  const cloudKeys = await listedKeys(sys, agent, token).catch((error) => {
1602
1651
  // fail-open: a list GitHub does not give is warned about below and makes no key.
1603
1652
  return { problem: detail(error) };
@@ -1614,6 +1663,36 @@ export async function onboard(sys, io, args = []) {
1614
1663
  makeKey = true;
1615
1664
  }
1616
1665
  }
1666
+ // A cloud session's proxy cannot read the agent's signing keys (#447), so the settings pin its cloud signing keys
1667
+ // as GitHub lists them now, with the one this run makes: made here, so the pull request pins it, and registered
1668
+ // last, as before. One that then fails to register reaches no clipboard, so no environment holds it; a later run
1669
+ // drops it once GitHub does not list it. A list GitHub does not give leaves the pin as it is.
1670
+ const fresh = makeKey ? newKey() : undefined;
1671
+ if (!('problem' in cloudKeys)) {
1672
+ const keys = [...cloudKeys.keys.filter((one) => one.title === CLOUD_KEY_TITLE && one.key !== '').map((one) => one.key), ...(fresh ? [publicLine(fresh)] : [])];
1673
+ const text = fileAt(SETTINGS_PATH);
1674
+ let pins;
1675
+ try {
1676
+ pins = text === undefined ? undefined : { ...settingsIn(text).cloudSigningKeys };
1677
+ }
1678
+ catch (error) {
1679
+ // fail-open: the pin stays as it is, and the plan says why.
1680
+ warnings.push(`cloud signing keys not pinned (${detail(error)})`);
1681
+ }
1682
+ if (text !== undefined && pins !== undefined) {
1683
+ const name = Object.keys(pins).find((login) => sameLogin(login, agent)) ?? agent;
1684
+ if (keys.join('\n') !== (pins[name] ?? []).join('\n')) {
1685
+ if (keys.length > 0)
1686
+ pins[name] = keys;
1687
+ else
1688
+ delete pins[name];
1689
+ const what = keys.length > 0 ? `pin ${agent}'s cloud signing ${keys.length === 1 ? 'key' : 'keys'}, which cloud sessions check theirs against` : `drop ${agent}'s cloud signing keys, which GitHub no longer lists`;
1690
+ // Written where it stands, the rest of the file as it is.
1691
+ change(SETTINGS_PATH, setMember(text, [], CLOUD_SIGNING_KEYS, pins), what);
1692
+ settingsItem(what);
1693
+ }
1694
+ }
1695
+ }
1617
1696
  let pullUrl;
1618
1697
  // Whether the pull request merges itself once its checks pass.
1619
1698
  let merging = false;
@@ -1716,7 +1795,7 @@ export async function onboard(sys, io, args = []) {
1716
1795
  let made = false;
1717
1796
  try {
1718
1797
  ({ ok: made } = await runStep(sys, io, paint, `cloud signing key for ${agent}`, async (out) => {
1719
- const code = await makeCloudKey(sys, out, agent, token);
1798
+ const code = await makeCloudKey(sys, out, agent, token, fresh ? { key: fresh } : {});
1720
1799
  if (code === 130)
1721
1800
  exitCode = 130;
1722
1801
  return code === 0;
@@ -1729,7 +1808,7 @@ export async function onboard(sys, io, args = []) {
1729
1808
  if (made)
1730
1809
  byHand.unshift(`Now: ${SIGNING_KEY_VAR}=… is on the clipboard. ${pasteLines(agent, "each Claude cloud environment's").join(' ')}`);
1731
1810
  else {
1732
- io.err(`onboard: ${agent} has no cloud signing key yet; everything before it is done`);
1811
+ io.err(`onboard: ${agent} has no cloud signing key yet; everything before it is done, and no environment holds the key the pull request pins`);
1733
1812
  byHand.push(keyByHand);
1734
1813
  }
1735
1814
  }
@@ -1,4 +1,4 @@
1
- import { BASE_ENV, agentHere, exportLines, anyLogin, either, loadSettings, lockScript, sameLogin, pathsFor, sessionNames, sessionRecord, sessionFileIs, } from './agent.js';
1
+ import { BASE_ENV, agentHere, exportLines, anyLogin, either, loadSettings, pinnedCloudKeys, lockScript, sameLogin, pathsFor, sessionNames, sessionRecord, sessionFileIs, } from './agent.js';
2
2
  import { AGENT_VAR } from './names.js';
3
3
  import { SIGNING_KEY_VAR, cloudLogin, cloudSigning, cloudToken, ranFromSetup, repoReleases } from './cloud.js';
4
4
  import { CLOUD_SETUP_PATH } from './onboard-pull.js';
@@ -173,7 +173,7 @@ async function cloudStart(sys) {
173
173
  : hook.state === 'outside'
174
174
  ? ` Its pre-push hook ${hook.path} is outside the repository and was not checked, so only the pull request's checks may hold the work rules.`
175
175
  : '';
176
- const signed = await cloudCommits(sys, root, envFile, asked);
176
+ const signed = cloudCommits(sys, root, envFile, asked, pinnedCloudKeys(settings, asked.login));
177
177
  return { line: `niyam: this cloud session works as ${asked.login} on GitHub.${unchecked}${signed}`, agent: asked.login };
178
178
  }
179
179
  /**
@@ -182,13 +182,14 @@ async function cloudStart(sys) {
182
182
  * identity, Claude's: `cloudSigning`'s variables, appended to CLAUDE_ENV_FILE
183
183
  * after the lock is lifted, which reaches every command Claude Code runs and
184
184
  * leaves the clone's git config alone. The key's variable is unset there, so
185
- * commands do not carry it in their environment. A warning only, said after
185
+ * commands do not carry it in their environment. `pinned` are the agent's
186
+ * cloud signing keys the repo's settings pin. A warning only, said after
186
187
  * the line: when any of it fails, the session works on as the agent and its
187
188
  * commits keep the image's identity, which PR identity passes.
188
189
  */
189
- async function cloudCommits(sys, root, envFile, asked) {
190
+ function cloudCommits(sys, root, envFile, asked, pinned) {
190
191
  const keeps = (why) => ` Its commits keep the cloud image's identity, Claude's: ${why}.`;
191
- const signing = await cloudSigning(sys, root, asked.login, asked.id);
192
+ const signing = cloudSigning(sys, root, asked.login, asked.id, pinned);
192
193
  if ('problem' in signing)
193
194
  return keeps(signing.problem);
194
195
  try {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veda-hq/niyam",
3
- "version": "0.6.26",
3
+ "version": "0.7.1",
4
4
  "description": "Work rules for repos that track work in GitHub Issues: setup, agent identity, push and PR checks.",
5
5
  "license": "MIT",
6
6
  "repository": {