signet-auth 1.0.0-beta.0

package/src/strategies/cookie.strategy.ts

@@ -0,0 +1,153 @@
+import type { IAuthStrategy, IAuthStrategyFactory, AuthContext } from '../core/interfaces/auth-strategy.js';
+import type { Credential, CookieCredential, ProviderConfig } from '../core/types.js';
+import type { StrategyConfig, CookieStrategyConfig } from '../config/schema.js';
+import type { Result } from '../core/result.js';
+import { ok, err } from '../core/result.js';
+import { BrowserError, type AuthError } from '../core/errors.js';
+import { parseDuration } from '../utils/duration.js';
+import { runHybridFlow } from '../browser/flows/hybrid-flow.js';
+import { isLoginPage } from '../browser/flows/form-login.flow.js';
+import { hasOAuthTokens } from '../browser/flows/oauth-consent.flow.js';
+
+const DEFAULT_TTL = '24h';
+
+/**
+ * Cookie-based authentication strategy.
+ * Launches a browser, navigates to the login page, waits for user auth,
+ * then extracts cookies from the authenticated session.
+ */
+class CookieStrategy implements IAuthStrategy {
+  private readonly ttlMs: number;
+  private readonly requiredCookies: string[];
+  private readonly strategyConfig: CookieStrategyConfig;
+
+  constructor(config: CookieStrategyConfig) {
+    this.strategyConfig = config;
+    this.ttlMs = parseDuration(config.ttl ?? DEFAULT_TTL);
+    this.requiredCookies = config.requiredCookies ?? [];
+  }
+
+  validate(credential: Credential): Result<boolean, AuthError> {
+    if (credential.type !== 'cookie') return ok(false);
+
+    // Check TTL based on obtainedAt
+    const obtainedAt = new Date(credential.obtainedAt).getTime();
+    if (Date.now() - obtainedAt > this.ttlMs) {
+      return ok(false);
+    }
+
+    // Check individual cookie expiry
+    const now = Date.now() / 1000;
+    const hasExpired = credential.cookies.some(
+      c => c.expires > 0 && c.expires < now,
+    );
+    if (hasExpired) return ok(false);
+
+    // Ensure we have at least one cookie
+    if (credential.cookies.length === 0) return ok(false);
+
+    return ok(true);
+  }
+
+  async authenticate(
+    provider: ProviderConfig,
+    context: AuthContext,
+  ): Promise<Result<Credential, AuthError>> {
+    const adapter = context.browserAdapter;
+
+    if (!provider.entryUrl) {
+      return err(new BrowserError(
+        `Provider "${provider.id}" requires an entryUrl for cookie authentication.`,
+        provider.id,
+      ));
+    }
+
+    return await runHybridFlow<Credential>(adapter, {
+      entryUrl: provider.entryUrl,
+      browserConfig: context.browserConfig,
+      forceVisible: provider.forceVisible ?? false,
+      // Cookie auth needs networkidle to ensure all post-SSO Set-Cookie responses arrive
+      waitUntil: 'networkidle',
+      xHeaders: provider.xHeaders,
+      providerDomains: provider.domains,
+
+      isAuthenticated: async (page) => {
+        // If requiredCookies is set, auth is complete only when those cookies exist
+        if (this.requiredCookies.length > 0) {
+          const urls = provider.domains.map(d => `https://${d}/`);
+          const cookies = await page.cookies(urls);
+          const cookieNames = new Set(cookies.map(c => c.name));
+          return this.requiredCookies.every(name => cookieNames.has(name));
+        }
+
+        // Default: auth is complete when we're no longer on a login page
+        const onLoginPage = await isLoginPage(page);
+        return !onLoginPage;
+      },
+
+      extractCredentials: async (page, xHeaders, meta) => {
+        // Only extract cookies matching this provider's domains (not all cookies from the shared profile)
+        // Include both domain roots AND current page URL (to capture path-scoped cookies like /wiki)
+        const urls = provider.domains.map(d => `https://${d}/`);
+        const currentUrl = page.url();
+        if (currentUrl && !urls.includes(currentUrl)) urls.push(currentUrl);
+        const cookies = await page.cookies(urls);
+        if (cookies.length === 0) {
+          return err(new BrowserError(
+            'No cookies found after authentication.',
+            provider.id,
+          ));
+        }
+
+        // Probe for OAuth tokens in browser storage (strategy mismatch detection)
+        const oauthTokensDetected = await hasOAuthTokens(page).catch(() => false);
+
+        const credential: CookieCredential = {
+          type: 'cookie',
+          cookies,
+          obtainedAt: new Date().toISOString(),
+          ...(xHeaders && Object.keys(xHeaders).length > 0 ? { xHeaders } : {}),
+        };
+
+        // Attach diagnostics metadata for post-auth validation
+        (credential as any).__diagnostics = {
+          authDetectedImmediately: meta?.immediateAuth ?? false,
+          oauthTokensDetected,
+          cookiesExtracted: cookies.length,
+        };
+
+        return ok(credential);
+      },
+    });
+  }
+
+  async refresh(): Promise<Result<Credential | null, AuthError>> {
+    // Cookies can't be refreshed — must re-authenticate via browser
+    return ok(null);
+  }
+
+  applyToRequest(credential: Credential): Record<string, string> {
+    if (credential.type !== 'cookie') return {};
+
+    const cookieStr = credential.cookies
+      .map(c => `${c.name}=${c.value}`)
+      .join('; ');
+
+    // Apply x-headers first, then set Cookie so it always wins
+    const headers: Record<string, string> = { ...credential.xHeaders };
+    headers['Cookie'] = cookieStr;
+
+    return headers;
+  }
+}
+
+export class CookieStrategyFactory implements IAuthStrategyFactory {
+  readonly name = 'cookie';
+
+  create(config: StrategyConfig): IAuthStrategy {
+    if (config.strategy !== 'cookie') {
+      throw new Error(`CookieStrategyFactory received wrong config type: ${config.strategy}`);
+    }
+    return new CookieStrategy(config);
+  }
+}

