@powersync/service-core 0.0.0-dev-20240620165206

package/src/auth/KeyStore.ts

@@ -0,0 +1,156 @@
+import * as jose from 'jose';
+import secs from '../util/secs.js';
+import { KeyOptions, KeySpec, SUPPORTED_ALGORITHMS } from './KeySpec.js';
+import { KeyCollector } from './KeyCollector.js';
+import { JwtPayload } from './JwtPayload.js';
+import { logger } from '@powersync/lib-services-framework';
+
+/**
+ * KeyStore to get keys and verify tokens.
+ *
+ *
+ * Similar to micro_auth's KeyStore, but with different caching and error handling.
+ *
+ * We generally assume that:
+ * 1. If we have a key kid matching a JWT kid, that is the correct key.
+ *    We don't look for other keys, even if there are algorithm or other issues.
+ * 2. Otherwise, iterate through "wildcard" keys and look for a matching signature.
+ *    Wildcard keys are any key defined without a kid.
+ *
+ * # Security considerations
+ *
+ * Some places for security holes:
+ * 1. Signature verification not done correctly: We rely on jose.jwtVerify() to do this correctly.
+ * 2. Using a key that has been revoked - see CachedKeyCollector's refresh strategy.
+ * 3. Using a key for the wrong purpose (e.g. key.use != 'sig'). Checked in RemoteJWKSCollector.
+ * 4. Not checking all attributes, e.g. a JWT trusted by the global firebase key, but has the wrong aud. Correct aud must be configured.
+ * 5. Using the incorrect algorithm, e.g. 'none', or using public key as a shared key.
+ *    We check the algorithm for each JWT against the matching key's configured algorithm or algorithm family.
+ *
+ * # Errors
+ *
+ * If we have a matching kid, we can generally get a detailed error (e.g. signature verification failed, invalid algorithm, etc).
+ * If we don't have a matching kid, we'll generally just get an error "Could not find an appropriate key...".
+ */
+export class KeyStore {
+  private collector: KeyCollector;
+
+  constructor(collector: KeyCollector) {
+    this.collector = collector;
+  }
+
+  async verifyJwt(token: string, options: { defaultAudiences: string[]; maxAge: string }): Promise<JwtPayload> {
+    const { result, keyOptions } = await this.verifyInternal(token, {
+      // audience is not checked here, since we vary the allowed audience based on the key
+      // audience: options.defaultAudiences,
+      clockTolerance: 60,
+      // More specific algorithm checking is done when selecting the key to use.
+      algorithms: SUPPORTED_ALGORITHMS,
+      requiredClaims: ['aud', 'sub', 'iat', 'exp']
+    });
+
+    let audiences = options.defaultAudiences;
+    if (keyOptions.requiresAudience) {
+      // Replace the audience, don't add
+      audiences = keyOptions.requiresAudience;
+    }
+
+    const tokenPayload = result.payload;
+
+    let aud = tokenPayload.aud!;
+    if (!Array.isArray(aud)) {
+      aud = [aud];
+    }
+    if (
+      !aud.some((a) => {
+        return audiences.includes(a);
+      })
+    ) {
+      throw new jose.errors.JWTClaimValidationFailed('unexpected "aud" claim value', 'aud', 'check_failed');
+    }
+
+    const tokenDuration = tokenPayload.exp! - tokenPayload.iat!;
+
+    // Implement our own maxAge validation, that rejects the token immediately if expiration
+    // 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}`);
+    }
+
+    const parameters = tokenPayload.parameters;
+    if (parameters != null && (Array.isArray(parameters) || typeof parameters != 'object')) {
+      throw new jose.errors.JWTInvalid('parameters must be an object');
+    }
+
+    return {
+      ...(tokenPayload as any),
+      parameters: {
+        user_id: tokenPayload.sub,
+        ...parameters
+      }
+    };
+  }
+
+  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! };
+  }
+
+  private async getCachedKey(token: string, header: jose.JWTHeaderParameters): Promise<KeySpec> {
+    const kid = header.kid;
+    const { keys, errors } = await this.collector.getKeys();
+    if (kid) {
+      // key has kid: JWK with exact kid, or JWK without kid
+      // key without kid: JWK without kid only
+      for (let key of keys) {
+        if (key.kid == kid) {
+          if (!key.matchesAlgorithm(header.alg)) {
+            throw new jose.errors.JOSEAlgNotAllowed(`Unexpected token algorithm ${header.alg}`);
+          }
+          return key;
+        }
+      }
+    }
+
+    for (let key of keys) {
+      // Checks signature and algorithm
+      if (key.kid != null) {
+        // Not a wildcard key
+        continue;
+      }
+      if (!key.matchesAlgorithm(header.alg)) {
+        continue;
+      }
+
+      if (await key.isValidSignature(token)) {
+        return key;
+      }
+    }
+
+    if (errors.length > 0) {
+      throw errors[0];
+    } else {
+      // No key found
+      // Trigger refresh of the keys - might be ready by the next request.
+      this.collector.noKeyFound?.().catch((e) => {
+        // Typically this error would be stored on the collector.
+        // This is just a last resort error handling.
+        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'
+      );
+    }
+  }
+}

