Backend — Advanced Configuration

import { createConsenti } from '@consenti/api'

const consenti = createConsenti({
  // Optional but recommended
  storage: {
    driver: 'json',            // not recommended for production
    path: './consenti-data',   // always required, even for MySQL/Mongo/Postgres — profiles are stored here
    // uri: process.env.CONSENTI_DB_URI,   // postgresql | mysql | mongodb connection string
    // poolMax: 5,                         // postgresql | mysql | mongodb — max connections per process (default 5)
  },
  auth: {
    mode: 'local',
    adminEmail: process.env.CONSENTI_ADMIN_EMAIL ?? '[email protected]',
    adminPassword: process.env.CONSENTI_ADMIN_PASSWORD ?? 'Consenti@123',
    masterSecret: process.env.CONSENTI_ADMIN_MASTER_SECRET ?? 'random-jwt-secret',
  },

  // Optional
  basePath: '/consenti',       // URL prefix for all routes
  dashboard: true,             // serve admin SPA at basePath

  rateLimit: {
    windowMs: 60_000,          // 1-minute window
    maxRequests: 60,           // requests per window per IP
  },

  compliance: {
    type: 'auto',                 // 'auto' = geo-resolve per visitor | ComplianceGroupId = fixed group
    geoDataProvider: 'default',   // 'default' | 'hosted-geoip-lite' | 'geoip' | 'maxmind' | CountryResolverFn
    complianceMap: 'default',     // 'default' (embedded map) | URL | { version, override?, countries }
    gpc: true,                    // server-side GPC enforcement on consent writes; false = off

    tcf: {
      enabled: false,
      cmpId: 0,
      cmpVersion: 1,
      publisherCC: 'DE',          // ISO 3166-1 alpha-2 — needed for spec-correct TC strings
    },

    gpp: {
      enabled: false,
      cmpId: 0,
      cmpVersion: 1,
      mspaCoveredTransaction: false,   // required, no default
      mspaOptOutOptionMode: 0,         // 0 = not applicable | 1 = yes | 2 = no
      mspaServiceProviderMode: 0,
    },

    dataSigningHash: process.env.CONSENTI_DATA_SIGNING_HASH,  // signs consent records, ownership cookies, parental-consent tokens; salts hashed IPs. Auto-generated if omitted.

    parentalConsentTokenTtlDays: 7,   // expiry of parental-consent tokens (default 7)

    dataRetention: {
      purgeAfterDays: 365,       // delete consent records older than this
    },
  },

  // S3 sync for profile locale JSON files (optional)
  s3Api: {
    enabled: false,
    region: 'us-east-1',
    bucketName: 'consenti-profiles',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
    // sessionToken: process.env.AWS_SESSION_TOKEN,  // for temporary credentials
  },

  // CDN / cache invalidation hook (optional)
  handleCache: (paths, profileId, isPurge) => {
    // paths: locale file paths written or removed
    // profileId: id of the profile that triggered the write
    // isPurge: true = files removed (deactivate/delete); false = files written (create/activate)
  },

  multiTenant: {
    enabled: false,
  },

  maxBodySize: 1_048_576,      // 1 MB request body limit
  trustedProxies: [],          // IPs / CIDRs of reverse proxies (nginx, Cloudflare…)

  branding: {
    appName: 'My CMP',         // dashboard header, login page, browser tab
    appLogoPath: './logo.svg', // local file or https:// URL
    hidePoweredBy: false,      // true = hide "Powered by Consenti" badge
  },

  plugins: [],
})

${storage.path}/
  db/
    consenti-data.json     ← JSON adapter
    consenti.db            ← SQLite adapters
  profiles/
    ${tenantId}/
      ${profileId}/
        1/                 ← version 1 (immutable once written)
          en.json
          fr-FR.json
          default.json     ← copy of defaultLocale content
        2/                 ← version 2 on next edit
      ${complianceGroup}/ → symlink to the active profile's version dir (hot-serve path)

storage: { driver: 'json', path: './consenti-data' } // path is a directory

# Node 20+ native addon (fastest; needs build toolchain or prebuilt binary)
npm install better-sqlite3

# Node 20+ WASM fallback (no compilation required)
npm install node-sqlite3-wasm

// Node 22.5+ — built-in, no install needed
storage: { driver: 'node:sqlite', path: './consenti-data' }

