@chronicle.app/auth 0.3.0 → 0.4.0

package/dist/CredentialManager.d.ts

@@ -9,18 +9,30 @@ export interface StoredCredentials {
     clientId?: string;
     clientSecret?: string;
     username?: string;
+    /** Which account signed in, for a provider with several. */
+    account?: string;
+    /** Where the refresh token is exchanged. */
+    tokenUrl?: string;
 }
 export declare class CredentialManager {
     private static fileManager;
+    private static fileManagerDir;
     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
+     * Retrieve stored credentials from file: the given account's, or the most
+     * recent sign-in
      */
-    static getCredentials(provider: string): Promise<StoredCredentials | null>;
+    static getCredentials(provider: string, options?: {
+        account?: string;
+    }): Promise<StoredCredentials | null>;
+    /**
+     * Every account's stored credentials for a provider
+     */
+    static getAllCredentials(provider: string): Promise<StoredCredentials[]>;
     /**
      * Remove credentials from file
      */
@@ -32,7 +44,10 @@ export declare class CredentialManager {
     /**
      * Get valid access token, checking expiration
      */
-    static getValidToken(provider: string): Promise<string | null>;
+    static getValidToken(provider: string, options?: {
+        account?: string;
+        refresh?: boolean;
+    }): Promise<string | null>;
     /**
      * List all stored provider credentials
      */

package/dist/CredentialManager.js

@@ -2,11 +2,15 @@ import { chronicleConfigDir } from './configDir.js';
 import { FileCredentialManager } from './FileCredentialManager.js';
 export class CredentialManager {
     static fileManager = null;
+    static fileManagerDir = 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());
+        // The same config directory oclif resolves, so the file matches what
+        // `chronicle auth set` writes from inside a command. Looked up each time,
+        // so a change to CHRONICLE_CONFIG_DIR (a test's own directory) is seen.
+        const dir = chronicleConfigDir();
+        if (!this.fileManager || this.fileManagerDir !== dir) {
+            this.fileManager = new FileCredentialManager(dir);
+            this.fileManagerDir = dir;
         }
         return this.fileManager;
     }
@@ -18,11 +22,19 @@ export class CredentialManager {
         await fileManager.storeCredentials(provider, credentials, clientId, clientSecret);
     }
     /**
-     * Retrieve stored credentials from file
+     * Retrieve stored credentials from file: the given account's, or the most
+     * recent sign-in
      */
-    static async getCredentials(provider) {
+    static async getCredentials(provider, options = {}) {
         const fileManager = this.getFileManager();
-        return fileManager.getCredentials(provider);
+        return fileManager.getCredentials(provider, options);
+    }
+    /**
+     * Every account's stored credentials for a provider
+     */
+    static async getAllCredentials(provider) {
+        const fileManager = this.getFileManager();
+        return fileManager.getAllCredentials(provider);
     }
     /**
      * Remove credentials from file
@@ -41,9 +53,9 @@ export class CredentialManager {
     /**
      * Get valid access token, checking expiration
      */
-    static async getValidToken(provider) {
+    static async getValidToken(provider, options = {}) {
         const fileManager = this.getFileManager();
-        return fileManager.getValidToken(provider);
+        return fileManager.getValidToken(provider, options);
     }
     /**
      * List all stored provider credentials

package/dist/FileCredentialManager.d.ts

@@ -9,6 +9,10 @@ export interface StoredCredentials {
     clientId?: string;
     clientSecret?: string;
     username?: string;
+    /** Which account signed in, for a provider with several. */
+    account?: string;
+    /** Where the refresh token is exchanged. */
+    tokenUrl?: string;
     [key: string]: any;
 }
 export declare class FileCredentialManager {
@@ -27,17 +31,23 @@ export declare class FileCredentialManager {
      */
     private saveCredentials;
     /**
-     * Store OAuth credentials for a provider
+     * Store OAuth credentials for a provider. A provider keeps one entry per
+     * account: signing in again replaces that account's entry, and a provider
+     * that doesn't name accounts keeps just one.
      */
     storeCredentials(provider: string, tokenResponse: TokenResponse, clientId?: string, clientSecret?: string): Promise<void>;
     /**
-     * Update stored credentials directly (used for token refresh)
+     * Replace the stored entry that `previous` was read from (used for token
+     * refresh), matched on its account, else its refresh token.
      */
     private updateStoredCredentials;
     /**
-     * Retrieve stored credentials for a provider (returns most recent credential)
+     * Retrieve stored credentials for a provider: the given account's, or the
+     * most recent sign-in.
      */
-    getCredentials(provider: string): Promise<StoredCredentials | null>;
+    getCredentials(provider: string, { account }?: {
+        account?: string;
+    }): Promise<StoredCredentials | null>;
     /**
      * Retrieve all stored credentials for a provider
      */
@@ -53,13 +63,17 @@ export declare class FileCredentialManager {
     /**
      * Get valid access token, checking expiration
      */
-    getValidToken(provider: string): Promise<string | null>;
+    getValidToken(provider: string, options?: {
+        account?: string;
+        refresh?: boolean;
+    }): Promise<string | null>;
     /**
      * Refresh an expired token using the refresh token
      */
     private refreshToken;
     /**
-     * Get the token refresh URL for a specific provider
+     * The token refresh URL for credentials stored before the token URL was
+     * saved with them.
      */
     private getRefreshUrl;
     /**

package/dist/FileCredentialManager.js

@@ -1,5 +1,7 @@
 import { promises as fs } from 'node:fs';
 import { join, dirname } from 'node:path';
+import { createLogger } from '@chronicle.app/logging';
+const logger = createLogger({ scope: 'credentials' });
 export class FileCredentialManager {
     credentialsPath;
     constructor(configDir) {
@@ -21,7 +23,7 @@ export class FileCredentialManager {
                 return {};
             }
             // If file is invalid, return empty and log warning
-            console.warn('Invalid credentials file, starting fresh:', error);
+            logger.warn('Invalid credentials file, starting fresh', { error: String(error) });
             return {};
         }
     }
@@ -53,14 +55,12 @@ export class FileCredentialManager {
         );
     }
     /**
-     * Store OAuth credentials for a provider
+     * Store OAuth credentials for a provider. A provider keeps one entry per
+     * account: signing in again replaces that account's entry, and a provider
+     * that doesn't name accounts keeps just one.
      */
     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,
@@ -81,32 +81,45 @@ export class FileCredentialManager {
                 'provider',
             ].includes(key))),
         };
-        // Add new credential to the array
-        credentials[provider].push(newCredential);
+        const kept = (credentials[provider] ?? []).filter(existing => newCredential.account && existing.account !== newCredential.account);
+        // Google sends a refresh token only on the first consent for a client;
+        // a later sign-in keeps the one already stored for that account.
+        const previous = (credentials[provider] ?? []).find(existing => existing.account === newCredential.account);
+        if (!newCredential.refreshToken && previous?.refreshToken) {
+            newCredential.refreshToken = previous.refreshToken;
+        }
+        credentials[provider] = [...kept, newCredential];
         await this.saveCredentials(credentials);
     }
     /**
-     * Update stored credentials directly (used for token refresh)
+     * Replace the stored entry that `previous` was read from (used for token
+     * refresh), matched on its account, else its refresh token.
      */
-    async updateStoredCredentials(provider, updatedCredentials) {
+    async updateStoredCredentials(provider, previous, updatedCredentials) {
         const credentials = await this.loadCredentials();
-        if (!credentials[provider] || credentials[provider].length === 0) {
-            credentials[provider] = [updatedCredentials];
-        }
-        else {
-            credentials[provider][0] = updatedCredentials;
-        }
+        const entries = credentials[provider] ?? [];
+        const index = entries.findIndex(entry => previous.account
+            ? entry.account === previous.account
+            : entry.refreshToken === previous.refreshToken);
+        if (index === -1)
+            entries.push(updatedCredentials);
+        else
+            entries[index] = updatedCredentials;
+        credentials[provider] = entries;
         await this.saveCredentials(credentials);
     }
     /**
-     * Retrieve stored credentials for a provider (returns most recent credential)
+     * Retrieve stored credentials for a provider: the given account's, or the
+     * most recent sign-in.
      */
-    async getCredentials(provider) {
+    async getCredentials(provider, { account } = {}) {
         const credentials = await this.loadCredentials();
-        const providerCredentials = credentials[provider];
-        return providerCredentials && providerCredentials.length > 0
-            ? (providerCredentials.at(-1) ?? null)
-            : null;
+        const providerCredentials = credentials[provider] ?? [];
+        if (account) {
+            const wanted = account.toLowerCase();
+            return providerCredentials.find(entry => entry.account?.toLowerCase() === wanted) ?? null;
+        }
+        return providerCredentials.at(-1) ?? null;
     }
     /**
      * Retrieve all stored credentials for a provider
@@ -140,13 +153,13 @@ export class FileCredentialManager {
     /**
      * Get valid access token, checking expiration
      */
-    async getValidToken(provider) {
-        const credentials = await this.getCredentials(provider);
+    async getValidToken(provider, options = {}) {
+        const credentials = await this.getCredentials(provider, options);
         if (!credentials) {
             return null;
         }
-        // If token is not expired, return it
-        if (!this.isTokenExpired(credentials)) {
+        // If token is not expired, return it, unless the caller saw it refused.
+        if (!options.refresh && !this.isTokenExpired(credentials)) {
             return credentials.accessToken;
         }
         // Token is expired - try to refresh if we have refresh token and client secret
@@ -158,7 +171,9 @@ export class FileCredentialManager {
                 }
             }
             catch (error) {
-                console.warn(`Failed to refresh ${provider} token:`, error instanceof Error ? error.message : error);
+                logger.warn(`Failed to refresh the ${provider} token`, {
+                    error: error instanceof Error ? error.message : String(error),
+                });
             }
         }
         return null;
@@ -170,7 +185,7 @@ export class FileCredentialManager {
         if (!credentials.refreshToken || !credentials.clientId || !credentials.clientSecret) {
             return null;
         }
-        const refreshUrl = this.getRefreshUrl(provider);
+        const refreshUrl = credentials.tokenUrl ?? this.getRefreshUrl(provider);
         if (!refreshUrl) {
             return null;
         }
@@ -197,9 +212,10 @@ export class FileCredentialManager {
                 accessToken: tokenData.access_token,
                 refreshToken: tokenData.refresh_token || credentials.refreshToken,
                 expiresIn: tokenData.expires_in,
+                scope: tokenData.scope ?? credentials.scope,
                 createdAt: new Date().toISOString(),
             };
-            await this.updateStoredCredentials(provider, updatedCredentials);
+            await this.updateStoredCredentials(provider, credentials, updatedCredentials);
             return tokenData.access_token;
         }
         catch (error) {
@@ -207,7 +223,8 @@ export class FileCredentialManager {
         }
     }
     /**
-     * Get the token refresh URL for a specific provider
+     * The token refresh URL for credentials stored before the token URL was
+     * saved with them.
      */
     getRefreshUrl(provider) {
         const refreshUrls = {

package/dist/OAuthProvider.d.ts

@@ -1,4 +1,4 @@
-import { OAuthParams, TokenResponse, OAuthConfig } from './types.js';
+import { ClientCredentials, OAuthParams, OAuthConfig, ProviderSetupContext, TokenResponse } from './types.js';
 /**
  * Base OAuth2 authorization-code flow. A standard provider only declares the
  * endpoints, scopes, and credential style:
@@ -14,6 +14,10 @@ import { OAuthParams, TokenResponse, OAuthConfig } from './types.js';
  *
  * A provider whose protocol deviates from OAuth2 (e.g. Last.fm's signed
  * auth.getSession) overrides buildAuthUrl / exchangeCodeForToken instead.
+ *
+ * A provider whose people register their own OAuth client can walk them
+ * through it in `setup()`, which `chronicle auth login` runs when no client
+ * is given on the command line.
  */
 export declare abstract class OAuthProvider {
     static providerId: string;
@@ -29,9 +33,39 @@ export declare abstract class OAuthProvider {
     static tokenAuthStyle: 'basic-header' | 'body';
     /** Provider-specific additions to the authorization URL. */
     static extraAuthParams: Record<string, string>;
+    /** Send a PKCE challenge with the authorization and its verifier with the exchange. */
+    static pkce: boolean;
+    /**
+     * Scopes by a name a person can pass to `chronicle auth login --add`, for
+     * a provider whose sources each need their own (`gmail`, `calendar`).
+     * Every login also asks for `scopes`.
+     */
+    static scopeSets: Record<string, string[]>;
+    /** The sets a first login asks for when none are named. */
+    static defaultScopeSets: string[];
+    /** Printed under the sign-in summary: what to run next. */
+    static signedInHint?: string;
+    /**
+     * Find or make the OAuth client to sign in with, walking the person
+     * through whatever the provider's console needs. Run by `chronicle auth
+     * login` when no `--client-id` is given.
+     */
+    static setup?(context: ProviderSetupContext): Promise<ClientCredentials>;
     protected params: OAuthParams;
     constructor(params: OAuthParams);
     static getConfig(): OAuthConfig;
+    /** The scopes for the named sets, with the provider's own, without repeats. */
+    static scopesFor(sets: string[]): string[];
+    /** The named sets a granted scope string covers in full. */
+    static scopeSetsIn(granted: string | undefined): string[];
+    /** A PKCE verifier: 43 URL-safe characters. */
+    static createCodeVerifier(): string;
+    /**
+     * Which account signed in, from the token response, for a provider that
+     * says (an OpenID `id_token`). Several accounts of one provider are kept
+     * apart by it.
+     */
+    protected accountFrom(_response: any): string | undefined;
     private get providerClass();
     /**
      * Build the authorization URL where the user will be redirected
@@ -48,7 +82,7 @@ export declare abstract class OAuthProvider {
     /**
      * Generate a random state parameter for CSRF protection
      */
-    protected generateState(): string;
+    static generateState(): string;
     /**
      * Build query string from parameters
      */

package/dist/OAuthProvider.js

@@ -1,4 +1,6 @@
 import axios from 'axios';
+import { EXIT_CODES, ExtractorError } from '@chronicle.app/logging';
+import { createHash, randomBytes } from 'node:crypto';
 /**
  * Base OAuth2 authorization-code flow. A standard provider only declares the
  * endpoints, scopes, and credential style:
@@ -14,6 +16,10 @@ import axios from 'axios';
  *
  * A provider whose protocol deviates from OAuth2 (e.g. Last.fm's signed
  * auth.getSession) overrides buildAuthUrl / exchangeCodeForToken instead.
+ *
+ * A provider whose people register their own OAuth client can walk them
+ * through it in `setup()`, which `chronicle auth login` runs when no client
+ * is given on the command line.
  */
 export class OAuthProvider {
     static providerId;
@@ -29,6 +35,18 @@ export class OAuthProvider {
     static tokenAuthStyle = 'body';
     /** Provider-specific additions to the authorization URL. */
     static extraAuthParams = {};
+    /** Send a PKCE challenge with the authorization and its verifier with the exchange. */
+    static pkce = false;
+    /**
+     * Scopes by a name a person can pass to `chronicle auth login --add`, for
+     * a provider whose sources each need their own (`gmail`, `calendar`).
+     * Every login also asks for `scopes`.
+     */
+    static scopeSets = {};
+    /** The sets a first login asks for when none are named. */
+    static defaultScopeSets = [];
+    /** Printed under the sign-in summary: what to run next. */
+    static signedInHint;
     params;
     constructor(params) {
         this.params = params;
@@ -42,6 +60,38 @@ export class OAuthProvider {
             requiresClientSecret: this.requiresClientSecret,
         };
     }
+    /** The scopes for the named sets, with the provider's own, without repeats. */
+    static scopesFor(sets) {
+        const unknown = sets.filter(set => !this.scopeSets[set]);
+        if (unknown.length > 0) {
+            const known = Object.keys(this.scopeSets);
+            throw new ExtractorError(`Unknown access "${unknown[0]}" for ${this.providerId}`, {
+                code: 'unknown-scope-set',
+                exitCode: EXIT_CODES.usage,
+                hint: `Use ${known.length > 1 ? `${known.slice(0, -1).join(', ')}, or ${known.at(-1)}` : known[0]}.`,
+            });
+        }
+        return [...new Set([...this.scopes, ...sets.flatMap(set => this.scopeSets[set])])];
+    }
+    /** The named sets a granted scope string covers in full. */
+    static scopeSetsIn(granted) {
+        const have = new Set((granted ?? '').split(/\s+/).filter(Boolean));
+        return Object.entries(this.scopeSets)
+            .filter(([, scopes]) => scopes.every(scope => have.has(scope)))
+            .map(([set]) => set);
+    }
+    /** A PKCE verifier: 43 URL-safe characters. */
+    static createCodeVerifier() {
+        return randomBytes(32).toString('base64url');
+    }
+    /**
+     * Which account signed in, from the token response, for a provider that
+     * says (an OpenID `id_token`). Several accounts of one provider are kept
+     * apart by it.
+     */
+    accountFrom(_response) {
+        return undefined;
+    }
     get providerClass() {
         return this.constructor;
     }
@@ -60,6 +110,12 @@ export class OAuthProvider {
             params.scope = scope;
         }
         Object.assign(params, cls.extraAuthParams);
+        if (cls.pkce && this.params.codeVerifier) {
+            params.code_challenge = createHash('sha256')
+                .update(this.params.codeVerifier)
+                .digest('base64url');
+            params.code_challenge_method = 'S256';
+        }
         if (this.params.state) {
             params.state = this.params.state;
         }
@@ -76,6 +132,9 @@ export class OAuthProvider {
                 code,
                 redirect_uri: this.params.redirectUri,
             });
+            if (cls.pkce && this.params.codeVerifier) {
+                data.set('code_verifier', this.params.codeVerifier);
+            }
             const headers = {
                 'Content-Type': 'application/x-www-form-urlencoded',
             };
@@ -88,6 +147,7 @@ export class OAuthProvider {
                 data.set('client_secret', this.params.clientSecret);
             }
             const response = await this.postToken(cls.tokenUrl, data, { headers });
+            const account = this.accountFrom(response);
             return {
                 provider: cls.providerId,
                 access_token: response.access_token,
@@ -97,6 +157,8 @@ export class OAuthProvider {
                 expires_in: response.expires_in,
                 scope: response.scope,
                 created_at: new Date().toISOString(),
+                ...(account && { account }),
+                tokenUrl: cls.tokenUrl,
             };
         }
         catch (error) {
@@ -115,8 +177,8 @@ export class OAuthProvider {
     /**
      * Generate a random state parameter for CSRF protection
      */
-    generateState() {
-        return Math.random().toString(36).slice(2, 15) + Math.random().toString(36).slice(2, 15);
+    static generateState() {
+        return randomBytes(16).toString('base64url');
     }
     /**
      * Build query string from parameters

package/dist/OAuthServer.d.ts

@@ -8,7 +8,9 @@ export declare class OAuthServer {
     private failure?;
     private resolve?;
     private reject?;
+    private pending?;
     start(preferredPort?: number, timeoutMs?: number): Promise<number>;
+    /** The callback, however many callers wait for it: they share one promise. */
     waitForCallback(): Promise<AuthorizationResult>;
     stop(error?: Error): void;
     getCallbackUrl(): string;

package/dist/OAuthServer.js

@@ -8,11 +8,13 @@ export class OAuthServer {
     failure;
     resolve;
     reject;
+    pending;
     async start(preferredPort = 0, timeoutMs = 5 * 60 * 1000) {
         if (this.server)
             throw new Error('OAuth server already started');
         this.result = undefined;
         this.failure = undefined;
+        this.pending = undefined;
         const server = http.createServer((request, response) => {
             const url = new URL(request.url || '/', 'http://127.0.0.1');
             if (url.pathname !== '/callback') {
@@ -54,6 +56,7 @@ export class OAuthServer {
             throw error;
         }
     }
+    /** The callback, however many callers wait for it: they share one promise. */
     async waitForCallback() {
         if (this.result)
             return this.result;
@@ -61,10 +64,11 @@ export class OAuthServer {
             throw this.failure;
         if (!this.server)
             throw new Error('Server not started');
-        return new Promise((resolve, reject) => {
+        this.pending ??= new Promise((resolve, reject) => {
             this.resolve = resolve;
             this.reject = reject;
         });
+        return this.pending;
     }
     stop(error = new Error('OAuth authorization cancelled')) {
         if (this.timeout)
@@ -76,6 +80,7 @@ export class OAuthServer {
         }
         this.resolve = undefined;
         this.reject = undefined;
+        this.pending = undefined;
         this.server?.closeAllConnections();
         this.server?.close();
         this.server = undefined;

package/dist/TokenHelper.d.ts

@@ -1,8 +1,13 @@
 export declare const TokenHelper: {
     /**
-     * Get a valid access token for a provider, with user-friendly error messages
+     * A valid access token for a provider, with user-friendly error messages.
+     * `refresh` gets a new one even when the stored one looks current: the
+     * source refused it.
      */
-    getValidToken(provider: string): Promise<string>;
+    getValidToken(provider: string, { account, refresh }?: {
+        account?: string;
+        refresh?: boolean;
+    }): Promise<string>;
     /**
      * Get token or use provided access token, with preference for keychain
      */
@@ -10,7 +15,9 @@ export declare const TokenHelper: {
     /**
      * Check if valid credentials exist for a provider
      */
-    hasValidCredentials(provider: string): Promise<boolean>;
+    hasValidCredentials(provider: string, options?: {
+        account?: string;
+    }): Promise<boolean>;
     /**
      * Remove stored credentials (for logout/reset)
      */

package/dist/TokenHelper.js

@@ -1,20 +1,35 @@
+import { AuthRequired } from '@chronicle.app/logging';
 import { CredentialManager } from './CredentialManager.js';
+import { OAuthProviderRegistry } from './ProviderRegistry.js';
 export const TokenHelper = {
     /**
-     * Get a valid access token for a provider, with user-friendly error messages
+     * A valid access token for a provider, with user-friendly error messages.
+     * `refresh` gets a new one even when the stored one looks current: the
+     * source refused it.
      */
-    async getValidToken(provider) {
-        const token = await CredentialManager.getValidToken(provider);
+    async getValidToken(provider, { account, refresh } = {}) {
+        const token = await CredentialManager.getValidToken(provider, { account, refresh });
         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`);
+            const stored = await CredentialManager.getCredentials(provider, { account });
+            // A client stored from an earlier sign-in is reused, and a provider
+            // with guided setup makes one, so the command needs no client flags then.
+            const login = stored?.clientId || OAuthProviderRegistry.get(provider)?.setup
+                ? `chronicle auth login ${provider}`
+                : `chronicle auth login ${provider} --client-id <id> --client-secret <secret>`;
+            if (stored) {
+                throw new AuthRequired(`${provider} credentials expired and couldn't be refreshed`, {
+                    hint: `Run \`${login}\` to sign in again.`,
+                });
             }
-            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`);
+            if (account && (await CredentialManager.hasCredentials(provider))) {
+                throw new AuthRequired(`No ${provider} credentials for that account`, {
+                    hint: `Run \`chronicle auth login ${provider}\` and sign in with that account.`,
+                    fields: { account },
+                });
             }
+            throw new AuthRequired(`No ${provider} credentials`, {
+                hint: `Run \`${login}\` to sign in.`,
+            });
         }
         return token;
     },
@@ -32,9 +47,9 @@ export const TokenHelper = {
     /**
      * Check if valid credentials exist for a provider
      */
-    async hasValidCredentials(provider) {
+    async hasValidCredentials(provider, options = {}) {
         try {
-            const token = await CredentialManager.getValidToken(provider);
+            const token = await CredentialManager.getValidToken(provider, options);
             return token !== null;
         }
         catch {

package/dist/resolveCredentials.d.ts

@@ -24,6 +24,12 @@ export interface ResolveCredentialsOptions {
      * exact user-facing message (auth command, credential-creation URL, …).
      */
     errorMessage?: string;
+    /**
+     * The next step printed under the error. Defaults to `chronicle auth set`,
+     * which stores the static secrets this path reads; an OAuth source whose
+     * token comes from `chronicle auth login` says so here.
+     */
+    hint?: 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>;

package/dist/resolveCredentials.js

@@ -1,3 +1,4 @@
+import { AuthRequired } from '@chronicle.app/logging';
 import { CredentialManager } from './CredentialManager.js';
 /** Pure resolution core, separated for testing. */
 export function pickCredentialFields(provider, stored, fields, options = {}) {
@@ -22,8 +23,7 @@ export function pickCredentialFields(provider, stored, fields, options = {}) {
             missing.push(name);
     }
     if (missing.length > 0) {
-        throw new Error(options.errorMessage ??
-            `${provider} credentials are missing ${missing.join(', ')}. Authenticate with: chronicle auth ${provider}`);
+        throw new AuthRequired(options.errorMessage ?? `${provider} credentials are missing ${missing.join(', ')}`, { hint: options.hint ?? `Run \`chronicle auth set ${provider}\` to store a token.` });
     }
     return resolved;
 }

package/dist/types.d.ts

@@ -1,9 +1,12 @@
+import type { Logger } from '@chronicle.app/logging';
 export interface OAuthParams {
     clientId: string;
     clientSecret: string;
     redirectUri: string;
     scopes?: string[];
     state?: string;
+    /** PKCE verifier, when the provider uses PKCE; its challenge goes in the auth URL. */
+    codeVerifier?: string;
 }
 export interface TokenResponse {
     provider: string;
@@ -14,6 +17,10 @@ export interface TokenResponse {
     scope?: string;
     created_at: string;
     username?: string;
+    /** Which of the provider's accounts signed in (an email), when it says. */
+    account?: string;
+    /** Where the refresh token is exchanged, saved so refresh needs no provider table. */
+    tokenUrl?: string;
 }
 export interface OAuthConfig {
     providerId: string;
@@ -29,4 +36,34 @@ export interface AuthorizationResult {
     error?: string;
     error_description?: string;
 }
+/** An OAuth client a person registered with the provider. */
+export interface ClientCredentials {
+    clientId: string;
+    clientSecret?: string;
+}
+/**
+ * What the CLI hands a provider's `setup()`: ways to talk to the person
+ * without the provider depending on the CLI.
+ */
+export interface ProviderSetupContext {
+    /** The command's logger; hints and notices go through it. */
+    logger: Logger;
+    /** Chronicle's config directory, for state the setup keeps between runs. */
+    configDir: string;
+    /** Named scope sets this login asks for (`--add`), so setup can enable their APIs. */
+    scopeSets: string[];
+    /** Whether a person is at a terminal to answer. */
+    interactive: boolean;
+    /** Start over instead of reusing what a previous setup made. */
+    fresh: boolean;
+    /** Open a page in the browser; with `--no-browser` it only prints the URL. */
+    openUrl(url: string): Promise<void>;
+    /**
+     * Ask the person something and return what they typed (empty for just
+     * Enter). Aborting `signal` withdraws the question.
+     */
+    ask(prompt: string, signal?: AbortSignal): Promise<string>;
+    /** Cancelled with Ctrl-C. */
+    signal: AbortSignal;
+}
 //# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chronicle.app/auth",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
@@ -19,7 +19,7 @@
   "type": "module",
   "description": "Standalone Chronicle credential and OAuth services",
   "devDependencies": {
-    "@chronicle.app/tsconfig": "0.3.0",
+    "@chronicle.app/tsconfig": "0.4.0",
     "@types/node": "^22.10.1",
     "typescript": "^5.7.2"
   },
@@ -37,6 +37,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
+    "@chronicle.app/logging": "0.4.0",
     "axios": "^1.7.9"
   },
   "engines": {