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

package/dist/core.js

@@ -5,12 +5,14 @@ import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { HTTPException } from "hono/http-exception";
 import { describeRoute, openAPIRouteHandler, resolver, validator } from "hono-openapi";
+import { EEA_COUNTRY_CODES, EU_COUNTRY_CODES, POLICY_MATCH_DATASET_VERSION, UK_COUNTRY_CODES, inspectPolicies, policyMatchers, resolvePolicyDecision, validatePolicyI18nConfig } from "@c15t/schema/types";
+import { deepMergeTranslations, selectLanguage } from "@c15t/translations";
+import { baseTranslations } from "@c15t/translations/all";
 import base_x from "base-x";
 import { fumadb } from "fumadb";
 import { column, idColumn, schema, table as schema_table } from "fumadb/schema";
-import { checkConsentOutputSchema, checkConsentQuerySchema, getSubjectInputSchema, getSubjectOutputSchema, initOutputSchema, listSubjectsOutputSchema, listSubjectsQuerySchema, patchSubjectOutputSchema, postSubjectInputSchema, postSubjectOutputSchema, statusOutputSchema, subjectIdSchema } from "@c15t/schema";
-import { deepMergeTranslations, selectLanguage } from "@c15t/translations";
-import { baseTranslations } from "@c15t/translations/all";
+import { checkConsentOutputSchema, checkConsentQuerySchema, compactDefined, dedupeTrimmedStrings, getSubjectInputSchema, getSubjectOutputSchema, initOutputSchema, listSubjectsOutputSchema, listSubjectsQuerySchema, patchSubjectOutputSchema, policyPackPresets, postSubjectInputSchema, postSubjectOutputSchema, statusOutputSchema, subjectIdSchema } from "@c15t/schema";
+import { SignJWT, errors, jwtVerify } from "jose";
 import { object, optional, string } from "valibot";
 function extractBearerToken(authHeader) {
     if (!authHeader) return null;
@@ -137,7 +139,7 @@ function createCORSOptions(trustedOrigins) {
         ]
     };
 }
-const version_version = '2.0.0-rc.4';
+const version_version = '2.0.0-rc.5';
 const config_createOpenAPIConfig = (options)=>({
         enabled: options.openapi?.enabled !== false,
         specPath: '/spec.json',
@@ -253,6 +255,133 @@ function getIpAddress(req, options) {
     }
     return null;
 }
+const DEFAULT_PROFILE = 'default';
+const warnedKeys = new Set();
+function isSupportedBaseLanguage(lang) {
+    return lang in baseTranslations;
+}
+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 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 validateMessages(options) {
+    return validatePolicyI18nConfig({
+        customTranslations: options.customTranslations,
+        i18n: options.i18n,
+        policies: options.policies
+    });
+}
+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: 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
+    });
+    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
+    };
+}
 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('; ');
@@ -575,6 +704,7 @@ const prefixes = {
     consentPolicy: 'pol',
     consentPurpose: 'pur',
     domain: 'dom',
+    runtimePolicyDecision: 'rpd',
     subject: 'sub'
 };
 const b58 = base_x('123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz');
@@ -846,6 +976,54 @@ function domainRegistry({ db, ctx }) {
         }
     };
 }