// Node 20+ with native addon
storage: { driver: 'better-sqlite3', path: './consenti-data' }

// Node 20+ WASM fallback
storage: { driver: 'node-sqlite3-wasm', path: './consenti-data' }

npm install pg         # PostgreSQL
npm install mysql2     # MySQL / MariaDB
npm install mongodb    # MongoDB

// PostgreSQL
storage: { driver: 'postgresql', path: './consenti-data', uri: process.env.CONSENTI_DB_URI }

// MySQL
storage: { driver: 'mysql', path: './consenti-data', uri: process.env.CONSENTI_DB_URI }

// MongoDB
storage: { driver: 'mongodb', path: './consenti-data', uri: process.env.CONSENTI_DB_URI, database: 'consenti' }

CONSENTI_DB_DRIVER=node:sqlite
CONSENTI_DB_PATH=./consenti-data

CONSENTI_DB_DRIVER=postgresql
CONSENTI_DB_PATH=./consenti-data      # still required: profiles are stored here
CONSENTI_DB_URI=postgresql://consenti:your-password@localhost:5432/consenti

# …or individual fields instead of CONSENTI_DB_URI:
# CONSENTI_DB_HOST=localhost
# CONSENTI_DB_PORT=5432
# CONSENTI_DB_USER=consenti
# CONSENTI_DB_PASSWORD=your-password
# CONSENTI_DB_DATABASE=consenti

CONSENTI_DB_DRIVER=mysql
CONSENTI_DB_PATH=./consenti-data      # still required: profiles are stored here
CONSENTI_DB_HOST=localhost
CONSENTI_DB_PORT=3306
CONSENTI_DB_USER=consenti
CONSENTI_DB_PASSWORD=your-password
CONSENTI_DB_DATABASE=consenti

# …or one connection string instead of the five lines above:
# CONSENTI_DB_URI=mysql://consenti:your-password@localhost:3306/consenti

CONSENTI_DB_DRIVER=mongodb
CONSENTI_DB_PATH=./consenti-data      # still required: profiles are stored here
CONSENTI_DB_URI=mongodb://consenti:your-password@localhost:27017/?authSource=admin
CONSENTI_DB_DATABASE=consenti         # default: consenti

# 1. Back up the database and stop the app.
# 2. Dry run — prints what would be renamed, changes nothing.
#    Uses the same CONSENTI_DB_* variables as the app
#    (or --driver, --uri, --host/--port/--user/--password, --database).
node node_modules/@consenti/api/scripts/migrate-to-consenti-prefix.mjs

# 3. Rename.
node node_modules/@consenti/api/scripts/migrate-to-consenti-prefix.mjs --apply

# 4. Start the app — it finishes any remaining schema upgrade itself.

auth: {
  mode: 'local',
  adminEmail: '[email protected]',
  adminPassword: process.env.CONSENTI_ADMIN_PASSWORD!, // min 12 chars; 16+ recommended
  masterSecret: process.env.CONSENTI_ADMIN_MASTER_SECRET!,         // stable secret for production
}

auth: {
  mode: 'jwt',
  masterSecret: process.env.CONSENTI_ADMIN_MASTER_SECRET!, // must match the secret used to sign your tokens
}

{
  "sub": "user-id",
  "email": "[email protected]",
  "roles": ["super_admin"],
  "tenantId": "default"
}

auth: {
  mode: 'oidc',
  masterSecret: process.env.CONSENTI_ADMIN_MASTER_SECRET!, // signs the session cookie after OIDC login
  oidc: {
    issuer: 'https://accounts.google.com',  // or any OIDC-compliant provider
    clientId: process.env.OIDC_CLIENT_ID!,
    clientSecret: process.env.OIDC_CLIENT_SECRET!,
    redirectUri: 'https://yourapp.com/consenti/auth/oidc/callback',
    claimsMapping: {
      email: 'email',           // default; override if your IdP uses a different claim
      roles: 'consenti_roles',  // default; the claim that carries Consenti role names
    },
  },
}

npm install samlify

auth: {
  mode: 'saml',
  masterSecret: process.env.CONSENTI_ADMIN_MASTER_SECRET!,
  saml: {
    issuer: 'https://idp.example.com',
    entryPoint: 'https://idp.example.com/sso/saml',  // IdP SSO URL
    cert: process.env.IDP_CERT!,                      // IdP signing certificate (PEM, without headers)
    callbackUrl: 'https://yourapp.com/consenti/admin/v1/auth/saml/acs',
  },
}

