From 6496728b9ea172e8a95fe2ed975c7e635c85a308 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Deyson=20Thom=C3=A9?= Date: Wed, 2 Sep 2026 15:35:08 -0300 Subject: [PATCH] Update release documentation --- README.md | 306 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 263 insertions(+), 43 deletions(-) diff --git a/README.md b/README.md index d661c7b..fc8dd2f 100644 --- a/README.md +++ b/README.md @@ -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`