signet-auth 1.0.0-beta.0

package/src/index.ts

@@ -0,0 +1,109 @@
+// Public API exports for signet
+
+// Config types and loader
+export type {
+  SignetConfig,
+  BrowserConfig,
+  StorageConfig,
+  ProviderEntry,
+  RemoteEntry,
+} from './config/schema.js';
+export { loadConfig, saveConfig, getConfigPath } from './config/loader.js';
+export { validateConfig, buildStrategyConfig } from './config/validator.js';
+export { generateConfigYaml } from './config/generator.js';
+export type { InitOptions } from './config/generator.js';
+
+// Dependency wiring
+export { createAuthDeps } from './deps.js';
+export type { AuthDeps } from './deps.js';
+
+// Core types
+export type {
+  Credential,
+  CookieCredential,
+  BearerCredential,
+  ApiKeyCredential,
+  BasicCredential,
+  CredentialType,
+  Cookie,
+  ProviderConfig,
+  StrategyConfig,
+  StrategyName,
+  CookieStrategyConfig,
+  OAuth2StrategyConfig,
+  ApiTokenStrategyConfig,
+  BasicStrategyConfig,
+  StoredCredential,
+  StoredEntry,
+  ProviderStatus,
+  BrowserLaunchOptions,
+  ILogger,
+  XHeaderConfig,
+  AuthDiagnostics,
+} from './core/types.js';
+
+// Result type
+export { ok, err, isOk, isErr } from './core/result.js';
+export type { Result } from './core/result.js';
+
+// Errors
+export {
+  AuthError,
+  ProviderNotFoundError,
+  CredentialNotFoundError,
+  CredentialExpiredError,
+  CredentialTypeError,
+  RefreshError,
+  BrowserError,
+  BrowserLaunchError,
+  BrowserTimeoutError,
+  BrowserNavigationError,
+  StorageError,
+  ConfigError,
+  ManualSetupRequired,
+  SyncError,
+  RemoteNotFoundError,
+  SyncConflictError,
+} from './core/errors.js';
+
+// Interfaces (for implementing custom adapters/strategies)
+export type { IAuthStrategy, IAuthStrategyFactory, AuthContext } from './core/interfaces/auth-strategy.js';
+export type { IBrowserAdapter, IBrowserSession, IBrowserPage, NavigateOptions, PageRequest, PageResponse } from './core/interfaces/browser-adapter.js';
+export type { IStorage } from './core/interfaces/storage.js';
+export type { IProviderRegistry } from './core/interfaces/provider.js';
+
+// AuthManager
+export { AuthManager } from './auth-manager.js';
+
+// Strategy factories (for custom registration)
+export { CookieStrategyFactory } from './strategies/cookie.strategy.js';
+export { OAuth2StrategyFactory } from './strategies/oauth2.strategy.js';
+export { ApiTokenStrategyFactory } from './strategies/api-token.strategy.js';
+export { BasicAuthStrategyFactory } from './strategies/basic-auth.strategy.js';
+export { StrategyRegistry } from './strategies/registry.js';
+
+// Storage implementations
+export { DirectoryStorage } from './storage/directory-storage.js';
+export { CachedStorage } from './storage/cached-storage.js';
+export { MemoryStorage } from './storage/memory-storage.js';
+
+// Provider system
+export { ProviderRegistry } from './providers/provider-registry.js';
+export { createDefaultProvider } from './providers/auto-provision.js';
+
+// Browser adapters
+export { PlaywrightAdapter } from './browser/adapters/playwright.adapter.js';
+
+// CLI
+export { run as runCli, parseArgs } from './cli/main.js';
+
+// Sync
+export { SyncEngine } from './sync/sync-engine.js';
+export { SshTransport } from './sync/transports/ssh.js';
+export { getRemotes, getRemote, addRemote, removeRemote } from './sync/remote-config.js';
+export type { RemoteConfig, SyncResult } from './sync/types.js';
+
+// Utilities
+export { decodeJwt, isJwtExpired, getJwtExpiresAt } from './utils/jwt.js';
+export { parseDuration, formatDuration } from './utils/duration.js';
+export { buildUserAgent } from './utils/http.js';

package/src/providers/auto-provision.ts

