Implement session management with OS keychain integration

- Save/load/delete session data from keychain
- Use @napi-rs/keyring for cross-platform support
- Track current session metadata
- Error handling for keychain operations
- Comprehensive unit tests with mocked keychain
- Fix AtpSessionData type compliance (add required 'active' field)

Co-Authored-By: Claude Sonnet 4.5 <[e-mail]>

.claude/settings.json

···
 {
   "permissions": {
-    "allow": [
-      "Bash(npm run test:*)",
-      "Bash(npm run build:*)",
-      "Bash(npm test:*)"
-    ]
+    "allow": ["Bash(npm run test:*)", "Bash(npm run build:*)", "Bash(npm test:*)"]
   }
 }

package.json

···
     "type": "git",
     "url": "[e-mail]:markbennett.ca/tangled-cli"
   },
-  "keywords": [
-    "git",
-    "tangled",
-    "pds",
-    "atproto",
-    "cli"
-  ],
+  "keywords": ["git", "tangled", "pds", "atproto", "cli"],
   "author": "Mark Bennett",
   "license": "MIT",
   "dependencies": {

src/lib/session.ts

···
+import type { AtpSessionData } from '@atproto/api';
+import { AsyncEntry } from '@napi-rs/keyring';
+
+const SERVICE_NAME = 'tangled-cli';
+
+export interface SessionMetadata {
+  handle: string;
+  did: string;
+  pds: string;
+  lastUsed: string; // ISO timestamp
+}
+
+/**
+ * Store session data in OS keychain
+ * @param sessionData - Session data from AtpAgent
+ */
+export async function saveSession(sessionData: AtpSessionData): Promise<void> {
+  try {
+    const accountId = sessionData.did || sessionData.handle;
+    if (!accountId) {
+      throw new Error('Session data must include DID or handle');
+    }
+
+    const serialized = JSON.stringify(sessionData);
+    const entry = new AsyncEntry(SERVICE_NAME, accountId);
+    await entry.setPassword(serialized);
+  } catch (error) {
+    throw new Error(
+      `Failed to save session to keychain: ${error instanceof Error ? error.message : 'Unknown error'}`
+    );
+  }
+}
+
+/**
+ * Retrieve session data from OS keychain
+ * @param accountId - User's DID or handle
+ */
+export async function loadSession(accountId: string): Promise<AtpSessionData | null> {
+  try {
+    const entry = new AsyncEntry(SERVICE_NAME, accountId);
+    const serialized = await entry.getPassword();
+    if (!serialized) {
+      return null;
+    }
+    return JSON.parse(serialized) as AtpSessionData;
+  } catch (error) {
+    throw new Error(
+      `Failed to load session from keychain: ${error instanceof Error ? error.message : 'Unknown error'}`
+    );
+  }
+}
+
+/**
+ * Delete session from OS keychain
+ * @param accountId - User's DID or handle
+ */
+export async function deleteSession(accountId: string): Promise<boolean> {
+  try {
+    const entry = new AsyncEntry(SERVICE_NAME, accountId);
+    return await entry.deleteCredential();
+  } catch (error) {
+    throw new Error(
+      `Failed to delete session from keychain: ${error instanceof Error ? error.message : 'Unknown error'}`
+    );
+  }
+}
+
+/**
+ * Store metadata about current session for CLI to track active user
+ * Uses a special "current" account in keychain
+ */
+export async function saveCurrentSessionMetadata(metadata: SessionMetadata): Promise<void> {
+  const serialized = JSON.stringify(metadata);
+  const entry = new AsyncEntry(SERVICE_NAME, 'current-session-metadata');
+  await entry.setPassword(serialized);
+}
+
+/**
+ * Get metadata about current active session
+ */
+export async function getCurrentSessionMetadata(): Promise<SessionMetadata | null> {
+  const entry = new AsyncEntry(SERVICE_NAME, 'current-session-metadata');
+  const serialized = await entry.getPassword();
+  if (!serialized) {
+    return null;
+  }
+  return JSON.parse(serialized) as SessionMetadata;
+}
+
+/**
+ * Clear current session metadata
+ */
+export async function clearCurrentSessionMetadata(): Promise<void> {
+  const entry = new AsyncEntry(SERVICE_NAME, 'current-session-metadata');
+  await entry.deleteCredential();
+}

tests/lib/session.test.ts

···
+import type { AtpSessionData } from '@atproto/api';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import {
+  type SessionMetadata,
+  clearCurrentSessionMetadata,
+  deleteSession,
+  getCurrentSessionMetadata,
+  loadSession,
+  saveCurrentSessionMetadata,
+  saveSession,
+} from '../../src/lib/session.js';
+
+// Mock @napi-rs/keyring
+vi.mock('@napi-rs/keyring', () => {
+  const mockStorage = new Map<string, string>();
+
+  return {
+    AsyncEntry: vi.fn().mockImplementation((service: string, account: string) => {
+      const key = `${service}:${account}`;
+
+      return {
+        setPassword: vi.fn().mockImplementation(async (password: string) => {
+          mockStorage.set(key, password);
+        }),
+        getPassword: vi.fn().mockImplementation(async () => {
+          return mockStorage.get(key) || null;
+        }),
+        deleteCredential: vi.fn().mockImplementation(async () => {
+          return mockStorage.delete(key);
+        }),
+      };
+    }),
+    // Export the storage for test access
+    __mockStorage: mockStorage,
+  };
+});
+
+describe('Session Management', () => {
+  beforeEach(async () => {
+    // Clear mock storage before each test
+    // biome-ignore lint/suspicious/noExplicitAny: accessing mock-specific property
+    const keyring = (await import('@napi-rs/keyring')) as any;
+    if (keyring.__mockStorage instanceof Map) {
+      keyring.__mockStorage.clear();
+    }
+    vi.clearAllMocks();
+  });
+
+  afterEach(async () => {
+    // Clean up after each test
+    // biome-ignore lint/suspicious/noExplicitAny: accessing mock-specific property
+    const keyring = (await import('@napi-rs/keyring')) as any;
+    if (keyring.__mockStorage instanceof Map) {
+      keyring.__mockStorage.clear();
+    }
+  });
+
+  describe('saveSession', () => {
+    it('should save session to keychain using DID', async () => {
+      const sessionData: AtpSessionData = {
+        did: 'did:plc:test123',
+        handle: 'user.bsky.social',
+        email: '[e-mail]',
+        emailConfirmed: true,
+        active: true,
+        accessJwt: 'token123',
+        refreshJwt: 'refresh123',
+      };
+
+      await saveSession(sessionData);
+
+      // Verify session was stored
+      const loaded = await loadSession('did:plc:test123');
+      expect(loaded).toEqual(sessionData);
+    });
+
+    it('should save and retrieve session with all required fields', async () => {
+      const sessionData: AtpSessionData = {
+        did: 'did:plc:test456',
+        handle: 'user.bsky.social',
+        email: '[e-mail]',
+        emailConfirmed: true,
+        active: true,
+        accessJwt: 'token123',
+        refreshJwt: 'refresh123',
+      };
+
+      await saveSession(sessionData);
+
+      // Verify session was stored (keyed by DID)
+      const loaded = await loadSession('did:plc:test456');
+      expect(loaded).toEqual(sessionData);
+    });
+
+    it('should throw error if session has no DID or handle', async () => {
+      const sessionData = {
+        email: '[e-mail]',
+        accessJwt: 'token123',
+        refreshJwt: 'refresh123',
+      } as AtpSessionData;
+
+      await expect(saveSession(sessionData)).rejects.toThrow(
+        'Session data must include DID or handle'
+      );
+    });
+  });
+
+  describe('loadSession', () => {
+    it('should load session from keychain', async () => {
+      const sessionData: AtpSessionData = {
+        did: 'did:plc:test123',
+        handle: 'user.bsky.social',
+        active: true,
+        accessJwt: 'token123',
+        refreshJwt: 'refresh123',
+      };
+
+      await saveSession(sessionData);
+      const result = await loadSession('did:plc:test123');
+
+      expect(result).toEqual(sessionData);
+    });
+
+    it('should return null when session not found', async () => {
+      const result = await loadSession('did:plc:notfound');
+      expect(result).toBeNull();
+    });
+  });
+
+  describe('deleteSession', () => {
+    it('should delete session from keychain', async () => {
+      const sessionData: AtpSessionData = {
+        did: 'did:plc:test123',
+        handle: 'user.bsky.social',
+        active: true,
+        accessJwt: 'token123',
+        refreshJwt: 'refresh123',
+      };
+
+      await saveSession(sessionData);
+
+      // Verify session exists
+      let loaded = await loadSession('did:plc:test123');
+      expect(loaded).toEqual(sessionData);
+
+      // Delete session
+      const deleted = await deleteSession('did:plc:test123');
+      expect(deleted).toBe(true);
+
+      // Verify session no longer exists
+      loaded = await loadSession('did:plc:test123');
+      expect(loaded).toBeNull();
+    });
+
+    it('should return false when deleting non-existent session', async () => {
+      const deleted = await deleteSession('did:plc:notfound');
+      expect(deleted).toBe(false);
+    });
+  });
+
+  describe('session metadata', () => {
+    it('should save and load current session metadata', async () => {
+      const metadata: SessionMetadata = {
+        handle: 'user.bsky.social',
+        did: 'did:plc:test123',
+        pds: 'https://bsky.social',
+        lastUsed: new Date().toISOString(),
+      };
+
+      await saveCurrentSessionMetadata(metadata);
+      const result = await getCurrentSessionMetadata();
+
+      expect(result).toEqual(metadata);
+    });
+
+    it('should return null when no metadata exists', async () => {
+      const result = await getCurrentSessionMetadata();
+      expect(result).toBeNull();
+    });
+
+    it('should clear current session metadata', async () => {
+      const metadata: SessionMetadata = {
+        handle: 'user.bsky.social',
+        did: 'did:plc:test123',
+        pds: 'https://bsky.social',
+        lastUsed: new Date().toISOString(),
+      };
+
+      await saveCurrentSessionMetadata(metadata);
+
+      // Verify metadata exists
+      let result = await getCurrentSessionMetadata();
+      expect(result).toEqual(metadata);
+
+      // Clear metadata
+      await clearCurrentSessionMetadata();
+
+      // Verify metadata no longer exists
+      result = await getCurrentSessionMetadata();
+      expect(result).toBeNull();
+    });
+  });
+});