@bi-analytics/arness-back 0.0.0-stage → 0.3.0

package/harness/skills/nest-base/templates/monitor/monitor-session.service.spec.ts

@@ -0,0 +1,57 @@
+// Plantilla del harness → src/common/monitor/monitor-session.service.spec.ts
+import { ConfigService } from '@nestjs/config';
+import { JwtService } from '@nestjs/jwt';
+import { MonitorSessionService, readCookie } from './monitor-session.service';
+
+const env: Record<string, string> = {
+  MONITOR_ENABLED: 'true',
+  ACCESS_TOKEN: 'example123',
+  JWT_ACCESS_SECRET: 'test-access-secret-with-enough-length',
+  MONITOR_SESSION_EXPIRES_IN: '10m',
+};
+const config = (overrides: Record<string, string> = {}): ConfigService =>
+  new ConfigService({ ...env, ...overrides });
+
+describe('MonitorSessionService', () => {
+  const jwt = new JwtService({});
+  const service = new MonitorSessionService(config(), jwt);
+
+  it('is disabled unless MONITOR_ENABLED is true', () => {
+    expect(service.isEnabled()).toBe(true);
+    expect(new MonitorSessionService(config({ MONITOR_ENABLED: 'false' }), jwt).isEnabled()).toBe(
+      false,
+    );
+  });
+
+  it('compares the password with ACCESS_TOKEN', () => {
+    expect(service.verifyPassword('example123')).toBe(true);
+    expect(service.verifyPassword('example12')).toBe(false);
+    expect(new MonitorSessionService(config({ ACCESS_TOKEN: '' }), jwt).verifyPassword('')).toBe(
+      false,
+    );
+  });
+
+  it('issues an HttpOnly, Secure, SameSite=Strict cookie scoped to /monitor', async () => {
+    const cookie = await service.createSessionCookie();
+    expect(cookie).toMatch(
+      /^arness_monitor=[\w-]+\.[\w-]+\.[\w-]+; Max-Age=600; Path=\/monitor; HttpOnly; Secure; SameSite=Strict$/,
+    );
+    expect(await service.hasValidSession(cookie.split(';')[0])).toBe(true);
+  });
+
+  it('rejects missing, tampered and non-monitor tokens', async () => {
+    const accessToken = await jwt.signAsync({ type: 'access' }, { secret: env.JWT_ACCESS_SECRET });
+    expect(await service.hasValidSession(undefined)).toBe(false);
+    expect(await service.hasValidSession('arness_monitor=abc.def.ghi')).toBe(false);
+    expect(await service.hasValidSession(`arness_monitor=${accessToken}`)).toBe(false);
+  });
+
+  it('clears the cookie on logout', () => {
+    expect(service.clearSessionCookie()).toContain('arness_monitor=; Max-Age=0; Path=/monitor');
+  });
+
+  it('reads a cookie from the header', () => {
+    expect(readCookie('a=1; arness_monitor=xyz; b=2', 'arness_monitor')).toBe('xyz');
+    expect(readCookie(undefined, 'arness_monitor')).toBeUndefined();
+  });
+});

package/harness/skills/nest-base/templates/monitor/monitor-session.service.ts

