Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
b0f4636534 |
No files matched your search
@@ -0,0 +1,71 @@
|
||||
import { RouterUsageAdapter } from './router-usage.adapter';
|
||||
const stats = {totalRequests:0,totalPromptTokens:0,totalCompletionTokens:0,totalCachedTokens:0,byModel:{},byProvider:{},byAccount:{}};
|
||||
describe('bounded read-only adapter', () => {
|
||||
afterEach(() => jest.restoreAllMocks());
|
||||
it('uses only authenticated GET stats with a validated period and never follows redirects', async () => {
|
||||
const fetcher = jest.spyOn(global, 'fetch').mockResolvedValue(new Response(JSON.stringify(stats)));
|
||||
const adapter = new RouterUsageAdapter();
|
||||
process.env.ROUTER_USAGE_BASE_URL = 'https://nr.parsaaghayi.ir';
|
||||
process.env.ROUTER_USAGE_CLI_TOKEN = 'server-only-secret';
|
||||
const result = await adapter.summary('24h');
|
||||
expect(result.status).toBe('available');
|
||||
expect(result.attribution).toEqual({scope:'9router_total',hermes:null,additive:false});
|
||||
expect(fetcher).toHaveBeenCalledTimes(1);
|
||||
expect(fetcher).toHaveBeenCalledWith('https://nr.parsaaghayi.ir/api/usage/stats?period=24h', expect.objectContaining({method:'GET',redirect:'error',headers:{'x-9r-cli-token':'server-only-secret',Accept:'application/json'}}));
|
||||
expect(JSON.stringify(result)).not.toContain('server-only-secret');
|
||||
});
|
||||
it('rejects invalid time filters before IO', async () => {
|
||||
const fetcher = jest.spyOn(global,'fetch');
|
||||
await expect(new RouterUsageAdapter().summary('../providers')).rejects.toThrow();
|
||||
expect(fetcher).not.toHaveBeenCalled();
|
||||
});
|
||||
it('fails closed when credential is missing', async () => {
|
||||
delete process.env.ROUTER_USAGE_CLI_TOKEN;
|
||||
const fetcher = jest.spyOn(global,'fetch');
|
||||
const result = await new RouterUsageAdapter().summary('7d');
|
||||
expect(result).toMatchObject({status:'unavailable',data:null,reason:'not_configured'});
|
||||
expect(fetcher).not.toHaveBeenCalled();
|
||||
});
|
||||
it.each([401,403,429,500])('returns unknown data without upstream error text for %s', async status => {
|
||||
process.env.ROUTER_USAGE_CLI_TOKEN='secret';
|
||||
jest.spyOn(global,'fetch').mockResolvedValue(new Response('credential-secret',{status}));
|
||||
const result = await new RouterUsageAdapter().summary('7d');
|
||||
expect(result).toMatchObject({status:'unavailable',data:null,reason:'upstream_unavailable'});
|
||||
expect(JSON.stringify(result)).not.toContain('credential-secret');
|
||||
});
|
||||
it('rejects oversized bodies even without content length', async () => {
|
||||
process.env.ROUTER_USAGE_CLI_TOKEN='secret';
|
||||
jest.spyOn(global,'fetch').mockResolvedValue(new Response('x'.repeat(1048577)));
|
||||
expect(await new RouterUsageAdapter().summary('7d')).toMatchObject({status:'unavailable',data:null});
|
||||
});
|
||||
it('does not return stale last-good totals after a failure', async () => {
|
||||
process.env.ROUTER_USAGE_CLI_TOKEN='secret';
|
||||
jest.spyOn(global,'fetch').mockResolvedValueOnce(new Response(JSON.stringify(stats))).mockRejectedValueOnce(new Error('token-secret'));
|
||||
const adapter=new RouterUsageAdapter();
|
||||
expect((await adapter.summary('7d')).status).toBe('available');
|
||||
expect(await adapter.summary('7d')).toMatchObject({status:'unavailable',data:null});
|
||||
});
|
||||
});
|
||||
|
||||
describe('transport boundaries', () => {
|
||||
afterEach(()=>jest.restoreAllMocks());
|
||||
it('never sends credentials to a configured alternate origin', async()=>{
|
||||
process.env.ROUTER_USAGE_CLI_TOKEN='secret';
|
||||
process.env.ROUTER_USAGE_BASE_URL='https://attacker.invalid';
|
||||
const fetcher=jest.spyOn(global,'fetch');
|
||||
expect(await new RouterUsageAdapter().summary()).toMatchObject({status:'unavailable',reason:'invalid_configuration'});
|
||||
expect(fetcher).not.toHaveBeenCalled();
|
||||
delete process.env.ROUTER_USAGE_BASE_URL;
|
||||
});
|
||||
it('bounds simultaneous upstream calls and exposes no stale totals', async()=>{
|
||||
process.env.ROUTER_USAGE_CLI_TOKEN='secret';
|
||||
let resolve!: (value: Response) => void;
|
||||
const pending=new Promise<Response>(r=>{resolve=r;});
|
||||
jest.spyOn(global,'fetch').mockReturnValue(pending);
|
||||
const adapter=new RouterUsageAdapter();
|
||||
const calls=Array.from({length:4},()=>adapter.summary());
|
||||
expect(await adapter.summary()).toMatchObject({status:'unavailable',reason:'busy',data:null});
|
||||
resolve(new Response('',{status:503}));
|
||||
await Promise.all(calls);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,45 @@
|
||||
import { BadRequestException, Injectable } from '@nestjs/common';
|
||||
import { normalizeStats } from './router-usage.contract';
|
||||
export const ROUTER_PERIODS = ['today','24h','7d','30d','60d','all'] as const;
|
||||
@Injectable()
|
||||
export class RouterUsageAdapter {
|
||||
private active = 0;
|
||||
async summary(period = '7d') {
|
||||
if (!ROUTER_PERIODS.includes(period as typeof ROUTER_PERIODS[number])) throw new BadRequestException('Invalid period');
|
||||
const base = {source:'9router' as const,period,attribution:{scope:'9router_total',hermes:null,additive:false},
|
||||
capabilities:{errors:false,reasoningTokens:false,cacheWriteTokens:false,quota:false,customTimeRange:false},
|
||||
freshness:{retrievedAt:null as string | null,sourceUpdatedAt:null,stale:null as boolean | null}};
|
||||
const unavailable = (reason: string) => ({...base,status:'unavailable' as const,reason,data:null});
|
||||
const token=process.env.ROUTER_USAGE_CLI_TOKEN;
|
||||
if (!token) return unavailable('not_configured');
|
||||
if (this.active >= 4) return unavailable('busy');
|
||||
this.active++;
|
||||
const controller = new AbortController();
|
||||
const timeout = setTimeout(() => controller.abort(),5000);
|
||||
try {
|
||||
const url=new URL(process.env.ROUTER_USAGE_BASE_URL || 'https://nr.parsaaghayi.ir');
|
||||
if (url.origin !== 'https://nr.parsaaghayi.ir' || url.username || url.password || url.pathname !== '/' || url.search || url.hash) return unavailable('invalid_configuration');
|
||||
const response=await fetch(`${url.origin}/api/usage/stats?period=${period}`,{
|
||||
method:'GET',redirect:'error',signal:controller.signal,
|
||||
headers:{'x-9r-cli-token':token,Accept:'application/json'},
|
||||
});
|
||||
if (!response.ok || !response.body) throw new Error('Upstream unavailable');
|
||||
const reader=response.body.getReader();
|
||||
const chunks:Uint8Array[]=[];
|
||||
let size=0;
|
||||
try {
|
||||
while (true) {
|
||||
const {done,value}=await reader.read();
|
||||
if (done) break;
|
||||
size+=value.byteLength;
|
||||
if (size>1048576) {await reader.cancel(); throw new Error('Response too large');}
|
||||
chunks.push(value);
|
||||
}
|
||||
} finally { reader.releaseLock(); }
|
||||
const data=normalizeStats(JSON.parse(Buffer.concat(chunks).toString('utf8')));
|
||||
return {...base,status:'available' as const,reason:null,data,
|
||||
freshness:{retrievedAt:new Date().toISOString(),sourceUpdatedAt:null,stale:null}};
|
||||
} catch { return unavailable('upstream_unavailable'); }
|
||||
finally { clearTimeout(timeout); this.active--; }
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
type RecordValue = Record<string, unknown>;
|
||||
export function record(value: unknown): RecordValue {
|
||||
if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('Invalid upstream schema');
|
||||
return value as RecordValue;
|
||||
}
|
||||
function count(value: unknown): number | null {
|
||||
return typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 ? value : null;
|
||||
}
|
||||
function identifier(value: unknown): string | null {
|
||||
return typeof value === 'string' && /^[a-zA-Z0-9_./:@()+ -]{1,180}$/.test(value) && !value.includes('@') && !/^(sk-|Bearer )/i.test(value) ? value : null;
|
||||
}
|
||||
function metrics(row: RecordValue, prefix = '') {
|
||||
const key = (name: string) => prefix ? prefix + name[0].toUpperCase() + name.slice(1) : name;
|
||||
return {
|
||||
requests: count(row[key('requests')]), inputTokens: count(row[key('promptTokens')]),
|
||||
outputTokens: count(row[key('completionTokens')]), cacheReadTokens: count(row[key('cachedTokens')]),
|
||||
cacheWriteTokens: null, reasoningTokens: null, errors: null,
|
||||
};
|
||||
}
|
||||
export function normalizeStats(value: unknown) {
|
||||
const stats = record(value);
|
||||
if (count(stats.totalRequests) === null) throw new Error('Invalid stats');
|
||||
const rows = (key: string) => {
|
||||
const entries = Object.entries(record(stats[key]));
|
||||
if (entries.length > 2000) throw new Error('Too many aggregates');
|
||||
return entries;
|
||||
};
|
||||
return {
|
||||
totals: metrics(stats, 'total'),
|
||||
providers: rows('byProvider').map(([id, row]) => ({provider: identifier(id), ...metrics(record(row))})),
|
||||
models: rows('byModel').map(([, row]) => { const r = record(row); return {model: identifier(r.rawModel), provider: identifier(r.provider), ...metrics(r)}; }),
|
||||
accounts: rows('byAccount').map(([, row]) => { const r = record(row); return {
|
||||
accountId: identifier(r.connectionId), model: identifier(r.rawModel), provider: identifier(r.provider), ...metrics(r),
|
||||
quota: {status: 'unknown' as const, remaining: null, resetAt: null, reason: 'upstream_quota_get_mutates_credentials'},
|
||||
}; }),
|
||||
};
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
import { Controller, Get, Header, Query, UseGuards, ValidationPipe } from '@nestjs/common';
|
||||
import { AuthGuard } from '@nestjs/passport';
|
||||
import { IsIn, IsOptional } from 'class-validator';
|
||||
import { Roles } from '../common/decorators/roles.decorator';
|
||||
import { RolesGuard } from '../common/guards/roles.guard';
|
||||
import { ROUTER_PERIODS, RouterUsageAdapter } from './router-usage.adapter';
|
||||
export class RouterUsageQuery {
|
||||
@IsOptional()
|
||||
@IsIn(ROUTER_PERIODS)
|
||||
period?: string;
|
||||
}
|
||||
@Controller('admin/router-usage')
|
||||
@UseGuards(AuthGuard('jwt'), RolesGuard)
|
||||
@Roles('admin')
|
||||
export class RouterUsageController {
|
||||
constructor(private readonly adapter: RouterUsageAdapter) {}
|
||||
@Get()
|
||||
@Header('Cache-Control','private, no-store')
|
||||
summary(@Query(new ValidationPipe({transform:true,whitelist:true,forbidNonWhitelisted:true})) query: RouterUsageQuery) {
|
||||
return this.adapter.summary(query.period ?? '7d');
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
import { Test } from '@nestjs/testing';
|
||||
import { INestApplication, ValidationPipe } from '@nestjs/common';
|
||||
import { AuthGuard } from '@nestjs/passport';
|
||||
import request from 'supertest';
|
||||
import { RouterUsageModule } from './router-usage.module';
|
||||
import { RouterUsageAdapter } from './router-usage.adapter';
|
||||
|
||||
describe('protected router usage HTTP contract', () => {
|
||||
let app: INestApplication;
|
||||
const summary=jest.fn().mockResolvedValue({status:'available',data:{}});
|
||||
beforeAll(async () => {
|
||||
const module=await Test.createTestingModule({imports:[RouterUsageModule]})
|
||||
.overrideProvider(RouterUsageAdapter).useValue({summary})
|
||||
.overrideGuard(AuthGuard('jwt')).useValue({canActivate(context: any){
|
||||
const req=context.switchToHttp().getRequest();
|
||||
if (!req.headers.authorization) return false;
|
||||
req.user={role:req.headers.authorization}; return true;
|
||||
}}).compile();
|
||||
app=module.createNestApplication();
|
||||
app.useGlobalPipes(new ValidationPipe({transform:true,whitelist:true,forbidNonWhitelisted:true}));
|
||||
await app.init();
|
||||
});
|
||||
afterAll(async()=>app.close());
|
||||
it('blocks unauthenticated access', async()=>{ await request(app.getHttpServer()).get('/admin/router-usage').expect(403); });
|
||||
it('blocks non-admin users', async()=>{ await request(app.getHttpServer()).get('/admin/router-usage').set('Authorization','customer').expect(403); });
|
||||
it('permits admins and defaults to 7d', async()=>{
|
||||
await request(app.getHttpServer()).get('/admin/router-usage').set('Authorization','admin').expect(200);
|
||||
expect(summary).toHaveBeenCalledWith('7d');
|
||||
});
|
||||
it('rejects unsupported custom time range', async()=>{
|
||||
await request(app.getHttpServer()).get('/admin/router-usage?from=2026-01-01').set('Authorization','admin').expect(400);
|
||||
});
|
||||
it('rejects invalid period', async()=>{
|
||||
await request(app.getHttpServer()).get('/admin/router-usage?period=invalid').set('Authorization','admin').expect(400);
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,6 @@
|
||||
import { Module } from '@nestjs/common';
|
||||
import { RouterUsageController } from './router-usage.controller';
|
||||
import { RouterUsageAdapter } from './router-usage.adapter';
|
||||
import { RolesGuard } from '../common/guards/roles.guard';
|
||||
@Module({controllers:[RouterUsageController],providers:[RouterUsageAdapter,RolesGuard],exports:[RouterUsageAdapter]})
|
||||
export class RouterUsageModule {}
|
||||
@@ -0,0 +1,28 @@
|
||||
import { normalizeStats } from './router-usage.contract';
|
||||
|
||||
describe('9router stats allowlist', () => {
|
||||
it('maps real aggregate fields without leaking API-key map keys or account labels', () => {
|
||||
const result = normalizeStats({totalRequests:2,totalPromptTokens:10,totalCompletionTokens:4,totalCachedTokens:3,
|
||||
byProvider:{codex:{requests:2,promptTokens:10,completionTokens:4,cachedTokens:3}},
|
||||
byModel:{'m (codex)':{rawModel:'m',provider:'codex',requests:2}},
|
||||
byAccount:{'private@example.com':{rawModel:'m',provider:'codex',connectionId:'account-1',accountName:'private@example.com',requests:2}},
|
||||
byApiKey:{'SECRET-KEY|m':{apiKey:'SECRET-KEY'}},accessToken:'SECRET-TOKEN'});
|
||||
expect(result.totals).toEqual({requests:2,inputTokens:10,outputTokens:4,cacheReadTokens:3,cacheWriteTokens:null,reasoningTokens:null,errors:null});
|
||||
expect(result.models[0]).toMatchObject({model:'m',provider:'codex',requests:2});
|
||||
expect(result.accounts[0]).toMatchObject({accountId:'account-1',quota:{status:'unknown',remaining:null,resetAt:null,reason:'upstream_quota_get_mutates_credentials'}});
|
||||
expect(JSON.stringify(result)).not.toMatch(/SECRET|private@|accountName|byApiKey/);
|
||||
});
|
||||
});
|
||||
|
||||
describe('unknown rather than fabricated metrics', () => {
|
||||
const empty = {totalRequests:0,byProvider:{},byModel:{},byAccount:{}};
|
||||
it('preserves known zero and unknown missing counters separately', () => {
|
||||
expect(normalizeStats(empty).totals).toEqual({requests:0,inputTokens:null,outputTokens:null,cacheReadTokens:null,cacheWriteTokens:null,reasoningTokens:null,errors:null});
|
||||
});
|
||||
it.each([null,{},[],{...empty,totalRequests:-1},{...empty,byModel:null}])('rejects invalid schemas', value => {
|
||||
expect(()=>normalizeStats(value)).toThrow();
|
||||
});
|
||||
it('rejects unsafe metric values instead of coercing them to zero', () => {
|
||||
expect(normalizeStats({...empty,totalPromptTokens:'10',totalCompletionTokens:-4,totalCachedTokens:Infinity}).totals).toMatchObject({inputTokens:null,outputTokens:null,cacheReadTokens:null});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,41 @@
|
||||
# 9router admin consumption adapter
|
||||
|
||||
## Wiring (integration owner)
|
||||
Import `RouterUsageModule` from `backend/src/router-usage/router-usage.module` into the root application's imports. This branch deliberately does not edit app.module.ts. Existing AuthModule/JWT strategy must be registered by the application. Route requires a JWT bearer user with admin/superadmin role; API-key authentication is deliberately not enabled for this sensitive endpoint.
|
||||
|
||||
Set backend-only `ROUTER_USAGE_CLI_TOKEN` using the existing router CLI auth token from the operator secret store. Optional `ROUTER_USAGE_BASE_URL` must be exactly `https://nr.parsaaghayi.ir` (an origin slash is accepted). Do not ship this token to the frontend. No environment/configuration was changed during implementation. No push/deploy performed; integration follows CI/CD and production needs separate Gate2.
|
||||
|
||||
## Exact API
|
||||
`GET /admin/router-usage?period=7d` (plus the existing application global prefix, if any).
|
||||
Allowed periods: `today`, `24h`, `7d`, `30d`, `60d`, `all`; default `7d`. Unknown query properties/custom from/to ranges and invalid periods return 400. Missing/invalid JWT is rejected by Passport; authenticated non-admin gets 403. Response is private/no-store.
|
||||
|
||||
Response fields:
|
||||
- `source: "9router"`, `period`
|
||||
- `status: "available" | "unavailable"`
|
||||
- `reason: null | "not_configured" | "invalid_configuration" | "busy" | "upstream_unavailable"`
|
||||
- `attribution: {scope:"9router_total", hermes:null, additive:false}`
|
||||
- `freshness: {retrievedAt: ISO8601|null, sourceUpdatedAt:null, stale:null}`. Retrieval time is NOT a guarantee of provider freshness. The source exposes no authoritative updated-at for aggregates. No last-good cache is served.
|
||||
- `capabilities: {errors:false, reasoningTokens:false, cacheWriteTokens:false, quota:false, customTimeRange:false}`
|
||||
- `data: null | {totals, providers:[], models:[], accounts:[]}`
|
||||
|
||||
Every metrics object contains `requests`, `inputTokens`, `outputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `reasoningTokens`, `errors` (number|null). Zero is retained only if upstream reported zero; absent/invalid counters remain null. Input/output/cache map to promptTokens/completionTokens/cachedTokens; cache-read is a subset of input, never add it again. Cache-write/reasoning/errors are always null because the stats contract does not expose these aggregates.
|
||||
|
||||
Provider rows: `{provider,...metrics}`. Model rows: `{model,provider,...metrics}`. Account rows: `{accountId,model,provider,...metrics,quota:{status:"unknown",remaining:null,resetAt:null,reason:"upstream_quota_get_mutates_credentials"}}`. Account rows are upstream account/model summaries, NOT unique account inventory; accounts without usage are absent. IDs are validated, nullable if unsafe; account names/emails are never returned. No raw upstream maps, logs, prompts, provider data or credentials are returned. Dimensions are different views of the same consumption: do NOT sum totals+models+accounts. Hermes attribution remains unknown; do NOT add Hermes telemetry to router totals.
|
||||
|
||||
## Deployed-source inspection and real probe
|
||||
Read-only inspected running `9router` image `decolua/9router:vpn`: compiled `/app/.next/server/app/api/usage/stats/route.js`, `/app/.next/server/chunks/9100.js`, `/app/.next/server/middleware.js`, `/app/.next/server/chunks/7211.js`, providers routes and `/app/open-sse/services/usage.js`. No credential tables or router DB contents were dumped/modified.
|
||||
|
||||
Verified stats route accepts the periods above. `today` uses router-local midnight, `24h` rolling history; 7/30/60d use router-local daily buckets, `all` all retained daily aggregates. This is not arbitrary UTC timestamp filtering; retention/completeness is upstream-owned.
|
||||
|
||||
Authenticated internal GET probe returned HTTP 200, 5 provider summaries, 21 model summaries, 21 account/model summaries. Verified model fields: requests, promptTokens, completionTokens, cachedTokens, cost, rawModel, provider, lastUsed. Account fields additionally include connectionId/accountName. Only schema/counts printed; no keys or account values printed. Public HTTPS reverse proxy path was not live-authenticated, so its separate proxy authentication/network reachability remains an operator verification step.
|
||||
|
||||
Dashboard routes authenticate using `x-9r-cli-token` or valid `auth_token` session cookie. Normal inference API Bearer keys do NOT authenticate these dashboard routes. CLI token is NOT the contents of cli-secret: deployed middleware computes first 16 hex characters of SHA256(machine-id + "9r-cli-auth" + cli-secret). Probe derived it only inside the router process command and never emitted it; no new token or configuration was created.
|
||||
|
||||
**Security finding:** stats `byApiKey` map keys contain raw inference keys, even when row fields are masked. Adapter discards this map entirely and never logs response bodies/errors.
|
||||
|
||||
**Quota blocker:** `GET /api/usage/[connectionId]` calls refreshAndUpdateCredentials, including updateProviderConnection; OAuth refresh/retry can persist credentials. It is NOT read-only despite being GET. Therefore adapter does NOT call it. Provider quota handlers can return quotas (used/total/remaining/resetAt), messages or synthesized unlimited defaults; these cannot safely be treated as verified provider truth here. Quota reset grants exist in provider helpers but must never be consumed by this adapter. No safe deployed cache-only provider quota route was established. A separately reviewed router-side non-mutating, provenance/timestamp-bearing quota snapshot API is required before exposing live remaining/reset. Quota is unknown, never zero/unlimited fabricated. Connection inventory/status refresh is also not represented as quota truth.
|
||||
|
||||
## Bounds and verification
|
||||
Only fixed-origin authenticated GET `/api/usage/stats` is invoked; redirect:error, abort after 5 seconds, streaming cap 1 MiB, <=2000 rows per dimension, <=4 concurrent requests per backend process. No retries or stale cache. Schema/transport/auth/rate-limit/oversize failures produce unavailable + null data without raw errors. No SQL, POST or token refresh.
|
||||
|
||||
Strict test-first slices observed missing contract, adapter, module failures before implementation. Disposable containers used existing backend image dependencies, read-only source mounts, network disabled and copied source into ephemeral /work; no host dependencies/build output or running containers changed. `npm run build` passed. Focused: 3 suites/24 tests passed. Full backend regression: 92 suites/781 tests passed (existing negative-path tests log expected payment/SSL errors). HTTP guard tests replace JWT authentication only and exercise real RolesGuard; deployed JWT strategy remains application-owned.
|
||||
Reference in new issue
Block a user