quickbase-js 2.4.0 → 2.4.1

package/src/auth/ticket.ts

@@ -0,0 +1,329 @@
+/**
+ * Ticket Authentication Strategy (XML API)
+ *
+ * Authenticates using username/password via the XML API_Authenticate endpoint.
+ * Unlike user tokens, tickets properly attribute record changes (createdBy/modifiedBy)
+ * to the authenticated user.
+ *
+ * NOTE: This uses the legacy QuickBase XML API (API_Authenticate).
+ * If QuickBase discontinues the XML API in the future, this file and related code
+ * can be safely removed.
+ *
+ * To find all related code, search for the marker: XML-API-TICKET
+ *
+ * Files to remove/update:
+ *   - src/auth/ticket.ts (this file)
+ *   - src/auth/index.ts (TicketStrategy export, createAuthStrategy case)
+ *   - src/core/types.ts (TicketAuthConfig)
+ *   - src/index.ts (exports)
+ *   - tests/auth/ticket.test.ts
+ *   - README.md: "Ticket Auth" section
+ */
+
+import type { AuthStrategy, AuthContext } from './types.js';
+import type { Logger } from '../core/logger.js';
+
+interface AuthenticateResponse {
+  ticket: string;
+  userid: string;
+  errcode: number;
+  errtext: string;
+  errdetail?: string;
+}
+
+/**
+ * Options for ticket authentication
+ */
+export interface TicketAuthOptions {
+  /** Ticket validity in hours (default: 12, max: 4380 ~6 months) */
+  hours?: number;
+  /** Callback invoked when ticket expires - use to show login UI */
+  onExpired?: () => void;
+  /** Persist ticket to storage for session survival (default: none) */
+  persist?: 'sessionStorage' | 'localStorage';
+}
+
+/** Data structure stored in persistent storage */
+interface PersistedTicketData {
+  ticket: string;
+  userId: string;
+  expiresAt: number;
+}
+
+/**
+ * Ticket authentication strategy using XML API_Authenticate.
+ *
+ * @example
+ * ```typescript
+ * const client = createClient({
+ *   realm: 'mycompany',
+ *   auth: {
+ *     type: 'ticket',
+ *     username: 'user@example.com',
+ *     password: 'password',
+ *   },
+ * });
+ * ```
+ *
+ * XML-API-TICKET: Remove this class if XML API is discontinued.
+ */
+export class TicketStrategy implements AuthStrategy {
+  private readonly username: string;
+  private password: string | null; // Cleared after first auth
+  private readonly hours: number;
+  private readonly realm: string;
+  private readonly fetchApi: typeof fetch;
+  private readonly logger: Logger;
+  private readonly onExpired?: () => void;
+  private readonly persist?: 'sessionStorage' | 'localStorage';
+  private readonly storageKey: string;
+
+  private ticket: string | null = null;
+  private userId: string | null = null;
+  private expiresAt: number | null = null;
+  private authenticated = false;
+  private pendingAuth: Promise<string> | null = null;
+
+  constructor(
+    username: string,
+    password: string,
+    options: TicketAuthOptions | undefined,
+    context: AuthContext
+  ) {
+    this.username = username;
+    this.password = password;
+    this.hours = Math.min(Math.max(options?.hours ?? 12, 1), 4380);
+    this.onExpired = options?.onExpired;
+    this.persist = options?.persist;
+    this.realm = context.realm;
+    this.fetchApi = context.fetchApi;
+    this.logger = context.logger;
+    this.storageKey = `qb_ticket_${this.realm}`;
+
+    // Try to restore ticket from storage
+    this.restoreFromStorage();
+  }
+
+  async getToken(_dbid?: string): Promise<string> {
+    // Return cached ticket if available and not expired
+    if (this.ticket && this.expiresAt && Date.now() < this.expiresAt) {
+      return this.ticket;
+    }
+
+    // If ticket existed but expired, clear it
+    if (this.ticket && this.expiresAt && Date.now() >= this.expiresAt) {
+      this.clearTicket();
+      this.onExpired?.();
+      throw new Error('Ticket expired; create a new client with fresh credentials');
+    }
+
+    // If already authenticated but no ticket, it expired
+    if (this.authenticated) {
+      this.onExpired?.();
+      throw new Error('Ticket expired; create a new client with fresh credentials');
+    }
+
+    // Dedupe concurrent auth requests
+    if (this.pendingAuth) {
+      return this.pendingAuth;
+    }
+
+    this.pendingAuth = this.authenticate();
+    try {
+      const ticket = await this.pendingAuth;
+      return ticket;
+    } finally {
+      this.pendingAuth = null;
+    }
+  }
+
+  getAuthorizationHeader(token: string): string {
+    return `QB-TICKET ${token}`;
+  }
+
+  async handleAuthError(_dbid?: string): Promise<boolean> {
+    // Clear expired ticket
+    this.clearTicket();
+
+    // Can't refresh - password was cleared after initial auth
+    this.logger.debug('Ticket auth error - cannot refresh (password was cleared)');
+    this.onExpired?.();
+    return false;
+  }
+
+  invalidate(_dbid?: string): void {
+    this.clearTicket();
+  }
+
+  private clearTicket(): void {
+    this.ticket = null;
+    this.expiresAt = null;
+    this.clearFromStorage();
+  }
+
+  /**
+   * Get the authenticated user's ID (available after first API call)
+   */
+  getUserId(): string | null {
+    return this.userId;
+  }
+
+  private async authenticate(): Promise<string> {
+    if (!this.password) {
+      this.onExpired?.();
+      throw new Error(
+        'No password to sign in with (the ticket expired, or sign-in failed); create a new client with fresh credentials'
+      );
+    }
+
+    const url = `https://${this.realm}.quickbase.com/db/main`;
+
+    // Build XML request body
+    const xmlBody = `<qdbapi>
+    <username>${this.escapeXml(this.username)}</username>
+    <password>${this.escapeXml(this.password)}</password>
+    <hours>${this.hours}</hours>
+</qdbapi>`;
+
+    // Drop the password now, whether sign-in succeeds or fails: it is only
+    // needed for this one request.
+    this.password = null;
+
+    this.logger.debug(`Authenticating via API_Authenticate for ${this.username}`);
+
+    const response = await this.fetchApi(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/xml',
+        'QUICKBASE-ACTION': 'API_Authenticate',
+      },
+      body: xmlBody,
+    });
+
+    const xmlText = await response.text();
+    const result = this.parseXmlResponse(xmlText);
+
+    if (result.errcode !== 0) {
+      const errMsg = result.errdetail || result.errtext || 'Unknown error';
+      throw new Error(`Authentication failed: ${errMsg} (code: ${result.errcode})`);
+    }
+
+    if (!result.ticket) {
+      throw new Error('No ticket returned from API_Authenticate');
+    }
+
+    // Store ticket and user ID
+    this.ticket = result.ticket;
+    this.userId = result.userid;
+    this.expiresAt = Date.now() + this.hours * 60 * 60 * 1000;
+    this.authenticated = true;
+
+    // Save to storage if persistence is enabled
+    this.saveToStorage();
+
+    this.logger.debug(`Authenticated successfully, userId: ${this.userId}`);
+
+    return this.ticket;
+  }
+
+  private parseXmlResponse(xml: string): AuthenticateResponse {
+    // Simple XML parsing for the specific response format
+    const getTagContent = (tag: string): string => {
+      const match = xml.match(new RegExp(`<${tag}>([^<]*)</${tag}>`));
+      return match?.[1] ?? '';
+    };
+
+    return {
+      ticket: getTagContent('ticket'),
+      userid: getTagContent('userid'),
+      errcode: parseInt(getTagContent('errcode'), 10) || 0,
+      errtext: getTagContent('errtext'),
+      errdetail: getTagContent('errdetail') || undefined,
+    };
+  }
+
+  private escapeXml(str: string): string {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+
+  private getStorage(): { getItem(key: string): string | null; setItem(key: string, value: string): void; removeItem(key: string): void } | null {
+    if (!this.persist) return null;
+    try {
+      // Check if we're in a browser environment
+      if (typeof globalThis === 'undefined') return null;
+      type StorageLike = { getItem(key: string): string | null; setItem(key: string, value: string): void; removeItem(key: string): void };
+      const win = globalThis as { localStorage?: StorageLike; sessionStorage?: StorageLike };
+      const storage = this.persist === 'localStorage' ? win.localStorage : win.sessionStorage;
+      return storage ?? null;
+    } catch {
+      // Storage may be disabled (e.g., private browsing)
+      return null;
+    }
+  }
+
+  private saveToStorage(): void {
+    const storage = this.getStorage();
+    if (!storage || !this.ticket || !this.userId || !this.expiresAt) return;
+
+    try {
+      const data: PersistedTicketData = {
+        ticket: this.ticket,
+        userId: this.userId,
+        expiresAt: this.expiresAt,
+      };
+      storage.setItem(this.storageKey, JSON.stringify(data));
+      this.logger.debug(`Ticket saved to ${this.persist}`);
+    } catch {
+      // Storage quota exceeded or other error - ignore
+      this.logger.debug(`Failed to save ticket to ${this.persist}`);
+    }
+  }
+
+  private restoreFromStorage(): void {
+    const storage = this.getStorage();
+    if (!storage) return;
+
+    try {
+      const json = storage.getItem(this.storageKey);
+      if (!json) return;
+
+      const data: PersistedTicketData = JSON.parse(json);
+
+      // Check if ticket is still valid (with 1 minute buffer)
+      if (Date.now() >= data.expiresAt - 60000) {
+        storage.removeItem(this.storageKey);
+        this.logger.debug('Stored ticket expired, removed from storage');
+        return;
+      }
+
+      this.ticket = data.ticket;
+      this.userId = data.userId;
+      this.expiresAt = data.expiresAt;
+      this.authenticated = true;
+      // Password stays null since we have a valid ticket
+      this.password = null;
+
+      this.logger.debug(`Ticket restored from ${this.persist}`);
+    } catch {
+      // Invalid JSON or other error - clear storage
+      storage.removeItem(this.storageKey);
+    }
+  }
+
+  private clearFromStorage(): void {
+    const storage = this.getStorage();
+    if (!storage) return;
+
+    try {
+      storage.removeItem(this.storageKey);
+      this.logger.debug(`Ticket cleared from ${this.persist}`);
+    } catch {
+      // Ignore errors
+    }
+  }
+}

