@c15t/backend 2.0.0-rc.6 → 2.0.0

package/dist/{364.js → 915.js}

@@ -1,11 +1,349 @@
-import { checkConsentOutputSchema, checkConsentQuerySchema, getSubjectInputSchema, getSubjectOutputSchema, initOutputSchema, listSubjectsOutputSchema, listSubjectsQuerySchema, patchSubjectOutputSchema, postSubjectInputSchema, postSubjectOutputSchema, statusOutputSchema, subjectIdSchema } from "@c15t/schema";
+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 base_x from "base-x";
-import { version, getMetrics, extractErrorMessage } from "./302.js";
+import { errors, jwtVerify } from "jose";
+import { extractErrorMessage, getMetrics, withDatabaseSpan } 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;
@@ -26,7 +364,7 @@ async function batchLoadPolicies(policyIds, ctx) {
     for (const p of policyMap.values())uniqueTypes.add(p.type);
     const latestPolicyByType = new Map();
     for (const type of uniqueTypes){
-        const latest = await registry.findOrCreatePolicy(type);
+        const latest = await registry.findLatestPolicyByType(type);
         if (latest) latestPolicyByType.set(type, latest.id);
     }
     return {
@@ -52,11 +390,17 @@ async function enrichConsents(consents, ctx) {
     }
     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;
             }
         }
@@ -73,6 +417,9 @@ async function enrichConsents(consents, ctx) {
             id: consent.id,
             type: policyType,
             policyId: consent.policyId ?? void 0,
+            policyVersion,
+            policyHash,
+            policyEffectiveDate,
             isLatestPolicy,
             preferences,
             givenAt: consent.givenAt
@@ -240,6 +587,94 @@ Use for geo-targeted consent banners and regional compliance.`,
     });
     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,
@@ -274,7 +709,7 @@ const statusHandler = async (c)=>{
     try {
         await ctx.db.findFirst('subject', {});
         return c.json({
-            version: version,
+            version: "2.0.0",
             timestamp: new Date(),
             client: clientInfo
         });
@@ -439,7 +874,7 @@ const listSubjectsHandler = async (c)=>{
         });
     }
 };
-const prefixes = {
+const utils_prefixes = {
     auditLog: 'log',
     consent: 'cns',
     consentPolicy: 'pol',
@@ -447,10 +882,10 @@ const prefixes = {
     domain: 'dom',
     subject: 'sub'
 };
-const b58 = base_x('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');
-function generateId(model) {
+const utils_b58 = base_x('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');
+function utils_generateId(model) {
     const buf = crypto.getRandomValues(new Uint8Array(20));
-    const prefix = prefixes[model];
+    const prefix = utils_prefixes[model];
     const EPOCH_TIMESTAMP = 1700000000000;
     const t = Date.now() - EPOCH_TIMESTAMP;
     const high = Math.floor(t / 0x100000000);
@@ -463,9 +898,9 @@ function generateId(model) {
     buf[5] = low >>> 16 & 255;
     buf[6] = low >>> 8 & 255;
     buf[7] = 255 & low;
-    return `${prefix}_${b58.encode(buf)}`;
+    return `${prefix}_${utils_b58.encode(buf)}`;
 }
-async function generateUniqueId(db, model, ctx, options = {}) {
+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`);
@@ -475,7 +910,7 @@ async function generateUniqueId(db, model, ctx, options = {}) {
         });
         throw error;
     }
