@chronicle.app/auth 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Louis
+
+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,4 @@
+# Chronicle auth
+
+Standalone credential files, OAuth providers, callback server, and token helpers.
+Uses `CHRONICLE_CONFIG_DIR` or the platform Chronicle config directory.

package/dist/CredentialManager.d.ts

@@ -0,0 +1,49 @@
+import { TokenResponse } from './types.js';
+export interface StoredCredentials {
+    accessToken: string;
+    refreshToken?: string;
+    tokenType: string;
+    expiresIn?: number;
+    scope?: string;
+    createdAt: string;
+    clientId?: string;
+    clientSecret?: string;
+    username?: string;
+}
+export declare class CredentialManager {
+    private static fileManager;
+    private static getFileManager;
+    /**
+     * Store OAuth credentials in local file
+     */
+    static storeCredentials(provider: string, credentials: TokenResponse, clientId?: string, clientSecret?: string): Promise<void>;
+    /**
+     * Retrieve stored credentials from file
+     */
+    static getCredentials(provider: string): Promise<StoredCredentials | null>;
+    /**
+     * Remove credentials from file
+     */
+    static removeCredentials(provider: string): Promise<void>;
+    /**
+     * Check if stored access token is expired
+     */
+    static isTokenExpired(credentials: StoredCredentials): boolean;
+    /**
+     * Get valid access token, checking expiration
+     */
+    static getValidToken(provider: string): Promise<string | null>;
+    /**
+     * List all stored provider credentials
+     */
+    static listProviders(): Promise<string[]>;
+    /**
+     * Check if credentials exist for a provider
+     */
+    static hasCredentials(provider: string): Promise<boolean>;
+    /**
+     * Get the path where credentials are stored (for user reference)
+     */
+    static getCredentialsPath(): string;
+}
+//# sourceMappingURL=CredentialManager.d.ts.map

package/dist/CredentialManager.js

@@ -0,0 +1,69 @@
+import { chronicleConfigDir } from './configDir.js';
+import { FileCredentialManager } from './FileCredentialManager.js';
+export class CredentialManager {
+    static fileManager = null;
+    static getFileManager() {
+        if (!this.fileManager) {
+            // The same config directory oclif resolves, so the file matches what
+            // `chronicle auth set` writes from inside a command.
+            this.fileManager = new FileCredentialManager(chronicleConfigDir());
+        }
+        return this.fileManager;
+    }
+    /**
+     * Store OAuth credentials in local file
+     */
+    static async storeCredentials(provider, credentials, clientId, clientSecret) {
+        const fileManager = this.getFileManager();
+        await fileManager.storeCredentials(provider, credentials, clientId, clientSecret);
+    }
+    /**
+     * Retrieve stored credentials from file
+     */
+    static async getCredentials(provider) {
+        const fileManager = this.getFileManager();
+        return fileManager.getCredentials(provider);
+    }
+    /**
+     * Remove credentials from file
+     */
+    static async removeCredentials(provider) {
+        const fileManager = this.getFileManager();
+        await fileManager.removeCredentials(provider);
+    }
+    /**
+     * Check if stored access token is expired
+     */
+    static isTokenExpired(credentials) {
+        const fileManager = this.getFileManager();
+        return fileManager.isTokenExpired(credentials);
+    }
+    /**
+     * Get valid access token, checking expiration
+     */
+    static async getValidToken(provider) {
+        const fileManager = this.getFileManager();
+        return fileManager.getValidToken(provider);
+    }
+    /**
+     * List all stored provider credentials
+     */
+    static async listProviders() {
+        const fileManager = this.getFileManager();
+        return fileManager.listProviders();
+    }
+    /**
+     * Check if credentials exist for a provider
+     */
+    static async hasCredentials(provider) {
+        const fileManager = this.getFileManager();
+        return fileManager.hasCredentials(provider);
+    }
+    /**
+     * Get the path where credentials are stored (for user reference)
+     */
+    static getCredentialsPath() {
+        const fileManager = this.getFileManager();
+        return fileManager.getCredentialsPath();
+    }
+}

package/dist/FileCredentialManager.d.ts

