@vorionsys/security 1.0.0

package/dist/api/v1/webhooks.js

@@ -0,0 +1,250 @@
+/**
+ * API v1 Webhook Routes
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+import { createLogger } from '../../common/logger.js';
+import { createWebhookService, verifyWebhookSignature, } from '../../intent/webhooks.js';
+import { ForbiddenError, NotFoundError } from '../../common/errors.js';
+import { requireTenantMembership } from '../../common/tenant-verification.js';
+import { getWebhookSecurityDocumentation } from '../middleware/webhook-verify.js';
+const webhookLogger = createLogger({ component: 'api-v1-webhooks' });
+const webhookService = createWebhookService();
+const WEBHOOK_EVENT_TYPES = [
+    'escalation.created',
+    'escalation.approved',
+    'escalation.rejected',
+    'escalation.timeout',
+    'intent.approved',
+    'intent.denied',
+    'intent.completed',
+];
+const webhookCreateBodySchema = z.object({
+    url: z.string().url(),
+    secret: z.string().min(16).max(256).optional(),
+    events: z.array(z.string().refine((value) => WEBHOOK_EVENT_TYPES.includes(value), {
+        message: 'Invalid webhook event type',
+    })).min(1),
+    enabled: z.boolean().optional().default(true),
+});
+const webhookIdParamsSchema = z.object({
+    id: z.string().uuid(),
+});
+const webhookDeliveriesQuerySchema = z.object({
+    limit: z.coerce.number().int().min(1).max(100).optional(),
+});
+const webhookRotateSecretBodySchema = z.object({
+    reason: z.string().max(500).optional(),
+});
+const webhookVerifySignatureBodySchema = z.object({
+    payload: z.string().min(1),
+    signature: z.string().min(1),
+    timestamp: z.number().int(),
+    secret: z.string().min(1),
+});
+async function getTenantId(request) {
+    const payload = await request.jwtVerify();
+    if (!payload.tenantId) {
+        throw new ForbiddenError('Tenant context missing from token');
+    }
+    if (!payload.sub) {
+        throw new ForbiddenError('User identifier missing from token');
+    }
+    await requireTenantMembership(payload.sub, payload.tenantId);
+    return payload.tenantId;
+}
+/**
+ * Register v1 webhook routes
+ */
+export async function registerWebhookRoutesV1(fastify) {
+    // Register webhook
+    // POST /webhooks - Create a new webhook
+    // Returns the webhook secret only once on creation
+    fastify.post('/webhooks', async (request, reply) => {
+        const tenantId = await getTenantId(request);
+        const body = webhookCreateBodySchema.parse(request.body ?? {});
+        try {
+            // Use returnSecret option to get the secret back (only returned once)
+            const result = await webhookService.registerWebhook(tenantId, {
+                url: body.url,
+                secret: body.secret,
+                events: body.events,
+                enabled: body.enabled ?? true,
+            }, { returnSecret: true });
+            const webhook = await webhookService.getWebhook(tenantId, result.webhookId);
+            webhookLogger.info({ webhookId: result.webhookId, tenantId, url: body.url }, 'Webhook registered');
+            // Return the secret only on creation (won't be returned again)
+            // Also include security documentation for verification
+            return reply.code(201).send({
+                id: result.webhookId,
+                config: webhook ? {
+                    ...webhook,
+                    // Don't include the decrypted secret in config, we return it separately
+                    secret: undefined,
+                } : undefined,
+                // The secret is only returned once - store it securely!
+                secret: result.secret,
+                secretPrefix: webhook?.secretPrefix,
+                security: {
+                    warning: 'Store this secret securely. It will not be shown again.',
+                    ...getWebhookSecurityDocumentation(),
+                },
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.startsWith('Invalid webhook URL')) {
+                return reply.status(400).send({
+                    error: {
+                        code: 'INVALID_WEBHOOK_URL',
+                        message: error.message,
+                    },
+                });
+            }
+            throw error;
+        }
+    });
+    // List webhooks
+    // GET /webhooks - List all webhooks for tenant
+    // Note: Secrets are never returned in list - only secretPrefix is shown
+    fastify.get('/webhooks', async (request, reply) => {
+        const tenantId = await getTenantId(request);
+        const webhooks = await webhookService.getWebhooks(tenantId);
+        return reply.send({
+            data: webhooks.map((w) => ({
+                id: w.id,
+                config: {
+                    url: w.config.url,
+                    enabled: w.config.enabled,
+                    events: w.config.events,
+                    retryAttempts: w.config.retryAttempts,
+                    retryDelayMs: w.config.retryDelayMs,
+                    // Show only the secret prefix, not the actual secret
+                    secretPrefix: w.config.secretPrefix,
+                    hasSecret: !!w.config.secret || !!w.config.secretHash,
+                    lastRotatedAt: w.config.lastRotatedAt,
+                },
+            })),
+        });
+    });
+    // Get single webhook
+    // GET /webhooks/:id - Get a single webhook by ID
+    fastify.get('/webhooks/:id', async (request, reply) => {
+        const tenantId = await getTenantId(request);
+        const params = webhookIdParamsSchema.parse(request.params ?? {});
+        const webhook = await webhookService.getWebhook(tenantId, params.id);
+        if (!webhook) {
+            return reply.status(404).send({
+                error: { code: 'WEBHOOK_NOT_FOUND', message: 'Webhook not found' },
+            });
+        }
+        return reply.send({
+            id: params.id,
+            config: {
+                url: webhook.url,
+                enabled: webhook.enabled,
+                events: webhook.events,
+                retryAttempts: webhook.retryAttempts,
+                retryDelayMs: webhook.retryDelayMs,
+                secretPrefix: webhook.secretPrefix,
+                hasSecret: !!webhook.secret || !!webhook.secretHash,
+                lastRotatedAt: webhook.lastRotatedAt,
+            },
+        });
+    });
+    // Delete webhook
+    fastify.delete('/webhooks/:id', async (request, reply) => {
+        const tenantId = await getTenantId(request);
+        const params = webhookIdParamsSchema.parse(request.params ?? {});
+        const deleted = await webhookService.unregisterWebhook(tenantId, params.id);
+        if (!deleted) {
+            return reply.status(404).send({
+                error: { code: 'WEBHOOK_NOT_FOUND', message: 'Webhook not found' },
+            });
+        }
+        webhookLogger.info({ webhookId: params.id, tenantId }, 'Webhook unregistered');
+        return reply.status(204).send();
+    });
+    // Get webhook deliveries
+    fastify.get('/webhooks/:id/deliveries', async (request, reply) => {
+        const tenantId = await getTenantId(request);
+        const params = webhookIdParamsSchema.parse(request.params ?? {});
+        const query = webhookDeliveriesQuerySchema.parse(request.query ?? {});
+        const webhooks = await webhookService.getWebhooks(tenantId);
+        const webhook = webhooks.find((w) => w.id === params.id);
+        if (!webhook) {
+            return reply.status(404).send({
+                error: { code: 'WEBHOOK_NOT_FOUND', message: 'Webhook not found' },
+            });
+        }
+        const deliveries = await webhookService.getDeliveries(tenantId, params.id, query.limit ?? 100);
+        return reply.send({
+            data: deliveries.map((d) => ({
+                id: d.id,
+                result: d.result,
+            })),
+        });
+    });
+    // Rotate webhook secret
+    // POST /webhooks/:id/rotate-secret - Generate a new secret for the webhook
+    // Returns the new secret only once
+    fastify.post('/webhooks/:id/rotate-secret', async (request, reply) => {
+        const tenantId = await getTenantId(request);
+        const payload = await request.jwtVerify();
+        const params = webhookIdParamsSchema.parse(request.params ?? {});
+        const body = webhookRotateSecretBodySchema.parse(request.body ?? {});
+        try {
+            const result = await webhookService.rotateSecret(tenantId, params.id, payload.sub, body.reason);
+            webhookLogger.info({ webhookId: params.id, tenantId, rotatedBy: payload.sub }, 'Webhook secret rotated');
+            // Return the new secret only once
+            return reply.send({
+                id: params.id,
+                secret: result.secret,
+                secretPrefix: result.secretPrefix,
+                previousSecretPrefix: result.previousSecretPrefix,
+                rotatedAt: new Date().toISOString(),
+                security: {
+                    warning: 'Store this secret securely. It will not be shown again.',
+                    ...getWebhookSecurityDocumentation(),
+                },
+            });
+        }
+        catch (error) {
+            if (error instanceof NotFoundError) {
+                return reply.status(404).send({
+                    error: { code: 'WEBHOOK_NOT_FOUND', message: 'Webhook not found' },
+                });
+            }
+            throw error;
+        }
+    });
+    // Test signature verification
+    // POST /webhooks/verify-signature - Test signature verification (public endpoint for testing)
+    // This helps webhook consumers validate their implementation
+    fastify.post('/webhooks/verify-signature', async (request, reply) => {
+        const body = webhookVerifySignatureBodySchema.parse(request.body ?? {});
+        const isValid = verifyWebhookSignature(body.payload, body.signature, body.secret, body.timestamp);
+        // Also compute what the expected signature should be for debugging
+        const now = Math.floor(Date.now() / 1000);
+        const timestampAge = now - body.timestamp;
+        const isTimestampValid = Math.abs(timestampAge) <= 300; // 5 minutes
+        return reply.send({
+            valid: isValid,
+            details: {
+                signatureValid: isValid,
+                timestampValid: isTimestampValid,
+                timestampAge: timestampAge,
+                currentTimestamp: now,
+                providedTimestamp: body.timestamp,
+            },
+            documentation: getWebhookSecurityDocumentation(),
+        });
+    });
+    // Get webhook security documentation
+    // GET /webhooks/security-docs - Get documentation for webhook signature verification
+    fastify.get('/webhooks/security-docs', async (_request, reply) => {
+        return reply.send(getWebhookSecurityDocumentation());
+    });
+    webhookLogger.debug('Webhook routes registered');
+}
+//# sourceMappingURL=webhooks.js.map

package/dist/api/v1/webhooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhooks.js","sourceRoot":"","sources":["../../../src/api/v1/webhooks.ts"],"names":[],"mappings":"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"}

package/dist/api/v2/trust.d.ts

@@ -0,0 +1,20 @@
+/**
+ * API v2 Trust Routes
+ *
+ * 16-factor trust model endpoints providing granular factor-level breakdowns,
+ * tier-aware gating analysis, and backward-compatible legacy component shapes.
+ *
+ * Replaces the deprecated 4-bucket TrustComponents model from v1 with
+ * per-factor scores drawn from @vorionsys/basis.
+ *
+ * @packageDocumentation
+ */
+import type { FastifyInstance } from 'fastify';
+/**
+ * Register v2 trust routes
+ *
+ * All routes are prefixed with /trust and expect the Fastify instance to be
+ * mounted under /api/v2 by the parent plugin.
+ */
+export declare function registerTrustRoutesV2(fastify: FastifyInstance): Promise<void>;
+//# sourceMappingURL=trust.d.ts.map

package/dist/api/v2/trust.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust.d.ts","sourceRoot":"","sources":["../../../src/api/v2/trust.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,SAAS,CAAC;AA2b7E;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAqJnF"}

package/dist/api/v2/trust.js

@@ -0,0 +1,362 @@
+/**
+ * API v2 Trust Routes
+ *
+ * 16-factor trust model endpoints providing granular factor-level breakdowns,
+ * tier-aware gating analysis, and backward-compatible legacy component shapes.
+ *
+ * Replaces the deprecated 4-bucket TrustComponents model from v1 with
+ * per-factor scores drawn from @vorionsys/basis.
+ *
+ * @packageDocumentation
+ */
+import { z } from 'zod';
+import { createLogger } from '../../common/logger.js';
+import { createTrustEngine, TRUST_LEVEL_NAMES, TRUST_THRESHOLDS, } from '../../trust-engine/index.js';
+import { ForbiddenError } from '../../common/errors.js';
+import { requireTenantMembership } from '../../common/tenant-verification.js';
+import { rateLimitPerTenant } from '../middleware/rateLimit.js';
+import { FACTOR_CODE_LIST, FACTOR_THRESHOLDS_BY_TIER, FACTOR_GROUPS, CORE_FACTORS, getCriticalFactorsForTier, } from '@vorionsys/basis';
+const trustLogger = createLogger({ component: 'api-v2-trust' });
+const trustEngine = createTrustEngine();
+// =============================================================================
+// ZOD SCHEMAS - Request Validation
+// =============================================================================
+/**
+ * Entity ID parameter schema
+ */
+const entityIdParamsSchema = z.object({
+    entityId: z.string().uuid('Invalid entity ID format'),
+});
+// =============================================================================
+// HELPER FUNCTIONS
+// =============================================================================
+/**
+ * Extract and validate tenant ID from JWT
+ */
+async function getTenantId(request) {
+    const payload = await request.jwtVerify();
+    if (!payload.tenantId) {
+        throw new ForbiddenError('Tenant context missing from token');
+    }
+    if (!payload.sub) {
+        throw new ForbiddenError('User identifier missing from token');
+    }
+    await requireTenantMembership(payload.sub, payload.tenantId);
+    return payload.tenantId;
+}
+/**
+ * Create error response
+ */
+function errorResponse(code, message, requestId, details) {
+    return {
+        success: false,
+        error: { code, message, details },
+        meta: { requestId, timestamp: new Date().toISOString(), apiVersion: 'v2' },
+    };
+}
+/**
+ * Create success response
+ */
+function successResponse(data, requestId) {
+    return {
+        success: true,
+        data,
+        meta: { requestId, timestamp: new Date().toISOString(), apiVersion: 'v2' },
+    };
+}
+/**
+ * Map a TrustLevel (0-7) to the corresponding TrustTier enum
+ */
+function levelToTrustTier(level) {
+    return level;
+}
+/**
+ * Get the factor name from its code string (e.g. 'CT-COMP' -> 'Competence')
+ */
+function getFactorName(code) {
+    // Convert dash-format to underscore key: 'CT-COMP' -> 'CT_COMP'
+    const key = code.replace('-', '_');
+    return CORE_FACTORS[key]?.name ?? code;
+}
+/**
+ * Get the factor tier label from its code string
+ */
+function getFactorTierLabel(code) {
+    const key = code.replace('-', '_');
+    const factor = CORE_FACTORS[key];
+    if (!factor)
+        return 'unknown';
+    switch (factor.tier) {
+        case 1: return 'foundational';
+        case 2: return 'operational';
+        case 3: return 'sophisticated';
+        case 4: return 'life_critical';
+        default: return 'unknown';
+    }
+}
+/**
+ * Get the trust tier the factor is first required from
+ */
+function getFactorRequiredFrom(code) {
+    const key = code.replace('-', '_');
+    return CORE_FACTORS[key]?.requiredFrom ?? 0;
+}
+/**
+ * Build a FactorDetail for a given factor code
+ */
+function buildFactorDetail(code, factorScores, currentTier, nextTier) {
+    const score = factorScores[code] ?? 0;
+    const currentThresholds = FACTOR_THRESHOLDS_BY_TIER[currentTier];
+    const currentThreshold = currentThresholds?.[code];
+    const nextThresholds = nextTier !== null ? FACTOR_THRESHOLDS_BY_TIER[nextTier] : null;
+    const nextThreshold = nextThresholds?.[code] ?? undefined;
+    return {
+        code,
+        name: getFactorName(code),
+        score,
+        weight: currentThreshold?.weight ?? 1,
+        tier: getFactorTierLabel(code),
+        requiredFrom: getFactorRequiredFrom(code),
+        meetsCurrentThreshold: currentThreshold ? score >= currentThreshold.minimum : true,
+        meetsNextThreshold: nextThreshold ? score >= nextThreshold.minimum : true,
+        currentThreshold: currentThreshold?.minimum ?? 0,
+        nextThreshold: nextThreshold?.minimum ?? null,
+    };
+}
+/**
+ * Calculate the average score for a group of factor codes
+ */
+function calculateGroupScore(factorCodes, factorScores) {
+    if (factorCodes.length === 0)
+        return 0;
+    const total = factorCodes.reduce((sum, code) => {
+        // Factor codes in FACTOR_GROUPS use underscore format (CT_COMP);
+        // factorScores uses dash format (CT-COMP). Normalize.
+        const dashCode = code.replace('_', '-');
+        return sum + (factorScores[dashCode] ?? 0);
+    }, 0);
+    return Math.round((total / factorCodes.length) * 1000) / 1000;
+}
+/**
+ * Build the factorGroups object for the response
+ */
+function buildFactorGroups(factorScores, currentTier, nextTier) {
+    const buildGroup = (groupKey) => {
+        const group = FACTOR_GROUPS[groupKey];
+        if (!group) {
+            return { factors: [], groupScore: 0 };
+        }
+        const factors = group.factors.map((factorKey) => {
+            // Convert underscore key to dash code: CT_COMP -> CT-COMP
+            const dashCode = factorKey.replace('_', '-');
+            return buildFactorDetail(dashCode, factorScores, currentTier, nextTier);
+        });
+        const groupScore = calculateGroupScore(group.factors, factorScores);
+        return { factors, groupScore };
+    };
+    return {
+        foundation: buildGroup('FOUNDATION'),
+        security: buildGroup('SECURITY'),
+        agency: buildGroup('AGENCY'),
+        maturity: buildGroup('MATURITY'),
+        evolution: buildGroup('EVOLUTION'),
+    };
+}
+/**
+ * Build tier requirements including gating factors for the next tier
+ */
+function buildTierRequirements(level, factorScores) {
+    const currentTier = levelToTrustTier(level);
+    const currentThresholdRange = TRUST_THRESHOLDS[level];
+    const currentTierInfo = {
+        name: TRUST_LEVEL_NAMES[level],
+        minScore: currentThresholdRange.min,
+    };
+    // If at max tier, there is no next tier
+    if (level >= 7) {
+        return { currentTier: currentTierInfo, nextTier: null };
+    }
+    const nextLevel = (level + 1);
+    const nextTier = levelToTrustTier(nextLevel);
+    const nextThresholdRange = TRUST_THRESHOLDS[nextLevel];
+    const nextThresholds = FACTOR_THRESHOLDS_BY_TIER[nextTier];
+    // Find factors that are gating (below the next tier's minimum AND critical)
+    const gatingFactors = [];
+    for (const code of FACTOR_CODE_LIST) {
+        const threshold = nextThresholds?.[code];
+        if (!threshold)
+            continue;
+        const score = factorScores[code] ?? 0;
+        if (threshold.critical && score < threshold.minimum) {
+            gatingFactors.push(code);
+        }
+    }
+    return {
+        currentTier: currentTierInfo,
+        nextTier: {
+            name: TRUST_LEVEL_NAMES[nextLevel],
+            minScore: nextThresholdRange.min,
+            gatingFactors,
+        },
+    };
+}
+/**
+ * Find all factors gating promotion to the next tier with detailed gap analysis
+ */
+function buildGatingAnalysis(level, score, factorScores) {
+    if (level >= 7)
+        return null;
+    const nextLevel = (level + 1);
+    const nextTier = levelToTrustTier(nextLevel);
+    const nextThresholdRange = TRUST_THRESHOLDS[nextLevel];
+    const nextThresholds = FACTOR_THRESHOLDS_BY_TIER[nextTier];
+    const gatingFactors = [];
+    for (const code of FACTOR_CODE_LIST) {
+        const threshold = nextThresholds?.[code];
+        if (!threshold)
+            continue;
+        const currentScore = factorScores[code] ?? 0;
+        if (currentScore < threshold.minimum) {
+            gatingFactors.push({
+                code,
+                name: getFactorName(code),
+                currentScore,
+                requiredMinimum: threshold.minimum,
+                gap: Math.round((threshold.minimum - currentScore) * 1000) / 1000,
+                critical: threshold.critical,
+            });
+        }
+    }
+    const criticalFactorsRequired = getCriticalFactorsForTier(nextTier);
+    const scoreGap = Math.max(0, nextThresholdRange.min - score);
+    // Promotion is ready only if score is sufficient AND no critical factors are gating
+    const criticalGating = gatingFactors.filter((f) => f.critical);
+    const promotionReady = scoreGap === 0 && criticalGating.length === 0;
+    return {
+        name: TRUST_LEVEL_NAMES[nextLevel],
+        tier: nextLevel,
+        minScore: nextThresholdRange.min,
+        maxScore: nextThresholdRange.max,
+        scoreGap,
+        gatingFactors,
+        criticalFactorsRequired,
+        promotionReady,
+    };
+}
+// =============================================================================
+// ROUTE REGISTRATION
+// =============================================================================
+/**
+ * Register v2 trust routes
+ *
+ * All routes are prefixed with /trust and expect the Fastify instance to be
+ * mounted under /api/v2 by the parent plugin.
+ */
+export async function registerTrustRoutesV2(fastify) {
+    // ---------------------------------------------------------------------------
+    // GET /trust/:entityId - Full 16-factor trust breakdown
+    // Rate limit: 100 requests per minute per tenant
+    // ---------------------------------------------------------------------------
+    fastify.get('/trust/:entityId', {
+        preHandler: rateLimitPerTenant({ limit: 100, windowSeconds: 60 }),
+    }, async (request, reply) => {
+        const tenantId = await getTenantId(request);
+        const params = entityIdParamsSchema.parse(request.params ?? {});
+        trustEngine.registerEntityTenant(params.entityId, tenantId);
+        const trustRecord = await trustEngine.getScore(params.entityId, {
+            tenantId,
+        });
+        if (!trustRecord) {
+            return reply.status(404).send(errorResponse('ENTITY_NOT_FOUND', 'Entity trust record not found', request.id, {
+                entityId: params.entityId,
+            }));
+        }
+        const currentTier = levelToTrustTier(trustRecord.level);
+        const nextTier = trustRecord.level < 7 ? levelToTrustTier((trustRecord.level + 1)) : null;
+        const responseData = {
+            entityId: trustRecord.entityId,
+            score: trustRecord.score,
+            level: trustRecord.level,
+            levelName: TRUST_LEVEL_NAMES[trustRecord.level],
+            factorScores: trustRecord.factorScores,
+            factorGroups: buildFactorGroups(trustRecord.factorScores, currentTier, nextTier),
+            tierRequirements: buildTierRequirements(trustRecord.level, trustRecord.factorScores),
+            components: trustRecord.components,
+            updatedAt: trustRecord.lastCalculatedAt,
+        };
+        return reply.send(successResponse(responseData, request.id));
+    });
+    // ---------------------------------------------------------------------------
+    // GET /trust/:entityId/factors - Factor detail with thresholds
+    // Rate limit: 100 requests per minute per tenant
+    // ---------------------------------------------------------------------------
+    fastify.get('/trust/:entityId/factors', {
+        preHandler: rateLimitPerTenant({ limit: 100, windowSeconds: 60 }),
+    }, async (request, reply) => {
+        const tenantId = await getTenantId(request);
+        const params = entityIdParamsSchema.parse(request.params ?? {});
+        trustEngine.registerEntityTenant(params.entityId, tenantId);
+        const trustRecord = await trustEngine.getScore(params.entityId, {
+            tenantId,
+        });
+        if (!trustRecord) {
+            return reply.status(404).send(errorResponse('ENTITY_NOT_FOUND', 'Entity trust record not found', request.id, {
+                entityId: params.entityId,
+            }));
+        }
+        const currentTier = levelToTrustTier(trustRecord.level);
+        const nextTier = trustRecord.level < 7 ? levelToTrustTier((trustRecord.level + 1)) : null;
+        const factors = FACTOR_CODE_LIST.map((code) => buildFactorDetail(code, trustRecord.factorScores, currentTier, nextTier));
+        const meetingThreshold = factors.filter((f) => f.meetsCurrentThreshold).length;
+        const belowThreshold = factors.filter((f) => !f.meetsCurrentThreshold).length;
+        const responseData = {
+            entityId: trustRecord.entityId,
+            score: trustRecord.score,
+            level: trustRecord.level,
+            levelName: TRUST_LEVEL_NAMES[trustRecord.level],
+            factors,
+            totalFactors: FACTOR_CODE_LIST.length,
+            meetingThreshold,
+            belowThreshold,
+            updatedAt: trustRecord.lastCalculatedAt,
+        };
+        return reply.send(successResponse(responseData, request.id));
+    });
+    // ---------------------------------------------------------------------------
+    // GET /trust/:entityId/gating - What's blocking promotion to next tier
+    // Rate limit: 50 requests per minute per tenant (analysis endpoint)
+    // ---------------------------------------------------------------------------
+    fastify.get('/trust/:entityId/gating', {
+        preHandler: rateLimitPerTenant({ limit: 50, windowSeconds: 60 }),
+    }, async (request, reply) => {
+        const tenantId = await getTenantId(request);
+        const params = entityIdParamsSchema.parse(request.params ?? {});
+        trustEngine.registerEntityTenant(params.entityId, tenantId);
+        const trustRecord = await trustEngine.getScore(params.entityId, {
+            tenantId,
+        });
+        if (!trustRecord) {
+            return reply.status(404).send(errorResponse('ENTITY_NOT_FOUND', 'Entity trust record not found', request.id, {
+                entityId: params.entityId,
+            }));
+        }
+        const currentThresholdRange = TRUST_THRESHOLDS[trustRecord.level];
+        const responseData = {
+            entityId: trustRecord.entityId,
+            score: trustRecord.score,
+            level: trustRecord.level,
+            levelName: TRUST_LEVEL_NAMES[trustRecord.level],
+            currentTier: {
+                name: TRUST_LEVEL_NAMES[trustRecord.level],
+                tier: trustRecord.level,
+                minScore: currentThresholdRange.min,
+                maxScore: currentThresholdRange.max,
+            },
+            nextTier: buildGatingAnalysis(trustRecord.level, trustRecord.score, trustRecord.factorScores),
+            updatedAt: trustRecord.lastCalculatedAt,
+        };
+        return reply.send(successResponse(responseData, request.id));
+    });
+    trustLogger.debug('Trust v2 routes registered');
+}
+//# sourceMappingURL=trust.js.map