@digitalpaws/starr 0.0.1

package/src/auth/rate-limiter.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { FastifyRequest, FastifyReply } from "fastify";
+
+interface RateLimitEntry {
+  count: number;
+  windowStart: number; // Unix milliseconds
+}
+
+export class RateLimiter {
+  private map = new Map<string, RateLimitEntry>();
+  private maxAttempts: number;
+  private windowMs: number;
+
+  constructor(maxAttempts = 4, windowMinutes = 15) {
+    this.maxAttempts = maxAttempts;
+    this.windowMs = windowMinutes * 60_000;
+  }
+
+  /**
+   * Record a failed attempt for the given key (typically IP).
+   * Returns true if the attempt is allowed, false if rate-limited.
+   */
+  check(key: string): boolean {
+    const now = Date.now();
+    const entry = this.map.get(key);
+
+    if (!entry || now - entry.windowStart > this.windowMs) {
+      // New window
+      this.map.set(key, { count: 1, windowStart: now });
+      return true;
+    }
+
+    entry.count++;
+    if (entry.count > this.maxAttempts) {
+      return false; // rate-limited
+    }
+    return true;
+  }
+
+  /**
+   * Reset the rate limit for a key (called on successful login).
+   */
+  reset(key: string): void {
+    this.map.delete(key);
+  }
+
+  /**
+   * How many seconds until the window resets for a key.
+   * Used to inform the client.
+   */
+  retryAfterSeconds(key: string): number {
+    const entry = this.map.get(key);
+    if (!entry) return 0;
+    const elapsed = Date.now() - entry.windowStart;
+    return Math.max(0, Math.ceil((this.windowMs - elapsed) / 1000));
+  }
+}
+
+// ── Fastify preHandler wrapper ────────────────────────────────
+
+/**
+ * Return a Fastify preHandler hook that rate-limits by IP.
+ * Usage:
+ *   server.post("/api/auth/login", { preHandler: rateLimit(5, 60) }, handler)
+ *
+ * @param maxAttempts  Maximum attempts allowed in the window.
+ * @param windowMinutes  Time window in minutes.
+ */
+export function rateLimit(maxAttempts: number, windowMinutes: number) {
+  const limiter = new RateLimiter(maxAttempts, windowMinutes);
+
+  return async (request: FastifyRequest, reply: FastifyReply) => {
+    const key = request.ip;
+    const allowed = limiter.check(key);
+    if (!allowed) {
+      reply
+        .status(429)
+        .header("Retry-After", String(limiter.retryAfterSeconds(key)))
+        .send({ error: "Too many requests. Please try again later." });
+      return;
+    }
+  };
+}

package/src/config/config-service.ts

