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

package/dist/core.cjs

@@ -1,6 +1,6 @@
 "use strict";
 var __webpack_modules__ = {
-    "./src/db/schema/index.ts" (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+    "./src/db/schema/index.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
         __webpack_require__.d(__webpack_exports__, {
             DB: ()=>DB
         });
@@ -180,6 +180,7 @@ var __webpack_modules__ = {
             id: (0, schema_namespaceObject.idColumn)('id', 'varchar(255)'),
             version: (0, schema_namespaceObject.column)('version', 'string'),
             type: (0, schema_namespaceObject.column)('type', 'string'),
+            hash: (0, schema_namespaceObject.column)('hash', 'string').nullable(),
             effectiveDate: (0, schema_namespaceObject.column)('effectiveDate', 'timestamp'),
             isActive: (0, schema_namespaceObject.column)('isActive', 'bool').defaultTo$(()=>true),
             createdAt: (0, schema_namespaceObject.column)('createdAt', 'timestamp').defaultTo$('now'),
@@ -294,7 +295,7 @@ var __webpack_modules__ = {
             ]
         });
     },
-    "./src/define-config.ts" (__unused_webpack_module, __webpack_exports__, __webpack_require__) {
+    "./src/define-config.ts" (__unused_rspack_module, __webpack_exports__, __webpack_require__) {
         __webpack_require__.d(__webpack_exports__, {
             defineConfig: ()=>defineConfig
         });
@@ -336,7 +337,7 @@ function __webpack_require__(moduleId) {
 })();
 (()=>{
     __webpack_require__.r = (exports1)=>{
-        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+        if ("u" > typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
             value: 'Module'
         });
         Object.defineProperty(exports1, '__esModule', {
@@ -737,7 +738,7 @@ var __webpack_exports__ = {};
             language
         };
     }
-    const version_version = '2.0.0-rc.5';
+    const version_version = '2.0.0-rc.8';
     function extractErrorMessage(error) {
         if (error instanceof AggregateError && error.errors?.length > 0) {
             const inner = error.errors.map((e)=>e instanceof Error ? e.message : String(e)).join('; ');
@@ -1132,6 +1133,23 @@ var __webpack_exports__ = {};
             throw error;
         }
     }
+    class LegalDocumentPolicyConflictError extends Error {
+        constructor(message){
+            super(message);
+            this.name = 'LegalDocumentPolicyConflictError';
+        }
+    }
+    async function buildLegalDocumentPolicyId(input) {
+        const digest = await (0, types_namespaceObject.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 {
@@ -1160,6 +1178,176 @@ var __webpack_exports__ = {};
                     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 {
@@ -1584,7 +1772,8 @@ var __webpack_exports__ = {};
             registry: createRegistry({
                 db: orm,
                 ctx: {
-                    logger
+                    logger,
+                    tenantId: options.tenantId
                 }
             })
         };
@@ -1611,7 +1800,7 @@ var __webpack_exports__ = {};
         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 {
@@ -1637,11 +1826,17 @@ var __webpack_exports__ = {};
         }
         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;
                 }
             }
@@ -1658,6 +1853,9 @@ var __webpack_exports__ = {};
                 id: consent.id,
                 type: policyType,
                 policyId: consent.policyId ?? void 0,
+                policyVersion,
+                policyHash,
+                policyEffectiveDate,
                 isLatestPolicy,
                 preferences,
                 givenAt: consent.givenAt
@@ -1772,11 +1970,7 @@ var __webpack_exports__ = {};
         const app = new external_hono_namespaceObject.Hono();
         app.get('/check', (0, external_hono_openapi_namespaceObject.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.
-
-**Query parameters:**
-- \`externalId\` – External user ID to check
-- \`type\` – Consent type(s) to check (comma-separated)`,
+            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'
             ],
@@ -2356,6 +2550,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 http_exception_namespaceObject.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 http_exception_namespaceObject.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 http_exception_namespaceObject.HTTPException(409, {
+                message: error.message,
+                cause: {
+                    code: 'LEGAL_DOCUMENT_RELEASE_CONFLICT'
+                }
+            });
+            if (error instanceof http_exception_namespaceObject.HTTPException) throw error;
+            throw new http_exception_namespaceObject.HTTPException(500, {
+                message: 'Internal server error',
+                cause: {
+                    code: 'INTERNAL_SERVER_ERROR'
+                }
+            });
+        }
+    };
+    const createLegalDocumentRoutes = ()=>{
+        const app = new external_hono_namespaceObject.Hono();
+        app.put('/:type/current', (0, external_hono_openapi_namespaceObject.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: (0, external_hono_openapi_namespaceObject.resolver)(schema_.legalDocumentCurrentOutputSchema)
+                        }
+                    }
+                },
+                401: {
+                    description: 'Missing or invalid API key'
+                },
+                409: {
+                    description: 'Release metadata conflicts with an existing release'
+                }
+            }
+        }), (0, external_hono_openapi_namespaceObject.validator)('param', schema_.legalDocumentCurrentParamsSchema), (0, external_hono_openapi_namespaceObject.validator)('json', schema_.legalDocumentCurrentInputSchema), syncCurrentLegalDocumentHandler);
+        return app;
+    };
     function getHeaders(headers) {
         if (!headers) return {
             countryCode: null,
@@ -2442,6 +2724,12 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
         const subjectId = c.req.param('id');
         const type = c.req.query('type');
         const typeFilter = type?.split(',').map((t)=>t.trim()) || [];
+        if (!subjectId) throw new http_exception_namespaceObject.HTTPException(400, {
+            message: 'Subject ID is required',
+            cause: {
+                code: 'SUBJECT_ID_REQUIRED'
+            }
+        });
         logger.debug('Request parameters', {
             subjectId,
             typeFilter
@@ -2633,6 +2921,12 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
         const subjectId = c.req.param('id');
         const body = await c.req.json();
         const { externalId, identityProvider = 'external' } = body;
+        if (!subjectId) throw new http_exception_namespaceObject.HTTPException(400, {
+            message: 'Subject ID is required',
+            cause: {
+                code: 'SUBJECT_ID_REQUIRED'
+            }
+        });
         logger.debug('Request parameters', {
             subjectId,
             externalId,
@@ -2709,6 +3003,79 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
             });
         }
     };
+    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 snapshot_resolveSnapshotIssuer(options) {
+        return options?.issuer?.trim() || DEFAULT_ISSUER;
+    }
+    function snapshot_resolveSnapshotAudience(params) {
+        const configuredAudience = params.options?.audience?.trim();
+        if (configuredAudience) return configuredAudience;
+        return params.tenantId ? `${DEFAULT_AUDIENCE}:${params.tenantId}` : DEFAULT_AUDIENCE;
+    }
+    function snapshot_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 (0, external_jose_namespaceObject.jwtVerify)(token, snapshot_getSigningKey(options.signingKey), {
+                issuer: snapshot_resolveSnapshotIssuer(options),
+                audience: snapshot_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 external_jose_namespaceObject.errors.JWTExpired) return {
+                valid: false,
+                reason: 'expired'
+            };
+            return {
+                valid: false,
+                reason: 'invalid'
+            };
+        }
+    }
     function buildRuntimeDecisionDedupeKey(input) {
         return [
             input.tenantId ?? 'default',
@@ -2788,6 +3155,9 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
         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';
     }
@@ -2822,6 +3192,45 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
                 }
         }
     }
