signet-auth 1.0.0-beta.0

package/dist/utils/http.js

@@ -0,0 +1,10 @@
+import os from 'node:os';
+/**
+ * Build a User-Agent string identifying signet.
+ */
+export function buildUserAgent() {
+    const platform = os.platform();
+    const arch = os.arch();
+    const nodeVersion = process.version;
+    return `signet/1.0.0 (${platform}; ${arch}) Node/${nodeVersion}`;
+}

package/dist/utils/jwt.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Lightweight JWT decode without signature verification.
+ * Used for reading token expiry and audience — NOT for security validation.
+ */
+export interface JwtPayload {
+    exp?: number;
+    iat?: number;
+    aud?: string | string[];
+    iss?: string;
+    sub?: string;
+    [key: string]: unknown;
+}
+export declare function decodeJwt(token: string): JwtPayload | null;
+export declare function isJwtExpired(token: string, bufferMs?: number): boolean;
+export declare function getJwtExpiresAt(token: string): Date | null;

package/dist/utils/jwt.js

@@ -0,0 +1,30 @@
+/**
+ * Lightweight JWT decode without signature verification.
+ * Used for reading token expiry and audience — NOT for security validation.
+ */
+export function decodeJwt(token) {
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const payload = parts[1];
+        const decoded = Buffer.from(payload, 'base64url').toString('utf-8');
+        return JSON.parse(decoded);
+    }
+    catch {
+        return null;
+    }
+}
+export function isJwtExpired(token, bufferMs = 0) {
+    const payload = decodeJwt(token);
+    if (!payload?.exp)
+        return false; // No expiry = assume valid
+    const expiresAtMs = payload.exp * 1000;
+    return Date.now() + bufferMs >= expiresAtMs;
+}
+export function getJwtExpiresAt(token) {
+    const payload = decodeJwt(token);
+    if (!payload?.exp)
+        return null;
+    return new Date(payload.exp * 1000);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "signet-auth",
+  "version": "1.0.0-beta.0",
+  "description": "General-purpose authentication CLI with pluggable strategies and browser adapters",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "sig": "./bin/sig.js"
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "src/",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "start": "node bin/sig.js",
+    "dev": "tsc && node bin/sig.js",
+    "test": "node --experimental-vm-modules node_modules/.bin/vitest run",
+    "test:watch": "node --experimental-vm-modules node_modules/.bin/vitest"
+  },
+  "dependencies": {
+    "playwright-core": "^1.50.0",
+    "yaml": "^2.7.0",
+    "proper-lockfile": "^4.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "typescript": "^5.3.0",
+    "vitest": "^3.0.0"
+  },
+  "keywords": [
+    "cli",
+    "auth",
+    "authentication",
+    "oauth2",
+    "browser",
+    "playwright-core"
+  ],
+  "author": "pylon <pylon.peng@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pylon/signet.git"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/auth-manager.ts

