@serfab/cadre-host 0.7.1 → 0.9.0

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

@@ -0,0 +1,290 @@
+/**
+ * DonationService unit tests — the donate-a-node lifecycle on the host side,
+ * exercised against a fake orchestrator (no real child processes) and a real
+ * on-disk DonationStore + GrantService.
+ *
+ * Covers: provision → awaiting_seed (pinned keys threaded, seedToken persisted +
+ * redacted), seedToken survival across a store reconstruct, per-grant quota-race
+ * serialization, reclaim-on-post-spawn-failure, and the stale-awaiting_seed reap.
+ *
+ * getPeer / applySeed do real `fetch` to a live node, so their happy paths live
+ * in the cross-package integration scenario (`cadre-host-node-donation`), not
+ * here.
+ */
+
+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 type {
+  Orchestrator,
+  OrchestratorCreateRequest,
+  OrchestratorCreateResult,
+  OrchestratorStats,
+} from '@serfab/cadre-provider';
+
+import { DonationService } from '../donation-service.js';
+import { DonationStore } from '../donation-store.js';
+import { GrantService } from '../grant-service.js';
+import { GrantStore } from '../grant-store.js';
+import { DonationError } from '../types.js';
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+/** Records every create/stop/remove; returns deterministic, unique spawn results. */
+class FakeOrchestrator implements Orchestrator {
+  createCalls: OrchestratorCreateRequest[] = [];
+  stopped: string[] = [];
+  removed: string[] = [];
+  failCreate = false;
+  createDelayMs = 0;
+  private counter = 0;
+
+  async createContainer(request: OrchestratorCreateRequest): Promise<OrchestratorCreateResult> {
+    this.createCalls.push(request);
+    if (this.createDelayMs) await sleep(this.createDelayMs);
+    if (this.failCreate) throw new Error('spawn boom');
+    const n = ++this.counter;
+    return {
+      dockerId: `dock_${n}`,
+      healthEndpoint: `http://127.0.0.1:${9000 + n}/health`,
+      metricsEndpoint: `http://127.0.0.1:${9000 + n}/metrics`,
+      seedEndpoint: `http://127.0.0.1:${9000 + n}/seed`,
+      seedToken: `seed-token-${n}`,
+      p2pPort: 4000 + n,
+    };
+  }
+
+  async stopContainer(dockerId: string): Promise<void> {
+    this.stopped.push(dockerId);
+  }
+
+  async removeContainer(dockerId: string): Promise<void> {
+    this.removed.push(dockerId);
+  }
+
+  async getStats(): Promise<OrchestratorStats> {
+    return { cpuPercent: 0, memoryBytes: 0, networkRxBytes: 0, networkTxBytes: 0 };
+  }
+
+  async isRunning(): Promise<boolean> {
+    return true;
+  }
+
+  async getLogs(): Promise<string> {
+    return '';
+  }
+}
+
+let tmpRoot: string;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-donation-svc-'));
+});
+
+afterEach(() => {
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+function makeGrants(opts?: { maxNodes?: number }): { grants: GrantService; token: string } {
+  const grants = new GrantService({ store: new GrantStore(join(tmpRoot, 'grants')) });
+  const token = grants.issue({ label: 'Alice', ...(opts?.maxNodes ? { maxNodes: opts.maxNodes } : {}) }).token;
+  return { grants, token };
+}
+
+const baseRequest = (grantToken: string) => ({
+  grantToken,
+  partyId: 'party-P',
+  bootstrapNodes: ['/ip4/127.0.0.1/tcp/4001/p2p/12D3KooReq'],
+  ownerKeys: ['owner-key-b64url'],
+});
+
+describe('DonationService.provision', () => {
+  it('spawns → awaiting_seed, threads pinned owner keys, persists (redacts) the seedToken', async () => {
+    const orch = new FakeOrchestrator();
+    const store = new DonationStore(join(tmpRoot, 'donations'));
+    const { grants, token } = makeGrants();
+    const svc = new DonationService({ orchestrator: orch, grants, store });
+
+    const view = await svc.provision(baseRequest(token));
+
+    expect(view.status).toBe('awaiting_seed');
+    expect(view.partyId).toBe('party-P');
+    expect(view.profile).toBe('storage'); // default
+    expect(view.grantToken).toBe(token);
+    // Redacted: host-only secret + loopback URL never cross the boundary.
+    expect((view as Record<string, unknown>).seedToken).toBeUndefined();
+    expect((view as Record<string, unknown>).seedEndpoint).toBeUndefined();
+
+    // The orchestrator got the requester's pinned owner key (the seed-trust anchor).
+    expect(orch.createCalls).toHaveLength(1);
+    expect(orch.createCalls[0].pinnedOwnerKeys).toEqual(['owner-key-b64url']);
+    expect(orch.createCalls[0].containerId).toBe(view.id);
+    expect(orch.createCalls[0].partyId).toBe('party-P');
+
+    // But the record on disk DOES retain the seedToken (crash-recovery).
+    const stored = store.get(view.id);
+    expect(stored?.seedToken).toBe('seed-token-1');
+    expect(stored?.seedEndpoint).toBe('http://127.0.0.1:9001/seed');
+    expect(store.liveNodeCount(token)).toBe(1);
+  });
+
+  it('honours an explicit transaction profile', async () => {
+    const orch = new FakeOrchestrator();
+    const { grants, token } = makeGrants();
+    const svc = new DonationService({
+      orchestrator: orch,
+      grants,
+      store: new DonationStore(join(tmpRoot, 'donations')),
+    });
+
+    const view = await svc.provision({ ...baseRequest(token), profile: 'transaction' });
+    expect(view.profile).toBe('transaction');
+    expect(orch.createCalls[0].profile).toBe('transaction');
+  });
+
+  it('denies an unknown grant token before spawning (unauthorized)', async () => {
+    const orch = new FakeOrchestrator();
+    const { grants } = makeGrants();
+    const svc = new DonationService({
+      orchestrator: orch,
+      grants,
+      store: new DonationStore(join(tmpRoot, 'donations')),
+    });
+
+    await expect(svc.provision(baseRequest('not-a-real-token')))
+      .rejects.toMatchObject({ code: 'unauthorized' });
+    expect(orch.createCalls).toHaveLength(0);
+  });
+});
+
+describe('DonationService seedToken persistence', () => {
+  it('reproduces the seedToken from a store rebuilt off disk (host-restart gap)', async () => {
+    const orch = new FakeOrchestrator();
+    const dir = join(tmpRoot, 'donations');
+    const { grants, token } = makeGrants();
+    const svc = new DonationService({ orchestrator: orch, grants, store: new DonationStore(dir) });
+
+    const view = await svc.provision(baseRequest(token));
+
+    // Simulate a host restart: brand-new store instance, same directory.
+    const reloaded = new DonationStore(dir);
+    const record = reloaded.get(view.id);
+    expect(record?.status).toBe('awaiting_seed');
+    expect(record?.seedToken).toBe('seed-token-1');
+    expect(record?.seedEndpoint).toBe('http://127.0.0.1:9001/seed');
+  });
+});
+
+describe('DonationService quota-race serialization', () => {
+  it('serializes per grant so two concurrent provisions at the boundary cannot both pass', async () => {
+    const orch = new FakeOrchestrator();
+    orch.createDelayMs = 40; // widen the check→create window so an unserialized impl would race
+    const { grants, token } = makeGrants({ maxNodes: 1 });
+    const svc = new DonationService({
+      orchestrator: orch,
+      grants,
+      store: new DonationStore(join(tmpRoot, 'donations')),
+    });
+
+    const [a, b] = await Promise.allSettled([
+      svc.provision(baseRequest(token)),
+      svc.provision(baseRequest(token)),
+    ]);
+
+    const fulfilled = [a, b].filter((r) => r.status === 'fulfilled');
+    const rejected = [a, b].filter((r) => r.status === 'rejected');
+    expect(fulfilled).toHaveLength(1);
+    expect(rejected).toHaveLength(1);
+    expect((rejected[0] as PromiseRejectedResult).reason).toMatchObject({ code: 'quota_exceeded' });
+    // Exactly one node was actually spawned.
+    expect(orch.createCalls).toHaveLength(1);
+  });
+});
+
+describe('DonationService reclaim-on-failure', () => {
+  it('reclaims the spawned resources and marks error when persistence fails after spawn', async () => {
+    const orch = new FakeOrchestrator();
+    const store = new DonationStore(join(tmpRoot, 'donations'));
+    // Fail the SECOND put — the awaiting_seed write, after the orchestrator has
+    // already handed back a dockerId. The service must reclaim it.
+    const realPut = store.put.bind(store);
+    let puts = 0;
+    (store as unknown as { put: (d: unknown) => void }).put = (d: unknown) => {
+      puts += 1;
+      if (puts === 2) throw new DonationError('storage_error', 'disk full');
+      realPut(d as never);
+    };
+    const { grants, token } = makeGrants();
+    const svc = new DonationService({ orchestrator: orch, grants, store });
+
+    await expect(svc.provision(baseRequest(token)))
+      .rejects.toMatchObject({ code: 'orchestrator_error' });
+
+    // The spawned child was reclaimed (removeContainer called with its dockerId).
+    expect(orch.removed).toEqual(['dock_1']);
+    // The record is marked error (the 3rd put, which succeeds) → not counted live.
+    const errored = store.list().find((d) => d.grantToken === token);
+    expect(errored?.status).toBe('error');
+    expect(store.liveNodeCount(token)).toBe(0);
+  });
+
+  it('does not reclaim when the spawn itself throws (nothing was allocated)', async () => {
+    const orch = new FakeOrchestrator();
+    orch.failCreate = true;
+    const store = new DonationStore(join(tmpRoot, 'donations'));
+    const { grants, token } = makeGrants();
+    const svc = new DonationService({ orchestrator: orch, grants, store });
+
+    await expect(svc.provision(baseRequest(token)))
+      .rejects.toMatchObject({ code: 'orchestrator_error' });
+    expect(orch.removed).toEqual([]);
+    expect(store.list().find((d) => d.grantToken === token)?.status).toBe('error');
+    expect(store.liveNodeCount(token)).toBe(0);
+  });
+});
+
+describe('DonationService.reapStaleAwaitingSeed', () => {
+  it('terminates awaiting_seed donations past the TTL and leaves fresh ones alone', async () => {
+    const orch = new FakeOrchestrator();
+    const store = new DonationStore(join(tmpRoot, 'donations'));
+    const { grants, token } = makeGrants({ maxNodes: 5 });
+    let clock = new Date('2025-01-01T00:00:00.000Z');
+    const svc = new DonationService({ orchestrator: orch, grants, store, now: () => clock });
+
+    // Old donation (enters awaiting_seed at T0).
+    const old = await svc.provision(baseRequest(token));
+
+    // Advance well past the TTL, then provision a fresh one at the new "now".
+    const ttlMs = 30 * 60 * 1000;
+    clock = new Date(Date.parse('2025-01-01T00:00:00.000Z') + ttlMs + 60_000);
+    const fresh = await svc.provision(baseRequest(token));
+
+    const reaped = await svc.reapStaleAwaitingSeed(ttlMs);
+
+    expect(reaped).toEqual([old.id]);
+    expect(store.get(old.id)?.status).toBe('terminated');
+    expect(store.get(fresh.id)?.status).toBe('awaiting_seed');
+    // The stale child was stopped + removed.
+    expect(orch.stopped).toContain('dock_1');
+    expect(orch.removed).toContain('dock_1');
+    // Only the fresh donation still counts against the quota.
+    expect(store.liveNodeCount(token)).toBe(1);
+  });
+
+  it('is a no-op when nothing is stale', async () => {
+    const orch = new FakeOrchestrator();
+    const { grants, token } = makeGrants();
+    const svc = new DonationService({
+      orchestrator: orch,
+      grants,
+      store: new DonationStore(join(tmpRoot, 'donations')),
+    });
+    await svc.provision(baseRequest(token));
+    expect(await svc.reapStaleAwaitingSeed(30 * 60 * 1000)).toEqual([]);
+    expect(orch.removed).toEqual([]);
+  });
+});

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

@@ -0,0 +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' });
+  });
+});

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

@@ -0,0 +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' }),
+    );
+  });
+});