@serfab/cadre-host 0.10.0 → 0.11.0

package/src/donation/__tests__/grant-service.test.ts

@@ -1,213 +1,213 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { mkdtempSync, rmSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { GrantService, createGrantAdminHandlers, DEFAULT_MAX_NODES } from '../grant-service.js';
-import { GrantStore } from '../grant-store.js';
-import { GrantError } from '../types.js';
-
-let tmpRoot: string;
-let store: GrantStore;
-let service: GrantService;
-
-beforeEach(() => {
-  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grant-svc-'));
-  store = new GrantStore(tmpRoot);
-  service = new GrantService({ store });
-});
-
-afterEach(() => {
-  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
-});
-
-describe('GrantService.issue', () => {
-  it('persists a grant and returns a base64url token', () => {
-    const grant = service.issue({ label: "Alice's cadre", maxNodes: 2 });
-    expect(grant.token).toBeTruthy();
-    // base64url alphabet only.
-    expect(grant.token).toMatch(/^[A-Za-z0-9_-]+$/);
-    expect(grant.label).toBe("Alice's cadre");
-    expect(grant.maxNodes).toBe(2);
-    expect(grant.createdAt).toBeTruthy();
-    expect(grant.expiresAt).toBeUndefined();
-    expect(grant.revokedAt).toBeUndefined();
-
-    expect(store.get(grant.token)).toMatchObject({ label: "Alice's cadre", maxNodes: 2 });
-  });
-
-  it('defaults maxNodes when omitted', () => {
-    const grant = service.issue({ label: 'Bob' });
-    expect(grant.maxNodes).toBe(DEFAULT_MAX_NODES);
-  });
-
-  it('sets expiresAt from ttlMs', () => {
-    const clock = new Date('2025-01-01T00:00:00.000Z');
-    const svc = new GrantService({ store, now: () => clock });
-    const grant = svc.issue({ label: 'Carol', ttlMs: 24 * 60 * 60 * 1000 });
-    expect(grant.expiresAt).toBe('2025-01-02T00:00:00.000Z');
-  });
-
-  it('rejects empty / whitespace labels', () => {
-    expect(() => service.issue({ label: '   ' })).toThrow(GrantError);
-    expect(() => service.issue({ label: '' })).toThrow(GrantError);
-  });
-
-  it('rejects labels over 200 characters', () => {
-    expect(() => service.issue({ label: 'a'.repeat(201) }))
-      .toThrow(expect.objectContaining({ code: 'invalid_label' }));
-  });
-
-  it('rejects non-positive / non-integer maxNodes', () => {
-    expect(() => service.issue({ label: 'X', maxNodes: 0 }))
-      .toThrow(expect.objectContaining({ code: 'invalid_max_nodes' }));
-    expect(() => service.issue({ label: 'X', maxNodes: -1 }))
-      .toThrow(expect.objectContaining({ code: 'invalid_max_nodes' }));
-    expect(() => service.issue({ label: 'X', maxNodes: 1.5 }))
-      .toThrow(expect.objectContaining({ code: 'invalid_max_nodes' }));
-  });
-
-  it('rejects non-positive ttl', () => {
-    expect(() => service.issue({ label: 'X', ttlMs: 0 }))
-      .toThrow(expect.objectContaining({ code: 'invalid_ttl' }));
-    expect(() => service.issue({ label: 'X', ttlMs: -1 }))
-      .toThrow(expect.objectContaining({ code: 'invalid_ttl' }));
-  });
-});
-
-describe('GrantService.validate', () => {
-  it('accepts a live grant', () => {
-    const { token } = service.issue({ label: 'Alice' });
-    const v = service.validate(token);
-    expect(v.ok).toBe(true);
-    expect(v.grant?.token).toBe(token);
-    expect(v.reason).toBeUndefined();
-  });
-
-  it('denies an empty bearer with unknown_token (never throws)', () => {
-    expect(service.validate('')).toEqual({ ok: false, reason: 'unknown_token' });
-  });
-
-  it('denies an unknown token with unknown_token (never throws)', () => {
-    expect(service.validate('does-not-exist')).toEqual({ ok: false, reason: 'unknown_token' });
-  });
-
-  it('denies a revoked grant with reason "revoked"', () => {
-    const { token } = service.issue({ label: 'Rev' });
-    service.revoke(token);
-    const v = service.validate(token);
-    expect(v.ok).toBe(false);
-    expect(v.reason).toBe('revoked');
-    expect(v.grant?.token).toBe(token);
-  });
-
-  it('denies an expired grant with reason "expired" even when not revoked', () => {
-    let clock = new Date('2025-01-01T00:00:00.000Z');
-    const svc = new GrantService({ store, now: () => clock });
-    const { token } = svc.issue({ label: 'Exp', ttlMs: 60_000 });
-
-    clock = new Date('2025-01-02T00:00:00.000Z'); // past expiry
-    const v = svc.validate(token);
-    expect(v.ok).toBe(false);
-    expect(v.reason).toBe('expired');
-  });
-
-  it('reports revoked over expired when both apply', () => {
-    let clock = new Date('2025-01-01T00:00:00.000Z');
-    const svc = new GrantService({ store, now: () => clock });
-    const { token } = svc.issue({ label: 'Both', ttlMs: 60_000 });
-    svc.revoke(token);
-
-    clock = new Date('2025-01-02T00:00:00.000Z'); // also past expiry now
-    expect(svc.validate(token).reason).toBe('revoked');
-  });
-});
-
-describe('GrantService.validateForProvision', () => {
-  it('allows up to the quota, then denies with quota_exceeded', () => {
-    const { token } = service.issue({ label: 'Alice', maxNodes: 2 });
-
-    // First two provisions (live count 0, then 1) pass.
-    expect(service.validateForProvision(token, () => 0).ok).toBe(true);
-    expect(service.validateForProvision(token, () => 1).ok).toBe(true);
-
-    // Third (live count already at 2) is denied.
-    const v = service.validateForProvision(token, () => 2);
-    expect(v.ok).toBe(false);
-    expect(v.reason).toBe('quota_exceeded');
-    expect(v.grant?.token).toBe(token);
-  });
-
-  it('does not consult liveNodeCount for an unknown token', () => {
-    let called = false;
-    const v = service.validateForProvision('nope', () => { called = true; return 0; });
-    expect(v).toEqual({ ok: false, reason: 'unknown_token' });
-    expect(called).toBe(false);
-  });
-
-  it('does not consult liveNodeCount for a revoked or expired grant', () => {
-    const { token } = service.issue({ label: 'Rev', maxNodes: 5 });
-    service.revoke(token);
-    let called = false;
-    const v = service.validateForProvision(token, () => { called = true; return 0; });
-    expect(v.reason).toBe('revoked');
-    expect(called).toBe(false);
-  });
-});
-
-describe('GrantService.revoke', () => {
-  it('throws not_found for an unknown token', () => {
-    expect(() => service.revoke('nope'))
-      .toThrow(expect.objectContaining({ code: 'not_found' }));
-  });
-
-  it('is idempotent (second revoke keeps the original timestamp)', () => {
-    let clock = new Date('2025-01-01T00:00:00.000Z');
-    const svc = new GrantService({ store, now: () => clock });
-    const { token } = svc.issue({ label: 'X' });
-
-    svc.revoke(token);
-    const first = store.get(token)?.revokedAt;
-
-    clock = new Date('2025-02-01T00:00:00.000Z');
-    svc.revoke(token); // no throw; keeps first timestamp
-    expect(store.get(token)?.revokedAt).toBe(first);
-  });
-});
-
-describe('GrantService.list', () => {
-  it('enumerates issued grants', () => {
-    service.issue({ label: 'A' });
-    service.issue({ label: 'B' });
-    expect(service.list().map(g => g.label).sort()).toEqual(['A', 'B']);
-  });
-});
-
-describe('createGrantAdminHandlers', () => {
-  it('exposes the admin HTTP-handler surface', async () => {
-    const handlers = createGrantAdminHandlers(service);
-
-    const issued = await handlers.postGrant({ label: 'Pat', maxNodes: 3 });
-    expect(issued.grant.token).toBeTruthy();
-    expect(issued.grant.maxNodes).toBe(3);
-
-    let listed = await handlers.listGrants();
-    expect(listed.grants.map(g => g.token)).toContain(issued.grant.token);
-
-    await handlers.deleteGrant(issued.grant.token);
-    listed = await handlers.listGrants();
-    // Revocation marks, not removes — the grant is still listed but revoked.
-    expect(listed.grants.find(g => g.token === issued.grant.token)?.revokedAt).toBeTruthy();
-  });
-
-  it('postGrant rejects a missing label', async () => {
-    const handlers = createGrantAdminHandlers(service);
-    await expect(handlers.postGrant({ label: undefined as unknown as string }))
-      .rejects.toMatchObject({ code: 'invalid_label' });
-  });
-
-  it('deleteGrant surfaces not_found for an unknown token', async () => {
-    const handlers = createGrantAdminHandlers(service);
-    await expect(handlers.deleteGrant('nope')).rejects.toMatchObject({ code: 'not_found' });
-  });
-});
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { GrantService, createGrantAdminHandlers, DEFAULT_MAX_NODES } from '../grant-service.js';
+import { GrantStore } from '../grant-store.js';
+import { GrantError } from '../types.js';
+
+let tmpRoot: string;
+let store: GrantStore;
+let service: GrantService;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grant-svc-'));
+  store = new GrantStore(tmpRoot);
+  service = new GrantService({ store });
+});
+
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('GrantService.issue', () => {
+  it('persists a grant and returns a base64url token', () => {
+    const grant = service.issue({ label: "Alice's cadre", maxNodes: 2 });
+    expect(grant.token).toBeTruthy();
+    // base64url alphabet only.
+    expect(grant.token).toMatch(/^[A-Za-z0-9_-]+$/);
+    expect(grant.label).toBe("Alice's cadre");
+    expect(grant.maxNodes).toBe(2);
+    expect(grant.createdAt).toBeTruthy();
+    expect(grant.expiresAt).toBeUndefined();
+    expect(grant.revokedAt).toBeUndefined();
+
+    expect(store.get(grant.token)).toMatchObject({ label: "Alice's cadre", maxNodes: 2 });
+  });
+
+  it('defaults maxNodes when omitted', () => {
+    const grant = service.issue({ label: 'Bob' });
+    expect(grant.maxNodes).toBe(DEFAULT_MAX_NODES);
+  });
+
+  it('sets expiresAt from ttlMs', () => {
+    const clock = new Date('2025-01-01T00:00:00.000Z');
+    const svc = new GrantService({ store, now: () => clock });
+    const grant = svc.issue({ label: 'Carol', ttlMs: 24 * 60 * 60 * 1000 });
+    expect(grant.expiresAt).toBe('2025-01-02T00:00:00.000Z');
+  });
+
+  it('rejects empty / whitespace labels', () => {
+    expect(() => service.issue({ label: '   ' })).toThrow(GrantError);
+    expect(() => service.issue({ label: '' })).toThrow(GrantError);
+  });
+
+  it('rejects labels over 200 characters', () => {
+    expect(() => service.issue({ label: 'a'.repeat(201) }))
+      .toThrow(expect.objectContaining({ code: 'invalid_label' }));
+  });
+
+  it('rejects non-positive / non-integer maxNodes', () => {
+    expect(() => service.issue({ label: 'X', maxNodes: 0 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_max_nodes' }));
+    expect(() => service.issue({ label: 'X', maxNodes: -1 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_max_nodes' }));
+    expect(() => service.issue({ label: 'X', maxNodes: 1.5 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_max_nodes' }));
+  });
+
+  it('rejects non-positive ttl', () => {
+    expect(() => service.issue({ label: 'X', ttlMs: 0 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_ttl' }));
+    expect(() => service.issue({ label: 'X', ttlMs: -1 }))
+      .toThrow(expect.objectContaining({ code: 'invalid_ttl' }));
+  });
+});
+
+describe('GrantService.validate', () => {
+  it('accepts a live grant', () => {
+    const { token } = service.issue({ label: 'Alice' });
+    const v = service.validate(token);
+    expect(v.ok).toBe(true);
+    expect(v.grant?.token).toBe(token);
+    expect(v.reason).toBeUndefined();
+  });
+
+  it('denies an empty bearer with unknown_token (never throws)', () => {
+    expect(service.validate('')).toEqual({ ok: false, reason: 'unknown_token' });
+  });
+
+  it('denies an unknown token with unknown_token (never throws)', () => {
+    expect(service.validate('does-not-exist')).toEqual({ ok: false, reason: 'unknown_token' });
+  });
+
+  it('denies a revoked grant with reason "revoked"', () => {
+    const { token } = service.issue({ label: 'Rev' });
+    service.revoke(token);
+    const v = service.validate(token);
+    expect(v.ok).toBe(false);
+    expect(v.reason).toBe('revoked');
+    expect(v.grant?.token).toBe(token);
+  });
+
+  it('denies an expired grant with reason "expired" even when not revoked', () => {
+    let clock = new Date('2025-01-01T00:00:00.000Z');
+    const svc = new GrantService({ store, now: () => clock });
+    const { token } = svc.issue({ label: 'Exp', ttlMs: 60_000 });
+
+    clock = new Date('2025-01-02T00:00:00.000Z'); // past expiry
+    const v = svc.validate(token);
+    expect(v.ok).toBe(false);
+    expect(v.reason).toBe('expired');
+  });
+
+  it('reports revoked over expired when both apply', () => {
+    let clock = new Date('2025-01-01T00:00:00.000Z');
+    const svc = new GrantService({ store, now: () => clock });
+    const { token } = svc.issue({ label: 'Both', ttlMs: 60_000 });
+    svc.revoke(token);
+
+    clock = new Date('2025-01-02T00:00:00.000Z'); // also past expiry now
+    expect(svc.validate(token).reason).toBe('revoked');
+  });
+});
+
+describe('GrantService.validateForProvision', () => {
+  it('allows up to the quota, then denies with quota_exceeded', () => {
+    const { token } = service.issue({ label: 'Alice', maxNodes: 2 });
+
+    // First two provisions (live count 0, then 1) pass.
+    expect(service.validateForProvision(token, () => 0).ok).toBe(true);
+    expect(service.validateForProvision(token, () => 1).ok).toBe(true);
+
+    // Third (live count already at 2) is denied.
+    const v = service.validateForProvision(token, () => 2);
+    expect(v.ok).toBe(false);
+    expect(v.reason).toBe('quota_exceeded');
+    expect(v.grant?.token).toBe(token);
+  });
+
+  it('does not consult liveNodeCount for an unknown token', () => {
+    let called = false;
+    const v = service.validateForProvision('nope', () => { called = true; return 0; });
+    expect(v).toEqual({ ok: false, reason: 'unknown_token' });
+    expect(called).toBe(false);
+  });
+
+  it('does not consult liveNodeCount for a revoked or expired grant', () => {
+    const { token } = service.issue({ label: 'Rev', maxNodes: 5 });
+    service.revoke(token);
+    let called = false;
+    const v = service.validateForProvision(token, () => { called = true; return 0; });
+    expect(v.reason).toBe('revoked');
+    expect(called).toBe(false);
+  });
+});
+
+describe('GrantService.revoke', () => {
+  it('throws not_found for an unknown token', () => {
+    expect(() => service.revoke('nope'))
+      .toThrow(expect.objectContaining({ code: 'not_found' }));
+  });
+
+  it('is idempotent (second revoke keeps the original timestamp)', () => {
+    let clock = new Date('2025-01-01T00:00:00.000Z');
+    const svc = new GrantService({ store, now: () => clock });
+    const { token } = svc.issue({ label: 'X' });
+
+    svc.revoke(token);
+    const first = store.get(token)?.revokedAt;
+
+    clock = new Date('2025-02-01T00:00:00.000Z');
+    svc.revoke(token); // no throw; keeps first timestamp
+    expect(store.get(token)?.revokedAt).toBe(first);
+  });
+});
+
+describe('GrantService.list', () => {
+  it('enumerates issued grants', () => {
+    service.issue({ label: 'A' });
+    service.issue({ label: 'B' });
+    expect(service.list().map(g => g.label).sort()).toEqual(['A', 'B']);
+  });
+});
+
+describe('createGrantAdminHandlers', () => {
+  it('exposes the admin HTTP-handler surface', async () => {
+    const handlers = createGrantAdminHandlers(service);
+
+    const issued = await handlers.postGrant({ label: 'Pat', maxNodes: 3 });
+    expect(issued.grant.token).toBeTruthy();
+    expect(issued.grant.maxNodes).toBe(3);
+
+    let listed = await handlers.listGrants();
+    expect(listed.grants.map(g => g.token)).toContain(issued.grant.token);
+
+    await handlers.deleteGrant(issued.grant.token);
+    listed = await handlers.listGrants();
+    // Revocation marks, not removes — the grant is still listed but revoked.
+    expect(listed.grants.find(g => g.token === issued.grant.token)?.revokedAt).toBeTruthy();
+  });
+
+  it('postGrant rejects a missing label', async () => {
+    const handlers = createGrantAdminHandlers(service);
+    await expect(handlers.postGrant({ label: undefined as unknown as string }))
+      .rejects.toMatchObject({ code: 'invalid_label' });
+  });
+
+  it('deleteGrant surfaces not_found for an unknown token', async () => {
+    const handlers = createGrantAdminHandlers(service);
+    await expect(handlers.deleteGrant('nope')).rejects.toMatchObject({ code: 'not_found' });
+  });
+});

package/src/donation/__tests__/grant-store.test.ts

@@ -1,113 +1,113 @@
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { GrantStore } from '../grant-store.js';
-import { GrantError } from '../types.js';
-import type { Grant } from '../types.js';
-
-let tmpRoot: string;
-
-function grant(over: Partial<Grant> = {}): Grant {
-  return {
-    token: 'tok-A',
-    label: "Alice's cadre",
-    maxNodes: 2,
-    createdAt: '2025-01-01T00:00:00.000Z',
-    ...over,
-  };
-}
-
-beforeEach(() => {
-  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grant-store-'));
-});
-
-afterEach(() => {
-  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
-});
-
-describe('GrantStore', () => {
-  it('returns empty state when file is missing', () => {
-    const store = new GrantStore(tmpRoot);
-    expect(store.list()).toEqual([]);
-    expect(store.get('anything')).toBeUndefined();
-  });
-
-  it('round-trips grants through save/load', () => {
-    const store = new GrantStore(tmpRoot);
-    store.add(grant({ token: 'tok-A', label: 'Alice' }));
-    store.add(grant({ token: 'tok-B', label: 'Bob', maxNodes: 1, expiresAt: '2025-06-01T00:00:00.000Z' }));
-
-    const reread = new GrantStore(tmpRoot);
-    expect(reread.list()).toHaveLength(2);
-    expect(reread.get('tok-A')).toMatchObject({ token: 'tok-A', label: 'Alice', maxNodes: 2 });
-    expect(reread.get('tok-B')?.expiresAt).toBe('2025-06-01T00:00:00.000Z');
-    expect(reread.get('tok-A')?.expiresAt).toBeUndefined();
-  });
-
-  it('removes grants', () => {
-    const store = new GrantStore(tmpRoot);
-    store.add(grant({ token: 'tok-A' }));
-    expect(store.remove('tok-A')).toBe(true);
-    expect(store.remove('tok-A')).toBe(false);
-
-    const reread = new GrantStore(tmpRoot);
-    expect(reread.list()).toEqual([]);
-  });
-
-  it('marks a grant revoked, idempotently', () => {
-    const store = new GrantStore(tmpRoot);
-    store.add(grant({ token: 'tok-A' }));
-
-    expect(store.markRevoked('tok-A', '2025-02-01T00:00:00.000Z')).toBe(true);
-    expect(store.get('tok-A')?.revokedAt).toBe('2025-02-01T00:00:00.000Z');
-
-    // Second revoke keeps the original timestamp.
-    expect(store.markRevoked('tok-A', '2025-03-01T00:00:00.000Z')).toBe(true);
-    expect(store.get('tok-A')?.revokedAt).toBe('2025-02-01T00:00:00.000Z');
-
-    // Unknown token.
-    expect(store.markRevoked('nope', '2025-02-01T00:00:00.000Z')).toBe(false);
-  });
-
-  it('writes through a temp file (atomic rename, no residue)', () => {
-    const store = new GrantStore(tmpRoot);
-    store.add(grant());
-    expect(existsSync(join(tmpRoot, 'grants.json'))).toBe(true);
-    expect(existsSync(join(tmpRoot, 'grants.json.tmp'))).toBe(false);
-  });
-
-  it('persists the version field in saved JSON', () => {
-    const store = new GrantStore(tmpRoot);
-    store.add(grant({ token: 'tok-A', label: 'one' }));
-    const raw = JSON.parse(readFileSync(join(tmpRoot, 'grants.json'), 'utf8'));
-    expect(raw.version).toBe(1);
-    expect(raw.grants['tok-A'].label).toBe('one');
-    // token is the map key, not duplicated inside the row.
-    expect(raw.grants['tok-A'].token).toBeUndefined();
-  });
-
-  it('throws on malformed JSON rather than silently wiping (would revoke everyone)', () => {
-    writeFileSync(join(tmpRoot, 'grants.json'), 'not json', 'utf8');
-    const store = new GrantStore(tmpRoot);
-    expect(() => store.load()).toThrow(GrantError);
-  });
-
-  it('throws on a file with the wrong shape', () => {
-    writeFileSync(join(tmpRoot, 'grants.json'), JSON.stringify({ version: 99, foo: 'bar' }), 'utf8');
-    const store = new GrantStore(tmpRoot);
-    expect(() => store.load()).toThrow(GrantError);
-  });
-
-  it('wraps a write failure as storage_error (not a bare Error)', () => {
-    const store = new GrantStore(tmpRoot);
-    // load() sees no grants.json (empty), then save() writes grants.json.tmp.
-    // Make that temp path a directory so writeFileSync fails (EISDIR) — the
-    // failure must surface as GrantError storage_error, not a bare Error.
-    mkdirSync(join(tmpRoot, 'grants.json.tmp'));
-    expect(() => store.add(grant())).toThrow(
-      expect.objectContaining({ code: 'storage_error' }),
-    );
-  });
-});
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { GrantStore } from '../grant-store.js';
+import { GrantError } from '../types.js';
+import type { Grant } from '../types.js';
+
+let tmpRoot: string;
+
+function grant(over: Partial<Grant> = {}): Grant {
+  return {
+    token: 'tok-A',
+    label: "Alice's cadre",
+    maxNodes: 2,
+    createdAt: '2025-01-01T00:00:00.000Z',
+    ...over,
+  };
+}
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-grant-store-'));
+});
+
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+describe('GrantStore', () => {
+  it('returns empty state when file is missing', () => {
+    const store = new GrantStore(tmpRoot);
+    expect(store.list()).toEqual([]);
+    expect(store.get('anything')).toBeUndefined();
+  });
+
+  it('round-trips grants through save/load', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant({ token: 'tok-A', label: 'Alice' }));
+    store.add(grant({ token: 'tok-B', label: 'Bob', maxNodes: 1, expiresAt: '2025-06-01T00:00:00.000Z' }));
+
+    const reread = new GrantStore(tmpRoot);
+    expect(reread.list()).toHaveLength(2);
+    expect(reread.get('tok-A')).toMatchObject({ token: 'tok-A', label: 'Alice', maxNodes: 2 });
+    expect(reread.get('tok-B')?.expiresAt).toBe('2025-06-01T00:00:00.000Z');
+    expect(reread.get('tok-A')?.expiresAt).toBeUndefined();
+  });
+
+  it('removes grants', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant({ token: 'tok-A' }));
+    expect(store.remove('tok-A')).toBe(true);
+    expect(store.remove('tok-A')).toBe(false);
+
+    const reread = new GrantStore(tmpRoot);
+    expect(reread.list()).toEqual([]);
+  });
+
+  it('marks a grant revoked, idempotently', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant({ token: 'tok-A' }));
+
+    expect(store.markRevoked('tok-A', '2025-02-01T00:00:00.000Z')).toBe(true);
+    expect(store.get('tok-A')?.revokedAt).toBe('2025-02-01T00:00:00.000Z');
+
+    // Second revoke keeps the original timestamp.
+    expect(store.markRevoked('tok-A', '2025-03-01T00:00:00.000Z')).toBe(true);
+    expect(store.get('tok-A')?.revokedAt).toBe('2025-02-01T00:00:00.000Z');
+
+    // Unknown token.
+    expect(store.markRevoked('nope', '2025-02-01T00:00:00.000Z')).toBe(false);
+  });
+
+  it('writes through a temp file (atomic rename, no residue)', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant());
+    expect(existsSync(join(tmpRoot, 'grants.json'))).toBe(true);
+    expect(existsSync(join(tmpRoot, 'grants.json.tmp'))).toBe(false);
+  });
+
+  it('persists the version field in saved JSON', () => {
+    const store = new GrantStore(tmpRoot);
+    store.add(grant({ token: 'tok-A', label: 'one' }));
+    const raw = JSON.parse(readFileSync(join(tmpRoot, 'grants.json'), 'utf8'));
+    expect(raw.version).toBe(1);
+    expect(raw.grants['tok-A'].label).toBe('one');
+    // token is the map key, not duplicated inside the row.
+    expect(raw.grants['tok-A'].token).toBeUndefined();
+  });
+
+  it('throws on malformed JSON rather than silently wiping (would revoke everyone)', () => {
+    writeFileSync(join(tmpRoot, 'grants.json'), 'not json', 'utf8');
+    const store = new GrantStore(tmpRoot);
+    expect(() => store.load()).toThrow(GrantError);
+  });
+
+  it('throws on a file with the wrong shape', () => {
+    writeFileSync(join(tmpRoot, 'grants.json'), JSON.stringify({ version: 99, foo: 'bar' }), 'utf8');
+    const store = new GrantStore(tmpRoot);
+    expect(() => store.load()).toThrow(GrantError);
+  });
+
+  it('wraps a write failure as storage_error (not a bare Error)', () => {
+    const store = new GrantStore(tmpRoot);
+    // load() sees no grants.json (empty), then save() writes grants.json.tmp.
+    // Make that temp path a directory so writeFileSync fails (EISDIR) — the
+    // failure must surface as GrantError storage_error, not a bare Error.
+    mkdirSync(join(tmpRoot, 'grants.json.tmp'));
+    expect(() => store.add(grant())).toThrow(
+      expect.objectContaining({ code: 'storage_error' }),
+    );
+  });
+});