@@ -0,0 +1,30 @@
+import type { ProviderConfig } from '../core/types.js';
+
+/**
+ * Create a default provider config from a URL.
+ * Used for auto-provisioning when no configured provider matches.
+ *
+ * Defaults to cookie strategy (most common for SSO).
+ * Provider ID = hostname, making it deterministic across restarts.
+ */
+export function createDefaultProvider(url: string): ProviderConfig {
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    // Treat as hostname — try adding https://
+    parsed = new URL(`https://${url}`);
+  }
+
+  const hostname = parsed.hostname;
+
+  return {
+    id: hostname,
+    name: hostname,
+    domains: [hostname],
+    entryUrl: `${parsed.protocol}//${parsed.host}/`,
+    strategy: 'cookie',
+    strategyConfig: { strategy: 'cookie' },
+    autoProvisioned: true,
+  };
+}

package/src/providers/config-loader.ts

@@ -0,0 +1,8 @@
+/**
+ * Provider config loader — delegates to the unified config system.
+ *
+ * This module is kept for backward compatibility. New code should use
+ * src/config/loader.ts directly.
+ */
+
+export { loadConfig } from '../config/loader.js';

package/src/providers/provider-registry.ts

@@ -0,0 +1,79 @@
+import type { IProviderRegistry } from '../core/interfaces/provider.js';
+import type { ProviderConfig } from '../core/types.js';
+
+/**
+ * Registry for provider configurations.
+ * Resolves URLs to providers using glob-style domain matching.
+ *
+ * Domain matching rules:
+ * - Exact: "api.example.com" matches only "api.example.com"
+ * - Wildcard: "*.example.com" matches "api.example.com", "www.example.com", etc.
+ * - Exact matches take priority over wildcard matches.
+ */
+export class ProviderRegistry implements IProviderRegistry {
+  private providers = new Map<string, ProviderConfig>();
+
+  constructor(initialProviders: ProviderConfig[] = []) {
+    for (const provider of initialProviders) {
+      this.providers.set(provider.id, provider);
+    }
+  }
+
+  resolve(url: string): ProviderConfig | null {
+    let hostname: string;
+    try {
+      hostname = new URL(url).hostname;
+    } catch {
+      // If URL parsing fails, treat the input as a hostname
+      hostname = url;
+    }
+
+    // First pass: exact domain match (higher priority)
+    for (const provider of this.providers.values()) {
+      for (const domain of provider.domains) {
+        if (!domain.includes('*') && hostname === domain) {
+          return provider;
+        }
+      }
+    }
+
+    // Second pass: glob/wildcard match
+    for (const provider of this.providers.values()) {
+      for (const domain of provider.domains) {
+        if (domain.includes('*') && matchGlob(hostname, domain)) {
+          return provider;
+        }
+      }
+    }
+
+    return null;
+  }
+
+  get(id: string): ProviderConfig | null {
+    return this.providers.get(id) ?? null;
+  }
+
+  list(): ProviderConfig[] {
+    return Array.from(this.providers.values());
+  }
+
+  register(provider: ProviderConfig): void {
+    this.providers.set(provider.id, provider);
+  }
+}
+
+/**
+ * Simple glob matching for domain patterns.
+ * Supports only "*" as a wildcard segment prefix.
+ * Examples:
+ *   "*.example.com" matches "api.example.com", "www.example.com"
+ *   "*.*.example.com" matches "a.b.example.com"
+ */
+function matchGlob(hostname: string, pattern: string): boolean {
+  // Convert glob to regex: *.example.com → ^[^.]+\.example\.com$
+  const escaped = pattern
+    .replace(/\./g, '\\.')
+    .replace(/\*/g, '[^.]+');
+  const regex = new RegExp(`^${escaped}$`, 'i');
+  return regex.test(hostname);
+}

package/src/storage/cached-storage.ts

@@ -0,0 +1,72 @@
+import type { IStorage } from '../core/interfaces/storage.js';
+import type { StoredCredential, StoredEntry } from '../core/types.js';
+
+interface CacheEntry {
+  value: StoredCredential | null;
+  expiresAt: number;
+}
+
+/**
+ * Decorator that adds a TTL cache over any IStorage implementation.
+ * Reads are cached; writes invalidate the cache for the affected key.
+ *
+ * Usage:
+ *   const storage = new CachedStorage(new DirectoryStorage(dir), { ttlMs: 5000 });
+ */
+export class CachedStorage implements IStorage {
+  private cache = new Map<string, CacheEntry>();
+  private listCache: { entries: StoredEntry[]; expiresAt: number } | null = null;
+
+  constructor(
+    private readonly inner: IStorage,
+    private readonly options: { ttlMs: number } = { ttlMs: 5000 },
+  ) {}
+
+  async get(providerId: string): Promise<StoredCredential | null> {
+    const cached = this.cache.get(providerId);
+    if (cached && Date.now() < cached.expiresAt) {
+      return cached.value;
+    }
+
+    const value = await this.inner.get(providerId);
+    this.cache.set(providerId, {
+      value,
+      expiresAt: Date.now() + this.options.ttlMs,
+    });
+    return value;
+  }
+
+  async set(providerId: string, credential: StoredCredential): Promise<void> {
+    this.invalidate(providerId);
+    await this.inner.set(providerId, credential);
+  }
+
+  async delete(providerId: string): Promise<void> {
+    this.invalidate(providerId);
+    await this.inner.delete(providerId);
+  }
+
+  async list(): Promise<StoredEntry[]> {
+    if (this.listCache && Date.now() < this.listCache.expiresAt) {
+      return this.listCache.entries;
+    }
+
+    const entries = await this.inner.list();
+    this.listCache = {
+      entries,
+      expiresAt: Date.now() + this.options.ttlMs,
+    };
+    return entries;
+  }
+
+  async clear(): Promise<void> {
+    this.cache.clear();
+    this.listCache = null;
+    await this.inner.clear();
+  }
+
+  private invalidate(providerId: string): void {
+    this.cache.delete(providerId);
+    this.listCache = null;
+  }
+}

