signet-auth 1.0.0 → 1.1.0

package/README.md

@@ -6,20 +6,39 @@ General-purpose authentication CLI. Manages credentials for any web service -- a
 
 ```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.
+### Local machine (has a browser)
 
-### From source
+```bash
+sig init                # Auto-detects your browser, creates ~/.signet/config.yaml
+sig login <url>         # Opens browser for SSO — done
+```
+
+### Remote / headless machine (no browser)
+
+```bash
+sig init --remote       # Sets up browserless mode
+```
+
+Then get credentials from your local machine or set them manually:
 
 ```bash
-git clone <repo-url> && cd signet
-npm install
-npm run build
+# On your local machine (has browser):
+sig remote add <name> <remote-host>             # Point to the remote machine
+sig sync push <name>                            # Push credentials over SSH
+
+# Or set credentials manually on the remote:
+sig login <url> --cookie "session=abc; id=xyz"  # Paste from browser DevTools
+sig login <url> --token <token>                 # API key or PAT
 ```
 
-The CLI is available as `sig` (or `./bin/sig.js`).
+### From source
+
+```bash
+git clone https://github.com/signet-auth/signet.git && cd signet
+npm install && npm run build
+```
 
 ## Quick Start
 
@@ -437,6 +456,144 @@ sig login https://api.example.com --token ghp_xxxxxxxxxxxxx
 
 Cookie-based auth is the default -- just `sig login <url>` and complete SSO in the browser window.
 
+## AI Agent Integration
+
+Signet works as an auth layer for AI coding agents (Claude Code, Cursor, Windsurf, etc.) that need to interact with authenticated web services. The agent shells out to `sig` via bash -- no SDK or MCP server needed.
+
+### How it works
+
+1. **Human authenticates once** via browser SSO: `sig login <url>`
+2. **Agent reuses stored credentials** via CLI: `sig get`, `sig request`
+3. **On auth failure**, agent re-triggers login: `sig login <url>` (opens browser for human)
+
+The human handles the browser SSO flow; the agent handles everything else.
+
+### Pattern 1: Direct authenticated requests
+
+For APIs where the agent makes HTTP calls directly. Signet injects credentials automatically.
+
+```bash
+# GET — read data
+sig request "https://jira.example.com/rest/api/2/issue/PROJ-123" --format body
+
+# POST — create/update (add CSRF headers for cookie-based APIs)
+sig request "https://jira.example.com/rest/api/2/issue" \
+  --method POST \
+  --header "Content-Type: application/json" \
+  --header "X-Requested-With: XMLHttpRequest" \
+  --body '{"fields": {"summary": "New issue"}}' \
+  --format body
+```
+
+Best for: REST APIs where the agent constructs requests directly (Jira, Confluence, etc.)
+
+### Pattern 2: Credential pass-through to scripts
+
+For agents that call helper scripts (Python, Node, etc.) which handle HTTP internally. The agent extracts the credential and passes it as a CLI argument.
+
+```bash
+# Cookie-based services
+CRED=$(sig get https://wiki.example.com/ --format value)
+python scripts/wiki_search.py --cookie "$CRED" --keyword "deployment guide"
+
+# Bearer token services
+TOKEN=$(sig get https://graph.microsoft.com/ --format value | sed 's/^Bearer //')
+python scripts/calendar.py --token "$TOKEN" --range today
+```
+
+**Note on bearer tokens:** `sig get` returns `Bearer eyJ...` (with prefix). If your scripts add the `Bearer` prefix themselves, strip it with `sed 's/^Bearer //'`.
+
+Best for: Complex workflows wrapped in Python/Node scripts that accept credentials via CLI args.
+
+### Pattern 3: Curl with sig credentials
+
+For multipart uploads or requests that `sig request` can't handle (e.g., file attachments).
+
+```bash
+CRED=$(sig get https://jira.example.com/ --format value)
+curl -X POST "https://jira.example.com/rest/api/2/issue/PROJ-123/attachments" \
+  -H "Cookie: $CRED" \
+  -H "X-Atlassian-Token: no-check" \
+  -F "file=@/path/to/file.png"
+```
+
+### Error handling for agents
+
+Teach agents to detect auth failures and re-authenticate:
+
+| Signal | Meaning | Agent action |
+|--------|---------|-------------|
+| HTTP 401/403 | Session expired | Run `sig login <url>`, retry |
+| HTML login page in response | SSO redirect | Run `sig login <url>`, retry |
+| `sig get` returns empty | No stored credential | Run `sig login <url>` |
+
+### Skill-based setup (Claude Code)
+
+For [Claude Code](https://docs.anthropic.com/en/docs/claude-code), create a [skill](https://docs.anthropic.com/en/docs/claude-code/skills) with a `SKILL.md` that documents the auth pattern and API endpoints. The skill triggers automatically based on its description.
+
+Example `SKILL.md` structure:
+
+```markdown
+---
+name: my-api
+description: "Interact with My API. Trigger on: my-api, tickets, issues..."
+---
+# My API
+
+## Authentication
+Get credential: `CRED=$(sig get https://api.example.com/ --format value)`
+Re-auth: `sig login https://api.example.com/`
+
+## Endpoints
+| Operation | Command |
+|-----------|---------|
+| List items | `sig request "https://api.example.com/items" --format body` |
+| Create item | `sig request "https://api.example.com/items" --method POST --body '...' --format body` |
+```
+
+### Multi-service configuration
+
+Agents often need access to multiple services. Configure all providers in a single `~/.signet/config.yaml`:
+
+```yaml
+providers:
+  jira:
+    domains: ["jira.example.com"]
+    strategy: cookie
+    config:
+      ttl: "10d"
+
+  wiki:
+    domains: ["wiki.example.com"]
+    strategy: cookie
+    config:
+      ttl: "12h"
+
+  ms-teams:
+    domains: ["teams.cloud.microsoft"]
+    entryUrl: https://teams.cloud.microsoft/v2/
+    strategy: oauth2
+    config:
+      audiences: ["https://ic3.teams.office.com"]
+
+  ms-graph:
+    domains: ["graph.microsoft.com"]
+    entryUrl: https://teams.cloud.microsoft/v2/
+    strategy: oauth2
+    config:
+      audiences: ["https://graph.microsoft.com"]
+```
+
+Then authenticate all at once:
+
+```bash
+sig login https://jira.example.com/
+sig login https://wiki.example.com/
+sig login https://teams.cloud.microsoft/v2/
+```
+
+The agent resolves providers by URL automatically -- no provider IDs needed in agent code.
+
 ## License
 
 [MIT](LICENSE)

package/dist/auth-manager.d.ts

@@ -34,9 +34,10 @@ export declare class AuthManager {
      */
     getCredentials(providerId: string): Promise<Result<Credential, AuthError>>;
     /**
-     * Resolve a provider by URL, auto-provisioning a default cookie provider if none matches.
+     * Resolve a provider by ID, name, URL, or domain.
+     * Auto-provisions a default cookie provider only for URL-like inputs that don't match.
      */
-    resolveProvider(url: string): ProviderConfig;
+    resolveProvider(input: string): ProviderConfig;
     /**
      * Get credentials for a specific provider, resolving by URL.
      */

package/dist/auth-manager.js

@@ -71,16 +71,24 @@ export class AuthManager {
         return ok(authResult.value);
     }
     /**
-     * Resolve a provider by URL, auto-provisioning a default cookie provider if none matches.
+     * Resolve a provider by ID, name, URL, or domain.
+     * Auto-provisions a default cookie provider only for URL-like inputs that don't match.
      */
-    resolveProvider(url) {
-        const existing = this.providers.resolve(url);
+    resolveProvider(input) {
+        const existing = this.providers.resolveFlexible(input);
         if (existing)
             return existing;
-        const provider = createDefaultProvider(url);
-        this.providers.register(provider);
-        this.logger?.info(`Auto-provisioned provider "${provider.id}" for ${url}`);
-        return provider;
+        // Only auto-provision for URL-like inputs (contains '.' or starts with 'http')
+        const isUrlLike = input.startsWith('http://') || input.startsWith('https://') || input.includes('.');
+        if (isUrlLike) {
+            const provider = createDefaultProvider(input);
+            this.providers.register(provider);
+            this.logger?.info(`Auto-provisioned provider "${provider.id}" for ${input}`);
+            return provider;
+        }
+        // For non-URL inputs that don't resolve, return a not-found error via a sentinel
+        // that will be caught by callers. We throw here since the method returns ProviderConfig.
+        throw new ProviderNotFoundError(input);
     }
     /**
      * Get credentials for a specific provider, resolving by URL.

package/dist/cli/commands/get.js

@@ -8,40 +8,42 @@ export async function runGet(positionals, flags, deps) {
         process.exitCode = 1;
         return;
     }
-    const isUrl = target.startsWith('http://') || target.startsWith('https://');
+    // Unified resolution: try ID → name → URL/domain
+    const resolved = deps.authManager.providerRegistry.resolveFlexible(target);
     let providerId;
     let credential;
-    if (isUrl) {
-        const result = await deps.authManager.getCredentialsByUrl(target);
+    if (resolved) {
+        providerId = resolved.id;
+        const result = await deps.authManager.getCredentials(providerId);
         if (!isOk(result)) {
             process.stderr.write(`Error: ${result.error.message}\n`);
             if (result.error.code === 'BROWSER_UNAVAILABLE') {
                 process.stderr.write(`Hint: Run "sig login ${target} --token <token>" or "sig sync pull" to get credentials.\n`);
             }
-            process.exitCode = result.error.code === 'PROVIDER_NOT_FOUND' ? 2 : 3;
+            process.exitCode = result.error.code === 'CREDENTIAL_NOT_FOUND' ? 3 : 1;
             return;
         }
-        providerId = result.value.provider.id;
-        credential = result.value.credential;
+        credential = result.value;
     }
     else {
-        const provider = deps.authManager.providerRegistry.get(target);
-        if (!provider) {
-            process.stderr.write(`Error: No provider found with ID "${target}".\n`);
+        // Fall through to URL-based resolution (with auto-provisioning) for URL-like inputs
+        const isUrl = target.includes('.') || target.startsWith('http');
+        if (!isUrl) {
+            process.stderr.write(`Error: No provider found matching "${target}".\n`);
             process.exitCode = 2;
             return;
         }
-        providerId = provider.id;
-        const result = await deps.authManager.getCredentials(providerId);
+        const result = await deps.authManager.getCredentialsByUrl(target);
         if (!isOk(result)) {
             process.stderr.write(`Error: ${result.error.message}\n`);
             if (result.error.code === 'BROWSER_UNAVAILABLE') {
                 process.stderr.write(`Hint: Run "sig login ${target} --token <token>" or "sig sync pull" to get credentials.\n`);
             }
-            process.exitCode = result.error.code === 'CREDENTIAL_NOT_FOUND' ? 3 : 1;
+            process.exitCode = result.error.code === 'PROVIDER_NOT_FOUND' ? 2 : 3;
             return;
         }
-        credential = result.value;
+        providerId = result.value.provider.id;
+        credential = result.value.credential;
     }
     const headers = deps.authManager.applyToRequest(providerId, credential);
     const entries = Object.entries(headers);

package/dist/cli/commands/login.js

@@ -2,6 +2,7 @@ import { buildStrategyConfig } from '../../config/validator.js';
 import { addProviderToConfig } from '../../config/loader.js';
 import { isOk } from '../../core/result.js';
 import { formatJson } from '../formatters.js';
+import { ProviderNotFoundError } from '../../core/errors.js';
 /** Convert runtime ProviderConfig to the YAML ProviderEntry format. */
 function toProviderEntry(pc) {
     const { strategy: _s, ...strategyRest } = pc.strategyConfig;
@@ -35,11 +36,22 @@ function parseCookieString(raw, domain) {
 export async function runLogin(positionals, flags, deps) {
     const url = positionals[0];
     if (!url) {
-        process.stderr.write('Usage: sig login <url>\n');
+        process.stderr.write('Usage: sig login <provider|url>\n');
         process.exitCode = 1;
         return;
     }
-    const baseProvider = deps.authManager.resolveProvider(url);
+    let baseProvider;
+    try {
+        baseProvider = deps.authManager.resolveProvider(url);
+    }
+    catch (e) {
+        if (e instanceof ProviderNotFoundError) {
+            process.stderr.write(`Error: No provider found matching "${url}". Run "sig providers" to see configured providers.\n`);
+            process.exitCode = 1;
+            return;
+        }
+        throw e;
+    }
     const hasOverrides = flags.strategy !== undefined;
     const provider = hasOverrides
         ? { ...baseProvider }

package/dist/cli/commands/logout.js

@@ -1,8 +1,10 @@
 export async function runLogout(positionals, flags, deps) {
     const providerId = positionals[0];
     if (providerId) {
-        await deps.authManager.clearCredentials(providerId);
-        process.stderr.write(`Credentials cleared for "${providerId}".\n`);
+        const resolved = deps.authManager.providerRegistry.resolveFlexible(providerId);
+        const resolvedId = resolved?.id ?? providerId;
+        await deps.authManager.clearCredentials(resolvedId);
+        process.stderr.write(`Credentials cleared for "${resolvedId}".\n`);
     }
     else {
         await deps.authManager.clearAll();

package/dist/cli/commands/status.js

@@ -3,7 +3,8 @@ export async function runStatus(positionals, flags, deps) {
     const providerId = flags.provider ?? positionals[0];
     const format = flags.format ?? (process.stdout.isTTY ? 'table' : 'json');
     if (providerId) {
-        const status = await deps.authManager.getStatus(providerId);
+        const resolved = deps.authManager.providerRegistry.resolveFlexible(providerId);
+        const status = await deps.authManager.getStatus(resolved?.id ?? providerId);
         if (format === 'json') {
             process.stdout.write(formatJson(status) + '\n');
         }

package/dist/cli/main.js

@@ -44,7 +44,7 @@ const HELP = `Usage: sig <command> [options]
 Commands:
   init                   Set up Signet configuration (interactive)
   get <provider|url>     Get credential headers for a provider or URL
-  login <url>            Authenticate with a system (browser or token)
+  login <provider|url>   Authenticate with a system (browser or token)
   request <url>          Make an authenticated HTTP request
   status [provider]      Show authentication status
   logout [provider]      Clear stored credentials

package/dist/core/interfaces/provider.d.ts

@@ -12,4 +12,6 @@ export interface IProviderRegistry {
     list(): ProviderConfig[];
     /** Register a new provider at runtime. Overwrites if ID already exists. */
     register(provider: ProviderConfig): void;
+    /** Resolve a provider by ID, name (case-insensitive), or URL/domain, in that order. */
+    resolveFlexible(input: string): ProviderConfig | null;
 }

package/dist/providers/provider-registry.d.ts

@@ -16,4 +16,5 @@ export declare class ProviderRegistry implements IProviderRegistry {
     get(id: string): ProviderConfig | null;
     list(): ProviderConfig[];
     register(provider: ProviderConfig): void;
+    resolveFlexible(input: string): ProviderConfig | null;
 }

package/dist/providers/provider-registry.js

@@ -50,6 +50,21 @@ export class ProviderRegistry {
     register(provider) {
         this.providers.set(provider.id, provider);
     }
+    resolveFlexible(input) {
+        // 1. Exact ID match
+        const byId = this.providers.get(input);
+        if (byId)
+            return byId;
+        // 2. Case-insensitive name match
+        const inputLower = input.toLowerCase();
+        for (const provider of this.providers.values()) {
+            if (provider.name.toLowerCase() === inputLower) {
+                return provider;
+            }
+        }
+        // 3. URL/domain match (existing behavior)
+        return this.resolve(input);
+    }
 }
 /**
  * Simple glob matching for domain patterns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signet-auth",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "General-purpose authentication CLI with pluggable strategies and browser adapters",
   "main": "dist/index.js",
   "type": "module",