|
|
|
@@ -4,9 +4,9 @@
|
|
|
|
|
|
|
|
|
|
**Goal:** Validate local and OIDC authentication on macOS, deploy the exact feat/thoth-auth candidate to the Aritmolab/PSD server before merging it into main, and complete end-to-end acceptance with remote Authentik.
|
|
|
|
|
|
|
|
|
|
**Architecture:** Test the candidate first as a standalone local installation. Then install the same immutable Git revision on the existing PSD installation with the installation-aware thothctl lifecycle, leaving main untouched. Authentik provides OIDC login and a mandatory direct groups claim; ThothII maps exact external groups to roles and validates mapped groups through the Authentik catalog API.
|
|
|
|
|
**Architecture:** Test the candidate first as a standalone local installation. Then install the same immutable Git revision on the existing PSD installation with the installation-aware tht lifecycle, leaving main untouched. Authentik provides OIDC login and a mandatory direct groups claim; ThothII maps exact external groups to roles and validates mapped groups through the Authentik catalog API.
|
|
|
|
|
|
|
|
|
|
**Tech Stack:** macOS, Docker Desktop, Docker Compose, tht/thothctl, local Argon2id authentication, generic OIDC Authorization Code + PKCE, Authentik, PSD workspace registry, reverse proxy/TLS.
|
|
|
|
|
**Tech Stack:** macOS, Docker Desktop, Docker Compose, native host `tht` plus Python workflow `tht`, local Argon2id authentication, generic OIDC Authorization Code + PKCE, Authentik, PSD workspace registry, reverse proxy/TLS.
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
@@ -26,7 +26,7 @@ git status --short --untracked-files=all
|
|
|
|
|
|
|
|
|
|
Never deploy a moving branch name without checking its resolved SHA. Never put passwords, OIDC client secrets, Authentik API tokens, cookies, authorization headers, raw ID tokens, or password hashes in Git, shell history, screenshots, logs, or evidence.
|
|
|
|
|
|
|
|
|
|
Use protected operator values for <PUBLIC_URL>, <OIDC_ISSUER>, <AUTHENTIK_BASE_URL>, <OIDC_CLIENT_ID>, <THTCTL>, <INSTALLATION>, <WORKSPACE_ID>, and <OLD_SHA>.
|
|
|
|
|
Use protected operator values for <PUBLIC_URL>, <OIDC_ISSUER>, <AUTHENTIK_BASE_URL>, <OIDC_CLIENT_ID>, <THT_BIN>, <INSTALLATION>, <WORKSPACE_ID>, and <OLD_SHA>.
|
|
|
|
|
|
|
|
|
|
The Authentik contract is mandatory: a direct non-empty JSON array claim named groups; exact groups TOT Users and TOT Admin; mappings TOT Users -> user and TOT Admin -> admin; and a separate group-view-only API service account exposed only as THT_AUTHENTIK_API_TOKEN. Extra upstream groups are valid and silently ignored.
|
|
|
|
|
|
|
|
|
@@ -71,7 +71,7 @@ Expected: Docker Desktop and Compose are available and line-ending validation pa
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
bash scripts/build-local.sh
|
|
|
|
|
bash scripts/build-thothctl.sh
|
|
|
|
|
bash scripts/build-tht.sh
|
|
|
|
|
tht setup --profile local
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
@@ -176,12 +176,12 @@ Go/no-go: do not proceed to PSD if local login, role separation, logout, or reme
|
|
|
|
|
**Step 1: Capture live state**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
THTCTL=<THTCTL>
|
|
|
|
|
THT_BIN=<THT_BIN>
|
|
|
|
|
INSTALLATION=<INSTALLATION>
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" status
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" doctor
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" pi status
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" pi doctor
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" status
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" doctor
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" pi status
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" pi doctor
|
|
|
|
|
git -C /srv/thothii/source/ThothII status --short --untracked-files=all
|
|
|
|
|
git -C /srv/thothii/source/ThothII rev-parse HEAD
|
|
|
|
|
```
|
|
|
|
@@ -190,14 +190,14 @@ Save the live SHA as <OLD_SHA> and capture image identities, workspace registry
|
|
|
|
|
|
|
|
|
|
**Step 2: Drain and back up**
|
|
|
|
|
|
|
|
|
|
Announce maintenance, close the reverse proxy or show its maintenance page, drain active work, and stop through thothctl. Create the protected, checksummed backup specified in docs/install/server.md, including runtime trees and PSD PostgreSQL/session data where applicable. Back up credentials separately. Never run docker compose down --volumes.
|
|
|
|
|
Announce maintenance, close the reverse proxy or show its maintenance page, drain active work, and stop through tht. Create the protected, checksummed backup specified in docs/install/server.md, including runtime trees and PSD PostgreSQL/session data where applicable. Back up credentials separately. Never run docker compose down --volumes.
|
|
|
|
|
|
|
|
|
|
**Step 3: Check preconditions**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
git -C /srv/thothii/source/ThothII config --local core.autocrlf false
|
|
|
|
|
bash /srv/thothii/source/ThothII/scripts/verify-line-endings.sh
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" update --check-only
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" update --check-only
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Expected: descriptor, protected secrets, Pi-state mount, workspace repository binding, and Compose render remain valid before source changes.
|
|
|
|
@@ -207,7 +207,7 @@ Expected: descriptor, protected secrets, Pi-state mount, workspace repository bi
|
|
|
|
|
**Files:**
|
|
|
|
|
|
|
|
|
|
- Server source checkout: /srv/thothii/source/ThothII
|
|
|
|
|
- Server operator binary: protected THTCTL path
|
|
|
|
|
- Server operator binary: protected THT_BIN path
|
|
|
|
|
- Server installation descriptor and secret files: unchanged paths unless a reviewed auth update is required
|
|
|
|
|
|
|
|
|
|
**Step 1: Select the exact candidate**
|
|
|
|
@@ -226,21 +226,21 @@ Do not merge or rebase main. The running installation is intentionally based on
|
|
|
|
|
```bash
|
|
|
|
|
cd /srv/thothii/source/ThothII
|
|
|
|
|
bash scripts/build-local.sh
|
|
|
|
|
THT_THOTHCTL_OUTPUT_DIRECTORY=/srv/thothii/operator/build-output bash scripts/build-thothctl.sh
|
|
|
|
|
THT_THT_OUTPUT_DIRECTORY=/srv/thothii/operator/build-output bash scripts/build-tht.sh
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Install the architecture-appropriate candidate thothctl only after its build succeeds. Keep the old operator binary recoverable.
|
|
|
|
|
Install the architecture-appropriate candidate tht only after its build succeeds. Keep the old operator binary recoverable.
|
|
|
|
|
|
|
|
|
|
**Step 3: Start and verify the candidate**
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" update --check-only
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" start --build
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" status
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" doctor --json
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" update --check-only
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" start --build
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" status
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" doctor --json
|
|
|
|
|
curl --fail http://127.0.0.1:8080/health
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" pi doctor
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" pi test
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" pi doctor
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" pi test
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Expected: candidate frontend/core and internal services are healthy, no data volume was replaced, and the candidate SHA is recorded. Liveness alone is not release approval.
|
|
|
|
@@ -294,7 +294,7 @@ A missing mapped group must fail with redacted oidc_mapped_group_missing. Unmapp
|
|
|
|
|
If configuration requires process reload:
|
|
|
|
|
|
|
|
|
|
```bash
|
|
|
|
|
"$THTCTL" --installation "$INSTALLATION" pi restart --yes --drain
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" pi restart --yes --drain
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Repeat authentication, doctor, and health checks. Do not substitute raw Compose commands.
|
|
|
|
@@ -329,13 +329,19 @@ During a controlled window, make discovery/JWKS unavailable or rename a mapped g
|
|
|
|
|
- Read: docs/install/server-workspace-registry.md
|
|
|
|
|
- Use: authenticated PSD browser sessions
|
|
|
|
|
|
|
|
|
|
**Step 1: Validate as administrator**
|
|
|
|
|
**Step 1: Validate the workspace and authentication from the host CLI**
|
|
|
|
|
|
|
|
|
|
In Workspace Management, select <WORKSPACE_ID> and run Validate workspace source. Expected: Git descriptor, Evidence/catalog invariants, and complete authentication readiness pass; result is redacted and identifies the workspace revision.
|
|
|
|
|
```bash
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" \
|
|
|
|
|
workspace inspect --workspace "$WORKSPACE_ID" --json
|
|
|
|
|
"$THT_BIN" --installation "$INSTALLATION" auth check --json
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
**Step 2: Test connections**
|
|
|
|
|
Expected: the workspace registry is ready, authentication readiness passes, and output is redacted while identifying the active workspace revision.
|
|
|
|
|
|
|
|
|
|
Run Test workspace connections for the selected workspace. Expected: protected DWH/Evidence secrets are used, status is redacted, and workspace source is unchanged.
|
|
|
|
|
**Step 2: Verify the application boundary**
|
|
|
|
|
|
|
|
|
|
Open the configured public URL, authenticate with the approved identity, and verify that the application reaches the selected workspace without unexpected `401`/`403` responses. Keep DWH/Evidence connection tests read-only and use only the existing approved smoke question.
|
|
|
|
|
|
|
|
|
|
**Step 3: Test ordinary-user authorization**
|
|
|
|
|
|
|
|
|
@@ -356,7 +362,7 @@ Do not run mutating production queries. Preserve only a session ID and redacted
|
|
|
|
|
**Files:**
|
|
|
|
|
|
|
|
|
|
- Create: docs/testing/evidence/2026-08-18-thothii-authentication-psd-acceptance.md or the approved external evidence location
|
|
|
|
|
- Read: docs/install/server.md and docs/contracts/thothctl-pi.md
|
|
|
|
|
- Read: docs/install/server.md and docs/contracts/tht-pi.md
|
|
|
|
|
|
|
|
|
|
**Step 1: Mandatory gates**
|
|
|
|
|
|
|
|
|
@@ -370,7 +376,7 @@ Do not run mutating production queries. Preserve only a session ID and redacted
|
|
|
|
|
| Candidate deploy | Server candidate status/doctor/health pass |
|
|
|
|
|
| Authentik | Direct groups claim, issuer/JWKS, secrets, catalog, and mapped groups pass |
|
|
|
|
|
| OIDC authorization | ordinary, admin, unmapped, malformed, logout, and outage cases pass |
|
|
|
|
|
| Workspace integration | Validate workspace source and test connections pass |
|
|
|
|
|
| Workspace integration | `tht workspace inspect` and `tht auth check` pass; the authenticated application reaches the selected workspace |
|
|
|
|
|
| PSD smoke | One harmless known-good session completes |
|
|
|
|
|
| Hygiene | No secrets, tokens, cookies, hashes, or raw claims in evidence |
|
|
|
|
|
|
|
|
|
@@ -380,9 +386,9 @@ Include candidate SHA, old SHA, timestamps, commands, browser cases, redacted di
|
|
|
|
|
|
|
|
|
|
**Step 3: Roll back a failed candidate**
|
|
|
|
|
|
|
|
|
|
1. Keep the proxy closed and preserve .thothctl/<installation-id>/ recovery state.
|
|
|
|
|
2. Do not use thothctl pi rollback as the whole-application rollback; it addresses only Pi lifecycle images.
|
|
|
|
|
3. Stop with thothctl.
|
|
|
|
|
1. Keep the proxy closed and preserve .tht/<installation-id>/ recovery state.
|
|
|
|
|
2. Do not use tht pi rollback as the whole-application rollback; it addresses only Pi lifecycle images.
|
|
|
|
|
3. Stop with tht.
|
|
|
|
|
4. Return the source checkout to <OLD_SHA>, rebuild old application/operator artifacts, and start through the same descriptor.
|
|
|
|
|
5. Run update --check-only, status, doctor, health, Pi smoke, workspace diagnostics, and one harmless session.
|
|
|
|
|
6. For ambiguous recovery, leave maintenance active and follow pi maintenance status / pi maintenance recover --yes. Never delete volumes, selectors, or recovery files to force progress.
|
|
|
|
@@ -400,4 +406,3 @@ Merge only after PSD owner acceptance, exact-SHA evidence, no unresolved auth/wo
|
|
|
|
|
## Handoff checklist
|
|
|
|
|
|
|
|
|
|
Deliver the redacted report, local result/SHA, PSD candidate SHA/images, Authentik provider and group mapping confirmation, workspace validation/connection results, backup/rollback status, and an explicit READY TO MERGE or NOT READY TO MERGE decision.
|
|
|
|
|
|
|
|
|
|