package/src/auth/LeakyBucket.ts

@@ -0,0 +1,66 @@
+/**
+ * Variation on a leaky bucket rate limiter.
+ *
+ * The base is a leaky bucket:
+ *  * The bucket is filled at a certain rate
+ *  * The bucket has a max capacity
+ *
+ * This gives an initial burst capacity, then continues
+ * at the refill rate when the burst capacity is depleted.
+ *
+ * This variation introduces an additional quadratic delay
+ * during the initial burst, which prevents the burst capacity
+ * from being consumed immediately. The steady-state rate
+ * is still the same.
+ *
+ *
+ * Steady state rate: x requests / ms.
+ * Steady state period: 1 / rate
+ *
+ * capacity: number of requests before steady state
+ *
+ * capacity == max_capacity: no delay between requests
+ * capacity = 0: delay = Steady state period
+ *
+ * variable_delay = (max_capacity - capacity)^2 / max_capacity^2 * period
+ */
+export class LeakyBucket {
+  private capacity: number;
+  private lastRequest: number;
+  private maxCapacity: number;
+  private periodMs: number;
+
+  public lastGrantedRequest: number;
+
+  constructor(options: { maxCapacity: number; periodMs: number }) {
+    this.capacity = options.maxCapacity;
+    this.maxCapacity = options.maxCapacity;
+    this.periodMs = options.periodMs;
+    this.lastRequest = 0;
+    this.lastGrantedRequest = 0;
+  }
+
+  allowed(): boolean {
+    const now = Date.now();
+    const elapsed = now - this.lastRequest;
+    const leaked = elapsed / this.periodMs;
+    this.capacity = Math.min(this.capacity + leaked, this.maxCapacity);
+    this.lastRequest = now;
+
+    const capacityUsed = this.maxCapacity - this.capacity;
+    const variableDelay = ((capacityUsed * capacityUsed) / (this.maxCapacity * this.maxCapacity)) * this.periodMs;
+
+    if (this.capacity >= 1 && variableDelay <= now - this.lastGrantedRequest) {
+      this.capacity -= 1;
+      this.lastGrantedRequest = now;
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  reset() {
+    this.capacity = this.maxCapacity;
+    this.lastGrantedRequest = 0;
+  }
+}

package/src/auth/RemoteJWKSCollector.ts

@@ -0,0 +1,130 @@
+import * as https from 'https';
+import * as http from 'http';
+import * as dns from 'dns/promises';
+import ip from 'ipaddr.js';
+import * as jose from 'jose';
+import * as net from 'net';
+import fetch from 'node-fetch';
+
+import { KeySpec } from './KeySpec.js';
+import { KeyCollector, KeyResult } from './KeyCollector.js';
+
+export type RemoteJWKSCollectorOptions = {
+  /**
+   * Blocks IP Ranges from the BLOCKED_IP_RANGES array
+   */
+  block_local_ip?: boolean;
+};
+
+/**
+ * Set of keys fetched from JWKS URI.
+ */
+export class RemoteJWKSCollector implements KeyCollector {
+  private url: URL;
+
+  constructor(url: string, protected options?: RemoteJWKSCollectorOptions) {
+    try {
+      this.url = new URL(url);
+    } catch (e) {
+      throw new Error(`Invalid jwks_uri: ${url}`);
+    }
+
+    // We do support http here for self-hosting use cases.
+    // Management service restricts this to https for hosted versions.
+    if (this.url.protocol != 'https:' && this.url.protocol != 'http:') {
+      throw new Error(`Only http(s) is supported for jwks_uri, got: ${url}`);
+    }
+  }
+
+  async getKeys(): Promise<KeyResult> {
+    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: await this.resolveAgent()
+    });
+
+    if (!res.ok) {
+      throw new jose.errors.JWKSInvalid(`JWKS request failed with ${res.statusText}`);
+    }
+
+    const data = (await res.json()) as any;
+
+    clearTimeout(timeout);
+
+    // https://github.com/panva/jose/blob/358e864a0cccf1e0f9928a959f91f18f3f06a7de/src/jwks/local.ts#L36
+    if (
+      data.keys == null ||
+      !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`)] };
+    }
+
+    let keys: KeySpec[] = [];
+    for (let keyData of data.keys) {
+      if (keyData.kty != 'RSA') {
+        // Only RSA public keys supported here
+        continue;
+      }
+
+      if (typeof keyData.use == 'string') {
+        if (keyData.use != 'sig') {
+          continue;
+        }
+      }
+      if (Array.isArray(keyData.key_ops)) {
+        if (!keyData.key_ops.includes('verify')) {
+          continue;
+        }
+      }
+
+      const key = await KeySpec.importKey(keyData);
+      keys.push(key);
+    }
+
+    return { keys: keys, errors: [] };
+  }
+
+  /**
+   * Resolve IP, and check that it is in an allowed range.
+   */
+  async resolveAgent(): Promise<http.Agent | https.Agent> {
+    const hostname = this.url.hostname;
+    let resolved_ip: string;
+    if (net.isIPv6(hostname)) {
+      throw new Error('IPv6 not supported yet');
+    } else if (net.isIPv4(hostname)) {
+      // All good
+      resolved_ip = hostname;
+    } else {
+      resolved_ip = (await dns.resolve4(hostname))[0];
+    }
+
+    const parsed = ip.parse(resolved_ip);
+    if (parsed.kind() != 'ipv4' || (this.options?.block_local_ip && parsed.range() !== 'unicast')) {
+      // Do not connect to any reserved IPs, including loopback and private ranges
+      throw new Error(`IPs in this range are not supported: ${resolved_ip}`);
+    }
+
+    const options = {
+      // This is the host that the agent connects to
+      host: resolved_ip
+    };
+
+    switch (this.url.protocol) {
+      case 'http:':
+        return new http.Agent(options);
+      case 'https:':
+        return new https.Agent(options);
+    }
+    throw new Error('http or or https is required for protocol');
+  }
+}

package/src/auth/StaticKeyCollector.ts

@@ -0,0 +1,21 @@
+import * as jose from 'jose';
+import { KeySpec } from './KeySpec.js';
+import { KeyCollector, KeyResult } from './KeyCollector.js';
+
+/**
+ * Set of static keys.
+ *
+ * A key can be added both with and without a kid, in case wildcard matching is desired.
+ */
+export class StaticKeyCollector implements KeyCollector {
+  static async importKeys(keys: jose.JWK[]) {
+    const parsedKeys = await Promise.all(keys.map((key) => KeySpec.importKey(key)));
+    return new StaticKeyCollector(parsedKeys);
+  }
+
+  constructor(private keys: KeySpec[]) {}
+
+  async getKeys(): Promise<KeyResult> {
+    return { keys: this.keys, errors: [] };
+  }
+}

package/src/auth/SupabaseKeyCollector.ts

@@ -0,0 +1,67 @@
+import * as jose from 'jose';
+import * as pgwire from '@powersync/service-jpgwire';
+import { connectPgWirePool, pgwireRows } from '@powersync/service-jpgwire';
+import { KeyCollector } from './KeyCollector.js';
+import { KeyOptions, KeySpec } from './KeySpec.js';
+import { retriedQuery } from '../util/pgwire_utils.js';
+import { ResolvedConnection } from '../util/config/types.js';
+
+/**
+ * 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.
+ */
+export class SupabaseKeyCollector implements KeyCollector {
+  private pool: pgwire.PgClient;
+
+  private keyOptions: KeyOptions = {
+    requiresAudience: ['authenticated'],
+    maxLifetimeSeconds: 86400 * 7 + 1200 // 1 week + 20 minutes margin
+  };
+
+  constructor(connection: ResolvedConnection) {
+    this.pool = connectPgWirePool(connection, {
+      // To avoid overloading the source database with open connections,
+      // limit to a single connection, and close the connection shortly
+      // after using it.
+      idleTimeout: 5_000,
+      maxSize: 1
+    });
+  }
+
+  async getKeys() {
+    let row: { jwt_secret: string };
+    try {
+      const rows = pgwireRows(
+        await retriedQuery(this.pool, `SELECT current_setting('app.settings.jwt_secret') as jwt_secret`)
+      );
+      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}`);
+      } else {
+        throw e;
+      }
+    }
+    const secret = row?.jwt_secret as string | undefined;
+    if (secret == null) {
+      return {
+        keys: [],
+        errors: [new jose.errors.JWKSNoMatchingKey()]
+      };
+    } else {
+      const key: jose.JWK = {
+        kty: 'oct',
+        alg: 'HS256',
+        // While the secret is valid base64, the base64-encoded form is the secret value.
+        k: Buffer.from(secret, 'utf8').toString('base64url')
+      };
+      const imported = await KeySpec.importKey(key, this.keyOptions);
+      return {
+        keys: [imported],
+        errors: []
+      };
+    }
+  }
+}

