Add admin-scoped Hermes runtime reads and isolated pinned HTTP inventory

This commit is contained in:
devops committed 2026-10-23 12:53:06 +00:00
1 parent 5507fbcb29
commit 4b17a6fcc3
14 files changed
+685

No files matched your search

@@ -0,0 +1,83 @@
import { Test } from '@nestjs/testing';
import { INestApplication } from '@nestjs/common';
import { PassportModule } from '@nestjs/passport';
import { Strategy, ExtractJwt } from 'passport-jwt';
import passport from 'passport';
import { sign } from 'jsonwebtoken';
import request from 'supertest';
import { RuntimeReadModule } from './runtime-read.module';
import { HermesIntegrationService } from './hermes-integration.service';
describe('runtime HTTP authentication and read contract', () => {
let app: INestApplication;
const health = jest.fn().mockResolvedValue({ ok: true, auth_required: true });
beforeAll(async () => {
passport.use(
'jwt',
new Strategy(
{
jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
secretOrKey: 'test-only-http-key',
},
(payload, done) => done(null, { id: payload.sub, role: payload.role }),
),
);
const module = await Test.createTestingModule({
imports: [
PassportModule,
RuntimeReadModule.register({ 'admin-1': ['default'] }),
],
})
.overrideProvider(HermesIntegrationService)
.useValue({ health })
.compile();
app = module.createNestApplication();
await app.init();
});
afterAll(async () => {
await app.close();
passport.unuse('jwt');
});
it('rejects missing and forged credentials before upstream', async () => {
health.mockClear();
await request(app.getHttpServer())
.get('/admin/orchestration/runtime/health')
.expect(401);
await request(app.getHttpServer())
.get('/admin/orchestration/runtime/health')
.set(
'Authorization',
'Bearer ' + sign({ sub: 'admin-1', role: 'Admin' }, 'forged'),
)
.expect(401);
expect(health).not.toHaveBeenCalled();
});
it('accepts verified allowlisted admin but rejects signed ungranted subject', async () => {
await request(app.getHttpServer())
.get('/admin/orchestration/runtime/health')
.set(
'Authorization',
'Bearer ' + sign({ sub: 'other', role: 'Admin' }, 'test-only-http-key'),
)
.expect(403);
const r = await request(app.getHttpServer())
.get('/admin/orchestration/runtime/health')
.set(
'Authorization',
'Bearer ' +
sign({ sub: 'admin-1', role: 'Admin' }, 'test-only-http-key'),
)
.expect(200);
expect(r.body).toEqual({ ok: true, auth_required: true });
expect(r.headers['set-cookie']).toBeUndefined();
});
it('does not register mutation handlers', async () => {
await request(app.getHttpServer())
.post('/admin/orchestration/runtime/schedules')
.set(
'Authorization',
'Bearer ' +
sign({ sub: 'admin-1', role: 'Admin' }, 'test-only-http-key'),
)
.expect(404);
});
});
@@ -0,0 +1,169 @@
import {
Controller,
Get,
Req,
Query,
UseGuards,
Injectable,
ForbiddenException,
ServiceUnavailableException,
HttpException,
} from '@nestjs/common';
import { AuthGuard } from '@nestjs/passport';
import {
HermesIntegrationService,
RuntimePrincipal,
} from './hermes-integration.service';
import { HermesError } from './hermes.adapter';
export interface VerifiedRuntimeRequest {
user?: {
id?: string;
role?: string;
isApiKey?: boolean;
profiles?: string[];
};
}
@Injectable()
export class RuntimeReadAccess {
private readonly grants: Readonly<Record<string, readonly string[]>>;
constructor(grants: Readonly<Record<string, readonly string[]>>) {
const copy: Record<string, readonly string[]> = Object.create(null);
for (const [subject, profiles] of Object.entries(grants)) {
if (
!subject ||
!Array.isArray(profiles) ||
profiles.length === 0 ||
profiles.some((p) => !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(p))
)
throw new Error('Invalid runtime access configuration');
copy[subject] = Object.freeze([...profiles]);
}
this.grants = Object.freeze(copy);
}
principal(req: VerifiedRuntimeRequest): RuntimePrincipal {
const u = req.user;
if (
!u?.id ||
u.isApiKey ||
!['admin', 'superadmin'].includes(
(u.role ?? '').toLowerCase().replace(/[_-]/g, ''),
) ||
!Object.hasOwn(this.grants, u.id)
)
throw new ForbiddenException('Runtime access denied');
return { subject: u.id, profiles: this.grants[u.id] };
}
authorize(
p: RuntimePrincipal,
permission: string,
profile?: string,
): Promise<boolean> {
return Promise.resolve(
permission === 'runtime.read' &&
Object.hasOwn(this.grants, p.subject) &&
(!profile || this.grants[p.subject].includes(profile)),
);
}
}
@Controller('admin/orchestration/runtime')
@UseGuards(AuthGuard('jwt'))
export class RuntimeReadController {
constructor(
private readonly runtime: HermesIntegrationService,
private readonly access: RuntimeReadAccess,
) {}
private async read(
req: VerifiedRuntimeRequest,
call: (p: RuntimePrincipal) => Promise<unknown>,
) {
const p = this.access.principal(req);
try {
return await call(p);
} catch (e) {
if (e instanceof HermesError) {
if (e.code === 'FORBIDDEN')
throw new ForbiddenException('Runtime access denied');
if (e.code === 'LIMIT')
throw new HttpException('Runtime request limit', 429);
}
throw new ServiceUnavailableException('Runtime unavailable');
}
}
private profile(
q: Record<string, unknown>,
p: RuntimePrincipal,
extras: string[] = [],
): string {
if (
Object.keys(q).some((k) => !['profile', ...extras].includes(k)) ||
typeof q.profile !== 'string' ||
!p.profiles.includes(q.profile)
)
throw new HermesError('FORBIDDEN');
return q.profile;
}
private number(
q: Record<string, unknown>,
key: string,
fallback: number,
min: number,
max: number,
): number {
if (q[key] === undefined) return fallback;
if (typeof q[key] !== 'string' || !/^\d+$/.test(q[key]))
throw new HermesError('LIMIT');
const n = Number(q[key]);
if (!Number.isSafeInteger(n) || n < min || n > max)
throw new HermesError('LIMIT');
return n;
}
@Get('health') health(@Req() req: VerifiedRuntimeRequest) {
return this.read(req, (p) => this.runtime.health(p));
}
@Get('profiles') profiles(@Req() req: VerifiedRuntimeRequest) {
return this.read(req, (p) => this.runtime.profiles(p));
}
@Get('status') status(
@Req() req: VerifiedRuntimeRequest,
@Query() q: Record<string, unknown>,
) {
return this.read(req, (p) => this.runtime.status(p, this.profile(q, p)));
}
@Get('usage') usage(
@Req() req: VerifiedRuntimeRequest,
@Query() q: Record<string, unknown>,
) {
return this.read(req, (p) =>
this.runtime.usage(
p,
this.profile(q, p, ['days']),
this.number(q, 'days', 30, 1, 365),
),
);
}
@Get('sessions') sessions(
@Req() req: VerifiedRuntimeRequest,
@Query() q: Record<string, unknown>,
) {
return this.read(req, (p) =>
this.runtime.sessions(
p,
this.profile(q, p, ['limit', 'offset']),
this.number(q, 'limit', 20, 1, 100),
this.number(q, 'offset', 0, 0, 10000),
),
);
}
@Get('schedules') schedules(
@Req() req: VerifiedRuntimeRequest,
@Query() q: Record<string, unknown>,
) {
return this.read(req, (p) => this.runtime.crons(p, this.profile(q, p)));
}
@Get('model-info') modelInfo(
@Req() req: VerifiedRuntimeRequest,
@Query() q: Record<string, unknown>,
) {
return this.read(req, (p) => this.runtime.modelInfo(p, this.profile(q, p)));
}
}
@@ -0,0 +1,48 @@
import { DynamicModule, Module } from '@nestjs/common';
import { open } from 'node:fs/promises';
import { HermesManagementModule } from './hermes-management.module';
import {
RuntimeReadAccess,
RuntimeReadController,
} from './runtime-read.controller';
import { HermesError } from './hermes.adapter';
export async function runtimeSecret(path: string): Promise<string> {
if (!/^\/run\/secrets\/[a-zA-Z0-9_-]+$/.test(path))
throw new HermesError('CONFIGURATION');
try {
const file = await open(path, 'r');
try {
const stat = await file.stat();
if (!stat.isFile() || stat.size > 4096) throw new Error();
const value = (await file.readFile('utf8')).trim();
if (!value || /[\r\n]/.test(value)) throw new Error();
return value;
} finally {
await file.close();
}
} catch {
throw new HermesError('AUTH_REQUIRED');
}
}
@Module({})
export class RuntimeReadModule {
static register(
grants: Readonly<Record<string, readonly string[]>>,
): DynamicModule {
const access = new RuntimeReadAccess(grants);
return {
module: RuntimeReadModule,
imports: [
HermesManagementModule.registerAuthenticated(
async () => ({
username: await runtimeSecret('/run/secrets/hermes_username'),
password: await runtimeSecret('/run/secrets/hermes_password'),
}),
access,
),
],
controllers: [RuntimeReadController],
providers: [{ provide: RuntimeReadAccess, useValue: access }],
};
}
}
@@ -0,0 +1,75 @@
import { Test } from '@nestjs/testing';
import {
RuntimeReadController,
RuntimeReadAccess,
} from './runtime-read.controller';
import { HermesIntegrationService } from './hermes-integration.service';
import { HermesError } from './hermes.adapter';
import {
ForbiddenException,
ServiceUnavailableException,
} from '@nestjs/common';
describe('runtime read boundary', () => {
const health = jest.fn();
const profiles = jest.fn();
const status = jest.fn();
const service = {
health,
profiles,
status,
} as unknown as HermesIntegrationService;
const access = new RuntimeReadAccess({ 'admin-1': ['default'] });
const controller = new RuntimeReadController(service, access);
beforeEach(() => jest.clearAllMocks());
it('denies unconfigured identity without IO', async () => {
await expect(
controller.health({ user: { id: 'other', role: 'Admin' } }),
).rejects.toBeInstanceOf(ForbiddenException);
expect(health).not.toHaveBeenCalled();
});
it('uses server scope not body or user supplied profiles', async () => {
status.mockResolvedValue({ overall: 'ok' });
await expect(
controller.status(
{ user: { id: 'admin-1', role: 'Admin', profiles: ['other'] } },
{ profile: 'other' },
),
).rejects.toBeInstanceOf(ForbiddenException);
expect(status).not.toHaveBeenCalled();
await controller.status(
{ user: { id: 'admin-1', role: 'Admin' } },
{ profile: 'default' },
);
expect(status).toHaveBeenCalledWith(
{ subject: 'admin-1', profiles: ['default'] },
'default',
);
});
it('rejects duplicate/missing/unknown query parameters before IO', async () => {
for (const q of [
{},
{ profile: ['default', 'other'] },
{ profile: 'default', token: 'leak' },
])
await expect(
controller.status({ user: { id: 'admin-1', role: 'Admin' } }, q),
).rejects.toBeInstanceOf(ForbiddenException);
expect(status).not.toHaveBeenCalled();
});
it('maps credential failure without leaking upstream errors', async () => {
health.mockRejectedValue(new HermesError('AUTH_REQUIRED'));
await expect(
controller.health({ user: { id: 'admin-1', role: 'Admin' } }),
).rejects.toThrow('Runtime unavailable');
});
it('rejects API keys and non-admins even when subject is configured', async () => {
for (const user of [
{ id: 'admin-1', role: 'User' },
{ id: 'admin-1', role: 'Admin', isApiKey: true },
])
await expect(controller.health({ user })).rejects.toBeInstanceOf(
ForbiddenException,
);
expect(health).not.toHaveBeenCalled();
});
});