-    const id = generateId(model);
+    const id = utils_generateId(model);
     try {
         const existing = await db.findFirst(model, {
             where: (b)=>b('id', '=', id)
@@ -489,7 +924,7 @@ async function generateUniqueId(db, model, ctx, options = {}) {
             });
             const delay = Math.min(baseDelay * 2 ** attempt, 1000);
             await new Promise((resolve)=>setTimeout(resolve, delay));
-            return generateUniqueId(db, model, ctx, {
+            return utils_generateUniqueId(db, model, ctx, {
                 maxRetries,
                 attempt: attempt + 1,
                 baseDelay
@@ -505,7 +940,7 @@ async function generateUniqueId(db, model, ctx, options = {}) {
         if (attempt < maxRetries - 1) {
             const delay = Math.min(baseDelay * 2 ** attempt, 2000);
             await new Promise((resolve)=>setTimeout(resolve, delay));
-            return generateUniqueId(db, model, ctx, {
+            return utils_generateUniqueId(db, model, ctx, {
                 maxRetries,
                 attempt: attempt + 1,
                 baseDelay
@@ -554,7 +989,7 @@ const patchSubjectHandler = async (c)=>{
                 }
             });
             await tx.create('auditLog', {
-                id: await generateUniqueId(tx, 'auditLog', ctx),
+                id: await utils_generateUniqueId(tx, 'auditLog', ctx),
                 subjectId,
                 entityType: 'subject',
                 entityId: subjectId,
@@ -604,6 +1039,79 @@ const patchSubjectHandler = async (c)=>{
         });
     }
 };
+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',
@@ -683,6 +1191,9 @@ function parseLanguageFromHeader(header) {
     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';
 }
@@ -717,6 +1228,45 @@ function buildSnapshotHttpException(reason) {
             }
     }
 }
+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;
@@ -742,16 +1292,30 @@ const postSubjectHandler = async (c)=>{
         const requestLanguage = parseLanguageFromHeader(acceptLanguage);
         const location = await getLocation(request, ctx);
         const resolvedJurisdiction = getJurisdiction(location, ctx);
-        const snapshotVerification = await verifyPolicySnapshotToken({
+        const legalDocumentConsent = isLegalDocumentType(type);
+        const runtimeSnapshotVerification = legalDocumentConsent ? {
+            valid: false,
+            reason: 'missing'
+        } : await verifyPolicySnapshotToken({
             token: input.policySnapshotToken,
             options: ctx.policySnapshot,
             tenantId: ctx.tenantId
         });
-        const hasValidSnapshot = snapshotVerification.valid;
-        const snapshotPayload = snapshotVerification.valid ? snapshotVerification.payload : null;
-        const shouldRequireSnapshot = !!ctx.policySnapshot?.signingKey && 'reject' === resolveSnapshotFailureMode(ctx);
-        if (!hasValidSnapshot && shouldRequireSnapshot) throw buildSnapshotHttpException(snapshotVerification.reason);
-        const resolvedPolicyDecision = hasValidSnapshot ? void 0 : await policy_resolvePolicyDecision({
+        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,
@@ -808,7 +1372,61 @@ const postSubjectHandler = async (c)=>{
         let purposeIds = [];
         let appliedPreferences;
         const inputPolicyId = 'policyId' in input ? input.policyId : void 0;
-        if (inputPolicyId) {
+        const inputPolicyHash = 'policyHash' in input ? input.policyHash : 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 && !inputPolicyHash) throw buildLegalDocumentProofHttpException('Legal document consent requires policyId or policyHash when snapshot verification is disabled');
+            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 if (inputPolicyHash) {
+                const policy = await registry.findLegalDocumentPolicyByHash(type, inputPolicyHash);
+                if (!policy) throw new HTTPException(404, {
+                    message: 'Policy not found',
+                    cause: {
+                        code: 'POLICY_NOT_FOUND',
+                        type,
+                        policyHash: inputPolicyHash
+                    }
+                });
+                if (!policy.isActive) throw new HTTPException(400, {
+                    message: 'Policy is inactive',
+                    cause: {
+                        code: 'POLICY_INACTIVE',
+                        policyId: policy.id,
+                        type,
+                        policyHash: inputPolicyHash
+                    }
+                });
+                policyId = policy.id;
+            }
+        } else if (inputPolicyId) {
             policyId = inputPolicyId;
             const policy = await registry.findConsentPolicyById(inputPolicyId);
             if (!policy) throw new HTTPException(404, {
@@ -870,6 +1488,13 @@ const postSubjectHandler = async (c)=>{
             });
             purposeIds = purposes;
         }
+        if (!policyId) throw new HTTPException(500, {
+            message: 'Failed to resolve policy',
+            cause: {
+                code: 'POLICY_RESOLUTION_FAILED',
+                type
+            }
+        });
         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;
@@ -962,7 +1587,7 @@ const postSubjectHandler = async (c)=>{
                     where: (b)=>b('dedupeKey', '=', decisionPayload.dedupeKey)
                 })) : void 0;
             const consentRecord = await tx.create('consent', {
-                id: await generateUniqueId(tx, 'consent', ctx),
+                id: await utils_generateUniqueId(tx, 'consent', ctx),
                 subjectId: subject.id,
                 domainId: domainRecord.id,
                 policyId,
@@ -1033,6 +1658,12 @@ const postSubjectHandler = async (c)=>{
             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: {
@@ -1066,7 +1697,7 @@ const createSubjectRoutes = ()=>{
     }), 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` – Optional `policyId`\n- `marketing_communications`, `age_verification`, `other` – Optional `preferences`",
+        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` – Prefer a signed `documentSnapshotToken`; otherwise use a release `policyHash`, with `policyId` kept only for compatibility\n- `marketing_communications`, `age_verification`, `other` – Optional `preferences`",
         tags: [
             'Subject',
             'Consent'
@@ -1137,4 +1768,4 @@ const createSubjectRoutes = ()=>{
     }), validator('query', listSubjectsQuerySchema), listSubjectsHandler);
     return app;
 };
-export { createConsentRoutes, createInitRoute, createStatusRoute, createSubjectRoutes };
+export { createConsentRoutes, createInitRoute, createLegalDocumentRoutes, createStatusRoute, createSubjectRoutes, generateUniqueId, policyRegistry };