aere-quantum/control-plane/README.md

# AERE Quantum Security Control Plane

From "we found the problem" to "this is exactly what changes, in which order, what we can migrate automatically, how the rest is
fixed on your server, and how that is proven". Node.js 24 with OpenSSL 3.5, no dependencies. It composes tools that exist beside it:
the cryptographic inventory (`crypto-inventory/`), the TLS readiness scanner (`readiness/`), the PQ Gateway, KMS and PKI
(`pq-gateway/`, `pq-kms/`, `pq-pki/`), the verification layer (`verify-layer/`) and the AIP-23 envelope builder (`proof-kinds/`).

Code comments, internal names, test names and file names are in Romanian; command lines, JSON fields, messages and this
documentation are in English (the data format was translated on 2026-09-29, version 2 of each format).

## 1. Plan: `control-plane.mjs`, `plan-migrare.mjs`

    node control-plane.mjs --code <dir> [--scan scan.json] [--json]

Runs the inventory on a code directory and, optionally, takes a scan of a hostname (the JSON of the readiness scanner), and writes a
prioritized plan. Every quantum-vulnerable asset becomes an action:

Since 2026-10-18 (first run on a code base that is not ours, a Rust messenger): a key agreement that the
application calls itself (X25519 in a ratchet, a PQXDH handshake, a Tor `ntor` handshake, `createECDH` in
Node) is **not** routed to the PQ Gateway, because a TLS edge cannot see it; its action is `manual`, in
code, with the hybrid target written out (X25519 + ML-KEM-768 in the same handshake and key schedule). A
signature or public-key encryption that the application performs itself keeps its PKI/KMS action (the
product issues the hybrid key, for real), and `how` says that the call site must then be changed to use it.
Only a finding with no call context (no `api`, no language) keeps the old routing: its context is not
known, so it is not guessed. The inventory's TLS configuration findings still go to the gateway.

    { ref, asset, problem, current, target, method: "auto-aere" | "manual" | "blocked", product: "gateway" | "kms" | "pki" | null,
      how, cn?, primitive?, urgency: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW", blocker, scope: "production" | "test", location, source }

Two rules added on 2026-10-18 after the run on the libsignal tree. A finding in **test code** (`tests/`, `benches/`, `fuzz/`,
`examples/`, `*Test.java`, `*.test.ts`, ...; the path rule lives in `scopulCaii`) stays in the plan but with `scope: "test"`,
urgency `LOW` and a `how` that says so, and `summary.byScope` counts it apart: on libsignal 76 of 197 actions (75 of them HIGH)
were in such files and stood in front of the production call sites. A **self-signed certificate** that is a pinned trust anchor
(valid for more than five years, or whose CN is not a host name: the AMD, Google and AWS attestation roots in libsignal) is
`blocked` with the reason written, not "auto through the PQ PKI": the PKI cannot replace a root the verifier pins, only its owner
can publish a post-quantum one. A short self-signed service certificate for a host name is still reissued by the PKI for the same CN.

Harvest-now-decrypt-later applies to key exchange and encrypted data, **not to signatures** (a signature is public; it is not
harvested), so a classical key exchange on a public endpoint is the only CRITICAL case, and a classical signature is a future
forgery risk. The plan is honest about blockers: a public WebPKI certificate cannot be reissued post-quantum today (no public CA
issues one), so it is `blocked` with the reason written, not `auto`. The scan findings are classified by a closed table on the ids
the scanner actually emits (the test derives them from the scanner's source and fails on an id without a classification).

## 2. Execution: `executa-migrare.mjs`

    node executa-migrare.mjs --plan plan.json --out <dir> [--consent ref1,ref2|all] [--execute]
      [--gw-cert c.pem --gw-key k.pem --gw-upstream http://h:p [--gw-mode hybrid-only|hybrid-preferred] [--gw-listen 127.0.0.1:8443] [--gw-keep]]
      [--kms-url http://127.0.0.1:8420 --kms-token-file f] [--pki-dir ca --pki-ca issuing --pki-roots ca/root.crt]   (AERE_PKI_PASSPHRASE)

Nothing runs without consent **per action**, and the default is a dry run (`--execute` starts the work). Each `auto-aere` action is
done through the matching product and judged by a **measurement afterwards**, not by an exit code:

| product | what it does | the proof afterwards | rollback |
|---|---|---|---|
| `gateway` | starts the PQ Gateway in front of the service and writes its configuration for your service manager | a client offering only `X25519MLKEM768` completes a TLS 1.3 handshake; a second, classical-only client says whether classical clients are still accepted (`hybrid-preferred`) or refused (`hybrid-only`) | the gateway is stopped |
| `kms` | creates the hybrid key (X25519 + ML-KEM-768) or rotates it if it exists; the name comes only from the `ref` (`mig-...`) | `latest_version` and the fingerprint read back from the KMS | older versions stay decryptable; nothing is deleted |
| `pki` | issues an ML-DSA-65 certificate from your PQ CA for a `cn` checked to be a host name (no wildcard) | `verifyChain` up to the root | files written in part are removed |

Every action is a record in a hash chain `sha256(seq | prev | record)` in `execution.json` (`records[]`, each `{ seq, prev, record,
hash }`; verdicts `OK`, `FAILED`, `DRY-RUN`, `SKIPPED-no-consent`). The console and anyone else can check it again; a changed or
removed record is caught. It does not change your DNS, ports or firewall (moving traffic to the gateway stays with you), does not
issue public WebPKI certificates, and does not delete keys.

## 3. Remediation: `remediere.mjs`

    node remediere.mjs recipe --plan plan.json --profile nginx|apache|haproxy|node|go [--json]
    node remediere.mjs verify --plan plan.json --scan after.json [--applied-at 2026-09-28T10:00:00Z] [--out dir]

The actions no AERE product can do (the `manual` ones: TLS 1.3 missing, TLS 1.2 accepted, the hybrid group not preferred, HSTS, the
certificate) live in your server's configuration, which we do not touch. The **recipe** gives, for your server software, the exact
fragment, where it goes, the measurable precondition (the OpenSSL or Go version and the command that shows it) and the configuration
check to run before reloading; fragments are generated from one structured form (groups, minimum version, HSTS), and certificate
problems get operational steps. The **proof**: after you apply it, a new scan judges each action `RESOLVED` (the defect is gone AND the
required property is measured), `UNRESOLVED`, or `UNMEASURED` (the scan failed, is of another host, or is not from after the time you
applied the change: `--applied-at`, otherwise the plan's `generatedAt`; with neither, everything is `UNMEASURED`). A domain in the
plan that is not a host name gets no recipe, so no command to copy is built with it. What is measured by us is written on every
recipe (`measured`): since 2026-10-18 all five profiles end to end, on real servers started from exactly the recipe's fragments
(nginx 1.31.7 with OpenSSL 3.5.8/3.5.9, Apache 2.4.69 with OpenSSL 3.5.9 and HAProxy 3.4.7 with OpenSSL 3.5.9, each in a container;
Go 1.26.5; Node earlier): a client offering only the hybrid group is accepted, a TLS 1.2 client is refused, HSTS is sent
(`dovezi/retete-2026-10-18/`); not measured: a production server with its full configuration, real browsers as clients.

## 4. Compliance report: `raport-conformitate.mjs`

    import { complianceReport, verifyReport } from './raport-conformitate.mjs';
    const { report, envelope, evidenceHash } = complianceReport({ plan, organization, date: '2026-09-28', risk: 'high', cnsa: true, cnsaCategories });

For every action: which regimes apply (NIST IR 8547 initial public draft; the EU coordinated roadmap of 2025-06-23; optionally
CNSA 2.0), each deadline and the days left on the report's date, and whether the asset is exposed today (key exchange: yes;
signature: no; a key of unknown use: not known). Each regime carries its source, the source's date and the date it was read; CNSA 2.0
is read from secondary sources, and says so. An action the report cannot classify is counted, and then the report cannot say that
there is no vulnerable algorithm. The report is bound to an AIP-23 `compliance` envelope whose `evidenceHash` is the digest of the
canonical report. It is not a certification and not a legal opinion, and it covers only what was inventoried and scanned.

## 5. Console: `consola.mjs`, `consola-web/`

    node consola.mjs --bundle bundle.json [--plan plan.json] [--execution execution.json] [--json]

One state of a deployment: the audit chain of the verification layer recomputed from its entries, the integrity of every AIP-23
envelope recomputed, the plan folded in, and the execution chain checked again. The console does not trust what a bundle says about
itself (`chainOk: true` over a modified log is reported as a suspect self-report). `consola-web/index.html` renders that output; it
computes nothing in the browser, and a bundle pasted there directly is shown as `UNCHECKED`.

## 6. Organization judgement: `organizatie.mjs`

    node organizatie.mjs --pack pack.json [--context context.json] [--require shield,identity,...] [--at <RFC 3339>] [--online] [--json]

Exit code 0 = VALID, 1 = INVALID, 2 = NOT_MEASURED (or the command could not run), 3 = PARTIAL.

An organization brings an **evidence pack**; every artifact in it is judged again by the published verifier of its kind, and the
result is one verdict per domain and a summary that is never stronger than the weakest domain that was asked for. Nothing the pack
says about itself is believed.

**The pack** (`aere-organization-evidence-pack`):

    { "kind": "aere-organization-evidence-pack", "organization": "...", "createdAt": "...",
      "artifacts": [ { "id": "...", "artifact": "<kind>", "input": { ... } }, ... ] }

`id` is letters, digits and `. _ : / -`, at most 128 characters, unique in the pack (a repeated id is judged once, its copies are
`NOT_MEASURED`). `artifact` is one of 25 kinds in eight domains:

| domain | kinds |
|---|---|
| `shield` | `shield-console` (a sidecar bundle, the plan and the execution chain, judged by `consola.mjs`; an execution given with a plan must be the executor's run of that plan) |
| `identity` | `identity-presentation`, `sdjwt-presentation`, `sdjwt-vc-presentation` |
| `compliance` | `compliance-presentation`, `travel-rule-binding`, `travel-rule-message`, `travel-rule-receipt`, `pq-compliance-report` (a report of section 4 and its envelope) |
| `ai` | `ai-trust-bundle`, `agent-ledger` |
| `payments` | `payment-risk`, `payment-receipt`, `market-timeline` |
| `devices` | `device-bundle`, `device-operation-log`, `device-reputation` |
| `audit` | `audit-log`, `audit-inclusion`, `audit-consistency` |
| `proofs` | `envelope` (AIP-23), `dataset-record`, `dataset-answer`, `dataset-consistency`, `dataset-sample` |

Cloud is not a domain of its own: what a Cloud product returns is judged in the domain of the artifact. The 23 kinds of the
conformance suite are judged through the suite's adapter (`../conformance/implementare-aere.mjs` beside a public copy of the control
plane), called as a program, so a verifier that does not start is seen as such; the two kinds of the control plane itself are judged
here (`shield-console` by the console's own evaluation, plus the binding of the execution to the plan given with it;
`pq-compliance-report` by `verifyReport`, by making the report again from its own findings with the same generator, which must give
exactly the report and the envelope's statement, and by the AIP-23 verifier for its envelope). The compliance envelope is not
signed, so a report bound to it shows only that the report is self-consistent; whether its findings are the real plan's is not
judged. A kind no verifier here judges is listed as unjudged.

**The context** (`aere-organization-context`) belongs to the party that relies on the pack, not to the organization:

    { "kind": "aere-organization-context", "now": "<RFC 3339>", "require": ["identity", ...],
      "byKind": { "<kind>": { ... } }, "byArtifact": { "<id>": { ... } } }

Every input of every verifier is classified (the test derives the keys from the adapter's source, from the source of the module the
adapter hands a whole input to, and from the 791 vectors of the suite, and fails on a key without a class): the **artifact** comes
only from the pack; a **stapled** input (a status list, a revocation, a firmware policy, signed by a third party) is taken from the
context and from the pack, joined, the context's lists first (a verifier reads only the first entries of a long list, so lists brought
by the pack cannot push the relying party's own revocation out of what is read); a **verifier** input (the trusted issuers or
manufacturers, the audience, the nonce, the expected values, the relying party's own readings: a market's arbiter and arbitration
timeout, the facts a reputation is computed from) comes from the context, and if only the pack brings it, it is used but the artifact
cannot be VALID (`PARTIAL`, because the organization chose its own trust); a **verifier-only** input (the chain to read, a
beneficiary's private KEM keys, the time limit) is never taken from the pack; the **clock** comes from the context for that artifact
or kind, then `--at`, then the context's global `now`, then this machine, never from the pack. For a market timeline and a reputation,
whose module reads the whole input, a key the module does not read by name stays with the artifact (so a member too many is still
refused).

**The verdicts.** Each artifact gets the verifier's verdict (`VALID`, `INVALID`, `PARTIAL`), or `NOT_MEASURED` when the verifier
did not run or gave no verdict of the suite's form: a verdict whose own levels do not give it (by the suite's rule in `verdict.mjs`),
or a verdict for another kind than the one asked in its place (the order of the adapter's answers cannot then be trusted, so none of
them is). When a batch does not complete (too few answers, or the time limit), each artifact is judged alone, so one artifact cannot
take the verdicts of the others with it. A domain is as weak as its weakest artifact; a domain with no artifact is
`NOT_PRESENTED`, and a required domain that is not presented makes the summary `NOT_MEASURED`, never `VALID`. The required domains
are `--require`, then `context.require`, then all eight. Unjudged artifacts cap a `VALID` summary at `PARTIAL` (the pack claims more
than was measured). A verdict written in the pack (`verdict`, `summary.verdict`, an artifact's `verdict` or `expected.verdict`) is
ignored, and named as suspect when it differs from the measurement.

**The network.** Anchoring and finality on a chain are read only with `--online`, and only for the kinds whose verifier reads the
chain (an AIP-23 envelope, a payment receipt, a market timeline, an AI trust bundle, the report's envelope). Without it, each of those
that claims a notarization is listed in `network.needed` and its levels say `NOT_MEASURED`. A device bundle or an operation log
judges its notarization on the relying party's own readings (`anchors`, `readings` in the context), never on the chain read here,
with `--online` or not: when they are missing it is listed in `network.readings`. `network.unmeasured` lists what `--online` could
not read, and `network.finality` names the chain each finality was read on, a testnet said as such (the summary says it too). The
console's Shield evaluation does not read a chain even with `--online`: a notarization claimed inside a sidecar bundle has to be
presented as its own `envelope` artifact.

**What it does not judge.** The truth of what an artifact asserts beyond what its verifier checks (a market timeline, a payment
receipt without the relying party's transaction readings, the findings of a compliance report), the honesty of the host that produced
a sidecar bundle (section 5), and any kind outside the table. `consola-web/index.html` shows the output (`--json`) domain by domain,
each artifact with its verifier and the evidence it rests on; a pack pasted there directly is shown as `UNCHECKED`. The view judges
nothing, but it never shows a verdict stronger than the output's own rows give (a domain no stronger than its weakest artifact, the
summary no stronger than its weakest required domain): an edited output that contradicts itself is shown at the weaker reading and
named. Everything that comes from the pack is shown as text.

## Tests

    bash probele-b1.sh                  # all seven below, each VERDE / ROSU / STRICAT (in the development repository only)
    node proba-plan-migrare.mjs         # 44: real certificates and keys (openssl) through the real inventory; the scanner's ids derived from its source
    node proba-control-plane.mjs        # 10: the command line end to end, an all-post-quantum tree gives an empty plan
    node proba-executa-migrare.mjs      # 30: on real products started locally (KMS, PQ CA, gateway), with the attacks of the review
    node proba-remediere.mjs            # 33: real TLS servers on 127.0.0.1 scanned by the readiness scanner, before and after the recipe
    node control-negativ-remediere.mjs  # 7 of 7 guards broken in a copy, each turns the test red
    node proba-raport-conformitate.mjs  # 30: on the real outputs of the inventory and the scanner; the envelope through the AIP-23 verifier
    node control-negativ-raport-conformitate.mjs   # 3 plantings, each turns the named check red
    node proba-consola.mjs              # 8: a good bundle and four negative controls
    node proba-consola-web.mjs          # 26: the viewer in a real Chromium, phone (390 px) and desktop (1440 px); needs playwright-core and a Chromium
    node control-negativ-consola-web.mjs   # 8 defects planted in a copy of the page, each turns its named check red
    node proba-organizatie.mjs          # 74 (75 with --online): artifacts made by the real producers (the suite's vectors, checked against INDEX.json; a Shield state,
                                        #     a plan and a report made now), a good pack and one broken artifact per kind, and the attacks of the
                                        #     adversarial review of 2026-10-21; --online adds a row on testnet 28001
    node control-negativ-organizatie.mjs   # 45 of 45 guards removed in a copy, each turns its named row red
    node proba-organizatie-web.mjs      # 48: the organization view in a real Chromium, 390 px and 1440 px, edited outputs and text from the pack included
    node control-negativ-organizatie-web.mjs   # 20 defects planted in a copy of the page, each turns its named check red

The report test runs the envelope through the AIP-23 reference verifier (`AERE_VERIFY_PROOF=<verify-proof.mjs from aere.network/tools>`).
The counts above were measured on 2026-10-21 in the development repository and from a fresh clone of the public one (until
that day the planner and command-line lines said 30 and 9, counts from before rows were added to those two probes).
No third party has reviewed any of this.