@powersync/service-core 1.11.3 → 1.12.1

package/dist/util/protocol-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol-types.js","sourceRoot":"","sources":["../../src/util/protocol-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAG9B,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,MAAM;IAEd;;OAEG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM;CAChB,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C;;OAEG;IACH,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;IAE1C;;OAEG;IACH,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE;IAElC;;OAEG;IACH,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;IAEtC;;OAEG;IACH,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;IAE9B;;OAEG;IACH,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;IAEjC;;OAEG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAEtC;;OAEG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC"}
+{"version":3,"file":"protocol-types.js","sourceRoot":"","sources":["../../src/util/protocol-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,CAAC,MAAM,UAAU,CAAC;AAI9B,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,MAAM;IAEd;;OAEG;IACH,KAAK,EAAE,CAAC,CAAC,MAAM;CAChB,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3C;;OAEG;IACH,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC,QAAQ,EAAE;IAE1C;;OAEG;IACH,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE;IAElC;;OAEG;IACH,gBAAgB,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;IAEtC;;OAEG;IACH,QAAQ,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;IAE9B;;OAEG;IACH,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE;IAEjC;;OAEG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAEtC;;OAEG;IACH,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC"}

package/dist/util/utils.d.ts

@@ -46,7 +46,7 @@ export declare function isCompleteRow(storeData: boolean, row: sync_rules.Toasta
  *
  * Used for tests.
  */
-export declare function reduceBucket(operations: OplogEntry[]): OplogEntry[];
+export declare function reduceBucket(operations: OplogEntry[]): OplogEntry<import("./protocol-types.js").StoredOplogData>[];
 /**
  * Flattens string to reduce memory usage (around 320 bytes -> 120 bytes),
  * at the cost of some upfront CPU usage.

package/package.json

@@ -5,7 +5,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.11.3",
+  "version": "1.12.1",
   "main": "dist/index.js",
   "license": "FSL-1.1-Apache-2.0",
   "type": "module",
@@ -29,19 +29,18 @@
     "node-fetch": "^3.3.2",
     "ts-codec": "^1.3.0",
     "uri-js": "^4.4.1",
-    "uuid": "^9.0.1",
+    "uuid": "^11.1.0",
     "winston": "^3.13.0",
     "yaml": "^2.3.2",
-    "@powersync/lib-services-framework": "0.5.4",
+    "@powersync/lib-services-framework": "0.6.0",
     "@powersync/service-jsonbig": "0.17.10",
-    "@powersync/service-rsocket-router": "0.0.21",
-    "@powersync/service-sync-rules": "0.26.0",
-    "@powersync/service-types": "0.10.0"
+    "@powersync/service-rsocket-router": "0.1.0",
+    "@powersync/service-sync-rules": "0.27.0",
+    "@powersync/service-types": "0.11.0"
   },
   "devDependencies": {
     "@types/async": "^3.2.24",
     "@types/lodash": "^4.17.5",
-    "@types/uuid": "^9.0.4",
     "fastify": "4.23.2",
     "fastify-plugin": "^4.5.1"
   },

package/src/api/RouteAPI.ts

@@ -49,11 +49,6 @@ export interface RouteAPI {
    */
   getReplicationLag(options: ReplicationLagOptions): Promise<number | undefined>;
 
-  /**
-   * Get the current LSN or equivalent replication HEAD position identifier
-   */
-  getReplicationHead(): Promise<string>;
-
   /**
    * Get the current LSN or equivalent replication HEAD position identifier.
    *

package/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 { AuthorizationError } 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: AuthorizationError[] = [];
   /**
    * 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)];
     }
   }
 

package/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 { AuthorizationError } 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: AuthorizationError[] = [];
     const promises = this.collectors.map((collector) =>
       collector.getKeys().then((result) => {
         keys.push(...result.keys);

package/src/auth/KeyCollector.ts

@@ -1,4 +1,4 @@
-import * as jose from 'jose';
+import { AuthorizationError } 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: AuthorizationError[];
   keys: KeySpec[];
 }

package/src/auth/KeyStore.ts

@@ -1,9 +1,10 @@
-import { logger } from '@powersync/lib-services-framework';
+import { logger, errors, AuthorizationError, ErrorCode } from '@powersync/lib-services-framework';
 import * as jose from 'jose';
 import secs from '../util/secs.js';
 import { JwtPayload } from './JwtPayload.js';
 import { KeyCollector } from './KeyCollector.js';
 import { KeyOptions, KeySpec, SUPPORTED_ALGORITHMS } from './KeySpec.js';
+import { mapAuthError } from './utils.js';
 
 /**
  * KeyStore to get keys and verify tokens.
@@ -49,7 +50,8 @@ export class KeyStore<Collector extends KeyCollector = KeyCollector> {
       clockTolerance: 60,
       // More specific algorithm checking is done when selecting the key to use.
       algorithms: SUPPORTED_ALGORITHMS,
-      requiredClaims: ['aud', 'sub', 'iat', 'exp']
+      // 'aud' presence is checked below, so we can add more details to the error message.
+      requiredClaims: ['sub', 'iat', 'exp']
     });
 
     let audiences = options.defaultAudiences;
@@ -60,8 +62,12 @@ export class KeyStore<Collector extends KeyCollector = KeyCollector> {
 
     const tokenPayload = result.payload;
 
-    let aud = tokenPayload.aud!;
-    if (!Array.isArray(aud)) {
+    let aud = tokenPayload.aud;
+    if (aud == null) {
+      throw new AuthorizationError(ErrorCode.PSYNC_S2105, `JWT payload is missing a required claim "aud"`, {
+        configurationDetails: `Current configuration allows these audience values: ${JSON.stringify(audiences)}`
+      });
+    } else if (!Array.isArray(aud)) {
       aud = [aud];
     }
     if (
@@ -69,7 +75,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 AuthorizationError(
+        ErrorCode.PSYNC_S2105,
+        `Unexpected "aud" claim value: ${JSON.stringify(tokenPayload.aud)}`,
+        { configurationDetails: `Current configuration allows these audience values: ${JSON.stringify(audiences)}` }
+      );
     }
 
     const tokenDuration = tokenPayload.exp! - tokenPayload.iat!;
@@ -78,12 +88,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 AuthorizationError(
+        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 AuthorizationError(ErrorCode.PSYNC_S2101, `Payload parameters must be an object`);
     }
 
     return tokenPayload as JwtPayload;
@@ -91,16 +104,20 @@ export class KeyStore<Collector extends KeyCollector = KeyCollector> {
 
   private async verifyInternal(token: string, options: jose.JWTVerifyOptions) {
     let keyOptions: KeyOptions | undefined = undefined;
-    const result = await jose.jwtVerify(
-      token,
-      async (header) => {
-        let key = await this.getCachedKey(token, header);
-        keyOptions = key.options;
-        return key.key;
-      },
-      options
-    );
-    return { result, keyOptions: keyOptions! };
+    try {
+      const result = await jose.jwtVerify(
+        token,
+        async (header) => {
+          let key = await this.getCachedKey(token, header);
+          keyOptions = key.options;
+          return key.key;
+        },
+        options
+      );
+      return { result, keyOptions: keyOptions! };
+    } catch (e) {
+      throw mapAuthError(e, token);
+    }
   }
 
   private async getCachedKey(token: string, header: jose.JWTHeaderParameters): Promise<KeySpec> {
@@ -112,7 +129,10 @@ 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 AuthorizationError(ErrorCode.PSYNC_S2101, `Unexpected token algorithm ${header.alg}`, {
+              configurationDetails: `Key kid: ${key.source.kid}, alg: ${key.source.alg}, kty: ${key.source.kty}`
+              // Token details automatically populated elsewhere
+            });
           }
           return key;
         }
@@ -145,8 +165,13 @@ 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 AuthorizationError(
+        ErrorCode.PSYNC_S2101,
+        'Could not find an appropriate key in the keystore. The key is missing or no key matched the token KID',
+        {
+          configurationDetails: `Known kid values: ${keys.map((key) => key.kid ?? '*').join(', ')}`
+          // tokenDetails automatically populated later
+        }
       );
     }
   }

package/src/auth/RemoteJWKSCollector.ts

@@ -4,6 +4,7 @@ import * as jose from 'jose';
 import fetch from 'node-fetch';
 
 import {
+  AuthorizationError,
   ErrorCode,
   LookupOptions,
   makeHostnameLookupFunction,
@@ -46,28 +47,43 @@ export class RemoteJWKSCollector implements KeyCollector {
     this.agent = this.resolveAgent();
   }
 
-  async getKeys(): Promise<KeyResult> {
+  private async getJwksData(): Promise<any> {
     const abortController = new AbortController();
     const timeout = setTimeout(() => {
       abortController.abort();
     }, 30_000);
 
-    const res = await fetch(this.url, {
-      method: 'GET',
-      headers: {
-        Accept: 'application/json'
-      },
-      signal: abortController.signal,
-      agent: this.agent
-    });
-
-    if (!res.ok) {
-      throw new jose.errors.JWKSInvalid(`JWKS request failed with ${res.statusText}`);
-    }
+    try {
+      const res = await fetch(this.url, {
+        method: 'GET',
+        headers: {
+          Accept: 'application/json'
+        },
+        signal: abortController.signal,
+        agent: this.agent
+      });
+
+      if (!res.ok) {
+        throw new AuthorizationError(ErrorCode.PSYNC_S2204, `JWKS request failed with ${res.statusText}`, {
+          configurationDetails: `JWKS URL: ${this.url}`
+        });
+      }
 
-    const data = (await res.json()) as any;
+      return (await res.json()) as any;
+    } catch (e) {
+      throw new AuthorizationError(ErrorCode.PSYNC_S2204, `JWKS request failed`, {
+        configurationDetails: `JWKS URL: ${this.url}`,
+        // This covers most cases of FetchError
+        // `cause: e` could lose the error message
+        cause: { message: e.message, code: e.code }
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
 
-    clearTimeout(timeout);
+  async getKeys(): Promise<KeyResult> {
+    const data = await this.getJwksData();
 
     // https://github.com/panva/jose/blob/358e864a0cccf1e0f9928a959f91f18f3f06a7de/src/jwks/local.ts#L36
     if (
@@ -75,7 +91,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 AuthorizationError(ErrorCode.PSYNC_S2204, `Invalid JWKS response`, {
+            configurationDetails: `JWKS URL: ${this.url}. Response:\n${JSON.stringify(data, null, 2)}`
+          })
+        ]
+      };
     }
 
     let keys: KeySpec[] = [];

package/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';

package/src/auth/utils.ts

@@ -0,0 +1,102 @@
+import { AuthorizationError, ErrorCode } from '@powersync/lib-services-framework';
+import * as jose from 'jose';
+
+export function mapJoseError(error: jose.errors.JOSEError, token: string): AuthorizationError {
+  const tokenDetails = tokenDebugDetails(token);
+  if (error.code === jose.errors.JWSInvalid.code || error.code === jose.errors.JWTInvalid.code) {
+    return new AuthorizationError(ErrorCode.PSYNC_S2101, 'Token is not a well-formed JWT. Check the token format.', {
+      tokenDetails,
+      cause: error
+    });
+  } else if (error.code === jose.errors.JWTClaimValidationFailed.code) {
+    // Jose message: missing required "sub" claim
+    const claim = (error as jose.errors.JWTClaimValidationFailed).claim;
+    return new AuthorizationError(
+      ErrorCode.PSYNC_S2101,
+      `JWT payload is missing a required claim ${JSON.stringify(claim)}`,
+      {
+        cause: error,
+        tokenDetails
+      }
+    );
+  } else if (error.code == jose.errors.JWTExpired.code) {
+    // Jose message: "exp" claim timestamp check failed
+    return new AuthorizationError(ErrorCode.PSYNC_S2103, `JWT has expired`, {
+      cause: error,
+      tokenDetails
+    });
+  }
+  return new AuthorizationError(ErrorCode.PSYNC_S2101, error.message, { cause: error });
+}
+
+export function mapAuthError(error: any, token: string): AuthorizationError {
+  if (error instanceof AuthorizationError) {
+    error.tokenDetails ??= tokenDebugDetails(token);
+    return error;
+  } else if (error instanceof jose.errors.JOSEError) {
+    return mapJoseError(error, token);
+  }
+  return new AuthorizationError(ErrorCode.PSYNC_S2101, error.message, {
+    cause: error,
+    tokenDetails: tokenDebugDetails(token)
+  });
+}
+
+export function mapJoseConfigError(error: jose.errors.JOSEError): AuthorizationError {
+  return new AuthorizationError(ErrorCode.PSYNC_S2201, error.message ?? 'Authorization error', { cause: error });
+}
+
+export function mapAuthConfigError(error: any): AuthorizationError {
+  if (error instanceof AuthorizationError) {
+    return error;
+  } else if (error instanceof jose.errors.JOSEError) {
+    return mapJoseConfigError(error);
+  }
+  return new AuthorizationError(ErrorCode.PSYNC_S2201, error.message ?? 'Auth configuration error', { cause: error });
+}
+
+/**
+ * Decode token for debugging purposes.
+ *
+ * We use this to add details to our logs. We don't log the entire token, since it may for example
+ * a password incorrectly used as a token.
+ */
+function tokenDebugDetails(token: string): string {
+  try {
+    // For valid tokens, we return the header and payload
+    const header = jose.decodeProtectedHeader(token);
+    const payload = jose.decodeJwt(token);
+    return `<header: ${JSON.stringify(header)} payload: ${JSON.stringify(payload)}>`;
+  } catch (e) {
+    // Token fails to parse. Return some details.
+    return invalidTokenDetails(token);
+  }
+}
+
+function invalidTokenDetails(token: string): string {
+  const parts = token.split('.');
+  if (parts.length !== 3) {
+    return `<token with ${parts.length} parts (needs 3), length=${token.length}>`;
+  }
+
+  const [headerB64, payloadB64, signatureB64] = parts;
+
+  try {
+    JSON.parse(Buffer.from(headerB64, 'base64url').toString('utf8'));
+  } catch (e) {
+    return `<token with unparsable header>`;
+  }
+
+  try {
+    JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8'));
+  } catch (e) {
+    return `<token with unparsable payload>`;
+  }
+  try {
+    Buffer.from(signatureB64, 'base64url');
+  } catch (e) {
+    return `<token with unparsable signature>`;
+  }
+
+  return `<invalid JWT, length=${token.length}>`;
+}

package/src/entry/commands/compact-action.ts

@@ -37,7 +37,10 @@ export function registerCompactAction(program: Command) {
       logger.info(`Compacting storage for ${buckets?.join(', ')}...`);
     }
     const config = await utils.loadConfig(extractRunnerOptions(options));
-    const serviceContext = new system.ServiceContextContainer(config);
+    const serviceContext = new system.ServiceContextContainer({
+      serviceMode: system.ServiceContextMode.COMPACT,
+      configuration: config
+    });
 
     // Register modules in order to allow custom module compacting
     const moduleManager = container.getImplementation(modules.ModuleManager);

package/src/entry/commands/migrate-action.ts

@@ -18,7 +18,10 @@ export function registerMigrationAction(program: Command) {
     .argument('<direction>', 'Migration direction. `up` or `down`')
     .action(async (direction: migrations.Direction, options) => {
       const config = await utils.loadConfig(extractRunnerOptions(options));
-      const serviceContext = new system.ServiceContextContainer(config);
+      const serviceContext = new system.ServiceContextContainer({
+        serviceMode: system.ServiceContextMode.MIGRATION,
+        configuration: config
+      });
 
       // Register modules in order to allow custom module migrations
       const moduleManager = container.getImplementation(modules.ModuleManager);

package/src/entry/commands/test-connection-action.ts

@@ -17,7 +17,10 @@ export function registerTestConnectionAction(program: Command) {
   return testConnectionCommand.description('Test connection').action(async (options) => {
     try {
       const config = await utils.loadConfig(extractRunnerOptions(options));
-      const serviceContext = new system.ServiceContextContainer(config);
+      const serviceContext = new system.ServiceContextContainer({
+        serviceMode: system.ServiceContextMode.TEST_CONNECTION,
+        configuration: config
+      });
 
       const replication = new ReplicationEngine();
       serviceContext.register(ReplicationEngine, replication);

package/src/routes/RouterEngine.ts

@@ -2,15 +2,8 @@ import { logger } from '@powersync/lib-services-framework';
 
 import * as api from '../api/api-index.js';
 
-import { ADMIN_ROUTES } from './endpoints/admin.js';
-import { CHECKPOINT_ROUTES } from './endpoints/checkpointing.js';
-import { PROBES_ROUTES } from './endpoints/probes.js';
-import { syncStreamReactive } from './endpoints/socket-route.js';
-import { SYNC_RULES_ROUTES } from './endpoints/sync-rules.js';
-import { SYNC_STREAM_ROUTES } from './endpoints/sync-stream.js';
 import { SocketRouteGenerator } from './router-socket.js';
 import { RouteDefinition } from './router.js';
-import { SyncContext } from '../sync/SyncContext.js';
 
 export type RouterSetupResponse = {
   onShutdown: () => Promise<void>;
@@ -47,14 +40,25 @@ export class RouterEngine {
     this.cleanupHandler = null;
     this.closed = false;
 
-    // Default routes
     this.routes = {
-      api_routes: [...ADMIN_ROUTES, ...CHECKPOINT_ROUTES, ...SYNC_RULES_ROUTES, ...PROBES_ROUTES],
-      stream_routes: [...SYNC_STREAM_ROUTES],
-      socket_routes: [syncStreamReactive]
+      api_routes: [],
+      stream_routes: [],
+      socket_routes: []
     };
   }
 
+  public registerRoutes(routes: Partial<RouterEngineRoutes>) {
+    this.routes.api_routes.push(...(routes.api_routes ?? []));
+    this.routes.stream_routes.push(...(routes.stream_routes ?? []));
+    this.routes.socket_routes.push(...(routes.socket_routes ?? []));
+  }
+
+  public get hasRoutes() {
+    return (
+      this.routes.api_routes.length > 0 || this.routes.stream_routes.length > 0 || this.routes.socket_routes.length > 0
+    );
+  }
+
   public registerAPI(api: api.RouteAPI) {
     if (this.api) {
       logger.warn('A RouteAPI has already been registered. Overriding existing implementation');
@@ -75,6 +79,12 @@ export class RouterEngine {
    */
   async start(setup: RouterSetup) {
     logger.info('Starting Router Engine...');
+
+    if (!this.hasRoutes) {
+      logger.info('Router Engine will not start an HTTP server as no routes have been registered.');
+      return;
+    }
+
     const { onShutdown } = await setup(this.routes);
     this.cleanupHandler = onShutdown;
     logger.info('Successfully started Router Engine.');

package/src/routes/auth.ts

@@ -4,6 +4,7 @@ import * as auth from '../auth/auth-index.js';
 import { ServiceContext } from '../system/ServiceContext.js';
 import * as util from '../util/util-index.js';
 import { BasicRouterRequest, Context, RequestEndpointHandlerPayload } from './router.js';
+import { AuthorizationError, AuthorizationResponse, ErrorCode, ServiceError } from '@powersync/lib-services-framework';
 
 export function endpoint(req: BasicRouterRequest) {
   const protocol = req.headers['x-forwarded-proto'] ?? req.protocol;
@@ -95,25 +96,25 @@ export function getTokenFromHeader(authHeader: string = ''): string | null {
   return token ?? null;
 }
 
-export const authUser = async (payload: RequestEndpointHandlerPayload) => {
+export const authUser = async (payload: RequestEndpointHandlerPayload): Promise<AuthorizationResponse> => {
   return authorizeUser(payload.context, payload.request.headers.authorization as string);
 };
 
-export async function authorizeUser(context: Context, authHeader: string = '') {
+export async function authorizeUser(context: Context, authHeader: string = ''): Promise<AuthorizationResponse> {
   const token = getTokenFromHeader(authHeader);
   if (token == null) {
     return {
       authorized: false,
-      errors: ['Authentication required']
+      error: new AuthorizationError(ErrorCode.PSYNC_S2106, 'Authentication required')
     };
   }
 
-  const { context: tokenContext, errors } = await generateContext(context.service_context, token);
+  const { context: tokenContext, tokenError } = await generateContext(context.service_context, token);
 
   if (!tokenContext) {
     return {
       authorized: false,
-      errors
+      error: tokenError
     };
   }
 
@@ -140,7 +141,7 @@ export async function generateContext(serviceContext: ServiceContext, token: str
   } catch (err) {
     return {
       context: null,
-      errors: [err.message]
+      tokenError: auth.mapAuthError(err, token)
     };
   }
 }

package/src/routes/configure-fastify.ts

@@ -1,4 +1,6 @@
 import type fastify from 'fastify';
+import * as uuid from 'uuid';
+
 import { registerFastifyRoutes } from './route-register.js';
 
 import * as system from '../system/system-index.js';
@@ -9,7 +11,7 @@ import { PROBES_ROUTES } from './endpoints/probes.js';
 import { SYNC_RULES_ROUTES } from './endpoints/sync-rules.js';
 import { SYNC_STREAM_ROUTES } from './endpoints/sync-stream.js';
 import { createRequestQueueHook, CreateRequestQueueParams } from './hooks.js';
-import { RouteDefinition, RouterServiceContext } from './router.js';
+import { ContextProvider, RouteDefinition } from './router.js';
 
 /**
  * A list of route definitions to be registered as endpoints.
@@ -58,15 +60,11 @@ export const DEFAULT_ROUTE_OPTIONS = {
 export function configureFastifyServer(server: fastify.FastifyInstance, options: FastifyServerConfig) {
   const { service_context, routes = DEFAULT_ROUTE_OPTIONS } = options;
 
-  const generateContext = async () => {
-    const { routerEngine } = service_context;
-    if (!routerEngine) {
-      throw new Error(`RouterEngine has not been registered`);
-    }
-
+  const generateContext: ContextProvider = async (request, options) => {
     return {
       user_id: undefined,
-      service_context: service_context as RouterServiceContext
+      service_context: service_context,
+      logger: options.logger
     };
   };