cookie-consent-jurisdiction-engine-v1/README.md

Universal Cookie Consent — Jurisdiction Engine v1

Independent consent management engine with a deterministic jurisdiction layer.

The project is designed as a reusable foundation for cookie consent and privacy integrations across different websites and jurisdictions.

Architecture

The system is divided into four main areas:

Universal Cookie Consent
│
├── Consent Core
│   ├── categories
│   ├── consent state
│   ├── events
│   └── persistence
│
├── Jurisdiction Engine
│   ├── jurisdiction catalog
│   ├── policies
│   ├── deterministic resolution
│   └── signal priority
│
├── Integration Layer
│   ├── jurisdiction context
│   └── Core integration
│
└── Tests
    ├── Core
    ├── Jurisdiction
    ├── Integration
    ├── Audit
    ├── Reliability
    └── Adversarial

The jurisdiction layer determines the regulatory/configuration context.

Jurisdiction does not grant consent.

The resolved jurisdiction is passed to the Consent Core as configuration.

Consent Core

The Core manages four consent categories:

• necessary
• preferences
• analytics
• marketing

Supported states:

• granted
• denied
• unknown

The necessary category remains permanently granted and cannot be denied through a valid consent operation.

Core operations include:

• initialize()
• acceptAll()
• rejectAll()
• setConsent()
• revoke()
• reset()
• setGpc()
• setJurisdiction()
• getState()
• getConfig()

Returned state is isolated from internal state so consumers cannot mutate the engine through returned objects.

Idempotent operations do not generate false state transitions or duplicate transition events.

Persistence

When browser cookie storage is available, consent state can be persisted through document.cookie.

Persisted envelopes are validated for:

• engine version;
• policy version;
• timestamp;
• categories;
• jurisdiction;
• GPC state.

Invalid, expired, incompatible, or malformed payloads are rejected safely.

When browser storage is unavailable, including the Node test environment, the engine does not pretend that persistence succeeded.

Jurisdiction Engine

Jurisdiction resolution is deterministic and uses only supplied configuration and signals.

Supported initial jurisdictions include:

• global
• us
• us-ma
• us-ca
• eu

Supported modes:

fixed

The site explicitly selects a jurisdiction.

auto

The engine resolves jurisdiction from available signals.

Resolution priority:

site-config
    ↓
server
    ↓
application
    ↓
browser
    ↓
fallback

global

The site deliberately selects the global baseline.

Unknown or invalid jurisdictions are rejected rather than silently converted into an incorrect configuration.

The jurisdiction catalog is intentionally structural at this stage. Detailed legal requirements are not guessed or embedded in the resolver.

GPC

Global Privacy Control is represented as state information.

Setting:

gpc = true

does not automatically grant optional consent categories.

Explicit consent remains an explicit consent decision and is not silently replaced by GPC state.

Events

The Core provides events associated with consent transitions and lifecycle operations, including:

• consent:changed
• consent:accepted
• consent:revoked
• consent:reset
• storage:error
• consent:expired
• initialized

Event behavior and idempotency are covered by the test suites.

Testing

The project currently has six validation groups:

Test group	Result
Core	19/19
Jurisdiction	20/20
Integration	10/10
Audit	14/14
Reliability	26/26
Adversarial	37/37
Total	126/126

The complete suite can be executed with:

./run-tests.sh

The test suite covers, among other areas:

• default and invalid configurations;
• consent state transitions;
• partial and complete consent;
• idempotency;
• revoke and reset;
• state isolation;
• immutable returned state;
• persistence;
• malformed persisted payloads;
• policy mismatch;
• expired consent;
• GPC behavior;
• jurisdiction resolution;
• signal priority;
• integration boundaries;
• adversarial inputs.

Browser Test Labs

Browser-oriented test pages are available under:

tests/

A local HTTP server can be started with:

python -m http.server 8000

The browser test pages include:

/tests/test.html
/tests/jurisdiction-test.html
/tests/integration/integration-test.html
/tests/audit/audit-test.html

Versioning

Current engine version:

1.0.1

Current policy version:

2026-01

The Git repository is maintained independently from the runtime engine version.

Development Principle

This project is being developed as a controlled and test-driven system.

Existing approved behavior must not be changed merely to make a new test pass.

When a test fails:

1. identify the exact cause;
2. determine whether the problem is in the engine or in the test;
3. preserve previously validated behavior;
4. change the Core or architecture only when there is an explicit technical reason;
5. add or adjust tests to increase confidence in the actual contract.

The objective is to establish confidence in the engine before adding higher-level functionality.

Repository

The project is maintained in a Gitea repository.

The current main branch contains the validated test suite and its adversarial extensions.

Current Status

The current implementation has passed:

126/126 tests

The next release step is a final release review covering documentation, versioning, and repository state before creating a stable release tag.