+    function buildLegalDocumentSnapshotHttpException(reason) {
+        switch(reason){
+            case 'missing':
+                return new http_exception_namespaceObject.HTTPException(409, {
+                    message: 'Legal document snapshot token is required',
+                    cause: {
+                        code: 'LEGAL_DOCUMENT_SNAPSHOT_REQUIRED'
+                    }
+                });
+            case 'expired':
+                return new http_exception_namespaceObject.HTTPException(409, {
+                    message: 'Legal document snapshot token has expired',
+                    cause: {
+                        code: 'LEGAL_DOCUMENT_SNAPSHOT_EXPIRED'
+                    }
+                });
+            case 'malformed':
+            case 'invalid':
+                return new http_exception_namespaceObject.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 http_exception_namespaceObject.HTTPException(409, {
+            message,
+            cause: {
+                code: 'LEGAL_DOCUMENT_PROOF_REQUIRED'
+            }
+        });
+    }
     const postSubjectHandler = async (c)=>{
         const ctx = c.get('c15tContext');
         const logger = ctx.logger;
@@ -2847,16 +3256,30 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
             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 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 resolvePolicyDecision({
                 policies: ctx.policyPacks,
                 countryCode: location.countryCode,
                 regionCode: location.regionCode,
@@ -2913,7 +3336,39 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
             let purposeIds = [];
             let appliedPreferences;
             const inputPolicyId = 'policyId' in input ? input.policyId : void 0;
-            if (inputPolicyId) {
+            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 http_exception_namespaceObject.HTTPException(404, {
+                    message: 'Policy not found',
+                    cause: {
+                        code: 'POLICY_NOT_FOUND',
+                        policyId,
+                        type
+                    }
+                });
+                if (!policy.isActive) throw new http_exception_namespaceObject.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 http_exception_namespaceObject.HTTPException(404, {
@@ -3138,6 +3593,12 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
                 errorType: error instanceof Error ? error.constructor.name : typeof error
             });
             if (error instanceof http_exception_namespaceObject.HTTPException) throw error;
+            if (error instanceof LegalDocumentPolicyConflictError) throw new http_exception_namespaceObject.HTTPException(409, {
+                message: error.message,
+                cause: {
+                    code: 'LEGAL_DOCUMENT_RELEASE_CONFLICT'
+                }
+            });
             throw new http_exception_namespaceObject.HTTPException(500, {
                 message: 'Internal server error',
                 cause: {
@@ -3150,11 +3611,7 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
         const app = new external_hono_namespaceObject.Hono();
         app.get('/:id', (0, external_hono_openapi_namespaceObject.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.
-
-**Query:** \`type\` – Filter by consent type(s), comma-separated (e.g. \`privacy_policy,cookie_banner\`).
-
-**Response:** \`subject\`, \`consents\` (matching filter), \`isValid\` (valid consent for requested type(s)).`,
+            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'
@@ -3175,12 +3632,7 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
         }), (0, external_hono_openapi_namespaceObject.validator)('param', schema_.getSubjectInputSchema), getSubjectHandler);
         app.post('/', (0, external_hono_openapi_namespaceObject.describeRoute)({
             summary: 'Record consent for a subject',
-            description: `Creates a new consent record (append-only). Creates the subject if it does not exist.
-
-**Request body by \`type\`:**
-- \`cookie_banner\` – Requires \`preferences\` object
-- \`privacy_policy\`, \`dpa\`, \`terms_and_conditions\` – Optional \`policyId\`
-- \`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` – 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'
@@ -3265,7 +3717,7 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
         if (!value) return;
         return (0, schema_.compactDefined)({
             allowedActions: (0, schema_.dedupeTrimmedStrings)(value.allowedActions),
-            primaryAction: value.primaryAction,
+            primaryActions: value.primaryActions,
             layout: value.layout,
             direction: value.direction,
             uiProfile: value.uiProfile,
@@ -3413,13 +3865,12 @@ Use for health checks, load balancer probes, and debugging. Performs a lightweig
             }));
             const publicSpecUrl = `${basePath}${openApiConfig.specPath}`.replace(/\/+/g, '/');
             app.get(openApiConfig.docsPath, (0, hono_api_reference_namespaceObject.apiReference)({
-                spec: {
-                    url: publicSpecUrl
-                },
+                url: publicSpecUrl,
                 pageTitle: `${options.appName || 'c15t API'} Documentation`
             }));
         }
         app.route('/init', createInitRoute(options));
+        app.route('/legal-documents', createLegalDocumentRoutes());
         app.route('/subjects', createSubjectRoutes());
         app.route('/consents', createConsentRoutes());
         app.route('/status', createStatusRoute());