import type { AdminUser } from '@consenti/api'

auth: {
  mode: 'custom',
  validateUser: async (req: Request): Promise<AdminUser | null> => {
    const token = req.headers.get('authorization')?.replace('Bearer ', '')
    if (!token) return null

    // call your own auth service, validate a session cookie, etc.
    const user = await myAuthService.verifyToken(token)
    if (!user) return null

    return {
      id: user.id,
      tenantId: 'default',
      name: user.name,
      email: user.email,
      passwordHash: '',
      isActive: true,
      createdAt: new Date().toISOString(),
      updatedAt: new Date().toISOString(),
    }
  },
}

// 1. Generate a secret + QR code for the current user (requires a valid JWT)
POST {basePath}/admin/v1/auth/totp/setup
→ { qrUrl, message }

// 2. Scan the QR code in an authenticator app, then verify a submitted 6-digit code
POST {basePath}/admin/v1/auth/totp/verify
{ "token": "123456" }
→ { success: true, message: 'TOTP enabled successfully' }

// 3. Disable TOTP for the current user
POST {basePath}/admin/v1/auth/totp/disable
→ { success: true, message: 'TOTP disabled' }

// Default — routes at /consenti/api/v1/...
basePath: '/consenti'

// Custom prefix
basePath: '/cmp'
// → public API:  /cmp/api/v1/consent
// → admin API:   /cmp/admin/...
// → dashboard:   /cmp  (SPA)
// → OpenAPI UI:  /cmp/api/docs

// Simplest — serve at /consenti
dashboard: true

// Disable (headless / API-only mode)
dashboard: false

// Serve at a custom path
dashboard: { enabled: true, path: '/admin' }

// Tighter limit for high-traffic sites
rateLimit: {
  windowMs: 60_000,    // 1-minute window
  maxRequests: 30,     // 30 req/min per IP
}

// Disable entirely (you handle rate limiting upstream)
rateLimit: { enabled: false }

// Zero-dep geo routing (timezone + Accept-Language heuristic)
compliance: {
  type: 'auto',
  geoDataProvider: 'default',
}

// IP-based — no install, calls ipinfo.io (requires outbound internet)
compliance: {
  type: 'auto',
  geoDataProvider: 'hosted-geoip-lite',
}

// IP-based — local lookup via geoip-lite (npm install geoip-lite)
compliance: {
  type: 'auto',
  geoDataProvider: 'geoip',
}

// Fixed group — GDPR-only product serving only EU visitors
compliance: {
  type: 'opt-in',
}

// Custom geo resolver — integrate your own GeoIP SaaS
compliance: {
  type: 'auto',
  // ctx: { ip, timezone, language, languages, locale } — languages/locale come from the widget
  geoDataProvider: async ({ ip, timezone, language, languages, locale }) => {
    const res = await fetch(`https://api.mygeoip.com/${ip}`)
    const data = await res.json()
    return { country: data.country_code, region: data.region, locale: data.locale ?? null }
  },
}

// Override the country -> compliance-group map itself
compliance: {
  type: 'auto',
  complianceMap: 'default', // 'default' (embedded map) | a URL string | an inline object
  // complianceMap: 'https://your-host.com/compliance-map.json',
  // Replaces the embedded map (default) — only the listed countries resolve:
  // complianceMap: { version: '2026-01', countries: { DE: { complianceGroup: 'opt-in' } } },
  // Merge over the embedded map — only DE changes, every other country keeps its built-in group:
  // complianceMap: { version: '2026-01', override: false, countries: { DE: { complianceGroup: 'opt-out' } } },
}

// Custom geo resolver that already knows the compliance group — skips the
// country/region jurisdiction-map lookup entirely for a provider carrying its own
// legal-grade jurisdiction data (e.g. routing into a custom, non-built-in group)
compliance: {
  type: 'auto',
  geoDataProvider: async ({ ip, timezone, language }) => {
    const res = await fetch(`https://api.my-legal-geo-service.com/${ip}`)
    const data = await res.json()
    return {
      country: data.country_code,
      region: data.region,
      locale: data.locale ?? null,
      complianceGroup: data.consentModel, // e.g. an operator-defined custom group id
    }
  },
}