package/src/auth/token-cache.ts

@@ -0,0 +1,97 @@
+/**
+ * Token cache with TTL support
+ *
+ * Manages cached temporary tokens with expiration handling.
+ * Tokens are stored per-dbid since QuickBase temp tokens are database-specific.
+ */
+
+import type { CachedToken } from './types.js';
+
+export class TokenCache {
+  private readonly cache = new Map<string, CachedToken>();
+  private readonly defaultLifespanMs: number;
+
+  constructor(defaultLifespanMs: number) {
+    this.defaultLifespanMs = defaultLifespanMs;
+  }
+
+  /**
+   * Get a cached token if it exists and is not expired
+   */
+  get(dbid: string): string | null {
+    const entry = this.cache.get(dbid);
+    if (!entry) {
+      return null;
+    }
+
+    // Check if token is expired (with 10 second buffer)
+    if (Date.now() >= entry.expiresAt - 10000) {
+      this.cache.delete(dbid);
+      return null;
+    }
+
+    return entry.token;
+  }
+
+  /**
+   * Store a token with optional custom lifespan
+   */
+  set(dbid: string, token: string, lifespanMs?: number): void {
+    const expiresAt = Date.now() + (lifespanMs ?? this.defaultLifespanMs);
+    this.cache.set(dbid, { token, expiresAt });
+  }
+
+  /**
+   * Remove a specific token from cache
+   */
+  delete(dbid: string): boolean {
+    return this.cache.delete(dbid);
+  }
+
+  /**
+   * Clear all cached tokens
+   */
+  clear(): void {
+    this.cache.clear();
+  }
+
+  /**
+   * Check if a token exists and is valid
+   */
+  has(dbid: string): boolean {
+    return this.get(dbid) !== null;
+  }
+
+  /**
+   * Get time until token expires (in ms), or null if not cached
+   */
+  getTimeToExpiry(dbid: string): number | null {
+    const entry = this.cache.get(dbid);
+    if (!entry) {
+      return null;
+    }
+    const ttl = entry.expiresAt - Date.now();
+    return ttl > 0 ? ttl : null;
+  }
+
+  /**
+   * Get the number of cached tokens
+   */
+  get size(): number {
+    // Clean up expired entries first
+    this.cleanup();
+    return this.cache.size;
+  }
+
+  /**
+   * Remove expired entries from cache
+   */
+  private cleanup(): void {
+    const now = Date.now();
+    for (const [dbid, entry] of this.cache) {
+      if (now >= entry.expiresAt) {
+        this.cache.delete(dbid);
+      }
+    }
+  }
+}

