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

package/dist/router.js

@@ -3,6 +3,8 @@ import { Hono } from "hono";
 import { describeRoute, resolver, validator } from "hono-openapi";
 import { HTTPException } from "hono/http-exception";
 import { SpanKind as api_SpanKind, SpanStatusCode as api_SpanStatusCode, context, metrics as api_metrics, trace as api_trace } from "@opentelemetry/api";
+import { SignJWT, errors, jwtVerify } from "jose";
+import { resolvePolicyDecision } from "@c15t/schema/types";
 import { deepMergeTranslations, selectLanguage } from "@c15t/translations";
 import { baseTranslations } from "@c15t/translations/all";
 import { object, optional, string } from "valibot";
@@ -15,7 +17,7 @@ function extractErrorMessage(error) {
     if (error instanceof Error) return error.message || error.name;
     return String(error);
 }
-const version_version = '2.0.0-rc.4';
+const version_version = '2.0.0-rc.5';
 let cachedConfig = null;
 let cachedDefaultAttributes = {};
 function create_telemetry_options_isTelemetryEnabled(options) {
@@ -611,6 +613,123 @@ function createGVLResolver(options) {
         }
     };
 }
+const POLICY_SNAPSHOT_JWT_HEADER = {
+    alg: 'HS256',
+    typ: 'JWT'
+};
+const DEFAULT_POLICY_SNAPSHOT_ISSUER = 'c15t';
+const DEFAULT_POLICY_SNAPSHOT_AUDIENCE = 'c15t-policy-snapshot';
+function resolveSnapshotIssuer(options) {
+    return options?.issuer?.trim() || DEFAULT_POLICY_SNAPSHOT_ISSUER;
+}
+function resolveSnapshotAudience(params) {
+    const configuredAudience = params.options?.audience?.trim();
+    if (configuredAudience) return configuredAudience;
+    return params.tenantId ? `${DEFAULT_POLICY_SNAPSHOT_AUDIENCE}:${params.tenantId}` : DEFAULT_POLICY_SNAPSHOT_AUDIENCE;
+}
+function getSigningKey(secret) {
+    return new TextEncoder().encode(secret);
+}
+function isPolicySnapshotPayload(payload) {
+    return 'string' == typeof payload.policyId && 'string' == typeof payload.fingerprint && 'string' == typeof payload.matchedBy && 'string' == typeof payload.jurisdiction && 'string' == typeof payload.model && 'string' == typeof payload.iss && 'string' == typeof payload.aud && 'string' == typeof payload.sub && 'number' == typeof payload.iat && 'number' == typeof payload.exp;
+}
+async function createPolicySnapshotToken(params) {
+    const { options } = params;
+    if (!options?.signingKey) return;
+    const iat = Math.floor(Date.now() / 1000);
+    const ttlSeconds = options.ttlSeconds ?? 1800;
+    const exp = iat + ttlSeconds;
+    const iss = resolveSnapshotIssuer(options);
+    const aud = resolveSnapshotAudience({
+        options,
+        tenantId: params.tenantId
+    });
+    const payload = {
+        iss,
+        aud,
+        sub: params.policyId,
+        tenantId: params.tenantId,
+        policyId: params.policyId,
+        fingerprint: params.fingerprint,
+        matchedBy: params.matchedBy,
+        country: params.country,
+        region: params.region,
+        jurisdiction: params.jurisdiction,
+        language: params.language,
+        model: params.model,
+        policyI18n: params.policyI18n,
+        expiryDays: params.expiryDays,
+        scopeMode: params.scopeMode,
+        uiMode: params.uiMode,
+        bannerUi: params.bannerUi,
+        dialogUi: params.dialogUi,
+        categories: params.categories,
+        preselectedCategories: params.preselectedCategories,
+        gpc: params.gpc,
+        proofConfig: params.proofConfig,
+        iat,
+        exp
+    };
+    const token = await new SignJWT(payload).setProtectedHeader(POLICY_SNAPSHOT_JWT_HEADER).setIssuedAt(iat).setExpirationTime(exp).sign(getSigningKey(options.signingKey));
+    return {
+        token,
+        payload
+    };
+}
+async function verifyPolicySnapshotToken(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 (!isPolicySnapshotPayload(payload)) return {
+            valid: false,
+            reason: 'invalid'
+        };
+        if (payload.sub !== payload.policyId) 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 geo_normalizeHeader(value) {
     if (!value) return null;
     return Array.isArray(value) ? value[0] ?? null : value;
@@ -766,26 +885,247 @@ function getJurisdiction(location, options) {
     if (options.disableGeoLocation) return 'GDPR';
     return checkJurisdiction(location.countryCode, location.regionCode);
 }
+async function policy_resolvePolicyDecision(params) {
+    return resolvePolicyDecision({
+        policies: params.policies,
+        countryCode: params.countryCode,
+        regionCode: params.regionCode,
+        jurisdiction: params.jurisdiction,
+        iabEnabled: params.iabEnabled
+    });
+}
+const DEFAULT_PROFILE = 'default';
+const warnedKeys = new Set();
 function isSupportedBaseLanguage(lang) {
     return lang in baseTranslations;
 }
-function translations_getTranslationsData(acceptLanguage, customTranslations) {
-    const supportedDefaultLanguages = Object.keys(baseTranslations);
-    const supportedCustomLanguages = Object.keys(customTranslations || {});
-    const supportedLanguages = [
-        ...supportedDefaultLanguages,
-        ...supportedCustomLanguages
+function warnOnce(logger, key, message, metadata) {
+    if (!logger || warnedKeys.has(key)) return;
+    warnedKeys.add(key);
+    logger.warn(message, metadata);
+}
+function normalizeLanguage(value) {
+    if (!value) return;
+    const normalized = value.split(',')[0]?.split(';')[0]?.trim().toLowerCase();
+    if (!normalized) return;
+    return normalized.split('-')[0] ?? void 0;
+}
+function normalizeProfiles(params) {
+    const profiles = params.i18n?.messages;
+    const legacy = params.customTranslations;
+    if (profiles && Object.keys(profiles).length > 0) {
+        if (legacy && Object.keys(legacy).length > 0) warnOnce(params.logger, 'i18n.customTranslations.ignored', '`customTranslations` is deprecated and ignored when `i18n.messages` is configured.');
+        return profiles;
+    }
+    if (legacy && Object.keys(legacy).length > 0) {
+        warnOnce(params.logger, 'i18n.customTranslations.deprecated', '`customTranslations` is deprecated. Use `i18n.messages` instead.');
+        return {
+            [DEFAULT_PROFILE]: {
+                translations: legacy
+            }
+        };
+    }
+    return {};
+}
+function buildCandidates(input) {
+    const raw = [
+        {
+            language: input.language,
+            reason: 'profile_language'
+        },
+        {
+            language: input.fallbackLanguage,
+            reason: 'profile_fallback'
+        }
     ];
-    const preferredLanguage = selectLanguage(supportedLanguages, {
+    const dedupe = new Set();
+    return raw.filter((candidate)=>{
+        const key = candidate.language;
+        if (dedupe.has(key)) return false;
+        dedupe.add(key);
+        return true;
+    });
+}
+function getProfileLanguages(profiles, profile) {
+    return Object.keys(profiles[profile]?.translations ?? {}).sort();
+}
+function getSelectableLanguages(input) {
+    return getProfileLanguages(input.profiles, input.profile);
+}
+function resolveFallbackLanguage(input) {
+    const configuredFallbackLanguage = normalizeLanguage(input.profile?.fallbackLanguage) ?? 'en';
+    const profileLanguages = Object.keys(input.profile?.translations ?? {}).sort();
+    if (profileLanguages.includes(configuredFallbackLanguage)) return configuredFallbackLanguage;
+    if (profileLanguages.includes('en')) return 'en';
+    return profileLanguages[0] ?? configuredFallbackLanguage;
+}
+function resolveActiveProfile(input) {
+    const requestedProfile = input.policyProfile ?? input.defaultProfile;
+    if (input.profiles[requestedProfile]) return requestedProfile;
+    if (input.policyProfile) warnOnce(input.logger, `i18n.profile.missing:${requestedProfile}`, `Policy i18n profile '${requestedProfile}' does not exist. Falling back to default profile '${input.defaultProfile}'.`);
+    return input.defaultProfile;
+}
+function translations_getTranslationsData(acceptLanguage, customTranslations, options) {
+    const profiles = normalizeProfiles({
+        customTranslations,
+        i18n: options?.i18n,
+        logger: options?.logger
+    });
+    const defaultProfile = options?.i18n?.defaultProfile ?? DEFAULT_PROFILE;
+    const profile = resolveActiveProfile({
+        profiles,
+        defaultProfile,
+        policyProfile: options?.policyI18n?.messageProfile,
+        logger: options?.logger
+    });
+    const configuredLanguages = Object.keys(profiles).length > 0 ? getSelectableLanguages({
+        profiles,
+        profile
+    }) : Object.keys(baseTranslations);
+    const fallbackLanguage = Object.keys(profiles).length > 0 ? resolveFallbackLanguage({
+        profile: profiles[profile]
+    }) : 'en';
+    const policyLanguage = normalizeLanguage(options?.policyI18n?.language);
+    const requestedLanguage = policyLanguage ?? selectLanguage(configuredLanguages, {
         header: acceptLanguage,
-        fallback: 'en'
+        fallback: fallbackLanguage
+    });
+    const candidates = buildCandidates({
+        language: requestedLanguage,
+        fallbackLanguage
+    });
+    const selectedCandidate = candidates.find((candidate)=>!!profiles[profile]?.translations[candidate.language]);
+    if (selectedCandidate && 'profile_language' !== selectedCandidate.reason) warnOnce(options?.logger, `i18n.fallback:${profile}:${requestedLanguage}:${selectedCandidate.language}`, `Policy translation fallback used (${selectedCandidate.reason}).`, {
+        requestedProfile: profile,
+        requestedLanguage,
+        resolvedProfile: profile,
+        resolvedLanguage: selectedCandidate.language
     });
-    const base = isSupportedBaseLanguage(preferredLanguage) ? baseTranslations[preferredLanguage] : baseTranslations.en;
-    const custom = supportedCustomLanguages.includes(preferredLanguage) ? customTranslations?.[preferredLanguage] : {};
+    let language = selectedCandidate?.language ?? requestedLanguage;
+    if (!selectedCandidate && !isSupportedBaseLanguage(language)) {
+        warnOnce(options?.logger, `i18n.base-fallback:${language}`, `No translation found for '${language}'. Falling back to base English translations.`);
+        language = 'en';
+    }
+    const base = isSupportedBaseLanguage(language) ? baseTranslations[language] : baseTranslations.en;
+    const custom = selectedCandidate ? profiles[profile]?.translations[selectedCandidate.language] : void 0;
     const translations = custom ? deepMergeTranslations(base, custom) : base;
     return {
         translations: translations,
-        language: preferredLanguage
+        language
+    };
+}
+function stripIabTranslations(translations) {
+    const { iab: _iab, ...rest } = translations;
+    return rest;
+}
+function resolveNoPolicyFallback() {
+    return {
+        id: 'no_banner',
+        model: 'none',
+        ui: {
+            mode: 'none'
+        }
+    };
+}
+async function resolveInitPayload(request, options, logger) {
+    const acceptLanguage = request.headers.get('accept-language') || 'en';
+    const location = await getLocation(request, options);
+    const jurisdiction = getJurisdiction(location, options);
+    const hasExplicitPolicyPack = void 0 !== options.policyPacks;
+    const isExplicitEmptyPolicyPack = hasExplicitPolicyPack && (options.policyPacks?.length ?? 0) === 0;
+    const policyDecision = isExplicitEmptyPolicyPack ? void 0 : await policy_resolvePolicyDecision({
+        policies: options.policyPacks,
+        countryCode: location.countryCode,
+        regionCode: location.regionCode,
+        jurisdiction,
+        iabEnabled: options.iab?.enabled === true
+    });
+    if (hasExplicitPolicyPack && !isExplicitEmptyPolicyPack && !policyDecision) logger?.warn('Policy packs configured but no policy matched', {
+        country: location.countryCode,
+        region: location.regionCode
+    });
+    const resolvedPolicy = hasExplicitPolicyPack ? policyDecision?.policy ?? resolveNoPolicyFallback() : void 0;
+    const iabOptions = options.iab;
+    const shouldIncludeIabPayload = iabOptions?.enabled === true && (!hasExplicitPolicyPack || resolvedPolicy?.model === 'iab');
+    const translationsResult = translations_getTranslationsData(acceptLanguage, options.customTranslations, {
+        i18n: options.i18n,
+        policyI18n: resolvedPolicy?.i18n,
+        logger
+    });
+    const responseTranslations = shouldIncludeIabPayload ? translationsResult : {
+        ...translationsResult,
+        translations: stripIabTranslations(translationsResult.translations)
+    };
+    let gvl = null;
+    if (shouldIncludeIabPayload && iabOptions) {
+        const language = translationsResult.language.split('-')[0] || 'en';
+        const gvlResolver = createGVLResolver({
+            appName: options.appName || 'c15t',
+            bundled: iabOptions.bundled,
+            cacheAdapter: options.cache?.adapter,
+            vendorIds: iabOptions.vendorIds,
+            endpoint: iabOptions.endpoint
+        });
+        gvl = await gvlResolver.get(language);
+    }
+    const customVendors = shouldIncludeIabPayload ? iabOptions?.customVendors : void 0;
+    const snapshot = policyDecision ? await createPolicySnapshotToken({
+        options: options.policySnapshot,
+        tenantId: options.tenantId,
+        policyId: policyDecision.policy.id,
+        fingerprint: policyDecision.fingerprint,
+        matchedBy: policyDecision.matchedBy,
+        country: location?.countryCode ?? null,
+        region: location?.regionCode ?? null,
+        jurisdiction,
+        language: translationsResult.language,
+        model: policyDecision.policy.model,
+        policyI18n: policyDecision.policy.i18n,
+        expiryDays: policyDecision.policy.consent?.expiryDays,
+        scopeMode: policyDecision.policy.consent?.scopeMode,
+        uiMode: policyDecision.policy.ui?.mode,
+        bannerUi: policyDecision.policy.ui?.banner,
+        dialogUi: policyDecision.policy.ui?.dialog,
+        categories: policyDecision.policy.consent?.categories,
+        preselectedCategories: policyDecision.policy.consent?.preselectedCategories,
+        gpc: policyDecision.policy.consent?.gpc,
+        proofConfig: policyDecision.policy.proof
+    }) : void 0;
+    const gpc = '1' === request.headers.get('sec-gpc');
+    getMetrics()?.recordInit({
+        jurisdiction,
+        country: location?.countryCode ?? void 0,
+        region: location?.regionCode ?? void 0,
+        gpc
+    });
+    return {
+        jurisdiction,
+        location,
+        translations: responseTranslations,
+        branding: options.branding || 'c15t',
+        ...shouldIncludeIabPayload && {
+            gvl,
+            customVendors
+        },
+        ...resolvedPolicy && {
+            policy: resolvedPolicy
+        },
+        ...policyDecision && {
+            policyDecision: {
+                policyId: policyDecision.policy.id,
+                fingerprint: policyDecision.fingerprint,
+                matchedBy: policyDecision.matchedBy,
+                country: location.countryCode,
+                region: location.regionCode,
+                jurisdiction
+            }
+        },
+        ...snapshot?.token && {
+            policySnapshotToken: snapshot.token
+        },
+        ...shouldIncludeIabPayload && iabOptions?.cmpId != null && {
+            cmpId: iabOptions.cmpId
+        }
     };
 }
 const createInitRoute = (options)=>{
@@ -798,7 +1138,7 @@ const createInitRoute = (options)=>{
 - **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 enabled
+- **GVL** – Global Vendor List when IAB is active for the request
 
 Use for geo-targeted consent banners and regional compliance.`,
         tags: [
@@ -815,42 +1155,9 @@ Use for geo-targeted consent banners and regional compliance.`,
             }
         }
     }), async (c)=>{
-        const request = c.req.raw;
-        const acceptLanguage = request.headers.get('accept-language') || 'en';
-        const location = await getLocation(request, options);
-        const jurisdiction = getJurisdiction(location, options);
-        const translationsResult = translations_getTranslationsData(acceptLanguage, options.customTranslations);
-        let gvl = null;
-        if (options.iab?.enabled) {
-            const language = translationsResult.language.split('-')[0] || 'en';
-            const gvlResolver = createGVLResolver({
-                appName: options.appName || 'c15t',
-                bundled: options.iab.bundled,
-                cacheAdapter: options.cache?.adapter,
-                vendorIds: options.iab.vendorIds,
-                endpoint: options.iab.endpoint
-            });
-            gvl = await gvlResolver.get(language);
-        }
-        const customVendors = options.iab?.customVendors;
-        const gpc = '1' === request.headers.get('sec-gpc');
-        getMetrics()?.recordInit({
-            jurisdiction,
-            country: location?.countryCode ?? void 0,
-            region: location?.regionCode ?? void 0,
-            gpc
-        });
-        return c.json({
-            jurisdiction,
-            location,
-            translations: translationsResult,
-            branding: options.branding || 'c15t',
-            gvl,
-            customVendors,
-            ...options.iab?.cmpId != null && {
-                cmpId: options.iab.cmpId
-            }
-        });
+        const ctx = c.get('c15tContext');
+        const payload = await resolveInitPayload(c.req.raw, options, ctx?.logger);
+        return c.json(payload);
     });
     return app;
 };
@@ -1206,6 +1513,119 @@ const patchSubjectHandler = async (c)=>{
         });
     }
 };
