@digitalpaws/starr 0.0.1

package/src/auth/oidc/oidc-flow.ts

@@ -0,0 +1,266 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import {
+  discovery,
+  buildAuthorizationUrl,
+  authorizationCodeGrant,
+  randomPKCECodeVerifier,
+  calculatePKCECodeChallenge,
+  randomState,
+  randomNonce,
+} from "openid-client";
+import type Database from "better-sqlite3";
+import type { Logger } from "../../types/plugin.js";
+import type { OidcProviderService } from "./oidc-provider-service.js";
+import type { User, UserService } from "./user-service.js";
+
+const STATE_TTL_MS = 10 * 60 * 1000;  // 10 minutes
+
+/** Result of a successful OIDC callback. */
+export interface OidcCallbackResult {
+  user: User;
+  providerId: string;
+  created: boolean;
+  redirectTo: string;
+}
+
+export class OidcFlow {
+  constructor(
+    private db: Database.Database,
+    private providerService: OidcProviderService,
+    private userService: UserService,
+    private baseUrl: string,   // e.g. "http://localhost:3457"
+    private logger: Logger,
+  ) {}
+
+  /**
+   * Stage 1 — Initiate the OIDC login flow.
+   *
+   * 1. Look up the provider configuration.
+   * 2. Discover the OIDC issuer's endpoints (via .well-known).
+   * 3. Generate PKCE code verifier and challenge, state, nonce.
+   * 4. Store the state in oidc_auth_states.
+   * 5. Return the redirect URL to send the user's browser to.
+   *
+   * @param providerId  The OIDC provider's UUID.
+   * @param redirectTo  Where to send the user after successful login (e.g. "/browse").
+   * @returns The authorization URL to redirect the browser to.
+   */
+  async initiateLogin(
+    providerId: string,
+    redirectTo: string = "/browse",
+  ): Promise<string> {
+    const provider = this.providerService.get(providerId);
+    if (!provider) {
+      throw new Error(`OIDC provider not found: ${providerId}`);
+    }
+    if (!provider.enabled) {
+      throw new Error(`OIDC provider is disabled: ${providerId}`);
+    }
+
+    // Discover the OIDC issuer's metadata
+    const config = await discovery(
+      new URL(provider.issuerUrl),
+      provider.clientId,
+      { client_secret: provider.clientSecret },
+    );
+
+    // Generate PKCE and state values
+    const codeVerifier = randomPKCECodeVerifier();
+    const codeChallenge = await calculatePKCECodeChallenge(codeVerifier);
+    const state = randomState();
+    const nonce = randomNonce();
+
+    // Store the auth state
+    this.db.prepare(`
+      INSERT INTO oidc_auth_states (state, nonce, code_verifier, provider_id, redirect_to, created_at)
+      VALUES (@state, @nonce, @codeVerifier, @providerId, @redirectTo, datetime('now'))
+    `).run({
+      state,
+      nonce,
+      codeVerifier,
+      providerId: provider.id,
+      redirectTo,
+    });
+
+    // Build the authorization URL
+    const authUrl = buildAuthorizationUrl(config, {
+      redirect_uri: `${this.baseUrl}/api/oidc/callback/${provider.id}`,
+      scope: provider.scopes,
+      state,
+      nonce,
+      code_challenge: codeChallenge,
+      code_challenge_method: "S256",
+      response_type: "code",
+    });
+
+    this.logger.info("OIDC login initiated", {
+      providerId: provider.id,
+      providerName: provider.name,
+    });
+
+    return authUrl.href;
+  }
+
+  /**
+   * Stage 2 — Handle the OIDC callback.
+   *
+   * 1. Validate the state (CSRF protection).
+   * 2. Look up stored auth state from DB.
+   * 3. Exchange authorization code for tokens.
+   * 4. Validate the ID token (handled by openid-client).
+   * 5. Find or create the user.
+   * 6. Clean up the used auth state.
+   *
+   * @returns The authenticated user and whether they were just created.
+   */
+  async handleCallback(
+    providerId: string,
+    code: string,
+    state: string,
+  ): Promise<OidcCallbackResult> {
+    // 1. Validate the state (CSRF)
+    if (!state || !code) {
+      throw new Error("Missing state or code parameter");
+    }
+
+    // 2. Look up the stored auth state
+    const authState = this.db.prepare(`
+      SELECT * FROM oidc_auth_states WHERE state = @state AND provider_id = @providerId
+    `).get({ state, providerId }) as any;
+
+    if (!authState) {
+      throw new Error("Invalid or expired OIDC state");
+    }
+
+    // Delete the used state now (before any further processing)
+    this.db.prepare("DELETE FROM oidc_auth_states WHERE state = @state").run({ state });
+
+    // 3. Clean up any expired auth states (older than 10 minutes)
+    this.cleanupExpiredStates();
+
+    // 4. Get the provider config and exchange the code
+    const provider = this.providerService.get(providerId);
+    if (!provider) {
+      throw new Error(`OIDC provider not found: ${providerId}`);
+    }
+
+    const config = await discovery(
+      new URL(provider.issuerUrl),
+      provider.clientId,
+      { client_secret: provider.clientSecret },
+    );
+
+    // Build the callback URL with code + state params (as the provider would redirect to)
+    const callbackUrl = new URL(`${this.baseUrl}/api/oidc/callback/${provider.id}`);
+    callbackUrl.searchParams.set("code", code);
+    callbackUrl.searchParams.set("state", state);
+
+    // Exchange the authorization code for tokens.
+    // openid-client automatically:
+    //   - Validates the state parameter
+    //   - Validates the ID token (signature, iss, aud, exp, expectedNonce)
+    //   - Fetches the JWKS from the provider
+    const tokenSet = await authorizationCodeGrant(
+      config,
+      callbackUrl,
+      {
+        expectedNonce: authState.nonce,
+        pkceCodeVerifier: authState.code_verifier,
+        expectedState: state,
+      },
+    );
+
+    // 5. Extract claims from the ID token
+    const idTokenClaims = tokenSet.claims();
+    if (!idTokenClaims) {
+      throw new Error("OIDC provider did not return an ID token");
+    }
+
+    // Cast claims to access OIDC standard claims (preferred_username, name, etc.)
+    const claims = idTokenClaims as Record<string, unknown>;
+
+    this.logger.info("OIDC callback successful", {
+      providerId,
+      sub: String(claims.sub ?? ""),
+      email: claims.email as string | undefined,
+    });
+
+    // 6. Resolve the role from the provider's role_attribute, if configured
+    let role: "admin" | "user" = provider.defaultRole;
+    if (provider.roleAttribute) {
+      const resolvedRole = this.resolveRoleFromClaim(claims, provider.roleAttribute, provider.defaultRole);
+      if (resolvedRole) role = resolvedRole;
+    }
+
+    // 7. Find or create the user
+    const { user, created } = this.userService.findOrCreateFromOidc(
+      {
+        sub: String(claims.sub ?? ""),
+        preferred_username: claims.preferred_username as string | undefined,
+        name: claims.name as string | undefined,
+        picture: claims.picture as string | undefined,
+        email: claims.email as string | undefined,
+      },
+      providerId,
+      role,
+    );
+
+    return { user, providerId, created, redirectTo: authState.redirect_to ?? "/browse" };
+  }
+
+  /**
+   * Resolve a Starr role from an OIDC claim using a JSONPath-like expression.
+   *
+   * Simple dot-notation path (e.g. "$.starr_roles" or "starr_roles"):
+   * - If the resolved value is an array, it's checked for "admin".
+   * - If it's a string, it's checked as-is.
+   * - If it's a boolean, true=admin, false=defaultRole.
+   * - If not found, returns null (caller uses defaultRole).
+   */
+  private resolveRoleFromClaim(
+    claims: Record<string, unknown>,
+    roleAttribute: string,
+    defaultRole: "admin" | "user",
+  ): "admin" | "user" | null {
+    try {
+      // Simple dot-notation path resolution
+      const path = roleAttribute.replace(/^\$\.?/, ""); // strip leading "$." or "$"
+      const keys = path.split(".");
+      let value: unknown = claims;
+      for (const key of keys) {
+        if (value && typeof value === "object" && key in (value as Record<string, unknown>)) {
+          value = (value as Record<string, unknown>)[key];
+        } else {
+          return null; // path not found
+        }
+      }
+
+      // Interpret the value
+      if (Array.isArray(value)) {
+        return value.includes("admin") ? "admin" : defaultRole;
+      }
+      if (typeof value === "string") {
+        return value === "admin" ? "admin" : (value === "user" ? "user" : null);
+      }
+      if (typeof value === "boolean") {
+        return value ? "admin" : defaultRole;
+      }
+    } catch {
+      // If anything goes wrong resolving the role, fall back to default
+    }
+    return null;
+  }
+
+  /** Delete auth states older than 10 minutes (capped at 100 rows). */
+  private cleanupExpiredStates(): void {
+    // Use SQLite's datetime arithmetic for consistent comparison with
+    // the stored datetime('now') format (no T, no Z).
+    this.db.prepare(`
+      DELETE FROM oidc_auth_states
+      WHERE created_at < datetime('now', @offset)
+      LIMIT 100
+    `).run({ offset: `-${STATE_TTL_MS / 1000} seconds` });
+  }
+}

