@open-vibe-lab/open-sub-auth 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,328 @@
+//#region src/types.d.ts
+/** OAuth token set returned after successful authentication */
+interface TokenSet {
+  accessToken: string;
+  refreshToken: string | null;
+  /** Unix timestamp in milliseconds when the access token expires */
+  expiresAt: number;
+  /** JWT id_token (present for OpenAI, contains email/plan info) */
+  idToken?: string;
+  tokenType: "bearer" | "api-key";
+  scopes?: string[];
+  /** Raw response from the token endpoint for extensibility */
+  raw?: Record<string, unknown>;
+}
+/** Configuration for an OAuth provider */
+interface ProviderConfig {
+  /** Unique identifier: "claude", "openai-codex", "github-copilot" */
+  name: string;
+  /** Human-readable display name */
+  displayName: string;
+  /** Authorization endpoint URL (for PKCE flow) */
+  authorizationEndpoint?: string;
+  /** Token exchange endpoint URL */
+  tokenEndpoint: string;
+  /** OAuth client ID */
+  clientId: string;
+  /** Redirect URI for callback (for PKCE flow) */
+  redirectUri?: string;
+  /** OAuth scopes to request */
+  scopes?: string[];
+  /** Device code endpoint URL (for device code flow) */
+  deviceCodeEndpoint?: string;
+  /** OAuth grant type */
+  grantType: "authorization_code" | "device_code";
+  /** Token exchange request body format (default: "form") */
+  tokenBodyFormat?: "form" | "json";
+  /** Use PKCE verifier as state parameter (non-standard, required by some providers) */
+  stateIsVerifier?: boolean;
+}
+/** Provider interface that all providers must implement */
+interface Provider {
+  readonly config: ProviderConfig;
+  /** Run the full interactive login flow */
+  login(options?: LoginOptions): Promise<TokenSet>;
+  /** Refresh an expired access token */
+  refresh(refreshToken: string): Promise<TokenSet>;
+  /** Build auth headers for making API calls */
+  getAuthHeaders(accessToken: string): AuthHeaders;
+  /** Extract a stable account identifier from tokens */
+  getAccountId(tokenSet: TokenSet): string;
+  /** Optional: human-readable account label (e.g., email) */
+  getAccountLabel?(tokenSet: TokenSet): string | undefined;
+}
+/** Options for the login flow */
+interface LoginOptions {
+  /** Override port for the local callback server */
+  port?: number;
+  /** Timeout in ms for the entire login flow (default: 120000) */
+  timeout?: number;
+  /** Use manual code input mode instead of local callback server */
+  manual?: boolean;
+  /** Callback when the browser should be opened */
+  onOpenBrowser?: (url: string) => void;
+  /** Callback for device code flow: display code to user */
+  onDeviceCode?: (code: DeviceCodeInfo) => void;
+}
+/** Device code information displayed to the user */
+interface DeviceCodeInfo {
+  userCode: string;
+  verificationUri: string;
+  expiresIn: number;
+  interval: number;
+}
+/** HTTP headers for authenticated API calls */
+type AuthHeaders = Record<string, string>;
+/** Stored credential with metadata */
+interface StoredCredential {
+  tokenSet: TokenSet;
+  metadata: TokenMetadata;
+}
+/** Metadata about a stored credential */
+interface TokenMetadata {
+  provider: string;
+  accountId: string;
+  accountLabel?: string;
+  createdAt: number;
+  lastRefreshedAt: number;
+}
+/** Token storage interface */
+interface TokenStore {
+  get(provider: string, accountId: string): Promise<StoredCredential | null>;
+  set(provider: string, accountId: string, credential: StoredCredential): Promise<void>;
+  delete(provider: string, accountId: string): Promise<void>;
+  list(provider?: string): Promise<StoredCredential[]>;
+}
+/** Status of a stored credential */
+interface CredentialStatus {
+  provider: string;
+  displayName: string;
+  accountId: string;
+  accountLabel?: string;
+  isExpired: boolean;
+  expiresAt: number;
+  hasRefreshToken: boolean;
+}
+/** PKCE parameters for OAuth flow */
+interface PKCEParams {
+  codeVerifier: string;
+  codeChallenge: string;
+}
+/** Result from the callback server or manual code input */
+interface AuthorizationResult {
+  code: string;
+  state: string;
+}
+//#endregion
+//#region src/errors.d.ts
+declare class OpenSubAuthError extends Error {
+  constructor(message: string);
+}
+declare class AuthenticationError extends OpenSubAuthError {
+  readonly provider?: string | undefined;
+  constructor(message: string, provider?: string | undefined);
+}
+declare class TokenExpiredError extends OpenSubAuthError {
+  readonly provider: string;
+  constructor(provider: string);
+}
+declare class TokenRefreshError extends OpenSubAuthError {
+  readonly provider: string;
+  readonly cause_: unknown;
+  constructor(provider: string, cause_: unknown);
+}
+declare class ProviderNotFoundError extends OpenSubAuthError {
+  readonly providerName: string;
+  constructor(providerName: string);
+}
+declare class NoCredentialError extends OpenSubAuthError {
+  readonly provider: string;
+  readonly accountId?: string | undefined;
+  constructor(provider: string, accountId?: string | undefined);
+}
+declare class OAuthCallbackError extends OpenSubAuthError {
+  constructor(message: string);
+}
+declare class OAuthTimeoutError extends OpenSubAuthError {
+  readonly timeoutMs: number;
+  constructor(timeoutMs: number);
+}
+declare class StateMismatchError extends OpenSubAuthError {
+  constructor();
+}
+//#endregion
+//#region src/token/manager.d.ts
+/** Central token lifecycle manager */
+declare class TokenManager {
+  private readonly store;
+  /** Per-provider+account mutex to prevent concurrent refreshes */
+  private readonly refreshLocks;
+  constructor(store: TokenStore);
+  /** Run the interactive login flow for a provider, store the tokens */
+  login(providerName: string, options?: LoginOptions): Promise<StoredCredential>;
+  /** Get a valid access token, refreshing if needed */
+  getToken(providerName: string, accountId?: string): Promise<string>;
+  /** Get authenticated headers for API calls */
+  getAuthHeaders(providerName: string, accountId?: string): Promise<AuthHeaders>;
+  /** Remove stored tokens for a provider */
+  logout(providerName: string, accountId?: string): Promise<void>;
+  /** Get status of all stored credentials */
+  status(): Promise<CredentialStatus[]>;
+  private isTokenValid;
+  private resolveCredential;
+  private refreshWithLock;
+  private doRefresh;
+}
+//#endregion
+//#region src/storage/file-store.d.ts
+/** Token store backed by an encrypted JSON file */
+declare class FileStore implements TokenStore {
+  private readonly filePath;
+  constructor(filePath?: string);
+  get(provider: string, accountId: string): Promise<StoredCredential | null>;
+  set(provider: string, accountId: string, credential: StoredCredential): Promise<void>;
+  delete(provider: string, accountId: string): Promise<void>;
+  list(provider?: string): Promise<StoredCredential[]>;
+  private deriveKey;
+  private encrypt;
+  private decrypt;
+  private readFile;
+  private writeFile;
+}
+//#endregion
+//#region src/storage/keychain-store.d.ts
+/** Token store backed by the OS keychain via cross-keychain */
+declare class KeychainStore implements TokenStore {
+  private keychain;
+  private getKeychain;
+  private makeKey;
+  get(provider: string, accountId: string): Promise<StoredCredential | null>;
+  set(provider: string, accountId: string, credential: StoredCredential): Promise<void>;
+  delete(provider: string, accountId: string): Promise<void>;
+  list(provider?: string): Promise<StoredCredential[]>;
+  private getIndex;
+  private setIndex;
+  private addToIndex;
+  private removeFromIndex;
+}
+//#endregion
+//#region src/storage/store.d.ts
+/**
+ * Create a token store, preferring the OS keychain with encrypted file fallback.
+ * @param preferKeychain - If true (default), try keychain first
+ */
+declare function createTokenStore(preferKeychain?: boolean): Promise<TokenStore>;
+//#endregion
+//#region src/providers/registry.d.ts
+/** Register a provider factory */
+declare function registerProvider(name: string, factory: () => Provider): void;
+/** Get a provider instance by name */
+declare function getProvider(name: string): Provider;
+/** List all registered provider names */
+declare function listProviders(): string[];
+//#endregion
+//#region src/providers/claude.d.ts
+declare class ClaudeProvider implements Provider {
+  readonly config: ProviderConfig;
+  login(options?: LoginOptions): Promise<TokenSet>;
+  refresh(refreshToken: string): Promise<TokenSet>;
+  getAuthHeaders(accessToken: string): AuthHeaders;
+  getAccountId(tokenSet: TokenSet): string;
+  getAccountLabel(_tokenSet: TokenSet): string | undefined;
+}
+//#endregion
+//#region src/providers/openai-codex.d.ts
+declare class OpenAICodexProvider implements Provider {
+  readonly config: ProviderConfig;
+  login(options?: LoginOptions): Promise<TokenSet>;
+  refresh(refreshToken: string): Promise<TokenSet>;
+  getAuthHeaders(accessToken: string): AuthHeaders;
+  getAccountId(tokenSet: TokenSet): string;
+  getAccountLabel(tokenSet: TokenSet): string | undefined;
+}
+/**
+ * Import tokens from an existing Codex CLI installation.
+ * Reads from ~/.codex/auth.json or $CODEX_HOME/auth.json.
+ */
+declare function importFromCodexCli(): TokenSet | null;
+//#endregion
+//#region src/core/crypto.d.ts
+/** Generate a cryptographically random PKCE code verifier (43-128 chars, base64url) */
+declare function generateCodeVerifier(): string;
+/** Generate a PKCE code challenge from a verifier using S256 method */
+declare function generateCodeChallenge(verifier: string): string;
+/** Generate both PKCE code verifier and challenge */
+declare function generatePKCE(): PKCEParams;
+/** Generate a random state parameter for CSRF protection */
+declare function generateState(): string;
+//#endregion
+//#region src/core/oauth-pkce.d.ts
+/** Build the full OAuth authorization URL with PKCE and state params */
+declare function buildAuthorizationUrl(config: ProviderConfig, codeChallenge: string, state: string, redirectUri: string): string;
+/** Exchange an authorization code for tokens */
+declare function exchangeCode(config: ProviderConfig, code: string, codeVerifier: string, redirectUri: string, state?: string): Promise<TokenSet>;
+/** Refresh an access token using a refresh token */
+declare function refreshAccessToken(config: ProviderConfig, refreshToken: string): Promise<TokenSet>;
+interface PKCEFlowOptions {
+  config: ProviderConfig;
+  loginOptions?: LoginOptions;
+  /**
+   * Manual mode redirect URI (used when manual=true).
+   * If not provided, manual mode is not available.
+   */
+  manualRedirectUri?: string;
+}
+/** Execute the full PKCE flow: generate params, open browser, wait for callback, exchange code */
+declare function executePKCEFlow(options: PKCEFlowOptions): Promise<TokenSet>;
+//#endregion
+//#region src/core/callback-server.d.ts
+interface CallbackServerOptions {
+  /** Port to listen on (0 = random available port) */
+  port?: number;
+  /** Expected state parameter for CSRF validation */
+  expectedState: string;
+  /** Timeout in milliseconds (default: 120000) */
+  timeout?: number;
+  /** Path to listen on (default: "/callback") */
+  path?: string;
+}
+/** Start a local HTTP server to receive the OAuth callback redirect */
+declare function startCallbackServer(options: CallbackServerOptions): Promise<{
+  result: Promise<AuthorizationResult>;
+  port: number;
+  close: () => void;
+}>;
+//#endregion
+//#region src/core/manual-code-input.d.ts
+/**
+ * Parse a "code#state" string (Anthropic's manual paste format).
+ * Also supports a plain authorization code (state validated separately).
+ */
+declare function parseCodeAndState(input: string, expectedState: string): AuthorizationResult;
+/** Prompt the user to paste the authorization code from their browser */
+declare function promptForCode(expectedState: string): Promise<AuthorizationResult>;
+//#endregion
+//#region src/core/browser.d.ts
+/** Open a URL in the user's default browser. Does not throw on failure. */
+declare function openBrowser(url: string): void;
+//#endregion
+//#region src/token/jwt.d.ts
+/** Decoded JWT claims (no signature verification) */
+interface JWTClaims {
+  sub?: string;
+  email?: string;
+  name?: string;
+  iss?: string;
+  aud?: string | string[];
+  exp?: number;
+  iat?: number;
+  [key: string]: unknown;
+}
+/**
+ * Decode a JWT token's payload without verifying the signature.
+ * Used to extract user info from id_tokens (e.g., OpenAI).
+ */
+declare function decodeJWT(token: string): JWTClaims;
+//#endregion
+export { type AuthHeaders, AuthenticationError, type AuthorizationResult, ClaudeProvider, type CredentialStatus, type DeviceCodeInfo, FileStore, KeychainStore, type LoginOptions, NoCredentialError, OAuthCallbackError, OAuthTimeoutError, OpenAICodexProvider, OpenSubAuthError, type PKCEParams, type Provider, type ProviderConfig, ProviderNotFoundError, StateMismatchError, type StoredCredential, TokenExpiredError, TokenManager, type TokenMetadata, TokenRefreshError, type TokenSet, type TokenStore, buildAuthorizationUrl, createTokenStore, decodeJWT, exchangeCode, executePKCEFlow, generateCodeChallenge, generateCodeVerifier, generatePKCE, generateState, getProvider, importFromCodexCli, listProviders, openBrowser, parseCodeAndState, promptForCode, refreshAccessToken, registerProvider, startCallbackServer };
+//# sourceMappingURL=index.d.mts.map