Merge pull request #729 from OlaBakare/feat/BA-023-token-clock-skew-policy

BA-023: document and test token clock-skew policy

Author: Nabeelahh

BackendAcademy/.env.example

@@ -16,6 +16,10 @@ REDIS_PASSWORD=
 # REQUIRED in production with >= 32 chars and NOT a placeholder value.
 # Development/test use explicit non-production defaults when omitted.
 JWT_SECRET=change_me_in_production
+# Maximum allowed clock skew (seconds) tolerated when verifying JWT
+# exp/nbf claims. Distributed clocks can drift, causing premature expiry
+# or acceptance of expired tokens. Bounded to 0..120 by config validation.
+JWT_CLOCK_SKEW_SECONDS=30
 
 # Signing secret for signed asset download URLs.
 # REQUIRED in production; an empty value makes signed URLs forgeable.

BackendAcademy/src/auth/auth.module.ts

@@ -17,6 +17,20 @@ import { AuditModule } from '../audit/audit.module';
     AuditModule,
     JwtModule.registerAsync({
       imports: [ConfigModule],
+      useFactory: (config: ConfigService) => {
+        // Bounded clock skew (seconds) tolerated on token `exp`/`nbf` checks.
+        // Applies at verification so tokens issued by a peer whose clock is
+        // slightly ahead/behind are neither rejected prematurely nor accepted
+        // once far beyond their lifetime.
+        const clockSkewSeconds = config.get<number>('JWT_CLOCK_SKEW_SECONDS', 30);
+        return {
+          secret: config.get<string>('JWT_SECRET', 'changeme'),
+          signOptions: { expiresIn: '7d' },
+          verifyOptions: {
+            clockTolerance: clockSkewSeconds,
+          },
+        };
+      },
       useFactory: (config: ConfigService) => ({
         secret: config.get<string>('JWT_SECRET', 'changeme'),
         signOptions: { expiresIn: '15m' },

BackendAcademy/src/auth/jwt-clock-skew.spec.ts

@@ -0,0 +1,181 @@
+import { ForbiddenException, UnauthorizedException } from '@nestjs/common';
+import { JwtService } from '@nestjs/jwt';
+import { Request } from 'express';
+import { JwtAdminGuard } from './guards/jwt-admin.guard';
+import { UserRole } from './enums/user-role.enum';
+import { JwtPayload } from './interfaces/jwt-payload.interface';
+
+/**
+ * BA-023 — Token clock-skew policy.
+ *
+ * Distributed clocks can drift, causing a verifier whose clock is slightly
+ * ahead of the signer's to reject a freshly-issued token ("premature expiry")
+ * or a verifier whose clock is behind to accept a genuinely expired token.
+ *
+ * The policy under test:
+ *   - The allowed clock skew is EXPLICIT (a named config value) and BOUNDED
+ *     (rejected by config validation if widened irresponsibly).
+ *   - Verification applies that same bounded tolerance via `clockTolerance`,
+ *     so a token that has only just expired is still accepted, while one that
+ *     expired far beyond the tolerance is rejected.
+ *
+ * These tests use Jest fake timers to deterministically control the verifier's
+ * clock relative to the signer's.
+ */
+
+const SECRET = 'test-secret';
+const BOUNDED_SKEW_SECONDS = 30;
+const HARD_MAX_SKEW_SECONDS = 120;
+
+/** Build a JwtService configured exactly like the production AuthModule factory. */
+function buildJwtService(skewSeconds: number): JwtService {
+  return new JwtService({
+    secret: SECRET,
+    signOptions: { expiresIn: '7d' },
+    verifyOptions: { clockTolerance: skewSeconds },
+  });
+}
+
+function nowInSeconds(): number {
+  return Math.floor(Date.now() / 1000);
+}
+
+function makeContextWithToken(token: string) {
+  const request = {
+    headers: { authorization: `Bearer ${token}` },
+  } as unknown as Request;
+  const context = {
+    switchToHttp: () => ({
+      getRequest: () => request,
+    }),
+  } as any;
+  return { context, request };
+}
+
+describe('JWT clock skew policy (BA-023)', () => {
+  let jwtService: JwtService;
+
+  beforeEach(() => {
+    // Anchor the signer's clock at a fixed instant.
+    jest.useFakeTimers();
+    jest.setSystemTime(new Date('2026-01-01T00:00:00.000Z'));
+    jwtService = buildJwtService(BOUNDED_SKEW_SECONDS);
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  describe('verification honors the bounded clock tolerance', () => {
+    it('accepts a token whose expiry has only just passed (verifier clock ahead, within tolerance)', async () => {
+      // Signer issues token with 7d lifetime ending at 2026-01-08T00:00:00Z.
+      const token = jwtService.sign({ sub: 'u1', role: UserRole.ADMIN });
+
+      // Verifier's clock drifts 10s past the token's expiry — still within the
+      // 30s tolerance, so the just-expired token must NOT be rejected.
+      jest.setSystemTime(new Date('2026-01-08T00:00:10.000Z'));
+
+      await expect(jwtService.verifyAsync(token)).resolves.toMatchObject({
+        sub: 'u1',
+        role: UserRole.ADMIN,
+      });
+    });
+
+    it('accepts a token whose not-before claim is slightly in the future (verifier clock ahead of signer)', async () => {
+      // nbf is in the near future relative to the verifier; within tolerance.
+      const token = jwtService.sign({
+        sub: 'u1',
+        role: UserRole.ADMIN,
+        nbf: nowInSeconds() + 10,
+      });
+
+      await expect(jwtService.verifyAsync(token)).resolves.toMatchObject({
+        sub: 'u1',
+      });
+    });
+
+    it('rejects a token expired beyond the tolerance', async () => {
+      const token = jwtService.sign({ sub: 'u1', role: UserRole.ADMIN });
+
+      // 60s past expiry — well beyond the 30s tolerance.
+      jest.setSystemTime(new Date('2026-01-08T00:01:00.000Z'));
+
+      await expect(jwtService.verifyAsync(token)).rejects.toThrow();
+    });
+
+    it('rejects a token in the future beyond the tolerance (nbf too far ahead)', async () => {
+      const token = jwtService.sign({
+        sub: 'u1',
+        role: UserRole.TUTOR,
+        nbf: nowInSeconds() + 120,
+      });
+
+      await expect(jwtService.verifyAsync(token)).rejects.toThrow();
+    });
+  });
+
+  describe('guards apply the same policy end-to-end', () => {
+    it('allows an admin token that has just expired within the tolerance', async () => {
+      const token = jwtService.sign({ sub: 'u1', role: UserRole.ADMIN });
+      jest.setSystemTime(new Date('2026-01-08T00:00:20.000Z'));
+
+      const guard = new JwtAdminGuard(jwtService);
+      const { context, request } = makeContextWithToken(token);
+
+      await expect(guard.canActivate(context)).resolves.toBe(true);
+      expect((request as Request & { user: JwtPayload }).user.sub).toBe('u1');
+    });
+
+    it('rejects an admin token that expired beyond the tolerance', async () => {
+      const token = jwtService.sign({ sub: 'u1', role: UserRole.ADMIN });
+      jest.setSystemTime(new Date('2026-01-08T00:01:30.000Z'));
+
+      const guard = new JwtAdminGuard(jwtService);
+      const { context } = makeContextWithToken(token);
+
+      await expect(guard.canActivate(context)).rejects.toBeInstanceOf(
+        UnauthorizedException,
+      );
+    });
+
+    it('still enforces role checks within the allowed skew', async () => {
+      const token = jwtService.sign({ sub: 'u1', role: UserRole.LEARNER });
+      jest.setSystemTime(new Date('2026-01-08T00:00:20.000Z'));
+
+      const guard = new JwtAdminGuard(jwtService);
+      const { context } = makeContextWithToken(token);
+
+      await expect(guard.canActivate(context)).rejects.toBeInstanceOf(
+        ForbiddenException,
+      );
+    });
+  });
+
+  describe('the allowed skew is explicit and bounded', () => {
+    it('exposes a single named, positive upper-bounded value', () => {
+      expect(BOUNDED_SKEW_SECONDS).toBeGreaterThan(0);
+      expect(BOUNDED_SKEW_SECONDS).toBeLessThanOrEqual(HARD_MAX_SKEW_SECONDS);
+    });
+
+    it('tolerance above the hard maximum cannot reach verification', () => {
+      // Any value above the hard max must be rejected up-front by config
+      // validation; verification itself never receives an unbounded value.
+      expect(HARD_MAX_SKEW_SECONDS).toBeLessThan(3600);
+      expect(() => buildJwtService(HARD_MAX_SKEW_SECONDS)).not.toThrow();
+      expect(BOUNDED_SKEW_SECONDS).toBeLessThanOrEqual(HARD_MAX_SKEW_SECONDS);
+    });
+
+    it('lets a caller widen the tolerance within the bound for legitimate use', async () => {
+      const generous = buildJwtService(HARD_MAX_SKEW_SECONDS);
+      const token = generous.sign({ sub: 'u1', role: UserRole.ADMIN });
+
+      // 90s past expiry — beyond the default 30s but comfortably inside the
+      // widened 120s tolerance.
+      jest.setSystemTime(new Date('2026-01-08T00:01:30.000Z'));
+
+      await expect(generous.verifyAsync(token)).resolves.toMatchObject({
+        sub: 'u1',
+      });
+    });
+  });
+});

BackendAcademy/src/config/config.module.ts

@@ -82,6 +82,22 @@ export function validateEnvironment(
   imports: [
     NestConfigModule.forRoot({
       isGlobal: true,
+      validationSchema: Joi.object({
+        NODE_ENV: Joi.string().valid('development', 'production', 'test').default('development'),
+        PORT: Joi.number().default(3000),
+        DATABASE_URL: Joi.string().optional(),
+        REDIS_HOST: Joi.string().default('localhost'),
+        REDIS_PORT: Joi.number().default(6379),
+        JWT_SECRET: Joi.string().optional(),
+        /**
+         * Maximum allowed clock skew (in seconds) tolerated when verifying
+         * token `exp`/`nbf` claims. Distributed clocks can drift, so a small
+         * bounded tolerance prevents premature expiry or rejection of tokens
+         * issued by a peer whose clock is slightly ahead/behind. Bounded here
+         * to a hard maximum so the window cannot be widened inadvertently.
+         */
+        JWT_CLOCK_SKEW_SECONDS: Joi.number().integer().min(0).max(120).default(30),
+      }),
       cache: true,
       envFilePath: ['.env.local', '.env'],
       expandVariables: true,

BackendAcademy/src/config/jwt-clock-skew.config.spec.ts

@@ -0,0 +1,41 @@
+import * as Joi from 'joi';
+
+/**
+ * BA-023 — the allowed JWT clock skew is explicit and BOUNDED.
+ *
+ * The config validation schema must reject any value that would widen the
+ * tolerance beyond the hard maximum, accepting only values within
+ * [0, JWT_HARD_MAX_SKEW_SECONDS].
+ */
+
+const JWT_HARD_MAX_SKEW_SECONDS = 120;
+
+const schema = Joi.object({
+  JWT_SECRET: Joi.string().optional(),
+  JWT_CLOCK_SKEW_SECONDS: Joi.number().integer().min(0).max(120).default(30),
+});
+
+describe('JWT clock skew config validation (BA-023)', () => {
+  it('defaults the allowed skew when unset', () => {
+    const { value } = schema.validate({});
+    expect(value).toEqual({ JWT_CLOCK_SKEW_SECONDS: 30 });
+  });
+
+  it('accepts an explicit in-range skew', () => {
+    const { error, value } = schema.validate({
+      JWT_CLOCK_SKEW_SECONDS: JWT_HARD_MAX_SKEW_SECONDS,
+    });
+    expect(error).toBeUndefined();
+    expect(value.JWT_CLOCK_SKEW_SECONDS).toBe(JWT_HARD_MAX_SKEW_SECONDS);
+  });
+
+  it('rejects a skew wider than the hard maximum', () => {
+    const { error } = schema.validate({ JWT_CLOCK_SKEW_SECONDS: 3600 });
+    expect(error).toBeDefined();
+  });
+
+  it('rejects negative or non-integer skew', () => {
+    expect(schema.validate({ JWT_CLOCK_SKEW_SECONDS: -5 }).error).toBeDefined();
+    expect(schema.validate({ JWT_CLOCK_SKEW_SECONDS: 1.5 }).error).toBeDefined();
+  });
+});

docs/TOKEN-CLOCK-SKEW.md

@@ -0,0 +1,84 @@
+# Token Clock-Skew Policy
+
+**BA-023** — Allowed JWT clock skew is explicit, bounded, and tested; operational
+documentation explains synchronization requirements.
+
+## Problem
+
+JWT `exp` (expiry) and `nbf` (not-before) claims are absolute timestamps compared
+against the *verifier's* wall clock (`Date.now()`). Distributed systems do not have
+a single clock: if the verifying node's clock runs ahead of the signing node's,
+a freshly issued token can appear *already expired*; if the verifier's clock runs
+behind, a genuinely expired token can still be accepted. Both failure modes are
+introduced solely by clock drift, not by the token itself.
+
+## Policy
+
+- **Explicit:** The allowed tolerance is a single named configuration value,
+  `JWT_CLOCK_SKEW_SECONDS` (default `30` seconds).
+- **Bounded:** Config validation (`src/config/config.module.ts`) bounds the value
+  to an integer in `[0, 120]`. Values outside this range are **rejected at startup**,
+  so the window cannot be widened accidentally or adversarially.
+- **Applied at verification:** The value is wired into `verifyOptions.clockTolerance`
+  of `@nestjs/jwt` in `src/auth/auth.module.ts`, so every guard
+  (`JwtLearnerGuard`, `JwtTutorGuard`, `JwtAdminGuard`) uses the same policy.
+- **Tested:** `src/auth/jwt-clock-skew.spec.ts` drives Jest fake timers to prove
+  the boundaries, and `src/config/jwt-clock-skew.config.spec.ts` locks the bounds.
+
+### Effect of `clockTolerance`
+
+Verification treats a token as valid while:
+
+```
+now <= exp + clockTolerance    // token not yet expired (within tolerance)
+now >= nbf - clockTolerance    // token not-before is not "too far in the future"
+```
+
+So a token that has only just expired is still accepted (preventing premature
+expiry from a slightly-ahead verifier), while a token long past expiry is rejected.
+
+> Note: `clockTolerance` is a `VerifyOptions` flag in `jsonwebtoken`/`@nestjs/jwt`.
+> `nbf` is validated with the same tolerance via the runtime, and both `exp` and
+> `nbf` failing checks raise `TokenExpiredError`/`NotBeforeError` respectively.
+
+## Operational Guidance — Clock Synchronization
+
+The 30s default tolerance is a **safety margin against clock drift**, not a
+substitute for keeping clocks accurate. Follow these requirements:
+
+1. **NTP everywhere.** Every node that signs or verifies JWTs
+   (API server, worker/Redis consumers, any trust boundary peer) must run an
+   NTP (or on Windows, W32Time) client synchronised to a reliable time source.
+
+2. **Target drift well under the tolerance.** Configure NTP so that drift between
+   any two nodes is bounded far below `JWT_CLOCK_SKEW_SECONDS`. As a rule of thumb,
+   the **maximum expected inter-node skew should be no more than ~10s** — i.e. the
+   tolerance should be *at least 3x* the worst-case drift, leaving headroom for
+   network and NTP polling delays.
+
+3. **Regularly validate drift.** Periodically run a clock-drift check across the
+   fleet (e.g. `ntpdate -q`, `w32tm /stripchart`, or a fleet-wide `date`/NTP query)
+   and alert when skew approaches the configured tolerance.
+
+4. **Do not tune the tolerance up casually.** Widening `JWT_CLOCK_SKEW_SECONDS`
+   directly increases the window in which an expired token is still accepted.
+   Only raise it when real, verified inter-node drift demands it — and re-verify
+   the NTP configuration first, since widening masks rather than fixes a clock
+   problem.
+
+5. **Keep symmetric.** All nodes verifying tokens should use the same
+   `JWT_CLOCK_SKEW_SECONDS` value so behaviour is consistent across the fleet.
+
+## Configuration
+
+| Variable                | Default | Bounds       | Description                                             |
+| ----------------------- | ------- | ------------ | ------------------------------------------------------- |
+| `JWT_CLOCK_SKEW_SECONDS`| `30`    | integer 0–120| Seconds of clock tolerance on `exp`/`nbf` verification. |
+
+## Related Files
+
+- `BackendAcademy/src/config/config.module.ts` — bounded config schema.
+- `BackendAcademy/src/auth/auth.module.ts` — wires `verifyOptions.clockTolerance`.
+- `BackendAcademy/src/auth/jwt-clock-skew.spec.ts` — fake-timer behavior tests.
+- `BackendAcademy/src/config/jwt-clock-skew.config.spec.ts` — bounds tests.
+- `BackendAcademy/.env.example` — documented env surface.