admin/cookie-consent-jurisdiction-engine-v1
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update release documentation

Browse Source
This commit is contained in:
Deyson Thomé
2026-09-02 15:35:08 -03:00
parent 8ac890c437
commit 6496728b9e
1 changed files with 263 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+263 -43
View File
@@ -1,57 +1,277 @@
# Universal Cookie Consent — Jurisdiction Engine v1 # Universal Cookie Consent — Jurisdiction Engine v1
Stage 3.2 introduces a pure, deterministic Jurisdiction Engine. Independent consent management engine with a deterministic jurisdiction layer.
## Responsibilities The project is designed as a reusable foundation for cookie consent and privacy integrations across different websites and jurisdictions.
The engine resolves a jurisdiction context and maps it to a policy family. ## Architecture
It deliberately does **not**:
- read IP addresses; The system is divided into four main areas:
- call geolocation APIs;
- access browser location;
- inspect GPC;
- enforce consent;
- modify the Core;
- integrate GTM;
- provide legal advice.
## Modes ```text
Universal Cookie Consent
- `fixed`: the site explicitly selects a jurisdiction. │
- `auto`: the site supports multiple jurisdictions and supplies available signals. ├── Consent Core
- `global`: the site deliberately selects the global baseline for everyone. │ ├── categories
│ ├── consent state
## Resolution priority │ ├── events
│ └── persistence
`site-config` > `server` > `application` > `browser` > `fallback` │
├── Jurisdiction Engine
The resolver is deterministic and uses only supplied signals. │ ├── jurisdiction catalog
│ ├── policies
## Initial catalog │ ├── deterministic resolution
│ └── signal priority
- `global` │
- `us` ├── Integration Layer
- `us-ma` │ ├── jurisdiction context
- `us-ca` │ └── Core integration
- `eu` │
└── Tests
The policy catalog is intentionally a structural placeholder. Detailed legal requirements will be researched and added in a later policy stage rather than being guessed or embedded in the resolver. ├── Core
├── Jurisdiction
## Tests ├── Integration
├── Audit
Node regression: ├── Reliability
└── Adversarial
```bash
node tests/jurisdiction-test.mjs
``` ```
Browser Test Lab: 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:
```text
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:
```text
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:
```bash
./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:
```text
tests/
```
A local HTTP server can be started with:
```bash ```bash
python -m http.server 8000 python -m http.server 8000
``` ```
Then open: The browser test pages include:
```text
/tests/test.html
/tests/jurisdiction-test.html
/tests/integration/integration-test.html
/tests/audit/audit-test.html
```
## Versioning
Current engine version:
```text
1.0.1
```
Current policy version:
```text
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:
```text
126/126 tests
```
The next release step is a final release review covering documentation, versioning, and repository state before creating a stable release tag.
`http://localhost:8000/tests/jurisdiction-test.html`