From b0f4636534a723df497047cad57bb76f6f0edbaa Mon Sep 17 00:00:00 2001 From: devops Date: Thu, 22 Oct 2026 18:40:19 +0000 Subject: [PATCH] feat(router-usage): add protected read-only consumption adapter with honest quota unknowns --- .../router-usage/router-usage.adapter.spec.ts | 71 +++++++++++++++++++ .../src/router-usage/router-usage.adapter.ts | 45 ++++++++++++ .../src/router-usage/router-usage.contract.ts | 37 ++++++++++ .../router-usage/router-usage.controller.ts | 22 ++++++ .../router-usage/router-usage.http.spec.ts | 36 ++++++++++ .../src/router-usage/router-usage.module.ts | 6 ++ backend/src/router-usage/router-usage.spec.ts | 28 ++++++++ docs/router-usage.md | 41 +++++++++++ 8 files changed, 286 insertions(+) create mode 100644 backend/src/router-usage/router-usage.adapter.spec.ts create mode 100644 backend/src/router-usage/router-usage.adapter.ts create mode 100644 backend/src/router-usage/router-usage.contract.ts create mode 100644 backend/src/router-usage/router-usage.controller.ts create mode 100644 backend/src/router-usage/router-usage.http.spec.ts create mode 100644 backend/src/router-usage/router-usage.module.ts create mode 100644 backend/src/router-usage/router-usage.spec.ts create mode 100644 docs/router-usage.md diff --git a/backend/src/router-usage/router-usage.adapter.spec.ts b/backend/src/router-usage/router-usage.adapter.spec.ts new file mode 100644 index 00000000..9cc3203f --- /dev/null +++ b/backend/src/router-usage/router-usage.adapter.spec.ts @@ -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(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); + }); +}); diff --git a/backend/src/router-usage/router-usage.adapter.ts b/backend/src/router-usage/router-usage.adapter.ts new file mode 100644 index 00000000..edb8e845 --- /dev/null +++ b/backend/src/router-usage/router-usage.adapter.ts @@ -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--; } + } +} diff --git a/backend/src/router-usage/router-usage.contract.ts b/backend/src/router-usage/router-usage.contract.ts new file mode 100644 index 00000000..18d29557 --- /dev/null +++ b/backend/src/router-usage/router-usage.contract.ts @@ -0,0 +1,37 @@ +type RecordValue = Record; +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'}, + }; }), + }; +} diff --git a/backend/src/router-usage/router-usage.controller.ts b/backend/src/router-usage/router-usage.controller.ts new file mode 100644 index 00000000..5933e2e0 --- /dev/null +++ b/backend/src/router-usage/router-usage.controller.ts @@ -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'); + } +} diff --git a/backend/src/router-usage/router-usage.http.spec.ts b/backend/src/router-usage/router-usage.http.spec.ts new file mode 100644 index 00000000..db03d697 --- /dev/null +++ b/backend/src/router-usage/router-usage.http.spec.ts @@ -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); + }); +}); diff --git a/backend/src/router-usage/router-usage.module.ts b/backend/src/router-usage/router-usage.module.ts new file mode 100644 index 00000000..434c4d76 --- /dev/null +++ b/backend/src/router-usage/router-usage.module.ts @@ -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 {} diff --git a/backend/src/router-usage/router-usage.spec.ts b/backend/src/router-usage/router-usage.spec.ts new file mode 100644 index 00000000..799c48ae --- /dev/null +++ b/backend/src/router-usage/router-usage.spec.ts @@ -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}); + }); +}); diff --git a/docs/router-usage.md b/docs/router-usage.md new file mode 100644 index 00000000..5b2a73ad --- /dev/null +++ b/docs/router-usage.md @@ -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.