@@ -0,0 +1,78 @@
+import { TokenResponse } from './types.js';
+export interface StoredCredentials {
+    accessToken: string;
+    refreshToken?: string;
+    tokenType: string;
+    expiresIn?: number;
+    scope?: string;
+    createdAt: string;
+    clientId?: string;
+    clientSecret?: string;
+    username?: string;
+    [key: string]: any;
+}
+export declare class FileCredentialManager {
+    private credentialsPath;
+    constructor(configDir: string);
+    /**
+     * Load all credentials from file
+     */
+    private loadCredentials;
+    /**
+     * Migrate old credential format (single objects) to new format (arrays)
+     */
+    private migrateCredentialsFormat;
+    /**
+     * Save all credentials to file
+     */
+    private saveCredentials;
+    /**
+     * Store OAuth credentials for a provider
+     */
+    storeCredentials(provider: string, tokenResponse: TokenResponse, clientId?: string, clientSecret?: string): Promise<void>;
+    /**
+     * Update stored credentials directly (used for token refresh)
+     */
+    private updateStoredCredentials;
+    /**
+     * Retrieve stored credentials for a provider (returns most recent credential)
+     */
+    getCredentials(provider: string): Promise<StoredCredentials | null>;
+    /**
+     * Retrieve all stored credentials for a provider
+     */
+    getAllCredentials(provider: string): Promise<StoredCredentials[]>;
+    /**
+     * Remove credentials for a provider
+     */
+    removeCredentials(provider: string): Promise<void>;
+    /**
+     * Check if stored access token is expired
+     */
+    isTokenExpired(credentials: StoredCredentials): boolean;
+    /**
+     * Get valid access token, checking expiration
+     */
+    getValidToken(provider: string): Promise<string | null>;
+    /**
+     * Refresh an expired token using the refresh token
+     */
+    private refreshToken;
+    /**
+     * Get the token refresh URL for a specific provider
+     */
+    private getRefreshUrl;
+    /**
+     * List all providers with stored credentials
+     */
+    listProviders(): Promise<string[]>;
+    /**
+     * Check if credentials exist for a provider
+     */
+    hasCredentials(provider: string): Promise<boolean>;
+    /**
+     * Get the path where credentials are stored (for user reference)
+     */
+    getCredentialsPath(): string;
+}
+//# sourceMappingURL=FileCredentialManager.d.ts.map

package/dist/FileCredentialManager.js

