signet-auth 1.0.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pylon Peng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,393 @@
+# Signet
+
+General-purpose authentication CLI. Manages credentials for any web service -- authenticate via browser SSO, store tokens, and make authenticated requests.
+
+## Install
+
+```bash
+npm install -g signet-auth
+sig init
+```
+
+That's it. `sig init` auto-detects your browser and creates `~/.signet/config.yaml` with sensible defaults.
+
+### From source
+
+```bash
+git clone <repo-url> && cd signet
+npm install
+npm run build
+```
+
+The CLI is available as `sig` (or `./bin/sig.js`).
+
+## Quick Start
+
+```bash
+sig init                              # Create config (interactive)
+sig login https://jira.example.com    # Authenticate via browser SSO
+sig get jira                          # Get credentials for scripts/tools
+sig request https://jira.example.com/rest/api/2/myself   # Authenticated request
+sig doctor                            # Check your setup
+```
+
+## Commands
+
+### `init` -- Set up Signet
+
+```bash
+sig init                # Interactive setup (detects browser, offers provider templates)
+sig init --yes          # Accept all defaults (non-interactive)
+sig init --force        # Overwrite existing config
+sig init --channel msedge --yes   # Use Edge instead of Chrome
+```
+
+Creates `~/.signet/config.yaml`, `~/.signet/credentials/`, and `~/.signet/browser-data/`. Detects your installed browser and generates a commented config file.
+
+### `doctor` -- Check your setup
+
+```bash
+sig doctor
+```
+
+Validates your environment: config file, directories, browser availability, Node.js version, stored credentials.
+
+```
+  ✓ Config file exists (~/.signet/config.yaml)
+  ✓ Config is valid
+  ✓ Credentials directory exists (~/.signet/credentials)
+  ✓ Browser data directory exists (~/.signet/browser-data)
+  ✓ Browser available (chrome)
+  ✓ Node.js version (v22.16.0)
+  ✓ Stored credentials (2 stored credentials)
+
+All checks passed.
+```
+
+### `login` -- Authenticate with a service
+
+```bash
+sig login <url>
+sig login <url> --token <value>
+sig login <url> --username <user> --password <pass>
+sig login <url> --strategy <cookie|oauth2|api-token|basic>
+```
+
+Opens a browser for SSO login by default. Use `--token` to store an API key or `--username`/`--password` for basic auth without a browser.
+
+### `get` -- Retrieve credentials
+
+```bash
+sig get <provider|url>
+sig get <provider|url> --format json|header|value
+```
+
+Returns stored credentials as JSON (default), raw headers, or just the value.
+
+### `request` -- Make authenticated HTTP requests
+
+```bash
+sig request <url>
+sig request <url> --method POST --body '{"key":"value"}'
+sig request <url> --header "X-Custom: value" --format body
+```
+
+Injects credentials automatically. Supports `GET`, `POST`, `PUT`, `PATCH`. Output as full JSON response (default), body only, or headers only.
+
+### `status` -- Check authentication status
+
+```bash
+sig status
+sig status <provider>
+sig status --format json|table
+```
+
+Shows which providers are authenticated, credential types, and expiry.
+
+### `logout` -- Clear credentials
+
+```bash
+sig logout [provider]
+```
+
+Clears credentials for a specific provider, or all providers if none specified.
+
+### `providers` -- List configured providers
+
+```bash
+sig providers
+sig providers --format json|table
+```
+
+### `remote` -- Manage remote credential stores
+
+```bash
+sig remote add <name> <host> [--user <user>] [--path <path>] [--ssh-key <key>]
+sig remote remove <name>
+sig remote list
+```
+
+Configure SSH remotes for credential synchronization.
+
+### `sync` -- Sync credentials with remotes
+
+```bash
+sig sync push [remote] [--provider <id>] [--force]
+sig sync pull [remote] [--provider <id>] [--force]
+```
+
+Push or pull credentials to/from remote machines over SSH. Use `--force` to overwrite on conflict.
+
+## Configuration
+
+All configuration lives in a single file: `~/.signet/config.yaml`. No env vars, no cascading, no project-local overrides.
+
+Run `sig init` to generate a config interactively, or copy `config/config.example.yaml` to `~/.signet/config.yaml`.
+
+### `browser` (required)
+
+Controls the browser used for SSO authentication.
+
+| Field | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `browserDataDir` | **yes** | -- | Directory for persistent browser profile (cookies, localStorage). Example: `~/.signet/browser-data` |
+| `channel` | **yes** | -- | Browser channel. Values: `chrome`, `msedge`, `chromium` |
+| `headlessTimeout` | **yes** | -- | Timeout in ms for headless auth attempt. Headless is tried first; if it times out, falls back to visible mode. Recommended: `15000`-`30000` |
+| `visibleTimeout` | **yes** | -- | Timeout in ms for visible (user-assisted) auth. Must be long enough for the user to complete SSO manually. Recommended: `60000`-`120000` |
+| `waitUntil` | **yes** | -- | Page load condition before checking auth status. Values: `load` (DOM loaded), `networkidle` (no network activity for 500ms), `domcontentloaded` (HTML parsed), `commit` (first byte received) |
+
+```yaml
+browser:
+  browserDataDir: ~/.signet/browser-data
+  channel: chrome
+  headlessTimeout: 15000
+  visibleTimeout: 60000
+  waitUntil: load
+```
+
+### `storage` (required)
+
+Where credentials are stored on disk.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `credentialsDir` | **yes** | Directory for per-provider credential JSON files. Example: `~/.signet/credentials` |
+
+```yaml
+storage:
+  credentialsDir: ~/.signet/credentials
+```
+
+### `remotes` (optional)
+
+SSH remotes for syncing credentials to other machines.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | **yes** | Transport type. Only `ssh` is supported |
+| `host` | **yes** | Remote hostname or IP |
+| `user` | no | SSH username. Defaults to current user |
+| `path` | no | Remote credentials directory. Defaults to `~/.signet/credentials` |
+| `sshKey` | no | Path to SSH private key. Defaults to system SSH config |
+
+```yaml
+remotes:
+  dev-server:
+    type: ssh
+    host: dev.example.com
+    user: deploy
+```
+
+### `providers` (optional)
+
+Provider entries map domains to authentication strategies. The key is the provider ID.
+
+Most services work with zero config -- just run `sig login <url>` and it auto-provisions a cookie provider. Define providers explicitly for OAuth2, API tokens, or when you need custom settings.
+
+#### Common provider fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `domains` | **yes** | Array of domains this provider handles. Used for URL-to-provider resolution. Example: `["jira.example.com"]` |
+| `strategy` | **yes** | Authentication strategy. Values: `cookie`, `oauth2`, `api-token`, `basic` |
+| `name` | no | Display name. Defaults to the provider ID |
+| `entryUrl` | no | URL to navigate to for browser-based auth. Required for `cookie` and `oauth2` strategies |
+| `forceVisible` | no | `true` to skip headless attempt and open visible browser immediately. Use for sites requiring CAPTCHAs, QR codes, or interactive auth. Default: `false` |
+| `config` | no | Strategy-specific settings (see below) |
+| `xHeaders` | no | Extra HTTP headers to capture during browser auth (see [xHeaders](#xheaders)) |
+
+#### Strategy: `cookie`
+
+For SSO-protected web apps. Opens a browser, waits for login, extracts cookies. This is the default strategy -- most sites need no config at all.
+
+| Config field | Required | Default | Description |
+|--------------|----------|---------|-------------|
+| `ttl` | no | `24h` | How long cookies are considered valid before re-authentication. Duration string: `ms`, `s`, `m`, `h`, `d`. Examples: `30m`, `12h`, `7d` |
+| `requiredCookies` | no | -- | Cookie names that must exist before auth is considered complete. Use for sites where the entry page isn't a login page (e.g. QR code login). Example: `["session_id", "id_token"]` |
+
+```yaml
+providers:
+  jira:
+    domains: ["jira.example.com"]
+    strategy: cookie
+    config:
+      ttl: "10d"
+```
+
+Minimal (uses all defaults):
+```yaml
+providers:
+  jira:
+    domains: ["jira.example.com"]
+    strategy: cookie
+```
+
+#### Strategy: `oauth2`
+
+For APIs using OAuth2/JWT tokens. Opens a browser for the OAuth consent flow, extracts tokens from browser localStorage.
+
+| Config field | Required | Default | Description |
+|--------------|----------|---------|-------------|
+| `audiences` | no | -- | Filter tokens by audience claim. Only tokens matching these audiences are extracted. Example: `["https://graph.microsoft.com"]` |
+| `tokenEndpoint` | no | -- | Token endpoint URL for refresh_token grant. Required if you want automatic token refresh |
+| `clientId` | no | -- | OAuth2 client ID for refresh_token grant. Required with `tokenEndpoint` |
+| `scopes` | no | -- | OAuth2 scopes for refresh_token grant. Example: `["openid", "profile", "User.Read"]` |
+
+```yaml
+providers:
+  ms-teams:
+    name: Microsoft Teams
+    domains: ["teams.cloud.microsoft"]
+    entryUrl: https://teams.cloud.microsoft/v2/
+    strategy: oauth2
+    config:
+      audiences: ["https://ic3.teams.office.com"]
+```
+
+#### Strategy: `api-token`
+
+For static API keys or personal access tokens. No browser needed -- prompts the user to enter a token.
+
+| Config field | Required | Default | Description |
+|--------------|----------|---------|-------------|
+| `headerName` | no | `Authorization` | HTTP header name to place the token in |
+| `headerPrefix` | no | `Bearer` | Prefix before the token value. Set to empty string for no prefix |
+| `setupInstructions` | no | -- | Instructions shown to the user when a token is needed. Supports multi-line |
+
+```yaml
+providers:
+  github:
+    name: GitHub
+    domains: ["github.com", "api.github.com"]
+    strategy: api-token
+    config:
+      headerName: Authorization
+      headerPrefix: Bearer
+      setupInstructions: |
+        Create a Personal Access Token at:
+        https://github.com/settings/tokens
+```
+
+#### Strategy: `basic`
+
+For username/password authentication. No browser needed -- prompts the user for credentials.
+
+| Config field | Required | Default | Description |
+|--------------|----------|---------|-------------|
+| `setupInstructions` | no | -- | Instructions shown to the user when credentials are needed |
+
+```yaml
+providers:
+  legacy-api:
+    domains: ["api.internal.corp"]
+    strategy: basic
+    config:
+      setupInstructions: "Contact IT for credentials."
+```
+
+#### xHeaders
+
+Capture extra HTTP headers during browser authentication. Useful for APIs that require anti-bot signatures, CSRF tokens, or custom headers that are set dynamically by the web app.
+
+Captured headers are stored alongside the credential and applied automatically on `sig get` and `sig request`.
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | **yes** | HTTP header name to capture (case-insensitive match) |
+| `source` | no | Where to capture from: `request` or `response`. Default: both |
+| `urlPattern` | no | Only capture from URLs matching this substring |
+| `staticValue` | no | Use a fixed value instead of capturing dynamically. When set, `source` and `urlPattern` are ignored |
+
+```yaml
+providers:
+  my-app:
+    domains: ["app.example.com"]
+    entryUrl: https://app.example.com/
+    strategy: cookie
+    forceVisible: true
+    config:
+      requiredCookies: ["id_token"]
+    xHeaders:
+      - name: x-csrf-token
+        source: request
+        urlPattern: app.example.com/api
+      - name: origin
+        staticValue: https://app.example.com
+      - name: referer
+        staticValue: https://app.example.com/
+```
+
+### Full example
+
+```yaml
+browser:
+  browserDataDir: ~/.signet/browser-data
+  channel: chrome
+  headlessTimeout: 15000
+  visibleTimeout: 60000
+  waitUntil: load
+
+storage:
+  credentialsDir: ~/.signet/credentials
+
+remotes:
+  dev-server:
+    type: ssh
+    host: dev.example.com
+    user: deploy
+
+providers:
+  jira:
+    domains: ["jira.example.com"]
+    strategy: cookie
+    config:
+      ttl: "10d"
+
+  github:
+    domains: ["github.com", "api.github.com"]
+    strategy: api-token
+    config:
+      setupInstructions: "Create a PAT at https://github.com/settings/tokens"
+
+  ms-teams:
+    domains: ["teams.cloud.microsoft"]
+    entryUrl: https://teams.cloud.microsoft/v2/
+    strategy: oauth2
+    config:
+      audiences: ["https://ic3.teams.office.com"]
+```
+
+## Authentication Strategies
+
+| Strategy | When to use | Browser needed |
+|----------|-------------|----------------|
+| **cookie** | SSO-protected web apps (default) | Yes |
+| **oauth2** | APIs with OAuth2/JWT tokens | Yes |
+| **api-token** | Static API keys or PATs | No |
+| **basic** | Username/password auth | No |
+
+Cookie-based auth is the default -- just `sig login <url>` and complete SSO in the browser window.
+
+## License
+
+[MIT](LICENSE)

package/bin/sig.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { execSync } from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const rootDir = join(__dirname, '..');
+
+function getVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(rootDir, 'package.json'), 'utf-8'));
+    return pkg.version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+}
+
+function buildIfNeeded() {
+  const distPath = join(rootDir, 'dist', 'index.js');
+  if (!existsSync(distPath)) {
+    // If no .git directory, this is likely a global install with missing dist/
+    const gitDir = join(rootDir, '.git');
+    if (!existsSync(gitDir)) {
+      console.error('[signet] dist/ directory is missing and this is not a dev checkout.');
+      console.error('[signet] Please reinstall: npm install -g signet-auth');
+      process.exit(1);
+    }
+
+    // Dev checkout: build from source
+    console.error('[signet] Building project...');
+    try {
+      execSync('npm run build', { cwd: rootDir, stdio: 'inherit' });
+    } catch (e) {
+      console.error('[signet] Build failed:', e.message);
+      process.exit(1);
+    }
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes('--version') || args.includes('-v')) {
+    console.log(getVersion());
+    process.exit(0);
+  }
+
+  buildIfNeeded();
+
+  const { run } = await import(join(rootDir, 'dist', 'cli', 'main.js'));
+  await run(args);
+}
+
+// Graceful shutdown
+process.on('SIGINT', () => process.exit(0));
+process.on('SIGTERM', () => process.exit(0));
+process.on('unhandledRejection', (err) => {
+  console.error('[signet] Unhandled rejection:', err);
+  process.exit(1);
+});
+
+main();

