feat: refresh PocketBase auth tokens automatically (#4)

Co-authored-by: Joshua Higgins <joshuafhiggins@gmail.com>
2026-10-22 18:58:48 -04:00
1 parent db4af0ef6a
commit 4dfb830f7a
@@ -5,12 +5,47 @@ import {
  PermissionResponse,
 } from '../types';

+export type AuthCollection = 'users' | '_superusers';
+
+export type ApiError = Error & {
+  status?: number;
+  isAuthError?: boolean;
+};
+
+export type AuthUpdateListener = (auth: AuthResponse) => void | Promise<void>;
+export type AuthFailureListener = (error: unknown) => void | Promise<void>;
+
+const AUTH_ERROR_MESSAGE = /authorization token|invalid token|unauthorized|not authenticated/i;
+
+export function isAuthCollection(value: unknown): value is AuthCollection {
+  return value === 'users' || value === '_superusers';
+}
+
+export function isRevokedAuthError(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  const status = (error as { status?: unknown }).status;
+  return status === 401 || status === 403 || status === 404;
+}
+
+function isSessionChanged(error: unknown): boolean {
+  return (
+    typeof error === 'object' &&
+    error !== null &&
+    (error as { sessionChanged?: boolean }).sessionChanged === true
+  );
+}
+
 class UpSnapAPI {
  private token: string | null = null;
  private address: string | null = null;
  private canCreate: boolean | null = null;
+  private authCollection: AuthCollection | null = null;
+  private authEpoch = 0;
  private unauthorizedHandler: (() => Promise<void>) | null = null;
+  private authUpdateListener: AuthUpdateListener | null = null;
+  private authFailureListener: AuthFailureListener | null = null;
  private isHandlingUnauthorized = false;
+  private refreshInFlight: Promise<AuthResponse> | null = null;

  setToken(token: string) {
    this.token = token;
@@ -22,6 +57,7 @@ class UpSnapAPI {

  clearToken() {
    this.token = null;
+    this.authEpoch += 1;
  }

  setAddress(address: string) {
@@ -48,10 +84,30 @@ class UpSnapAPI {
    this.canCreate = null;
  }

+  setAuthCollection(collection: AuthCollection | null) {
+    this.authCollection = collection;
+  }
+
+  getAuthCollection(): AuthCollection | null {
+    return this.authCollection;
+  }
+
+  clearAuthCollection() {
+    this.authCollection = null;
+  }
+
  setUnauthorizedHandler(handler: (() => Promise<void>) | null) {
    this.unauthorizedHandler = handler;
  }

+  setAuthUpdateListener(listener: AuthUpdateListener | null) {
+    this.authUpdateListener = listener;
+  }
+
+  setAuthFailureListener(listener: AuthFailureListener | null) {
+    this.authFailureListener = listener;
+  }
+
  private async handleUnauthorized() {
    if (!this.unauthorizedHandler || this.isHandlingUnauthorized) {
      return;
@@ -66,7 +122,7 @@ class UpSnapAPI {
    }
  }

-  private async throwApiError(response: Response, fallbackMessage: string): Promise<never> {
+  private async errorFromResponse(response: Response, fallbackMessage: string): Promise<ApiError> {
    let message = fallbackMessage;

    try {
@@ -76,23 +132,26 @@ class UpSnapAPI {
      // Ignore JSON parsing errors and use the fallback message.
    }

-    const isAuthError =
+    const apiError = new Error(message) as ApiError;
+    apiError.status = response.status;
+    apiError.isAuthError =
      response.status === 401 ||
      response.status === 403 ||
-      /authorization token|invalid token|unauthorized|not authenticated/i.test(message);
+      AUTH_ERROR_MESSAGE.test(message);
+    return apiError;
+  }

-    if (isAuthError) {
+  private async throwApiError(
+    response: Response,
+    fallbackMessage: string,
+    skipUnauthorizedHandler = false,
+  ): Promise<never> {
+    const error = await this.errorFromResponse(response, fallbackMessage);
+
+    if (error.isAuthError && !skipUnauthorizedHandler) {
      await this.handleUnauthorized();
    }

-    const error = new Error(message) as Error & {
-      status?: number;
-      isAuthError?: boolean;
-    };
-
-    error.status = response.status;
-    error.isAuthError = isAuthError;
-
    throw error;
  }

@@ -108,11 +167,166 @@ class UpSnapAPI {
    return headers;
  }

+  private sessionChanged(): ApiError {
+    const error = new Error('Auth session changed') as ApiError & { sessionChanged: true };
+    error.sessionChanged = true;
+    error.isAuthError = true;
+    return error;
+  }
+
+  /**
+   * One refresh is shared by the expiry timer and every request that receives a 401.
+   * PocketBase returns a new auth token and record for the same collection.
+   */
+  async refreshAuth(): Promise<AuthResponse> {
+    if (!this.refreshInFlight) {
+      this.refreshInFlight = this.performRefresh().finally(() => {
+        this.refreshInFlight = null;
+      });
+    }
+
+    return this.refreshInFlight;
+  }
+
+  private async performRefresh(): Promise<AuthResponse> {
+    const epoch = this.authEpoch;
+    const tokenAtStart = this.token;
+
+    try {
+      if (!tokenAtStart || !this.address) {
+        throw Object.assign(new Error('Not authenticated'), {
+          status: 401,
+          isAuthError: true,
+        }) as ApiError;
+      }
+
+      const collections: AuthCollection[] = this.authCollection
+        ? [this.authCollection]
+        : ['users', '_superusers'];
+      let lastError: ApiError | null = null;
+
+      for (let index = 0; index < collections.length; index += 1) {
+        const collection = collections[index];
+        const response = await fetch(
+          `${this.address}/collections/${collection}/auth-refresh`,
+          {
+            method: 'POST',
+            headers: this.getHeaders(),
+          },
+        );
+
+        if (this.authEpoch !== epoch || this.token !== tokenAtStart) {
+          throw this.sessionChanged();
+        }
+
+        if (response.ok) {
+          const data = (await response.json()) as AuthResponse;
+          if (this.authEpoch !== epoch || this.token !== tokenAtStart) {
+            throw this.sessionChanged();
+          }
+          if (!data?.token) {
+            throw Object.assign(new Error('Auth refresh failed'), {
+              status: 401,
+              isAuthError: true,
+            }) as ApiError;
+          }
+
+          this.authCollection = isAuthCollection(data.record?.collectionName)
+            ? data.record.collectionName
+            : collection;
+          this.token = data.token;
+          if (this.authCollection === '_superusers') {
+            this.canCreate = true;
+          }
+
+          try {
+            await this.authUpdateListener?.(data);
+          } catch (error) {
+            console.error('Failed to persist refreshed auth', error);
+          }
+
+          return data;
+        }
+
+        lastError = await this.errorFromResponse(response, 'Auth refresh failed');
+        const tryNextCollection =
+          !this.authCollection && index < collections.length - 1 && response.status === 403;
+        if (!tryNextCollection) {
+          throw lastError;
+        }
+      }
+
+      throw (
+        lastError ??
+        (Object.assign(new Error('Auth refresh failed'), {
+          status: 401,
+          isAuthError: true,
+        }) as ApiError)
+      );
+    } catch (error) {
+      if (!isSessionChanged(error)) {
+        try {
+          await this.authFailureListener?.(error);
+        } catch (listenerError) {
+          console.error('Failed to handle auth refresh failure', listenerError);
+        }
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * On 401, refresh once and retry the original request.
+   * A second 401, or a refresh the server rejects, ends the session.
+   */
+  private async request(url: string, fallbackMessage: string, init?: RequestInit): Promise<Response> {
+    const send = () =>
+      fetch(url, {
+        ...init,
+        headers: this.getHeaders(),
+      });
+
+    const response = await send();
+    if (response.ok) {
+      return response;
+    }
+
+    if (response.status === 401 && this.token) {
+      try {
+        await this.refreshAuth();
+      } catch (error) {
+        if (isSessionChanged(error)) {
+          throw error;
+        }
+        if (!isRevokedAuthError(error)) {
+          throw error;
+        }
+        await this.handleUnauthorized();
+        return this.throwApiError(response, fallbackMessage, true);
+      }
+
+      const retried = await send();
+      if (!retried.ok) {
+        if (retried.status === 401) {
+          await this.handleUnauthorized();
+          return this.throwApiError(retried, fallbackMessage, true);
+        }
+        return this.throwApiError(retried, fallbackMessage);
+      }
+      return retried;
+    }
+
+    return this.throwApiError(response, fallbackMessage);
+  }
+
  async authenticate(
    serverAddress: string,
    identity: string,
    password: string
  ): Promise<AuthResponse> {
+    this.authEpoch += 1;
+    this.token = null;
+    this.authCollection = null;
    this.address = serverAddress + '/api';

    const response = await fetch(
@@ -125,7 +339,7 @@ class UpSnapAPI {
    );

    if (!response.ok) {
-      const response = await fetch(
+      const superuserResponse = await fetch(
        `${this.address}/collections/_superusers/auth-with-password`,
        {
          method: 'POST',
@@ -134,18 +348,20 @@ class UpSnapAPI {
        }
      );

-      if (!response.ok) {
-        await this.throwApiError(response, 'Authentication failed');
+      if (!superuserResponse.ok) {
+        await this.throwApiError(superuserResponse, 'Authentication failed');
      }

-      const data: AuthResponse = await response.json();
+      const data: AuthResponse = await superuserResponse.json();
      this.token = data.token;
+      this.authCollection = '_superusers';
      this.canCreate = true;
      return data;
    }

    const data: AuthResponse = await response.json();
    this.token = data.token;
+    this.authCollection = 'users';

    const userID = data.record.id;
    const userPermissionResponse = await fetch(
@@ -165,142 +381,80 @@ class UpSnapAPI {
  }

  async getDevices(page = 1, perPage = 100): Promise<Device[]> {
-    const response = await fetch(
+    const response = await this.request(
      `${this.address}/collections/devices/records?page=${page}&perPage=${perPage}`,
-      {
-        headers: this.getHeaders(),
-      }
+      'Failed to fetch devices',
    );

-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to fetch devices');
-    }
-
    const data = await response.json();
    return data.items;
  }

  async getDevice(id: string): Promise<Device> {
-    const response = await fetch(
+    const response = await this.request(
      `${this.address}/collections/devices/records/${id}`,
-      {
-        headers: this.getHeaders(),
-      }
+      'Failed to fetch device',
    );

-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to fetch device');
-    }
-
    return response.json();
  }

  async createDevice(device: Partial<Device>): Promise<Device> {
-    const response = await fetch(
+    const response = await this.request(
      `${this.address}/collections/devices/records`,
+      'Failed to create device',
      {
        method: 'POST',
-        headers: this.getHeaders(),
        body: JSON.stringify(device),
-      }
+      },
    );

-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to create device');
-    }
-
    return response.json();
  }

  async updateDevice(id: string, device: Partial<Device>): Promise<Device> {
-    const response = await fetch(
+    const response = await this.request(
      `${this.address}/collections/devices/records/${id}`,
+      'Failed to update device',
      {
        method: 'PATCH',
-        headers: this.getHeaders(),
        body: JSON.stringify(device),
-      }
+      },
    );

-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to update device');
-    }
-
    return response.json();
  }

  async deleteDevice(id: string): Promise<void> {
-    const response = await fetch(
+    await this.request(
      `${this.address}/collections/devices/records/${id}`,
-      {
-        method: 'DELETE',
-        headers: this.getHeaders(),
-      }
+      'Failed to delete device',
+      { method: 'DELETE' },
    );
-
-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to delete device');
-    }
  }

  async wakeDevice(id: string): Promise<void> {
-    const response = await fetch(`${this.address}/upsnap/wake/${id}`, {
-      headers: this.getHeaders(),
-    });
-
-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to wake device');
-    }
+    await this.request(`${this.address}/upsnap/wake/${id}`, 'Failed to wake device');
  }

  async wakeGroup(id: string): Promise<void> {
-    const response = await fetch(`${this.address}/upsnap/wakegroup/${id}`, {
-      headers: this.getHeaders(),
-    });
-
-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to wake group');
-    }
+    await this.request(`${this.address}/upsnap/wakegroup/${id}`, 'Failed to wake group');
  }

  async sleepDevice(id: string): Promise<void> {
-    const response = await fetch(`${this.address}/upsnap/sleep/${id}`, {
-      headers: this.getHeaders(),
-    });
-
-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to sleep device');
-    }
+    await this.request(`${this.address}/upsnap/sleep/${id}`, 'Failed to sleep device');
  }

  async rebootDevice(id: string): Promise<void> {
-    const response = await fetch(`${this.address}/upsnap/reboot/${id}`, {
-      headers: this.getHeaders(),
-    });
-
-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to reboot device');
-    }
+    await this.request(`${this.address}/upsnap/reboot/${id}`, 'Failed to reboot device');
  }

  async shutdownDevice(id: string): Promise<void> {
-    const response = await fetch(`${this.address}/upsnap/shutdown/${id}`, {
-      headers: this.getHeaders(),
-    });
-
-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to shutdown device');
-    }
+    await this.request(`${this.address}/upsnap/shutdown/${id}`, 'Failed to shutdown device');
  }

  async scanNetwork(): Promise<NetworkScanResult[]> {
-    const response = await fetch(`${this.address}/upsnap/scan`, {
-      headers: this.getHeaders(),
-    });
-
-    if (!response.ok) {
-      await this.throwApiError(response, 'Failed to scan network');
-    }
+    const response = await this.request(`${this.address}/upsnap/scan`, 'Failed to scan network');

    const data = await response.json();
    if (data.devices && Array.isArray(data.devices)) {
@@ -0,0 +1,41 @@
+const BASE64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+
+function decodeBase64Url(segment: string): string {
+  const normalized = segment.replace(/-/g, '+').replace(/_/g, '/');
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4);
+  const bytes: number[] = [];
+
+  for (let index = 0; index < padded.length; index += 4) {
+    const a = BASE64_ALPHABET.indexOf(padded[index]);
+    const b = BASE64_ALPHABET.indexOf(padded[index + 1]);
+    const c = padded[index + 2] === '=' ? 0 : BASE64_ALPHABET.indexOf(padded[index + 2]);
+    const d = padded[index + 3] === '=' ? 0 : BASE64_ALPHABET.indexOf(padded[index + 3]);
+    if (a < 0 || b < 0 || c < 0 || d < 0) {
+      throw new Error('Invalid base64url');
+    }
+
+    const chunk = (a << 18) | (b << 12) | (c << 6) | d;
+    bytes.push((chunk >> 16) & 255);
+    if (padded[index + 2] !== '=') bytes.push((chunk >> 8) & 255);
+    if (padded[index + 3] !== '=') bytes.push(chunk & 255);
+  }
+
+  return String.fromCharCode(...bytes);
+}
+
+/**
+ * Reads the JWT `exp` claim in milliseconds.
+ * Scheduling only; the signature is not verified.
+ */
+export function getJwtExpiryMs(token: string): number | null {
+  const segment = token.split('.')[1];
+  if (!segment) return null;
+
+  try {
+    const payload = JSON.parse(decodeBase64Url(segment)) as { exp?: unknown };
+    if (typeof payload.exp !== 'number' || !Number.isFinite(payload.exp)) return null;
+    return payload.exp * 1000;
+  } catch {
+    return null;
+  }
+}