One-Time Access Tokens: What If Every API Request Burned Its Token?

src/auth/ ├── auth.module.ts ├── auth.controller.ts ├── auth.service.ts ├── auth.config.ts ├── dto/login.dto.ts ├── guards/one-time-token.guard.ts ├── tokens/ │ ├── one-time-token.service.ts │ ├── one-time-token.repository.ts │ └── one-time-token.types.ts ├── decorators/ public, current-session └── utils/ bearer-token, password 

CREATE TABLE ota_chains ( id uuid PRIMARY KEY, user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE, created_at timestamptz NOT NULL DEFAULT now(), revoked_at timestamptz, revoke_reason text ); CREATE INDEX ota_chains_user_id_idx ON ota_chains (user_id); CREATE TABLE ota_tokens ( id uuid PRIMARY KEY, -- the JWT's jti chain_id uuid NOT NULL REFERENCES ota_chains(id) ON DELETE CASCADE, parent_id uuid REFERENCES ota_tokens(id), seq integer NOT NULL, status text NOT NULL DEFAULT 'active' CHECK (status IN ('active', 'used', 'revoked')), issued_at timestamptz NOT NULL DEFAULT now(), expires_at timestamptz NOT NULL, -- same instant as the JWT's exp used_at timestamptz, used_for text, -- e.g. "POST /orders" request_id text, -- correlation / trace id client_ip inet, UNIQUE (chain_id, seq) -- a chain cannot fork ); CREATE INDEX ota_tokens_expires_at_idx ON ota_tokens (expires_at); -- for pruning 

import { Inject, Injectable } from '@nestjs/common'; import { Pool } from 'pg'; import { PG_POOL } from '../../database/database.module'; import { NewToken, RequestContext, TokenStatus, TrailEntry } from './one-time-token.types'; @Injectable() export class OneTimeTokenRepository { constructor(@Inject(PG_POOL) private readonly db: Pool) {} async createChain(chainId: string, userId: string, first: NewToken): Promise<void> { await this.db.query( `WITH chain AS ( INSERT INTO ota_chains (id, user_id) VALUES ($1, $2) RETURNING id ) INSERT INTO ota_tokens (id, chain_id, seq, expires_at) SELECT $3, id, 1, to_timestamp($4) FROM chain`, [chainId, userId, first.jti, first.expiresAt], ); } /** * Burns the token and inserts its successor in a single statement. * The UPDATE takes a row lock, so of any number of concurrent requests * presenting the same token, exactly one gets a row back. */ async burnAndIssue(jti: string, next: NewToken, context: RequestContext): Promise<boolean> { const { rowCount } = await this.db.query( `WITH burned AS ( UPDATE ota_tokens t SET status = 'used', used_at = now(), used_for = $2, request_id = $3, client_ip = $4 WHERE t.id = $1 AND t.status = 'active' AND t.expires_at > now() AND EXISTS (SELECT 1 FROM ota_chains c WHERE c.id = t.chain_id AND c.revoked_at IS NULL) RETURNING t.id, t.chain_id, t.seq ) INSERT INTO ota_tokens (id, chain_id, parent_id, seq, expires_at) SELECT $5, chain_id, id, seq + 1, to_timestamp($6) FROM burned`, [jti, context.usedFor, context.requestId, context.clientIp, next.jti, next.expiresAt], ); return rowCount === 1; } async findStatus(jti: string): Promise<TokenStatus | undefined> { const { rows } = await this.db.query<{ status: TokenStatus }>( `SELECT status FROM ota_tokens WHERE id = $1`, [jti], ); return rows[0]?.status; } /** Returns false if the chain was already revoked. */ async revokeChain(chainId: string, reason: string): Promise<boolean> { const { rowCount } = await this.db.query( `WITH revoked AS ( UPDATE ota_chains SET revoked_at = now(), revoke_reason = $2 WHERE id = $1 AND revoked_at IS NULL RETURNING id ) UPDATE ota_tokens t SET status = 'revoked' FROM revoked WHERE t.chain_id = revoked.id AND t.status = 'active'`, [chainId, reason], ); return (rowCount ?? 0) > 0; } async findTrail(chainId: string): Promise<TrailEntry[]> { const { rows } = await this.db.query<TrailEntry>( `SELECT seq, status, used_for AS "usedFor", request_id AS "requestId", host(client_ip) AS "clientIp", used_at AS "usedAt" FROM ota_tokens WHERE chain_id = $1 ORDER BY seq`, [chainId], ); return rows; } } 