package/src/strategies/oauth2.strategy.ts

@@ -0,0 +1,178 @@
+import type { IAuthStrategy, IAuthStrategyFactory, AuthContext } from '../core/interfaces/auth-strategy.js';
+import type { Credential, BearerCredential, ProviderConfig } from '../core/types.js';
+import type { StrategyConfig, OAuth2StrategyConfig } from '../config/schema.js';
+import type { Result } from '../core/result.js';
+import { ok, err } from '../core/result.js';
+import { BrowserError, RefreshError, type AuthError } from '../core/errors.js';
+import { runHybridFlow } from '../browser/flows/hybrid-flow.js';
+import { extractOAuthTokens, hasOAuthTokens } from '../browser/flows/oauth-consent.flow.js';
+import { isLoginPage } from '../browser/flows/form-login.flow.js';
+
+const EXPIRY_BUFFER_MS = 5 * 60 * 1000; // 5 minutes
+
+/**
+ * OAuth2 authentication strategy.
+ * Supports browser-based authorization with token extraction from localStorage,
+ * and silent refresh using refresh tokens.
+ */
+class OAuth2Strategy implements IAuthStrategy {
+  private readonly strategyConfig: OAuth2StrategyConfig;
+
+  constructor(config: OAuth2StrategyConfig) {
+    this.strategyConfig = config;
+  }
+
+  validate(credential: Credential): Result<boolean, AuthError> {
+    if (credential.type !== 'bearer') return ok(false);
+
+    if (!credential.accessToken || credential.accessToken.trim() === '') {
+      return ok(false);
+    }
+
+    // Check expiry with buffer
+    if (credential.expiresAt) {
+      const expiresAtMs = new Date(credential.expiresAt).getTime();
+      if (Date.now() + EXPIRY_BUFFER_MS >= expiresAtMs) {
+        return ok(false);
+      }
+    }
+
+    return ok(true);
+  }
+
+  async authenticate(
+    provider: ProviderConfig,
+    context: AuthContext,
+  ): Promise<Result<Credential, AuthError>> {
+    const adapter = context.browserAdapter;
+
+    if (!provider.entryUrl) {
+      return err(new BrowserError(
+        `Provider "${provider.id}" requires an entryUrl for OAuth2 authentication.`,
+        provider.id,
+      ));
+    }
+
+    return await runHybridFlow<Credential>(adapter, {
+      entryUrl: provider.entryUrl,
+      browserConfig: context.browserConfig,
+      forceVisible: provider.forceVisible ?? false,
+      xHeaders: provider.xHeaders,
+      providerDomains: provider.domains,
+
+      isAuthenticated: async (page) => {
+        const onLogin = await isLoginPage(page);
+        if (onLogin) return false;
+        return await hasOAuthTokens(page, this.strategyConfig.audiences);
+      },
+
+      extractCredentials: async (page, xHeaders, meta) => {
+        const result = await extractOAuthTokens(page, {
+          audiences: this.strategyConfig.audiences,
+          extractRefreshToken: true,
+          maxRetries: 8, // Up to 16s of waiting for MSAL to store tokens
+        });
+        // Attach captured headers to the bearer credential
+        if (result.ok && xHeaders && Object.keys(xHeaders).length > 0) {
+          const cred = result.value as BearerCredential;
+          cred.xHeaders = xHeaders;
+        }
+        // Attach diagnostics metadata for post-auth validation
+        if (result.ok) {
+          (result.value as any).__diagnostics = {
+            authDetectedImmediately: meta?.immediateAuth ?? false,
+            oauthTokensDetected: true,
+            cookiesExtracted: 0,
+          };
+        }
+        return result;
+      },
+    });
+  }
+
+  async refresh(
+    credential: Credential,
+  ): Promise<Result<Credential | null, AuthError>> {
+    if (credential.type !== 'bearer') return ok(null);
+    if (!credential.refreshToken) return ok(null);
+
+    if (!this.strategyConfig.tokenEndpoint || !this.strategyConfig.clientId) {
+      return ok(null); // Can't refresh without endpoint and client ID
+    }
+
+    try {
+      const body = new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: this.strategyConfig.clientId,
+        refresh_token: credential.refreshToken,
+      });
+
+      if (this.strategyConfig.scopes && this.strategyConfig.scopes.length > 0) {
+        body.set('scope', this.strategyConfig.scopes.join(' '));
+      }
+
+      const response = await fetch(this.strategyConfig.tokenEndpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: body.toString(),
+      });
+
+      if (!response.ok) {
+        const errorBody = await response.text();
+        return err(new RefreshError(
+          credential.tokenEndpoint ?? 'unknown',
+          `Token refresh failed (${response.status}): ${errorBody}`,
+        ));
+      }
+
+      const tokenResponse = await response.json() as {
+        access_token: string;
+        refresh_token?: string;
+        expires_in?: number;
+        scope?: string;
+      };
+
+      const expiresAt = tokenResponse.expires_in
+        ? new Date(Date.now() + tokenResponse.expires_in * 1000).toISOString()
+        : undefined;
+
+      const refreshed: BearerCredential = {
+        type: 'bearer',
+        accessToken: tokenResponse.access_token,
+        refreshToken: tokenResponse.refresh_token ?? credential.refreshToken,
+        expiresAt,
+        scopes: tokenResponse.scope?.split(' '),
+        tokenEndpoint: credential.tokenEndpoint,
+        ...(credential.xHeaders ? { xHeaders: credential.xHeaders } : {}),
+      };
+
+      return ok(refreshed);
+    } catch (e: unknown) {
+      return err(new RefreshError(
+        credential.tokenEndpoint ?? 'unknown',
+        (e as Error).message,
+      ));
+    }
+  }
+
+  applyToRequest(credential: Credential): Record<string, string> {
+    if (credential.type !== 'bearer') return {};
+
+    // Apply x-headers first, then set Authorization so it always wins
+    const headers: Record<string, string> = { ...credential.xHeaders };
+    headers['Authorization'] = `Bearer ${credential.accessToken}`;
+
+    return headers;
+  }
+}
+
+export class OAuth2StrategyFactory implements IAuthStrategyFactory {
+  readonly name = 'oauth2';
+
+  create(config: StrategyConfig): IAuthStrategy {
+    if (config.strategy !== 'oauth2') {
+      throw new Error(`OAuth2StrategyFactory received wrong config type: ${config.strategy}`);
+    }
+    return new OAuth2Strategy(config);
+  }
+}