package/src/auth/auth-index.ts

@@ -0,0 +1,10 @@
+export * from './CachedKeyCollector.js';
+export * from './CompoundKeyCollector.js';
+export * from './JwtPayload.js';
+export * from './KeyCollector.js';
+export * from './KeySpec.js';
+export * from './KeyStore.js';
+export * from './LeakyBucket.js';
+export * from './RemoteJWKSCollector.js';
+export * from './StaticKeyCollector.js';
+export * from './SupabaseKeyCollector.js';

package/src/db/db-index.ts

@@ -0,0 +1 @@
+export * as mongo from './mongo.js';

package/src/db/mongo.ts

@@ -0,0 +1,72 @@
+import * as mongo from 'mongodb';
+import * as timers from 'timers/promises';
+
+import { configFile } from '@powersync/service-types';
+
+/**
+ * Time for new connection to timeout.
+ */
+export const MONGO_CONNECT_TIMEOUT_MS = 10_000;
+
+/**
+ * Time for individual requests to timeout the socket.
+ */
+export const MONGO_SOCKET_TIMEOUT_MS = 60_000;
+
+/**
+ * Time for individual requests to timeout the operation.
+ *
+ * This is time spent on the cursor, not total time.
+ *
+ * Must be less than MONGO_SOCKET_TIMEOUT_MS to ensure proper error handling.
+ */
+export const MONGO_OPERATION_TIMEOUT_MS = 30_000;
+
+export function createMongoClient(config: configFile.PowerSyncConfig['storage']) {
+  return new mongo.MongoClient(config.uri, {
+    auth: {
+      username: config.username,
+      password: config.password
+    },
+    // Time for connection to timeout
+    connectTimeoutMS: MONGO_CONNECT_TIMEOUT_MS,
+    // Time for individual requests to timeout
+    socketTimeoutMS: MONGO_SOCKET_TIMEOUT_MS,
+    // How long to wait for new primary selection
+    serverSelectionTimeoutMS: 30_000,
+
+    // Avoid too many connections:
+    // 1. It can overwhelm the source database.
+    // 2. Processing too many queries in parallel can cause the process to run out of memory.
+    maxPoolSize: 8,
+
+    maxConnecting: 3,
+    maxIdleTimeMS: 60_000
+  });
+}
+
+/**
+ * Wait up to a minute for authentication errors to resolve.
+ *
+ * There can be a delay between an Atlas user being created, and that user being
+ * available on the database cluster. This works around it.
+ *
+ * This is specifically relevant for migrations and teardown - other parts of the stack
+ * can generate handle these failures and just retry or restart.
+ */
+export async function waitForAuth(db: mongo.Db) {
+  const start = Date.now();
+  while (Date.now() - start < 60_000) {
+    try {
+      await db.command({ ping: 1 });
+      // Success
+      break;
+    } catch (e) {
+      if (e.codeName == 'AuthenticationFailed') {
+        await timers.setTimeout(1_000);
+        continue;
+      }
+      throw e;
+    }
+  }
+}

