@geslar/cli 0.2.0 → 0.3.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
@@ -10,6 +10,18 @@ geslar run -e DB_PASSWORD=geslar://Work/Database/password -- ./start-server.sh
10
10
 
11
11
  The server never sees which vault, item, or field a reference asks for — resolution happens locally, after decrypting on your machine.
12
12
 
13
+ ## MCP server
14
+
15
+ `geslar mcp serve` runs a stdio [MCP](https://modelcontextprotocol.io) server for Claude Code, Claude Desktop, Cursor, and other MCP clients — 6 tools (list vaults/items, whoami, provision-env, run, recent audit) scoped to an [agent profile](https://docs.geslar.app/cli/reference#agent-profiles), gated behind an out-of-band pre-grant (`geslar mcp allow`/`allow-cmd`) for anything that writes or executes. No tool returns a secret value — `run` reports only exit status and line counts, and by default returns no process output at all.
16
+
17
+ ```sh
18
+ geslar unlock --ttl 30m
19
+ geslar agent create my-agent --vault Work
20
+ geslar mcp init my-agent --client claude-code
21
+ ```
22
+
23
+ `geslar mcp init` detects your MCP client and wires up the config for you (never contains a token). It points the config at your globally-installed `geslar` if one is on your PATH (tracking whatever version that is), otherwise at a version-pinned `npx -y @geslar/cli@<version>` — never an unpinned `@latest`. Full reference — all 6 tools, the pre-grant model, and known limitations — at [docs.geslar.app/cli/reference](https://docs.geslar.app/cli/reference).
24
+
13
25
  Full docs: install (including standalone Windows/Linux binaries), quickstart, the `geslar://` reference syntax, agent profiles, and known limitations — see [docs.geslar.app/cli/reference](https://docs.geslar.app/cli/reference) or the `docs/cli/` directory in the [geslar-suite](https://github.com/StudioIT/geslar-suite) repository.
14
26
 
15
27
  ## License
package/dist/index.js CHANGED
@@ -1408,6 +1408,12 @@ var ApiClient = class {
1408
1408
  getAgentWhoami() {
1409
1409
  return this.request("/v1/agents/whoami", { method: "GET" });
1410
1410
  }
1411
+ /** Reachable by an agent bearer (geslar-api Task 2) — scoped to this
1412
+ * principal's own agent.* events only. */
1413
+ getAuditRecent(params = {}) {
1414
+ const qs = params.limit ? `?limit=${encodeURIComponent(String(params.limit))}` : "";
1415
+ return this.request(`/v1/audit${qs}`, { method: "GET" });
1416
+ }
1411
1417
  /**
1412
1418
  * Create an account. All crypto happens in @geslar/core/crypto
1413
1419
  * (prepareRegistration) — this only ships auth_hash + opaque wrapped blobs.
@@ -2148,10 +2154,21 @@ var ApiClient = class {
2148
2154
  getGroupMembers(orgId, gid) {
2149
2155
  return this.request(`/v1/orgs/${encodeURIComponent(orgId)}/groups/${encodeURIComponent(gid)}/members`, { method: "GET" });
2150
2156
  }
2151
- /** F4 Rez 2 Faza 1: collections a group holds a grant on (group-inheritance fan-out). */
2157
+ /** F4 Rez 2 Faza 1: collections a group holds a grant on (group-inheritance fan-out).
2158
+ * F3b-2: response now also carries the group's current allow-capabilities per collection. */
2152
2159
  getGroupCollections(orgId, gid) {
2153
2160
  return this.request(`/v1/orgs/${encodeURIComponent(orgId)}/groups/${encodeURIComponent(gid)}/collections`, { method: "GET" });
2154
2161
  }
2162
+ /** F3b-2: direct-member mirror of getGroupCollections — powers MemberDetailPage's Škrinje tab. */
2163
+ getMemberCollections(orgId, uid) {
2164
+ return this.request(`/v1/orgs/${encodeURIComponent(orgId)}/members/${encodeURIComponent(uid)}/collections`, { method: "GET" });
2165
+ }
2166
+ /** F3b-2: wires the existing admin-listing GET /v1/orgs/:id/collections route
2167
+ * (previously had zero client callers) — used to pick a not-yet-granted
2168
+ * Škrinja when assigning new group/member access. */
2169
+ getOrgCollections(orgId) {
2170
+ return this.request(`/v1/orgs/${encodeURIComponent(orgId)}/collections`, { method: "GET" });
2171
+ }
2155
2172
  addGroupMember(orgId, gid, userId) {
2156
2173
  return this.request(`/v1/orgs/${encodeURIComponent(orgId)}/groups/${encodeURIComponent(gid)}/members`, {
2157
2174
  method: "POST",
@@ -3438,6 +3455,168 @@ async function agentRevokeCommand(name, opts) {
3438
3455
  }
3439
3456
  }
3440
3457
 
3458
+ // src/mcp/grant-store.ts
3459
+ import { randomUUID as randomUUID2, randomBytes as randomBytes3, createHmac, timingSafeEqual } from "node:crypto";
3460
+ var DEFAULT_GRANT_TTL_SEC = 3600;
3461
+ var MAX_GRANT_TTL_SEC = 8 * 3600;
3462
+ var GRANT_NAMESPACE = "mcp-grant";
3463
+ var SIGNING_KEY_NAMESPACE = "mcp-grant-signing-key";
3464
+ async function getOrCreateSigningKey() {
3465
+ const backend = await selectBackend(SIGNING_KEY_NAMESPACE);
3466
+ const existing = await backend.load();
3467
+ if (existing) return Buffer.from(existing, "base64");
3468
+ const key = randomBytes3(32);
3469
+ await backend.save(key.toString("base64"));
3470
+ return key;
3471
+ }
3472
+ function sign(key, payload) {
3473
+ return createHmac("sha256", key).update(payload).digest("base64");
3474
+ }
3475
+ function verifySignature(key, payload, signature) {
3476
+ const expected = sign(key, payload);
3477
+ const a = Buffer.from(expected);
3478
+ const b = Buffer.from(signature);
3479
+ return a.length === b.length && timingSafeEqual(a, b);
3480
+ }
3481
+ async function loadAll2() {
3482
+ const backend = await selectBackend(GRANT_NAMESPACE);
3483
+ const raw = await backend.load();
3484
+ if (!raw) return [];
3485
+ let envelope;
3486
+ try {
3487
+ envelope = JSON.parse(raw);
3488
+ } catch {
3489
+ return [];
3490
+ }
3491
+ if (typeof envelope !== "object" || envelope === null || typeof envelope.payload !== "string" || typeof envelope.signature !== "string") {
3492
+ return [];
3493
+ }
3494
+ const { payload, signature } = envelope;
3495
+ const key = await getOrCreateSigningKey();
3496
+ if (!verifySignature(key, payload, signature)) return [];
3497
+ let grants;
3498
+ try {
3499
+ grants = JSON.parse(payload);
3500
+ } catch {
3501
+ return [];
3502
+ }
3503
+ const now = Date.now();
3504
+ return grants.filter((g) => now - g.createdAt <= g.ttlSec * 1e3);
3505
+ }
3506
+ async function saveAll(grants) {
3507
+ const backend = await selectBackend(GRANT_NAMESPACE);
3508
+ const key = await getOrCreateSigningKey();
3509
+ const payload = JSON.stringify(grants);
3510
+ const signature = sign(key, payload);
3511
+ await backend.save(JSON.stringify({ payload, signature }));
3512
+ }
3513
+ function clampTtl(ttlSec) {
3514
+ const v = ttlSec ?? DEFAULT_GRANT_TTL_SEC;
3515
+ return Math.min(Math.max(v, 1), MAX_GRANT_TTL_SEC);
3516
+ }
3517
+ async function createGrant(partial) {
3518
+ const grants = await loadAll2();
3519
+ const grant = {
3520
+ ...partial,
3521
+ id: randomUUID2(),
3522
+ createdAt: Date.now(),
3523
+ usesRemaining: partial.maxUses
3524
+ };
3525
+ grants.push(grant);
3526
+ await saveAll(grants);
3527
+ return grant;
3528
+ }
3529
+ function createScopeGrant(scope, opts) {
3530
+ return createGrant({ kind: "scope", scope, ttlSec: clampTtl(opts.ttlSec), maxUses: opts.maxUses ?? null });
3531
+ }
3532
+ function createCmdGrant(pattern, opts) {
3533
+ return createGrant({ kind: "cmd", pattern, ttlSec: clampTtl(opts.ttlSec), maxUses: opts.maxUses ?? null });
3534
+ }
3535
+ function listGrants() {
3536
+ return loadAll2();
3537
+ }
3538
+ async function revokeGrant(id) {
3539
+ const grants = await loadAll2();
3540
+ const next = grants.filter((g) => g.id !== id);
3541
+ if (next.length === grants.length) return false;
3542
+ await saveAll(next);
3543
+ return true;
3544
+ }
3545
+ async function revokeAllGrants() {
3546
+ await saveAll([]);
3547
+ }
3548
+
3549
+ // src/commands/mcp-allow.ts
3550
+ async function mcpAllowCommand(scope, opts) {
3551
+ try {
3552
+ const ttlSec = opts.ttl ? parseTtl(opts.ttl) : void 0;
3553
+ const grant = await createScopeGrant(scope, { ttlSec, maxUses: opts.maxUses });
3554
+ print(`Granted MCP access to "${scope}" (grant ${grant.id}, ttl ${grant.ttlSec}s${grant.maxUses ? `, max ${grant.maxUses} uses` : ""}).`);
3555
+ return EXIT.OK;
3556
+ } catch (err) {
3557
+ printErr(err.message);
3558
+ return EXIT.GENERAL;
3559
+ }
3560
+ }
3561
+
3562
+ // src/commands/mcp-allow-cmd.ts
3563
+ async function mcpAllowCmdCommand(pattern, opts) {
3564
+ try {
3565
+ const ttlSec = opts.ttl ? parseTtl(opts.ttl) : void 0;
3566
+ const grant = await createCmdGrant(pattern, { ttlSec, maxUses: opts.maxUses });
3567
+ print(`Granted MCP run access to commands matching "${pattern}" (grant ${grant.id}, ttl ${grant.ttlSec}s).`);
3568
+ print("Reminder: this narrows ACCIDENTAL scope only \u2014 it is not a security boundary against an injected agent (spec-mcp \xA71/\xA72.1). Keep patterns as narrow as your workflow allows.");
3569
+ return EXIT.OK;
3570
+ } catch (err) {
3571
+ printErr(err.message);
3572
+ return EXIT.GENERAL;
3573
+ }
3574
+ }
3575
+
3576
+ // src/commands/mcp-grants.ts
3577
+ async function mcpGrantsCommand() {
3578
+ try {
3579
+ const grants = await listGrants();
3580
+ if (grants.length === 0) {
3581
+ print("No active MCP grants.");
3582
+ return EXIT.OK;
3583
+ }
3584
+ for (const g of grants) {
3585
+ const target = g.kind === "scope" ? `scope: ${g.scope}` : `cmd: ${g.pattern}`;
3586
+ const uses = g.usesRemaining !== null ? `, ${g.usesRemaining} uses left` : "";
3587
+ const ageSec = Math.floor((Date.now() - g.createdAt) / 1e3);
3588
+ const remainingSec = Math.max(0, g.ttlSec - ageSec);
3589
+ print(`${g.id} ${target}${uses} (expires in ${remainingSec}s)`);
3590
+ }
3591
+ return EXIT.OK;
3592
+ } catch (err) {
3593
+ printErr(err.message);
3594
+ return EXIT.GENERAL;
3595
+ }
3596
+ }
3597
+
3598
+ // src/commands/mcp-revoke.ts
3599
+ async function mcpRevokeCommand(id, opts) {
3600
+ try {
3601
+ if (opts.all) {
3602
+ await revokeAllGrants();
3603
+ print("All MCP grants revoked.");
3604
+ return EXIT.OK;
3605
+ }
3606
+ if (!id) throw new CliError(EXIT.GENERAL, "Provide a grant id, or --all");
3607
+ const revoked = await revokeGrant(id);
3608
+ print(revoked ? `Grant ${id} revoked.` : `No grant found with id ${id} (already expired or never existed).`);
3609
+ return EXIT.OK;
3610
+ } catch (err) {
3611
+ if (err instanceof CliError) {
3612
+ printErr(err.message);
3613
+ return err.exitCode;
3614
+ }
3615
+ printErr(err.message);
3616
+ return EXIT.GENERAL;
3617
+ }
3618
+ }
3619
+
3441
3620
  // src/index.ts
3442
3621
  var program = new Command();
3443
3622
  program.name("geslar").description("Geslar Agentic Access CLI").enablePositionalOptions().option("--agent <name>", "operate as this agent profile instead of your own account (spec-access-core.md \xA74)").version(CLI_VERSION);
@@ -3487,6 +3666,19 @@ agent.command("list").description("List your agent profiles").action(async () =>
3487
3666
  agent.command("revoke").argument("<name>", "profile name").description("Revoke an agent profile and clear its local token").action(async (name) => {
3488
3667
  process.exitCode = await agentRevokeCommand(name, {});
3489
3668
  });
3669
+ var mcp = program.command("mcp").description("Model Context Protocol server + pre-grant management (spec-mcp.md)");
3670
+ mcp.command("allow").argument("<scope>", "vault (or vault/item) to pre-approve for MCP write/execute tools").option("--ttl <duration>", "grant lifetime, e.g. 1h (default 1h, max 8h)").option("--max-uses <n>", "limit the number of times this grant may be consumed", (v) => parseInt(v, 10)).action(async (scope, opts) => {
3671
+ process.exitCode = await mcpAllowCommand(scope, opts);
3672
+ });
3673
+ mcp.command("allow-cmd").argument("<pattern>", 'command pattern for geslar_run, e.g. "npm test" (supports * wildcard)').option("--ttl <duration>", "grant lifetime, e.g. 1h (default 1h, max 8h)").option("--max-uses <n>", "limit the number of times this grant may be consumed", (v) => parseInt(v, 10)).action(async (pattern, opts) => {
3674
+ process.exitCode = await mcpAllowCmdCommand(pattern, opts);
3675
+ });
3676
+ mcp.command("grants").description("List active MCP pre-grants").action(async () => {
3677
+ process.exitCode = await mcpGrantsCommand();
3678
+ });
3679
+ mcp.command("revoke").argument("[id]", "grant id to revoke").option("--all", "revoke every active grant").action(async (id, opts) => {
3680
+ process.exitCode = await mcpRevokeCommand(id, opts);
3681
+ });
3490
3682
  void (async () => {
3491
3683
  try {
3492
3684
  await program.parseAsync(process.argv);