cookie-consent-jurisdiction-engine-v1

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.

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:

identify the exact cause;
determine whether the problem is in the engine or in the test;
preserve previously validated behavior;
change the Core or architecture only when there is an explicit technical reason;
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.

README.md

Universal Cookie Consent — Jurisdiction Engine v1

Architecture

Consent Core