@@ -0,0 +1,77 @@
+// Plantilla del harness → src/common/monitor/monitor-session.service.ts
+import { Injectable } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { JwtService, JwtSignOptions } from '@nestjs/jwt';
+import { createHash, timingSafeEqual } from 'node:crypto';
+import {
+  MONITOR_COOKIE,
+  MONITOR_DEFAULT_SESSION_EXPIRES_IN,
+  MONITOR_HOME_URL,
+  MONITOR_TOKEN_TYPE,
+} from './monitor.constants';
+
+const sha256 = (value: string): Buffer => createHash('sha256').update(value).digest();
+
+/** Reads one cookie from a raw Cookie header without extra dependencies. */
+export function readCookie(header: string | undefined, name: string): string | undefined {
+  for (const part of (header ?? '').split(';')) {
+    const index = part.indexOf('=');
+    if (index > 0 && part.slice(0, index).trim() === name) return part.slice(index + 1).trim();
+  }
+  return undefined;
+}
+
+@Injectable()
+export class MonitorSessionService {
+  constructor(
+    private readonly config: ConfigService,
+    private readonly jwt: JwtService,
+  ) {}
+
+  isEnabled(): boolean {
+    const value = this.config.get<unknown>('MONITOR_ENABLED');
+    return value === true || value === 'true';
+  }
+
+  /** Same comparison as /auth/login: sha256 of both values and timingSafeEqual. */
+  verifyPassword(candidate: string): boolean {
+    const expected = this.config.get<string>('ACCESS_TOKEN') ?? '';
+    return expected.length > 0 && timingSafeEqual(sha256(candidate), sha256(expected));
+  }
+
+  async createSessionCookie(): Promise<string> {
+    const expiresIn = (this.config.get<string>('MONITOR_SESSION_EXPIRES_IN') ||
+      MONITOR_DEFAULT_SESSION_EXPIRES_IN) as JwtSignOptions['expiresIn'];
+    const token = await this.jwt.signAsync(
+      { type: MONITOR_TOKEN_TYPE },
+      { secret: this.secret(), expiresIn },
+    );
+    const { exp, iat } = this.jwt.decode<{ exp: number; iat: number }>(token);
+    return this.cookie(token, exp - iat);
+  }
+
+  clearSessionCookie(): string {
+    return this.cookie('', 0);
+  }
+
+  async hasValidSession(cookieHeader: string | undefined): Promise<boolean> {
+    const token = readCookie(cookieHeader, MONITOR_COOKIE);
+    if (!token) return false;
+    try {
+      const payload = await this.jwt.verifyAsync<{ type?: string }>(token, {
+        secret: this.secret(),
+      });
+      return payload.type === MONITOR_TOKEN_TYPE;
+    } catch {
+      return false;
+    }
+  }
+
+  private secret(): string {
+    return this.config.getOrThrow<string>('JWT_ACCESS_SECRET');
+  }
+
+  private cookie(value: string, maxAgeSeconds: number): string {
+    return `${MONITOR_COOKIE}=${value}; Max-Age=${maxAgeSeconds}; Path=${MONITOR_HOME_URL}; HttpOnly; Secure; SameSite=Strict`;
+  }
+}

package/harness/skills/nest-base/templates/monitor/monitor-widget.interface.ts

@@ -0,0 +1,18 @@
+// Plantilla del harness → src/common/monitor/monitor-widget.interface.ts
+export interface MonitorValue {
+  /** Main figure shown on the card. Never secrets, SQL, driver errors or business data. */
+  value: string | number;
+  /** Optional breakdown (label → value). */
+  detail?: ReadonlyArray<{ label: string; value: string | number }>;
+}
+
+export interface MonitorWidget {
+  readonly id: string;
+  readonly title: string;
+  /** Ascending position on the page. */
+  readonly order: number;
+  collect(): Promise<MonitorValue>;
+}
+
+/** Multi-provider token: every widget registered in MonitorModule. */
+export const MONITOR_WIDGETS = Symbol('MONITOR_WIDGETS');

package/harness/skills/nest-base/templates/monitor/monitor.constants.ts

@@ -0,0 +1,25 @@
+// Plantilla del harness → src/common/monitor/monitor.constants.ts (AGENTS.md §10).
+export const MONITOR_PATH = 'monitor';
+export const MONITOR_LOGIN_URL = `/${MONITOR_PATH}/login`;
+export const MONITOR_HOME_URL = `/${MONITOR_PATH}`;
+export const MONITOR_COOKIE = 'arness_monitor';
+export const MONITOR_TOKEN_TYPE = 'monitor';
+export const MONITOR_DEFAULT_SESSION_EXPIRES_IN = '15m';
+export const MONITOR_WIDGET_TIMEOUT_MS = 2000;
+
+/** Route segments that never count as business endpoints. */
+export const MONITOR_EXCLUDED_SEGMENTS: ReadonlySet<string> = new Set([
+  MONITOR_PATH,
+  'health',
+  'auth',
+]);
+
+/** Sent on every monitor response: no scripts, no framing, no caching. */
+export const MONITOR_SECURITY_HEADERS: Readonly<Record<string, string>> = Object.freeze({
+  'Content-Security-Policy':
+    "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'",
+  'Cache-Control': 'no-store',
+  'X-Frame-Options': 'DENY',
+  'X-Content-Type-Options': 'nosniff',
+  'Referrer-Policy': 'no-referrer',
+});