package/src/storage/directory-storage.ts

@@ -0,0 +1,204 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import lockfile from 'proper-lockfile';
+import type { IStorage } from '../core/interfaces/storage.js';
+import type { StoredCredential, StoredEntry } from '../core/types.js';
+import { StorageError } from '../core/errors.js';
+
+interface ProviderFile {
+  version: 1;
+  providerId: string;
+  credential: StoredCredential['credential'];
+  strategy: string;
+  updatedAt: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Convert a provider ID into a human-readable, filesystem-safe filename.
+ * Replaces unsafe characters with underscores.
+ */
+function sanitizeId(providerId: string): string {
+  return providerId.replace(/[^a-zA-Z0-9._-]/g, '_');
+}
+
+/**
+ * Per-provider directory-based storage.
+ * Each provider's credentials are stored in a separate JSON file
+ * under the configured directory: `{dirPath}/{sanitizedProviderId}.json`.
+ *
+ * Uses per-file advisory locking via `proper-lockfile` and atomic writes
+ * (write to tmp + rename) for safe concurrent access.
+ */
+export class DirectoryStorage implements IStorage {
+  constructor(private readonly dirPath: string) {}
+
+  async get(providerId: string): Promise<StoredCredential | null> {
+    const filePath = this.filePathFor(providerId);
+    try {
+      const data = await this.readFile(filePath);
+      return this.toStoredCredential(data);
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+        return null;
+      }
+      throw new StorageError('read', (e as Error).message);
+    }
+  }
+
+  async set(providerId: string, credential: StoredCredential): Promise<void> {
+    const filePath = this.filePathFor(providerId);
+    await this.ensureDir();
+
+    const data: ProviderFile = {
+      version: 1,
+      providerId,
+      credential: credential.credential,
+      strategy: credential.strategy,
+      updatedAt: credential.updatedAt,
+      ...(credential.metadata ? { metadata: credential.metadata } : {}),
+    };
+
+    await this.withLock(filePath, async () => {
+      await this.atomicWrite(filePath, data);
+    });
+  }
+
+  async delete(providerId: string): Promise<void> {
+    const filePath = this.filePathFor(providerId);
+    try {
+      await fs.unlink(filePath);
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+        return; // No-op if not found
+      }
+      throw new StorageError('delete', (e as Error).message);
+    }
+  }
+
+  async list(): Promise<StoredEntry[]> {
+    let files: string[];
+    try {
+      files = await fs.readdir(this.dirPath);
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+        return [];
+      }
+      throw new StorageError('list', (e as Error).message);
+    }
+
+    const entries: StoredEntry[] = [];
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+
+      const filePath = path.join(this.dirPath, file);
+      try {
+        const data = await this.readFile(filePath);
+        entries.push({
+          providerId: data.providerId,
+          strategy: data.strategy,
+          updatedAt: data.updatedAt,
+          credentialType: data.credential.type,
+        });
+      } catch {
+        // Skip files that can't be read or parsed
+        continue;
+      }
+    }
+
+    return entries;
+  }
+
+  async clear(): Promise<void> {
+    let files: string[];
+    try {
+      files = await fs.readdir(this.dirPath);
+    } catch (e: unknown) {
+      if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+        return;
+      }
+      throw new StorageError('clear', (e as Error).message);
+    }
+
+    for (const file of files) {
+      if (!file.endsWith('.json')) continue;
+
+      const filePath = path.join(this.dirPath, file);
+      try {
+        await fs.unlink(filePath);
+      } catch (e: unknown) {
+        if ((e as NodeJS.ErrnoException).code !== 'ENOENT') {
+          throw new StorageError('clear', (e as Error).message);
+        }
+      }
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  private filePathFor(providerId: string): string {
+    return path.join(this.dirPath, `${sanitizeId(providerId)}.json`);
+  }
+
+  private async ensureDir(): Promise<void> {
+    await fs.mkdir(this.dirPath, { recursive: true });
+  }
+
+  private async readFile(filePath: string): Promise<ProviderFile> {
+    const content = await fs.readFile(filePath, 'utf-8');
+    const data = JSON.parse(content) as ProviderFile;
+    if (!data.version || !data.providerId || !data.credential) {
+      throw new StorageError('read', `Invalid provider file: ${filePath}`);
+    }
+    return data;
+  }
+
+  private toStoredCredential(data: ProviderFile): StoredCredential {
+    return {
+      credential: data.credential,
+      providerId: data.providerId,
+      strategy: data.strategy,
+      updatedAt: data.updatedAt,
+      ...(data.metadata ? { metadata: data.metadata } : {}),
+    };
+  }
+
+  private async atomicWrite(filePath: string, data: ProviderFile): Promise<void> {
+    try {
+      const content = JSON.stringify(data, null, 2);
+      const tmpPath = `${filePath}.tmp.${process.pid}`;
+      await fs.writeFile(tmpPath, content, 'utf-8');
+      await fs.rename(tmpPath, filePath);
+    } catch (e: unknown) {
+      throw new StorageError('write', (e as Error).message);
+    }
+  }
+
+  private async withLock<T>(filePath: string, fn: () => Promise<T>): Promise<T> {
+    await this.ensureDir();
+
+    // Use a separate .lock file so we never create dummy credential files
+    const lockPath = `${filePath}.lock`;
+    await fs.writeFile(lockPath, '', { flag: 'a' });
+
+    let release: (() => Promise<void>) | undefined;
+    try {
+      release = await lockfile.lock(lockPath, {
+        retries: { retries: 5, minTimeout: 100, maxTimeout: 1000 },
+        stale: 10000,
+      });
+      return await fn();
+    } catch (e: unknown) {
+      if ((e as Error).message?.includes('ELOCKED')) {
+        throw new StorageError('lock', 'Could not acquire file lock. Another process may be writing.');
+      }
+      throw e;
+    } finally {
+      if (release) {
+        await release().catch(() => {});
+      }
+    }
+  }
+}