package/src/entry/cli-entry.ts

@@ -0,0 +1,40 @@
+import { Command } from 'commander';
+
+import * as utils from '../util/util-index.js';
+import { registerMigrationAction } from './commands/migrate-action.js';
+import { registerTearDownAction } from './commands/teardown-action.js';
+import { registerStartAction } from './entry-index.js';
+import { logger } from '@powersync/lib-services-framework';
+
+/**
+ * Generates a Commander program which serves as the entry point
+ * for the PowerSync service.
+ * This registers standard actions for teardown and migrations.
+ * Optionally registers the start command handlers.
+ */
+export function generateEntryProgram(startHandlers?: Record<utils.ServiceRunner, utils.Runner>) {
+  const entryProgram = new Command();
+  entryProgram.name('powersync-runner').description('CLI to initiate a PowerSync service runner');
+
+  registerTearDownAction(entryProgram);
+  registerMigrationAction(entryProgram);
+
+  if (startHandlers) {
+    registerStartAction(entryProgram, startHandlers);
+  }
+
+  return {
+    program: entryProgram,
+    /**
+     * Executes the main program. Ends the NodeJS process if an exception was caught.
+     */
+    execute: async function runProgram() {
+      try {
+        await entryProgram.parseAsync();
+      } catch (e) {
+        logger.error('Fatal error', e);
+        process.exit(1);
+      }
+    }
+  };
+}