package/harness/skills/nest-base/templates/monitor/monitor.controller.ts

@@ -0,0 +1,84 @@
+// Plantilla del harness → src/common/monitor/monitor.controller.ts
+import { Body, Controller, Get, Post, Req, Res, UseFilters, UseGuards } from '@nestjs/common';
+import type { Request, Response } from 'express';
+import { LoginAttemptLimiter } from '../security/login-attempts';
+import {
+  MONITOR_HOME_URL,
+  MONITOR_LOGIN_URL,
+  MONITOR_PATH,
+  MONITOR_SECURITY_HEADERS,
+} from './monitor.constants';
+import { MonitorLogin, MonitorRoute } from './monitor.decorators';
+import { MonitorLoginRedirectFilter } from './monitor-login-redirect.filter';
+import { MonitorLoginDto } from './monitor-login.dto';
+import { renderLoginPage, renderMonitorPage } from './monitor-page';
+import { MonitorSessionGuard } from './monitor-session.guard';
+import { MonitorSessionService } from './monitor-session.service';
+import { MonitorService } from './monitor.service';
+
+function sendHtml(res: Response, status: number, html: string): void {
+  res.status(status).set(MONITOR_SECURITY_HEADERS).type('html').send(html);
+}
+
+/** Fuera de /api/v1. No es @Public(): lo protege MonitorSessionGuard con cookie, no el Bearer. */
+@MonitorRoute()
+@UseGuards(MonitorSessionGuard)
+@UseFilters(MonitorLoginRedirectFilter)
+@Controller(MONITOR_PATH)
+export class MonitorController {
+  constructor(
+    private readonly monitor: MonitorService,
+    private readonly session: MonitorSessionService,
+    private readonly attempts: LoginAttemptLimiter,
+  ) {}
+
+  @Get()
+  async page(@Res() res: Response): Promise<void> {
+    sendHtml(res, 200, renderMonitorPage(await this.monitor.collect(), new Date()));
+  }
+
+  @MonitorLogin()
+  @Get('login')
+  loginForm(@Res() res: Response): void {
+    sendHtml(res, 200, renderLoginPage());
+  }
+
+  @MonitorLogin()
+  @Post('login')
+  async login(
+    @Body() body: MonitorLoginDto,
+    @Req() req: Request,
+    @Res() res: Response,
+  ): Promise<void> {
+    // Same limiter as /auth/login (contrato-http.md, Límite de intentos).
+    const client = req.ip ?? 'unknown';
+    const status = this.attempts.check(client);
+    if (!status.allowed) {
+      const minutes = Math.ceil(status.retryAfterSeconds / 60);
+      res.setHeader('Retry-After', String(status.retryAfterSeconds));
+      sendHtml(
+        res,
+        429,
+        renderLoginPage(`Demasiados intentos. Intenta de nuevo en ${minutes} min.`),
+      );
+      return;
+    }
+    if (!this.session.verifyPassword(body.password)) {
+      this.attempts.registerFailure(client);
+      sendHtml(res, 401, renderLoginPage('Contraseña incorrecta'));
+      return;
+    }
+    this.attempts.reset(client);
+    res
+      .set(MONITOR_SECURITY_HEADERS)
+      .setHeader('Set-Cookie', await this.session.createSessionCookie());
+    res.redirect(303, MONITOR_HOME_URL);
+  }
+
+  @MonitorLogin()
+  @Post('logout')
+  logout(@Res() res: Response): void {
+    res.set(MONITOR_SECURITY_HEADERS).setHeader('Set-Cookie', this.session.clearSessionCookie());
+    res.redirect(303, MONITOR_LOGIN_URL);
+  }
+}

package/harness/skills/nest-base/templates/monitor/monitor.decorators.ts