package/src/storage/memory-storage.ts

@@ -0,0 +1,35 @@
+import type { IStorage } from '../core/interfaces/storage.js';
+import type { StoredCredential, StoredEntry } from '../core/types.js';
+
+/**
+ * In-memory storage implementation for testing.
+ * No persistence — data is lost when the process exits.
+ */
+export class MemoryStorage implements IStorage {
+  private store = new Map<string, StoredCredential>();
+
+  async get(providerId: string): Promise<StoredCredential | null> {
+    return this.store.get(providerId) ?? null;
+  }
+
+  async set(providerId: string, credential: StoredCredential): Promise<void> {
+    this.store.set(providerId, credential);
+  }
+
+  async delete(providerId: string): Promise<void> {
+    this.store.delete(providerId);
+  }
+
+  async list(): Promise<StoredEntry[]> {
+    return Array.from(this.store.entries()).map(([providerId, stored]) => ({
+      providerId,
+      strategy: stored.strategy,
+      updatedAt: stored.updatedAt,
+      credentialType: stored.credential.type,
+    }));
+  }
+
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+}

package/src/strategies/api-token.strategy.ts

@@ -0,0 +1,87 @@
+import type { IAuthStrategy, IAuthStrategyFactory, AuthContext } from '../core/interfaces/auth-strategy.js';
+import type { Credential, ApiKeyCredential, ProviderConfig } from '../core/types.js';
+import type { StrategyConfig, ApiTokenStrategyConfig } from '../config/schema.js';
+import type { Result } from '../core/result.js';
+import { ok, err } from '../core/result.js';
+import { ManualSetupRequired, type AuthError } from '../core/errors.js';
+import { decodeJwt } from '../utils/jwt.js';
+
+const DEFAULT_HEADER_NAME = 'Authorization';
+const DEFAULT_HEADER_PREFIX = 'Bearer';
+const DEFAULT_SETUP_INSTRUCTIONS = 'Please provide an API token or Personal Access Token.';
+
+/**
+ * Static API token strategy.
+ * User provides the token manually — no browser automation needed.
+ * Optionally checks JWT expiry if the token is a JWT.
+ */
+class ApiTokenStrategy implements IAuthStrategy {
+  private readonly headerName: string;
+  private readonly headerPrefix: string;
+  private readonly setupInstructions: string;
+
+  constructor(config: ApiTokenStrategyConfig) {
+    this.headerName = config.headerName ?? DEFAULT_HEADER_NAME;
+    this.headerPrefix = config.headerPrefix ?? DEFAULT_HEADER_PREFIX;
+    this.setupInstructions = config.setupInstructions ?? DEFAULT_SETUP_INSTRUCTIONS;
+  }
+
+  validate(credential: Credential): Result<boolean, AuthError> {
+    if (credential.type !== 'api-key') {
+      return ok(false);
+    }
+
+    if (!credential.key || credential.key.trim() === '') {
+      return ok(false);
+    }
+
+    // If the key looks like a JWT, check its expiry
+    const jwt = decodeJwt(credential.key);
+    if (jwt?.exp) {
+      const expiresAtMs = jwt.exp * 1000;
+      if (Date.now() >= expiresAtMs) {
+        return ok(false);
+      }
+    }
+
+    return ok(true);
+  }
+
+  async authenticate(
+    provider: ProviderConfig,
+  ): Promise<Result<Credential, AuthError>> {
+    // API tokens cannot be obtained automatically — user must provide them.
+    return err(
+      new ManualSetupRequired(
+        provider.id,
+        this.setupInstructions,
+      ),
+    );
+  }
+
+  async refresh(): Promise<Result<Credential | null, AuthError>> {
+    // Static tokens cannot be refreshed
+    return ok(null);
+  }
+
+  applyToRequest(credential: Credential): Record<string, string> {
+    if (credential.type !== 'api-key') return {};
+
+    const value = this.headerPrefix
+      ? `${this.headerPrefix} ${credential.key}`
+      : credential.key;
+
+    return { [this.headerName]: value };
+  }
+}
+
+export class ApiTokenStrategyFactory implements IAuthStrategyFactory {
+  readonly name = 'api-token';
+
+  create(config: StrategyConfig): IAuthStrategy {
+    if (config.strategy !== 'api-token') {
+      throw new Error(`ApiTokenStrategyFactory received wrong config type: ${config.strategy}`);
+    }
+    return new ApiTokenStrategy(config);
+  }
+}