@@ -0,0 +1,241 @@
+import { promises as fs } from 'node:fs';
+import { join, dirname } from 'node:path';
+export class FileCredentialManager {
+    credentialsPath;
+    constructor(configDir) {
+        this.credentialsPath = join(configDir, 'credentials.json');
+    }
+    /**
+     * Load all credentials from file
+     */
+    async loadCredentials() {
+        try {
+            const credentialsText = await fs.readFile(this.credentialsPath, 'utf-8');
+            const parsed = JSON.parse(credentialsText);
+            // Migrate old format to new array format
+            return this.migrateCredentialsFormat(parsed);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                // Credentials file doesn't exist, return empty
+                return {};
+            }
+            // If file is invalid, return empty and log warning
+            console.warn('Invalid credentials file, starting fresh:', error);
+            return {};
+        }
+    }
+    /**
+     * Migrate old credential format (single objects) to new format (arrays)
+     */
+    migrateCredentialsFormat(credentials) {
+        const migrated = {};
+        for (const [provider, creds] of Object.entries(credentials)) {
+            if (Array.isArray(creds)) {
+                // Already in new format
+                migrated[provider] = creds;
+            }
+            else {
+                // Old format - convert to array
+                migrated[provider] = [creds];
+            }
+        }
+        return migrated;
+    }
+    /**
+     * Save all credentials to file
+     */
+    async saveCredentials(credentials) {
+        // Ensure config directory exists
+        await fs.mkdir(dirname(this.credentialsPath), { recursive: true });
+        // Write credentials file with proper formatting and permissions
+        await fs.writeFile(this.credentialsPath, JSON.stringify(credentials, null, 2), { mode: 0o600 } // Restrict to user read/write only
+        );
+    }
+    /**
+     * Store OAuth credentials for a provider
+     */
+    async storeCredentials(provider, tokenResponse, clientId, clientSecret) {
+        const credentials = await this.loadCredentials();
+        // Initialize provider array if it doesn't exist
+        if (!credentials[provider]) {
+            credentials[provider] = [];
+        }
+        const newCredential = {
+            accessToken: tokenResponse.access_token,
+            refreshToken: tokenResponse.refresh_token,
+            tokenType: tokenResponse.token_type,
+            expiresIn: tokenResponse.expires_in,
+            scope: tokenResponse.scope,
+            createdAt: tokenResponse.created_at,
+            clientId,
+            clientSecret,
+            // Include any additional fields from the token response
+            ...Object.fromEntries(Object.entries(tokenResponse).filter(([key]) => ![
+                'access_token',
+                'refresh_token',
+                'token_type',
+                'expires_in',
+                'scope',
+                'created_at',
+                'provider',
+            ].includes(key))),
+        };
+        // Add new credential to the array
+        credentials[provider].push(newCredential);
+        await this.saveCredentials(credentials);
+    }
+    /**
+     * Update stored credentials directly (used for token refresh)
+     */
+    async updateStoredCredentials(provider, updatedCredentials) {
+        const credentials = await this.loadCredentials();
+        if (!credentials[provider] || credentials[provider].length === 0) {
+            credentials[provider] = [updatedCredentials];
+        }
+        else {
+            credentials[provider][0] = updatedCredentials;
+        }
+        await this.saveCredentials(credentials);
+    }
+    /**
+     * Retrieve stored credentials for a provider (returns most recent credential)
+     */
+    async getCredentials(provider) {
+        const credentials = await this.loadCredentials();
+        const providerCredentials = credentials[provider];
+        return providerCredentials && providerCredentials.length > 0
+            ? (providerCredentials.at(-1) ?? null)
+            : null;
+    }
+    /**
+     * Retrieve all stored credentials for a provider
+     */
+    async getAllCredentials(provider) {
+        const credentials = await this.loadCredentials();
+        return credentials[provider] || [];
+    }
+    /**
+     * Remove credentials for a provider
+     */
+    async removeCredentials(provider) {
+        const credentials = await this.loadCredentials();
+        delete credentials[provider];
+        await this.saveCredentials(credentials);
+    }
+    /**
+     * Check if stored access token is expired
+     */
+    isTokenExpired(credentials) {
+        if (!credentials.expiresIn) {
+            return false; // No expiration info, assume valid
+        }
+        const createdAt = new Date(credentials.createdAt).getTime();
+        const expiresAt = createdAt + credentials.expiresIn * 1000;
+        const now = Date.now();
+        // Consider expired if less than 5 minutes remaining
+        const bufferTime = 5 * 60 * 1000; // 5 minutes
+        return now >= expiresAt - bufferTime;
+    }
+    /**
+     * Get valid access token, checking expiration
+     */
+    async getValidToken(provider) {
+        const credentials = await this.getCredentials(provider);
+        if (!credentials) {
+            return null;
+        }
+        // If token is not expired, return it
+        if (!this.isTokenExpired(credentials)) {
+            return credentials.accessToken;
+        }
+        // Token is expired - try to refresh if we have refresh token and client secret
+        if (credentials.refreshToken && credentials.clientId && credentials.clientSecret) {
+            try {
+                const refreshedToken = await this.refreshToken(provider, credentials);
+                if (refreshedToken) {
+                    return refreshedToken;
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to refresh ${provider} token:`, error instanceof Error ? error.message : error);
+            }
+        }
+        return null;
+    }
+    /**
+     * Refresh an expired token using the refresh token
+     */
+    async refreshToken(provider, credentials) {
+        if (!credentials.refreshToken || !credentials.clientId || !credentials.clientSecret) {
+            return null;
+        }
+        const refreshUrl = this.getRefreshUrl(provider);
+        if (!refreshUrl) {
+            return null;
+        }
+        try {
+            const response = await fetch(refreshUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Authorization: `Basic ${Buffer.from(`${credentials.clientId}:${credentials.clientSecret}`).toString('base64')}`,
+                },
+                body: new URLSearchParams({
+                    grant_type: 'refresh_token',
+                    refresh_token: credentials.refreshToken,
+                }),
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`HTTP ${response.status}: ${errorText}`);
+            }
+            const tokenData = (await response.json());
+            // Update stored credentials with new token
+            const updatedCredentials = {
+                ...credentials,
+                accessToken: tokenData.access_token,
+                refreshToken: tokenData.refresh_token || credentials.refreshToken,
+                expiresIn: tokenData.expires_in,
+                createdAt: new Date().toISOString(),
+            };
+            await this.updateStoredCredentials(provider, updatedCredentials);
+            return tokenData.access_token;
+        }
+        catch (error) {
+            throw new Error(`Token refresh failed: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    /**
+     * Get the token refresh URL for a specific provider
+     */
+    getRefreshUrl(provider) {
+        const refreshUrls = {
+            spotify: 'https://accounts.spotify.com/api/token',
+            // Google's token endpoint accepts client_secret_basic, so the shared
+            // Basic-auth refresh above works for it.
+            youtube: 'https://oauth2.googleapis.com/token',
+        };
+        return refreshUrls[provider] || null;
+    }
+    /**
+     * List all providers with stored credentials
+     */
+    async listProviders() {
+        const credentials = await this.loadCredentials();
+        return Object.keys(credentials);
+    }
+    /**
+     * Check if credentials exist for a provider
+     */
+    async hasCredentials(provider) {
+        const credentials = await this.getCredentials(provider);
+        return credentials !== null;
+    }
+    /**
+     * Get the path where credentials are stored (for user reference)
+     */
+    getCredentialsPath() {
+        return this.credentialsPath;
+    }
+}

package/dist/OAuthProvider.d.ts

@@ -0,0 +1,57 @@
+import { OAuthParams, TokenResponse, OAuthConfig } from './types.js';
+/**
+ * Base OAuth2 authorization-code flow. A standard provider only declares the
+ * endpoints, scopes, and credential style:
+ *
+ *   class MyProvider extends OAuthProvider {
+ *     static override providerId = 'my-source';
+ *     static override authorizationUrl = 'https://example.com/authorize';
+ *     static override tokenUrl = 'https://example.com/token';
+ *     static override scopes = ['read'];
+ *     static override tokenAuthStyle = 'basic-header';   // or 'body' (default)
+ *     static override extraAuthParams = { access_type: 'offline' };
+ *   }
+ *
+ * A provider whose protocol deviates from OAuth2 (e.g. Last.fm's signed
+ * auth.getSession) overrides buildAuthUrl / exchangeCodeForToken instead.
+ */
+export declare abstract class OAuthProvider {
+    static providerId: string;
+    static authorizationUrl: string;
+    static tokenUrl: string;
+    static scopes: string[];
+    static requiresClientSecret: boolean;
+    /**
+     * Where the client credentials go on the token exchange: 'basic-header'
+     * sends an Authorization: Basic header; 'body' (default) puts
+     * client_id/client_secret in the form body.
+     */
+    static tokenAuthStyle: 'basic-header' | 'body';
+    /** Provider-specific additions to the authorization URL. */
+    static extraAuthParams: Record<string, string>;
+    protected params: OAuthParams;
+    constructor(params: OAuthParams);
+    static getConfig(): OAuthConfig;
+    private get providerClass();
+    /**
+     * Build the authorization URL where the user will be redirected
+     */
+    buildAuthUrl(): string;
+    /**
+     * Exchange authorization code for access tokens
+     */
+    exchangeCodeForToken(code: string): Promise<TokenResponse>;
+    /** One POST to the token endpoint; overridable so tests can mock HTTP. */
+    protected postToken(url: string, data: URLSearchParams, config: {
+        headers: Record<string, string>;
+    }): Promise<any>;
+    /**
+     * Generate a random state parameter for CSRF protection
+     */
+    protected generateState(): string;
+    /**
+     * Build query string from parameters
+     */
+    protected buildQueryString(params: Record<string, string>): string;
+}
+//# sourceMappingURL=OAuthProvider.d.ts.map

package/dist/OAuthProvider.js

@@ -0,0 +1,129 @@
+import axios from 'axios';
+/**
+ * Base OAuth2 authorization-code flow. A standard provider only declares the
+ * endpoints, scopes, and credential style:
+ *
+ *   class MyProvider extends OAuthProvider {
+ *     static override providerId = 'my-source';
+ *     static override authorizationUrl = 'https://example.com/authorize';
+ *     static override tokenUrl = 'https://example.com/token';
+ *     static override scopes = ['read'];
+ *     static override tokenAuthStyle = 'basic-header';   // or 'body' (default)
+ *     static override extraAuthParams = { access_type: 'offline' };
+ *   }
+ *
+ * A provider whose protocol deviates from OAuth2 (e.g. Last.fm's signed
+ * auth.getSession) overrides buildAuthUrl / exchangeCodeForToken instead.
+ */
+export class OAuthProvider {
+    static providerId;
+    static authorizationUrl;
+    static tokenUrl;
+    static scopes = [];
+    static requiresClientSecret = true;
+    /**
+     * Where the client credentials go on the token exchange: 'basic-header'
+     * sends an Authorization: Basic header; 'body' (default) puts
+     * client_id/client_secret in the form body.
+     */
+    static tokenAuthStyle = 'body';
+    /** Provider-specific additions to the authorization URL. */
+    static extraAuthParams = {};
+    params;
+    constructor(params) {
+        this.params = params;
+    }
+    static getConfig() {
+        return {
+            providerId: this.providerId,
+            authorizationUrl: this.authorizationUrl,
+            tokenUrl: this.tokenUrl,
+            scopes: this.scopes,
+            requiresClientSecret: this.requiresClientSecret,
+        };
+    }
+    get providerClass() {
+        return this.constructor;
+    }
+    /**
+     * Build the authorization URL where the user will be redirected
+     */
+    buildAuthUrl() {
+        const cls = this.providerClass;
+        const params = {
+            client_id: this.params.clientId,
+            response_type: 'code',
+            redirect_uri: this.params.redirectUri,
+        };
+        const scope = (this.params.scopes?.length ? this.params.scopes : cls.scopes).join(' ');
+        if (scope) {
+            params.scope = scope;
+        }
+        Object.assign(params, cls.extraAuthParams);
+        if (this.params.state) {
+            params.state = this.params.state;
+        }
+        return `${cls.authorizationUrl}?${this.buildQueryString(params)}`;
+    }
+    /**
+     * Exchange authorization code for access tokens
+     */
+    async exchangeCodeForToken(code) {
+        const cls = this.providerClass;
+        try {
+            const data = new URLSearchParams({
+                grant_type: 'authorization_code',
+                code,
+                redirect_uri: this.params.redirectUri,
+            });
+            const headers = {
+                'Content-Type': 'application/x-www-form-urlencoded',
+            };
+            if (cls.tokenAuthStyle === 'basic-header') {
+                const credentials = Buffer.from(`${this.params.clientId}:${this.params.clientSecret}`).toString('base64');
+                headers.Authorization = `Basic ${credentials}`;
+            }
+            else {
+                data.set('client_id', this.params.clientId);
+                data.set('client_secret', this.params.clientSecret);
+            }
+            const response = await this.postToken(cls.tokenUrl, data, { headers });
+            return {
+                provider: cls.providerId,
+                access_token: response.access_token,
+                refresh_token: response.refresh_token,
+                // Some providers (foursquare) omit token_type on the exchange
+                token_type: response.token_type ?? 'Bearer',
+                expires_in: response.expires_in,
+                scope: response.scope,
+                created_at: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            if (axios.isAxiosError(error)) {
+                const message = error.response?.data?.error_description || error.response?.data?.error || error.message;
+                throw new Error(`Failed to exchange code for tokens: ${message}`);
+            }
+            throw error;
+        }
+    }
+    /** One POST to the token endpoint; overridable so tests can mock HTTP. */
+    async postToken(url, data, config) {
+        const response = await axios.post(url, data, config);
+        return response.data;
+    }
+    /**
+     * Generate a random state parameter for CSRF protection
+     */
+    generateState() {
+        return Math.random().toString(36).slice(2, 15) + Math.random().toString(36).slice(2, 15);
+    }
+    /**
+     * Build query string from parameters
+     */
+    buildQueryString(params) {
+        return Object.entries(params)
+            .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(value)}`)
+            .join('&');
+    }
+}

package/dist/OAuthServer.d.ts

@@ -0,0 +1,16 @@
+import type { AuthorizationResult } from './types.js';
+/** A loopback-only callback server. Its pending callback always settles on shutdown. */
+export declare class OAuthServer {
+    private server?;
+    private port?;
+    private timeout?;
+    private result?;
+    private failure?;
+    private resolve?;
+    private reject?;
+    start(preferredPort?: number, timeoutMs?: number): Promise<number>;
+    waitForCallback(): Promise<AuthorizationResult>;
+    stop(error?: Error): void;
+    getCallbackUrl(): string;
+}
+//# sourceMappingURL=OAuthServer.d.ts.map

package/dist/OAuthServer.js

@@ -0,0 +1,89 @@
+import http from 'node:http';
+/** A loopback-only callback server. Its pending callback always settles on shutdown. */
+export class OAuthServer {
+    server;
+    port;
+    timeout;
+    result;
+    failure;
+    resolve;
+    reject;
+    async start(preferredPort = 0, timeoutMs = 5 * 60 * 1000) {
+        if (this.server)
+            throw new Error('OAuth server already started');
+        this.result = undefined;
+        this.failure = undefined;
+        const server = http.createServer((request, response) => {
+            const url = new URL(request.url || '/', 'http://127.0.0.1');
+            if (url.pathname !== '/callback') {
+                response.writeHead(url.pathname === '/' ? 200 : 404, { 'Content-Type': 'text/plain' });
+                response.end(url.pathname === '/' ? 'Waiting for authorization.' : 'Not found');
+                return;
+            }
+            const result = {};
+            for (const key of ['code', 'token', 'state', 'error', 'error_description']) {
+                const value = url.searchParams.get(key);
+                if (value !== null)
+                    result[key] = value;
+            }
+            this.result = result;
+            response.writeHead(result.error ? 400 : 200, { 'Content-Type': 'text/plain' });
+            response.end(result.error
+                ? 'Authorization failed. Return to your terminal.'
+                : 'Authorization received. Return to your terminal.');
+            this.resolve?.(result);
+        });
+        this.server = server;
+        try {
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(preferredPort, '127.0.0.1', () => {
+                    server.removeListener('error', reject);
+                    resolve();
+                });
+            });
+            const address = server.address();
+            if (!address || typeof address === 'string')
+                throw new Error('Failed to start OAuth server');
+            this.port = address.port;
+            this.timeout = setTimeout(() => this.stop(new Error('OAuth authorization timed out')), timeoutMs);
+            return this.port;
+        }
+        catch (error) {
+            this.stop();
+            throw error;
+        }
+    }
+    async waitForCallback() {
+        if (this.result)
+            return this.result;
+        if (this.failure)
+            throw this.failure;
+        if (!this.server)
+            throw new Error('Server not started');
+        return new Promise((resolve, reject) => {
+            this.resolve = resolve;
+            this.reject = reject;
+        });
+    }
+    stop(error = new Error('OAuth authorization cancelled')) {
+        if (this.timeout)
+            clearTimeout(this.timeout);
+        this.timeout = undefined;
+        if (!this.result) {
+            this.failure = error;
+            this.reject?.(error);
+        }
+        this.resolve = undefined;
+        this.reject = undefined;
+        this.server?.closeAllConnections();
+        this.server?.close();
+        this.server = undefined;
+        this.port = undefined;
+    }
+    getCallbackUrl() {
+        if (!this.port)
+            throw new Error('Server not started');
+        return `http://127.0.0.1:${this.port}/callback`;
+    }
+}

package/dist/ProviderRegistry.d.ts

@@ -0,0 +1,25 @@
+import { OAuthProvider } from './OAuthProvider.js';
+export declare class OAuthProviderRegistry {
+    private static providers;
+    /**
+     * Register an OAuth provider
+     */
+    static register(provider: typeof OAuthProvider): void;
+    /**
+     * Get a provider by ID
+     */
+    static get(providerId: string): typeof OAuthProvider | undefined;
+    /**
+     * Get all registered provider IDs
+     */
+    static getProviderIds(): string[];
+    /**
+     * Check if a provider is registered
+     */
+    static has(providerId: string): boolean;
+    /**
+     * Get all providers
+     */
+    static getAll(): Map<string, typeof OAuthProvider>;
+}
+//# sourceMappingURL=ProviderRegistry.d.ts.map

package/dist/ProviderRegistry.js

@@ -0,0 +1,36 @@
+export class OAuthProviderRegistry {
+    static providers = new Map();
+    /**
+     * Register an OAuth provider
+     */
+    static register(provider) {
+        if (!provider.providerId) {
+            throw new Error(`Provider must have a providerId: ${provider.name}`);
+        }
+        this.providers.set(provider.providerId, provider);
+    }
+    /**
+     * Get a provider by ID
+     */
+    static get(providerId) {
+        return this.providers.get(providerId);
+    }
+    /**
+     * Get all registered provider IDs
+     */
+    static getProviderIds() {
+        return [...this.providers.keys()];
+    }
+    /**
+     * Check if a provider is registered
+     */
+    static has(providerId) {
+        return this.providers.has(providerId);
+    }
+    /**
+     * Get all providers
+     */
+    static getAll() {
+        return new Map(this.providers);
+    }
+}

package/dist/TokenHelper.d.ts

@@ -0,0 +1,23 @@
+export declare const TokenHelper: {
+    /**
+     * Get a valid access token for a provider, with user-friendly error messages
+     */
+    getValidToken(provider: string): Promise<string>;
+    /**
+     * Get token or use provided access token, with preference for keychain
+     */
+    getTokenWithFallback(provider: string, providedToken?: string): Promise<string>;
+    /**
+     * Check if valid credentials exist for a provider
+     */
+    hasValidCredentials(provider: string): Promise<boolean>;
+    /**
+     * Remove stored credentials (for logout/reset)
+     */
+    removeCredentials(provider: string): Promise<void>;
+    /**
+     * List providers with stored credentials
+     */
+    listProvidersWithCredentials(): Promise<string[]>;
+};
+//# sourceMappingURL=TokenHelper.d.ts.map

package/dist/TokenHelper.js

@@ -0,0 +1,56 @@
+import { CredentialManager } from './CredentialManager.js';
+export const TokenHelper = {
+    /**
+     * Get a valid access token for a provider, with user-friendly error messages
+     */
+    async getValidToken(provider) {
+        const token = await CredentialManager.getValidToken(provider);
+        if (!token) {
+            const hasCredentials = await CredentialManager.hasCredentials(provider);
+            if (hasCredentials) {
+                throw new Error(`${provider} credentials are expired and could not be refreshed. Please re-authenticate:\n` +
+                    `  chronicle auth ${provider} --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET`);
+            }
+            else {
+                throw new Error(`No ${provider} credentials found. Please authenticate first:\n` +
+                    `  chronicle auth ${provider} --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET`);
+            }
+        }
+        return token;
+    },
+    /**
+     * Get token or use provided access token, with preference for keychain
+     */
+    async getTokenWithFallback(provider, providedToken) {
+        // If user provided a token explicitly, use it
+        if (providedToken) {
+            return providedToken;
+        }
+        // Otherwise try to get from keychain
+        return this.getValidToken(provider);
+    },
+    /**
+     * Check if valid credentials exist for a provider
+     */
+    async hasValidCredentials(provider) {
+        try {
+            const token = await CredentialManager.getValidToken(provider);
+            return token !== null;
+        }
+        catch {
+            return false;
+        }
+    },
+    /**
+     * Remove stored credentials (for logout/reset)
+     */
+    async removeCredentials(provider) {
+        await CredentialManager.removeCredentials(provider);
+    },
+    /**
+     * List providers with stored credentials
+     */
+    async listProvidersWithCredentials() {
+        return CredentialManager.listProviders();
+    },
+};

package/dist/configDir.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The directory Chronicle keeps its config and credentials in — the same one
+ * oclif resolves for `Config.configDir`, so code running outside an oclif
+ * command (the agent harness, plugins' own tooling) reads the files that
+ * `chronicle config set` and `chronicle auth set` write. `CHRONICLE_CONFIG_DIR`
+ * is oclif's scoped override, then XDG_CONFIG_HOME / LOCALAPPDATA (Windows) /
+ * ~/.config, mirroring `@oclif/core` `Config.dir('config')`.
+ */
+export declare function chronicleConfigDir(): string;
+//# sourceMappingURL=configDir.d.ts.map

package/dist/configDir.js

@@ -0,0 +1,16 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * The directory Chronicle keeps its config and credentials in — the same one
+ * oclif resolves for `Config.configDir`, so code running outside an oclif
+ * command (the agent harness, plugins' own tooling) reads the files that
+ * `chronicle config set` and `chronicle auth set` write. `CHRONICLE_CONFIG_DIR`
+ * is oclif's scoped override, then XDG_CONFIG_HOME / LOCALAPPDATA (Windows) /
+ * ~/.config, mirroring `@oclif/core` `Config.dir('config')`.
+ */
+export function chronicleConfigDir() {
+    return (process.env.CHRONICLE_CONFIG_DIR ||
+        join(process.env.XDG_CONFIG_HOME ||
+            (process.platform === 'win32' && process.env.LOCALAPPDATA) ||
+            join(homedir(), '.config'), 'chronicle'));
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from './CredentialManager.js';
+export { FileCredentialManager } from './FileCredentialManager.js';
+export * from './OAuthProvider.js';
+export * from './ProviderRegistry.js';
+export * from './OAuthServer.js';
+export * from './TokenHelper.js';
+export * from './resolveCredentials.js';
+export * from './types.js';
+export * from './configDir.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+export * from './CredentialManager.js';
+export { FileCredentialManager } from './FileCredentialManager.js';
+export * from './OAuthProvider.js';
+export * from './ProviderRegistry.js';
+export * from './OAuthServer.js';
+export * from './TokenHelper.js';
+export * from './resolveCredentials.js';
+export * from './types.js';
+export * from './configDir.js';

package/dist/resolveCredentials.d.ts

@@ -0,0 +1,36 @@
+import { StoredCredentials } from './CredentialManager.js';
+/**
+ * Shared credential resolution for API plugins. Consolidates the per-plugin
+ * pattern of "flag/constructor value, else stored credential under one of a
+ * few historical field names, else a source-specific error".
+ *
+ * This is the CredentialManager (stored-secret) path; OAuth sources that need
+ * refresh go through TokenHelper.getValidToken instead.
+ */
+export interface CredentialFieldSpec {
+    /** StoredCredentials fields tried in order until one has a value. */
+    from: Array<keyof StoredCredentials | string>;
+    /** Optional fields resolve to undefined instead of failing the lookup. */
+    optional?: boolean;
+}
+export interface ResolveCredentialsOptions {
+    /**
+     * Already-resolved values (CLI flags, constructor args). A non-empty
+     * override wins without consulting the store.
+     */
+    overrides?: Record<string, string | undefined>;
+    /**
+     * Full replacement for the missing-credential error, so a plugin keeps its
+     * exact user-facing message (auth command, credential-creation URL, …).
+     */
+    errorMessage?: string;
+}
+/** Pure resolution core, separated for testing. */
+export declare function pickCredentialFields<F extends string>(provider: string, stored: object | null, fields: Record<F, CredentialFieldSpec>, options?: ResolveCredentialsOptions): Record<F, string | undefined>;
+/**
+ * Resolve a source's credentials: overrides first, then the stored
+ * credentials under each field's alias chain. Throws when a required field
+ * is missing everywhere.
+ */
+export declare function resolveCredentials<F extends string>(provider: string, fields: Record<F, CredentialFieldSpec>, options?: ResolveCredentialsOptions): Promise<Record<F, string | undefined>>;
+//# sourceMappingURL=resolveCredentials.d.ts.map

package/dist/resolveCredentials.js

@@ -0,0 +1,44 @@
+import { CredentialManager } from './CredentialManager.js';
+/** Pure resolution core, separated for testing. */
+export function pickCredentialFields(provider, stored, fields, options = {}) {
+    const resolved = {};
+    const missing = [];
+    const storedFields = (stored ?? {});
+    for (const name of Object.keys(fields)) {
+        const spec = fields[name];
+        const override = options.overrides?.[name];
+        let value = override || undefined;
+        if (value === undefined && stored) {
+            for (const alias of spec.from) {
+                const candidate = storedFields[alias];
+                if (typeof candidate === 'string' && candidate !== '') {
+                    value = candidate;
+                    break;
+                }
+            }
+        }
+        resolved[name] = value;
+        if (value === undefined && !spec.optional)
+            missing.push(name);
+    }
+    if (missing.length > 0) {
+        throw new Error(options.errorMessage ??
+            `${provider} credentials are missing ${missing.join(', ')}. Authenticate with: chronicle auth ${provider}`);
+    }
+    return resolved;
+}
+/**
+ * Resolve a source's credentials: overrides first, then the stored
+ * credentials under each field's alias chain. Throws when a required field
+ * is missing everywhere.
+ */
+export async function resolveCredentials(provider, fields, options = {}) {
+    let stored = null;
+    try {
+        stored = await CredentialManager.getCredentials(provider);
+    }
+    catch {
+        // No stored credentials — overrides may still satisfy the spec.
+    }
+    return pickCredentialFields(provider, stored, fields, options);
+}

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+export interface OAuthParams {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes?: string[];
+    state?: string;
+}
+export interface TokenResponse {
+    provider: string;
+    access_token: string;
+    refresh_token?: string;
+    token_type: string;
+    expires_in?: number;
+    scope?: string;
+    created_at: string;
+    username?: string;
+}
+export interface OAuthConfig {
+    providerId: string;
+    authorizationUrl: string;
+    tokenUrl: string;
+    scopes: string[];
+    requiresClientSecret: boolean;
+}
+export interface AuthorizationResult {
+    code?: string;
+    token?: string;
+    state?: string;
+    error?: string;
+    error_description?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@chronicle.app/auth",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "scripts": {
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "lint": "eslint src --ext .ts,.js",
+    "test": "node --test src/*.test.js"
+  },
+  "keywords": [],
+  "author": "Andrew Louis",
+  "license": "MIT",
+  "type": "module",
+  "description": "Standalone Chronicle credential and OAuth services",
+  "devDependencies": {
+    "@chronicle.app/tsconfig": "0.1.0",
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2"
+  },
+  "homepage": "https://chronicle.app",
+  "bugs": {
+    "url": "https://github.com/chronicle-app/chronicle/issues/new?labels=core:etl&title=[etl]%20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chronicle-app/chronicle.git",
+    "directory": "core/auth"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "axios": "^1.7.9"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  }
+}