package/src/auth/types.ts

@@ -0,0 +1,50 @@
+/**
+ * Authentication strategy types
+ */
+
+import type { Logger } from '../core/logger.js';
+
+/**
+ * Interface that all auth strategies must implement
+ */
+export interface AuthStrategy {
+  /**
+   * Get a valid token for the given database ID
+   * @param dbid - The database ID (required for temp tokens)
+   */
+  getToken(dbid?: string): Promise<string>;
+
+  /**
+   * Get the authorization header value
+   */
+  getAuthorizationHeader(token: string): string;
+
+  /**
+   * Handle authentication errors (e.g., refresh token on 401)
+   * @returns true if token was refreshed and request should be retried
+   */
+  handleAuthError(dbid?: string): Promise<boolean>;
+
+  /**
+   * Invalidate cached tokens (if applicable)
+   */
+  invalidate(dbid?: string): void;
+}
+
+/**
+ * Context passed to auth strategy constructors
+ */
+export interface AuthContext {
+  realm: string;
+  baseUrl: string;
+  fetchApi: typeof fetch;
+  logger: Logger;
+}
+
+/**
+ * Token cache entry
+ */
+export interface CachedToken {
+  token: string;
+  expiresAt: number;
+}

package/src/auth/user-token.ts

@@ -0,0 +1,38 @@
+/**
+ * User Token Authentication Strategy
+ *
+ * Simplest auth method - uses a persistent user token directly.
+ * Token is passed in the Authorization header as "QB-USER-TOKEN {token}"
+ */
+
+import type { AuthStrategy, AuthContext } from './types.js';
+import type { Logger } from '../core/logger.js';
+
+export class UserTokenStrategy implements AuthStrategy {
+  private readonly userToken: string;
+  private readonly logger: Logger;
+
+  constructor(userToken: string, context: AuthContext) {
+    this.userToken = userToken;
+    this.logger = context.logger;
+  }
+
+  async getToken(_dbid?: string): Promise<string> {
+    // User tokens don't change, just return the configured token
+    return this.userToken;
+  }
+
+  getAuthorizationHeader(token: string): string {
+    return `QB-USER-TOKEN ${token}`;
+  }
+
+  async handleAuthError(_dbid?: string): Promise<boolean> {
+    // User tokens can't be refreshed - if auth fails, it's a permanent failure
+    this.logger.debug('Auth error with user token - cannot refresh');
+    return false;
+  }
+
+  invalidate(_dbid?: string): void {
+    // No-op for user tokens - they don't have cached state
+  }
+}