package/src/strategies/basic-auth.strategy.ts

@@ -0,0 +1,64 @@
+import type { IAuthStrategy, IAuthStrategyFactory } from '../core/interfaces/auth-strategy.js';
+import type { Credential, ProviderConfig } from '../core/types.js';
+import type { StrategyConfig, BasicStrategyConfig } from '../config/schema.js';
+import type { Result } from '../core/result.js';
+import { ok, err } from '../core/result.js';
+import { ManualSetupRequired, type AuthError } from '../core/errors.js';
+
+/**
+ * Basic authentication strategy.
+ * User provides username + password — no browser automation needed.
+ * Produces an Authorization: Basic <base64> header.
+ */
+class BasicAuthStrategy implements IAuthStrategy {
+  private readonly setupInstructions?: string;
+
+  constructor(config: BasicStrategyConfig) {
+    this.setupInstructions = config.setupInstructions;
+  }
+
+  validate(credential: Credential): Result<boolean, AuthError> {
+    if (credential.type !== 'basic') return ok(false);
+    return ok(
+      credential.username.length > 0 && credential.password.length > 0,
+    );
+  }
+
+  async authenticate(
+    provider: ProviderConfig,
+  ): Promise<Result<Credential, AuthError>> {
+    return err(
+      new ManualSetupRequired(
+        provider.id,
+        this.setupInstructions ??
+          provider.setupInstructions ??
+          'Please provide username and password for basic authentication.',
+      ),
+    );
+  }
+
+  async refresh(): Promise<Result<Credential | null, AuthError>> {
+    return ok(null);
+  }
+
+  applyToRequest(credential: Credential): Record<string, string> {
+    if (credential.type !== 'basic') return {};
+
+    const encoded = Buffer.from(
+      `${credential.username}:${credential.password}`,
+    ).toString('base64');
+
+    return { Authorization: `Basic ${encoded}` };
+  }
+}
+
+export class BasicAuthStrategyFactory implements IAuthStrategyFactory {
+  readonly name = 'basic';
+
+  create(config: StrategyConfig): IAuthStrategy {
+    if (config.strategy !== 'basic') {
+      throw new Error(`BasicAuthStrategyFactory received wrong config type: ${config.strategy}`);
+    }
+    return new BasicAuthStrategy(config);
+  }
+}