@@ -0,0 +1,11 @@
+// Plantilla del harness → src/common/monitor/monitor.decorators.ts
+import { CustomDecorator, SetMetadata } from '@nestjs/common';
+
+export const IS_MONITOR_ROUTE_KEY = 'arness:monitor-route';
+export const IS_MONITOR_LOGIN_KEY = 'arness:monitor-login';
+
+/** Marks the monitor controller: JwtAuthGuard skips it and MonitorSessionGuard protects it instead. */
+export const MonitorRoute = (): CustomDecorator<string> => SetMetadata(IS_MONITOR_ROUTE_KEY, true);
+
+/** Monitor handlers reachable without a session (login form, login and logout). */
+export const MonitorLogin = (): CustomDecorator<string> => SetMetadata(IS_MONITOR_LOGIN_KEY, true);

package/harness/skills/nest-base/templates/monitor/monitor.module.ts

@@ -0,0 +1,30 @@
+// Plantilla del harness → src/common/monitor/monitor.module.ts
+import { Module } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import { JwtModule } from '@nestjs/jwt';
+import { MonitorController } from './monitor.controller';
+import { MonitorSessionGuard } from './monitor-session.guard';
+import { MonitorSessionService } from './monitor-session.service';
+import { MonitorService } from './monitor.service';
+import { MONITOR_WIDGETS, MonitorWidget } from './monitor-widget.interface';
+import { EndpointsTotalWidget } from './widgets/endpoints-total.widget';
+
+/** Widgets del tablero: agrega la clase a WIDGETS (playbook new-monitor-widget). */
+const WIDGETS = [EndpointsTotalWidget];
+
+@Module({
+  imports: [DiscoveryModule, JwtModule.register({})],
+  controllers: [MonitorController],
+  providers: [
+    MonitorService,
+    MonitorSessionService,
+    MonitorSessionGuard,
+    ...WIDGETS,
+    {
+      provide: MONITOR_WIDGETS,
+      useFactory: (...widgets: MonitorWidget[]): MonitorWidget[] => widgets,
+      inject: WIDGETS,
+    },
+  ],
+})
+export class MonitorModule {}

package/harness/skills/nest-base/templates/monitor/monitor.service.spec.ts

@@ -0,0 +1,55 @@
+// Plantilla del harness → src/common/monitor/monitor.service.spec.ts
+import { Test } from '@nestjs/testing';
+import { MONITOR_WIDGETS, MonitorWidget } from './monitor-widget.interface';
+import { MonitorService } from './monitor.service';
+
+const widget = (id: string, order: number, collect: MonitorWidget['collect']): MonitorWidget => ({
+  id,
+  title: id,
+  order,
+  collect,
+});
+
+describe('MonitorService', () => {
+  const build = async (widgets: MonitorWidget[]): Promise<MonitorService> => {
+    const moduleRef = await Test.createTestingModule({
+      providers: [MonitorService, { provide: MONITOR_WIDGETS, useValue: widgets }],
+    }).compile();
+    return moduleRef.get(MonitorService);
+  };
+
+  it('returns the widgets ordered by order', async () => {
+    const service = await build([
+      widget('b', 20, () => Promise.resolve({ value: 2 })),
+      widget('a', 10, () => Promise.resolve({ value: 1 })),
+    ]);
+    expect((await service.collect()).map((c) => c.id)).toEqual(['a', 'b']);
+  });
+
+  it('marks a failing widget as unavailable without exposing the error', async () => {
+    const service = await build([
+      widget('ok', 1, () => Promise.resolve({ value: 7 })),
+      widget('broken', 2, () =>
+        Promise.reject(new Error('password authentication failed for user "x"')),
+      ),
+      widget('throws', 3, () => {
+        throw new Error('sync');
+      }),
+    ]);
+    const cards = await service.collect();
+    expect(cards).toEqual([
+      { id: 'ok', title: 'ok', status: 'ok', value: { value: 7 } },
+      { id: 'broken', title: 'broken', status: 'unavailable' },
+      { id: 'throws', title: 'throws', status: 'unavailable' },
+    ]);
+  });
+
+  it('marks a slow widget as unavailable', async () => {
+    jest.useFakeTimers();
+    const service = await build([widget('slow', 1, () => new Promise(() => undefined))]);
+    const pending = service.collect();
+    await jest.advanceTimersByTimeAsync(2000);
+    expect((await pending)[0].status).toBe('unavailable');
+    jest.useRealTimers();
+  });
+});

