PlatformAdminBootstrapService

Kind: Service

Source: atloria-monorepo/apps/api/src/platform/platform-admin-bootstrap.service.ts

Declarative bootstrap of platform admins from PLATFORM_ADMIN_EMAILS (a comma-separated k8s-secret value). Runs once on boot and treats the env list as the source of truth:

• promotes listed users that exist,
• demotes any current platform admin NOT on the list (so revocation is just an edit to the secret + redeploy).

SAFETY: when the list is empty/unset this is a NO-OP — it never mass-demotes. That protects against a misconfigured/blank secret wiping out access; recovery is the one-off scripts/grant-platform-admin.ts or restoring the secret.

Emails not matching any user are logged, not created — a platform admin must already be a real member of some org.

PlatformAdminBootstrapService reconciles platform administrator access from the PLATFORM_ADMIN_EMAILS environment variable during application startup. It promotes existing users listed in the comma-separated secret and demotes current platform admins omitted from it, making the secret the authoritative access list. An empty or unset value is intentionally a no-op to prevent accidental mass revocation.

Methods

Dependencies

• PrismaService
• ConfigService

When something fails

• PlatformAdminBootstrapService handles failure in 1 place: it logs it and continues in all 1.

Diagram

mermaid
sequenceDiagram
    participant App as NestJS Application
    participant Service as PlatformAdminBootstrapService
    participant Env as PLATFORM_ADMIN_EMAILS
    participant Users as User Repository

    App->>Service: onModuleInit()
    Service->>Env: Read and parse email list

    alt Email list is empty or unset
        Service-->>App: No-op (preserve existing admins)
    else Email list contains emails
        Service->>Users: Find users matching configured emails
        Users-->>Service: Existing users and unmatched emails

        Service->>Users: Promote matched users to platform admin
        Service->>Users: Find current platform admins
        Service->>Users: Demote admins not in configured list

        Service-->>App: Reconciliation result
    end

Usage

ts
import { PlatformAdminBootstrapService } from './platform-admin-bootstrap.service';

// Normally invoked automatically by NestJS through onModuleInit().
@Injectable()
export class PlatformMaintenanceService {
  constructor(
    private readonly platformAdminBootstrap: PlatformAdminBootstrapService,
  ) {}

  async reconcilePlatformAdmins() {
    const result = await this.platformAdminBootstrap.reconcile();

    console.log(
      `Promoted: ${result.promoted}, demoted: ${result.demoted}`,
    );

    if (result.unmatched.length > 0) {
      console.warn(
        'Configured platform admin emails do not match existing users:',
        result.unmatched,
      );
    }

    return result;
  }
}

AI Coding Instructions

• Treat PLATFORM_ADMIN_EMAILS as the source of truth only when it contains at least one valid configured value; never change the empty/unset-list no-op safety behavior.
• Do not create users for unmatched emails. Platform administrators must already exist as members of an organization.
• Preserve the startup integration through onModuleInit() so reconciliation runs automatically after the NestJS module initializes.
• When changing reconciliation logic, ensure both promotion and revocation paths remain idempotent and return accurate promoted, demoted, and unmatched counts.
• Use scripts/grant-platform-admin.ts or restore the configured secret for recovery scenarios rather than weakening bootstrap safety checks.

Relationships

• DEPENDS_ON → PrismaService
• DEPENDS_ON → configservice

Referenced By

• PlatformModule (MODULE_PROVIDES)
• PlatformModule (MODULE_EXPORTS)