@@ -0,0 +1,434 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type Database from "better-sqlite3";
+import type { ConfigSchema, ConfigField, Logger } from "../types/plugin.js";
+import { validateConfig, type ValidationResult } from "./validate.js";
+import { encrypt, decrypt } from "../datastore/encrypt.js";
+
+/**
+ * Sentinel value used to mask secret fields in UI-exported data.
+ * When update() receives this value for a secret field, it preserves
+ * the existing encrypted value rather than overwriting it.
+ */
+export const SECRET_UNCHANGED_SENTINEL = "__STARR_SECRET_UNCHANGED__";
+
+export interface PluginConfigEntry {
+  schema: ConfigSchema<any>;
+  values: Record<string, unknown>;
+  needsConfiguration: boolean;
+  updatedAt: string;
+}
+
+export interface PluginConfigSummary {
+  pluginId: string;
+  instanceId?: string;
+  needsConfiguration: boolean;
+  updatedAt: string;
+  /** The connected library ID, if any (for downloader instances). */
+  libraryId?: string;
+}
+
+export class ConfigService {
+  private db: Database.Database;
+  private logger: Logger;
+  private onReload?: (pluginId: string) => void;
+
+  // Prepared statements
+  private getStmt: Database.Statement;
+  private getByInstanceStmt: Database.Statement;
+  private upsertStmt: Database.Statement;
+  private listStmt: Database.Statement;
+  private listInstancesStmt: Database.Statement;
+  private deleteInstanceStmt: Database.Statement;
+
+  constructor(
+    db: Database.Database,
+    logger: Logger,
+    onReload?: (pluginId: string) => void,
+  ) {
+    this.db = db;
+    this.logger = logger;
+    this.onReload = onReload;
+
+    this.getStmt = db.prepare(
+      'SELECT schema, "values", updated_at FROM plugin_config WHERE plugin_id = ?',
+    );
+    this.getByInstanceStmt = db.prepare(
+      'SELECT schema, "values", updated_at FROM plugin_config WHERE plugin_id = ? AND instance_id = ?',
+    );
+    this.upsertStmt = db.prepare(`
+      INSERT INTO plugin_config (plugin_id, instance_id, schema, "values", updated_at)
+      VALUES (?, ?, ?, ?, datetime('now'))
+      ON CONFLICT(plugin_id, instance_id) DO UPDATE SET
+        schema = excluded.schema,
+        "values" = excluded."values",
+        updated_at = datetime('now')
+    `);
+    this.listStmt = db.prepare(
+      'SELECT plugin_id, instance_id, schema, "values", updated_at FROM plugin_config ORDER BY plugin_id, instance_id',
+    );
+    this.listInstancesStmt = db.prepare(
+      'SELECT plugin_id, instance_id, schema, "values", updated_at FROM plugin_config WHERE plugin_id = ? ORDER BY instance_id',
+    );
+    this.deleteInstanceStmt = db.prepare(
+      "DELETE FROM plugin_config WHERE plugin_id = ? AND instance_id = ?",
+    );
+  }
+
+  /**
+   * Called by the plugin context during register.
+   * Returns read-only validated values.
+   */
+  register<T>(
+    pluginId: string,
+    schema: ConfigSchema<T>,
+    instanceId = "default",
+  ): Readonly<T> {
+    const row = this.getByInstanceStmt.get(pluginId, instanceId) as
+      | { schema: string; values: string; updated_at: string }
+      | undefined;
+
+    if (row) {
+      // Existing row — decrypt secrets, re-validate against current schema
+      const storedValues = this.decryptValues(schema, JSON.parse(row.values));
+      // Merge stored values with defaults from the current schema so that
+      // newly added fields (e.g. libraryId) are picked up.
+      const mergedValues = { ...this.buildDefaults(schema), ...storedValues };
+      const result = validateConfig(schema, mergedValues);
+
+      if (result.valid) {
+        // Schema or values may have changed (new optional fields, new defaults).
+        // Persist the current schema so get/list reflect it, and persist the
+        // merged values so existing config is preserved.
+        const toPersist = this.encryptValues(schema, mergedValues);
+        this.upsertStmt.run(pluginId, instanceId, JSON.stringify(schema), JSON.stringify(toPersist));
+        return Object.freeze(result.values as T);
+      }
+
+      // Validation failed against current schema (e.g., new required field added)
+      this.logger.warn("config re-validation failed, marking needs-configuration", {
+        pluginId,
+        instanceId,
+        errors: result.errors,
+      });
+      // Persist the new schema (so get/list reflect current schema) but keep
+      // existing values so user's prior changes aren't lost.
+      const toPersistOnFail = this.encryptValues(schema, mergedValues);
+      this.upsertStmt.run(pluginId, instanceId, JSON.stringify(schema), JSON.stringify(toPersistOnFail));
+      // Return defaults, plugin will need configuration
+      const defaults = this.buildDefaults(schema);
+      return Object.freeze(defaults as T);
+    }
+
+    // No existing row — first registration
+    const defaults = this.buildDefaults(schema);
+    const result = validateConfig(schema, defaults);
+
+    if (!result.valid) {
+      // Has required fields without defaults — persist defaults and mark needs-configuration
+      this.logger.warn("config has missing required fields, needs-configuration", {
+        pluginId,
+        instanceId,
+        errors: result.errors,
+      });
+    }
+
+    // Persist schema and values (encrypt secrets before storing)
+    const toPersist = this.encryptValues(schema, result.valid ? result.values : defaults);
+    this.upsertStmt.run(pluginId, instanceId, JSON.stringify(schema), JSON.stringify(toPersist));
+
+    return Object.freeze((result.valid ? result.values : defaults) as T);
+  }
+
+  /**
+   * Called by the admin settings API when saving config.
+   * Updates values, persists, and triggers reload.
+   */
+  update(
+    pluginId: string,
+    schema: ConfigSchema<any>,
+    input: Record<string, unknown>,
+    instanceId = "default",
+  ): ValidationResult {
+    const result = validateConfig(schema, input);
+
+    if (!result.valid) {
+      // Validation errors block save (CF3)
+      return result;
+    }
+
+    // Before persisting, handle secret fields:
+    // If a secret field's value is the sentinel, retrieve and use the existing
+    // decrypted value (so encryptValues() can re-encrypt it properly).
+    const existingRow = this.getByInstanceStmt.get(pluginId, instanceId) as
+      | { schema: string; values: string }
+      | undefined;
+
+    if (existingRow) {
+      const existingParsed = JSON.parse(existingRow.values);
+      const existingDecrypted = this.decryptValues(schema, existingParsed);
+      for (const [key, field] of Object.entries(schema)) {
+        const f = field as ConfigField;
+        if (f.type === "secret") {
+          if (result.values[key] === SECRET_UNCHANGED_SENTINEL) {
+            // Use the decrypted existing value — will be re-encrypted below
+            result.values[key] = existingDecrypted[key];
+          }
+        }
+      }
+    }
+
+    // Encrypt secret fields before persisting
+    const toPersist = this.encryptValues(schema, result.values);
+
+    // Persist
+    this.upsertStmt.run(pluginId, instanceId, JSON.stringify(schema), JSON.stringify(toPersist));
+
+    // Trigger reload
+    this.logger.info("config updated, triggering reload", { pluginId, instanceId });
+    this.onReload?.(pluginId);
+
+    return result;
+  }
+
+  /**
+   * Called by the admin UI to get render data.
+   * Returns schema + values (with secrets masked) + needsConfiguration flag.
+   */
+  get(pluginId: string, instanceId = "default"): PluginConfigEntry | undefined {
+    const row = this.getByInstanceStmt.get(pluginId, instanceId) as
+      | { schema: string; values: string; updated_at: string }
+      | undefined;
+
+    if (!row) return undefined;
+
+    const schema = JSON.parse(row.schema) as ConfigSchema<any>;
+    const storedValues = JSON.parse(row.values);
+
+    // Decrypt secrets for internal computation
+    const decryptedValues = this.decryptValues(schema, storedValues);
+
+    // Mask secrets for UI output
+    const maskedValues = this.maskSecretValues(schema, decryptedValues);
+
+    const needsConfiguration = this.computeNeedsConfiguration(schema, decryptedValues);
+
+    return {
+      schema,
+      values: maskedValues,
+      needsConfiguration,
+      updatedAt: row.updated_at,
+    };
+  }
+
+  /**
+   * Called by the admin UI to list all plugins with config status.
+   */
+  list(): PluginConfigSummary[] {
+    const rows = this.listStmt.all() as Array<{
+      plugin_id: string;
+      instance_id: string;
+      schema: string;
+      values: string;
+      updated_at: string;
+    }>;
+
+    return rows
+      .filter((row) => !row.plugin_id.startsWith("_core."))
+      .map((row) => {
+        const schema = JSON.parse(row.schema) as ConfigSchema<any>;
+        const values = JSON.parse(row.values);
+        const decryptedValues = this.decryptValues(schema, values);
+        const needsConfiguration = this.computeNeedsConfiguration(schema, decryptedValues);
+
+        return {
+          pluginId: row.plugin_id,
+          instanceId: row.instance_id,
+          needsConfiguration,
+          updatedAt: row.updated_at,
+          libraryId: decryptedValues.libraryId as string | undefined,
+        };
+      });
+  }
+
+  /**
+   * List all instances for a given plugin.
+   */
+  listInstances(pluginId: string): PluginConfigSummary[] {
+    const rows = this.listInstancesStmt.all(pluginId) as Array<{
+      plugin_id: string;
+      instance_id: string;
+      schema: string;
+      values: string;
+      updated_at: string;
+    }>;
+
+    return rows
+      .filter((row) => !row.plugin_id.startsWith("_core."))
+      .map((row) => {
+        const schema = JSON.parse(row.schema) as ConfigSchema<any>;
+        const values = JSON.parse(row.values);
+        const decryptedValues = this.decryptValues(schema, values);
+        const needsConfiguration = this.computeNeedsConfiguration(schema, decryptedValues);
+
+        return {
+          pluginId: row.plugin_id,
+          instanceId: row.instance_id,
+          needsConfiguration,
+          updatedAt: row.updated_at,
+          libraryId: decryptedValues.libraryId as string | undefined,
+        };
+      });
+  }
+
+  /**
+   * Create a new plugin instance with the given instanceId and config values.
+   * Validates and persists.
+   */
+  createInstance<T>(
+    pluginId: string,
+    instanceId: string,
+    schema: ConfigSchema<T>,
+    values: Record<string, unknown>,
+  ): ValidationResult {
+    // Validate
+    const result = validateConfig(schema, values);
+    if (!result.valid) return result;
+
+    // Check for duplicate instance
+    const existing = this.get(pluginId, instanceId);
+    if (existing) {
+      return { valid: false, values: {}, errors: [{ field: "instanceId", message: `Instance "${instanceId}" already exists` }] };
+    }
+
+    // Encrypt and persist
+    const toPersist = this.encryptValues(schema, result.values);
+    this.upsertStmt.run(pluginId, instanceId, JSON.stringify(schema), JSON.stringify(toPersist));
+
+    return result;
+  }
+
+  /**
+   * Delete a plugin instance and its config.
+   */
+  deleteInstance(pluginId: string, instanceId: string): void {
+    const result = this.deleteInstanceStmt.run(pluginId, instanceId);
+    if (result.changes === 0) {
+      throw new Error(`Instance not found: ${pluginId}::${instanceId}`);
+    }
+  }
+
+  /**
+   * Return decrypted stored values for a plugin, or undefined if no row exists.
+   * Used by the test-connection endpoint to resolve secret sentinels.
+   */
+  getDecryptedValues(pluginId: string, instanceId = "default"): Record<string, unknown> | undefined {
+    const row = this.getByInstanceStmt.get(pluginId, instanceId) as
+      | { schema: string; values: string }
+      | undefined;
+
+    if (!row) return undefined;
+
+    const schema = JSON.parse(row.schema) as ConfigSchema<any>;
+    const storedValues = JSON.parse(row.values);
+    return this.decryptValues(schema, storedValues);
+  }
+
+  /**
+   * Check whether a plugin needs configuration (required fields missing).
+   * Used by context.ts for the debug log.
+   */
+  needsConfiguration(pluginId: string, instanceId = "default"): boolean {
+    const row = this.getByInstanceStmt.get(pluginId, instanceId) as
+      | { schema: string; values: string }
+      | undefined;
+
+    if (!row) return false;
+    const schema = JSON.parse(row.schema) as ConfigSchema<any>;
+    const storedValues = JSON.parse(row.values);
+    const decryptedValues = this.decryptValues(schema, storedValues);
+    return this.computeNeedsConfiguration(schema, decryptedValues);
+  }
+
+  // ── Private helpers ──────────────────────────────────────
+
+  private buildDefaults(schema: ConfigSchema<any>): Record<string, unknown> {
+    const defaults: Record<string, unknown> = {};
+    for (const [key, rawField] of Object.entries(schema)) {
+      const field = rawField as ConfigField;
+      if (field.default !== undefined) {
+        defaults[key] = field.default;
+      }
+    }
+    return defaults;
+  }
+
+  private computeNeedsConfiguration(
+    schema: ConfigSchema<any>,
+    values: Record<string, unknown>,
+  ): boolean {
+    for (const [key, rawField] of Object.entries(schema)) {
+      const field = rawField as ConfigField;
+      if (field.required === true) {
+        const val = values[key];
+        if (val === undefined || val === null || val === "") {
+          if (field.default === undefined) {
+            return true;
+          }
+        }
+      }
+    }
+    return false;
+  }
+
+  private encryptValues(
+    schema: ConfigSchema<any>,
+    values: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const result = { ...values };
+    for (const [key, rawField] of Object.entries(schema)) {
+      const field = rawField as ConfigField;
+      if (field.type === "secret" && result[key] !== undefined && result[key] !== null) {
+        const plaintext = String(result[key]);
+        result[key] = encrypt(plaintext);
+      }
+    }
+    return result;
+  }
+
+  private decryptValues(
+    schema: ConfigSchema<any>,
+    values: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const result = { ...values };
+    for (const [key, rawField] of Object.entries(schema)) {
+      const field = rawField as ConfigField;
+      if (field.type === "secret" && result[key] !== undefined && result[key] !== null && typeof result[key] === "string") {
+        try {
+          result[key] = decrypt(result[key] as string);
+        } catch {
+          // If decryption fails, leave as-is (corrupted data)
+          this.logger.warn("failed to decrypt secret field", { field: key });
+        }
+      }
+    }
+    return result;
+  }
+
+  private maskSecretValues(
+    schema: ConfigSchema<any>,
+    values: Record<string, unknown>,
+  ): Record<string, unknown> {
+    const result = { ...values };
+    for (const [key, rawField] of Object.entries(schema)) {
+      const field = rawField as ConfigField;
+      if (field.type === "secret") {
+        if (result[key] !== undefined && result[key] !== null && result[key] !== "") {
+          result[key] = SECRET_UNCHANGED_SENTINEL;
+        }
+      }
+    }
+    return result;
+  }
+}

