First pass of error message improvements.

rkistner · rkistner · commit 99e84eb34ef3 · 2025-05-07T13:44:56.000+02:00
diff --git a/modules/module-postgres/src/auth/SupabaseKeyCollector.ts b/modules/module-postgres/src/auth/SupabaseKeyCollector.ts
@@ -1,17 +1,18 @@
 import * as lib_postgres from '@powersync/lib-service-postgres';
-import { auth } from '@powersync/service-core';
+import { auth, KeyResult } from '@powersync/service-core';
 import * as pgwire from '@powersync/service-jpgwire';
 import * as jose from 'jose';
 
 import * as types from '../types/types.js';
+import { AuthorizationError2, ErrorCode } from '@powersync/lib-services-framework';
 
 /**
  * Fetches key from the Supabase database.
  *
  * Unfortunately, despite the JWTs containing a kid, we have no way to lookup that kid
  * before receiving a valid token.
  *
- * @deprecated Supabase is removing support for "app.settings.jwt_secret".
+ * @deprecated Supabase is removing support for "app.settings.jwt_secret". This is likely to not function anymore, except in some self-hosted setups.
  */
 export class SupabaseKeyCollector implements auth.KeyCollector {
   private pool: pgwire.PgClient;
@@ -35,7 +36,7 @@ export class SupabaseKeyCollector implements auth.KeyCollector {
     return this.pool.end();
   }
 
-  async getKeys() {
+  async getKeys(): Promise<KeyResult> {
     let row: { jwt_secret: string };
     try {
       const rows = pgwire.pgwireRows(
@@ -44,7 +45,10 @@ export class SupabaseKeyCollector implements auth.KeyCollector {
       row = rows[0] as any;
     } catch (e) {
       if (e.message?.includes('unrecognized configuration parameter')) {
-        throw new jose.errors.JOSEError(`Generate a new JWT secret on Supabase. Cause: ${e.message}`);
+        throw new AuthorizationError2(
+          ErrorCode.PSYNC_S2201,
+          'No JWT secret found in Supabase database. Manually configure the secret.'
+        );
       } else {
         throw e;
       }
@@ -53,7 +57,12 @@ export class SupabaseKeyCollector implements auth.KeyCollector {
     if (secret == null) {
       return {
         keys: [],
-        errors: [new jose.errors.JWKSNoMatchingKey()]
+        errors: [
+          new AuthorizationError2(
+            ErrorCode.PSYNC_S2201,
+            'No JWT secret found in Supabase database. Manually configure the secret.'
+          )
+        ]
       };
     } else {
       const key: jose.JWK = {
diff --git a/packages/service-core/src/auth/CachedKeyCollector.ts b/packages/service-core/src/auth/CachedKeyCollector.ts
@@ -3,6 +3,8 @@ import timers from 'timers/promises';
 import { KeySpec } from './KeySpec.js';
 import { LeakyBucket } from './LeakyBucket.js';
 import { KeyCollector, KeyResult } from './KeyCollector.js';
+import { AuthorizationError2 } from '@powersync/lib-services-framework';
+import { mapAuthConfigError } from './utils.js';
 
 /**
  * Manages caching and refreshing for a key collector.
@@ -39,7 +41,7 @@ export class CachedKeyCollector implements KeyCollector {
    */
   private keyExpiry = 3600000;
 
-  private currentErrors: jose.errors.JOSEError[] = [];
+  private currentErrors: AuthorizationError2[] = [];
   /**
    * Indicates a "fatal" error that should be retried.
    */
@@ -103,11 +105,7 @@ export class CachedKeyCollector implements KeyCollector {
     } catch (e) {
       this.error = true;
       // No result - keep previous keys
-      if (e instanceof jose.errors.JOSEError) {
-        this.currentErrors = [e];
-      } else {
-        this.currentErrors = [new jose.errors.JOSEError(e.message ?? 'Failed to fetch keys')];
-      }
+      this.currentErrors = [mapAuthConfigError(e)];
     }
   }
 
diff --git a/packages/service-core/src/auth/CompoundKeyCollector.ts b/packages/service-core/src/auth/CompoundKeyCollector.ts
@@ -1,6 +1,7 @@
 import * as jose from 'jose';
 import { KeySpec } from './KeySpec.js';
 import { KeyCollector, KeyResult } from './KeyCollector.js';
+import { AuthorizationError2 } from '@powersync/lib-services-framework';
 
 export class CompoundKeyCollector implements KeyCollector {
   private collectors: KeyCollector[];
@@ -15,7 +16,7 @@ export class CompoundKeyCollector implements KeyCollector {
 
   async getKeys(): Promise<KeyResult> {
     let keys: KeySpec[] = [];
-    let errors: jose.errors.JOSEError[] = [];
+    let errors: AuthorizationError2[] = [];
     const promises = this.collectors.map((collector) =>
       collector.getKeys().then((result) => {
         keys.push(...result.keys);
diff --git a/packages/service-core/src/auth/KeyCollector.ts b/packages/service-core/src/auth/KeyCollector.ts
@@ -1,4 +1,4 @@
-import * as jose from 'jose';
+import { AuthorizationError2 } from '@powersync/lib-services-framework';
 import { KeySpec } from './KeySpec.js';
 
 export interface KeyCollector {
@@ -22,6 +22,6 @@ export interface KeyCollector {
 }
 
 export interface KeyResult {
-  errors: jose.errors.JOSEError[];
+  errors: AuthorizationError2[];
   keys: KeySpec[];
 }
diff --git a/packages/service-core/src/auth/KeyStore.ts b/packages/service-core/src/auth/KeyStore.ts
@@ -1,4 +1,4 @@
-import { logger } from '@powersync/lib-services-framework';
+import { logger, errors, AuthorizationError2, ErrorCode } from '@powersync/lib-services-framework';
 import * as jose from 'jose';
 import secs from '../util/secs.js';
 import { JwtPayload } from './JwtPayload.js';
@@ -69,7 +69,11 @@ export class KeyStore<Collector extends KeyCollector = KeyCollector> {
         return audiences.includes(a);
       })
     ) {
-      throw new jose.errors.JWTClaimValidationFailed('unexpected "aud" claim value', 'aud', 'check_failed');
+      throw new AuthorizationError2(
+        ErrorCode.PSYNC_S2105,
+        `Unexpected "aud" claim value: ${JSON.stringify(tokenPayload.aud)}`,
+        { sensitiveDetails: `Current configuration allows these audience values: ${JSON.stringify(audiences)}` }
+      );
     }
 
     const tokenDuration = tokenPayload.exp! - tokenPayload.iat!;
@@ -78,12 +82,15 @@ export class KeyStore<Collector extends KeyCollector = KeyCollector> {
     // is too far into the future.
     const maxAge = keyOptions.maxLifetimeSeconds ?? secs(options.maxAge);
     if (tokenDuration > maxAge) {
-      throw new jose.errors.JWTInvalid(`Token must expire in a maximum of ${maxAge} seconds, got ${tokenDuration}`);
+      throw new AuthorizationError2(
+        ErrorCode.PSYNC_S2104,
+        `Token must expire in a maximum of ${maxAge} seconds, got ${tokenDuration}s`
+      );
     }
 
     const parameters = tokenPayload.parameters;
     if (parameters != null && (Array.isArray(parameters) || typeof parameters != 'object')) {
-      throw new jose.errors.JWTInvalid('parameters must be an object');
+      throw new AuthorizationError2(ErrorCode.PSYNC_S2101, `Payload parameters must be an object`);
     }
 
     return tokenPayload as JwtPayload;
@@ -112,7 +119,9 @@ export class KeyStore<Collector extends KeyCollector = KeyCollector> {
       for (let key of keys) {
         if (key.kid == kid) {
           if (!key.matchesAlgorithm(header.alg)) {
-            throw new jose.errors.JOSEAlgNotAllowed(`Unexpected token algorithm ${header.alg}`);
+            throw new AuthorizationError2(ErrorCode.PSYNC_S2101, `Unexpected token algorithm ${header.alg}`, {
+              sensitiveDetails: `Key kid: ${key.source.kid}, alg: ${key.source.alg}, kty: ${key.source.kty}`
+            });
           }
           return key;
         }
@@ -145,8 +154,12 @@ export class KeyStore<Collector extends KeyCollector = KeyCollector> {
         logger.error(`Failed to refresh keys`, e);
       });
 
-      throw new jose.errors.JOSEError(
-        'Could not find an appropriate key in the keystore. The key is missing or no key matched the token KID'
+      throw new AuthorizationError2(
+        ErrorCode.PSYNC_S2101,
+        'Could not find an appropriate key in the keystore. The key is missing or no key matched the token KID',
+        {
+          sensitiveDetails: `Token kid: ${kid}, token algorithm: ${header.alg}, known kid values: ${keys.map((key) => key.kid ?? '*').join(', ')}`
+        }
       );
     }
   }
diff --git a/packages/service-core/src/auth/RemoteJWKSCollector.ts b/packages/service-core/src/auth/RemoteJWKSCollector.ts
@@ -4,6 +4,7 @@ import * as jose from 'jose';
 import fetch from 'node-fetch';
 
 import {
+  AuthorizationError2,
   ErrorCode,
   LookupOptions,
   makeHostnameLookupFunction,
@@ -62,7 +63,9 @@ export class RemoteJWKSCollector implements KeyCollector {
     });
 
     if (!res.ok) {
-      throw new jose.errors.JWKSInvalid(`JWKS request failed with ${res.statusText}`);
+      throw new AuthorizationError2(ErrorCode.PSYNC_S2204, `JWKS request failed with ${res.statusText}`, {
+        sensitiveDetails: `JWKS URL: ${this.url}`
+      });
     }
 
     const data = (await res.json()) as any;
@@ -75,7 +78,14 @@ export class RemoteJWKSCollector implements KeyCollector {
       !Array.isArray(data.keys) ||
       !(data.keys as any[]).every((key) => typeof key == 'object' && !Array.isArray(key))
     ) {
-      return { keys: [], errors: [new jose.errors.JWKSInvalid(`No keys in found in JWKS response`)] };
+      return {
+        keys: [],
+        errors: [
+          new AuthorizationError2(ErrorCode.PSYNC_S2204, `JWKS request failed with ${res.statusText}`, {
+            sensitiveDetails: `JWKS URL: ${this.url}. Response:\n${JSON.stringify(data, null, 2)}`
+          })
+        ]
+      };
     }
 
     let keys: KeySpec[] = [];
diff --git a/packages/service-core/src/auth/auth-index.ts b/packages/service-core/src/auth/auth-index.ts
@@ -8,3 +8,4 @@ export * from './LeakyBucket.js';
 export * from './RemoteJWKSCollector.js';
 export * from './StaticKeyCollector.js';
 export * from './StaticSupabaseKeyCollector.js';
+export * from './utils.js';
diff --git a/packages/service-core/src/auth/utils.ts b/packages/service-core/src/auth/utils.ts
@@ -0,0 +1,34 @@
+import { AuthorizationError2, ErrorCode } from '@powersync/lib-services-framework';
+import * as jose from 'jose';
+
+export function mapJoseError(error: jose.errors.JOSEError): AuthorizationError2 {
+  // TODO: improved message for exp issues, etc
+  if (error.code === 'ERR_JWS_INVALID' || error.code === 'ERR_JWT_INVALID') {
+    throw new AuthorizationError2(ErrorCode.PSYNC_S2101, 'Token is not a well-formed JWT. Check the token format.', {
+      details: error.message
+    });
+  }
+  return new AuthorizationError2(ErrorCode.PSYNC_S2101, error.message, { cause: error });
+}
+
+export function mapAuthError(error: any): AuthorizationError2 {
+  if (error instanceof AuthorizationError2) {
+    return error;
+  } else if (error instanceof jose.errors.JOSEError) {
+    return mapJoseError(error);
+  }
+  return new AuthorizationError2(ErrorCode.PSYNC_S2101, error.message, { cause: error });
+}
+
+export function mapJoseConfigError(error: jose.errors.JOSEError): AuthorizationError2 {
+  return new AuthorizationError2(ErrorCode.PSYNC_S2201, error.message, { cause: error });
+}
+
+export function mapAuthConfigError(error: any): AuthorizationError2 {
+  if (error instanceof AuthorizationError2) {
+    return error;
+  } else if (error instanceof jose.errors.JOSEError) {
+    return mapJoseConfigError(error);
+  }
+  return new AuthorizationError2(ErrorCode.PSYNC_S2201, error.message, { cause: error });
+}
diff --git a/packages/service-core/src/routes/auth.ts b/packages/service-core/src/routes/auth.ts
@@ -105,7 +105,7 @@ export async function authorizeUser(context: Context, authHeader: string = ''):
   if (token == null) {
     return {
       authorized: false,
-      error: new AuthorizationError2(ErrorCode.PSYNC_S2115, 'Authentication required')
+      error: new AuthorizationError2(ErrorCode.PSYNC_S2106, 'Authentication required')
     };
   }
 
@@ -139,20 +139,10 @@ export async function generateContext(serviceContext: ServiceContext, token: str
       }
     };
   } catch (err) {
-    if (err instanceof ServiceError) {
-      return {
-        context: null,
-        tokenError: err
-      };
-    } else {
-      return {
-        context: null,
-        tokenError: new AuthorizationError2(ErrorCode.PSYNC_S2101, 'Authentication error', {
-          details: err.message,
-          cause: err
-        })
-      };
-    }
+    return {
+      context: null,
+      tokenError: auth.mapAuthError(err)
+    };
   }
 }
 
diff --git a/packages/service-core/src/routes/configure-rsocket.ts b/packages/service-core/src/routes/configure-rsocket.ts
@@ -26,15 +26,15 @@ export function configureRSocket(router: ReactiveSocketRouter<Context>, options:
       const { token, user_agent } = RSocketContextMeta.decode(deserialize(data) as any);
 
       if (!token) {
-        throw new errors.AuthorizationError2(ErrorCode.PSYNC_S2115, 'No token provided');
+        throw new errors.AuthorizationError2(ErrorCode.PSYNC_S2106, 'No token provided');
       }
 
       try {
         const extracted_token = getTokenFromHeader(token);
         if (extracted_token != null) {
           const { context, tokenError } = await generateContext(options.service_context, extracted_token);
           if (context?.token_payload == null) {
-            throw new errors.AuthorizationError2(ErrorCode.PSYNC_S2115, 'Authentication required');
+            throw new errors.AuthorizationError2(ErrorCode.PSYNC_S2106, 'Authentication required');
           }
 
           if (!service_context.routerEngine) {
@@ -50,7 +50,7 @@ export function configureRSocket(router: ReactiveSocketRouter<Context>, options:
           };
         } else {
           // Token field is present, but did not contain a token.
-          throw new errors.AuthorizationError2(ErrorCode.PSYNC_S2115, 'No valid token provided');
+          throw new errors.AuthorizationError2(ErrorCode.PSYNC_S2106, 'No valid token provided');
         }
       } catch (ex) {
         logger.error(ex);
diff --git a/packages/service-errors/src/codes.ts b/packages/service-errors/src/codes.ts
@@ -313,34 +313,39 @@ export enum ErrorCode {
    * 1. Token kid is not found in the keystore.
    * 2. Signature does not match the kid in the keystore.
    */
-  PSYNC_S2111 = 'PSYNC_S2111',
+  PSYNC_S2102 = 'PSYNC_S2102',
 
   /**
    * Token has expired. Check the expiry date on the token.
    */
-  PSYNC_S2112 = 'PSYNC_S2112',
+  PSYNC_S2103 = 'PSYNC_S2103',
 
   /**
-   * Token expiration date is too long. Issue shorter-lived tokens.
+   * Token expiration period is too long. Issue shorter-lived tokens.
    */
-  PSYNC_S2113 = 'PSYNC_S2113',
+  PSYNC_S2104 = 'PSYNC_S2104',
 
   /**
    * Token audience does not match expected values.
    *
    * Check the aud value on the token, compared to the audience values allowed in the service config.
    */
-  PSYNC_S2114 = 'PSYNC_S2114',
+  PSYNC_S2105 = 'PSYNC_S2105',
 
   /**
    * No token provided. An auth token is required for every request.
    *
    * The Auhtorization header must start with "Token" or "Bearer", followed by the JWT.
    */
-  PSYNC_S2115 = 'PSYNC_S2115',
+  PSYNC_S2106 = 'PSYNC_S2106',
 
   // ## PSYNC_S22xx: Auth integration errors
 
+  /**
+   * Generic auth configuration error. See the message for details.
+   */
+  PSYNC_S2201 = 'PSYNC_S2201',
+
   /**
    * IPv6 support is not enabled for the JWKS URI.
    *
@@ -355,6 +360,11 @@ export enum ErrorCode {
    */
   PSYNC_S2203 = 'PSYNC_S2203',
 
+  /**
+   * JWKS request failed.
+   */
+  PSYNC_S2204 = 'PSYNC_S2204',
+
   // ## PSYNC_S23xx: Sync API errors
 
   /**

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import * as jose from 'jose';`
	`1`	`+import { AuthorizationError2 } from '@powersync/lib-services-framework';`
`2`	`2`	`import { KeySpec } from './KeySpec.js';`
`3`	`3`
`4`	`4`	`export interface KeyCollector {`
`@@ -22,6 +22,6 @@ export interface KeyCollector {`
`22`	`22`	`}`
`23`	`23`
`24`	`24`	`export interface KeyResult {`
`25`		`- errors: jose.errors.JOSEError[];`
	`25`	`+ errors: AuthorizationError2[];`
`26`	`26`	`keys: KeySpec[];`
`27`	`27`	`}`