@wildo-ai/saas-backend-lib 1.0.1

package/dist/esm/security/consumable-tokens/services/__tests__/mock-consumable-token.service.js

@@ -0,0 +1,55 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * Vitest-oriented mock consumable-token service for backend tests.
+ *
+ * **Naming**: `mock-*.service.ts` — canonical mock module, not a test suite.
+ * Plain `.ts` keeps it barrel-compilable, and Vitest also excludes these files
+ * explicitly as a defensive guard.
+ */
+import 'reflect-metadata';
+import { injectable } from 'inversify';
+import { vi } from 'vitest';
+const tokenStore = new Map();
+export function resetMockConsumableTokenStore() {
+    tokenStore.clear();
+}
+let MockConsumableTokenService = class MockConsumableTokenService {
+    createToken = vi.fn(async (params) => {
+        const token = `tok_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+        tokenStore.set(token, {
+            metadata: params.metadata ?? {},
+            tokenType: params.tokenType,
+        });
+        return {
+            token,
+            _id: `id-${token}`,
+        };
+    });
+    consumeToken = vi.fn(async (token) => {
+        const stored = tokenStore.get(token);
+        if (!stored) {
+            const error = new Error('Token not found or already consumed');
+            error.customMessageReference = 'NOT_FOUND';
+            throw error;
+        }
+        tokenStore.delete(token);
+        return {
+            tokenType: stored.tokenType,
+            metadata: stored.metadata,
+        };
+    });
+    reset() {
+        this.createToken.mockClear();
+        this.consumeToken.mockClear();
+    }
+};
+MockConsumableTokenService = __decorate([
+    injectable()
+], MockConsumableTokenService);
+export { MockConsumableTokenService };
+//# sourceMappingURL=mock-consumable-token.service.js.map

package/dist/esm/security/consumable-tokens/services/__tests__/mock-consumable-token.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-consumable-token.service.js","sourceRoot":"","sources":["../../../../../../src/security/consumable-tokens/services/__tests__/mock-consumable-token.service.ts"],"names":[],"mappings":";;;;;;AAAA;;;;;;GAMG;AACH,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAO5B,MAAM,UAAU,GAAG,IAAI,GAAG,EAAqC,CAAC;AAEhE,MAAM,UAAU,6BAA6B;IAC3C,UAAU,CAAC,KAAK,EAAE,CAAC;AACrB,CAAC;AAGM,IAAM,0BAA0B,GAAhC,MAAM,0BAA0B;IACrC,WAAW,GAAG,EAAE,CAAC,EAAE,CACjB,KAAK,EAAE,MAKN,EAAE,EAAE;QACH,MAAM,KAAK,GAAG,OAAO,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;QAC7E,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE;YACpB,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,EAAE;YAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;SAC5B,CAAC,CAAC;QACH,OAAO;YACL,KAAK;YACL,GAAG,EAAE,MAAM,KAAK,EAAE;SACV,CAAC;IACb,CAAC,CACF,CAAC;IAEF,YAAY,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,KAAa,EAAE,EAAE;QAC3C,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;YAC9D,KAAqD,CAAC,sBAAsB,GAAG,WAAW,CAAC;YAC5F,MAAM,KAAK,CAAC;QACd,CAAC;QAED,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACzB,OAAO;YACL,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,QAAQ,EAAE,MAAM,CAAC,QAAQ;SACjB,CAAC;IACb,CAAC,CAAC,CAAC;IAEH,KAAK;QACH,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;QAC7B,IAAI,CAAC,YAAY,CAAC,SAAS,EAAE,CAAC;IAChC,CAAC;CACF,CAAA;AAvCY,0BAA0B;IADtC,UAAU,EAAE;GACA,0BAA0B,CAuCtC"}

package/dist/esm/security/consumable-tokens/services/consumable-token.backend.service.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Consumable Token Backend Service
+ *
+ * Central service for the full lifecycle of consumable tokens:
+ * - Token creation with crypto-secure random values
+ * - Token validation (expiry, consumption, revocation, type matching)
+ * - Atomic token consumption (race-condition safe via findOneAndUpdate)
+ * - Token revocation (soft invalidation via revokedAt)
+ * - Pipeline helpers for declarative tokenGeneration/tokenRevocation configs
+ *
+ * Security (R2): Raw token values are NEVER logged. Only token._id is logged.
+ */
+import { ConsumableToken_ConsumptionMode, type ConsumableTokenTypes, type TokenGenerationConfig, type TokenRevocationConfig, type ExecutionContext_RoleInfo } from '@wildo-ai/saas-models';
+import { type DurationValue } from '@wildo-ai/zod-decorators';
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service.js';
+import { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service.js';
+import { MongoDBService } from '../../../databases/services/mongodb.service.js';
+import type { ConsumableToken } from '../../../security/consumable-tokens/models/consumable-tokens.shared.schemas.js';
+export interface CreateTokenParams {
+    /** Token type identifier (e.g., CoreConsumableTokenTypes.FILE_PUBLIC_ACCESS). NOT the Wildo resource type. */
+    tokenType: ConsumableTokenTypes;
+    consumptionMode: ConsumableToken_ConsumptionMode;
+    expiresIn: DurationValue;
+    organizationId?: string;
+    userId?: string;
+    /** The Wildo resource identifier this token targets (e.g., 'users', 'files'). */
+    resourceIdentifier?: string;
+    relatedId?: string;
+    metadata?: Record<string, any>;
+    roles?: ExecutionContext_RoleInfo[];
+    maxUses?: number;
+    /** W7.3b: Whether this token can be exchanged for a one-off session JWT. */
+    createsOneOffSession?: boolean;
+    /** W7.3b: When the token is consumed — at exchange time or at target operation time. */
+    consumeAt?: 'EXCHANGE' | 'TARGET_OPERATION';
+    /** W7.3b: Scoped caller identity for audit and authorization narrowing. */
+    targeting?: {
+        initiatorIds?: Record<string, string>;
+    };
+}
+export interface TokenGenerationResult {
+    tokenValue: string;
+    tokenId: string;
+}
+export interface TokenRevocationResult {
+    revokedCount: number;
+}
+export declare class ConsumableTokenBackendService {
+    private readonly logger;
+    private readonly errorBuilder;
+    private readonly mongoDBService;
+    constructor(logger: LoggerService, errorBuilder: ErrorBuilderBackendService, mongoDBService: MongoDBService);
+    /**
+     * Create a new consumable token.
+     * Generates a 32-byte hex crypto-random token value and persists it.
+     *
+     * @returns The full entity WITH the raw token value (for passing to emails/responses).
+     *          NEVER log the returned token value (R2).
+     */
+    createToken(params: CreateTokenParams): Promise<ConsumableToken & {
+        token: string;
+    }>;
+    /**
+     * Validate a token without consuming it.
+     * Checks: existence, revocation, expiry, consumption status, type matching.
+     *
+     * @param tokenValue - The raw token string from the request
+     * @param expectedTypes - Optional array of accepted token types for this operation
+     * @returns The validated token entity
+     * @throws Appropriate error for each failure mode
+     */
+    validateToken(tokenValue: string, expectedTypes?: ConsumableTokenTypes[]): Promise<ConsumableToken>;
+    /**
+     * Atomically consume a token.
+     * Uses MongoDB `findOneAndUpdate` with conditions to prevent race conditions.
+     *
+     * - SINGLE_USE: condition `{ isConsumed: false }`, sets `{ isConsumed: true, usesCount: 1 }`
+     * - BOUNDED_REUSE: condition `{ usesCount: { $lt: maxUses } }`, inc `usesCount`, set `isConsumed` if exhausted
+     * - EPHEMERAL_STATE: condition `{ isConsumed: false }`, sets `{ isConsumed: true }`
+     *
+     * @param tokenValue - The raw token string
+     * @returns The updated token entity
+     * @throws CONSUMABLE_TOKEN_RACE_CONDITION if atomic update fails (concurrent consumption)
+     */
+    consumeToken(tokenValue: string): Promise<ConsumableToken>;
+    /**
+     * Soft-revoke a token by setting revokedAt.
+     * This is a soft invalidation — the record stays in DB for audit.
+     * Hard deletion is handled by the cleanup cron job.
+     */
+    revokeToken(tokenId: string): Promise<void>;
+    /**
+     * Revoke all tokens matching a relatedId and optionally a token type.
+     * Uses repository directly (R6 — intentional, not routed through operation pipeline).
+     *
+     * @returns Count of revoked tokens
+     */
+    revokeTokensByRelatedId(relatedId: string, tokenType?: ConsumableTokenTypes): Promise<number>;
+    /**
+     * Find all unconsumed, non-revoked, non-expired tokens for a given relatedId and token type.
+     * Used by Email OTP verification (Step 10) to find matching OTP tokens.
+     *
+     * @returns Array of matching token documents (may be empty)
+     */
+    findTokensByRelatedId(relatedId: string, tokenType: ConsumableTokenTypes): Promise<ConsumableToken[]>;
+    /**
+     * Process a declarative tokenGeneration config from an operation variant.
+     * Called AFTER the core operation succeeds, BEFORE notification dispatch.
+     *
+     * Returns `{ tokenValue, tokenId }` for injection into notification context.
+     */
+    processTokenGeneration(config: TokenGenerationConfig, currentState: Record<string, any>, executionContext: {
+        organizationId?: string;
+        userId?: string;
+        resourceType?: string;
+    }): Promise<TokenGenerationResult>;
+    /**
+     * Process a declarative tokenRevocation config from an operation variant.
+     * Called BEFORE the core operation (pre-operation step).
+     *
+     * Revokes all tokens matching the related resource ID and configured token types.
+     */
+    processTokenRevocation(config: TokenRevocationConfig, currentState: Record<string, any>, _executionContext: {
+        organizationId?: string;
+    }): Promise<TokenRevocationResult>;
+    /**
+     * Get the native MongoDB collection for consumable tokens.
+     * Used for atomic operations that bypass the repository execution context pattern.
+     */
+    private getTokenCollection;
+    /**
+     * Calculate the expiration date from a relative duration.
+     */
+    private calculateExpiresAt;
+    /**
+     * Resolve a StaticOrDerived value.
+     * If the value is a function, call it with the currentObject.
+     * If static, return as-is.
+     */
+    private resolveStaticOrDerived;
+}
+//# sourceMappingURL=consumable-token.backend.service.d.ts.map

package/dist/esm/security/consumable-tokens/services/consumable-token.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumable-token.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/security/consumable-tokens/services/consumable-token.backend.service.ts"],"names":[],"mappings":"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"}

package/dist/esm/security/consumable-tokens/services/consumable-token.backend.service.js

@@ -0,0 +1,446 @@
+/**
+ * Consumable Token Backend Service
+ *
+ * Central service for the full lifecycle of consumable tokens:
+ * - Token creation with crypto-secure random values
+ * - Token validation (expiry, consumption, revocation, type matching)
+ * - Atomic token consumption (race-condition safe via findOneAndUpdate)
+ * - Token revocation (soft invalidation via revokedAt)
+ * - Pipeline helpers for declarative tokenGeneration/tokenRevocation configs
+ *
+ * Security (R2): Raw token values are NEVER logged. Only token._id is logged.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { injectable, inject } from 'inversify';
+import crypto from 'crypto';
+import { ConsumableToken_ConsumptionMode, ErrorType, ErrorCustomMessageReference, } from '@wildo-ai/saas-models';
+import { durationToSeconds } from '@wildo-ai/zod-decorators';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+import { ErrorBuilderBackendService } from '../../../errors/services/error-builder.backend.service.js';
+import { MongoDBService } from '../../../databases/services/mongodb.service.js';
+// ============================================================================
+// SERVICE
+// ============================================================================
+let ConsumableTokenBackendService = class ConsumableTokenBackendService {
+    logger;
+    errorBuilder;
+    mongoDBService;
+    constructor(logger, errorBuilder, mongoDBService) {
+        this.logger = logger;
+        this.errorBuilder = errorBuilder;
+        this.mongoDBService = mongoDBService;
+    }
+    // ==========================================================================
+    // CORE TOKEN OPERATIONS
+    // ==========================================================================
+    /**
+     * Create a new consumable token.
+     * Generates a 32-byte hex crypto-random token value and persists it.
+     *
+     * @returns The full entity WITH the raw token value (for passing to emails/responses).
+     *          NEVER log the returned token value (R2).
+     */
+    async createToken(params) {
+        const tokenValue = crypto.randomBytes(32).toString('hex');
+        const now = new Date();
+        const expiresAt = this.calculateExpiresAt(params.expiresIn, now);
+        const tokenData = {
+            token: tokenValue,
+            tokenType: params.tokenType,
+            resourceIdentifier: params.resourceIdentifier,
+            consumptionMode: params.consumptionMode,
+            organizationId: params.organizationId,
+            userId: params.userId,
+            relatedId: params.relatedId,
+            metadata: params.metadata || {},
+            roles: params.roles || [],
+            expiresAt,
+            isConsumed: false,
+            usesCount: 0,
+            ...(params.createsOneOffSession !== undefined && { createsOneOffSession: params.createsOneOffSession }),
+            ...(params.consumeAt && { consumeAt: params.consumeAt }),
+            ...(params.targeting && { targeting: params.targeting }),
+            createdAt: now,
+            updatedAt: now,
+        };
+        // maxUses is required for BOUNDED_REUSE
+        if (params.consumptionMode === ConsumableToken_ConsumptionMode.BOUNDED_REUSE) {
+            if (!params.maxUses || params.maxUses < 1) {
+                throw this.errorBuilder.buildError(ErrorType.VALIDATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.VALIDATION,
+                    context: { reason: 'maxUses is required and must be >= 1 for BOUNDED_REUSE tokens' }
+                });
+            }
+            tokenData.maxUses = params.maxUses;
+        }
+        // Use the native MongoDB collection for direct insert (bypasses execution context requirement)
+        const collection = this.getTokenCollection();
+        const _id = crypto.randomUUID();
+        tokenData._id = _id;
+        await collection.insertOne(tokenData);
+        // Log creation without the raw token value (R2)
+        this.logger.info('Consumable token created', {
+            tokenId: _id,
+            tokenType: params.tokenType,
+            consumptionMode: params.consumptionMode,
+            relatedId: params.relatedId,
+            organizationId: params.organizationId,
+            expiresAt: expiresAt.toISOString(),
+        });
+        return tokenData;
+    }
+    /**
+     * Validate a token without consuming it.
+     * Checks: existence, revocation, expiry, consumption status, type matching.
+     *
+     * @param tokenValue - The raw token string from the request
+     * @param expectedTypes - Optional array of accepted token types for this operation
+     * @returns The validated token entity
+     * @throws Appropriate error for each failure mode
+     */
+    async validateToken(tokenValue, expectedTypes) {
+        const collection = this.getTokenCollection();
+        const tokenDoc = await collection.findOne({ token: tokenValue });
+        if (!tokenDoc) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_NOT_FOUND,
+            });
+        }
+        const token = tokenDoc;
+        // Check revocation
+        if (token.revokedAt) {
+            this.logger.warn('Revoked token used', { tokenId: token._id });
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_REVOKED,
+                context: { tokenId: token._id },
+            });
+        }
+        // Check expiry
+        if (token.expiresAt < new Date()) {
+            this.logger.warn('Expired token used', { tokenId: token._id });
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_EXPIRED,
+                context: { tokenId: token._id },
+            });
+        }
+        // Check consumption status based on mode
+        if (token.consumptionMode === ConsumableToken_ConsumptionMode.SINGLE_USE && token.isConsumed) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_ALREADY_CONSUMED,
+                context: { tokenId: token._id },
+            });
+        }
+        if (token.consumptionMode === ConsumableToken_ConsumptionMode.BOUNDED_REUSE) {
+            const maxUses = token.maxUses;
+            if (maxUses && token.usesCount >= maxUses) {
+                throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_ALREADY_CONSUMED,
+                    context: { tokenId: token._id, usesCount: token.usesCount, maxUses },
+                });
+            }
+        }
+        if (token.consumptionMode === ConsumableToken_ConsumptionMode.EPHEMERAL_STATE && token.isConsumed) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_ALREADY_CONSUMED,
+                context: { tokenId: token._id },
+            });
+        }
+        // Check type matching
+        if (expectedTypes && expectedTypes.length > 0) {
+            if (!expectedTypes.includes(token.tokenType)) {
+                this.logger.warn('Token type mismatch', {
+                    tokenId: token._id,
+                    tokenType: token.tokenType,
+                    expectedTypes
+                });
+                throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                    customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_TYPE_MISMATCH,
+                    context: { tokenId: token._id, tokenType: token.tokenType, expectedTypes },
+                });
+            }
+        }
+        return token;
+    }
+    /**
+     * Atomically consume a token.
+     * Uses MongoDB `findOneAndUpdate` with conditions to prevent race conditions.
+     *
+     * - SINGLE_USE: condition `{ isConsumed: false }`, sets `{ isConsumed: true, usesCount: 1 }`
+     * - BOUNDED_REUSE: condition `{ usesCount: { $lt: maxUses } }`, inc `usesCount`, set `isConsumed` if exhausted
+     * - EPHEMERAL_STATE: condition `{ isConsumed: false }`, sets `{ isConsumed: true }`
+     *
+     * @param tokenValue - The raw token string
+     * @returns The updated token entity
+     * @throws CONSUMABLE_TOKEN_RACE_CONDITION if atomic update fails (concurrent consumption)
+     */
+    async consumeToken(tokenValue) {
+        const collection = this.getTokenCollection();
+        const now = new Date();
+        // First, read the token to determine its consumption mode.
+        // Also check that the token hasn't expired or been revoked.
+        const existingTokenDoc = await collection.findOne({
+            token: tokenValue,
+            revokedAt: { $exists: false },
+            expiresAt: { $gt: now },
+        });
+        if (!existingTokenDoc) {
+            throw this.errorBuilder.buildError(ErrorType.AUTHENTICATION, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_NOT_FOUND,
+            });
+        }
+        const existingToken = existingTokenDoc;
+        let filter;
+        let update;
+        // All filters include expiresAt + revokedAt guards to prevent consuming expired/revoked tokens
+        // in the atomic update (defense-in-depth against TOCTOU between the read above and the update below).
+        const expiryGuard = { expiresAt: { $gt: now }, revokedAt: { $exists: false } };
+        switch (existingToken.consumptionMode) {
+            case ConsumableToken_ConsumptionMode.SINGLE_USE: {
+                filter = { token: tokenValue, isConsumed: false, ...expiryGuard };
+                update = {
+                    $set: { isConsumed: true, usesCount: 1, updatedAt: now }
+                };
+                break;
+            }
+            case ConsumableToken_ConsumptionMode.BOUNDED_REUSE: {
+                const maxUses = existingToken.maxUses || 1;
+                filter = { token: tokenValue, usesCount: { $lt: maxUses }, ...expiryGuard };
+                // Use aggregation pipeline update to atomically increment usesCount
+                // AND compute isConsumed from the post-increment value.
+                // This avoids the race condition where two concurrent requests
+                // both read the same pre-increment usesCount and fail to set isConsumed.
+                update = [
+                    { $set: { usesCount: { $add: ['$usesCount', 1] }, updatedAt: now } },
+                    { $set: { isConsumed: { $gte: ['$usesCount', maxUses] } } },
+                ];
+                break;
+            }
+            case ConsumableToken_ConsumptionMode.EPHEMERAL_STATE: {
+                filter = { token: tokenValue, isConsumed: false, ...expiryGuard };
+                update = {
+                    $set: { isConsumed: true, usesCount: 1, updatedAt: now }
+                };
+                break;
+            }
+            default: {
+                // Fallback: treat as single-use
+                filter = { token: tokenValue, isConsumed: false, ...expiryGuard };
+                update = {
+                    $set: { isConsumed: true, usesCount: 1, updatedAt: now }
+                };
+            }
+        }
+        const result = await collection.findOneAndUpdate(filter, update, { returnDocument: 'after' });
+        if (!result) {
+            this.logger.warn('Token consumption race condition', { tokenId: existingToken._id });
+            throw this.errorBuilder.buildError(ErrorType.CONFLICT, undefined, {
+                customMessageReference: ErrorCustomMessageReference.CONSUMABLE_TOKEN_RACE_CONDITION,
+                context: { tokenId: existingToken._id },
+            });
+        }
+        this.logger.info('Consumable token consumed', {
+            tokenId: existingToken._id,
+            consumptionMode: existingToken.consumptionMode
+        });
+        return result;
+    }
+    /**
+     * Soft-revoke a token by setting revokedAt.
+     * This is a soft invalidation — the record stays in DB for audit.
+     * Hard deletion is handled by the cleanup cron job.
+     */
+    async revokeToken(tokenId) {
+        const collection = this.getTokenCollection();
+        const now = new Date();
+        await collection.updateOne({ _id: tokenId }, { $set: { revokedAt: now, updatedAt: now } });
+        this.logger.info('Consumable token revoked', { tokenId });
+    }
+    /**
+     * Revoke all tokens matching a relatedId and optionally a token type.
+     * Uses repository directly (R6 — intentional, not routed through operation pipeline).
+     *
+     * @returns Count of revoked tokens
+     */
+    async revokeTokensByRelatedId(relatedId, tokenType) {
+        const collection = this.getTokenCollection();
+        const now = new Date();
+        const filter = {
+            relatedId,
+            revokedAt: { $exists: false },
+        };
+        if (tokenType) {
+            filter.tokenType = tokenType;
+        }
+        const result = await collection.updateMany(filter, { $set: { revokedAt: now, updatedAt: now } });
+        const revokedCount = result.modifiedCount;
+        if (revokedCount > 0) {
+            this.logger.info('Consumable tokens revoked by relatedId', {
+                relatedId,
+                tokenType,
+                revokedCount
+            });
+        }
+        return revokedCount;
+    }
+    /**
+     * Find all unconsumed, non-revoked, non-expired tokens for a given relatedId and token type.
+     * Used by Email OTP verification (Step 10) to find matching OTP tokens.
+     *
+     * @returns Array of matching token documents (may be empty)
+     */
+    async findTokensByRelatedId(relatedId, tokenType) {
+        const collection = this.getTokenCollection();
+        const now = new Date();
+        const docs = await collection.find({
+            relatedId,
+            tokenType: tokenType,
+            revokedAt: { $exists: false },
+            isConsumed: { $ne: true },
+            expiresAt: { $gt: now },
+        }).toArray();
+        return docs;
+    }
+    // ==========================================================================
+    // PIPELINE HELPERS — Called by services-registry-handler for declarative config
+    // ==========================================================================
+    /**
+     * Process a declarative tokenGeneration config from an operation variant.
+     * Called AFTER the core operation succeeds, BEFORE notification dispatch.
+     *
+     * Returns `{ tokenValue, tokenId }` for injection into notification context.
+     */
+    async processTokenGeneration(config, currentState, executionContext) {
+        // Revoke existing tokens if configured
+        if (config.revokeExistingForSameRelated) {
+            const relatedId = currentState[config.relatedIdField || '_id'];
+            if (relatedId) {
+                await this.revokeTokensByRelatedId(relatedId, config.tokenType);
+            }
+        }
+        // Resolve static or derived values
+        const resolvedExpiresIn = this.resolveStaticOrDerived(config.expiresIn, currentState);
+        const resolvedGrantedRoles = config.grantedRoles
+            ? this.resolveStaticOrDerived(config.grantedRoles, currentState)
+            : undefined;
+        // Build create params
+        const createParams = {
+            tokenType: config.tokenType,
+            consumptionMode: config.consumptionMode,
+            expiresIn: resolvedExpiresIn,
+            organizationId: currentState.organizationId || executionContext.organizationId,
+            resourceIdentifier: executionContext.resourceType,
+            relatedId: currentState[config.relatedIdField || '_id'],
+            roles: resolvedGrantedRoles,
+            maxUses: config.maxUses,
+        };
+        // Resolve userId if configured
+        if (config.userIdField) {
+            createParams.userId = currentState[config.userIdField];
+        }
+        // W7.3b: Bridge to one-off sessions when configured
+        if (config.createsOneOffSession) {
+            createParams.createsOneOffSession = true;
+            createParams.consumeAt = config.consumeAt;
+        }
+        if (config.targetingFields) {
+            const initiatorIds = {};
+            const orgId = currentState.organizationId || executionContext.organizationId;
+            if (orgId)
+                initiatorIds.organizationId = orgId;
+            for (const [fieldId, fieldPath] of Object.entries(config.targetingFields)) {
+                const value = currentState[fieldPath];
+                if (value)
+                    initiatorIds[fieldId] = String(value);
+            }
+            if (Object.keys(initiatorIds).length > 0) {
+                createParams.targeting = { initiatorIds };
+            }
+        }
+        const token = await this.createToken(createParams);
+        return {
+            tokenValue: token.token,
+            tokenId: token._id,
+        };
+    }
+    /**
+     * Process a declarative tokenRevocation config from an operation variant.
+     * Called BEFORE the core operation (pre-operation step).
+     *
+     * Revokes all tokens matching the related resource ID and configured token types.
+     */
+    async processTokenRevocation(config, currentState, _executionContext) {
+        const relatedId = currentState[config.relatedIdField || '_id'];
+        if (!relatedId) {
+            this.logger.warn('Token revocation skipped: no relatedId found', {
+                relatedIdField: config.relatedIdField || '_id',
+            });
+            return { revokedCount: 0 };
+        }
+        let totalRevoked = 0;
+        for (const tokenType of config.tokenTypes) {
+            const count = await this.revokeTokensByRelatedId(relatedId, tokenType);
+            totalRevoked += count;
+        }
+        this.logger.info('Token revocation completed', {
+            relatedId,
+            tokenTypes: config.tokenTypes,
+            totalRevoked,
+        });
+        return { revokedCount: totalRevoked };
+    }
+    // ==========================================================================
+    // PRIVATE HELPERS
+    // ==========================================================================
+    /**
+     * Get the native MongoDB collection for consumable tokens.
+     * Used for atomic operations that bypass the repository execution context pattern.
+     */
+    getTokenCollection() {
+        const connection = this.mongoDBService.getConnection();
+        if (!connection) {
+            throw this.errorBuilder.buildError(ErrorType.DATABASE, undefined, {
+                context: { reason: 'MongoDB connection not available for consumable tokens' },
+            });
+        }
+        return connection.collection('consumabletokens');
+    }
+    /**
+     * Calculate the expiration date from a relative duration.
+     */
+    calculateExpiresAt(expiresIn, from = new Date()) {
+        const ms = durationToSeconds(expiresIn) * 1000;
+        return new Date(from.getTime() + ms);
+    }
+    /**
+     * Resolve a StaticOrDerived value.
+     * If the value is a function, call it with the currentObject.
+     * If static, return as-is.
+     */
+    resolveStaticOrDerived(value, currentObject) {
+        if (typeof value === 'function') {
+            return value(currentObject);
+        }
+        return value;
+    }
+};
+ConsumableTokenBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ErrorBuilderService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.MongoDBService)),
+    __metadata("design:paramtypes", [Function, ErrorBuilderBackendService,
+        MongoDBService])
+], ConsumableTokenBackendService);
+export { ConsumableTokenBackendService };
+//# sourceMappingURL=consumable-token.backend.service.js.map