compliance: {
  type: 'auto',
  geoDataProvider: 'geoip', // or 'maxmind' / 'hosted-geoip-lite' — needed to resolve a US state at all
  complianceMap: {
    version: '2026-01',
    countries: {
      US: {
        complianceGroup: 'opt-out',
        default: 'opt-out-strict',
        overriddenRegions: {
          CO: { complianceGroup: 'opt-out', requiresSensitiveOptIn: true },
        },
      },
    },
  },
}

s3Api: {
  enabled: true,
  region: 'us-east-1',
  bucketName: 'my-cmp-profiles',
  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
}

handleCache: (paths, profileId, isPurge) => {
  if (isPurge) {
    // Purge these paths from your CDN / nginx proxy cache
    for (const p of paths) {
      cdnClient.purge(p)
    }
  } else {
    // Warm the cache at these paths
    for (const p of paths) {
      cdnClient.warm(p)
    }
  }
}

import { CloudFrontClient, CreateInvalidationCommand } from '@aws-sdk/client-cloudfront'

const cloudfront = new CloudFrontClient({ region: 'us-east-1' })

handleCache: async (paths, _profileId, isPurge) => {
  // Only the pointer.json paths need active invalidation — versioned locale
  // files are immutable and can just expire out of cache on their own TTL.
  const pointerPaths = paths.filter(p => p.endsWith('pointer.json'))
  if (pointerPaths.length === 0) return

  await cloudfront.send(new CreateInvalidationCommand({
    DistributionId: process.env.CLOUDFRONT_DISTRIBUTION_ID!,
    InvalidationBatch: {
      CallerReference: `${Date.now()}`,
      Paths: {
        Quantity: pointerPaths.length,
        Items: pointerPaths.map(p => `/${p.replace(/^.*\/profiles\//, 'profiles/')}`),
      },
    },
  }))
}

compliance: {
  tcf: {
    enabled: true,
    cmpId: 42,          // your IAB CMP ID
    cmpVersion: 1,
    publisherCC: 'DE',  // your country — needed for spec-correct TC strings
  },
}

compliance: {
  gpp: {
    enabled: true,
    cmpId: 9999,
    cmpVersion: 1,
    mspaCoveredTransaction: true,
    mspaOptOutOptionMode: 1,     // 0 = not applicable | 1 = yes | 2 = no
    mspaServiceProviderMode: 2,
  },
}

// Keep consent records for 1 year, then purge automatically
compliance: {
  dataRetention: {
    purgeAfterDays: 365,
  },
}

multiTenant: { enabled: true }

// Clients must then pass:
// X-Tenant-ID: acme-corp
// or: GET /consenti/api/v1/consent?tenantId=acme-corp

maxBodySize: 512_000   // 512 KB

// Single proxy
trustedProxies: ['127.0.0.1']

// Private network (e.g. Kubernetes cluster)
trustedProxies: ['10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16']

import {
  ConsentiServerPlugin,
  type PluginContext,
  type CreateConsentInput,
  type ConsentDbRecord,
} from '@consenti/api'

export class AuditWebhookPlugin extends ConsentiServerPlugin {
  name = 'audit-webhook'

  async initialize(ctx: PluginContext): Promise<void> {
    // ctx.storage — direct StorageAdapter access
    // ctx.config  — full ConsentiServerConfig
    console.log('AuditWebhookPlugin ready')
  }

  async afterConsentSave(record: ConsentDbRecord): Promise<void> {
    await fetch('https://webhook.example.com/consent', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(record),
    })
  }

  async destroy(): Promise<void> {
    // clean up connections, timers, etc.
  }
}

// Register it:
plugins: [new AuditWebhookPlugin()]

// Minimal — just change the app name
branding: {
  appName: 'Acme CMP',
}

// Full white-label — custom name, logo, and hide badge
branding: {
  appName: 'Acme CMP',
  appLogoPath: './assets/acme-logo.svg',  // local file — copied and served automatically
  hidePoweredBy: true,
}

// Logo from a public CDN
branding: {
  appName: 'Acme CMP',
  appLogoPath: 'https://cdn.acme.com/logo.svg',
}

createConsenti({
  compliance: {
    dataSigningHash: process.env.CONSENTI_DATA_SIGNING_HASH,
  },
})