import { Inject, Injectable, Logger, UnauthorizedException } from '@nestjs/common'; import { ConfigType } from '@nestjs/config'; import { JwtService } from '@nestjs/jwt'; import { randomUUID } from 'node:crypto'; import { authConfig } from '../auth.config'; import { OneTimeTokenRepository } from './one-time-token.repository'; import { NewToken, RequestContext, Session, TokenClaims, TrailEntry } from './one-time-token.types'; export interface Rotation { session: Session; nextToken: string; } @Injectable() export class OneTimeTokenService { private readonly logger = new Logger(OneTimeTokenService.name); constructor( private readonly tokens: OneTimeTokenRepository, private readonly jwt: JwtService, @Inject(authConfig.KEY) private readonly config: ConfigType<typeof authConfig>, ) {} /** Starts a new chain for an authenticated user and returns its first token. */ async startChain(userId: string): Promise<string> { const chainId = randomUUID(); const first = this.newToken(); await this.tokens.createChain(chainId, userId, first); return this.sign({ userId, chainId, seq: 1 }, first); } /** Burns the presented token and returns the caller's session with the next token. */ async rotate(presented: string, context: RequestContext): Promise<Rotation> { const claims = await this.verifySignature(presented); const session: Session = { userId: claims.sub, chainId: claims.cid, seq: claims.seq }; const next = this.newToken(); const burned = await this.tokens.burnAndIssue(claims.jti, next, context); if (!burned) { await this.revokeIfReplayed(claims, context); throw new UnauthorizedException(); } return { session, nextToken: await this.sign({ ...session, seq: session.seq + 1 }, next) }; } revokeChain(chainId: string, reason: string): Promise<boolean> { return this.tokens.revokeChain(chainId, reason); } trail(chainId: string): Promise<TrailEntry[]> { return this.tokens.findTrail(chainId); } private newToken(): NewToken { return { jti: randomUUID(), expiresAt: Math.floor(Date.now() / 1000) + this.config.tokenTtlSeconds, }; } private sign(session: Session, token: NewToken): Promise<string> { return this.jwt.signAsync( { sub: session.userId, cid: session.chainId, seq: session.seq, exp: token.expiresAt }, { jwtid: token.jti }, ); } /** * Checks the signature only. Expiry is enforced by the burn statement, so * that a token which is both expired and already spent still counts as a * replay instead of being dismissed as "just expired". */ private async verifySignature(token: string): Promise<TokenClaims> { try { return await this.jwt.verifyAsync<TokenClaims>(token, { ignoreExpiration: true }); } catch { throw new UnauthorizedException(); } } /** A spent token coming back means two parties hold the same chain. */ private async revokeIfReplayed(claims: TokenClaims, context: RequestContext): Promise<void> { const status = await this.tokens.findStatus(claims.jti); if (status !== 'used') return; // expired, or the chain is already revoked await this.tokens.revokeChain(claims.cid, `replay of seq ${claims.seq}`); this.logger.warn({ event: 'one_time_token_replay', chainId: claims.cid, userId: claims.sub, seq: claims.seq, ...context, }); } } 

import { CanActivate, ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common'; import { Reflector } from '@nestjs/core'; import { Request, Response } from 'express'; import { randomUUID } from 'node:crypto'; import { isIP } from 'node:net'; import { IS_PUBLIC } from '../decorators/public.decorator'; import { OneTimeTokenService } from '../tokens/one-time-token.service'; import { NEXT_TOKEN_HEADER } from '../tokens/one-time-token.types'; import { extractBearerToken } from '../utils/bearer-token.util'; @Injectable() export class OneTimeTokenGuard implements CanActivate { constructor( private readonly reflector: Reflector, private readonly tokens: OneTimeTokenService, ) {} async canActivate(context: ExecutionContext): Promise<boolean> { const isPublic = this.reflector.getAllAndOverride<boolean>(IS_PUBLIC, [ context.getHandler(), context.getClass(), ]); if (isPublic) return true; const http = context.switchToHttp(); const request = http.getRequest<Request>(); const response = http.getResponse<Response>(); const token = extractBearerToken(request); if (!token) throw new UnauthorizedException(); const { session, nextToken } = await this.tokens.rotate(token, { usedFor: `${request.method} ${request.route?.path ?? request.path}`, requestId: request.header('x-request-id') ?? randomUUID(), clientIp: request.ip && isIP(Source：https://dev.to/marius_trelea_44abd6fb263/one-time-access-tokens-what-if-every-api-request-burned-its-token-2knj
My favorites