docs: plan per-installation DWH REST auth

2026-08-20 22:44:23 +02:00
parent 8a1c23536f
commit 4ef0a6a833
3 changed files with 752 additions and 16 deletions
@@ -2,7 +2,7 @@

 **Date:** 2026-08-20

-**Status:** Approved in discussion; awaiting review of this written specification
+**Status:** Approved by the owner

 ## Purpose

@@ -105,10 +105,10 @@ beyond the approved PSD `systemd` deployment is not required by this implementat
 One credential identifies one ThothII installation, not one human user. An installation may have
 more than one temporarily active generation during rotation.

-The external key has two components:
+The external key contains a version marker, a public key ID, and a random secret:

 ```text
-<public-key-id>.<random-secret>
+thtdwh_v1.<public-key-id>.<random-secret>
 ```

 Requirements:
@@ -271,7 +271,10 @@ is local-only and does not weaken the authentication decision.

 The exposed shared credential is represented temporarily as `legacy-shared`. It is imported only
 from an approved protected source and is never placed in a command argument, terminal output,
-document, or evidence file.
+document, or evidence file. Because the existing value does not use the new versioned key
+format, it is stored as the only permitted `legacy_raw` record. The service compares the digest of
+the complete opaque legacy header only for that reserved record. After `legacy-shared` is revoked,
+no unversioned credential is accepted.

 The production route does not switch to the new authenticator until all of the following hold: