@powersync/service-core 1.11.3 → 1.12.0

package/dist/util/config/collectors/impl/yaml-env.js

@@ -0,0 +1,59 @@
+/**
+ * Environment variables can be substituted into the YAML config
+ * when parsing if the environment variable name starts with this prefix.
+ * Attempting to substitute any other environment variable will throw an exception.
+ *
+ * Example of substitution:
+ * storage:
+ *    type: mongodb
+ *    uri: !env PS_MONGO_URI
+ */
+const YAML_ENV_PREFIX = 'PS_';
+/**
+ * Custom YAML tag which performs string environment variable substitution
+ * Allows for type casting string environment variables to boolean or number
+ * by using the syntax !env PS_MONGO_PORT::number or !env PS_USE_SUPABASE::boolean
+ */
+export const YamlEnvTag = {
+    tag: '!env',
+    resolve(envName, onError) {
+        if (!envName.startsWith(YAML_ENV_PREFIX)) {
+            onError(`Attempting to substitute environment variable ${envName} is not allowed. Variables must start with "${YAML_ENV_PREFIX}"`);
+            return envName;
+        }
+        // allow type casting if the envName contains a type suffix
+        // e.g. PS_MONGO_PORT::number or PS_USE_SUPABASE::boolean
+        const [name, type = 'string'] = envName.split('::');
+        let value = process.env[name];
+        if (typeof value == 'undefined') {
+            onError(`Attempted to substitute environment variable "${envName}" which is undefined. Set this variable on the environment.`);
+            return envName;
+        }
+        switch (type) {
+            case 'string':
+                return value;
+            case 'number':
+                const numberValue = Number(value);
+                if (Number.isNaN(numberValue)) {
+                    onError(`Environment variable "${envName}" is not a valid number. Got: "${value}".`);
+                    return envName;
+                }
+                return numberValue;
+            case 'boolean':
+                if (value?.toLowerCase() == 'true') {
+                    return true;
+                }
+                else if (value?.toLowerCase() == 'false') {
+                    return false;
+                }
+                else {
+                    onError(`Environment variable "${envName}" is not a boolean. Expected "true" or "false", got "${value}".`);
+                    return envName;
+                }
+            default:
+                onError(`Environment variable "${envName}" has an invalid type suffix "${type}".`);
+                return envName;
+        }
+    }
+};
+//# sourceMappingURL=yaml-env.js.map

package/dist/util/config/collectors/impl/yaml-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-env.js","sourceRoot":"","sources":["../../../../../src/util/config/collectors/impl/yaml-env.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,eAAe,GAAG,KAAK,CAAC;AAE9B;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAmB;IACxC,GAAG,EAAE,MAAM;IACX,OAAO,CAAC,OAAe,EAAE,OAAgC;QACvD,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,eAAe,CAAC,EAAE,CAAC;YACzC,OAAO,CACL,iDAAiD,OAAO,+CAA+C,eAAe,GAAG,CAC1H,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,2DAA2D;QAC3D,yDAAyD;QACzD,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAEpD,IAAI,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAE9B,IAAI,OAAO,KAAK,IAAI,WAAW,EAAE,CAAC;YAChC,OAAO,CACL,iDAAiD,OAAO,6DAA6D,CACtH,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,QAAQ,IAAI,EAAE,CAAC;YACb,KAAK,QAAQ;gBACX,OAAO,KAAK,CAAC;YACf,KAAK,QAAQ;gBACX,MAAM,WAAW,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;gBAClC,IAAI,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,CAAC;oBAC9B,OAAO,CAAC,yBAAyB,OAAO,kCAAkC,KAAK,IAAI,CAAC,CAAC;oBACrF,OAAO,OAAO,CAAC;gBACjB,CAAC;gBACD,OAAO,WAAW,CAAC;YACrB,KAAK,SAAS;gBACZ,IAAI,KAAK,EAAE,WAAW,EAAE,IAAI,MAAM,EAAE,CAAC;oBACnC,OAAO,IAAI,CAAC;gBACd,CAAC;qBAAM,IAAI,KAAK,EAAE,WAAW,EAAE,IAAI,OAAO,EAAE,CAAC;oBAC3C,OAAO,KAAK,CAAC;gBACf,CAAC;qBAAM,CAAC;oBACN,OAAO,CAAC,yBAAyB,OAAO,wDAAwD,KAAK,IAAI,CAAC,CAAC;oBAC3G,OAAO,OAAO,CAAC;gBACjB,CAAC;YACH;gBACE,OAAO,CAAC,yBAAyB,OAAO,iCAAiC,IAAI,IAAI,CAAC,CAAC;gBACnF,OAAO,OAAO,CAAC;QACnB,CAAC;IACH,CAAC;CACF,CAAC"}