@@ -0,0 +1,331 @@
+import type { IAuthStrategy, AuthContext } from './core/interfaces/auth-strategy.js';
+import type { IBrowserAdapter } from './core/interfaces/browser-adapter.js';
+import type { IStorage } from './core/interfaces/storage.js';
+import type { IProviderRegistry } from './core/interfaces/provider.js';
+import type { Credential, ProviderConfig, StoredCredential, ProviderStatus, ILogger } from './core/types.js';
+import type { BrowserConfig } from './config/schema.js';
+import { createDefaultProvider } from './providers/auto-provision.js';
+import type { Result } from './core/result.js';
+import { ok, err, isOk } from './core/result.js';
+import {
+  CredentialNotFoundError,
+  CredentialExpiredError,
+  CredentialTypeError,
+  ProviderNotFoundError,
+  type AuthError,
+} from './core/errors.js';
+import { StrategyRegistry } from './strategies/registry.js';
+
+export interface AuthManagerDeps {
+  storage: IStorage;
+  strategyRegistry: StrategyRegistry;
+  providerRegistry: IProviderRegistry;
+  browserAdapterFactory: () => IBrowserAdapter;
+  browserConfig: BrowserConfig;
+  logger?: ILogger;
+}
+
+/**
+ * Central orchestrator for authentication lifecycle.
+ * All dependencies are injected — no singletons, no global state.
+ *
+ * Flow: validate → refresh → authenticate
+ */
+export class AuthManager {
+  private readonly storage: IStorage;
+  private readonly strategies: StrategyRegistry;
+  private readonly providers: IProviderRegistry;
+  private readonly browserAdapterFactory: () => IBrowserAdapter;
+  private readonly browserConfig: BrowserConfig;
+  private readonly logger?: ILogger;
+
+  constructor(deps: AuthManagerDeps) {
+    this.storage = deps.storage;
+    this.strategies = deps.strategyRegistry;
+    this.providers = deps.providerRegistry;
+    this.browserAdapterFactory = deps.browserAdapterFactory;
+    this.browserConfig = deps.browserConfig;
+    this.logger = deps.logger;
+  }
+
+  /**
+   * Get valid credentials for a provider.
+   * Tries: stored → refresh → authenticate, in that order.
+   */
+  async getCredentials(providerId: string): Promise<Result<Credential, AuthError>> {
+    const provider = this.providers.get(providerId);
+    if (!provider) return err(new ProviderNotFoundError(providerId));
+
+    const strategy = this.strategies.get(provider.strategy, provider.strategyConfig);
+    const key = this.storageKey(provider);
+
+    // Step 1: Check stored credentials
+    const stored = await this.storage.get(key);
+    if (stored) {
+      const validation = strategy.validate(stored.credential, provider.strategyConfig);
+      if (isOk(validation) && validation.value) {
+        // Check credential type constraints
+        const typeCheck = this.checkCredentialType(provider, stored.credential);
+        if (!isOk(typeCheck)) return typeCheck;
+        return ok(stored.credential);
+      }
+
+      // Step 2: Try refresh
+      this.logger?.debug(`Credentials for "${providerId}" are invalid, attempting refresh...`);
+      const refreshResult = await strategy.refresh(stored.credential, provider.strategyConfig);
+      if (isOk(refreshResult) && refreshResult.value) {
+        const typeCheck = this.checkCredentialType(provider, refreshResult.value);
+        if (!isOk(typeCheck)) return typeCheck;
+
+        await this.store(key, provider.strategy, refreshResult.value);
+        return ok(refreshResult.value);
+      }
+    }
+
+    // Step 3: Full authentication
+    this.logger?.info(`Authenticating with "${providerId}"...`);
+    const context: AuthContext = {
+      browserAdapter: this.browserAdapterFactory(),
+      browserConfig: this.browserConfig,
+      logger: this.logger,
+    };
+
+    const authResult = await strategy.authenticate(provider, context);
+    if (!isOk(authResult)) return authResult;
+
+    const typeCheck = this.checkCredentialType(provider, authResult.value);
+    if (!isOk(typeCheck)) return typeCheck;
+
+    await this.store(key, provider.strategy, authResult.value);
+    return ok(authResult.value);
+  }
+
+  /**
+   * Resolve a provider by URL, auto-provisioning a default cookie provider if none matches.
+   */
+  resolveProvider(url: string): ProviderConfig {
+    const existing = this.providers.resolve(url);
+    if (existing) return existing;
+
+    const provider = createDefaultProvider(url);
+    this.providers.register(provider);
+    this.logger?.info(`Auto-provisioned provider "${provider.id}" for ${url}`);
+    return provider;
+  }
+
+  /**
+   * Get credentials for a specific provider, resolving by URL.
+   */
+  async getCredentialsByUrl(url: string): Promise<Result<{ provider: ProviderConfig; credential: Credential }, AuthError>> {
+    const provider = this.resolveProvider(url);
+
+    const result = await this.getCredentials(provider.id);
+    if (!isOk(result)) return result;
+
+    return ok({ provider, credential: result.value });
+  }
+
+  /**
+   * Force re-authentication, deleting any stored credentials first.
+   */
+  async forceReauth(providerId: string): Promise<Result<Credential, AuthError>> {
+    const provider = this.providers.get(providerId);
+    if (provider) {
+      await this.storage.delete(this.storageKey(provider));
+    }
+    return this.getCredentials(providerId);
+  }
+
+  /**
+   * Store a credential directly (e.g., user-provided API token).
+   */
+  async setCredential(
+    providerId: string,
+    credential: Credential,
+  ): Promise<Result<void, AuthError>> {
+    const provider = this.providers.get(providerId);
+    if (!provider) return err(new ProviderNotFoundError(providerId));
+
+    const typeCheck = this.checkCredentialType(provider, credential);
+    if (!isOk(typeCheck)) return typeCheck;
+
+    await this.store(this.storageKey(provider), provider.strategy, credential);
+    return ok(undefined);
+  }
+
+  /**
+   * Get status for a provider (non-triggering — won't start auth).
+   */
+  async getStatus(providerId: string): Promise<ProviderStatus> {
+    const provider = this.providers.get(providerId);
+    if (!provider) {
+      return {
+        id: providerId,
+        name: providerId,
+        configured: false,
+        valid: false,
+        strategy: 'unknown',
+      };
+    }
+
+    const stored = await this.storage.get(this.storageKey(provider));
+    if (!stored) {
+      return {
+        id: provider.id,
+        name: provider.name,
+        configured: true,
+        valid: false,
+        strategy: provider.strategy,
+      };
+    }
+
+    const strategy = this.strategies.get(provider.strategy, provider.strategyConfig);
+    const validation = strategy.validate(stored.credential, provider.strategyConfig);
+    const valid = isOk(validation) && validation.value;
+
+    const expiresAt = this.getExpiresAt(stored.credential);
+    const expiresInMinutes = expiresAt
+      ? Math.max(0, Math.round((expiresAt.getTime() - Date.now()) / 60000))
+      : undefined;
+
+    return {
+      id: provider.id,
+      name: provider.name,
+      configured: true,
+      valid,
+      credentialType: stored.credential.type,
+      strategy: provider.strategy,
+      expiresAt: expiresAt?.toISOString(),
+      expiresInMinutes,
+    };
+  }
+
+  /**
+   * Get status for all configured providers.
+   */
+  async getAllStatus(): Promise<ProviderStatus[]> {
+    const providers = this.providers.list();
+    return Promise.all(providers.map(p => this.getStatus(p.id)));
+  }
+
+  /**
+   * Clear stored credentials for a provider.
+   */
+  async clearCredentials(providerId: string): Promise<void> {
+    const provider = this.providers.get(providerId);
+    const key = provider ? this.storageKey(provider) : providerId;
+    await this.storage.delete(key);
+  }
+
+  /**
+   * Clear all stored credentials.
+   */
+  async clearAll(): Promise<void> {
+    await this.storage.clear();
+  }
+
+  /**
+   * Apply credentials to an outgoing request (as headers).
+   */
+  applyToRequest(
+    providerId: string,
+    credential: Credential,
+  ): Record<string, string> {
+    const provider = this.providers.get(providerId);
+    if (!provider) return {};
+
+    const strategy = this.strategies.get(provider.strategy, provider.strategyConfig);
+    return strategy.applyToRequest(credential);
+  }
+
+  /**
+   * Validate a credential by making a test request to the provider's entry URL.
+   * Returns the HTTP status and whether the response redirects to a login page.
+   */
+  async validateCredential(
+    provider: ProviderConfig,
+    credential: Credential,
+  ): Promise<{ status: number | null; isLoginRedirect: boolean }> {
+    if (!provider.entryUrl) return { status: null, isLoginRedirect: false };
+    try {
+      const strategy = this.strategies.get(provider.strategy, provider.strategyConfig);
+      const headers = strategy.applyToRequest(credential);
+      const response = await fetch(provider.entryUrl, {
+        method: 'GET',
+        headers: { ...headers, 'User-Agent': 'signet/1.0' },
+        redirect: 'manual',
+      });
+      const location = response.headers.get('location') ?? '';
+      const loginPatterns = [
+        '/login', '/signin', '/sign-in', '/auth', '/sso', '/oauth',
+        '/adfs/', '/saml/', 'login.microsoftonline.com',
+        'accounts.google.com',
+      ];
+      const isLoginRedirect = response.status >= 300 && response.status < 400
+        && loginPatterns.some(p => location.toLowerCase().includes(p));
+      return { status: response.status, isLoginRedirect };
+    } catch {
+      return { status: null, isLoginRedirect: false };
+    }
+  }
+
+  /** Expose the provider registry for handlers */
+  get providerRegistry(): IProviderRegistry {
+    return this.providers;
+  }
+
+  /** Storage key: uses credentialFile if configured, otherwise provider ID. */
+  private storageKey(provider: ProviderConfig): string {
+    return provider.credentialFile ?? provider.id;
+  }
+
+  private checkCredentialType(
+    provider: ProviderConfig,
+    credential: Credential,
+  ): Result<void, AuthError> {
+    if (
+      provider.acceptedCredentialTypes &&
+      provider.acceptedCredentialTypes.length > 0 &&
+      !provider.acceptedCredentialTypes.includes(credential.type)
+    ) {
+      return err(new CredentialTypeError(
+        provider.id,
+        provider.acceptedCredentialTypes,
+        credential.type,
+      ));
+    }
+    return ok(undefined);
+  }
+
+  private async store(
+    providerId: string,
+    strategy: string,
+    credential: Credential,
+  ): Promise<void> {
+    // Strip transient diagnostics metadata before persisting
+    const { __diagnostics, ...clean } = credential as any;
+    const stored: StoredCredential = {
+      credential: clean,
+      providerId,
+      strategy,
+      updatedAt: new Date().toISOString(),
+    };
+    await this.storage.set(providerId, stored);
+  }
+
+  private getExpiresAt(credential: Credential): Date | null {
+    switch (credential.type) {
+      case 'bearer':
+        return credential.expiresAt ? new Date(credential.expiresAt) : null;
+      case 'cookie': {
+        // Earliest cookie expiry, or null if all session cookies
+        const expiries = credential.cookies
+          .filter(c => c.expires > 0)
+          .map(c => c.expires * 1000);
+        return expiries.length > 0 ? new Date(Math.min(...expiries)) : null;
+      }
+      default:
+        return null;
+    }
+  }
+}