package/src/entry/commands/config-command.ts

@@ -0,0 +1,36 @@
+import { Command } from 'commander';
+
+import * as util from '../../util/util-index.js';
+
+/**
+ * Wraps a Command with the standard config options
+ */
+export function wrapConfigCommand(command: Command) {
+  return command
+    .option(
+      `-c, --config-path [path]`,
+      'Path (inside container) to YAML config file. Defaults to process.env.POWERSYNC_CONFIG_PATH',
+      util.env.POWERSYNC_CONFIG_PATH
+    )
+    .option(
+      `-c64, --config-base64 [base64]`,
+      'Base64 encoded YAML or JSON config file. Defaults to process.env.POWERSYNC_CONFIG_B64',
+      util.env.POWERSYNC_CONFIG_B64
+    )
+    .option(
+      `-sync64, --sync-base64 [base64]`,
+      'Base64 encoded YAML Sync Rules. Defaults to process.env.POWERSYNC_SYNC_RULES_B64',
+      util.env.POWERSYNC_SYNC_RULES_B64
+    );
+}
+
+/**
+ * Extracts runner configuration params from Command options.
+ */
+export function extractRunnerOptions(options: any): util.RunnerConfig {
+  return {
+    config_path: options.configPath,
+    config_base64: options.configBase64,
+    sync_rules_base64: options.syncBase64
+  };
+}

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

@@ -0,0 +1,25 @@
+import { Command } from 'commander';
+
+import { extractRunnerOptions, wrapConfigCommand } from './config-command.js';
+import { migrate } from '../../migrations/migrations.js';
+import { Direction } from '../../migrations/definitions.js';
+
+const COMMAND_NAME = 'migrate';
+
+export function registerMigrationAction(program: Command) {
+  const migrationCommand = program.command(COMMAND_NAME);
+
+  wrapConfigCommand(migrationCommand);
+
+  return migrationCommand
+    .description('Run migrations')
+    .argument('<direction>', 'Migration direction. `up` or `down`')
+    .action(async (direction: Direction, options) => {
+      const runnerConfig = extractRunnerOptions(options);
+
+      await migrate({
+        direction,
+        runner_config: runnerConfig
+      });
+    });
+}

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

@@ -0,0 +1,24 @@
+import { Command } from 'commander';
+
+import * as utils from '../../util/util-index.js';
+import { extractRunnerOptions, wrapConfigCommand } from './config-command.js';
+
+const COMMAND_NAME = 'start';
+
+export function registerStartAction(program: Command, handlers: Record<utils.ServiceRunner, utils.Runner>) {
+  const startCommand = program.command(COMMAND_NAME);
+
+  wrapConfigCommand(startCommand);
+
+  return startCommand
+    .description('Starts a PowerSync service runner.')
+    .option(
+      `-r, --runner-type [${Object.values(utils.ServiceRunner).join('|')}]`,
+      'Type of runner to start. Defaults to unified runner.',
+      utils.env.PS_RUNNER_TYPE
+    )
+    .action(async (options) => {
+      const runner = handlers[options.runnerType as utils.ServiceRunner];
+      await runner(extractRunnerOptions(options));
+    });
+}

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

@@ -0,0 +1,23 @@
+import { Command } from 'commander';
+
+import { extractRunnerOptions, wrapConfigCommand } from './config-command.js';
+import { teardown } from '../../runner/teardown.js';
+
+const COMMAND_NAME = 'teardown';
+
+export function registerTearDownAction(program: Command) {
+  const teardownCommand = program.command(COMMAND_NAME);
+
+  wrapConfigCommand(teardownCommand);
+
+  return teardownCommand
+    .argument('[ack]', 'Type `TEARDOWN` to confirm teardown should occur')
+    .description('Terminate all replicating sync rules, deleting the replication slots')
+    .action(async (ack, options) => {
+      if (ack !== 'TEARDOWN') {
+        throw new Error('TEARDOWN was not acknowledged.');
+      }
+
+      await teardown(extractRunnerOptions(options));
+    });
+}

package/src/entry/entry-index.ts

@@ -0,0 +1,5 @@
+export * from './cli-entry.js';
+export * from './commands/config-command.js';
+export * from './commands/migrate-action.js';
+export * from './commands/start-action.js';
+export * from './commands/teardown-action.js';