package/dist/util/config/compound-config-collector.js

@@ -3,10 +3,10 @@ import * as auth from '../../auth/auth-index.js';
 import { Base64ConfigCollector } from './collectors/impl/base64-config-collector.js';
 import { FallbackConfigCollector } from './collectors/impl/fallback-config-collector.js';
 import { FileSystemConfigCollector } from './collectors/impl/filesystem-config-collector.js';
+import { DEFAULT_MAX_BUCKETS_PER_CONNECTION, DEFAULT_MAX_CONCURRENT_CONNECTIONS, DEFAULT_MAX_DATA_FETCH_CONCURRENCY, DEFAULT_MAX_PARAMETER_QUERY_RESULTS, DEFAULT_MAX_POOL_SIZE } from './defaults.js';
 import { Base64SyncRulesCollector } from './sync-rules/impl/base64-sync-rules-collector.js';
 import { FileSystemSyncRulesCollector } from './sync-rules/impl/filesystem-sync-rules-collector.js';
 import { InlineSyncRulesCollector } from './sync-rules/impl/inline-sync-rules-collector.js';
-import { DEFAULT_MAX_BUCKETS_PER_CONNECTION, DEFAULT_MAX_CONCURRENT_CONNECTIONS, DEFAULT_MAX_DATA_FETCH_CONCURRENCY, DEFAULT_MAX_PARAMETER_QUERY_RESULTS, DEFAULT_MAX_POOL_SIZE } from './defaults.js';
 const POWERSYNC_DEV_KID = 'powersync-dev';
 const DEFAULT_COLLECTOR_OPTIONS = {
     configCollectors: [new Base64ConfigCollector(), new FileSystemConfigCollector(), new FallbackConfigCollector()],
@@ -107,6 +107,23 @@ export class CompoundConfigCollector {
                 disable_telemetry_sharing: baseConfig.telemetry?.disable_telemetry_sharing ?? false,
                 internal_service_endpoint: baseConfig.telemetry?.internal_service_endpoint ?? 'https://pulse.journeyapps.com/v1/metrics'
             },
+            healthcheck: {
+                /**
+                 * Default to legacy mode if no probes config is provided.
+                 * If users provide a config, all options require explicit opt-in.
+                 */
+                probes: baseConfig.healthcheck?.probes
+                    ? {
+                        use_filesystem: baseConfig.healthcheck.probes.use_filesystem ?? false,
+                        use_http: baseConfig.healthcheck.probes.use_http ?? false,
+                        use_legacy: baseConfig.healthcheck.probes.use_legacy ?? false
+                    }
+                    : {
+                        use_filesystem: false,
+                        use_http: false,
+                        use_legacy: true
+                    }
+            },
             api_parameters: {
                 max_buckets_per_connection: baseConfig.api?.parameters?.max_buckets_per_connection ?? DEFAULT_MAX_BUCKETS_PER_CONNECTION,
                 max_parameter_query_results: baseConfig.api?.parameters?.max_parameter_query_results ?? DEFAULT_MAX_PARAMETER_QUERY_RESULTS,

package/dist/util/config/compound-config-collector.js.map

@@ -1 +1 @@
-{"version":3,"file":"compound-config-collector.js","sourceRoot":"","sources":["../../../src/util/config/compound-config-collector.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"compound-config-collector.js","sourceRoot":"","sources":["../../../src/util/config/compound-config-collector.ts"],"names":[],"mappings":"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"}

package/dist/util/config/types.d.ts

@@ -60,5 +60,16 @@ export type ResolvedPowerSyncConfig = {
     };
     /** Prefix for postgres replication slot names. May eventually be connection-specific. */
     slot_name_prefix: string;
+    healthcheck: {
+        probes: {
+            use_filesystem: boolean;
+            use_http: boolean;
+            /**
+             * @deprecated This maintains backwards compatibility with the legacy default.
+             * Explicit probe configuration should be used instead.
+             */
+            use_legacy: boolean;
+        };
+    };
     parameters: Record<string, number | string | boolean | null>;
 };

package/package.json

@@ -5,7 +5,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.11.3",
+  "version": "1.12.0",
   "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.26.1",
+    "@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/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);