fix(stage): isolate credentialless author bootstrap and recovery rehearsal
Stage author bootstrap (dedicated repair) / bootstrap (push) Failing after 3m55s

This commit is contained in:
Canina Automation committed 2026-10-28 19:52:55 +00:00
1 parent 6ed0e73311
commit 46da1c5339
30 files changed
+1295 -62

No files matched your search

+30
View File
@@ -0,0 +1,30 @@
import 'reflect-metadata';
import { NestFactory } from '@nestjs/core';
import { MaintenanceModule } from './maintenance.module';
import { assertStageScope } from '../admin/stage-author-restoration.service';
/** Exported for startup-contract testing; importing never starts a listener. */
export async function startMaintenance(
env: NodeJS.ProcessEnv = process.env,
create = (module: typeof MaintenanceModule) => NestFactory.create(module),
) {
// Deny before connecting to any infrastructure.
assertStageScope(env);
const port = Number(env.PORT);
if (!/^\d+$/.test(env.PORT || '') || !Number.isInteger(port) || port < 1 || port > 65535) {
throw new Error('Explicit valid maintenance PORT required');
}
const app = await create(MaintenanceModule);
app.setGlobalPrefix('api');
app.enableShutdownHooks();
await app.listen(port, '127.0.0.1');
return app;
}
if (require.main === module) {
startMaintenance().catch(() => {
// Do not emit connection strings or credentials on startup failure.
console.error('Maintenance startup failed');
process.exitCode = 1;
});
}
@@ -0,0 +1,10 @@
import { Injectable } from '@nestjs/common';
import { PrismaService } from '../prisma/prisma.service';
/** Connection lifecycle only: deliberately bypass PrismaService's startup DDL. */
@Injectable()
export class MaintenancePrismaService extends PrismaService {
async onModuleInit(): Promise<void> {
await this.$connect();
}
}
@@ -0,0 +1,23 @@
import { Controller, ForbiddenException, Post, Req, UseGuards } from '@nestjs/common';
import type { Request } from 'express';
import { StageAuthorRestorationService } from '../admin/stage-author-restoration.service';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
import { Roles } from '../common/decorators/roles.decorator';
import { RolesGuard } from '../common/guards/roles.guard';
import { HumanAdminGuard } from '../common/guards/human-admin.guard';
@Controller('admin/users')
@UseGuards(JwtAuthGuard, RolesGuard, HumanAdminGuard)
@Roles('Admin', 'SUPER_ADMIN')
export class MaintenanceController {
constructor(private readonly restoration: StageAuthorRestorationService) {}
@Post('stage-author-restoration')
async restoreStageAuthors(@Req() req: Request) {
// Never trust proxy headers for this administrative operation.
if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(req.socket?.remoteAddress || '')) {
throw new ForbiddenException('Loopback maintenance endpoint only');
}
return this.restoration.restoreStageAuthors();
}
}
@@ -0,0 +1,35 @@
import { Module, UnauthorizedException } from '@nestjs/common';
import { Reflector } from '@nestjs/core';
import { PrismaService } from '../prisma/prisma.service';
import { RedisService } from '../redis/redis.service';
import { UsersService } from '../users/users.service';
import { JwtStrategy } from '../auth/jwt.strategy';
import { JwtAuthGuard } from '../auth/jwt-auth.guard';
import { ApiKeysService } from '../admin/api-keys.service';
import { RolesGuard } from '../common/guards/roles.guard';
import { HumanAdminGuard } from '../common/guards/human-admin.guard';
import { StageAuthorRestorationService } from '../admin/stage-author-restoration.service';
import { MaintenancePrismaService } from './maintenance-prisma.service';
import { MaintenanceController } from './maintenance.controller';
/** No App/Auth/Admin/Prisma modules: their lifecycles are not maintenance-safe. */
@Module({
controllers: [MaintenanceController],
providers: [
{ provide: PrismaService, useClass: MaintenancePrismaService },
RedisService,
UsersService,
Reflector,
JwtStrategy,
// JwtAuthGuard requires this token. Reject rather than instantiate the
// API-key service or allow API keys to enter this JWT-only control plane.
{ provide: ApiKeysService, useValue: {
validateKey: async () => { throw new UnauthorizedException('JWT required'); },
} },
JwtAuthGuard,
RolesGuard,
HumanAdminGuard,
StageAuthorRestorationService,
],
})
export class MaintenanceModule {}
+109
View File
@@ -0,0 +1,109 @@
import { Test } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import { MODULE_METADATA } from '@nestjs/common/constants';
import { JwtService } from '@nestjs/jwt';
import request from 'supertest';
import { MaintenanceModule } from './maintenance.module';
import { MaintenancePrismaService } from './maintenance-prisma.service';
import { MaintenanceController } from './maintenance.controller';
import { PrismaService } from '../prisma/prisma.service';
import { RedisService } from '../redis/redis.service';
import { StageAuthorRestorationService } from '../admin/stage-author-restoration.service';
import { getJwtSecret } from '../auth/auth.constants';
import { startMaintenance } from './main';
describe('isolated maintenance runtime', () => {
let app: INestApplication;
const user = { id: 'admin-test', role: 'Admin', isPublicAuthor: false };
const prisma = { user: { findUnique: jest.fn() }, $connect: jest.fn(), $disconnect: jest.fn() };
const redis = { get: jest.fn() };
const restoration = { restoreStageAuthors: jest.fn() };
const jwt = new JwtService();
const token = (payload: Record<string, unknown> = {}, secret = getJwtSecret()) => jwt.sign({ sub: user.id, ...payload }, { secret, expiresIn: '5m' });
const post = (bearer?: string) => {
const req = request(app.getHttpServer()).post('/api/admin/users/stage-author-restoration');
return bearer ? req.set('Authorization', 'Bearer ' + bearer) : req;
};
beforeEach(async () => {
jest.clearAllMocks();
prisma.user.findUnique.mockResolvedValue(user);
redis.get.mockResolvedValue(null);
restoration.restoreStageAuthors.mockResolvedValue({ success: true });
const module = await Test.createTestingModule({ imports: [MaintenanceModule] })
.overrideProvider(PrismaService).useValue(prisma)
.overrideProvider(RedisService).useValue(redis)
.overrideProvider(StageAuthorRestorationService).useValue(restoration).compile();
app = module.createNestApplication();
app.setGlobalPrefix('api');
await app.listen(0, '127.0.0.1');
});
afterEach(async () => { await app?.close(); });
it('has no module imports, and exactly one small controller', () => {
expect(Reflect.getMetadata(MODULE_METADATA.IMPORTS, MaintenanceModule) || []).toEqual([]);
expect(Reflect.getMetadata(MODULE_METADATA.CONTROLLERS, MaintenanceModule)).toEqual([MaintenanceController]);
});
it('connects Prisma without invoking its DDL lifecycle', async () => {
const connect = jest.fn().mockResolvedValue(undefined);
const ddl = jest.fn();
await MaintenancePrismaService.prototype.onModuleInit.call({ $connect: connect, ensureTablesExist: ddl });
expect(connect).toHaveBeenCalledTimes(1);
expect(ddl).not.toHaveBeenCalled();
});
it('entrypoint only binds IPv4 loopback and uses env PORT', async () => {
const isolatedApp = { setGlobalPrefix: jest.fn(), enableShutdownHooks: jest.fn(), listen: jest.fn() };
const create = jest.fn().mockResolvedValue(isolatedApp);
await startMaintenance({ APP_ENV: 'stage', STAGE_AUTHOR_RESTORATION_ENABLED: 'true', STAGE_AUTHOR_RESTORATION_MODE: 'rehearsal', DATABASE_URL: 'postgresql://postgres@127.0.0.1:5432/rehearsal', PORT: '39071' }, create);
expect(create).toHaveBeenCalledWith(MaintenanceModule);
expect(isolatedApp.listen).toHaveBeenCalledWith(39071, '127.0.0.1');
await expect(startMaintenance({ PORT: '39071' }, create)).rejects.toThrow();
expect(create).toHaveBeenCalledTimes(1);
});
it('uses the real strategy and guards over loopback HTTP', async () => {
await post().expect(401);
await post('invalid').expect(401);
await post(token({}, 'wrong-secret')).expect(401);
expect(restoration.restoreStageAuthors).not.toHaveBeenCalled();
const access = token();
await post(access).expect(201, { success: true });
expect(redis.get).toHaveBeenCalledWith('bl_token:' + access);
expect(prisma.user.findUnique).toHaveBeenCalled();
expect(restoration.restoreStageAuthors).toHaveBeenCalledTimes(1);
expect(app.getHttpServer().address().address).toBe('127.0.0.1');
});
it('rejects expired and blacklisted sessions', async () => {
await post(jwt.sign({ sub: user.id }, { secret: getJwtSecret(), expiresIn: -1 })).expect(401);
redis.get.mockResolvedValue('revoked');
await post(token()).expect(401);
expect(restoration.restoreStageAuthors).not.toHaveBeenCalled();
});
it.each([
[{ ...user, role: 'User_PetOwner' }, 403],
[{ ...user, isPublicAuthor: true }, 401],
[{ ...user, isApiKey: true, scopes: ['admin'] }, 403],
[{ ...user, stageTestSession: 'test', stageTestGeneration: 'gen' }, 401],
[null, 401],
])('rejects unauthorized database principal %j', async (principal, status) => {
prisma.user.findUnique.mockResolvedValue(principal);
await post(token({ stageTestSession: 'test', stageTestGeneration: 'gen' })).expect(status);
expect(restoration.restoreStageAuthors).not.toHaveBeenCalled();
});
it('accepts SUPER_ADMIN but never accepts an API key', async () => {
prisma.user.findUnique.mockResolvedValue({ ...user, role: 'SUPER_ADMIN' });
await post(token()).expect(201);
restoration.restoreStageAuthors.mockClear();
await post().set('x-api-key', 'not-a-jwt').expect(401);
expect(restoration.restoreStageAuthors).not.toHaveBeenCalled();
});
it('exposes no ordinary app routes', async () => {
await request(app.getHttpServer()).get('/api/admin/users').expect(404);
await request(app.getHttpServer()).post('/api/auth/login').expect(404);
await request(app.getHttpServer()).get('/api/admin/users/stage-author-restoration').expect(404);
});
it.each([undefined, '10.0.0.2', '127.0.0.1.evil', '::ffff:10.0.0.2'])('ignores forwarded headers for non-loopback socket %s', async remoteAddress => {
const controller = new MaintenanceController(restoration as any);
await expect(controller.restoreStageAuthors({ socket: { remoteAddress }, headers: { 'x-forwarded-for': '127.0.0.1' } } as any)).rejects.toThrow();
expect(restoration.restoreStageAuthors).not.toHaveBeenCalled();
});
});