@c15t/backend 2.0.0-rc.5 → 2.0.0-rc.8

package/dist/915.js

@@ -0,0 +1,1742 @@
+import { hashSha256Hex } from "@c15t/schema/types";
+import base_x from "base-x";
+import { checkConsentOutputSchema, checkConsentQuerySchema, getSubjectInputSchema, getSubjectOutputSchema, initOutputSchema, legalDocumentCurrentInputSchema, legalDocumentCurrentOutputSchema, legalDocumentCurrentParamsSchema, listSubjectsOutputSchema, listSubjectsQuerySchema, patchSubjectOutputSchema, postSubjectInputSchema, postSubjectOutputSchema, statusOutputSchema, subjectIdSchema } from "@c15t/schema";
+import { Hono } from "hono";
+import { describeRoute, resolver, validator } from "hono-openapi";
+import { HTTPException } from "hono/http-exception";
+import { errors, jwtVerify } from "jose";
+import { version, getMetrics, withDatabaseSpan, extractErrorMessage } from "./302.js";
+import { getLocation, resolveInitPayload, policy_resolvePolicyDecision, verifyPolicySnapshotToken, getJurisdiction } from "./583.js";
+import * as __rspack_external_valibot from "valibot";
+const prefixes = {
+    auditLog: 'log',
+    consent: 'cns',
+    consentPolicy: 'pol',
+    consentPurpose: 'pur',
+    domain: 'dom',
+    runtimePolicyDecision: 'rpd',
+    subject: 'sub'
+};
+const b58 = base_x('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');
+function generateId(model) {
+    const buf = crypto.getRandomValues(new Uint8Array(20));
+    const prefix = prefixes[model];
+    const EPOCH_TIMESTAMP = 1700000000000;
+    const t = Date.now() - EPOCH_TIMESTAMP;
+    const high = Math.floor(t / 0x100000000);
+    const low = t >>> 0;
+    buf[0] = high >>> 24 & 255;
+    buf[1] = high >>> 16 & 255;
+    buf[2] = high >>> 8 & 255;
+    buf[3] = 255 & high;
+    buf[4] = low >>> 24 & 255;
+    buf[5] = low >>> 16 & 255;
+    buf[6] = low >>> 8 & 255;
+    buf[7] = 255 & low;
+    return `${prefix}_${b58.encode(buf)}`;
+}
+async function generateUniqueId(db, model, ctx, options = {}) {
+    const { maxRetries = 10, attempt = 0, baseDelay = 5 } = options;
+    if (attempt >= maxRetries) {
+        const error = new Error(`Failed to generate unique ID for ${model} after ${maxRetries} attempts`);
+        ctx?.logger?.error?.('ID generation failed', {
+            model,
+            maxRetries
+        });
+        throw error;
+    }
+    const id = generateId(model);
+    try {
+        const existing = await db.findFirst(model, {
+            where: (b)=>b('id', '=', id)
+        });
+        if (existing) {
+            ctx?.logger?.debug?.('ID conflict detected', {
+                id,
+                model,
+                attempt: attempt + 1,
+                maxRetries
+            });
+            const delay = Math.min(baseDelay * 2 ** attempt, 1000);
+            await new Promise((resolve)=>setTimeout(resolve, delay));
+            return generateUniqueId(db, model, ctx, {
+                maxRetries,
+                attempt: attempt + 1,
+                baseDelay
+            });
+        }
+        return id;
+    } catch (error) {
+        ctx?.logger?.error?.('Error checking ID uniqueness', {
+            error: error.message,
+            model,
+            attempt
+        });
+        if (attempt < maxRetries - 1) {
+            const delay = Math.min(baseDelay * 2 ** attempt, 2000);
+            await new Promise((resolve)=>setTimeout(resolve, delay));
+            return generateUniqueId(db, model, ctx, {
+                maxRetries,
+                attempt: attempt + 1,
+                baseDelay
+            });
+        }
+        throw error;
+    }
+}
+class LegalDocumentPolicyConflictError extends Error {
+    constructor(message){
+        super(message);
+        this.name = 'LegalDocumentPolicyConflictError';
+    }
+}
+async function buildLegalDocumentPolicyId(input) {
+    const digest = await hashSha256Hex([
+        input.tenantId ?? 'default',
+        input.type,
+        input.hash
+    ].join('|'));
+    return `pol_${digest}`;
+}
+function hasLegalDocumentPolicyConflict(policy, input) {
+    return policy.version !== input.version || policy.hash !== input.hash || policy.effectiveDate.getTime() !== input.effectiveDate.getTime();
+}
+function policyRegistry({ db, ctx }) {
+    const { logger } = ctx;
+    return {
+        findConsentPolicyById: async (policyId)=>{
+            const start = Date.now();
+            try {
+                const result = await withDatabaseSpan({
+                    operation: 'find',
+                    entity: 'consentPolicy'
+                }, async ()=>{
+                    const policy = await db.findFirst('consentPolicy', {
+                        where: (b)=>b('id', '=', policyId)
+                    });
+                    return policy;
+                });
+                getMetrics()?.recordDbQuery({
+                    operation: 'find',
+                    entity: 'consentPolicy'
+                }, Date.now() - start);
+                return result;
+            } catch (error) {
+                getMetrics()?.recordDbError({
+                    operation: 'find',
+                    entity: 'consentPolicy'
+                });
+                throw error;
+            }
+        },
+        findLatestPolicyByType: async (type)=>{
+            const start = Date.now();
+            try {
+                const result = await withDatabaseSpan({
+                    operation: 'findLatest',
+                    entity: 'consentPolicy'
+                }, async ()=>db.findFirst('consentPolicy', {
+                        where: (b)=>b.and(b('isActive', '=', true), b('type', '=', type)),
+                        orderBy: [
+                            'effectiveDate',
+                            'desc'
+                        ]
+                    }));
+                getMetrics()?.recordDbQuery({
+                    operation: 'findLatest',
+                    entity: 'consentPolicy'
+                }, Date.now() - start);
+                return result;
+            } catch (error) {
+                getMetrics()?.recordDbError({
+                    operation: 'findLatest',
+                    entity: 'consentPolicy'
+                });
+                throw error;
+            }
+        },
+        findLegalDocumentPolicyByHash: async (type, hash)=>{
+            const start = Date.now();
+            try {
+                const policyId = await buildLegalDocumentPolicyId({
+                    tenantId: ctx.tenantId,
+                    type,
+                    hash
+                });
+                const result = await withDatabaseSpan({
+                    operation: 'findByHash',
+                    entity: 'consentPolicy'
+                }, async ()=>db.findFirst('consentPolicy', {
+                        where: (b)=>b('id', '=', policyId)
+                    }));
+                getMetrics()?.recordDbQuery({
+                    operation: 'findByHash',
+                    entity: 'consentPolicy'
+                }, Date.now() - start);
+                return result;
+            } catch (error) {
+                getMetrics()?.recordDbError({
+                    operation: 'findByHash',
+                    entity: 'consentPolicy'
+                });
+                throw error;
+            }
+        },
+        syncCurrentLegalDocumentPolicy: async (input)=>{
+            const start = Date.now();
+            try {
+                const result = await withDatabaseSpan({
+                    operation: 'syncCurrent',
+                    entity: 'consentPolicy'
+                }, async ()=>{
+                    const policyId = await buildLegalDocumentPolicyId({
+                        tenantId: ctx.tenantId,
+                        type: input.type,
+                        hash: input.hash
+                    });
+                    return db.transaction(async (tx)=>{
+                        const existing = await tx.findFirst('consentPolicy', {
+                            where: (b)=>b('id', '=', policyId)
+                        });
+                        if (existing) {
+                            if (hasLegalDocumentPolicyConflict(existing, input)) throw new LegalDocumentPolicyConflictError('Release metadata conflicts with existing consent policy');
+                            await tx.updateMany('consentPolicy', {
+                                where: (b)=>b.and(b('type', '=', input.type), b('isActive', '=', true), b('id', '!=', existing.id)),
+                                set: {
+                                    isActive: false
+                                }
+                            });
+                            if (!existing.isActive) {
+                                await tx.updateMany('consentPolicy', {
+                                    where: (b)=>b('id', '=', existing.id),
+                                    set: {
+                                        isActive: true
+                                    }
+                                });
+                                return {
+                                    ...existing,
+                                    isActive: true
+                                };
+                            }
+                            return existing;
+                        }
+                        await tx.updateMany('consentPolicy', {
+                            where: (b)=>b.and(b('type', '=', input.type), b('isActive', '=', true)),
+                            set: {
+                                isActive: false
+                            }
+                        });
+                        const policy = await tx.create('consentPolicy', {
+                            id: policyId,
+                            version: input.version,
+                            type: input.type,
+                            hash: input.hash,
+                            effectiveDate: input.effectiveDate,
+                            isActive: true
+                        });
+                        return policy;
+                    });
+                });
+                getMetrics()?.recordDbQuery({
+                    operation: 'syncCurrent',
+                    entity: 'consentPolicy'
+                }, Date.now() - start);
+                return result;
+            } catch (error) {
+                getMetrics()?.recordDbError({
+                    operation: 'syncCurrent',
+                    entity: 'consentPolicy'
+                });
+                throw error;
+            }
+        },
+        findOrCreateLegalDocumentPolicy: async (input)=>{
+            const start = Date.now();
+            try {
+                const result = await withDatabaseSpan({
+                    operation: 'findOrCreateLegalDocument',
+                    entity: 'consentPolicy'
+                }, async ()=>{
+                    const policyId = await buildLegalDocumentPolicyId({
+                        tenantId: ctx.tenantId,
+                        type: input.type,
+                        hash: input.hash
+                    });
+                    const existing = await db.findFirst('consentPolicy', {
+                        where: (b)=>b('id', '=', policyId)
+                    });
+                    if (existing) {
+                        if (hasLegalDocumentPolicyConflict(existing, input)) throw new LegalDocumentPolicyConflictError('Release metadata conflicts with existing consent policy');
+                        return existing;
+                    }
+                    const policy = await db.create('consentPolicy', {
+                        id: policyId,
+                        version: input.version,
+                        type: input.type,
+                        hash: input.hash,
+                        effectiveDate: input.effectiveDate,
+                        isActive: false
+                    }).catch(async ()=>{
+                        const concurrent = await db.findFirst('consentPolicy', {
+                            where: (b)=>b('id', '=', policyId)
+                        });
+                        if (!concurrent) throw new LegalDocumentPolicyConflictError('Failed to create legal document consent policy');
+                        if (hasLegalDocumentPolicyConflict(concurrent, input)) throw new LegalDocumentPolicyConflictError('Release metadata conflicts with existing consent policy');
+                        return concurrent;
+                    });
+                    return policy;
+                });
+                getMetrics()?.recordDbQuery({
+                    operation: 'findOrCreateLegalDocument',
+                    entity: 'consentPolicy'
+                }, Date.now() - start);
+                return result;
+            } catch (error) {
+                getMetrics()?.recordDbError({
+                    operation: 'findOrCreateLegalDocument',
+                    entity: 'consentPolicy'
+                });
+                throw error;
+            }
+        },
+        findOrCreatePolicy: async (type)=>{
+            const start = Date.now();
+            try {
+                const result = await withDatabaseSpan({
+                    operation: 'findOrCreate',
+                    entity: 'consentPolicy'
+                }, async ()=>{
+                    const existingPolicy = await db.findFirst('consentPolicy', {
+                        where: (b)=>b.and(b('isActive', '=', true), b('type', '=', type)),
+                        orderBy: [
+                            'effectiveDate',
+                            'desc'
+                        ]
+                    });
+                    if (existingPolicy) {
+                        logger.debug('Found existing policy', {
+                            type,
+                            policyId: existingPolicy.id
+                        });
+                        return existingPolicy;
+                    }
+                    const policy = await db.create('consentPolicy', {
+                        id: await generateUniqueId(db, 'consentPolicy', ctx),
+                        version: '1.0.0',
+                        type,
+                        effectiveDate: new Date(),
+                        isActive: true
+                    });
+                    return policy;
+                });
+                getMetrics()?.recordDbQuery({
+                    operation: 'findOrCreate',
+                    entity: 'consentPolicy'
+                }, Date.now() - start);
+                return result;
+            } catch (error) {
+                getMetrics()?.recordDbError({
+                    operation: 'findOrCreate',
+                    entity: 'consentPolicy'
+                });
+                throw error;
+            }
+        }
+    };
+}
+function parsePurposeIds(purposeIds) {
+    if (null == purposeIds) return [];
+    const ids = 'object' == typeof purposeIds && 'json' in purposeIds ? purposeIds.json : purposeIds;
+    return Array.isArray(ids) ? ids : [];
+}
+async function batchLoadPolicies(policyIds, ctx) {
+    const { db, registry } = ctx;
+    const policyMap = new Map();
+    if (policyIds.size > 0) {
+        const policies = await db.findMany('consentPolicy', {
+            where: (b)=>b('id', 'in', [
+                    ...policyIds
+                ])
+        });
+        for (const p of policies)policyMap.set(p.id, p);
+    }
+    const uniqueTypes = new Set();
+    for (const p of policyMap.values())uniqueTypes.add(p.type);
+    const latestPolicyByType = new Map();
+    for (const type of uniqueTypes){
+        const latest = await registry.findLatestPolicyByType(type);
+        if (latest) latestPolicyByType.set(type, latest.id);
+    }
+    return {
+        policyMap,
+        latestPolicyByType
+    };
+}
+async function enrichConsents(consents, ctx) {
+    if (0 === consents.length) return [];
+    const policyIds = new Set();
+    for (const c of consents)if (c.policyId) policyIds.add(c.policyId);
+    const { policyMap, latestPolicyByType } = await batchLoadPolicies(policyIds, ctx);
+    const allPurposeIds = new Set();
+    for (const c of consents)for (const id of parsePurposeIds(c.purposeIds))allPurposeIds.add(id);
+    const purposeMap = new Map();
+    if (allPurposeIds.size > 0) {
+        const purposes = await ctx.db.findMany('consentPurpose', {
+            where: (b)=>b('id', 'in', [
+                    ...allPurposeIds
+                ])
+        });
+        for (const p of purposes)purposeMap.set(p.id, p.code);
+    }
+    return consents.map((consent)=>{
+        let policyType = 'unknown';
+        let policyVersion;
+        let policyHash;
+        let policyEffectiveDate;
+        let isLatestPolicy = false;
+        if (consent.policyId) {
+            const policy = policyMap.get(consent.policyId);
+            if (policy) {
+                policyType = policy.type;
+                policyVersion = policy.version;
+                policyHash = policy.hash ?? void 0;
+                policyEffectiveDate = policy.effectiveDate;
+                isLatestPolicy = latestPolicyByType.get(policyType) === consent.policyId;
+            }
+        }
+        let preferences;
+        const ids = parsePurposeIds(consent.purposeIds);
+        if (ids.length > 0) {
+            preferences = {};
+            for (const purposeId of ids){
+                const code = purposeMap.get(purposeId);
+                if (code) preferences[code] = true;
+            }
+        }
+        return {
+            id: consent.id,
+            type: policyType,
+            policyId: consent.policyId ?? void 0,
+            policyVersion,
+            policyHash,
+            policyEffectiveDate,
+            isLatestPolicy,
+            preferences,
+            givenAt: consent.givenAt
+        };
+    });
+}
+async function resolveConsentPolicies(consents, ctx) {
+    if (0 === consents.length) return [];
+    const policyIds = new Set();
+    for (const c of consents)if (c.policyId) policyIds.add(c.policyId);
+    const { policyMap, latestPolicyByType } = await batchLoadPolicies(policyIds, ctx);
+    return consents.map((consent)=>{
+        let policyType = 'unknown';
+        let isLatestPolicy = false;
+        if (consent.policyId) {
+            const policy = policyMap.get(consent.policyId);
+            if (policy) {
+                policyType = policy.type;
+                isLatestPolicy = latestPolicyByType.get(policyType) === consent.policyId;
+            }
+        }
+        return {
+            consentId: consent.id,
+            policyType,
+            policyId: consent.policyId ?? void 0,
+            isLatestPolicy
+        };
+    });
+}
+const checkConsentHandler = async (c)=>{
+    const ctx = c.get('c15tContext');
+    const logger = ctx.logger;
+    logger.info('Handling GET /consents/check request');
+    const { db, registry } = ctx;
+    const externalId = c.req.query('externalId');
+    const type = c.req.query('type');
+    if (!externalId) throw new HTTPException(422, {
+        message: 'externalId query parameter is required',
+        cause: {
+            code: 'EXTERNAL_ID_REQUIRED'
+        }
+    });
+    if (!type) throw new HTTPException(422, {
+        message: 'type query parameter is required',
+        cause: {
+            code: 'TYPE_REQUIRED'
+        }
+    });
+    const types = type.split(',').map((t)=>t.trim());
+    logger.debug('Request parameters', {
+        externalId,
+        types
+    });
+    try {
+        const subjects = await db.findMany('subject', {
+            where: (b)=>b('externalId', '=', externalId)
+        });
+        const subjectIds = subjects.map((s)=>s.id);
+        const results = {};
+        for (const t of types)results[t] = {
+            hasConsent: false,
+            isLatestPolicy: false
+        };
+        if (0 === subjectIds.length) {
+            logger.debug('No subjects found for externalId', {
+                externalId
+            });
+            return c.json({
+                results
+            });
+        }
+        const allConsents = await Promise.all(subjectIds.map((subjectId)=>db.findMany('consent', {
+                where: (b)=>b('subjectId', '=', subjectId)
+            })));
+        const consents = allConsents.flat();
+        const policyInfos = await resolveConsentPolicies(consents, {
+            db,
+            registry
+        });
+        for (const info of policyInfos){
+            if (!types.includes(info.policyType)) continue;
+            const entry = results[info.policyType];
+            if (entry) {
+                entry.hasConsent = true;
+                if (info.isLatestPolicy) entry.isLatestPolicy = true;
+            }
+        }
+        logger.debug('Consent check results', {
+            externalId,
+            results
+        });
+        const metrics = getMetrics();
+        if (metrics) for (const [type, result] of Object.entries(results))metrics.recordConsentCheck(type, result.hasConsent);
+        return c.json({
+            results
+        });
+    } catch (error) {
+        logger.error('Error in GET /consents/check handler', {
+            error: extractErrorMessage(error),
+            errorType: error instanceof Error ? error.constructor.name : typeof error
+        });
+        if (error instanceof HTTPException) throw error;
+        throw new HTTPException(500, {
+            message: 'Internal server error',
+            cause: {
+                code: 'INTERNAL_SERVER_ERROR'
+            }
+        });
+    }
+};
+const createConsentRoutes = ()=>{
+    const app = new Hono();
+    app.get('/check', describeRoute({
+        summary: 'Check consent by external user ID',
+        description: "Pre-banner cross-device consent check. Use to avoid showing the banner when the user has already consented on another device.\n\n**Query parameters:**\n- `externalId` – External user ID to check\n- `type` – Consent type(s) to check (comma-separated)",
+        tags: [
+            'Consent'
+        ],
+        responses: {
+            200: {
+                description: 'Consent check result per requested type(s)',
+                content: {
+                    'application/json': {
+                        schema: resolver(checkConsentOutputSchema)
+                    }
+                }
+            },
+            422: {
+                description: 'Invalid or missing query parameters'
+            }
+        }
+    }), validator('query', checkConsentQuerySchema), checkConsentHandler);
+    return app;
+};
+const createInitRoute = (options)=>{
+    const app = new Hono();
+    app.get('/', describeRoute({
+        summary: 'Get initial consent manager state',
+        description: `Returns the initial state required to render the consent manager.
+
+- **Jurisdiction** – User's jurisdiction (defaults to GDPR if geo-location is disabled)
+- **Location** – User's location (null if geo-location is disabled)
+- **Translations** – Consent manager copy (from \`Accept-Language\` header)
+- **Branding** – Configured branding key
+- **GVL** – Global Vendor List when IAB is active for the request
+
+Use for geo-targeted consent banners and regional compliance.`,
+        tags: [
+            'Init'
+        ],
+        responses: {
+            200: {
+                description: 'Initialization payload (jurisdiction, location, translations, branding, GVL)',
+                content: {
+                    'application/json': {
+                        schema: resolver(initOutputSchema)
+                    }
+                }
+            }
+        }
+    }), async (c)=>{
+        const ctx = c.get('c15tContext');
+        const payload = await resolveInitPayload(c.req.raw, options, ctx?.logger);
+        return c.json(payload);
+    });
+    return app;
+};
+const syncCurrentLegalDocumentHandler = async (c)=>{
+    const ctx = c.get('c15tContext');
+    const logger = ctx.logger;
+    logger.info('Handling PUT /legal-documents/:type/current request');
+    if (!ctx.apiKeyAuthenticated) throw new HTTPException(401, {
+        message: 'API key required. Use Authorization: Bearer <api_key>',
+        cause: {
+            code: 'UNAUTHORIZED'
+        }
+    });
+    const type = c.req.param('type');
+    const body = await c.req.json();
+    const effectiveDate = new Date(body.effectiveDate);
+    if (Number.isNaN(effectiveDate.getTime())) throw new HTTPException(422, {
+        message: 'effectiveDate must be a valid ISO-8601 string',
+        cause: {
+            code: 'INPUT_VALIDATION_FAILED'
+        }
+    });
+    try {
+        const policy = await ctx.registry.syncCurrentLegalDocumentPolicy({
+            type,
+            version: body.version,
+            hash: body.hash,
+            effectiveDate
+        });
+        return c.json({
+            policy: {
+                id: policy.id,
+                type: policy.type,
+                version: policy.version,
+                hash: policy.hash,
+                effectiveDate: policy.effectiveDate,
+                isActive: policy.isActive
+            }
+        });
+    } catch (error) {
+        logger.error('Error in PUT /legal-documents/:type/current handler', {
+            error: extractErrorMessage(error),
+            errorType: error instanceof Error ? error.constructor.name : typeof error
+        });
+        if (error instanceof LegalDocumentPolicyConflictError) throw new HTTPException(409, {
+            message: error.message,
+            cause: {
+                code: 'LEGAL_DOCUMENT_RELEASE_CONFLICT'
+            }
+        });
+        if (error instanceof HTTPException) throw error;
+        throw new HTTPException(500, {
+            message: 'Internal server error',
+            cause: {
+                code: 'INTERNAL_SERVER_ERROR'
+            }
+        });
+    }
+};
+const createLegalDocumentRoutes = ()=>{
+    const app = new Hono();
+    app.put('/:type/current', describeRoute({
+        summary: 'Sync the current legal document release (API key required)',
+        description: 'Marks a legal document release as the latest known version for its type. Requires a Bearer API key.',
+        tags: [
+            'LegalDocument'
+        ],
+        security: [
+            {
+                bearerAuth: []
+            }
+        ],
+        responses: {
+            200: {
+                description: 'Current legal document release synced successfully',
+                content: {
+                    'application/json': {
+                        schema: resolver(legalDocumentCurrentOutputSchema)
+                    }
+                }
+            },
+            401: {
+                description: 'Missing or invalid API key'
+            },
+            409: {
+                description: 'Release metadata conflicts with an existing release'
+            }
+        }
+    }), validator('param', legalDocumentCurrentParamsSchema), validator('json', legalDocumentCurrentInputSchema), syncCurrentLegalDocumentHandler);
+    return app;
+};
+function getHeaders(headers) {
+    if (!headers) return {
+        countryCode: null,
+        regionCode: null,
+        acceptLanguage: null
+    };
+    const normalizeHeader = (value)=>{
+        if (!value) return null;
+        return Array.isArray(value) ? value[0] ?? null : value;
+    };
+    const countryCode = normalizeHeader(headers.get('x-c15t-country')) ?? normalizeHeader(headers.get('cf-ipcountry')) ?? normalizeHeader(headers.get('x-vercel-ip-country')) ?? normalizeHeader(headers.get('x-amz-cf-ipcountry')) ?? normalizeHeader(headers.get('x-country-code'));
+    const regionCode = normalizeHeader(headers.get('x-c15t-region')) ?? normalizeHeader(headers.get('x-vercel-ip-country-region')) ?? normalizeHeader(headers.get('x-region-code'));
+    const acceptLanguage = normalizeHeader(headers.get('accept-language'));
+    return {
+        countryCode,
+        regionCode,
+        acceptLanguage
+    };
+}
+const statusHandler = async (c)=>{
+    const ctx = c.get('c15tContext');
+    const { countryCode, regionCode, acceptLanguage } = getHeaders(ctx.headers);
+    const clientInfo = {
+        ip: ctx.ipAddress ?? null,
+        acceptLanguage,
+        userAgent: ctx.userAgent ?? null,
+        region: {
+            countryCode,
+            regionCode
+        }
+    };
+    try {
+        await ctx.db.findFirst('subject', {});
+        return c.json({
+            version: version,
+            timestamp: new Date(),
+            client: clientInfo
+        });
+    } catch (error) {
+        ctx.logger.error('Database health check failed', {
+            error
+        });
+        throw new HTTPException(503, {
+            message: 'Database health check failed',
+            cause: {
+                code: 'SERVICE_UNAVAILABLE',
+                error
+            }
+        });
+    }
+};
+const createStatusRoute = ()=>{
+    const app = new Hono();
+    app.get('/', describeRoute({
+        summary: 'Health check and API status',
+        description: `Returns API version, timestamp, and client info (IP, region, user agent).
+
+Use for health checks, load balancer probes, and debugging. Performs a lightweight DB check; returns 503 if the database is unreachable.`,
+        tags: [
+            'Status'
+        ],
+        responses: {
+            200: {
+                description: 'API is healthy (version, timestamp, client info)',
+                content: {
+                    'application/json': {
+                        schema: resolver(statusOutputSchema)
+                    }
+                }
+            },
+            503: {
+                description: 'Service unavailable (e.g. database unreachable)'
+            }
+        }
+    }), statusHandler);
+    return app;
+};
+const getSubjectHandler = async (c)=>{
+    const ctx = c.get('c15tContext');
+    const logger = ctx.logger;
+    logger.info('Handling GET /subjects/:id request');
+    const { db, registry } = ctx;
+    const subjectId = c.req.param('id');
+    const type = c.req.query('type');
+    const typeFilter = type?.split(',').map((t)=>t.trim()) || [];
+    if (!subjectId) throw new HTTPException(400, {
+        message: 'Subject ID is required',
+        cause: {
+            code: 'SUBJECT_ID_REQUIRED'
+        }
+    });
+    logger.debug('Request parameters', {
+        subjectId,
+        typeFilter
+    });
+    try {
+        const subject = await db.findFirst('subject', {
+            where: (b)=>b('id', '=', subjectId)
+        });
+        if (!subject) throw new HTTPException(404, {
+            message: 'Subject not found',
+            cause: {
+                code: 'SUBJECT_NOT_FOUND',
+                subjectId
+            }
+        });
+        const consents = await db.findMany('consent', {
+            where: (b)=>b('subjectId', '=', subjectId)
+        });
+        const consentItems = await enrichConsents(consents, {
+            db,
+            registry
+        });
+        const filteredConsents = typeFilter.length > 0 ? consentItems.filter((consent)=>typeFilter.includes(consent.type)) : consentItems;
+        const isValid = 0 === typeFilter.length || typeFilter.every((t)=>filteredConsents.some((consent)=>consent.type === t && consent.isLatestPolicy));
+        return c.json({
+            subject: {
+                id: subject.id,
+                externalId: subject.externalId ?? void 0,
+                createdAt: subject.createdAt
+            },
+            consents: filteredConsents,
+            isValid
+        });
+    } catch (error) {
+        logger.error('Error in GET /subjects/:id handler', {
+            error: extractErrorMessage(error),
+            errorType: error instanceof Error ? error.constructor.name : typeof error
+        });
+        if (error instanceof HTTPException) throw error;
+        throw new HTTPException(500, {
+            message: 'Internal server error',
+            cause: {
+                code: 'INTERNAL_SERVER_ERROR'
+            }
+        });
+    }
+};
+const listSubjectsHandler = async (c)=>{
+    const ctx = c.get('c15tContext');
+    const logger = ctx.logger;
+    logger.info('Handling GET /subjects request');
+    const { db, registry } = ctx;
+    if (!ctx.apiKeyAuthenticated) throw new HTTPException(401, {
+        message: 'API key required. Use Authorization: Bearer <api_key>',
+        cause: {
+            code: 'UNAUTHORIZED'
+        }
+    });
+    const externalId = c.req.query('externalId');
+    if (!externalId) throw new HTTPException(422, {
+        message: 'externalId query parameter is required',
+        cause: {
+            code: 'EXTERNAL_ID_REQUIRED'
+        }
+    });
+    logger.debug('Request parameters', {
+        externalId
+    });
+    try {
+        const subjects = await db.findMany('subject', {
+            where: (b)=>b('externalId', '=', externalId)
+        });
+        const subjectItems = await Promise.all(subjects.map(async (subject)=>{
+            const consents = await db.findMany('consent', {
+                where: (b)=>b('subjectId', '=', subject.id)
+            });
+            const consentItems = await enrichConsents(consents, {
+                db,
+                registry
+            });
+            return {
+                id: subject.id,
+                externalId: subject.externalId ?? externalId,
+                createdAt: subject.createdAt,
+                consents: consentItems
+            };
+        }));
+        logger.info('Found subjects for externalId', {
+            externalId,
+            count: subjectItems.length
+        });
+        return c.json({
+            subjects: subjectItems
+        });
+    } catch (error) {
+        logger.error('Error in GET /subjects handler', {
+            error: extractErrorMessage(error),
+            errorType: error instanceof Error ? error.constructor.name : typeof error
+        });
+        if (error instanceof HTTPException) throw error;
+        throw new HTTPException(500, {
+            message: 'Internal server error',
+            cause: {
+                code: 'INTERNAL_SERVER_ERROR'
+            }
+        });
+    }
+};
+const utils_prefixes = {
+    auditLog: 'log',
+    consent: 'cns',
+    consentPolicy: 'pol',
+    consentPurpose: 'pur',
+    domain: 'dom',
+    subject: 'sub'
+};
+const utils_b58 = base_x('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');
+function utils_generateId(model) {
+    const buf = crypto.getRandomValues(new Uint8Array(20));
+    const prefix = utils_prefixes[model];
+    const EPOCH_TIMESTAMP = 1700000000000;
+    const t = Date.now() - EPOCH_TIMESTAMP;
+    const high = Math.floor(t / 0x100000000);
+    const low = t >>> 0;
+    buf[0] = high >>> 24 & 255;
+    buf[1] = high >>> 16 & 255;
+    buf[2] = high >>> 8 & 255;
+    buf[3] = 255 & high;
+    buf[4] = low >>> 24 & 255;
+    buf[5] = low >>> 16 & 255;
+    buf[6] = low >>> 8 & 255;
+    buf[7] = 255 & low;
+    return `${prefix}_${utils_b58.encode(buf)}`;
+}
+async function utils_generateUniqueId(db, model, ctx, options = {}) {
+    const { maxRetries = 10, attempt = 0, baseDelay = 5 } = options;
+    if (attempt >= maxRetries) {
+        const error = new Error(`Failed to generate unique ID for ${model} after ${maxRetries} attempts`);
+        ctx?.logger?.error?.('ID generation failed', {
+            model,
+            maxRetries
+        });
+        throw error;
+    }
+    const id = utils_generateId(model);
+    try {
+        const existing = await db.findFirst(model, {
+            where: (b)=>b('id', '=', id)
+        });
+        if (existing) {
+            ctx?.logger?.debug?.('ID conflict detected', {
+                id,
+                model,
+                attempt: attempt + 1,
+                maxRetries
+            });
+            const delay = Math.min(baseDelay * 2 ** attempt, 1000);
+            await new Promise((resolve)=>setTimeout(resolve, delay));
+            return utils_generateUniqueId(db, model, ctx, {
+                maxRetries,
+                attempt: attempt + 1,
+                baseDelay
+            });
+        }
+        return id;
+    } catch (error) {
+        ctx?.logger?.error?.('Error checking ID uniqueness', {
+            error: error.message,
+            model,
+            attempt
+        });
+        if (attempt < maxRetries - 1) {
+            const delay = Math.min(baseDelay * 2 ** attempt, 2000);
+            await new Promise((resolve)=>setTimeout(resolve, delay));
+            return utils_generateUniqueId(db, model, ctx, {
+                maxRetries,
+                attempt: attempt + 1,
+                baseDelay
+            });
+        }
+        throw error;
+    }
+}
+const patchSubjectHandler = async (c)=>{
+    const ctx = c.get('c15tContext');
+    const logger = ctx.logger;
+    logger.info('Handling PATCH /subjects/:id request');
+    const { db } = ctx;
+    const subjectId = c.req.param('id');
+    const body = await c.req.json();
+    const { externalId, identityProvider = 'external' } = body;
+    if (!subjectId) throw new HTTPException(400, {
+        message: 'Subject ID is required',
+        cause: {
+            code: 'SUBJECT_ID_REQUIRED'
+        }
+    });
+    logger.debug('Request parameters', {
+        subjectId,
+        externalId,
+        identityProvider
+    });
+    try {
+        const subject = await db.findFirst('subject', {
+            where: (b)=>b('id', '=', subjectId)
+        });
+        if (!subject) throw new HTTPException(404, {
+            message: 'Subject not found',
+            cause: {
+                code: 'SUBJECT_NOT_FOUND',
+                subjectId
+            }
+        });
+        await db.transaction(async (tx)=>{
+            await tx.updateMany('subject', {
+                where: (b)=>b('id', '=', subjectId),
+                set: {
+                    externalId,
+                    identityProvider,
+                    updatedAt: new Date()
+                }
+            });
+            await tx.create('auditLog', {
+                id: await utils_generateUniqueId(tx, 'auditLog', ctx),
+                subjectId,
+                entityType: 'subject',
+                entityId: subjectId,
+                actionType: 'identify_user',
+                ipAddress: ctx.ipAddress || null,
+                userAgent: ctx.userAgent || null,
+                changes: {
+                    externalId: {
+                        from: subject.externalId,
+                        to: externalId
+                    },
+                    identityProvider: {
+                        from: subject.identityProvider,
+                        to: identityProvider
+                    }
+                },
+                metadata: {
+                    externalId,
+                    identityProvider
+                }
+            });
+        });
+        logger.info('Subject linked to external ID', {
+            subjectId,
+            externalId,
+            identityProvider
+        });
+        getMetrics()?.recordSubjectLinked(identityProvider);
+        return c.json({
+            success: true,
+            subject: {
+                id: subjectId,
+                externalId
+            }
+        });
+    } catch (error) {
+        logger.error('Error in PATCH /subjects/:id handler', {
+            error: extractErrorMessage(error),
+            errorType: error instanceof Error ? error.constructor.name : typeof error
+        });
+        if (error instanceof HTTPException) throw error;
+        throw new HTTPException(500, {
+            message: 'Internal server error',
+            cause: {
+                code: 'INTERNAL_SERVER_ERROR'
+            }
+        });
+    }
+};
+const DEFAULT_ISSUER = 'c15t';
+const DEFAULT_AUDIENCE = 'c15t-legal-document-snapshot';
+function isLegalDocumentPolicyType(type) {
+    return 'privacy_policy' === type || 'terms_and_conditions' === type || 'dpa' === type;
+}
+function resolveSnapshotIssuer(options) {
+    return options?.issuer?.trim() || DEFAULT_ISSUER;
+}
+function resolveSnapshotAudience(params) {
+    const configuredAudience = params.options?.audience?.trim();
+    if (configuredAudience) return configuredAudience;
+    return params.tenantId ? `${DEFAULT_AUDIENCE}:${params.tenantId}` : DEFAULT_AUDIENCE;
+}
+function getSigningKey(secret) {
+    return new TextEncoder().encode(secret);
+}
+function isLegalDocumentSnapshotPayload(payload) {
+    return 'string' == typeof payload.iss && 'string' == typeof payload.aud && 'string' == typeof payload.sub && isLegalDocumentPolicyType(payload.type) && 'string' == typeof payload.version && 'string' == typeof payload.hash && 'string' == typeof payload.effectiveDate && 'number' == typeof payload.iat && 'number' == typeof payload.exp;
+}
+async function verifyLegalDocumentSnapshotToken(params) {
+    const { token, options, tenantId } = params;
+    if (!options?.signingKey) return {
+        valid: false,
+        reason: 'missing'
+    };
+    if (!token) return {
+        valid: false,
+        reason: 'missing'
+    };
+    if (3 !== token.split('.').length) return {
+        valid: false,
+        reason: 'malformed'
+    };
+    try {
+        const { payload, protectedHeader } = await jwtVerify(token, getSigningKey(options.signingKey), {
+            issuer: resolveSnapshotIssuer(options),
+            audience: resolveSnapshotAudience({
+                options,
+                tenantId
+            })
+        });
+        const header = protectedHeader;
+        if ('HS256' !== header.alg || 'JWT' !== header.typ) return {
+            valid: false,
+            reason: 'invalid'
+        };
+        if (!isLegalDocumentSnapshotPayload(payload)) return {
+            valid: false,
+            reason: 'invalid'
+        };
+        if (payload.sub !== payload.hash) return {
+            valid: false,
+            reason: 'invalid'
+        };
+        if ((tenantId ?? void 0) !== (payload.tenantId ?? void 0)) return {
+            valid: false,
+            reason: 'invalid'
+        };
+        return {
+            valid: true,
+            payload
+        };
+    } catch (error) {
+        if (error instanceof errors.JWTExpired) return {
+            valid: false,
+            reason: 'expired'
+        };
+        return {
+            valid: false,
+            reason: 'invalid'
+        };
+    }
+}
+function buildRuntimeDecisionDedupeKey(input) {
+    return [
+        input.tenantId ?? 'default',
+        input.fingerprint,
+        input.matchedBy,
+        input.countryCode ?? 'none',
+        input.regionCode ?? 'none',
+        input.jurisdiction,
+        input.language ?? 'none'
+    ].join('|');
+}
+function buildDecisionPayload(params) {
+    const { tenantId, snapshot, decision, location, jurisdiction, language, proofConfig } = params;
+    if (snapshot?.valid && snapshot.payload) {
+        const sp = snapshot.payload;
+        return {
+            tenantId,
+            policyId: sp.policyId,
+            fingerprint: sp.fingerprint,
+            matchedBy: sp.matchedBy,
+            countryCode: sp.country,
+            regionCode: sp.region,
+            jurisdiction: sp.jurisdiction,
+            language: sp.language,
+            model: sp.model,
+            policyI18n: sp.policyI18n,
+            uiMode: sp.uiMode,
+            bannerUi: sp.bannerUi,
+            dialogUi: sp.dialogUi,
+            categories: sp.categories,
+            preselectedCategories: sp.preselectedCategories,
+            proofConfig: sp.proofConfig,
+            dedupeKey: buildRuntimeDecisionDedupeKey({
+                tenantId,
+                fingerprint: sp.fingerprint,
+                matchedBy: sp.matchedBy,
+                countryCode: sp.country,
+                regionCode: sp.region,
+                jurisdiction: sp.jurisdiction,
+                language: sp.language
+            }),
+            source: 'snapshot_token'
+        };
+    }
+    if (decision) return {
+        tenantId,
+        policyId: decision.policy.id,
+        fingerprint: decision.fingerprint,
+        matchedBy: decision.matchedBy,
+        countryCode: location.countryCode,
+        regionCode: location.regionCode,
+        jurisdiction,
+        language,
+        model: decision.policy.model,
+        policyI18n: decision.policy.i18n,
+        uiMode: decision.policy.ui?.mode,
+        bannerUi: decision.policy.ui?.banner,
+        dialogUi: decision.policy.ui?.dialog,
+        categories: decision.policy.consent?.categories,
+        preselectedCategories: decision.policy.consent?.preselectedCategories,
+        proofConfig,
+        dedupeKey: buildRuntimeDecisionDedupeKey({
+            tenantId,
+            fingerprint: decision.fingerprint,
+            matchedBy: decision.matchedBy,
+            countryCode: location.countryCode,
+            regionCode: location.regionCode,
+            jurisdiction,
+            language
+        }),
+        source: 'write_time_fallback'
+    };
+}
+function parseLanguageFromHeader(header) {
+    if (!header) return;
+    const firstLanguage = header.split(',')[0]?.split(';')[0]?.trim();
+    if (!firstLanguage) return;
+    return firstLanguage.split('-')[0]?.toLowerCase();
+}
+function isLegalDocumentType(type) {
+    return 'privacy_policy' === type || 'terms_and_conditions' === type || 'dpa' === type;
+}
+function resolveSnapshotFailureMode(ctx) {
+    return ctx.policySnapshot?.onValidationFailure ?? 'reject';
+}
+function buildSnapshotHttpException(reason) {
+    switch(reason){
+        case 'missing':
+            return new HTTPException(409, {
+                message: 'Policy snapshot token is required',
+                cause: {
+                    code: 'POLICY_SNAPSHOT_REQUIRED'
+                }
+            });
+        case 'expired':
+            return new HTTPException(409, {
+                message: 'Policy snapshot token has expired',
+                cause: {
+                    code: 'POLICY_SNAPSHOT_EXPIRED'
+                }
+            });
+        case 'malformed':
+        case 'invalid':
+            return new HTTPException(409, {
+                message: 'Policy snapshot token is invalid',
+                cause: {
+                    code: 'POLICY_SNAPSHOT_INVALID'
+                }
+            });
+        default:
+            {
+                const _exhaustive = reason;
+                throw new Error(`Unhandled policy snapshot verification failure reason: ${_exhaustive}`);
+            }
+    }
+}
+function buildLegalDocumentSnapshotHttpException(reason) {
+    switch(reason){
+        case 'missing':
+            return new HTTPException(409, {
+                message: 'Legal document snapshot token is required',
+                cause: {
+                    code: 'LEGAL_DOCUMENT_SNAPSHOT_REQUIRED'
+                }
+            });
+        case 'expired':
+            return new HTTPException(409, {
+                message: 'Legal document snapshot token has expired',
+                cause: {
+                    code: 'LEGAL_DOCUMENT_SNAPSHOT_EXPIRED'
+                }
+            });
+        case 'malformed':
+        case 'invalid':
+            return new HTTPException(409, {
+                message: 'Legal document snapshot token is invalid',
+                cause: {
+                    code: 'LEGAL_DOCUMENT_SNAPSHOT_INVALID'
+                }
+            });
+        default:
+            {
+                const _exhaustive = reason;
+                throw new Error(`Unhandled legal document snapshot verification failure reason: ${_exhaustive}`);
+            }
+    }
+}
+function buildLegalDocumentProofHttpException(message) {
+    return new HTTPException(409, {
+        message,
+        cause: {
+            code: 'LEGAL_DOCUMENT_PROOF_REQUIRED'
+        }
+    });
+}
+const postSubjectHandler = async (c)=>{
+    const ctx = c.get('c15tContext');
+    const logger = ctx.logger;
+    logger.info('Handling POST /subjects request');
+    const { db, registry } = ctx;
+    const input = await c.req.json();
+    const { type, subjectId, identityProvider, externalSubjectId, domain, metadata, givenAt: givenAtEpoch } = input;
+    const preferences = 'preferences' in input ? input.preferences : void 0;
+    const givenAt = new Date(givenAtEpoch);
+    const rawConsentAction = 'consentAction' in input ? input.consentAction : void 0;
+    let derivedConsentAction;
+    logger.debug('Request parameters', {
+        type,
+        subjectId,
+        identityProvider,
+        externalSubjectId,
+        domain
+    });
+    try {
+        if ('cookie_banner' === type) logger.warn('`cookie_banner` policy type is deprecated in 2.0 RC and will be removed in 2.0 GA. Use backend runtime `policyPacks` for banner behavior.');
+        const request = c.req.raw ?? new Request('https://c15t.local/subjects');
+        const acceptLanguage = request.headers.get('accept-language');
+        const requestLanguage = parseLanguageFromHeader(acceptLanguage);
+        const location = await getLocation(request, ctx);
+        const resolvedJurisdiction = getJurisdiction(location, ctx);
+        const legalDocumentConsent = isLegalDocumentType(type);
+        const runtimeSnapshotVerification = legalDocumentConsent ? {
+            valid: false,
+            reason: 'missing'
+        } : await verifyPolicySnapshotToken({
+            token: input.policySnapshotToken,
+            options: ctx.policySnapshot,
+            tenantId: ctx.tenantId
+        });
+        const legalDocumentSnapshotVerification = legalDocumentConsent ? await verifyLegalDocumentSnapshotToken({
+            token: input.documentSnapshotToken,
+            options: ctx.legalDocumentSnapshot,
+            tenantId: ctx.tenantId
+        }) : {
+            valid: false,
+            reason: 'missing'
+        };
+        const hasValidSnapshot = runtimeSnapshotVerification.valid;
+        const snapshotPayload = runtimeSnapshotVerification.valid ? runtimeSnapshotVerification.payload : null;
+        const shouldRequireSnapshot = !legalDocumentConsent && !!ctx.policySnapshot?.signingKey && 'reject' === resolveSnapshotFailureMode(ctx);
+        if (!hasValidSnapshot && shouldRequireSnapshot) throw buildSnapshotHttpException(runtimeSnapshotVerification.reason);
+        const shouldRequireLegalDocumentSnapshot = legalDocumentConsent && !!ctx.legalDocumentSnapshot?.signingKey;
+        if (shouldRequireLegalDocumentSnapshot && !legalDocumentSnapshotVerification.valid) throw buildLegalDocumentSnapshotHttpException(legalDocumentSnapshotVerification.reason);
+        const resolvedPolicyDecision = hasValidSnapshot ? void 0 : legalDocumentConsent ? void 0 : await policy_resolvePolicyDecision({
+            policies: ctx.policyPacks,
+            countryCode: location.countryCode,
+            regionCode: location.regionCode,
+            jurisdiction: resolvedJurisdiction,
+            iabEnabled: ctx.iab?.enabled === true
+        });
+        const effectivePolicy = hasValidSnapshot && snapshotPayload ? {
+            id: snapshotPayload.policyId,
+            model: snapshotPayload.model,
+            i18n: snapshotPayload.policyI18n,
+            consent: {
+                expiryDays: snapshotPayload.expiryDays,
+                scopeMode: snapshotPayload.scopeMode,
+                categories: snapshotPayload.categories,
+                preselectedCategories: snapshotPayload.preselectedCategories,
+                gpc: snapshotPayload.gpc
+            },
+            ui: {
+                mode: snapshotPayload.uiMode,
+                banner: snapshotPayload.bannerUi,
+                dialog: snapshotPayload.dialogUi
+            },
+            proof: snapshotPayload.proofConfig
+        } : resolvedPolicyDecision?.policy;
+        const effectiveModel = effectivePolicy?.model ?? ('opt-in' === input.jurisdictionModel || 'opt-out' === input.jurisdictionModel || 'iab' === input.jurisdictionModel ? input.jurisdictionModel : void 0);
+        if ('all' === rawConsentAction) derivedConsentAction = 'accept_all';
+        else if ('necessary' === rawConsentAction) derivedConsentAction = 'opt-out' === effectiveModel ? 'opt_out' : 'reject_all';
+        else if ('custom' === rawConsentAction) derivedConsentAction = 'custom';
+        const subject = await registry.findOrCreateSubject({
+            subjectId,
+            externalSubjectId,
+            identityProvider,
+            ipAddress: ctx.ipAddress
+        });
+        if (!subject) throw new HTTPException(500, {
+            message: 'Failed to create subject',
+            cause: {
+                code: 'SUBJECT_CREATION_FAILED',
+                subjectId
+            }
+        });
+        logger.debug('Subject found/created', {
+            subjectId: subject.id
+        });
+        const domainRecord = await registry.findOrCreateDomain(domain);
+        if (!domainRecord) throw new HTTPException(500, {
+            message: 'Failed to create domain',
+            cause: {
+                code: 'DOMAIN_CREATION_FAILED',
+                domain
+            }
+        });
+        let policyId;
+        let purposeIds = [];
+        let appliedPreferences;
+        const inputPolicyId = 'policyId' in input ? input.policyId : void 0;
+        if (legalDocumentConsent && legalDocumentSnapshotVerification.valid) {
+            if (legalDocumentSnapshotVerification.payload.type !== type) throw buildLegalDocumentSnapshotHttpException('invalid');
+            const effectiveDate = new Date(legalDocumentSnapshotVerification.payload.effectiveDate);
+            if (Number.isNaN(effectiveDate.getTime())) throw buildLegalDocumentSnapshotHttpException('invalid');
+            const documentPolicy = await registry.findOrCreateLegalDocumentPolicy({
+                type,
+                version: legalDocumentSnapshotVerification.payload.version,
+                hash: legalDocumentSnapshotVerification.payload.hash,
+                effectiveDate
+            });
+            policyId = documentPolicy.id;
+        } else if (legalDocumentConsent) {
+            if (!ctx.legalDocumentSnapshot?.signingKey && !inputPolicyId) throw buildLegalDocumentProofHttpException('Legal document consent requires policyId when snapshot verification is disabled');
+            if (!inputPolicyId) throw buildLegalDocumentProofHttpException('Legal document consent requires a valid document snapshot token or policyId');
+            policyId = inputPolicyId;
+            const policy = await registry.findConsentPolicyById(inputPolicyId);
+            if (!policy) throw new HTTPException(404, {
+                message: 'Policy not found',
+                cause: {
+                    code: 'POLICY_NOT_FOUND',
+                    policyId,
+                    type
+                }
+            });
+            if (!policy.isActive) throw new HTTPException(400, {
+                message: 'Policy is inactive',
+                cause: {
+                    code: 'POLICY_INACTIVE',
+                    policyId,
+                    type
+                }
+            });
+        } else if (inputPolicyId) {
+            policyId = inputPolicyId;
+            const policy = await registry.findConsentPolicyById(inputPolicyId);
+            if (!policy) throw new HTTPException(404, {
+                message: 'Policy not found',
+                cause: {
+                    code: 'POLICY_NOT_FOUND',
+                    policyId,
+                    type
+                }
+            });
+            if (!policy.isActive) throw new HTTPException(400, {
+                message: 'Policy is inactive',
+                cause: {
+                    code: 'POLICY_INACTIVE',
+                    policyId,
+                    type
+                }
+            });
+        } else {
+            const policy = await registry.findOrCreatePolicy(type);
+            if (!policy) throw new HTTPException(500, {
+                message: 'Failed to create policy',
+                cause: {
+                    code: 'POLICY_CREATION_FAILED',
+                    type
+                }
+            });
+            policyId = policy.id;
+        }
+        if (preferences) {
+            const allowedCategories = effectivePolicy?.consent?.categories;
+            const effectiveScopeMode = effectivePolicy?.consent?.scopeMode ?? 'permissive';
+            const hasWildcardCategoryScope = allowedCategories?.includes('*') === true;
+            const appliedPreferenceEntries = Object.entries(preferences);
+            let filteredAppliedPreferenceEntries = appliedPreferenceEntries;
+            if (allowedCategories && allowedCategories.length > 0 && !hasWildcardCategoryScope) {
+                const disallowed = appliedPreferenceEntries.map(([purpose])=>purpose).filter((purpose)=>!allowedCategories.includes(purpose));
+                filteredAppliedPreferenceEntries = appliedPreferenceEntries.filter(([purpose])=>allowedCategories.includes(purpose));
+                if (disallowed.length > 0 && 'strict' === effectiveScopeMode) throw new HTTPException(400, {
+                    message: 'Preferences include categories not allowed by policy',
+                    cause: {
+                        code: 'PURPOSE_NOT_ALLOWED',
+                        disallowed
+                    }
+                });
+            }
+            appliedPreferences = Object.fromEntries(filteredAppliedPreferenceEntries);
+            const filteredConsentedPurposeCodes = filteredAppliedPreferenceEntries.filter(([_, isConsented])=>isConsented).map(([purposeCode])=>purposeCode);
+            logger.debug('Consented purposes', {
+                consentedPurposes: filteredConsentedPurposeCodes
+            });
+            const purposesRaw = await Promise.all(filteredConsentedPurposeCodes.map((purposeCode)=>registry.findOrCreateConsentPurposeByCode(purposeCode)));
+            const purposes = purposesRaw.map((purpose)=>purpose?.id ?? null).filter((id)=>Boolean(id));
+            logger.debug('Filtered purposes', {
+                purposes
+            });
+            if (0 === purposes.length) logger.warn('No valid purpose IDs found after filtering. Using empty list.', {
+                consentedPurposes: filteredConsentedPurposeCodes
+            });
+            purposeIds = purposes;
+        }
+        const expiryDays = effectivePolicy?.consent?.expiryDays;
+        const validUntil = 'number' == typeof expiryDays && Number.isFinite(expiryDays) ? new Date(givenAt.getTime() + 86400000 * Math.max(0, expiryDays)) : void 0;
+        const proofConfig = effectivePolicy?.proof;
+        const shouldStoreIp = proofConfig?.storeIp ?? true;
+        const shouldStoreUserAgent = proofConfig?.storeUserAgent ?? true;
+        const shouldStoreLanguage = proofConfig?.storeLanguage ?? false;
+        const effectiveLanguage = (snapshotPayload?.language && hasValidSnapshot ? snapshotPayload.language : requestLanguage) ?? void 0;
+        const metadataWithPolicy = {
+            ...metadata ?? {},
+            ...shouldStoreLanguage && effectiveLanguage ? {
+                policyLanguage: effectiveLanguage
+            } : {}
+        };
+        const effectiveJurisdiction = hasValidSnapshot && snapshotPayload ? snapshotPayload.jurisdiction : resolvedJurisdiction;
+        const decisionPayload = buildDecisionPayload({
+            tenantId: ctx.tenantId,
+            snapshot: hasValidSnapshot && snapshotPayload ? {
+                valid: true,
+                payload: snapshotPayload
+            } : null,
+            decision: resolvedPolicyDecision,
+            location: {
+                countryCode: location.countryCode,
+                regionCode: location.regionCode
+            },
+            jurisdiction: resolvedJurisdiction,
+            language: effectiveLanguage,
+            proofConfig
+        });
+        const existingConsent = await db.findFirst('consent', {
+            where: (b)=>b.and(b('subjectId', '=', subject.id), b('domainId', '=', domainRecord.id), b('policyId', '=', policyId), b('givenAt', '=', givenAt))
+        });
+        if (existingConsent) {
+            logger.debug('Duplicate consent detected, returning existing record', {
+                consentId: existingConsent.id
+            });
+            return c.json({
+                subjectId: subject.id,
+                consentId: existingConsent.id,
+                domainId: domainRecord.id,
+                domain: domainRecord.name,
+                type,
+                metadata,
+                appliedPreferences,
+                uiSource: input.uiSource,
+                givenAt: existingConsent.givenAt
+            });
+        }
+        const result = await db.transaction(async (tx)=>{
+            logger.debug('Creating consent record', {
+                subjectId: subject.id,
+                domainId: domainRecord.id,
+                policyId,
+                purposeIds
+            });
+            const runtimePolicyDecision = decisionPayload ? await tx.findFirst('runtimePolicyDecision', {
+                where: (b)=>b('dedupeKey', '=', decisionPayload.dedupeKey)
+            }) ?? await tx.create('runtimePolicyDecision', {
+                id: `rpd_${crypto.randomUUID().replaceAll('-', '')}`,
+                tenantId: decisionPayload.tenantId,
+                policyId: decisionPayload.policyId,
+                fingerprint: decisionPayload.fingerprint,
+                matchedBy: decisionPayload.matchedBy,
+                countryCode: decisionPayload.countryCode,
+                regionCode: decisionPayload.regionCode,
+                jurisdiction: decisionPayload.jurisdiction,
+                language: decisionPayload.language,
+                model: decisionPayload.model,
+                policyI18n: decisionPayload.policyI18n ? {
+                    json: decisionPayload.policyI18n
+                } : void 0,
+                uiMode: decisionPayload.uiMode,
+                bannerUi: decisionPayload.bannerUi ? {
+                    json: decisionPayload.bannerUi
+                } : void 0,
+                dialogUi: decisionPayload.dialogUi ? {
+                    json: decisionPayload.dialogUi
+                } : void 0,
+                categories: decisionPayload.categories ? {
+                    json: decisionPayload.categories
+                } : void 0,
+                preselectedCategories: decisionPayload.preselectedCategories ? {
+                    json: decisionPayload.preselectedCategories
+                } : void 0,
+                proofConfig: decisionPayload.proofConfig ? {
+                    json: decisionPayload.proofConfig
+                } : void 0,
+                dedupeKey: decisionPayload.dedupeKey
+            }).catch(async ()=>tx.findFirst('runtimePolicyDecision', {
+                    where: (b)=>b('dedupeKey', '=', decisionPayload.dedupeKey)
+                })) : void 0;
+            const consentRecord = await tx.create('consent', {
+                id: await utils_generateUniqueId(tx, 'consent', ctx),
+                subjectId: subject.id,
+                domainId: domainRecord.id,
+                policyId,
+                purposeIds: {
+                    json: purposeIds
+                },
+                metadata: Object.keys(metadataWithPolicy).length > 0 ? {
+                    json: metadataWithPolicy
+                } : void 0,
+                ipAddress: shouldStoreIp ? ctx.ipAddress : null,
+                userAgent: shouldStoreUserAgent ? ctx.userAgent : null,
+                jurisdiction: effectiveJurisdiction,
+                jurisdictionModel: effectiveModel,
+                tcString: input.tcString,
+                uiSource: input.uiSource,
+                consentAction: derivedConsentAction,
+                givenAt,
+                validUntil,
+                runtimePolicyDecisionId: runtimePolicyDecision?.id,
+                runtimePolicySource: decisionPayload?.source
+            });
+            logger.debug('Created consent', {
+                consentRecord: consentRecord.id
+            });
+            if (!consentRecord) throw new HTTPException(500, {
+                message: 'Failed to create consent',
+                cause: {
+                    code: 'CONSENT_CREATION_FAILED',
+                    subjectId: subject.id,
+                    domain
+                }
+            });
+            return {
+                consent: consentRecord
+            };
+        });
+        const metrics = getMetrics();
+        if (metrics) {
+            const jurisdiction = effectiveJurisdiction;
+            metrics.recordConsentCreated({
+                type,
+                jurisdiction
+            });
+            const hasAccepted = preferences && Object.values(preferences).some(Boolean);
+            if (hasAccepted) metrics.recordConsentAccepted({
+                type,
+                jurisdiction
+            });
+            else metrics.recordConsentRejected({
+                type,
+                jurisdiction
+            });
+        }
+        return c.json({
+            subjectId: subject.id,
+            consentId: result.consent.id,
+            domainId: domainRecord.id,
+            domain: domainRecord.name,
+            type,
+            metadata,
+            appliedPreferences,
+            uiSource: input.uiSource,
+            givenAt: result.consent.givenAt
+        });
+    } catch (error) {
+        logger.error('Error in POST /subjects handler', {
+            error: extractErrorMessage(error),
+            errorType: error instanceof Error ? error.constructor.name : typeof error
+        });
+        if (error instanceof HTTPException) throw error;
+        if (error instanceof LegalDocumentPolicyConflictError) throw new HTTPException(409, {
+            message: error.message,
+            cause: {
+                code: 'LEGAL_DOCUMENT_RELEASE_CONFLICT'
+            }
+        });
+        throw new HTTPException(500, {
+            message: 'Internal server error',
+            cause: {
+                code: 'INTERNAL_SERVER_ERROR'
+            }
+        });
+    }
+};
+const createSubjectRoutes = ()=>{
+    const app = new Hono();
+    app.get('/:id', describeRoute({
+        summary: 'Get subject consent status',
+        description: "Returns the subject's consent status for this device. Use to check if the subject has valid consent for given policy types.\n\n**Query:** `type` – Filter by consent type(s), comma-separated (e.g. `privacy_policy,cookie_banner`).\n\n**Response:** `subject`, `consents` (matching filter), `isValid` (valid consent for requested type(s)).",
+        tags: [
+            'Subject',
+            'Consent'
+        ],
+        responses: {
+            200: {
+                description: 'Subject and consent records for the requested type(s)',
+                content: {
+                    'application/json': {
+                        schema: resolver(getSubjectOutputSchema)
+                    }
+                }
+            },
+            404: {
+                description: 'Subject not found for the given ID'
+            }
+        }
+    }), validator('param', getSubjectInputSchema), getSubjectHandler);
+    app.post('/', describeRoute({
+        summary: 'Record consent for a subject',
+        description: "Creates a new consent record (append-only). Creates the subject if it does not exist.\n\n**Request body by `type`:**\n- `cookie_banner` – Requires `preferences` object\n- `privacy_policy`, `dpa`, `terms_and_conditions` – Requires a valid `documentSnapshotToken` when legal-document verification is enabled, otherwise an explicit `policyId`\n- `marketing_communications`, `age_verification`, `other` – Optional `preferences`",
+        tags: [
+            'Subject',
+            'Consent'
+        ],
+        responses: {
+            200: {
+                description: 'Consent recorded; subject and consent in response',
+                content: {
+                    'application/json': {
+                        schema: resolver(postSubjectOutputSchema)
+                    }
+                }
+            },
+            422: {
+                description: 'Invalid request body (schema or validation failed)'
+            }
+        }
+    }), validator('json', postSubjectInputSchema), postSubjectHandler);
+    app.patch('/:id', describeRoute({
+        summary: 'Link external ID to subject',
+        description: 'Associates an external user ID with an existing subject (e.g. after login). Enables cross-device consent sync.',
+        tags: [
+            'Subject'
+        ],
+        responses: {
+            200: {
+                description: 'Subject updated with external ID',
+                content: {
+                    'application/json': {
+                        schema: resolver(patchSubjectOutputSchema)
+                    }
+                }
+            },
+            404: {
+                description: 'Subject not found for the given ID'
+            }
+        }
+    }), validator('param', __rspack_external_valibot.object({
+        id: subjectIdSchema
+    })), validator('json', __rspack_external_valibot.object({
+        externalId: __rspack_external_valibot.string(),
+        identityProvider: __rspack_external_valibot.optional(__rspack_external_valibot.string())
+    })), patchSubjectHandler);
+    app.get('/', describeRoute({
+        summary: 'List subjects by external ID (API key required)',
+        description: 'Returns all subjects linked to the given external ID. Requires Bearer token (API key). Use for server-side consent lookups.',
+        tags: [
+            'Subject'
+        ],
+        security: [
+            {
+                bearerAuth: []
+            }
+        ],
+        responses: {
+            200: {
+                description: 'List of subjects for the external ID',
+                content: {
+                    'application/json': {
+                        schema: resolver(listSubjectsOutputSchema)
+                    }
+                }
+            },
+            401: {
+                description: 'Missing or invalid API key'
+            }
+        }
+    }), validator('query', listSubjectsQuerySchema), listSubjectsHandler);
+    return app;
+};
+export { createConsentRoutes, createInitRoute, createLegalDocumentRoutes, createStatusRoute, createSubjectRoutes, generateUniqueId, policyRegistry };