Update release documentation
This commit is contained in:
Deyson Thomé
@@ -1,57 +1,277 @@
|
||||
# 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.
|
||||
It deliberately does **not**:
|
||||
## Architecture
|
||||
|
||||
- read IP addresses;
|
||||
- call geolocation APIs;
|
||||
- access browser location;
|
||||
- inspect GPC;
|
||||
- enforce consent;
|
||||
- modify the Core;
|
||||
- integrate GTM;
|
||||
- provide legal advice.
|
||||
The system is divided into four main areas:
|
||||
|
||||
## Modes
|
||||
|
||||
- `fixed`: the site explicitly selects a jurisdiction.
|
||||
- `auto`: the site supports multiple jurisdictions and supplies available signals.
|
||||
- `global`: the site deliberately selects the global baseline for everyone.
|
||||
|
||||
## Resolution priority
|
||||
|
||||
`site-config` > `server` > `application` > `browser` > `fallback`
|
||||
|
||||
The resolver is deterministic and uses only supplied signals.
|
||||
|
||||
## Initial catalog
|
||||
|
||||
- `global`
|
||||
- `us`
|
||||
- `us-ma`
|
||||
- `us-ca`
|
||||
- `eu`
|
||||
|
||||
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.
|
||||
|
||||
## Tests
|
||||
|
||||
Node regression:
|
||||
|
||||
```bash
|
||||
node tests/jurisdiction-test.mjs
|
||||
```text
|
||||
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
|
||||
```
|
||||
|
||||
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
|
||||
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`
|
||||
|
||||
Reference in New Issue
Block a user