package/harness/skills/nest-base/templates/monitor/monitor.service.ts

@@ -0,0 +1,49 @@
+// Plantilla del harness → src/common/monitor/monitor.service.ts
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import { MONITOR_WIDGET_TIMEOUT_MS } from './monitor.constants';
+import { MONITOR_WIDGETS, MonitorValue, MonitorWidget } from './monitor-widget.interface';
+
+export interface MonitorCard {
+  id: string;
+  title: string;
+  status: 'ok' | 'unavailable';
+  value?: MonitorValue;
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error('timeout')), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+@Injectable()
+export class MonitorService {
+  private readonly logger = new Logger(MonitorService.name);
+
+  constructor(@Inject(MONITOR_WIDGETS) private readonly widgets: MonitorWidget[]) {}
+
+  /** A failing or slow widget becomes "unavailable"; the page always renders. */
+  async collect(): Promise<MonitorCard[]> {
+    const ordered = [...this.widgets].sort((a, b) => a.order - b.order || a.id.localeCompare(b.id));
+    return Promise.all(
+      ordered.map(async (widget): Promise<MonitorCard> => {
+        const { id, title } = widget;
+        try {
+          const value = await withTimeout(
+            Promise.resolve().then(() => widget.collect()),
+            MONITOR_WIDGET_TIMEOUT_MS,
+          );
+          return { id, title, status: 'ok', value };
+        } catch (error) {
+          // Only the error type: messages may carry SQL, hosts or data.
+          this.logger.warn(
+            `Monitor widget "${id}" unavailable (${error instanceof Error ? error.name : 'unknown'})`,
+          );
+          return { id, title, status: 'unavailable' };
+        }
+      }),
+    );
+  }
+}

package/harness/skills/nest-base/templates/monitor/widgets/endpoints-total.widget.spec.ts

@@ -0,0 +1,51 @@
+// Plantilla del harness → src/common/monitor/widgets/endpoints-total.widget.spec.ts
+import { Controller, Get, Post } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import { Test } from '@nestjs/testing';
+import { EndpointsTotalWidget } from './endpoints-total.widget';
+
+@Controller('cartera/resumen')
+class CarteraController {
+  @Get()
+  list(): void {}
+
+  @Get(['detalle', 'detalle-v2'])
+  detail(): void {}
+
+  helper(): void {}
+}
+
+@Controller()
+class RecaudoController {
+  @Get('recaudo/diario')
+  daily(): void {}
+}
+
+@Controller('auth')
+class AuthController {
+  @Post('login')
+  login(): void {}
+}
+
+@Controller('health')
+class HealthController {
+  @Get()
+  check(): void {}
+}
+
+describe('EndpointsTotalWidget', () => {
+  it('counts routes by module segment and skips auth, health and monitor', async () => {
+    const moduleRef = await Test.createTestingModule({
+      imports: [DiscoveryModule],
+      controllers: [CarteraController, RecaudoController, AuthController, HealthController],
+      providers: [EndpointsTotalWidget],
+    }).compile();
+    await expect(moduleRef.get(EndpointsTotalWidget).collect()).resolves.toEqual({
+      value: 4,
+      detail: [
+        { label: 'cartera', value: 3 },
+        { label: 'recaudo', value: 1 },
+      ],
+    });
+  });
+});

package/harness/skills/nest-base/templates/monitor/widgets/endpoints-total.widget.ts