package/dist/auth-manager.d.ts

@@ -0,0 +1,90 @@
+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, ProviderStatus, ILogger } from './core/types.js';
+import type { BrowserConfig } from './config/schema.js';
+import type { Result } from './core/result.js';
+import { 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 declare class AuthManager {
+    private readonly storage;
+    private readonly strategies;
+    private readonly providers;
+    private readonly browserAdapterFactory;
+    private readonly browserConfig;
+    private readonly logger?;
+    constructor(deps: AuthManagerDeps);
+    /**
+     * Get valid credentials for a provider.
+     * Tries: stored → refresh → authenticate, in that order.
+     */
+    getCredentials(providerId: string): Promise<Result<Credential, AuthError>>;
+    /**
+     * Resolve a provider by URL, auto-provisioning a default cookie provider if none matches.
+     */
+    resolveProvider(url: string): ProviderConfig;
+    /**
+     * Get credentials for a specific provider, resolving by URL.
+     */
+    getCredentialsByUrl(url: string): Promise<Result<{
+        provider: ProviderConfig;
+        credential: Credential;
+    }, AuthError>>;
+    /**
+     * Force re-authentication, deleting any stored credentials first.
+     */
+    forceReauth(providerId: string): Promise<Result<Credential, AuthError>>;
+    /**
+     * Store a credential directly (e.g., user-provided API token).
+     */
+    setCredential(providerId: string, credential: Credential): Promise<Result<void, AuthError>>;
+    /**
+     * Get status for a provider (non-triggering — won't start auth).
+     */
+    getStatus(providerId: string): Promise<ProviderStatus>;
+    /**
+     * Get status for all configured providers.
+     */
+    getAllStatus(): Promise<ProviderStatus[]>;
+    /**
+     * Clear stored credentials for a provider.
+     */
+    clearCredentials(providerId: string): Promise<void>;
+    /**
+     * Clear all stored credentials.
+     */
+    clearAll(): Promise<void>;
+    /**
+     * Apply credentials to an outgoing request (as headers).
+     */
+    applyToRequest(providerId: string, credential: Credential): Record<string, string>;
+    /**
+     * 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.
+     */
+    validateCredential(provider: ProviderConfig, credential: Credential): Promise<{
+        status: number | null;
+        isLoginRedirect: boolean;
+    }>;
+    /** Expose the provider registry for handlers */
+    get providerRegistry(): IProviderRegistry;
+    /** Storage key: uses credentialFile if configured, otherwise provider ID. */
+    private storageKey;
+    private checkCredentialType;
+    private store;
+    private getExpiresAt;
+}