package/src/browser/adapters/playwright.adapter.ts

@@ -0,0 +1,247 @@
+import os from "node:os";
+import path from "node:path";
+import type {
+  IBrowserAdapter,
+  IBrowserSession,
+  IBrowserPage,
+  NavigateOptions,
+  PageRequest,
+  PageResponse,
+} from "../../core/interfaces/browser-adapter.js";
+import type { Cookie, BrowserLaunchOptions } from "../../core/types.js";
+import type { BrowserConfig } from "../../config/schema.js";
+import { BrowserLaunchError } from "../../core/errors.js";
+
+function expandHome(p: string): string {
+  if (p.startsWith("~/") || p === "~") {
+    return path.join(os.homedir(), p.slice(1));
+  }
+  return p;
+}
+
+/**
+ * Playwright-based browser adapter.
+ * Uses playwright-core (no bundled browsers) — requires a system Chrome/Chromium/Edge.
+ * Defaults to system Chrome (channel: 'chrome') when no explicit browser is configured.
+ */
+export class PlaywrightAdapter implements IBrowserAdapter {
+  readonly name = "playwright";
+
+  constructor(private readonly browserConfig: BrowserConfig) {}
+
+  async launch(options: BrowserLaunchOptions): Promise<IBrowserSession> {
+    const { browserDataDir, channel } = this.browserConfig;
+
+    let pw: typeof import("playwright-core");
+    try {
+      pw = await import("playwright-core");
+    } catch {
+      throw new BrowserLaunchError(
+        "playwright-core is not available. Run: npm install playwright-core",
+      );
+    }
+
+    try {
+      const context = await pw.chromium.launchPersistentContext(
+        expandHome(browserDataDir),
+        {
+          channel: channel,
+          headless: options.headless ?? true,
+          timeout: options.timeout,
+          args: options.args,
+        },
+      );
+      return new PlaywrightSession(context);
+    } catch (e: unknown) {
+      const msg = (e as Error).message;
+      const hint =
+        msg.includes("executable") || msg.includes("Failed to launch")
+          ? `${msg}. Ensure a system browser is installed, or check browser.channel in ~/.signet/config.yaml.`
+          : msg;
+      throw new BrowserLaunchError(hint);
+    }
+  }
+}
+
+class PlaywrightSession implements IBrowserSession {
+  constructor(
+    private readonly context: import("playwright-core").BrowserContext,
+  ) {}
+
+  async newPage(): Promise<IBrowserPage> {
+    const page = await this.context.newPage();
+    return new PlaywrightPage(page, this.context);
+  }
+
+  async pages(): Promise<IBrowserPage[]> {
+    return this.context.pages().map((p) => new PlaywrightPage(p, this.context));
+  }
+
+  async close(): Promise<void> {
+    try {
+      await this.context.close();
+    } catch {
+      // Suppress close errors
+    }
+  }
+
+  isConnected(): boolean {
+    return true; // Persistent context doesn't expose isConnected
+  }
+}
+
+class PlaywrightPage implements IBrowserPage {
+  constructor(
+    private readonly page: import("playwright-core").Page,
+    private readonly context: import("playwright-core").BrowserContext,
+  ) {}
+
+  async goto(url: string, options?: NavigateOptions): Promise<void> {
+    await this.page.goto(url, {
+      waitUntil: options?.waitUntil as
+        | "load"
+        | "networkidle"
+        | "domcontentloaded"
+        | "commit",
+      timeout: options?.timeout,
+    });
+  }
+
+  url(): string {
+    return this.page.url();
+  }
+
+  async waitForUrl(
+    pattern: string | RegExp,
+    options?: { timeout?: number },
+  ): Promise<void> {
+    await this.page.waitForURL(pattern, options);
+  }
+
+  async waitForNavigation(options?: { timeout?: number }): Promise<void> {
+    await this.page.waitForLoadState("networkidle", options);
+  }
+
+  async waitForLoadState(
+    state?: "load" | "networkidle" | "domcontentloaded",
+  ): Promise<void> {
+    await this.page.waitForLoadState(state);
+  }
+
+  async fill(selector: string, value: string): Promise<void> {
+    await this.page.locator(selector).fill(value);
+  }
+
+  async click(selector: string, options?: { timeout?: number }): Promise<void> {
+    await this.page.locator(selector).click({ timeout: options?.timeout });
+  }
+
+  async type(
+    selector: string,
+    text: string,
+    options?: { delay?: number },
+  ): Promise<void> {
+    await this.page
+      .locator(selector)
+      .pressSequentially(text, { delay: options?.delay });
+  }
+
+  async waitForSelector(
+    selector: string,
+    options?: { timeout?: number; state?: "visible" | "hidden" | "attached" },
+  ): Promise<void> {
+    await this.page.locator(selector).waitFor({
+      timeout: options?.timeout,
+      state: options?.state,
+    });
+  }
+
+  async cookies(urls?: string[]): Promise<Cookie[]> {
+    const rawCookies = await this.context.cookies(urls);
+    return rawCookies.map((c) => ({
+      name: c.name,
+      value: c.value,
+      domain: c.domain,
+      path: c.path,
+      expires: c.expires,
+      httpOnly: c.httpOnly,
+      secure: c.secure,
+      sameSite:
+        c.sameSite === "Strict"
+          ? "Strict"
+          : c.sameSite === "Lax"
+            ? "Lax"
+            : c.sameSite === "None"
+              ? "None"
+              : undefined,
+    }));
+  }
+
+  async evaluate<T>(fn: (() => T) | string): Promise<T> {
+    if (typeof fn === "string") {
+      return (await this.page.evaluate(fn)) as T;
+    }
+    return await this.page.evaluate(fn);
+  }
+
+  async evaluateWithArg<T, A>(fn: (arg: A) => T, arg: A): Promise<T> {
+    return await this.page.evaluate(fn as any, arg as any);
+  }
+
+  async screenshot(options?: {
+    path?: string;
+    fullPage?: boolean;
+  }): Promise<Buffer> {
+    return Buffer.from(await this.page.screenshot(options));
+  }
+
+  async content(): Promise<string> {
+    return await this.page.content();
+  }
+
+  async title(): Promise<string> {
+    return await this.page.title();
+  }
+
+  async close(): Promise<void> {
+    if (!this.page.isClosed()) {
+      await this.page.close();
+    }
+  }
+
+  isClosed(): boolean {
+    return this.page.isClosed();
+  }
+
+  onClose(handler: () => void): void {
+    this.page.on("close", handler);
+  }
+
+  onRequest(handler: (request: PageRequest) => void): () => void {
+    const listener = (req: import("playwright-core").Request) => {
+      handler({
+        url: req.url(),
+        method: req.method(),
+        headers: req.headers(),
+      });
+    };
+    this.page.on("request", listener);
+    return () => {
+      this.page.off("request", listener);
+    };
+  }
+
+  onResponse(handler: (response: PageResponse) => void): () => void {
+    const listener = (res: import("playwright-core").Response) => {
+      handler({
+        url: res.url(),
+        status: res.status(),
+        headers: res.headers(),
+      });
+    };
+    this.page.on("response", listener);
+    return () => {
+      this.page.off("response", listener);
+    };
+  }
+}