@@ -0,0 +1,53 @@
+// Plantilla del harness → src/common/monitor/widgets/endpoints-total.widget.ts
+import { Injectable } from '@nestjs/common';
+import { PATH_METADATA, METHOD_METADATA } from '@nestjs/common/constants';
+import { DiscoveryService, MetadataScanner, Reflector } from '@nestjs/core';
+import { MONITOR_EXCLUDED_SEGMENTS } from '../monitor.constants';
+import { MonitorValue, MonitorWidget } from '../monitor-widget.interface';
+
+const toPaths = (value: string | string[] | undefined): string[] =>
+  (Array.isArray(value) ? value : [value ?? '']).map((path) => path.replace(/^\/+|\/+$/g, ''));
+
+/** Counts the HTTP routes of the API (excluding monitor, health and auth), grouped by module segment. */
+@Injectable()
+export class EndpointsTotalWidget implements MonitorWidget {
+  readonly id = 'endpoints-total';
+  readonly title = 'Endpoints de la API';
+  readonly order = 10;
+
+  constructor(
+    private readonly discovery: DiscoveryService,
+    private readonly scanner: MetadataScanner,
+    private readonly reflector: Reflector,
+  ) {}
+
+  collect(): Promise<MonitorValue> {
+    const byModule = new Map<string, number>();
+    for (const { metatype, instance } of this.discovery.getControllers()) {
+      if (!metatype || !instance) continue;
+      const prefixes = toPaths(
+        this.reflector.get<string | string[] | undefined>(PATH_METADATA, metatype),
+      );
+      const prototype = Object.getPrototypeOf(instance) as Record<string, unknown>;
+      for (const name of this.scanner.getAllMethodNames(prototype)) {
+        const handler = prototype[name];
+        if (typeof handler !== 'function') continue;
+        if (this.reflector.get<number | undefined>(METHOD_METADATA, handler) === undefined)
+          continue;
+        for (const prefix of prefixes) {
+          for (const path of toPaths(
+            this.reflector.get<string | string[] | undefined>(PATH_METADATA, handler),
+          )) {
+            const segment = [prefix, path].filter(Boolean).join('/').split('/')[0] || '/';
+            if (MONITOR_EXCLUDED_SEGMENTS.has(segment)) continue;
+            byModule.set(segment, (byModule.get(segment) ?? 0) + 1);
+          }
+        }
+      }
+    }
+    const detail = [...byModule.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([label, value]) => ({ label, value }));
+    return Promise.resolve({ value: detail.reduce((sum, item) => sum + item.value, 0), detail });
+  }
+}

package/harness/skills/nest-base/templates/prettierignore

@@ -0,0 +1,6 @@
+dist
+coverage
+node_modules
+pnpm-lock.yaml
+postman
+harness

package/harness/skills/nest-base/templates/prettierrc.json

@@ -0,0 +1,8 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100,
+  "semi": true,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/harness/skills/nest-base/templates/security/login-attempts.spec.ts

@@ -0,0 +1,48 @@
+// Plantilla del harness → src/common/security/login-attempts.spec.ts
+import { LoginAttemptLimiter } from './login-attempts';
+
+describe('LoginAttemptLimiter', () => {
+  let now: number;
+  const limiter = (maxTrackedClients?: number): LoginAttemptLimiter =>
+    new LoginAttemptLimiter({ maxAttempts: 3, windowSeconds: 60, maxTrackedClients }, () => now);
+
+  beforeEach(() => {
+    now = 1_000_000;
+  });
+
+  it('blocks a client after maxAttempts failures until the window ends', () => {
+    const attempts = limiter();
+    expect(attempts.registerFailure('10.0.0.1')).toEqual({ allowed: true, retryAfterSeconds: 0 });
+    attempts.registerFailure('10.0.0.1');
+    expect(attempts.registerFailure('10.0.0.1')).toEqual({ allowed: false, retryAfterSeconds: 60 });
+
+    now += 59_500;
+    expect(attempts.check('10.0.0.1')).toEqual({ allowed: false, retryAfterSeconds: 1 });
+
+    now += 500;
+    expect(attempts.check('10.0.0.1')).toEqual({ allowed: true, retryAfterSeconds: 0 });
+  });
+
+  it('counts each client separately', () => {
+    const attempts = limiter();
+    for (let i = 0; i < 3; i += 1) attempts.registerFailure('10.0.0.1');
+    expect(attempts.check('10.0.0.1').allowed).toBe(false);
+    expect(attempts.check('10.0.0.2').allowed).toBe(true);
+  });
+
+  it('a successful login resets the counter', () => {
+    const attempts = limiter();
+    attempts.registerFailure('10.0.0.1');
+    attempts.registerFailure('10.0.0.1');
+    attempts.reset('10.0.0.1');
+    expect(attempts.registerFailure('10.0.0.1').allowed).toBe(true);
+  });
+
+  it('never tracks more than maxTrackedClients', () => {
+    const attempts = limiter(2);
+    for (let i = 0; i < 3; i += 1) attempts.registerFailure('10.0.0.1');
+    attempts.registerFailure('10.0.0.2');
+    attempts.registerFailure('10.0.0.3');
+    expect(attempts.check('10.0.0.1').allowed).toBe(true);
+  });
+});