+function runtimePolicyDecisionRegistry({ db, ctx }) {
+    const { logger } = ctx;
+    return {
+        findOrCreateRuntimePolicyDecision: async (input)=>{
+            const existing = await db.findFirst('runtimePolicyDecision', {
+                where: (b)=>b('dedupeKey', '=', input.dedupeKey)
+            });
+            if (existing) return existing;
+            logger.debug('Creating runtime policy decision', {
+                policyId: input.policyId,
+                fingerprint: input.fingerprint,
+                matchedBy: input.matchedBy
+            });
+            return db.create('runtimePolicyDecision', {
+                id: `rpd_${crypto.randomUUID().replaceAll('-', '')}`,
+                tenantId: input.tenantId,
+                policyId: input.policyId,
+                fingerprint: input.fingerprint,
+                matchedBy: input.matchedBy,
+                countryCode: input.countryCode,
+                regionCode: input.regionCode,
+                jurisdiction: input.jurisdiction,
+                language: input.language,
+                model: input.model,
+                policyI18n: input.policyI18n ? {
+                    json: input.policyI18n
+                } : void 0,
+                uiMode: input.uiMode,
+                bannerUi: input.bannerUi ? {
+                    json: input.bannerUi
+                } : void 0,
+                dialogUi: input.dialogUi ? {
+                    json: input.dialogUi
+                } : void 0,
+                categories: input.categories ? {
+                    json: input.categories
+                } : void 0,
+                preselectedCategories: input.preselectedCategories ? {
+                    json: input.preselectedCategories
+                } : void 0,
+                proofConfig: input.proofConfig ? {
+                    json: input.proofConfig
+                } : void 0,
+                dedupeKey: input.dedupeKey
+            });
+        }
+    };
+}
 function subjectRegistry({ db, ctx }) {
     const { logger } = ctx;
     return {
@@ -923,7 +1101,8 @@ const createRegistry = (ctx)=>({
         ...subjectRegistry(ctx),
         ...consentPurposeRegistry(ctx),
         ...policyRegistry(ctx),
-        ...domainRegistry(ctx)
+        ...domainRegistry(ctx),
+        ...runtimePolicyDecisionRegistry(ctx)
     });
 const auditLogTable = schema_table('auditLog', {
     id: idColumn('id', 'varchar(255)'),
@@ -1090,6 +1269,8 @@ const consent_consentTable = schema_table('consent', {
     tcString: column('tcString', 'string').nullable(),
     uiSource: column('uiSource', 'string').nullable(),
     consentAction: column('consentAction', 'string').nullable(),
+    runtimePolicyDecisionId: column('runtimePolicyDecisionId', 'string').nullable(),
+    runtimePolicySource: column('runtimePolicySource', 'string').nullable(),
     tenantId: column('tenantId', 'string').nullable()
 });
 const consent_policy_consentPolicyTable = schema_table('consentPolicy', {
@@ -1115,6 +1296,27 @@ const domain_domainTable = schema_table('domain', {
     updatedAt: column('updatedAt', 'timestamp').defaultTo$('now'),
     tenantId: column('tenantId', 'string').nullable()
 });
+const runtimePolicyDecisionTable = schema_table('runtimePolicyDecision', {
+    id: idColumn('id', 'varchar(255)'),
+    tenantId: column('tenantId', 'string').nullable(),
+    policyId: column('policyId', 'string'),
+    fingerprint: column('fingerprint', 'string'),
+    matchedBy: column('matchedBy', 'string'),
+    countryCode: column('countryCode', 'string').nullable(),
+    regionCode: column('regionCode', 'string').nullable(),
+    jurisdiction: column('jurisdiction', 'string'),
+    language: column('language', 'string').nullable(),
+    model: column('model', 'string'),
+    policyI18n: column('policyI18n', 'json').nullable(),
+    uiMode: column('uiMode', 'string').nullable(),
+    bannerUi: column('bannerUi', 'json').nullable(),
+    dialogUi: column('dialogUi', 'json').nullable(),
+    categories: column('categories', 'json').nullable(),
+    preselectedCategories: column('preselectedCategories', 'json').nullable(),
+    proofConfig: column('proofConfig', 'json').nullable(),
+    dedupeKey: column('dedupeKey', 'string').unique(),
+    createdAt: column('createdAt', 'timestamp').defaultTo$('now')
+});
 const subject_subjectTable = schema_table('subject', {
     id: idColumn('id', 'varchar(255)'),
     externalId: column('externalId', 'string').nullable(),
@@ -1129,6 +1331,7 @@ const v2 = schema({
         subject: subject_subjectTable,
         domain: domain_domainTable,
         consentPolicy: consent_policy_consentPolicyTable,
+        runtimePolicyDecision: runtimePolicyDecisionTable,
         consentPurpose: consent_purpose_consentPurposeTable,
         consent: consent_consentTable,
         auditLog: audit_log_auditLogTable
@@ -1144,6 +1347,9 @@ const v2 = schema({
         consentPolicy: ({ many })=>({
                 consents: many('consent')
             }),
+        runtimePolicyDecision: ({ many })=>({
+                consents: many('consent')
+            }),
         consentPurpose: ()=>({}),
         consent: ({ one })=>({
                 subject: one('subject', [
@@ -1157,6 +1363,10 @@ const v2 = schema({
                 policy: one('consentPolicy', [
                     'policyId',
                     'id'
+                ]).foreignKey(),
+                runtimePolicyDecision: one('runtimePolicyDecision', [
+                    'runtimePolicyDecisionId',
+                    'id'
                 ]).foreignKey()
             }),
         auditLog: ({ one })=>({
@@ -1243,6 +1453,18 @@ function withTenantScope(db, tenantId) {
         }
     });
 }
+function policy_inspectPolicies(policies, options) {
+    return inspectPolicies(policies, options);
+}
+async function policy_resolvePolicyDecision(params) {
+    return resolvePolicyDecision({
+        policies: params.policies,
+        countryCode: params.countryCode,
+        regionCode: params.regionCode,
+        jurisdiction: params.jurisdiction,
+        iabEnabled: params.iabEnabled
+    });
+}
 let globalLogger;
 function initLogger(options) {
     globalLogger = logger_createLogger({
@@ -1269,6 +1491,18 @@ const init = (options)=>{
     const rawOrm = client.orm('2.0.0');
     const orm = options.tenantId ? withTenantScope(rawOrm, options.tenantId) : rawOrm;
     const { ipAddress: _ipAddressConfig, ...baseOptions } = options;
+    const i18nValidation = validateMessages({
+        i18n: options.i18n,
+        customTranslations: options.customTranslations,
+        policies: options.policyPacks
+    });
+    for (const warning of i18nValidation.warnings)logger.warn(`i18n: ${warning}`);
+    if (i18nValidation.errors.length > 0) throw new Error(`Invalid i18n configuration:\n${i18nValidation.errors.map((error)=>`- ${error}`).join('\n')}`);
+    const policyValidation = policy_inspectPolicies(options.policyPacks ?? [], {
+        iabEnabled: options.iab?.enabled === true
+    });
+    for (const warning of policyValidation.warnings)logger.warn(`policyPacks: ${warning}`);
+    if (policyValidation.errors.length > 0) throw new Error(policyValidation.errors[0]);
     const context = {
         ...baseOptions,
         appName,
@@ -1628,6 +1862,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;
@@ -1783,26 +2134,118 @@ function getJurisdiction(location, options) {
     if (options.disableGeoLocation) return 'GDPR';
     return checkJurisdiction(location.countryCode, location.regionCode);
 }
-function isSupportedBaseLanguage(lang) {
-    return lang in baseTranslations;
+function stripIabTranslations(translations) {
+    const { iab: _iab, ...rest } = translations;
+    return rest;
 }
-function translations_getTranslationsData(acceptLanguage, customTranslations) {
-    const supportedDefaultLanguages = Object.keys(baseTranslations);
-    const supportedCustomLanguages = Object.keys(customTranslations || {});
-    const supportedLanguages = [
-        ...supportedDefaultLanguages,
-        ...supportedCustomLanguages
-    ];
-    const preferredLanguage = selectLanguage(supportedLanguages, {
-        header: acceptLanguage,
-        fallback: 'en'
+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
     });
-    const base = isSupportedBaseLanguage(preferredLanguage) ? baseTranslations[preferredLanguage] : baseTranslations.en;
-    const custom = supportedCustomLanguages.includes(preferredLanguage) ? customTranslations?.[preferredLanguage] : {};
-    const translations = custom ? deepMergeTranslations(base, custom) : base;
     return {
-        translations: translations,
-        language: preferredLanguage
+        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)=>{
@@ -1815,7 +2258,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: [
@@ -1832,42 +2275,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;
 };
@@ -2223,6 +2633,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;
@@ -2234,9 +2757,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,
@@ -2245,6 +2765,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,
@@ -2271,6 +2835,7 @@ const postSubjectHandler = async (c)=>{
         });
         let policyId;
         let purposeIds = [];
+        let appliedPreferences;
         const inputPolicyId = 'policyId' in input ? input.policyId : void 0;
         if (inputPolicyId) {
             policyId = inputPolicyId;
@@ -2303,20 +2868,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))
         });
@@ -2331,6 +2942,7 @@ const postSubjectHandler = async (c)=>{
                 domain: domainRecord.name,
                 type,
                 metadata,
+                appliedPreferences,
                 uiSource: input.uiSource,
                 givenAt: existingConsent.givenAt
             });
@@ -2342,6 +2954,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 utils_generateUniqueId(tx, 'consent', ctx),
                 subjectId: subject.id,
@@ -2350,17 +2998,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
@@ -2379,7 +3030,7 @@ const postSubjectHandler = async (c)=>{
         });
         const metrics = getMetrics();
         if (metrics) {
-            const jurisdiction = input.jurisdiction;
+            const jurisdiction = effectiveJurisdiction;
             metrics.recordConsentCreated({
                 type,
                 jurisdiction
@@ -2401,6 +3052,7 @@ const postSubjectHandler = async (c)=>{
             domain: domainRecord.name,
             type,
             metadata,
+            appliedPreferences,
             uiSource: input.uiSource,
             givenAt: result.consent.givenAt
         });
@@ -2524,6 +3176,86 @@ const createSubjectRoutes = ()=>{
     return app;
 };
 const defineConfig = (config)=>config;
+const DEFAULT_FALLBACK_POLICY_INPUT = {
+    id: 'world_no_banner',
+    isDefault: true,
+    model: 'none',
+    uiMode: 'none'
+};
+function mergeMatch(input) {
+    return policyMatchers.merge(input.countries?.length ? policyMatchers.countries(input.countries) : {}, input.regions?.length ? policyMatchers.regions(input.regions) : {}, input.isDefault ? policyMatchers["default"]() : {});
+}
+function compactUiSurface(value) {
+    if (!value) return;
+    return compactDefined({
+        allowedActions: dedupeTrimmedStrings(value.allowedActions),
+        primaryAction: value.primaryAction,
+        layout: value.layout,
+        direction: value.direction,
+        uiProfile: value.uiProfile,
+        scrollLock: value.scrollLock
+    });
+}
+function buildPolicyConfig(input) {
+    const categories = dedupeTrimmedStrings(input.categories);
+    const preselectedCategories = dedupeTrimmedStrings(input.preselectedCategories);
+    return {
+        id: input.id,
+        match: mergeMatch(input),
+        i18n: input.i18n,
+        consent: compactDefined({
+            model: input.model,
+            expiryDays: input.expiryDays,
+            scopeMode: input.scopeMode,
+            categories,
+            preselectedCategories,
+            gpc: input.gpc
+        }),
+        ui: compactDefined({
+            mode: input.uiMode,
+            banner: compactUiSurface(input.banner),
+            dialog: compactUiSurface(input.dialog)
+        }),
+        proof: compactDefined({
+            storeIp: input.proof?.storeIp,
+            storeUserAgent: input.proof?.storeUserAgent,
+            storeLanguage: input.proof?.storeLanguage
+        })
+    };
+}
+function buildPolicyPack(inputs) {
+    return inputs.map((input)=>buildPolicyConfig(input));
+}
+function buildPolicyPackWithDefault(inputs, defaultPolicy) {
+    const pack = buildPolicyPack(inputs);
+    const hasDefault = pack.some((policy)=>policy.match.isDefault);
+    if (hasDefault) return pack;
+    const fallbackInput = defaultPolicy ? {
+        ...defaultPolicy,
+        isDefault: true,
+        countries: void 0,
+        regions: void 0
+    } : DEFAULT_FALLBACK_POLICY_INPUT;
+    return [
+        ...pack,
+        buildPolicyConfig(fallbackInput)
+    ];
+}
+function composePacks(...packs) {
+    const seen = new Set();
+    const result = [];
+    for (const pack of packs)for (const policy of pack)if (!seen.has(policy.id)) {
+        seen.add(policy.id);
+        result.push(policy);
+    }
+    return result;
+}
+const policyBuilder = {
+    create: buildPolicyConfig,
+    createPack: buildPolicyPack,
+    createPackWithDefault: buildPolicyPackWithDefault,
+    composePacks
+};
 const c15tInstance = (options)=>{
     const context = init(options);
     const logger = logger_createLogger(options.logger);
@@ -2700,4 +3432,4 @@ const c15tInstance = (options)=>{
         getDocsUI
     };
 };
-export { c15tInstance, defineConfig, version_version as version };
+export { EEA_COUNTRY_CODES, EU_COUNTRY_CODES, POLICY_MATCH_DATASET_VERSION, UK_COUNTRY_CODES, c15tInstance, defineConfig, policy_inspectPolicies as inspectPolicies, policyBuilder, policyMatchers, policyPackPresets, version_version as version };