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

.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
   /**
@@ -287,6 +299,7 @@ export interface WoTSettings {
 
 export interface Settings {
   info: Info
+  admin?: AdminSettings
   payments?: Payments
   paymentsProcessors?: PaymentsProcessors
   network: Network

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

@@ -0,0 +1,71 @@
+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
+    const token = createAdminSessionToken(expiresAt)
+
+    response
+      .status(200)
+      .setHeader('content-type', 'application/json')
+      .setHeader('Set-Cookie', buildAdminSessionCookieHeader(request, currentSettings, token, sessionTtlSeconds))
+      .send({ authenticated: true, expiresAt })
+  }
+
+  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()
+}

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

@@ -0,0 +1,7 @@
+import { GetAdminSessionController } from '../../controllers/admin/get-session-controller'
+import { IController } from '../../@types/controllers'
+import { createAdminAuthProvider } from '../admin-auth-provider-factory'
+
+export const createGetAdminSessionController = (): IController => {
+  return new GetAdminSessionController(createAdminAuthProvider())
+}

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

@@ -0,0 +1,7 @@
+import { PostAdminLoginController } from '../../controllers/admin/post-login-controller'
+import { IController } from '../../@types/controllers'
+import { createAdminAuthProvider } from '../admin-auth-provider-factory'
+
+export const createPostAdminLoginController = (): IController => {
+  return new PostAdminLoginController(createAdminAuthProvider())
+}

src/handlers/request-handlers/admin-rate-limit-middleware.ts

@@ -0,0 +1,27 @@
+import { NextFunction, Request, Response } from 'express'
+
+import { createSettings } from '../../factories/settings-factory'
+import { rateLimiterFactory } from '../../factories/rate-limiter-factory'
+import { isAdminRateLimited } from '../../utils/admin-rate-limit'
+
+const sendTooManyRequests = (response: Response) => {
+  response.status(429).setHeader('content-type', 'application/json').send({ error: 'Too many requests' })
+}
+
+export const adminLoginRateLimitMiddleware = async (request: Request, response: Response, next: NextFunction) => {
+  if (await isAdminRateLimited(request, createSettings(), rateLimiterFactory, 'login')) {
+    sendTooManyRequests(response)
+    return
+  }
+
+  next()
+}
+
+export const adminRateLimitMiddleware = async (request: Request, response: Response, next: NextFunction) => {
+  if (await isAdminRateLimited(request, createSettings(), rateLimiterFactory, 'admin')) {
+    sendTooManyRequests(response)
+    return
+  }
+
+  next()
+}

src/routes/admin/index.ts

@@ -0,0 +1,43 @@
+import { json, NextFunction, Request, Response, Router } from 'express'
+
+import { createAdminAuthProvider } from '../../factories/admin-auth-provider-factory'
+import { createGetAdminHealthController } from '../../factories/controllers/get-admin-health-controller-factory'
+import { createGetAdminSessionController } from '../../factories/controllers/get-admin-session-controller-factory'
+import { createPostAdminLoginController } from '../../factories/controllers/post-admin-login-controller-factory'
+import { createSettings } from '../../factories/settings-factory'
+import {
+  adminLoginRateLimitMiddleware,
+  adminRateLimitMiddleware,
+} from '../../handlers/request-handlers/admin-rate-limit-middleware'
+import { rateLimiterMiddleware } from '../../handlers/request-handlers/rate-limiter-middleware'
+import { withController } from '../../handlers/request-handlers/with-controller-request-handler'
+
+const router: Router = Router()
+
+const requireAdminEnabled = (_request: Request, response: Response, next: NextFunction) => {
+  const settings = createSettings()
+  if (!settings.admin?.enabled) {
+    response.status(404).setHeader('content-type', 'text/plain').send('Not Found')
+    return
+  }
+
+  next()
+}
+
+const requireAdminAuth = (request: Request, response: Response, next: NextFunction) => {
+  if (!createAdminAuthProvider().isRequestAuthenticated(request)) {
+    response.status(401).setHeader('content-type', 'application/json').send({ error: 'Unauthorized' })
+    return
+  }
+
+  next()
+}
+
+router.use(requireAdminEnabled)
+router.use(rateLimiterMiddleware)
+
+router.post('/login', adminLoginRateLimitMiddleware, json(), withController(createPostAdminLoginController))
+router.get('/session', adminRateLimitMiddleware, requireAdminAuth, withController(createGetAdminSessionController))
+router.get('/health', adminRateLimitMiddleware, requireAdminAuth, withController(createGetAdminHealthController))
+
+export default router

src/routes/index.ts

@@ -1,6 +1,7 @@
 import express, { Router } from 'express'
 
 import { nodeinfo21Handler, nodeinfoHandler } from '../handlers/request-handlers/nodeinfo-handler'
+import adminRouter from './admin'
 import admissionRouter from './admissions'
 import callbacksRouter from './callbacks'
 import { getHealthRequestHandler } from '../handlers/request-handlers/get-health-request-handler'
@@ -28,6 +29,7 @@ router.get('/.well-known/nodeinfo', nodeinfoHandler)
 router.get('/nodeinfo/2.1', nodeinfo21Handler)
 router.get('/nodeinfo/2.0', nodeinfo21Handler)
 
+router.use('/admin', adminRouter)
 router.use('/invoices', rateLimiterMiddleware, invoiceRouter)
 router.use('/admissions', rateLimiterMiddleware, admissionRouter)
 router.use('/callbacks', rateLimiterMiddleware, callbacksRouter)

src/schemas/admin-login-schema.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+
+export const adminLoginBodySchema = z
+  .object({
+    password: z.string().min(1),
+  })
+  .strict()

src/utils/admin-health.ts

@@ -0,0 +1,55 @@
+import { getCacheClient } from '../cache/client'
+import { getMasterDbClient } from '../database/client'
+
+export interface AdminDependencyHealth {
+  ok: boolean
+}
+
+export interface AdminHealthSnapshot {
+  status: 'ok' | 'degraded'
+  uptimeSeconds: number
+  worker: {
+    type: string
+    index?: string
+  }
+  database: AdminDependencyHealth
+  redis: AdminDependencyHealth
+}
+
+export const collectAdminHealthSnapshot = async (): Promise<AdminHealthSnapshot> => {
+  const database = await pingDatabase()
+  const redis = await pingRedis()
+
+  return {
+    status: database.ok && redis.ok ? 'ok' : 'degraded',
+    uptimeSeconds: Math.floor(process.uptime()),
+    worker: {
+      type: process.env.WORKER_TYPE ?? 'primary',
+      ...(process.env.WORKER_INDEX ? { index: process.env.WORKER_INDEX } : {}),
+    },
+    database,
+    redis,
+  }
+}
+
+const pingDatabase = async (): Promise<AdminDependencyHealth> => {
+  try {
+    await getMasterDbClient().raw('SELECT 1')
+    return { ok: true }
+  } catch {
+    return { ok: false }
+  }
+}
+
+const pingRedis = async (): Promise<AdminDependencyHealth> => {
+  try {
+    const client = getCacheClient()
+    if (!client.isOpen) {
+      await client.connect()
+    }
+    const pong = await client.ping()
+    return { ok: pong === 'PONG' }
+  } catch {
+    return { ok: false }
+  }
+}