signet-auth 1.0.0-beta.0

package/src/config/generator.ts

@@ -0,0 +1,122 @@
+/**
+ * Config YAML generator for signet.
+ * Uses template literals (NOT YAML.stringify) to preserve comments.
+ */
+
+export interface InitOptions {
+  channel: string;
+  browserDataDir: string;
+  credentialsDir: string;
+  headlessTimeout: number;
+  visibleTimeout: number;
+  waitUntil: string;
+  providers?: Array<{
+    id: string;
+    domains: string[];
+    strategy: string;
+    entryUrl?: string;
+    config?: Record<string, unknown>;
+  }>;
+}
+
+function yamlArray(items: string[]): string {
+  return `[${items.map(d => `"${d}"`).join(', ')}]`;
+}
+
+function renderProviderConfig(config: Record<string, unknown>, indent: number): string {
+  const spaces = ' '.repeat(indent);
+  const lines: string[] = [];
+  for (const [key, value] of Object.entries(config)) {
+    if (Array.isArray(value)) {
+      lines.push(`${spaces}${key}: ${yamlArray(value as string[])}`);
+    } else if (typeof value === 'string') {
+      lines.push(`${spaces}${key}: ${value}`);
+    } else if (typeof value === 'number' || typeof value === 'boolean') {
+      lines.push(`${spaces}${key}: ${String(value)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function renderProvider(provider: {
+  id: string;
+  domains: string[];
+  strategy: string;
+  entryUrl?: string;
+  config?: Record<string, unknown>;
+}): string {
+  const lines: string[] = [];
+  lines.push(`  ${provider.id}:`);
+  lines.push(`    domains: ${yamlArray(provider.domains)}`);
+  lines.push(`    strategy: ${provider.strategy}`);
+  if (provider.entryUrl) {
+    lines.push(`    entryUrl: ${provider.entryUrl}`);
+  }
+  if (provider.config && Object.keys(provider.config).length > 0) {
+    lines.push('    config:');
+    lines.push(renderProviderConfig(provider.config, 6));
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Generate a commented YAML config string from the given options.
+ * Uses template literals to preserve comments and formatting.
+ */
+export function generateConfigYaml(options: InitOptions): string {
+  const providerSection = options.providers && options.providers.length > 0
+    ? options.providers.map(p => renderProvider(p)).join('\n\n')
+    : `  # No providers configured yet.
+  # Add providers here or use "sig login <url>" for auto-provisioning.
+  #
+  # Example — cookie-based (SSO):
+  #   my-jira:
+  #     domains: ["jira.example.com"]
+  #     strategy: cookie
+  #     config:
+  #       ttl: "12h"
+  #
+  # Example — API token:
+  #   github:
+  #     domains: ["github.com", "api.github.com"]
+  #     strategy: api-token
+  #     config:
+  #       headerName: Authorization
+  #       headerPrefix: Bearer`;
+
+  return `# Signet unified configuration
+# Generated by "sig init". All configuration lives in this single file.
+# Documentation: https://github.com/pylon/signet
+
+# Browser settings (required)
+# Controls browser automation for cookie and OAuth2 authentication.
+browser:
+  browserDataDir: ${options.browserDataDir}   # Persistent browser profile directory
+  channel: ${options.channel}                        # Browser channel (chrome, msedge, chromium)
+  headlessTimeout: ${options.headlessTimeout}                 # Timeout for headless auth attempt (ms)
+  visibleTimeout: ${options.visibleTimeout}                # Timeout for visible/user-assisted auth (ms)
+  waitUntil: ${options.waitUntil}                       # Page load condition (load, networkidle, domcontentloaded, commit)
+
+# Storage settings (required)
+# Where per-provider credential files are stored.
+storage:
+  credentialsDir: ${options.credentialsDir}   # Per-provider credential files directory
+
+# Remote credential stores (optional)
+# Sync credentials to/from remote machines via SSH.
+# remotes:
+#   dev-server:
+#     type: ssh
+#     host: dev.example.com
+#     user: deploy
+#     path: ~/.signet/credentials
+#     sshKey: ~/.ssh/id_ed25519
+
+# Provider configurations
+# Cookie-based providers (most SSO systems) don't need config at all —
+# just call "sig login https://jira.example.com" and it auto-provisions.
+# Only create entries here for OAuth2, API tokens, or advanced settings.
+providers:
+${providerSection}
+`;
+}

package/src/config/loader.ts

@@ -0,0 +1,70 @@
+/**
+ * Single config file loader for signet.
+ * Reads ONLY ~/.signet/config.yaml — no cascade, no env vars.
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import YAML from 'yaml';
+import type { Result } from '../core/result.js';
+import { ok, err } from '../core/result.js';
+import { ConfigError, type AuthError } from '../core/errors.js';
+import type { SignetConfig } from './schema.js';
+import { validateConfig } from './validator.js';
+
+const CONFIG_PATH = path.join(os.homedir(), '.signet', 'config.yaml');
+
+/**
+ * Load and validate the unified config from ~/.signet/config.yaml.
+ * Returns Result<SignetConfig, AuthError>.
+ */
+export async function loadConfig(): Promise<Result<SignetConfig, AuthError>> {
+  let content: string;
+  try {
+    content = await fs.readFile(CONFIG_PATH, 'utf-8');
+  } catch (e: unknown) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+      return err(new ConfigError(
+        `Config file not found: ${CONFIG_PATH}. ` +
+        'Create it with browser.browserDataDir, storage.credentialsDir, and providers sections.',
+      ));
+    }
+    return err(new ConfigError(
+      `Failed to read config from ${CONFIG_PATH}: ${(e as Error).message}`,
+    ));
+  }
+
+  let raw: unknown;
+  try {
+    raw = YAML.parse(content);
+  } catch (e: unknown) {
+    return err(new ConfigError(
+      `Invalid YAML in ${CONFIG_PATH}: ${(e as Error).message}`,
+    ));
+  }
+
+  if (!raw || typeof raw !== 'object') {
+    return err(new ConfigError(
+      `Config file ${CONFIG_PATH} is empty or not an object.`,
+    ));
+  }
+
+  return validateConfig(raw as Record<string, unknown>);
+}
+
+/**
+ * Save the full config back to ~/.signet/config.yaml.
+ * Used by remote add/remove commands to persist changes.
+ */
+export async function saveConfig(config: SignetConfig): Promise<void> {
+  await fs.mkdir(path.dirname(CONFIG_PATH), { recursive: true });
+  await fs.writeFile(CONFIG_PATH, YAML.stringify(config), 'utf-8');
+}
+
+/**
+ * Get the config file path (for error messages).
+ */
+export function getConfigPath(): string {
+  return CONFIG_PATH;
+}

package/src/config/schema.ts

@@ -0,0 +1,75 @@
+/**
+ * Unified configuration schema for signet.
+ * All config lives in ~/.signet/config.yaml — no cascade, no env vars.
+ *
+ * Strategy config types are defined in core/types.ts (shared vocabulary)
+ * and re-exported here for convenience.
+ */
+
+import type {
+  CredentialType,
+  XHeaderConfig,
+  StrategyName,
+} from '../core/types.js';
+
+// Re-export strategy config types from core/types (the source of truth)
+export type {
+  CookieStrategyConfig,
+  OAuth2StrategyConfig,
+  ApiTokenStrategyConfig,
+  BasicStrategyConfig,
+  StrategyConfig,
+  StrategyName,
+} from '../core/types.js';
+
+// ============================================================================
+// Top-level Config Sections
+// ============================================================================
+
+export interface BrowserConfig {
+  browserDataDir: string;
+  channel: string;
+  headlessTimeout: number;
+  visibleTimeout: number;
+  waitUntil: 'load' | 'networkidle' | 'domcontentloaded' | 'commit';
+}
+
+export interface StorageConfig {
+  credentialsDir: string;  // MANDATORY
+}
+
+export interface RemoteEntry {
+  type: 'ssh';
+  host: string;
+  user?: string;
+  path?: string;
+  sshKey?: string;
+}
+
+// ============================================================================
+// Root Config
+// ============================================================================
+
+export interface SignetConfig {
+  browser: BrowserConfig;
+  storage: StorageConfig;
+  remotes?: Record<string, RemoteEntry>;
+  providers: Record<string, ProviderEntry>;
+}
+
+// ============================================================================
+// Provider Entry (as it appears in YAML)
+// ============================================================================
+
+export interface ProviderEntry {
+  name?: string;
+  domains: string[];
+  entryUrl?: string;
+  strategy: StrategyName;
+  config?: Record<string, unknown>;
+  acceptedCredentialTypes?: CredentialType[];
+  setupInstructions?: string;
+  credentialFile?: string;
+  xHeaders?: XHeaderConfig[];
+  forceVisible?: boolean;
+}

package/src/config/validator.ts

@@ -0,0 +1,281 @@
+/**
+ * Runtime validation for the unified signet config.
+ * Returns Result<SignetConfig, AuthError>.
+ */
+
+import type { Result } from '../core/result.js';
+import { ok, err } from '../core/result.js';
+import { ConfigError, type AuthError } from '../core/errors.js';
+import type {
+  SignetConfig,
+  BrowserConfig,
+  StorageConfig,
+  ProviderEntry,
+  RemoteEntry,
+  StrategyName,
+  StrategyConfig,
+} from './schema.js';
+
+const VALID_STRATEGIES: readonly StrategyName[] = ['cookie', 'oauth2', 'api-token', 'basic'];
+const VALID_WAIT_UNTIL = ['load', 'networkidle', 'domcontentloaded', 'commit'];
+
+/**
+ * Validate a raw config object parsed from YAML.
+ */
+export function validateConfig(raw: Record<string, unknown>): Result<SignetConfig, AuthError> {
+  const errors: string[] = [];
+
+  // --- browser section ---
+  if (!raw.browser || typeof raw.browser !== 'object') {
+    errors.push('Missing required section: "browser"');
+  } else {
+    const browser = raw.browser as Record<string, unknown>;
+    if (typeof browser.browserDataDir !== 'string' || browser.browserDataDir.trim() === '') {
+      errors.push('Missing required field: browser.browserDataDir');
+    }
+    if (typeof browser.channel !== 'string' || browser.channel.trim() === '') {
+      errors.push('Missing required field: browser.channel');
+    }
+    if (browser.headlessTimeout !== undefined && typeof browser.headlessTimeout !== 'number') {
+      errors.push('browser.headlessTimeout must be a number');
+    }
+    if (browser.visibleTimeout !== undefined && typeof browser.visibleTimeout !== 'number') {
+      errors.push('browser.visibleTimeout must be a number');
+    }
+    if (browser.waitUntil !== undefined && !VALID_WAIT_UNTIL.includes(browser.waitUntil as string)) {
+      errors.push(`browser.waitUntil must be one of: ${VALID_WAIT_UNTIL.join(', ')}`);
+    }
+  }
+
+  // --- storage section ---
+  if (!raw.storage || typeof raw.storage !== 'object') {
+    errors.push('Missing required section: "storage"');
+  } else {
+    const storage = raw.storage as Record<string, unknown>;
+    if (typeof storage.credentialsDir !== 'string' || storage.credentialsDir.trim() === '') {
+      errors.push('Missing required field: storage.credentialsDir');
+    }
+  }
+
+  // --- providers section (optional — null/missing means zero providers) ---
+  if (raw.providers !== undefined && raw.providers !== null) {
+    if (typeof raw.providers !== 'object') {
+      errors.push('"providers" must be an object (or omitted)');
+    } else {
+      const providers = raw.providers as Record<string, unknown>;
+      for (const [id, entry] of Object.entries(providers)) {
+        if (!entry || typeof entry !== 'object') {
+          errors.push(`Provider "${id}": must be an object`);
+          continue;
+        }
+        const providerErrors = validateProviderEntry(id, entry as Record<string, unknown>);
+        errors.push(...providerErrors);
+      }
+    }
+  }
+
+  // --- remotes section (optional) ---
+  if (raw.remotes !== undefined) {
+    if (typeof raw.remotes !== 'object' || raw.remotes === null) {
+      errors.push('"remotes" must be an object');
+    } else {
+      const remotes = raw.remotes as Record<string, unknown>;
+      for (const [name, entry] of Object.entries(remotes)) {
+        if (!entry || typeof entry !== 'object') {
+          errors.push(`Remote "${name}": must be an object`);
+          continue;
+        }
+        const r = entry as Record<string, unknown>;
+        if (r.type !== 'ssh') {
+          errors.push(`Remote "${name}": only type "ssh" is supported`);
+        }
+        if (typeof r.host !== 'string' || r.host.trim() === '') {
+          errors.push(`Remote "${name}": missing required field "host"`);
+        }
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return err(new ConfigError(
+      `Config validation failed:\n  - ${errors.join('\n  - ')}`,
+    ));
+  }
+
+  // Build the validated config
+  const browserRaw = raw.browser as Record<string, unknown>;
+  const browser: BrowserConfig = {
+    browserDataDir: browserRaw.browserDataDir as string,
+    channel: browserRaw.channel as string,
+    headlessTimeout: typeof browserRaw.headlessTimeout === 'number' ? browserRaw.headlessTimeout : 30_000,
+    visibleTimeout: typeof browserRaw.visibleTimeout === 'number' ? browserRaw.visibleTimeout : 120_000,
+    waitUntil: typeof browserRaw.waitUntil === 'string' ? browserRaw.waitUntil as BrowserConfig['waitUntil'] : 'load',
+  };
+
+  const storageRaw = raw.storage as Record<string, unknown>;
+  const storage: StorageConfig = {
+    credentialsDir: storageRaw.credentialsDir as string,
+  };
+
+  const providers: Record<string, ProviderEntry> = {};
+  if (raw.providers && typeof raw.providers === 'object') {
+    for (const [id, entry] of Object.entries(raw.providers as Record<string, unknown>)) {
+      providers[id] = parseProviderEntry(entry as Record<string, unknown>);
+    }
+  }
+
+  let remotes: Record<string, RemoteEntry> | undefined;
+  if (raw.remotes && typeof raw.remotes === 'object') {
+    remotes = {};
+    for (const [name, entry] of Object.entries(raw.remotes as Record<string, unknown>)) {
+      const r = entry as Record<string, unknown>;
+      remotes[name] = {
+        type: 'ssh',
+        host: r.host as string,
+        ...(typeof r.user === 'string' ? { user: r.user } : {}),
+        ...(typeof r.path === 'string' ? { path: r.path } : {}),
+        ...(typeof r.sshKey === 'string' ? { sshKey: r.sshKey } : {}),
+      };
+    }
+  }
+
+  const config: SignetConfig = {
+    browser,
+    storage,
+    providers,
+    ...(remotes ? { remotes } : {}),
+  };
+
+  return ok(config);
+}
+
+function validateProviderEntry(id: string, raw: Record<string, unknown>): string[] {
+  const errors: string[] = [];
+
+  if (!Array.isArray(raw.domains) || raw.domains.length === 0) {
+    errors.push(`Provider "${id}": missing required field "domains" (non-empty array)`);
+  } else {
+    for (const d of raw.domains) {
+      if (typeof d !== 'string') {
+        errors.push(`Provider "${id}": domains must be strings`);
+        break;
+      }
+    }
+  }
+
+  if (typeof raw.strategy !== 'string') {
+    errors.push(`Provider "${id}": missing required field "strategy"`);
+  } else if (!VALID_STRATEGIES.includes(raw.strategy as StrategyName)) {
+    errors.push(
+      `Provider "${id}": invalid strategy "${raw.strategy}". ` +
+      `Valid strategies: ${VALID_STRATEGIES.join(', ')}`,
+    );
+  }
+
+  // Validate forceVisible at provider level
+  if (raw.forceVisible !== undefined && typeof raw.forceVisible !== 'boolean') {
+    errors.push(`Provider "${id}": forceVisible must be a boolean`);
+  }
+
+  // Validate strategy-specific config shape
+  if (typeof raw.strategy === 'string' && raw.config && typeof raw.config === 'object') {
+    const strategyErrors = validateStrategyConfig(
+      id,
+      raw.strategy as StrategyName,
+      raw.config as Record<string, unknown>,
+    );
+    errors.push(...strategyErrors);
+  }
+
+  return errors;
+}
+
+function validateStrategyConfig(
+  id: string,
+  strategy: StrategyName,
+  config: Record<string, unknown>,
+): string[] {
+  const errors: string[] = [];
+
+  // Cross-strategy field checks: warn about fields that don't belong
+  if (strategy === 'cookie') {
+    const oauthFields = ['audiences', 'tokenEndpoint', 'clientId', 'scopes'];
+    for (const field of oauthFields) {
+      if (config[field] !== undefined) {
+        errors.push(
+          `Provider "${id}": config.${field} is not valid for strategy "cookie"`,
+        );
+      }
+    }
+  }
+
+  if (strategy === 'oauth2') {
+    const cookieFields = ['ttl', 'requiredCookies'];
+    for (const field of cookieFields) {
+      if (config[field] !== undefined) {
+        errors.push(
+          `Provider "${id}": config.${field} is not valid for strategy "oauth2"`,
+        );
+      }
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Merge a provider entry's strategy + config into a typed StrategyConfig.
+ */
+export function buildStrategyConfig(
+  strategy: StrategyName,
+  config?: Record<string, unknown>,
+): StrategyConfig {
+  const c = config ?? {};
+
+  switch (strategy) {
+    case 'cookie':
+      return {
+        strategy: 'cookie',
+        ...(typeof c.ttl === 'string' ? { ttl: c.ttl } : {}),
+        ...(Array.isArray(c.requiredCookies) ? { requiredCookies: c.requiredCookies as string[] } : {}),
+      };
+
+    case 'oauth2':
+      return {
+        strategy: 'oauth2',
+        ...(Array.isArray(c.audiences) ? { audiences: c.audiences as string[] } : {}),
+        ...(typeof c.tokenEndpoint === 'string' ? { tokenEndpoint: c.tokenEndpoint } : {}),
+        ...(typeof c.clientId === 'string' ? { clientId: c.clientId } : {}),
+        ...(Array.isArray(c.scopes) ? { scopes: c.scopes as string[] } : {}),
+      };
+
+    case 'api-token':
+      return {
+        strategy: 'api-token',
+        ...(typeof c.headerName === 'string' ? { headerName: c.headerName } : {}),
+        ...(typeof c.headerPrefix === 'string' ? { headerPrefix: c.headerPrefix } : {}),
+        ...(typeof c.setupInstructions === 'string' ? { setupInstructions: c.setupInstructions } : {}),
+      };
+
+    case 'basic':
+      return {
+        strategy: 'basic',
+        ...(typeof c.setupInstructions === 'string' ? { setupInstructions: c.setupInstructions } : {}),
+      };
+  }
+}
+
+function parseProviderEntry(raw: Record<string, unknown>): ProviderEntry {
+  return {
+    ...(typeof raw.name === 'string' ? { name: raw.name } : {}),
+    domains: raw.domains as string[],
+    ...(typeof raw.entryUrl === 'string' ? { entryUrl: raw.entryUrl } : {}),
+    strategy: raw.strategy as StrategyName,
+    ...(raw.config && typeof raw.config === 'object' ? { config: raw.config as Record<string, unknown> } : {}),
+    ...(Array.isArray(raw.acceptedCredentialTypes) ? { acceptedCredentialTypes: raw.acceptedCredentialTypes } : {}),
+    ...(typeof raw.setupInstructions === 'string' ? { setupInstructions: raw.setupInstructions } : {}),
+    ...(typeof raw.credentialFile === 'string' ? { credentialFile: raw.credentialFile } : {}),
+    ...(Array.isArray(raw.xHeaders) ? { xHeaders: raw.xHeaders } : {}),
+    ...(typeof raw.forceVisible === 'boolean' ? { forceVisible: raw.forceVisible } : {}),
+  };
+}