package/harness/skills/nest-base/templates/security/login-attempts.ts

@@ -0,0 +1,90 @@
+// Plantilla del harness → src/common/security/login-attempts.ts (AGENTS.md §8, contrato-http.md "Límite de intentos").
+// Counts failed logins per client in memory: one counter per instance, never depends on Redis.
+// /auth/login and /monitor/login share it.
+
+export interface LoginAttemptOptions {
+  maxAttempts: number;
+  windowSeconds: number;
+  /** Upper bound of tracked clients, so an attacker cannot grow the map without limit. */
+  maxTrackedClients?: number;
+}
+
+export interface LoginAttemptStatus {
+  allowed: boolean;
+  /** Seconds until the client can try again (0 when allowed). Goes to the Retry-After header. */
+  retryAfterSeconds: number;
+}
+
+interface Failures {
+  count: number;
+  resetAt: number;
+}
+
+const DEFAULT_MAX_TRACKED_CLIENTS = 10000;
+
+export class LoginAttemptLimiter {
+  private readonly failures = new Map<string, Failures>();
+  private readonly maxTrackedClients: number;
+
+  constructor(
+    private readonly options: LoginAttemptOptions,
+    private readonly now: () => number = Date.now,
+  ) {
+    this.maxTrackedClients = options.maxTrackedClients ?? DEFAULT_MAX_TRACKED_CLIENTS;
+  }
+
+  /** Call before comparing the password: a blocked client gets 429 without checking it. */
+  check(client: string): LoginAttemptStatus {
+    const entry = this.current(client);
+    if (!entry || entry.count < this.options.maxAttempts) {
+      return { allowed: true, retryAfterSeconds: 0 };
+    }
+    return { allowed: false, retryAfterSeconds: this.secondsUntil(entry.resetAt) };
+  }
+
+  /** Call after a wrong password. The window starts at the first failure. */
+  registerFailure(client: string): LoginAttemptStatus {
+    const entry = this.current(client);
+    if (entry) {
+      entry.count += 1;
+    } else {
+      this.makeRoom();
+      this.failures.set(client, {
+        count: 1,
+        resetAt: this.now() + this.options.windowSeconds * 1000,
+      });
+    }
+    return this.check(client);
+  }
+
+  /** Call after a successful login. */
+  reset(client: string): void {
+    this.failures.delete(client);
+  }
+
+  private current(client: string): Failures | undefined {
+    const entry = this.failures.get(client);
+    if (entry && entry.resetAt <= this.now()) {
+      this.failures.delete(client);
+      return undefined;
+    }
+    return entry;
+  }
+
+  private makeRoom(): void {
+    if (this.failures.size < this.maxTrackedClients) return;
+    const now = this.now();
+    for (const [client, entry] of this.failures) {
+      if (entry.resetAt <= now) this.failures.delete(client);
+    }
+    // Still full: drop the oldest entry (Map keeps insertion order).
+    if (this.failures.size >= this.maxTrackedClients) {
+      const oldest = this.failures.keys().next().value;
+      if (oldest !== undefined) this.failures.delete(oldest);
+    }
+  }
+
+  private secondsUntil(timestamp: number): number {
+    return Math.max(1, Math.ceil((timestamp - this.now()) / 1000));
+  }
+}