package/src/config/validate.ts

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import type { ConfigSchema, ConfigField } from "../types/plugin.js";
+
+export interface ValidationResult {
+  valid: boolean;
+  values: Record<string, unknown>;
+  errors: FieldError[];
+}
+
+export interface FieldError {
+  field: string;
+  message: string;
+}
+
+function isMissing(value: unknown): boolean {
+  if (value === undefined || value === null) return true;
+  if (typeof value === "string" && value === "") return true;
+  return false;
+}
+
+function coerceNumber(value: unknown): { value: number; ok: boolean } {
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) return { value, ok: true };
+    return { value: NaN, ok: false };
+  }
+  if (typeof value === "string") {
+    if (value === "") return { value: NaN, ok: false };
+    const n = Number(value);
+    if (Number.isFinite(n)) return { value: n, ok: true };
+    return { value: NaN, ok: false };
+  }
+  return { value: NaN, ok: false };
+}
+
+function coerceBoolean(value: unknown): { value: boolean; ok: boolean } {
+  if (typeof value === "boolean") return { value, ok: true };
+  if (value === "true") return { value: true, ok: true };
+  if (value === "false") return { value: false, ok: true };
+  return { value: false, ok: false };
+}
+
+export function validateConfig<T>(
+  schema: ConfigSchema<T>,
+  input: Record<string, unknown>,
+): ValidationResult {
+  const values: Record<string, unknown> = {};
+  const errors: FieldError[] = [];
+
+  for (const [key, rawField] of Object.entries(schema)) {
+    const field = rawField as ConfigField;
+    const inputVal = key in input ? input[key] : undefined;
+    const missing = isMissing(inputVal);
+
+    // Handle missing values
+    if (missing) {
+      if (field.default !== undefined) {
+        // Default is defined — use it (even if null)
+        values[key] = field.default;
+        continue;
+      }
+      if (field.required === true) {
+        errors.push({ field: key, message: "required field is missing" });
+        continue;
+      }
+      // Optional field with no default — store undefined
+      values[key] = undefined;
+      continue;
+    }
+
+    // Value is present — validate and coerce based on type
+    switch (field.type) {
+      case "string":
+      case "secret": {
+        if (typeof inputVal !== "string") {
+          errors.push({ field: key, message: `expected string, got ${typeof inputVal}` });
+        } else {
+          values[key] = inputVal;
+        }
+        break;
+      }
+
+      case "number": {
+        const coerced = coerceNumber(inputVal);
+        if (!coerced.ok) {
+          errors.push({ field: key, message: `expected a finite number, got ${JSON.stringify(inputVal)}` });
+        } else {
+          values[key] = coerced.value;
+        }
+        break;
+      }
+
+      case "boolean": {
+        const coerced = coerceBoolean(inputVal);
+        if (!coerced.ok) {
+          errors.push({ field: key, message: `expected boolean or "true"/"false", got ${JSON.stringify(inputVal)}` });
+        } else {
+          values[key] = coerced.value;
+        }
+        break;
+      }
+
+      case "enum": {
+        if (typeof inputVal !== "string") {
+          errors.push({ field: key, message: `expected string for enum, got ${typeof inputVal}` });
+        } else if (field.options && field.options.length > 0 && !field.options.includes(inputVal)) {
+          errors.push({
+            field: key,
+            message: `value "${inputVal}" is not in allowed options: [${field.options.join(", ")}]`,
+          });
+        } else {
+          values[key] = inputVal;
+        }
+        break;
+      }
+
+      case "url": {
+        if (typeof inputVal !== "string") {
+          errors.push({ field: key, message: `expected string for URL, got ${typeof inputVal}` });
+        } else {
+          try {
+            new URL(inputVal);
+            values[key] = inputVal;
+          } catch {
+            errors.push({ field: key, message: `"${inputVal}" is not a valid URL` });
+          }
+        }
+        break;
+      }
+
+      case "path": {
+        if (typeof inputVal !== "string" || inputVal === "") {
+          errors.push({ field: key, message: `expected non-empty string for path, got ${JSON.stringify(inputVal)}` });
+        } else {
+          values[key] = inputVal;
+        }
+        break;
+      }
+
+      default:
+        // Unknown field type — leniently accept as-is
+        values[key] = inputVal;
+        break;
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    values: errors.length === 0 ? values : {},
+    errors,
+  };
+}