package/src/strategies/registry.ts

@@ -0,0 +1,34 @@
+import type { IAuthStrategy, IAuthStrategyFactory } from '../core/interfaces/auth-strategy.js';
+import type { StrategyConfig } from '../config/schema.js';
+import { ConfigError } from '../core/errors.js';
+
+/**
+ * Registry that maps strategy names to their factories.
+ * Built-in strategies are registered at startup; users can add custom ones.
+ */
+export class StrategyRegistry {
+  private factories = new Map<string, IAuthStrategyFactory>();
+
+  register(factory: IAuthStrategyFactory): void {
+    this.factories.set(factory.name, factory);
+  }
+
+  get(name: string, config: StrategyConfig): IAuthStrategy {
+    const factory = this.factories.get(name);
+    if (!factory) {
+      const available = Array.from(this.factories.keys()).join(', ');
+      throw new ConfigError(
+        `Unknown strategy "${name}". Available strategies: ${available || 'none'}`,
+      );
+    }
+    return factory.create(config);
+  }
+
+  has(name: string): boolean {
+    return this.factories.has(name);
+  }
+
+  list(): string[] {
+    return Array.from(this.factories.keys());
+  }
+}

package/src/sync/remote-config.ts

@@ -0,0 +1,60 @@
+/**
+ * Remote configuration — reads/writes from the unified ~/.signet/config.yaml.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import YAML from 'yaml';
+import type { RemoteConfig } from './types.js';
+
+const CONFIG_PATH = path.join(os.homedir(), '.signet', 'config.yaml');
+
+interface ConfigFile {
+  browser?: Record<string, unknown>;
+  storage?: Record<string, unknown>;
+  providers?: Record<string, unknown>;
+  remotes?: Record<string, Omit<RemoteConfig, 'name'>>;
+}
+
+async function loadRawConfig(): Promise<ConfigFile> {
+  try {
+    const content = await fs.readFile(CONFIG_PATH, 'utf-8');
+    return YAML.parse(content) ?? {};
+  } catch (e: unknown) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return {};
+    throw e;
+  }
+}
+
+async function saveRawConfig(config: ConfigFile): Promise<void> {
+  await fs.mkdir(path.dirname(CONFIG_PATH), { recursive: true });
+  await fs.writeFile(CONFIG_PATH, YAML.stringify(config), 'utf-8');
+}
+
+export async function getRemotes(): Promise<RemoteConfig[]> {
+  const config = await loadRawConfig();
+  if (!config.remotes) return [];
+  return Object.entries(config.remotes).map(([name, r]) => ({ name, ...r }));
+}
+
+export async function getRemote(name: string): Promise<RemoteConfig | null> {
+  const remotes = await getRemotes();
+  return remotes.find(r => r.name === name) ?? null;
+}
+
+export async function addRemote(remote: RemoteConfig): Promise<void> {
+  const config = await loadRawConfig();
+  if (!config.remotes) config.remotes = {};
+  const { name, ...rest } = remote;
+  config.remotes[name] = rest;
+  await saveRawConfig(config);
+}
+
+export async function removeRemote(name: string): Promise<boolean> {
+  const config = await loadRawConfig();
+  if (!config.remotes || !config.remotes[name]) return false;
+  delete config.remotes[name];
+  await saveRawConfig(config);
+  return true;
+}

package/src/sync/sync-engine.ts

@@ -0,0 +1,113 @@
+import type { IStorage } from '../core/interfaces/storage.js';
+import type { RemoteConfig, SyncResult } from './types.js';
+import { SshTransport } from './transports/ssh.js';
+
+function sanitizeId(providerId: string): string {
+  return providerId.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+export class SyncEngine {
+  private readonly transport: SshTransport;
+
+  constructor(
+    private readonly storage: IStorage,
+    private readonly remote: RemoteConfig,
+  ) {
+    this.transport = new SshTransport();
+  }
+
+  async push(providerIds?: string[], force = false): Promise<SyncResult> {
+    const result: SyncResult = { pushed: [], pulled: [], skipped: [], errors: [] };
+
+    // Get local entries
+    const localEntries = await this.storage.list();
+    const toPush = providerIds
+      ? localEntries.filter(e => providerIds.includes(e.providerId))
+      : localEntries;
+
+    if (toPush.length === 0) {
+      return result;
+    }
+
+    // Get remote entries for conflict detection
+    const remoteEntries = await this.transport.listRemote(this.remote);
+    const remoteMap = new Map(remoteEntries.map(e => [e.providerId, e]));
+
+    for (const entry of toPush) {
+      try {
+        const filename = `${sanitizeId(entry.providerId)}.json`;
+        const remoteEntry = remoteMap.get(entry.providerId);
+
+        // Conflict detection: skip if remote is newer
+        if (remoteEntry && !force) {
+          const localTime = new Date(entry.updatedAt).getTime();
+          const remoteTime = new Date(remoteEntry.updatedAt).getTime();
+          if (remoteTime > localTime) {
+            result.skipped.push(entry.providerId);
+            continue;
+          }
+        }
+
+        const stored = await this.storage.get(entry.providerId);
+        if (!stored) continue;
+
+        await this.transport.writeRemote(this.remote, filename, stored);
+        result.pushed.push(entry.providerId);
+      } catch (e: unknown) {
+        result.errors.push({
+          providerId: entry.providerId,
+          error: (e as Error).message,
+        });
+      }
+    }
+
+    return result;
+  }
+
+  async pull(providerIds?: string[], force = false): Promise<SyncResult> {
+    const result: SyncResult = { pushed: [], pulled: [], skipped: [], errors: [] };
+
+    // Get remote entries
+    const remoteEntries = await this.transport.listRemote(this.remote);
+    const toPull = providerIds
+      ? remoteEntries.filter(e => providerIds.includes(e.providerId))
+      : remoteEntries;
+
+    if (toPull.length === 0) {
+      return result;
+    }
+
+    for (const entry of toPull) {
+      try {
+        // Conflict detection
+        if (!force) {
+          const local = await this.storage.get(entry.providerId);
+          if (local) {
+            const localTime = new Date(local.updatedAt).getTime();
+            const remoteTime = new Date(entry.updatedAt).getTime();
+            if (localTime > remoteTime) {
+              result.skipped.push(entry.providerId);
+              continue;
+            }
+          }
+        }
+
+        const stored = await this.transport.readRemote(this.remote, entry.filename);
+        if (!stored) {
+          result.errors.push({ providerId: entry.providerId, error: 'Failed to read from remote' });
+          continue;
+        }
+
+        await this.storage.set(entry.providerId, stored);
+        result.pulled.push(entry.providerId);
+      } catch (e: unknown) {
+        result.errors.push({
+          providerId: entry.providerId,
+          error: (e as Error).message,
+        });
+      }
+    }
+
+    return result;
+  }
+}

package/src/sync/transports/ssh.ts

@@ -0,0 +1,130 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'node:path';
+import os from 'node:os';
+import type { RemoteConfig } from '../types.js';
+import type { StoredCredential } from '../../core/types.js';
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_REMOTE_PATH = '~/.signet/credentials';
+
+export class SshTransport {
+
+  private sshArgs(remote: RemoteConfig): string[] {
+    const args: string[] = [];
+    if (remote.sshKey) args.push('-i', remote.sshKey);
+    args.push('-o', 'BatchMode=yes', '-o', 'StrictHostKeyChecking=accept-new');
+    return args;
+  }
+
+  private remoteTarget(remote: RemoteConfig): string {
+    const user = remote.user ?? os.userInfo().username;
+    return `${user}@${remote.host}`;
+  }
+
+  private remotePath(remote: RemoteConfig): string {
+    return remote.path ?? DEFAULT_REMOTE_PATH;
+  }
+
+  /** List provider files on the remote */
+  async listRemote(remote: RemoteConfig): Promise<{ providerId: string; updatedAt: string; filename: string }[]> {
+    const target = this.remoteTarget(remote);
+    const rpath = this.remotePath(remote);
+
+    try {
+      const { stdout } = await execFileAsync('ssh', [
+        ...this.sshArgs(remote),
+        target,
+        `find ${rpath} -maxdepth 1 -name '*.json' -print 2>/dev/null || true`,
+      ]);
+
+      const files = stdout.trim().split('\n').filter(Boolean);
+      const entries: { providerId: string; updatedAt: string; filename: string }[] = [];
+
+      for (const file of files) {
+        const filename = path.basename(file);
+        try {
+          const { stdout: content } = await execFileAsync('ssh', [
+            ...this.sshArgs(remote),
+            target,
+            `cat "${file}"`,
+          ]);
+          const data = JSON.parse(content);
+          entries.push({
+            providerId: data.providerId,
+            updatedAt: data.updatedAt,
+            filename,
+          });
+        } catch {
+          // Skip unreadable files
+        }
+      }
+
+      return entries;
+    } catch {
+      return [];
+    }
+  }
+
+  /** Read a single credential from remote */
+  async readRemote(remote: RemoteConfig, filename: string): Promise<StoredCredential | null> {
+    const target = this.remoteTarget(remote);
+    const rpath = this.remotePath(remote);
+
+    try {
+      const { stdout } = await execFileAsync('ssh', [
+        ...this.sshArgs(remote),
+        target,
+        `cat ${rpath}/"${filename}"`,
+      ]);
+      const data = JSON.parse(stdout);
+      return {
+        credential: data.credential,
+        providerId: data.providerId,
+        strategy: data.strategy,
+        updatedAt: data.updatedAt,
+        ...(data.metadata ? { metadata: data.metadata } : {}),
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  /** Write a credential file to remote via ssh pipe (avoids scp tilde issues) */
+  async writeRemote(remote: RemoteConfig, filename: string, stored: StoredCredential): Promise<void> {
+    const rpath = this.remotePath(remote);
+
+    const data = {
+      version: 1,
+      providerId: stored.providerId,
+      credential: stored.credential,
+      strategy: stored.strategy,
+      updatedAt: stored.updatedAt,
+      ...(stored.metadata ? { metadata: stored.metadata } : {}),
+    };
+
+    const content = JSON.stringify(data, null, 2);
+
+    // Write via ssh stdin pipe — avoids scp's tilde expansion issues
+    // The remote shell handles ~ expansion in mkdir and cat redirect
+    await this.sshWrite(remote, `mkdir -p ${rpath} && cat > ${rpath}/"${filename}"`, content);
+  }
+
+  private sshWrite(remote: RemoteConfig, command: string, stdin: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const target = this.remoteTarget(remote);
+      const proc = execFile('ssh', [
+        ...this.sshArgs(remote),
+        target,
+        command,
+      ], (error) => {
+        if (error) reject(error);
+        else resolve();
+      });
+
+      proc.stdin?.write(stdin);
+      proc.stdin?.end();
+    });
+  }
+}

package/src/sync/types.ts

@@ -0,0 +1,15 @@
+export interface RemoteConfig {
+  name: string;
+  type: 'ssh';
+  host: string;
+  user?: string;
+  path?: string;       // defaults to ~/.signet/credentials
+  sshKey?: string;     // path to SSH key
+}
+
+export interface SyncResult {
+  pushed: string[];    // provider IDs successfully synced
+  pulled: string[];
+  skipped: string[];   // conflicts (skipped unless --force)
+  errors: { providerId: string; error: string }[];
+}