package/src/auth/oidc/oidc-provider-service.ts

@@ -0,0 +1,174 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { randomUUID } from "node:crypto";
+import type Database from "better-sqlite3";
+import type { Logger } from "../../types/plugin.js";
+
+/**
+ * Shape of an OIDC provider as stored.
+ * client_secret is encrypted at rest.
+ */
+export interface OidcProvider {
+  id: string;
+  name: string;
+  issuerUrl: string;
+  clientId: string;
+  clientSecret: string;   // plaintext in-memory, encrypted at rest
+  scopes: string;
+  roleAttribute: string | null;
+  defaultRole: "admin" | "user";
+  enabled: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Public-facing shape (no secret, for the login page).
+ */
+export interface OidcProviderPublic {
+  id: string;
+  name: string;
+  enabled: boolean;
+}
+
+/** Shape used when creating or updating a provider. */
+export interface OidcProviderInput {
+  name: string;
+  issuerUrl: string;
+  clientId: string;
+  clientSecret: string;
+  scopes?: string;
+  roleAttribute?: string | null;
+  defaultRole?: "admin" | "user";
+  enabled?: boolean;
+}
+
+export class OidcProviderService {
+  constructor(
+    private db: Database.Database,
+    private encrypt: (plaintext: string) => string,
+    private decrypt: (ciphertext: string) => string,
+    private logger: Logger,
+  ) {}
+
+  /** List all providers (with encrypted secrets, for admin API). */
+  list(): OidcProvider[] {
+    const rows = this.db
+      .prepare("SELECT * FROM oidc_providers ORDER BY name ASC")
+      .all() as any[];
+    return rows.map(this.rowToProvider);
+  }
+
+  /** List only enabled providers (public info, no secrets). */
+  listEnabled(): OidcProviderPublic[] {
+    const rows = this.db
+      .prepare("SELECT id, name, enabled FROM oidc_providers WHERE enabled = 1 ORDER BY name ASC")
+      .all() as any[];
+    return rows.map((r: any) => ({
+      id: r.id,
+      name: r.name,
+      enabled: !!r.enabled,
+    }));
+  }
+
+  /** Get a single provider by ID. */
+  get(id: string): OidcProvider | null {
+    const row = this.db
+      .prepare("SELECT * FROM oidc_providers WHERE id = @id")
+      .get({ id }) as any;
+    return row ? this.rowToProvider(row) : null;
+  }
+
+  /** Create a new provider. Returns the created provider. */
+  create(input: OidcProviderInput): OidcProvider {
+    const id = randomUUID();
+    const encryptedSecret = this.encrypt(input.clientSecret);
+    const scopes = input.scopes ?? "openid profile email";
+    const defaultRole = input.defaultRole ?? "user";
+
+    this.db.prepare(`
+      INSERT INTO oidc_providers (id, name, issuer_url, client_id, client_secret,
+        scopes, role_attribute, default_role, enabled)
+      VALUES (@id, @name, @issuerUrl, @clientId, @clientSecret,
+        @scopes, @roleAttribute, @defaultRole, @enabled)
+    `).run({
+      id,
+      name: input.name,
+      issuerUrl: input.issuerUrl,
+      clientId: input.clientId,
+      clientSecret: encryptedSecret,
+      scopes,
+      roleAttribute: input.roleAttribute ?? null,
+      defaultRole,
+      enabled: input.enabled !== false ? 1 : 0,
+    });
+
+    this.logger.info("OIDC provider created", { id, name: input.name });
+    return this.get(id)!;
+  }
+
+  /** Update an existing provider. Fields that are undefined are not changed. */
+  update(id: string, input: Partial<OidcProviderInput>): OidcProvider | null {
+    const existing = this.get(id);
+    if (!existing) return null;
+
+    const name = input.name ?? existing.name;
+    const issuerUrl = input.issuerUrl ?? existing.issuerUrl;
+    const clientId = input.clientId ?? existing.clientId;
+    const clientSecret = input.clientSecret
+      ? this.encrypt(input.clientSecret)
+      : existing.clientSecret;  // Keep existing encrypted value if no new secret provided
+    const scopes = input.scopes ?? existing.scopes;
+    const roleAttribute = input.roleAttribute !== undefined
+      ? (input.roleAttribute ?? null)
+      : existing.roleAttribute;
+    const defaultRole = input.defaultRole ?? existing.defaultRole;
+    const enabled = input.enabled !== undefined ? (input.enabled ? 1 : 0) : (existing.enabled ? 1 : 0);
+
+    this.db.prepare(`
+      UPDATE oidc_providers SET
+        name = @name,
+        issuer_url = @issuerUrl,
+        client_id = @clientId,
+        client_secret = @clientSecret,
+        scopes = @scopes,
+        role_attribute = @roleAttribute,
+        default_role = @defaultRole,
+        enabled = @enabled,
+        updated_at = datetime('now')
+      WHERE id = @id
+    `).run({ id, name, issuerUrl, clientId, clientSecret, scopes, roleAttribute, defaultRole, enabled });
+
+    this.logger.info("OIDC provider updated", { id, name });
+    return this.get(id);
+  }
+
+  /** Delete a provider. Also cleans up auth states referencing it (CASCADE). */
+  delete(id: string): boolean {
+    const existing = this.get(id);
+    if (!existing) return false;
+
+    this.db.prepare("DELETE FROM oidc_providers WHERE id = @id").run({ id });
+    this.logger.info("OIDC provider deleted", { id, name: existing.name });
+    return true;
+  }
+
+  // ── Private helpers ──
+
+  private rowToProvider(row: any): OidcProvider {
+    return {
+      id: row.id,
+      name: row.name,
+      issuerUrl: row.issuer_url,
+      clientId: row.client_id,
+      clientSecret: this.decrypt(row.client_secret),
+      scopes: row.scopes,
+      roleAttribute: row.role_attribute,
+      defaultRole: row.default_role,
+      enabled: !!row.enabled,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    };
+  }
+}

package/src/auth/oidc/user-service.ts

@@ -0,0 +1,227 @@
+// SPDX-License-Identifier: 0BSD
+// SPDX-FileCopyrightText: 2025 Digi <digitalpaws@proton.me>
+
+import { randomUUID } from "node:crypto";
+import type Database from "better-sqlite3";
+import type { Logger } from "../../types/plugin.js";
+
+export interface User {
+  id: string;
+  username: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+  role: "admin" | "user";
+  provider: "local" | "oidc";
+  oidcSub: string | null;
+  oidcProviderId: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** Shape for updating user role (admin-only). */
+export interface UserRoleUpdate {
+  role: "admin" | "user";
+}
+
+export class UserService {
+  constructor(
+    private db: Database.Database,
+    private logger: Logger,
+  ) {}
+
+  /** Get a user by UUID or the fixed admin id. */
+  get(id: string): User | null {
+    const row = this.db
+      .prepare("SELECT * FROM users WHERE id = @id")
+      .get({ id }) as any;
+    return row ? this.rowToUser(row) : null;
+  }
+
+  /** Get a user by username. */
+  getByUsername(username: string): User | null {
+    const row = this.db
+      .prepare("SELECT * FROM users WHERE username = @username")
+      .get({ username }) as any;
+    return row ? this.rowToUser(row) : null;
+  }
+
+  /**
+   * Find a user by OIDC subject and provider.
+   * This is the primary lookup during OIDC callback.
+   */
+  getByOidcSub(oidcSub: string, oidcProviderId: string): User | null {
+    const row = this.db
+      .prepare(
+        "SELECT * FROM users WHERE oidc_sub = @sub AND oidc_provider_id = @providerId"
+      )
+      .get({ sub: oidcSub, providerId: oidcProviderId }) as any;
+    return row ? this.rowToUser(row) : null;
+  }
+
+  /**
+   * Find or create a user from OIDC claims during callback.
+   *
+   * Steps:
+   * 1. Look up by (oidc_sub, oidc_provider_id).
+   * 2. If found, update display_name, avatar_url, username from claims.
+   * 3. If not found, create a new user with provider='oidc'.
+   *
+   * Returns the user and a boolean indicating whether it was newly created.
+   */
+  findOrCreateFromOidc(
+    claims: {
+      sub: string;
+      preferred_username?: string;
+      name?: string;
+      picture?: string;
+      email?: string;
+    },
+    oidcProviderId: string,
+    defaultRole: "admin" | "user",
+  ): { user: User; created: boolean } {
+    // 1. Look up existing user by OIDC identity
+    let user = this.getByOidcSub(claims.sub, oidcProviderId);
+    if (user) {
+      // 2. Update claims (username/display name/avatar may have changed at the IdP)
+      const displayName = claims.name ?? claims.preferred_username ?? claims.sub;
+      const avatarUrl = claims.picture ?? null;
+      const username = claims.preferred_username ?? claims.sub;
+
+      this.db.prepare(`
+        UPDATE users SET
+          username = @username,
+          display_name = @displayName,
+          avatar_url = @avatarUrl,
+          updated_at = datetime('now')
+        WHERE id = @id
+      `).run({
+        id: user.id,
+        username,
+        displayName,
+        avatarUrl,
+      });
+
+      user = this.get(user.id)!;
+      return { user, created: false };
+    }
+
+    // 3. Create new user
+    const id = randomUUID();
+    const displayName = claims.name ?? claims.preferred_username ?? claims.sub;
+    const avatarUrl = claims.picture ?? null;
+    const username = claims.preferred_username ?? claims.sub;
+
+    // If the preferred_username is already taken, append a suffix
+    let finalUsername = username;
+    let suffix = 1;
+    while (this.getByUsername(finalUsername)) {
+      finalUsername = `${username}_${suffix}`;
+      suffix++;
+    }
+
+    this.db.prepare(`
+      INSERT INTO users (id, username, display_name, avatar_url, role, provider,
+        oidc_sub, oidc_provider_id)
+      VALUES (@id, @username, @displayName, @avatarUrl, @role, 'oidc',
+        @oidcSub, @oidcProviderId)
+    `).run({
+      id,
+      username: finalUsername,
+      displayName,
+      avatarUrl,
+      role: defaultRole,
+      oidcSub: claims.sub,
+      oidcProviderId,
+    });
+
+    user = this.get(id)!;
+    this.logger.info("OIDC user auto-created", {
+      userId: user.id,
+      username: user.username,
+      providerId: oidcProviderId,
+    });
+    return { user, created: true };
+  }
+
+  /** List all users (admin only). */
+  list(): User[] {
+    const rows = this.db
+      .prepare("SELECT * FROM users ORDER BY created_at ASC")
+      .all() as any[];
+    return rows.map(this.rowToUser);
+  }
+
+  /** Count how many admin users exist. */
+  countAdmins(): number {
+    const row = this.db
+      .prepare("SELECT COUNT(*) AS count FROM users WHERE role = 'admin'")
+      .get() as { count: number };
+    return row.count;
+  }
+
+  /** Change a user's role. Returns the updated user or null if not found. */
+  setRole(id: string, role: "admin" | "user"): User | null {
+    const user = this.get(id);
+    if (!user) return null;
+
+    // Prevent demoting the built-in local admin account
+    if (id === "admin" && role === "user") {
+      throw new Error("Cannot demote the built-in admin account");
+    }
+
+    // Prevent demoting the last admin
+    if (user.role === "admin" && role === "user") {
+      const adminCount = this.countAdmins();
+      if (adminCount <= 1) {
+        throw new Error("Cannot demote the last admin user");
+      }
+    }
+
+    this.db.prepare(`
+      UPDATE users SET role = @role, updated_at = datetime('now') WHERE id = @id
+    `).run({ id, role });
+
+    this.logger.info("user role changed", {
+      targetUserId: id,
+      newRole: role,
+    });
+    return this.get(id);
+  }
+
+  /** Check if there is at least one admin user. */
+  hasAdmin(): boolean {
+    const row = this.db
+      .prepare("SELECT 1 FROM users WHERE role = 'admin' LIMIT 1")
+      .get();
+    return row !== undefined;
+  }
+
+  /**
+   * Resolve a user identifier (UUID or "admin") to a user.
+   * Used when validating sessions that may have either format in user_id.
+   */
+  resolveUser(userId: string): User | null {
+    // Try direct lookup by id first
+    const user = this.get(userId);
+    if (user) return user;
+    // Fallback: try as username (for backward compat with old sessions)
+    return this.getByUsername(userId);
+  }
+
+  // ── Private helpers ──
+
+  private rowToUser(row: any): User {
+    return {
+      id: row.id,
+      username: row.username,
+      displayName: row.display_name,
+      avatarUrl: row.avatar_url,
+      role: row.role,
+      provider: row.provider,
+      oidcSub: row.oidc_sub,
+      oidcProviderId: row.oidc_provider_id,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    };
+  }
+}