feat: add admin backend foundation (login, session, health) (#641)

Author: Ferryx349

.changeset/admin-console-phase-1.md

@@ -0,0 +1,5 @@
+---
+"nostream": minor
+---
+
+feat: add disabled-by-default admin API with password auth, session, and health endpoints

resources/default-settings.yaml

@@ -112,6 +112,19 @@ limits:
       - "::1"
       - "10.10.10.1"
       - "::ffff:10.10.10.1"
+  admin:
+    rateLimits:
+      - description: 30 admin requests/min
+        period: 60000
+        rate: 30
+    loginRateLimits:
+      - description: 10 login attempts per 15 minutes
+        period: 900000
+        rate: 10
+    ipWhitelist:
+      - "::1"
+      - "10.10.10.1"
+      - "::ffff:10.10.10.1"
   connection:
     rateLimits:
       - period: 1000
@@ -229,3 +242,6 @@ limits:
       - "::1"
       - "10.10.10.1"
       - "::ffff:10.10.10.1"
+admin:
+  enabled: false
+  sessionTtlSeconds: 86400

src/@types/admin.ts

@@ -0,0 +1,7 @@
+import { Request, Response } from 'express'
+
+export interface IAdminAuthProvider {
+  handleLogin(request: Request, response: Response): Promise<void>
+  isRequestAuthenticated(request: Request): boolean
+  getSessionExpiresAt(request: Request): number | undefined
+}

src/@types/settings.ts

@@ -141,10 +141,17 @@ export interface AdmissionCheckLimits {
   ipWhitelist?: string[]
 }
 
+export interface AdminLimits {
+  rateLimits?: RateLimit[]
+  loginRateLimits?: RateLimit[]
+  ipWhitelist?: string[]
+}
+
 export interface Limits {
   rateLimiter?: RateLimiterSettings
   invoice?: InvoiceLimits
   admissionCheck?: AdmissionCheckLimits
+  admin?: AdminLimits
   connection?: ConnectionLimits
   client?: ClientLimits
   event?: EventLimits
@@ -266,6 +273,11 @@ export interface Nip05Settings {
   domainBlacklist?: string[]
 }
 
+export interface AdminSettings {
+  enabled: boolean
+  passwordHash?: string
+  sessionTtlSeconds?: number
+}
 export interface WoTSettings {
   enabled: boolean
   /**
@@ -295,6 +307,7 @@ export interface Nip43Settings {
 
 export interface Settings {
   info: Info
+  admin?: AdminSettings
   payments?: Payments
   paymentsProcessors?: PaymentsProcessors
   network: Network

src/admin/password-admin-auth-provider.ts

@@ -0,0 +1,76 @@
+import { Request, Response } from 'express'
+
+import { IAdminAuthProvider } from '../@types/admin'
+import { Settings } from '../@types/settings'
+import { adminLoginBodySchema } from '../schemas/admin-login-schema'
+import { verifyAdminPasswordHash, verifyPlaintextPassword } from '../utils/admin-password'
+import {
+  buildAdminSessionCookieHeader,
+  createAdminSessionToken,
+  getAdminSessionTokenFromRequest,
+  isValidAdminSessionToken,
+  parseAdminSessionToken,
+  resolveAdminSessionTtlSeconds,
+} from '../utils/admin-session'
+import { validateSchema } from '../utils/validation'
+
+export class PasswordAdminAuthProvider implements IAdminAuthProvider {
+  public constructor(private readonly settings: () => Settings) {}
+
+  public async handleLogin(request: Request, response: Response): Promise<void> {
+    const validation = validateSchema(adminLoginBodySchema)(request.body)
+    if (validation.error) {
+      response.status(400).setHeader('content-type', 'application/json').send({ error: 'Invalid request' })
+      return
+    }
+
+    if (!this.verifyPassword(validation.value.password)) {
+      response.status(401).setHeader('content-type', 'application/json').send({ error: 'Unauthorized' })
+      return
+    }
+
+    const currentSettings = this.settings()
+    const sessionTtlSeconds = resolveAdminSessionTtlSeconds(currentSettings.admin?.sessionTtlSeconds)
+    const expiresAt = Math.floor(Date.now() / 1000) + sessionTtlSeconds
+
+    try {
+      const token = createAdminSessionToken(expiresAt)
+
+      response
+        .status(200)
+        .setHeader('content-type', 'application/json')
+        .setHeader('Set-Cookie', buildAdminSessionCookieHeader(request, currentSettings, token, sessionTtlSeconds))
+        .send({ authenticated: true, expiresAt })
+    } catch {
+      response.status(500).setHeader('content-type', 'application/json').send({ error: 'Internal Server Error' })
+    }
+  }
+
+  public isRequestAuthenticated(request: Request): boolean {
+    const token = this.getToken(request)
+    return token ? isValidAdminSessionToken(token) : false
+  }
+
+  public getSessionExpiresAt(request: Request): number | undefined {
+    const token = this.getToken(request)
+    return token ? parseAdminSessionToken(token)?.expiresAt : undefined
+  }
+
+  private getToken(request: Request): string | undefined {
+    return getAdminSessionTokenFromRequest(request.headers.authorization, request.headers.cookie)
+  }
+
+  private verifyPassword(password: string): boolean {
+    const envPassword = process.env.ADMIN_PASSWORD
+    if (typeof envPassword === 'string' && envPassword.length > 0) {
+      return verifyPlaintextPassword(password, envPassword)
+    }
+
+    const passwordHash = this.settings().admin?.passwordHash
+    if (!passwordHash) {
+      return false
+    }
+
+    return verifyAdminPasswordHash(password, passwordHash)
+  }
+}

src/controllers/admin/get-health-controller.ts

@@ -0,0 +1,11 @@
+import { Request, Response } from 'express'
+
+import { IController } from '../../@types/controllers'
+import { collectAdminHealthSnapshot } from '../../utils/admin-health'
+
+export class GetAdminHealthController implements IController {
+  public async handleRequest(_request: Request, response: Response): Promise<void> {
+    const health = await collectAdminHealthSnapshot()
+    response.status(200).setHeader('content-type', 'application/json').send(health)
+  }
+}

src/controllers/admin/get-session-controller.ts

@@ -0,0 +1,15 @@
+import { Request, Response } from 'express'
+
+import { IAdminAuthProvider } from '../../@types/admin'
+import { IController } from '../../@types/controllers'
+
+export class GetAdminSessionController implements IController {
+  public constructor(private readonly authProvider: IAdminAuthProvider) {}
+
+  public async handleRequest(request: Request, response: Response): Promise<void> {
+    response.status(200).setHeader('content-type', 'application/json').send({
+      authenticated: true,
+      expiresAt: this.authProvider.getSessionExpiresAt(request),
+    })
+  }
+}

src/controllers/admin/post-login-controller.ts

@@ -0,0 +1,12 @@
+import { Request, Response } from 'express'
+
+import { IAdminAuthProvider } from '../../@types/admin'
+import { IController } from '../../@types/controllers'
+
+export class PostAdminLoginController implements IController {
+  public constructor(private readonly authProvider: IAdminAuthProvider) {}
+
+  public async handleRequest(request: Request, response: Response): Promise<void> {
+    await this.authProvider.handleLogin(request, response)
+  }
+}

src/factories/admin-auth-provider-factory.ts

@@ -0,0 +1,7 @@
+import { PasswordAdminAuthProvider } from '../admin/password-admin-auth-provider'
+import { IAdminAuthProvider } from '../@types/admin'
+import { createSettings } from './settings-factory'
+
+export const createAdminAuthProvider = (): IAdminAuthProvider => {
+  return new PasswordAdminAuthProvider(createSettings)
+}

src/factories/controllers/get-admin-health-controller-factory.ts

@@ -0,0 +1,6 @@
+import { GetAdminHealthController } from '../../controllers/admin/get-health-controller'
+import { IController } from '../../@types/controllers'
+
+export const createGetAdminHealthController = (): IController => {
+  return new GetAdminHealthController()
+}