+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 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}`);
+            }
+    }
+}
 const postSubjectHandler = async (c)=>{
     const ctx = c.get('c15tContext');
     const logger = ctx.logger;
@@ -1217,9 +1637,6 @@ const postSubjectHandler = async (c)=>{
     const givenAt = new Date(givenAtEpoch);
     const rawConsentAction = 'consentAction' in input ? input.consentAction : void 0;
     let derivedConsentAction;
-    if ('all' === rawConsentAction) derivedConsentAction = 'accept_all';
-    else if ('necessary' === rawConsentAction) derivedConsentAction = 'opt-out' === input.jurisdictionModel ? 'opt_out' : 'reject_all';
-    else if ('custom' === rawConsentAction) derivedConsentAction = 'custom';
     logger.debug('Request parameters', {
         type,
         subjectId,
@@ -1228,6 +1645,50 @@ const postSubjectHandler = async (c)=>{
         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 snapshotVerification = 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({
+            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,
@@ -1254,6 +1715,7 @@ const postSubjectHandler = async (c)=>{
         });
         let policyId;
         let purposeIds = [];
+        let appliedPreferences;
         const inputPolicyId = 'policyId' in input ? input.policyId : void 0;
         if (inputPolicyId) {
             policyId = inputPolicyId;
@@ -1286,20 +1748,66 @@ const postSubjectHandler = async (c)=>{
             policyId = policy.id;
         }
         if (preferences) {
-            const consentedPurposes = Object.entries(preferences).filter(([_, isConsented])=>isConsented).map(([purposeCode])=>purposeCode);
+            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
+                consentedPurposes: filteredConsentedPurposeCodes
             });
-            const purposesRaw = await Promise.all(consentedPurposes.map((purposeCode)=>registry.findOrCreateConsentPurposeByCode(purposeCode)));
+            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
+                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))
         });
@@ -1314,6 +1822,7 @@ const postSubjectHandler = async (c)=>{
                 domain: domainRecord.name,
                 type,
                 metadata,
+                appliedPreferences,
                 uiSource: input.uiSource,
                 givenAt: existingConsent.givenAt
             });
@@ -1325,6 +1834,42 @@ const postSubjectHandler = async (c)=>{
                 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 generateUniqueId(tx, 'consent', ctx),
                 subjectId: subject.id,
@@ -1333,17 +1878,20 @@ const postSubjectHandler = async (c)=>{
                 purposeIds: {
                     json: purposeIds
                 },
-                metadata: metadata ? {
-                    json: metadata
+                metadata: Object.keys(metadataWithPolicy).length > 0 ? {
+                    json: metadataWithPolicy
                 } : void 0,
-                ipAddress: ctx.ipAddress,
-                userAgent: ctx.userAgent,
-                jurisdiction: input.jurisdiction,
-                jurisdictionModel: input.jurisdictionModel,
+                ipAddress: shouldStoreIp ? ctx.ipAddress : null,
+                userAgent: shouldStoreUserAgent ? ctx.userAgent : null,
+                jurisdiction: effectiveJurisdiction,
+                jurisdictionModel: effectiveModel,
                 tcString: input.tcString,
                 uiSource: input.uiSource,
                 consentAction: derivedConsentAction,
-                givenAt
+                givenAt,
+                validUntil,
+                runtimePolicyDecisionId: runtimePolicyDecision?.id,
+                runtimePolicySource: decisionPayload?.source
             });
             logger.debug('Created consent', {
                 consentRecord: consentRecord.id
@@ -1362,7 +1910,7 @@ const postSubjectHandler = async (c)=>{
         });
         const metrics = getMetrics();
         if (metrics) {
-            const jurisdiction = input.jurisdiction;
+            const jurisdiction = effectiveJurisdiction;
             metrics.recordConsentCreated({
                 type,
                 jurisdiction
@@ -1384,6 +1932,7 @@ const postSubjectHandler = async (c)=>{
             domain: domainRecord.name,
             type,
             metadata,
+            appliedPreferences,
             uiSource: input.uiSource,
             givenAt: result.consent.givenAt
         });