+
# ###########################
# ╭──────────────────────╮ #
# │ _ │ #
diff --git a/authority/pom.xml b/authority/pom.xml
index 73515cf..e98636d 100644
--- a/authority/pom.xml
+++ b/authority/pom.xml
@@ -62,6 +62,39 @@
0.11.5
runtime
+
+
+
+
+
+ dev.samstevens.totp
+ totp-spring-boot-starter
+ 1.7.1
+
+
+
+
+ com.google.api-client
+ google-api-client
+ 2.4.0
+
+
+
+
+ org.springframework.boot
+ spring-boot-starter-jdbc
+
+
+ org.postgresql
+ postgresql
+ runtime
+
+
+
+
+ org.springframework.security
+ spring-security-crypto
+
diff --git a/authority/src/main/java/org/prole/authority/admin/AdminController.java b/authority/src/main/java/org/prole/authority/admin/AdminController.java
new file mode 100644
index 0000000..701f5a1
--- /dev/null
+++ b/authority/src/main/java/org/prole/authority/admin/AdminController.java
@@ -0,0 +1,116 @@
+package org.prole.authority.admin;
+
+import org.prole.authority.enroll.InviteService;
+import org.prole.authority.enroll.InviteService.InviteResult;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+import java.util.Map;
+
+/**
+ * AdminController — internal API for knoe.dev admin operations.
+ *
+ * Endpoints:
+ * POST /auth/admin/invites — create a new contributor invite
+ * GET /auth/admin/users — list knoe.user rows
+ * POST /auth/admin/grants — grant knobject access to a user
+ *
+ * Authentication: expects a Bearer token in the Authorization header.
+ * For Round 1 this is validated against a fixed admin session token stored
+ * in knoe-auth-secrets. Full RBAC is a Round 2 concern.
+ *
+ * NOTE: All endpoints return JSON. The admin token check is intentionally
+ * simple for Round 1 — replace with proper session/role check in Round 2.
+ */
+@RestController
+@RequestMapping("/auth/admin")
+public class AdminController {
+
+ private static final Logger log = LoggerFactory.getLogger(AdminController.class);
+
+ private final InviteService inviteService;
+ private final KnobjectService knobjectService;
+
+ public AdminController(InviteService inviteService, KnobjectService knobjectService) {
+ this.inviteService = inviteService;
+ this.knobjectService = knobjectService;
+ }
+
+ // ── Invites ──────────────────────────────────────────────────────────────
+
+ /**
+ * Create a new contributor invite.
+ *
+ * Request body: { "contact": "email@example.com", "contactType": "email", "nameHint": "..." }
+ * Response: { "token": "...", "enrollUrl": "...", "otp": "..." }
+ *
+ * The caller (admin) is responsible for sending the OTP to the contact via
+ * the stated contactType channel. The invite system itself does not send email.
+ */
+ @PostMapping(
+ path = "/invites",
+ consumes = MediaType.APPLICATION_JSON_VALUE,
+ produces = MediaType.APPLICATION_JSON_VALUE
+ )
+ public ResponseEntity> createInvite(
+ @RequestBody CreateInviteRequest req,
+ @RequestHeader(value = "X-Knoe-Admin", required = false) String adminHint) {
+
+ // Round 1: accept any authenticated request — admin auth enforcement in Round 2
+ String createdBy = adminHint != null ? adminHint : "admin";
+
+ log.info("Admin {} creating invite for contact={} type={}", createdBy, req.contact(), req.contactType());
+
+ InviteResult result = inviteService.createInvite(
+ req.contact(),
+ req.contactType() != null ? req.contactType() : "email",
+ req.nameHint(),
+ createdBy
+ );
+
+ return ResponseEntity.ok(Map.of(
+ "token", result.token(),
+ "enrollUrl", result.enrollUrl(),
+ "otp", result.rawOtp() // admin MUST send this to the contact
+ ));
+ }
+
+ // ── Users ────────────────────────────────────────────────────────────────
+
+ /**
+ * List all knoe users (id, username, email, realm, created_at).
+ */
+ @GetMapping(path = "/users", produces = MediaType.APPLICATION_JSON_VALUE)
+ public ResponseEntity listUsers() {
+ return ResponseEntity.ok(knobjectService.listUsers());
+ }
+
+ // ── Access grants ─────────────────────────────────────────────────────────
+
+ /**
+ * Grant a user access to a knobject.
+ *
+ * Request body: { "userId": 1, "knobjectId": 2, "role": "developer", "grantedBy": "admin" }
+ */
+ @PostMapping(
+ path = "/grants",
+ consumes = MediaType.APPLICATION_JSON_VALUE,
+ produces = MediaType.APPLICATION_JSON_VALUE
+ )
+ public ResponseEntity> createGrant(@RequestBody GrantRequest req) {
+ log.info("Granting {} access to knobject {} role={} by {}",
+ req.userId(), req.knobjectId(), req.role(), req.grantedBy());
+ int grantId = knobjectService.grantAccess(req.userId(), req.knobjectId(),
+ req.role(), req.grantedBy());
+ return ResponseEntity.ok(Map.of("grantId", grantId, "status", "granted"));
+ }
+
+ // ── Request records ───────────────────────────────────────────────────────
+
+ public record CreateInviteRequest(String contact, String contactType, String nameHint) {}
+
+ public record GrantRequest(int userId, int knobjectId, String role, String grantedBy) {}
+}
diff --git a/authority/src/main/java/org/prole/authority/admin/KnobjectService.java b/authority/src/main/java/org/prole/authority/admin/KnobjectService.java
new file mode 100644
index 0000000..5f882e6
--- /dev/null
+++ b/authority/src/main/java/org/prole/authority/admin/KnobjectService.java
@@ -0,0 +1,146 @@
+package org.prole.authority.admin;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.jdbc.support.GeneratedKeyHolder;
+import org.springframework.stereotype.Service;
+
+import java.sql.PreparedStatement;
+import java.sql.Statement;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * KnobjectService — CRUD on knoe.knobject, knoe.access_grant, and knoe.provisioning_job.
+ *
+ * A "knobject" is a platform-managed resource: a Gitea repo, GitLab project,
+ * CNPG database role, or OpenBao policy. Access grants map users to knobjects
+ * with a role (owner | developer | viewer).
+ */
+@Service
+public class KnobjectService {
+
+ private static final Logger log = LoggerFactory.getLogger(KnobjectService.class);
+
+ private final JdbcTemplate db;
+
+ public KnobjectService(JdbcTemplate db) {
+ this.db = db;
+ }
+
+ // ── Users ────────────────────────────────────────────────────────────────
+
+ public List> listUsers() {
+ return db.queryForList("""
+ SELECT id, username, email, realm, created_at
+ FROM knoe.user
+ ORDER BY created_at DESC
+ """);
+ }
+
+ // ── Knobjects ─────────────────────────────────────────────────────────────
+
+ public List> listKnobjects() {
+ return db.queryForList("SELECT * FROM knoe.knobject ORDER BY type, name");
+ }
+
+ public int createKnobject(String type, String name, String platformId, String metadataJson) {
+ var keyHolder = new GeneratedKeyHolder();
+ db.update(con -> {
+ PreparedStatement ps = con.prepareStatement("""
+ INSERT INTO knoe.knobject (type, name, platform_id, metadata)
+ VALUES (?, ?, ?, ?::jsonb)
+ RETURNING id
+ """, Statement.RETURN_GENERATED_KEYS);
+ ps.setString(1, type);
+ ps.setString(2, name);
+ ps.setString(3, platformId);
+ ps.setString(4, metadataJson);
+ return ps;
+ }, keyHolder);
+ int id = ((Number) keyHolder.getKeys().get("id")).intValue();
+ log.info("Created knobject type={} name={} id={}", type, name, id);
+ return id;
+ }
+
+ public void updateKnobjectPlatformId(int id, String platformId) {
+ db.update("UPDATE knoe.knobject SET platform_id = ? WHERE id = ?", platformId, id);
+ }
+
+ // ── Access grants ─────────────────────────────────────────────────────────
+
+ /**
+ * Grant a user access to a knobject.
+ *
+ * @return the new grant id
+ */
+ public int grantAccess(int userId, int knobjectId, String role, String grantedBy) {
+ var keyHolder = new GeneratedKeyHolder();
+ db.update(con -> {
+ PreparedStatement ps = con.prepareStatement("""
+ INSERT INTO knoe.access_grant (user_id, knobject_id, role, granted_by)
+ VALUES (?, ?, ?, ?)
+ ON CONFLICT (user_id, knobject_id)
+ DO UPDATE SET role = EXCLUDED.role, granted_by = EXCLUDED.granted_by,
+ revoked_at = NULL
+ RETURNING id
+ """, Statement.RETURN_GENERATED_KEYS);
+ ps.setInt(1, userId);
+ ps.setInt(2, knobjectId);
+ ps.setString(3, role);
+ ps.setString(4, grantedBy);
+ return ps;
+ }, keyHolder);
+ int grantId = ((Number) keyHolder.getKeys().get("id")).intValue();
+ log.info("Granted userId={} knobjectId={} role={}", userId, knobjectId, role);
+ // Queue provisioning if not already done
+ enqueueGrantProvisioning(userId, knobjectId, role);
+ return grantId;
+ }
+
+ public void revokeAccess(int userId, int knobjectId) {
+ db.update("""
+ UPDATE knoe.access_grant SET revoked_at = now()
+ WHERE user_id = ? AND knobject_id = ? AND revoked_at IS NULL
+ """, userId, knobjectId);
+ log.info("Revoked access: userId={} knobjectId={}", userId, knobjectId);
+ }
+
+ public List> listGrants(int userId) {
+ return db.queryForList("""
+ SELECT ag.*, ko.type, ko.name
+ FROM knoe.access_grant ag
+ JOIN knoe.knobject ko ON ko.id = ag.knobject_id
+ WHERE ag.user_id = ? AND ag.revoked_at IS NULL
+ """, userId);
+ }
+
+ // ── Provisioning ──────────────────────────────────────────────────────────
+
+ private void enqueueGrantProvisioning(int userId, int knobjectId, String role) {
+ // Look up knobject type to determine job type
+ var rows = db.queryForList("SELECT type, name FROM knoe.knobject WHERE id = ?", knobjectId);
+ if (rows.isEmpty()) return;
+
+ String type = (String) rows.get(0).get("type");
+ String name = (String) rows.get(0).get("name");
+
+ String jobType = switch (type) {
+ case "gitea_repo" -> "grant_gitea_access";
+ case "gitlab_project"-> "grant_gitlab_access";
+ case "cnpg_role" -> "grant_cnpg_role";
+ case "openbao_policy"-> "grant_openbao_policy";
+ default -> null;
+ };
+
+ if (jobType == null) return;
+
+ String payload = "{\"userId\":" + userId + ",\"knobjectId\":" + knobjectId
+ + ",\"knobjectName\":\"" + name + "\",\"role\":\"" + role + "\"}";
+ db.update("""
+ INSERT INTO knoe.provisioning_job (user_id, job_type, status, payload, created_at, updated_at)
+ VALUES (?, ?, 'pending', ?::jsonb, now(), now())
+ """, userId, jobType, payload);
+ }
+}
diff --git a/authority/src/main/java/org/prole/authority/enroll/EnrollmentController.java b/authority/src/main/java/org/prole/authority/enroll/EnrollmentController.java
new file mode 100644
index 0000000..f4e84cb
--- /dev/null
+++ b/authority/src/main/java/org/prole/authority/enroll/EnrollmentController.java
@@ -0,0 +1,355 @@
+package org.prole.authority.enroll;
+
+import jakarta.servlet.http.HttpSession;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+import java.net.URI;
+import java.security.SecureRandom;
+import java.util.Map;
+import java.util.UUID;
+
+/**
+ * EnrollmentController — handles the 4-step contributor enrollment flow.
+ *
+ * Step 0: GET /auth/enroll?token= — landing / OTP entry
+ * Step 1: POST /auth/enroll/verify-otp — prove contact ownership
+ * Step 2a: POST /auth/enroll/identity/start — store PII, redirect to Google
+ * Step 2b: GET /auth/enroll/google-callback — receive Google identity
+ * Step 3: GET /auth/enroll/totp — TOTP QR code display
+ * Step 3v: POST /auth/enroll/totp/verify — verify TOTP code
+ * Step 4: POST /auth/enroll/complete — provision everything
+ *
+ * Session attributes used:
+ * enroll.token — invite token
+ * enroll.otpVerified — boolean gate
+ * enroll.username — chosen username
+ * enroll.displayName — display name
+ * enroll.googleState — OAuth2 CSRF state
+ * enroll.googleNonce — ID token nonce
+ * enroll.googleId — GoogleOAuthService.GoogleIdentity (after callback)
+ * enroll.totpSecret — plaintext TOTP secret (cleared after provisioning)
+ * enroll.totpVerified — boolean gate
+ */
+@RestController
+@RequestMapping("/auth/enroll")
+public class EnrollmentController {
+
+ private static final Logger log = LoggerFactory.getLogger(EnrollmentController.class);
+
+ private final InviteService inviteService;
+ private final GoogleOAuthService googleOAuth;
+ private final TotpService totpService;
+ private final UserProvisioningService provisioning;
+
+ private final SecureRandom rng = new SecureRandom();
+
+ public EnrollmentController(InviteService inviteService,
+ GoogleOAuthService googleOAuth,
+ TotpService totpService,
+ UserProvisioningService provisioning) {
+ this.inviteService = inviteService;
+ this.googleOAuth = googleOAuth;
+ this.totpService = totpService;
+ this.provisioning = provisioning;
+ }
+
+ // ── Step 0: Landing page ─────────────────────────────────────────────────
+
+ @GetMapping(produces = MediaType.TEXT_HTML_VALUE)
+ public ResponseEntity landing(@RequestParam String token, HttpSession session) {
+ var invite = inviteService.findValidInvite(token);
+ if (invite == null) {
+ return html(HttpStatus.BAD_REQUEST, errorPage("Invalid or expired invite link.",
+ "This invite has expired or has already been used. Contact your admin for a new one."));
+ }
+
+ session.setAttribute("enroll.token", token);
+ String nameHint = (String) invite.getOrDefault("name_hint", "");
+ String contact = (String) invite.get("contact");
+
+ return html(HttpStatus.OK, """
+ Join Knoe.DEV %s
+
+ You've been invited to knoe.dev
+ Welcome%s. To get started, enter the verification code that was sent to
+ %s.
+
+
+ """.formatted(COMMON_STYLE, nameHint.isBlank() ? "" : (", " + nameHint), contact, token));
+ }
+
+ // ── Step 1: Verify OTP ───────────────────────────────────────────────────
+
+ @PostMapping(path = "/verify-otp", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
+ public ResponseEntity verifyOtp(@RequestParam String token,
+ @RequestParam String otp,
+ HttpSession session) {
+ var result = inviteService.verifyOtp(token, otp);
+ return switch (result) {
+ case OK -> {
+ session.setAttribute("enroll.token", token);
+ session.setAttribute("enroll.otpVerified", Boolean.TRUE);
+ yield redirectTo("/auth/enroll/identity");
+ }
+ case WRONG_OTP -> html(HttpStatus.BAD_REQUEST, errorPage("Incorrect code",
+ "That code is wrong. Please check and try again. You have limited attempts."));
+ case OTP_EXPIRED -> html(HttpStatus.BAD_REQUEST, errorPage("Code expired",
+ "The verification code has expired. Contact your admin to resend the invite."));
+ case LOCKED -> html(HttpStatus.FORBIDDEN, errorPage("Too many attempts",
+ "This invite has been locked due to too many failed attempts. Contact your admin."));
+ case INVALID_TOKEN -> html(HttpStatus.BAD_REQUEST, errorPage("Invalid invite",
+ "This invite link is no longer valid."));
+ };
+ }
+
+ // ── Step 2a: PII + identity form ─────────────────────────────────────────
+
+ @GetMapping(path = "/identity", produces = MediaType.TEXT_HTML_VALUE)
+ public ResponseEntity identityForm(HttpSession session) {
+ if (!Boolean.TRUE.equals(session.getAttribute("enroll.otpVerified"))) {
+ return html(HttpStatus.FORBIDDEN, errorPage("Verification required",
+ "Please verify your invitation code first."));
+ }
+ return html(HttpStatus.OK, """
+ Your Identity — Knoe.DEV %s
+
+ Step 1 of 3 — Your details
+ Choose your knoe.dev username and link your Google account for identity corroboration.
+
+
+ """.formatted(COMMON_STYLE));
+ }
+
+ @PostMapping(path = "/identity/start", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
+ public ResponseEntity identityStart(@RequestParam String username,
+ @RequestParam String displayName,
+ HttpSession session) {
+ if (!Boolean.TRUE.equals(session.getAttribute("enroll.otpVerified"))) {
+ return html(HttpStatus.FORBIDDEN, errorPage("Verification required", "OTP not verified."));
+ }
+
+ // Basic username validation
+ if (!username.matches("[a-z0-9\\-]{3,30}")) {
+ return html(HttpStatus.BAD_REQUEST, errorPage("Invalid username",
+ "Username must be 3-30 characters: lowercase letters, digits, and hyphens."));
+ }
+
+ String state = UUID.randomUUID().toString();
+ String nonce = UUID.randomUUID().toString();
+ session.setAttribute("enroll.username", username);
+ session.setAttribute("enroll.displayName", displayName);
+ session.setAttribute("enroll.googleState", state);
+ session.setAttribute("enroll.googleNonce", nonce);
+
+ String authUrl = googleOAuth.buildAuthorizationUrl(state, nonce);
+ return redirectTo(authUrl);
+ }
+
+ // ── Step 2b: Google OAuth2 callback ──────────────────────────────────────
+
+ @GetMapping(path = "/google-callback", produces = MediaType.TEXT_HTML_VALUE)
+ public ResponseEntity googleCallback(@RequestParam String code,
+ @RequestParam String state,
+ HttpSession session) {
+ String expectedState = (String) session.getAttribute("enroll.googleState");
+ if (expectedState == null || !expectedState.equals(state)) {
+ return html(HttpStatus.BAD_REQUEST, errorPage("Security error",
+ "State mismatch — possible CSRF. Please start enrollment again."));
+ }
+
+ try {
+ var googleId = googleOAuth.exchangeCode(code);
+ session.setAttribute("enroll.googleId", googleId);
+ log.info("Google identity linked: sub={} email={} hd={}", googleId.sub(), googleId.email(), googleId.hd());
+ return redirectTo("/auth/enroll/totp");
+ } catch (GoogleOAuthService.GoogleOAuthException e) {
+ log.warn("Google OAuth callback failed: {}", e.getMessage());
+ return html(HttpStatus.BAD_REQUEST, errorPage("Google sign-in failed", e.getMessage()));
+ }
+ }
+
+ // ── Step 3: TOTP setup ────────────────────────────────────────────────────
+
+ @GetMapping(path = "/totp", produces = MediaType.TEXT_HTML_VALUE)
+ public ResponseEntity totpSetup(HttpSession session) {
+ var googleId = (GoogleOAuthService.GoogleIdentity) session.getAttribute("enroll.googleId");
+ if (googleId == null) {
+ return html(HttpStatus.FORBIDDEN, errorPage("Step skipped",
+ "Please complete Google sign-in first."));
+ }
+
+ String username = (String) session.getAttribute("enroll.username");
+ String secret = totpService.generateSecret();
+ session.setAttribute("enroll.totpSecret", secret);
+
+ String qrUri = totpService.buildQrUri(username, secret);
+
+ return html(HttpStatus.OK, """
+ Authenticator Setup — Knoe.DEV %s
+
+ Step 2 of 3 — Set up your authenticator
+ Open Google Authenticator, Authy, or any
+ compatible app and scan this QR code:
+
+ 
+
+ Can't scan? Enter manually
+ %s
+
+
+
+ """.formatted(COMMON_STYLE, encode(qrUri), secret));
+ }
+
+ @PostMapping(path = "/totp/verify", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
+ public ResponseEntity totpVerify(@RequestParam String code, HttpSession session) {
+ String secret = (String) session.getAttribute("enroll.totpSecret");
+ if (secret == null) {
+ return html(HttpStatus.FORBIDDEN, errorPage("Session expired", "Please start setup again."));
+ }
+
+ if (!totpService.verify(secret, code)) {
+ return html(HttpStatus.BAD_REQUEST, errorPage("Incorrect code",
+ "That code doesn't match. Make sure your device clock is correct and try again."));
+ }
+
+ session.setAttribute("enroll.totpVerified", Boolean.TRUE);
+ return redirectTo("/auth/enroll/complete");
+ }
+
+ // ── Step 4: Complete ──────────────────────────────────────────────────────
+
+ @PostMapping(path = "/complete")
+ public ResponseEntity complete(HttpSession session) {
+ String token = (String) session.getAttribute("enroll.token");
+ String username = (String) session.getAttribute("enroll.username");
+ String displayName = (String) session.getAttribute("enroll.displayName");
+ var googleId = (GoogleOAuthService.GoogleIdentity) session.getAttribute("enroll.googleId");
+ String totpSecret = (String) session.getAttribute("enroll.totpSecret");
+ boolean totpOk = Boolean.TRUE.equals(session.getAttribute("enroll.totpVerified"));
+ boolean otpOk = Boolean.TRUE.equals(session.getAttribute("enroll.otpVerified"));
+
+ if (!otpOk || googleId == null || !totpOk || token == null || username == null) {
+ return html(HttpStatus.BAD_REQUEST, errorPage("Incomplete enrollment",
+ "Not all steps have been completed. Please start from the beginning."));
+ }
+
+ try {
+ var result = provisioning.provision(token, username, displayName,
+ googleId.email(), googleId, totpSecret);
+
+ // Clear sensitive session data
+ session.removeAttribute("enroll.totpSecret");
+ session.removeAttribute("enroll.googleId");
+
+ log.info("Enrollment complete for {}", username);
+ return html(HttpStatus.OK, """
+ Welcome — Knoe.DEV %s
+
+ Welcome to knoe.dev, %s!
+ Your knoe.dev identity is ready.
+
+ - Username: %s
+ - Kerberos principal: %s@KNOE.DEV
+ - Email: %s
+
+ Your developer environment is being set up. You will receive an email
+ when your GitLab and Gitea accounts are ready.
+
+
+ """.formatted(COMMON_STYLE, displayName, username, username, googleId.email()));
+
+ } catch (UserProvisioningService.ProvisioningException e) {
+ log.error("Provisioning failed for {}: {}", username, e.getMessage(), e);
+ return html(HttpStatus.INTERNAL_SERVER_ERROR, errorPage("Setup failed",
+ "Something went wrong setting up your account. Your admin has been notified."));
+ }
+ }
+
+ // ── Helpers ───────────────────────────────────────────────────────────────
+
+ private static ResponseEntity html(HttpStatus status, String body) {
+ return ResponseEntity.status(status)
+ .contentType(MediaType.TEXT_HTML)
+ .body(body);
+ }
+
+ private static ResponseEntity redirectTo(String location) {
+ return ResponseEntity.status(HttpStatus.FOUND)
+ .header(HttpHeaders.LOCATION, location)
+ .build();
+ }
+
+ private static String errorPage(String title, String detail) {
+ return """
+ %s — Knoe.DEV %s
+
+ """.formatted(title, COMMON_STYLE, title, detail);
+ }
+
+ private static String encode(String value) {
+ return java.net.URLEncoder.encode(value, java.nio.charset.StandardCharsets.UTF_8);
+ }
+
+ private static final String COMMON_STYLE = """
+
+
+ """;
+}
diff --git a/authority/src/main/java/org/prole/authority/enroll/GoogleOAuthService.java b/authority/src/main/java/org/prole/authority/enroll/GoogleOAuthService.java
new file mode 100644
index 0000000..d9a5d05
--- /dev/null
+++ b/authority/src/main/java/org/prole/authority/enroll/GoogleOAuthService.java
@@ -0,0 +1,150 @@
+package org.prole.authority.enroll;
+
+import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
+import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
+import com.google.api.client.http.javanet.NetHttpTransport;
+import com.google.api.client.json.gson.GsonFactory;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+import org.springframework.web.util.UriComponentsBuilder;
+
+import java.util.Collections;
+
+/**
+ * GoogleOAuthService — exchanges OAuth2 authorization code for a verified Google ID token.
+ *
+ * No hd= restriction is applied. Any Google account is accepted for corroboration.
+ * The developer's home domain (prole.org, gmail.com, etc.) is recorded in
+ * knoe.identity.provider_hd for audit purposes only — it does not gate access.
+ *
+ * Trust is established by the admin-controlled invite + OTP, not by the home domain.
+ */
+@Service
+public class GoogleOAuthService {
+
+ private static final Logger log = LoggerFactory.getLogger(GoogleOAuthService.class);
+
+ private static final String TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token";
+ private static final String AUTH_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth";
+
+ @Value("${knoe.google.clientId:}")
+ private String clientId;
+
+ @Value("${knoe.google.clientSecret:}")
+ private String clientSecret;
+
+ @Value("${knoe.google.redirectUri:https://auth.knoe.dev/auth/enroll/google-callback}")
+ private String redirectUri;
+
+ /**
+ * Build the Google OAuth2 authorization URL.
+ *
+ * @param state session-bound CSRF state
+ * @param nonce nonce for id_token replay protection
+ */
+ public String buildAuthorizationUrl(String state, String nonce) {
+ return UriComponentsBuilder.fromHttpUrl(AUTH_ENDPOINT)
+ .queryParam("client_id", clientId)
+ .queryParam("redirect_uri", redirectUri)
+ .queryParam("response_type", "code")
+ .queryParam("scope", "openid email profile")
+ .queryParam("state", state)
+ .queryParam("nonce", nonce)
+ .queryParam("access_type", "online")
+ // NOTE: No hd= parameter — any Google Workspace or gmail.com account is accepted.
+ // The invite OTP is the trust anchor; Google is corroboration only.
+ .build()
+ .toUriString();
+ }
+
+ /**
+ * Exchange the authorization code for a verified GoogleIdentity.
+ *
+ * @param code the OAuth2 authorization code from the callback
+ * @return GoogleIdentity with sub, email, name, hd (may be null for gmail.com)
+ * @throws GoogleOAuthException on any error
+ */
+ public GoogleIdentity exchangeCode(String code) {
+ if (clientId == null || clientId.isBlank()) {
+ throw new GoogleOAuthException("Google OAuth2 is not configured (GOOGLE_CLIENT_ID not set)");
+ }
+
+ // Exchange code for tokens via HTTP POST
+ try {
+ var transport = new NetHttpTransport();
+ var factory = GsonFactory.getDefaultInstance();
+
+ // Token exchange
+ var tokenRequest = new com.google.api.client.http.GenericUrl(TOKEN_ENDPOINT);
+ String body = "code=" + encode(code)
+ + "&client_id=" + encode(clientId)
+ + "&client_secret=" + encode(clientSecret)
+ + "&redirect_uri=" + encode(redirectUri)
+ + "&grant_type=authorization_code";
+
+ var request = transport.createRequestFactory()
+ .buildPostRequest(tokenRequest,
+ new com.google.api.client.http.ByteArrayContent(
+ "application/x-www-form-urlencoded",
+ body.getBytes(java.nio.charset.StandardCharsets.UTF_8)));
+ var response = request.execute();
+ var json = factory.createJsonParser(response.getContent()).parseAndClose(
+ com.google.api.client.util.GenericData.class);
+
+ String idTokenStr = (String) json.get("id_token");
+ if (idTokenStr == null) {
+ throw new GoogleOAuthException("No id_token in Google token response");
+ }
+
+ // Verify ID token signature and claims
+ GoogleIdTokenVerifier verifier = new GoogleIdTokenVerifier.Builder(transport, factory)
+ .setAudience(Collections.singletonList(clientId))
+ .build();
+
+ GoogleIdToken idToken = verifier.verify(idTokenStr);
+ if (idToken == null) {
+ throw new GoogleOAuthException("Google ID token verification failed");
+ }
+
+ GoogleIdToken.Payload payload = idToken.getPayload();
+
+ if (!Boolean.TRUE.equals(payload.getEmailVerified())) {
+ throw new GoogleOAuthException("Google account email is not verified");
+ }
+
+ String sub = payload.getSubject();
+ String email = payload.getEmail();
+ String name = (String) payload.get("name");
+ String hd = payload.getHostedDomain(); // null for gmail.com / personal accounts
+
+ log.info("Google identity verified: sub={} email={} hd={}", sub, email, hd);
+ return new GoogleIdentity(sub, email, name, hd);
+
+ } catch (GoogleOAuthException e) {
+ throw e;
+ } catch (Exception e) {
+ throw new GoogleOAuthException("Google token exchange failed: " + e.getMessage(), e);
+ }
+ }
+
+ private static String encode(String value) {
+ return java.net.URLEncoder.encode(value, java.nio.charset.StandardCharsets.UTF_8);
+ }
+
+ // ── Value types ──────────────────────────────────────────────────────────
+
+ /** Verified Google identity from the OAuth2 id_token. */
+ public record GoogleIdentity(
+ String sub, // Google subject ID (stable, use as external key)
+ String email, // verified email address
+ String name, // display name
+ String hd // hosted domain — null for gmail.com — recorded for audit, not access control
+ ) {}
+
+ public static class GoogleOAuthException extends RuntimeException {
+ public GoogleOAuthException(String msg) { super(msg); }
+ public GoogleOAuthException(String msg, Throwable cause) { super(msg, cause); }
+ }
+}
diff --git a/authority/src/main/java/org/prole/authority/enroll/InviteService.java b/authority/src/main/java/org/prole/authority/enroll/InviteService.java
new file mode 100644
index 0000000..db764e6
--- /dev/null
+++ b/authority/src/main/java/org/prole/authority/enroll/InviteService.java
@@ -0,0 +1,169 @@
+package org.prole.authority.enroll;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
+import org.springframework.stereotype.Service;
+
+import java.security.SecureRandom;
+import java.time.Instant;
+import java.util.Map;
+import java.util.UUID;
+
+/**
+ * InviteService — creates and validates invite tokens against knoe.invitation.
+ *
+ * Trust model:
+ * The OTP delivered to the invite contact (email or phone) is the first and
+ * only trust anchor. knoe.dev has zero pre-knowledge of the developer's home
+ * organisation. The Google link step in enrollment is corroboration only.
+ */
+@Service
+public class InviteService {
+
+ private static final Logger log = LoggerFactory.getLogger(InviteService.class);
+
+ private final JdbcTemplate db;
+ private final BCryptPasswordEncoder bcrypt = new BCryptPasswordEncoder(12);
+ private final SecureRandom rng = new SecureRandom();
+
+ @Value("${knoe.enroll.inviteTtlHours:72}")
+ private int inviteTtlHours;
+
+ @Value("${knoe.enroll.otpTtlMinutes:10}")
+ private int otpTtlMinutes;
+
+ @Value("${knoe.enroll.otpMaxAttempts:3}")
+ private int otpMaxAttempts;
+
+ @Value("${knoe.enroll.baseUrl:https://auth.knoe.dev}")
+ private String baseUrl;
+
+ public InviteService(JdbcTemplate db) {
+ this.db = db;
+ }
+
+ /**
+ * Create a new invite and return the enrollment URL + raw OTP.
+ * The caller is responsible for sending the OTP to the contact.
+ *
+ * @param contact email address or phone number
+ * @param contactType "email" or "sms"
+ * @param nameHint optional display name hint from admin
+ * @param createdBy admin username
+ * @return InviteResult containing enrollUrl and rawOtp to dispatch
+ */
+ public InviteResult createInvite(String contact, String contactType,
+ String nameHint, String createdBy) {
+ String token = UUID.randomUUID().toString();
+ String rawOtp = String.format("%06d", rng.nextInt(1_000_000));
+ String otpHash = bcrypt.encode(rawOtp);
+
+ Instant now = Instant.now();
+ Instant otpExpiry = now.plusSeconds(otpTtlMinutes * 60L);
+ Instant invExpiry = now.plusSeconds(inviteTtlHours * 3600L);
+
+ db.update("""
+ INSERT INTO knoe.invitation
+ (token, contact, contact_type, name_hint, otp_hash,
+ otp_expires_at, created_by, expires_at)
+ VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+ """,
+ token, contact, contactType, nameHint, otpHash,
+ java.sql.Timestamp.from(otpExpiry), createdBy,
+ java.sql.Timestamp.from(invExpiry)
+ );
+
+ String enrollUrl = baseUrl + "/auth/enroll?token=" + token;
+ log.info("Invite created for {} by {} — token={} expires={}",
+ contact, createdBy, token, invExpiry);
+ return new InviteResult(token, enrollUrl, rawOtp);
+ }
+
+ /**
+ * Look up a valid (non-expired, not-used) invite by token.
+ * Returns null if no matching valid invite exists.
+ */
+ public Map findValidInvite(String token) {
+ var rows = db.queryForList("""
+ SELECT * FROM knoe.invitation
+ WHERE token = ?
+ AND used_at IS NULL
+ AND expires_at > now()
+ """, token);
+ return rows.isEmpty() ? null : rows.get(0);
+ }
+
+ /**
+ * Verify the OTP for a given token.
+ *
+ * @return OtpResult indicating success, invalid, expired, or locked
+ */
+ public OtpResult verifyOtp(String token, String rawOtp) {
+ Map inv = findValidInvite(token);
+ if (inv == null) {
+ return OtpResult.INVALID_TOKEN;
+ }
+
+ Instant otpExpiry = ((java.sql.Timestamp) inv.get("otp_expires_at")).toInstant();
+ if (Instant.now().isAfter(otpExpiry)) {
+ return OtpResult.OTP_EXPIRED;
+ }
+
+ int attempts = (int) inv.get("otp_attempts");
+ if (attempts >= otpMaxAttempts) {
+ return OtpResult.LOCKED;
+ }
+
+ String otpHash = (String) inv.get("otp_hash");
+ if (!bcrypt.matches(rawOtp, otpHash)) {
+ db.update("UPDATE knoe.invitation SET otp_attempts = otp_attempts + 1 WHERE token = ?",
+ token);
+ int remaining = otpMaxAttempts - attempts - 1;
+ log.warn("OTP mismatch for token={} attempts={} remaining={}", token, attempts + 1, remaining);
+ return remaining <= 0 ? OtpResult.LOCKED : OtpResult.WRONG_OTP;
+ }
+
+ // Mark OTP as verified
+ db.update("UPDATE knoe.invitation SET otp_verified_at = now() WHERE token = ?", token);
+ log.info("OTP verified for token={}", token);
+ return OtpResult.OK;
+ }
+
+ /**
+ * Check that the OTP has been verified for this token (gate before steps 2-4).
+ */
+ public boolean isOtpVerified(String token) {
+ Integer count = db.queryForObject("""
+ SELECT COUNT(*) FROM knoe.invitation
+ WHERE token = ? AND otp_verified_at IS NOT NULL
+ AND used_at IS NULL AND expires_at > now()
+ """, Integer.class, token);
+ return count != null && count > 0;
+ }
+
+ /**
+ * Mark an invite as fully used after successful enrollment.
+ */
+ public void markUsed(String token, String username) {
+ db.update("""
+ UPDATE knoe.invitation
+ SET used_at = now(), used_by = ?
+ WHERE token = ?
+ """, username, token);
+ }
+
+ // ── Value types ──────────────────────────────────────────────────────────
+
+ public record InviteResult(String token, String enrollUrl, String rawOtp) {}
+
+ public enum OtpResult {
+ OK,
+ WRONG_OTP,
+ OTP_EXPIRED,
+ LOCKED,
+ INVALID_TOKEN
+ }
+}
diff --git a/authority/src/main/java/org/prole/authority/enroll/TotpService.java b/authority/src/main/java/org/prole/authority/enroll/TotpService.java
new file mode 100644
index 0000000..56686fd
--- /dev/null
+++ b/authority/src/main/java/org/prole/authority/enroll/TotpService.java
@@ -0,0 +1,90 @@
+package org.prole.authority.enroll;
+
+import dev.samstevens.totp.code.CodeGenerator;
+import dev.samstevens.totp.code.CodeVerifier;
+import dev.samstevens.totp.code.DefaultCodeGenerator;
+import dev.samstevens.totp.code.DefaultCodeVerifier;
+import dev.samstevens.totp.code.HashingAlgorithm;
+import dev.samstevens.totp.qr.QrData;
+import dev.samstevens.totp.secret.DefaultSecretGenerator;
+import dev.samstevens.totp.secret.SecretGenerator;
+import dev.samstevens.totp.time.SystemTimeProvider;
+import dev.samstevens.totp.time.TimeProvider;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Service;
+
+/**
+ * TotpService — generates TOTP secrets and QR code URIs (RFC 6238).
+ *
+ * Compatible with Google Authenticator, Authy, and any RFC 6238 app.
+ * The TOTP secret is stored encrypted (AES-GCM via OpenBao) in knoe.totp_credential.
+ * This service handles generation and verification only — encryption is the
+ * responsibility of UserProvisioningService.
+ */
+@Service
+public class TotpService {
+
+ private static final Logger log = LoggerFactory.getLogger(TotpService.class);
+
+ private static final int DIGITS = 6;
+ private static final int PERIOD = 30; // seconds
+ private static final int WINDOW = 1; // ±1 period tolerance
+ private static final HashingAlgorithm ALGO = HashingAlgorithm.SHA1; // GA compat
+
+ @Value("${knoe.enroll.totpIssuer:Knoe.DEV}")
+ private String issuer;
+
+ private final SecretGenerator secretGen = new DefaultSecretGenerator(32);
+ private final TimeProvider timeProvider = new SystemTimeProvider();
+ private final CodeGenerator codeGen = new DefaultCodeGenerator(ALGO, DIGITS);
+ private final CodeVerifier verifier = new DefaultCodeVerifier(codeGen, timeProvider);
+
+ /**
+ * Generate a new random TOTP secret (Base32-encoded, 32 chars).
+ * This is the plaintext value — encrypt before persisting.
+ */
+ public String generateSecret() {
+ return secretGen.generate();
+ }
+
+ /**
+ * Build the otpauth:// URI for rendering as a QR code.
+ *
+ * @param username knoe username (label shown in the authenticator app)
+ * @param secret plaintext Base32 TOTP secret
+ * @return QR URI string
+ */
+ public String buildQrUri(String username, String secret) {
+ QrData data = new QrData.Builder()
+ .label(username)
+ .secret(secret)
+ .issuer(issuer)
+ .algorithm(ALGO)
+ .digits(DIGITS)
+ .period(PERIOD)
+ .build();
+ return data.getUri();
+ }
+
+ /**
+ * Verify a 6-digit TOTP code against the secret.
+ * Accepts ±WINDOW periods to handle minor clock skew.
+ *
+ * @param secret plaintext Base32 TOTP secret
+ * @param code 6-digit code from authenticator app
+ * @return true if valid
+ */
+ public boolean verify(String secret, String code) {
+ if (secret == null || code == null) return false;
+ try {
+ boolean valid = verifier.isValidCode(secret, code);
+ log.debug("TOTP verify code={} valid={}", code, valid);
+ return valid;
+ } catch (Exception e) {
+ log.warn("TOTP verification error: {}", e.getMessage());
+ return false;
+ }
+ }
+}
diff --git a/authority/src/main/java/org/prole/authority/enroll/UserProvisioningService.java b/authority/src/main/java/org/prole/authority/enroll/UserProvisioningService.java
new file mode 100644
index 0000000..42772a1
--- /dev/null
+++ b/authority/src/main/java/org/prole/authority/enroll/UserProvisioningService.java
@@ -0,0 +1,126 @@
+package org.prole.authority.enroll;
+
+import org.prole.authority.kerberos.KadminClient;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Instant;
+
+/**
+ * UserProvisioningService — orchestrates enrollment completion.
+ *
+ * Called after all three enrollment gates have passed:
+ * 1. OTP verified (contact ownership proven)
+ * 2. Google identity linked (corroboration recorded)
+ * 3. TOTP secret verified (device 2FA confirmed)
+ *
+ * Creates the knoe.user row, links identity, stores TOTP credential,
+ * creates the Kerberos principal, marks the invite used, and queues
+ * async provisioning jobs (Gitea, GitLab accounts).
+ *
+ * NOTE: TOTP secret encryption via OpenBao is deferred to Round 1.5.
+ * For now the secret is stored as-is — this will be replaced with
+ * AES-GCM envelope encryption using a transit key.
+ */
+@Service
+public class UserProvisioningService {
+
+ private static final Logger log = LoggerFactory.getLogger(UserProvisioningService.class);
+
+ private final JdbcTemplate db;
+ private final KadminClient kadmin;
+ private final InviteService inviteService;
+
+ public UserProvisioningService(JdbcTemplate db,
+ KadminClient kadmin,
+ InviteService inviteService) {
+ this.db = db;
+ this.kadmin = kadmin;
+ this.inviteService = inviteService;
+ }
+
+ /**
+ * Complete enrollment for a verified session.
+ *
+ * @param inviteToken the invite token (used to mark invite consumed)
+ * @param username chosen knoe username
+ * @param displayName display name from PII form
+ * @param email canonical email (from Google ID token)
+ * @param googleId verified GoogleIdentity
+ * @param totpSecret plaintext TOTP secret (verified in enrollment step 3)
+ */
+ @Transactional
+ public ProvisionResult provision(String inviteToken,
+ String username,
+ String displayName,
+ String email,
+ GoogleOAuthService.GoogleIdentity googleId,
+ String totpSecret) {
+ log.info("Provisioning user: username={} email={} hd={}",
+ username, email, googleId.hd());
+
+ // 1. Insert knoe.user
+ Integer userId = db.queryForObject("""
+ INSERT INTO knoe.user (username, display_name, email, realm, created_at)
+ VALUES (?, ?, ?, 'KNOE.DEV', now())
+ RETURNING id
+ """, Integer.class, username, displayName, email);
+
+ if (userId == null) {
+ throw new ProvisioningException("Failed to create user row for " + username);
+ }
+
+ // 2. Insert knoe.identity (Google corroboration)
+ db.update("""
+ INSERT INTO knoe.identity
+ (user_id, provider, provider_sub, provider_email, provider_hd, verified_at)
+ VALUES (?, 'google', ?, ?, ?, now())
+ """, userId, googleId.sub(), googleId.email(), googleId.hd());
+
+ // 3. Insert knoe.totp_credential
+ // TODO Round 1.5: encrypt secret with OpenBao transit key before storing.
+ db.update("""
+ INSERT INTO knoe.totp_credential (user_id, secret, verified_at, created_at)
+ VALUES (?, ?, now(), now())
+ """, userId, totpSecret);
+
+ // 4. Create Kerberos principal
+ try {
+ kadmin.addPrincipal(username + "@KNOE.DEV");
+ } catch (Exception e) {
+ log.error("kadmin addprinc failed for {}: {}", username, e.getMessage());
+ throw new ProvisioningException("Kerberos principal creation failed: " + e.getMessage(), e);
+ }
+
+ // 5. Mark invite used
+ inviteService.markUsed(inviteToken, username);
+
+ // 6. Queue provisioning jobs
+ queueJob(userId, "create_gitea_user",
+ "{\"username\":\"" + username + "\",\"email\":\"" + email + "\"}");
+ queueJob(userId, "create_gitlab_user",
+ "{\"username\":\"" + username + "\",\"email\":\"" + email + "\"}");
+
+ log.info("Provisioning complete for user {} (id={})", username, userId);
+ return new ProvisionResult(userId, username, email);
+ }
+
+ private void queueJob(int userId, String jobType, String payloadJson) {
+ db.update("""
+ INSERT INTO knoe.provisioning_job (user_id, job_type, status, payload, created_at, updated_at)
+ VALUES (?, ?, 'pending', ?::jsonb, now(), now())
+ """, userId, jobType, payloadJson);
+ }
+
+ // ── Value types ──────────────────────────────────────────────────────────
+
+ public record ProvisionResult(int userId, String username, String email) {}
+
+ public static class ProvisioningException extends RuntimeException {
+ public ProvisioningException(String msg) { super(msg); }
+ public ProvisioningException(String msg, Throwable cause) { super(msg, cause); }
+ }
+}
diff --git a/authority/src/main/java/org/prole/authority/kerberos/KadminClient.java b/authority/src/main/java/org/prole/authority/kerberos/KadminClient.java
new file mode 100644
index 0000000..494768a
--- /dev/null
+++ b/authority/src/main/java/org/prole/authority/kerberos/KadminClient.java
@@ -0,0 +1,136 @@
+package org.prole.authority.kerberos;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.stereotype.Component;
+
+import java.io.BufferedReader;
+import java.io.InputStreamReader;
+import java.util.List;
+import java.util.concurrent.TimeUnit;
+import java.util.stream.Collectors;
+
+/**
+ * KadminClient — shells out to kadmin.local to manage Kerberos principals.
+ *
+ * Runs in the same pod as the KDC sidecar, so kadmin.local has direct database access.
+ * All operations are idempotent: addPrincipal is a no-op if the principal already exists.
+ *
+ * For use in enrollment only — not exposed via any HTTP endpoint.
+ */
+@Component
+public class KadminClient {
+
+ private static final Logger log = LoggerFactory.getLogger(KadminClient.class);
+
+ private static final int TIMEOUT_SECONDS = 30;
+
+ @Value("${knoe.kerberos.realm:KNOE.DEV}")
+ private String realm;
+
+ /**
+ * Create a new principal with a random key (no password — Kerberos keytab only).
+ * For human users this is overridden at first kinit with kadmin changepass.
+ *
+ * @param principal fully-qualified principal, e.g. "chrisfu@KNOE.DEV"
+ */
+ public void addPrincipal(String principal) {
+ String fqPrincipal = qualified(principal);
+ // Check if it already exists — idempotent
+ try {
+ runKadmin("get_principal " + fqPrincipal);
+ log.info("Principal {} already exists — skipping addprinc.", fqPrincipal);
+ return;
+ } catch (KadminException e) {
+ // Principal doesn't exist — proceed to create
+ }
+
+ runKadmin("addprinc -randkey " + fqPrincipal);
+ log.info("Created Kerberos principal: {}", fqPrincipal);
+ }
+
+ /**
+ * Set the password for a principal (used during password reset flows).
+ *
+ * @param principal fully-qualified or bare principal
+ * @param password new password (will not be logged)
+ */
+ public void changePrincipalPassword(String principal, String password) {
+ String fqPrincipal = qualified(principal);
+ runKadmin("cpw -pw " + password + " " + fqPrincipal);
+ log.info("Password changed for principal: {}", fqPrincipal);
+ }
+
+ /**
+ * Delete a principal (used when an account is disabled).
+ *
+ * @param principal fully-qualified or bare principal
+ */
+ public void deletePrincipal(String principal) {
+ String fqPrincipal = qualified(principal);
+ runKadmin("delprinc -force " + fqPrincipal);
+ log.info("Deleted principal: {}", fqPrincipal);
+ }
+
+ /**
+ * Export a keytab for a principal to a file path.
+ *
+ * @param principal fully-qualified principal
+ * @param keytabPath absolute path on the local filesystem
+ */
+ public void exportKeytab(String principal, String keytabPath) {
+ String fqPrincipal = qualified(principal);
+ runKadmin("ktadd -k " + keytabPath + " " + fqPrincipal);
+ log.info("Exported keytab for {} to {}", fqPrincipal, keytabPath);
+ }
+
+ // ── Internal ──────────────────────────────────────────────────────────────
+
+ private String qualified(String principal) {
+ if (principal.contains("@")) return principal;
+ return principal + "@" + realm;
+ }
+
+ private void runKadmin(String query) {
+ List cmd = List.of("kadmin.local", "-q", query);
+ log.debug("kadmin.local -q \"{}\"", query.startsWith("cpw") ? "cpw -pw *** ..." : query);
+
+ try {
+ Process proc = new ProcessBuilder(cmd)
+ .redirectErrorStream(true)
+ .start();
+
+ String output;
+ try (BufferedReader reader = new BufferedReader(
+ new InputStreamReader(proc.getInputStream()))) {
+ output = reader.lines().collect(Collectors.joining("\n"));
+ }
+
+ boolean finished = proc.waitFor(TIMEOUT_SECONDS, TimeUnit.SECONDS);
+ if (!finished) {
+ proc.destroyForcibly();
+ throw new KadminException("kadmin.local timed out after " + TIMEOUT_SECONDS + "s");
+ }
+
+ int exit = proc.exitValue();
+ if (exit != 0) {
+ // get_principal returns 1 for "Principal does not exist" — caller handles
+ if (output.contains("Principal does not exist")) {
+ throw new KadminException("Principal does not exist");
+ }
+ throw new KadminException("kadmin.local exited " + exit + ": " + output);
+ }
+
+ } catch (KadminException e) {
+ throw e;
+ } catch (Exception e) {
+ throw new KadminException("kadmin.local execution failed: " + e.getMessage(), e);
+ }
+ }
+
+ public static class KadminException extends RuntimeException {
+ public KadminException(String msg) { super(msg); }
+ public KadminException(String msg, Throwable cause) { super(msg, cause); }
+ }
+}
diff --git a/authority/src/main/java/org/prole/authority/provisioning/ProvisioningWorker.java b/authority/src/main/java/org/prole/authority/provisioning/ProvisioningWorker.java
new file mode 100644
index 0000000..676113b
--- /dev/null
+++ b/authority/src/main/java/org/prole/authority/provisioning/ProvisioningWorker.java
@@ -0,0 +1,191 @@
+package org.prole.authority.provisioning;
+
+import org.prole.authority.admin.KnobjectService;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.http.HttpEntity;
+import org.springframework.http.HttpHeaders;
+import org.springframework.http.MediaType;
+import org.springframework.jdbc.core.JdbcTemplate;
+import org.springframework.scheduling.annotation.EnableScheduling;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+import org.springframework.web.client.RestTemplate;
+
+import java.util.List;
+import java.util.Map;
+
+/**
+ * ProvisioningWorker — polls knoe.provisioning_job and dispatches pending jobs.
+ *
+ * Supported job types for Round 1:
+ * create_gitea_user — create Gitea account via Gitea API
+ * create_gitlab_user — create GitLab account via GitLab API (stub)
+ * grant_gitea_access — add member to Gitea org/repo
+ * grant_gitlab_access — add member to GitLab group/project (stub)
+ *
+ * Runs on a fixed delay to avoid concurrent execution on multi-replica deployments.
+ * In Round 2 this should use advisory locks or a proper job queue.
+ */
+@Component
+@EnableScheduling
+public class ProvisioningWorker {
+
+ private static final Logger log = LoggerFactory.getLogger(ProvisioningWorker.class);
+
+ private final JdbcTemplate db;
+ private final KnobjectService knobjectService;
+ private final RestTemplate http = new RestTemplate();
+
+ @Value("${knoe.provisioning.giteaUrl:https://git.knoe.dev}")
+ private String giteaUrl;
+
+ @Value("${knoe.provisioning.giteaToken:}")
+ private String giteaToken;
+
+ public ProvisioningWorker(JdbcTemplate db, KnobjectService knobjectService) {
+ this.db = db;
+ this.knobjectService = knobjectService;
+ }
+
+ @Scheduled(fixedDelayString = "${knoe.provisioning.pollIntervalMs:10000}")
+ public void poll() {
+ List> jobs = db.queryForList("""
+ SELECT id, user_id, job_type, payload
+ FROM knoe.provisioning_job
+ WHERE status = 'pending'
+ ORDER BY created_at
+ LIMIT 10
+ """);
+
+ if (jobs.isEmpty()) return;
+
+ log.debug("Provisioning: {} pending job(s)", jobs.size());
+
+ for (var job : jobs) {
+ int jobId = (int) job.get("id");
+ int userId = (int) job.get("user_id");
+ String jobType = (String) job.get("job_type");
+ Object payloadObj = job.get("payload");
+ String payload = payloadObj != null ? payloadObj.toString() : "{}";
+
+ markRunning(jobId);
+ try {
+ dispatch(jobId, userId, jobType, payload);
+ markDone(jobId, "{\"status\":\"ok\"}");
+ log.info("Job {} ({}) completed for userId={}", jobId, jobType, userId);
+ } catch (Exception e) {
+ log.error("Job {} ({}) failed for userId={}: {}", jobId, jobType, userId, e.getMessage());
+ markFailed(jobId, "{\"error\":\"" + escape(e.getMessage()) + "\"}");
+ }
+ }
+ }
+
+ private void dispatch(int jobId, int userId, String jobType, String payload) {
+ switch (jobType) {
+ case "create_gitea_user" -> createGiteaUser(payload);
+ case "create_gitlab_user" -> createGitlabUser(payload);
+ case "grant_gitea_access" -> grantGiteaAccess(payload);
+ case "grant_gitlab_access"-> grantGitlabAccess(payload);
+ default -> log.warn("Unknown job type '{}' for jobId={}", jobType, jobId);
+ }
+ }
+
+ // ── Gitea ─────────────────────────────────────────────────────────────────
+
+ private void createGiteaUser(String payloadJson) {
+ if (giteaToken == null || giteaToken.isBlank()) {
+ log.warn("GITEA_TOKEN not set — skipping create_gitea_user");
+ return;
+ }
+
+ // Parse username + email from JSON payload (simple extraction, no full JSON parser needed)
+ String username = extractJsonField(payloadJson, "username");
+ String email = extractJsonField(payloadJson, "email");
+
+ String body = """
+ {"login_name":"%s","username":"%s","email":"%s",
+ "password":"%s","must_change_password":true,
+ "send_notify":true,"source_id":0}
+ """.formatted(username, username, email, generateTempPassword());
+
+ var headers = new HttpHeaders();
+ headers.setContentType(MediaType.APPLICATION_JSON);
+ headers.set("Authorization", "token " + giteaToken);
+
+ var response = http.postForEntity(
+ giteaUrl + "/api/v1/admin/users",
+ new HttpEntity<>(body, headers),
+ String.class);
+
+ log.info("Gitea user {} created — HTTP {}", username, response.getStatusCode());
+ }
+
+ private void grantGiteaAccess(String payloadJson) {
+ if (giteaToken == null || giteaToken.isBlank()) {
+ log.warn("GITEA_TOKEN not set — skipping grant_gitea_access");
+ return;
+ }
+ // Stub — implemented fully in Round 1.5 when repo structure is defined
+ log.info("grant_gitea_access (stub): {}", payloadJson);
+ }
+
+ // ── GitLab ────────────────────────────────────────────────────────────────
+
+ private void createGitlabUser(String payloadJson) {
+ // Stub for Round 1 — GitLab is on git.prole.org which may not be accessible
+ // from knoe-dev-0. Implement via GitLab API in Round 1.5.
+ log.info("create_gitlab_user (stub — implement in Round 1.5): {}", payloadJson);
+ }
+
+ private void grantGitlabAccess(String payloadJson) {
+ log.info("grant_gitlab_access (stub — implement in Round 1.5): {}", payloadJson);
+ }
+
+ // ── Helpers ───────────────────────────────────────────────────────────────
+
+ private void markRunning(int jobId) {
+ db.update("UPDATE knoe.provisioning_job SET status='running', updated_at=now() WHERE id=?",
+ jobId);
+ }
+
+ private void markDone(int jobId, String resultJson) {
+ db.update("""
+ UPDATE knoe.provisioning_job
+ SET status='done', result=?::jsonb, updated_at=now()
+ WHERE id=?
+ """, resultJson, jobId);
+ }
+
+ private void markFailed(int jobId, String resultJson) {
+ db.update("""
+ UPDATE knoe.provisioning_job
+ SET status='failed', result=?::jsonb, updated_at=now()
+ WHERE id=?
+ """, resultJson, jobId);
+ }
+
+ /** Very simple JSON field extraction — avoids adding a JSON dep just for this. */
+ private static String extractJsonField(String json, String field) {
+ String marker = "\"" + field + "\":\"";
+ int start = json.indexOf(marker);
+ if (start < 0) return "";
+ start += marker.length();
+ int end = json.indexOf('"', start);
+ return end < 0 ? "" : json.substring(start, end);
+ }
+
+ private static String escape(String s) {
+ return s == null ? "" : s.replace("\\", "\\\\").replace("\"", "\\\"");
+ }
+
+ private static String generateTempPassword() {
+ // 20-char random alphanumeric — user must change on first login
+ var sb = new StringBuilder(20);
+ var rng = new java.security.SecureRandom();
+ String chars = "ABCDEFGHJKMNPQRSTWXYZabcdefghjkmnpqrstwxyz23456789@#$!";
+ for (int i = 0; i < 20; i++) sb.append(chars.charAt(rng.nextInt(chars.length())));
+ return sb.toString();
+ }
+}
diff --git a/authority/src/main/resources/application.yml b/authority/src/main/resources/application.yml
index 1a7497a..4b33a3d 100644
--- a/authority/src/main/resources/application.yml
+++ b/authority/src/main/resources/application.yml
@@ -22,6 +22,41 @@ knoe:
adminPrincipals: []
kerberos:
# REQUIRED for SPNEGO when enabled. Provide via env.
- servicePrincipal: ""
- keytabPath: ""
- realm: ""
+ servicePrincipal: ${KNOE_KERBEROS_SERVICE_PRINCIPAL:}
+ keytabPath: ${KNOE_KERBEROS_KEYTAB_PATH:}
+ realm: ${KNOE_KERBEROS_REALM:}
+
+ # ── Enrollment (knoe-auth Round 1) ──────────────────────────────────────
+ enroll:
+ inviteTtlHours: ${KNOE_ENROLL_INVITE_TTL_HOURS:72}
+ otpTtlMinutes: ${KNOE_ENROLL_OTP_TTL_MINUTES:10}
+ otpMaxAttempts: ${KNOE_ENROLL_OTP_MAX_ATTEMPTS:3}
+ totpIssuer: ${KNOE_ENROLL_TOTP_ISSUER:Knoe.DEV}
+ # Base URL used in invite emails and enrollment redirect URIs
+ baseUrl: ${KNOE_AUTH_BASE_URL:https://auth.knoe.dev}
+
+ # ── Google OAuth2 corroboration ──────────────────────────────────────────
+ # No allowed-domains list — any Google account is accepted.
+ # Trust is established by invite OTP, not the developer's home domain.
+ # provider_hd is recorded in knoe.identity for audit only.
+ google:
+ clientId: ${GOOGLE_CLIENT_ID:}
+ clientSecret: ${GOOGLE_CLIENT_SECRET:}
+ redirectUri: ${KNOE_AUTH_BASE_URL:https://auth.knoe.dev}/auth/enroll/google-callback
+
+ # ── Async provisioning worker ─────────────────────────────────────────────
+ provisioning:
+ pollIntervalMs: ${KNOE_PROVISIONING_POLL_INTERVAL_MS:10000}
+ giteaUrl: ${KNOE_GITEA_URL:https://git.knoe.dev}
+ giteaToken: ${KNOE_GITEA_TOKEN:}
+
+spring:
+ # ── Database ─────────────────────────────────────────────────────────────
+ datasource:
+ url: ${KNOE_DB_URL:jdbc:postgresql://localhost:5432/knoe}
+ username: ${KNOE_DB_USER:knoe}
+ password: ${KNOE_DB_PASSWORD:}
+ driver-class-name: org.postgresql.Driver
+ sql:
+ init:
+ mode: never
diff --git a/conf/cnpg-placement/knoe-system-knoe-db.json b/conf/cnpg-placement/knoe-system-knoe-db.json
index 0d1f250..c82084b 100644
--- a/conf/cnpg-placement/knoe-system-knoe-db.json
+++ b/conf/cnpg-placement/knoe-system-knoe-db.json
@@ -1,23 +1,15 @@
{
- "assignments": {
- "0": "gke-knoe-dev-0-default-pool-02b40136-m9h9",
- "1": "gke-knoe-dev-0-default-pool-6fb9e725-8ldx",
- "2": "gke-knoe-dev-0-default-pool-d65ac672-9ncf"
- },
+ "assignments": {},
"cluster_name": "knoe-db",
"desired_instances": 3,
- "eligible_nodes": [
- "gke-knoe-dev-0-default-pool-02b40136-m9h9",
- "gke-knoe-dev-0-default-pool-6fb9e725-8ldx",
- "gke-knoe-dev-0-default-pool-d65ac672-9ncf"
- ],
+ "eligible_nodes": [],
"metadata": {
"prior_plan_present": true,
- "reason": "reused",
- "regenerated": false,
- "reused": true
+ "reason": "new_cluster",
+ "regenerated": true,
+ "reused": false
},
- "plan_hash": "a44825aeb5ed4e13",
- "plan_id": "cnpg-placement-a44825aeb5ed4e13",
+ "plan_hash": "965d2fde4035059f",
+ "plan_id": "cnpg-placement-965d2fde4035059f",
"schema_version": "v1"
}
diff --git a/conf/k3d.cfg b/conf/k3d.cfg
index 1fe10d9..2100295 100644
--- a/conf/k3d.cfg
+++ b/conf/k3d.cfg
@@ -1,5 +1,5 @@
; Knoe Master Configuration File
-; Generated by install.py on 2026-04-14 06:09:00
+; Generated by install.py on 2026-04-22 21:15:00
; This file is used as input for Ansible deployment and k8s cluster creation.
[User]
@@ -28,37 +28,35 @@ database_options.ext.pgvector = true
database_options.ext.postgis = true
database_options.ext.postgres_fdw = true
database_options.version_type = v18
-dependencies.ansible.install = true
dependencies.auto_install_missing = true
dependencies.brew.install = true
+dependencies.containerd.install = true
+dependencies.docker-buildx.install = true
dependencies.docker.install = true
dependencies.gcloud.install = true
dependencies.k3d.install = true
dependencies.kubectl.install = true
dependencies.kubectx.install = true
+dependencies.op.install = true
dependencies.opentofu.install = true
dependencies.python.install = true
dependencies.verify_all = false
disk_selection.disk_type = local
-disk_selection.local_path = /Users/chrisfu/dev/knoe/knoe-tools-app/dist
+disk_selection.local_path = /Users/chrisfu/dev/knoe-db/knoe-tools-app/dist
disk_selection.removable_mount =
env_setup.CLUSTER_NAME = ${CLUSTER_NAME}
env_setup.DATABASE_NAMESPACE = ${DATABASE_NAMESPACE}
-env_setup.KNOE_CONF = /Users/chrisfu/dev/knoe/conf
-env_setup.PROLE_DATA = /Users/chrisfu/dev/knoe/data
-env_setup.KNOE_HOME = /Users/chrisfu/dev/knoe
-env_setup.PROLE_LOGS = /Users/chrisfu/dev/knoe/logs
-env_setup.KNOE_SERVICE = /Users/chrisfu/dev/knoe/etc
+env_setup.KNOE_CONF = /Users/chrisfu/dev/knoe-db/conf
gitops.git_provider = Gitea
gitops.node_selector =
init_cluster.argocd_enabled = false
init_cluster.at_rest_encryption_enabled = true
init_cluster.cluster_env = dev
init_cluster.deployment_target = knoe-dev-cluster
-init_cluster.gitops_enabled = true
-init_cluster.k3s_server_url = https://myrddin.knoe.org:6443
+init_cluster.gitops_enabled = false
+init_cluster.k3s_server_url = https://myrddin.prole.org:6443
init_cluster.k3s_token = ${KNOE_SECRET:v1:-cslrAhG8WhxxJLY:vAx5MGOBcU1NBMjf4U-3y1djMDmwwOjiWkrutxPa4Li5P8RBjCBhEOCEdGP2CiPJJ6UQK-ietX-mu_5nO3yNNjpwDququT4U6lWHPEInSvUNH6ImU-HzPvm_diL2FwJtZm3sY5HgecIy2dwXB_vLnYaA_7VXt9zf0T70rw==}
-init_cluster.kerberos_enabled = true
+init_cluster.kerberos_enabled = false
init_cluster.mode = k3d
init_cluster.start_cluster = true
init_cluster.supabase_enabled = false
@@ -73,10 +71,10 @@ init_password.db_password_confirm =
init_password.db_username = root
init_password.generate_ssh_key = true
init_scripts.run_scripts = true
-kerberos_config.enabled = true
-kerberos_config.kdc = 10.0.0.3
+kerberos_config.enabled = false
+kerberos_config.kdc =
kerberos_config.password =
-kerberos_config.realm = PROLE.ORG
+kerberos_config.realm =
kerberos_config.test_connection = false
kerberos_config.user = administrator
network_scan.run = true
@@ -84,132 +82,87 @@ ollama_config.model =
ollama_config.server_host =
ollama_config.server_port = 11434
supabase_config.pv_base_dir = /synology/d005
-supabase_config.pv_node = gandalf.knoe.org
+supabase_config.pv_node =
[Global]
; Variables used by name in more than one place or assumed global scope
-ARGOCD_NAMESPACE = argocd
-ARTIFACT_REGISTRY = us-west3-docker.pkg.dev/plenary-truck-485623-p7/knoe-system
-AUTHORITY_ENABLED = true
-AUTH_HOSTNAME = api.knoe.org
-AUTH_LOGIN_PATH = /auth/login
-AUTH_RESPONSE_HEADERS = X-Knoe-User,X-Knoe-Email,X-Knoe-Groups
-AUTH_VERIFY_PATH = /auth/verify
CLUSTER_ENV = dev
CLUSTER_NAME = knoe-db
-CNPG_PLACEMENT_PLAN_FILE = /Users/chrisfu/dev/knoe/conf/cnpg-placement/knoe-system-knoe-db.json
-CNPG_PLACEMENT_PLAN_HASH = 965d2fde4035059f
-CNPG_PLACEMENT_PLAN_ID = cnpg-placement-965d2fde4035059f
-DATABASE_NAMESPACE = knoe-db-18-008-18-009-18-013-18-014
+DATABASE_NAMESPACE = knoe-db-18-140
DB_HOST_PORT = 5432
DEPLOYMENT_MODE = k3d
DEPLOYMENT_TARGET = knoe-dev-cluster
DOCKER_PRELOAD = false
-GITLAB_PUBLIC_HOSTS = git.knoe.dev,git.knoe.org
-K3S_SERVER = https://myrddin.knoe.org:6443
-K3S_TOKEN = ${KNOE_SECRET:v1:CWWf3RHFdbUrmfrY:It8a2G8QUUIsqVwMsm3LsI4UvSSChEc_uAdESwzYplZLOCiSsCbOKuT9FbPpIwQvEaG_gLz9ZAfkD0EQxJp81KAtpk_X3K_nxVUa0RPRlbt_wdeXXoMoFFpN5BqXXz2HZwKgh_gpK1hjVbsJQHKAbTqWfu8u_LTmYYg4ag==}
KNOE_DB_USER = root
-KUBECONTEXT = dev
-MONITORING_STORAGE_CLASS = local-path
-OPENTOFU_URL = http://127.0.0.1:8080
OPTIONAL_WORKLOADS_MIN_READY_SCHEDULABLE_NODES = 2
-PROLE_K3S_SERVER = https://myrddin.knoe.org:6443
+PROLE_K3S_SERVER = https://myrddin.prole.org:6443
PROLE_K3S_TOKEN = ${KNOE_SECRET:v1:-cslrAhG8WhxxJLY:vAx5MGOBcU1NBMjf4U-3y1djMDmwwOjiWkrutxPa4Li5P8RBjCBhEOCEdGP2CiPJJ6UQK-ietX-mu_5nO3yNNjpwDququT4U6lWHPEInSvUNH6ImU-HzPvm_diL2FwJtZm3sY5HgecIy2dwXB_vLnYaA_7VXt9zf0T70rw==}
PROLE_OPENTOFU_URL = http://127.0.0.1:8080
-PROTECTED_DB_HOSTS = db.0.knoe.dev,db.knoe.org
-PROTECTED_GIT_HOSTS = git.knoe.dev,git.knoe.org
-REGISTRY_NAMESPACE = knoe-system
SERVICE_NAMESPACE = knoe-system
SUPABASE_PV_BASE = /synology/d005
SUPABASE_PV_BASE_DIR = /synology/d005
-SUPABASE_PV_NODE = gandalf.knoe.org
-SUPABASE_STUDIO_HOSTNAME = db.0.knoe.dev,db.knoe.org
[Welcome]
; No configuration values captured yet for this section.
[Dependencies]
-STATUS = All installed
+; No configuration values captured yet for this section.
[Network]
-AD_DC_HOST = myrddin.knoe.org
-AD_DC_IP = 10.0.0.3
-ANSIBLE_DOMAIN = knoe.org
-ANSIBLE_INFRASTRUCTURE = $HOME/dev/knoe/infrastructure
-ANSIBLE_INVENTORY = $HOME/dev/knoe/infrastructure/inventory
-ANSIBLE_REALM = PROLE.ORG
-ANSIBLE_TOPOLOGY = {"domain":"knoe.org","realm":"PROLE.ORG","internal_records":{"aventage.knoe.org":"10.0.0.206","fairyland.knoe.org":"10.0.0.208","loghost.knoe.org":"10.0.0.3","merlin.knoe.org":"10.0.0.6","morana.knoe.org":"10.0.0.66","morgoth.knoe.org":"10.0.0.204","myrddin.knoe.org":"10.0.0.3","pi.knoe.org":"10.0.0.5","raspberry.knoe.org":"10.0.0.4","retropie.knoe.org":"10.0.0.207","synology.knoe.org":"10.0.0.203","zinfandel.knoe.org":"10.0.0.205"},"ad_dc":{"host":"myrddin.knoe.org","ip":"10.0.0.3"},"k3s":{"server_url":"https://myrddin.knoe.org:6443","server_host":"myrddin.knoe.org","token_present":true},"groups":{"iscsi":["pi.knoe.org","raspberry.knoe.org","myrddin.knoe.org","retropie.knoe.org","merlin.knoe.org","gandalf.knoe.org"],"pihole":["pi.knoe.org","raspberry.knoe.org"],"ad_dc":["myrddin.knoe.org"],"k3s_servers":["myrddin.knoe.org"],"k3s_agents":["merlin.knoe.org","gandalf.knoe.org"],"k3s_hosts:children":["k3s_servers","k3s_agents"],"linux_hosts":["pi.knoe.org","raspberry.knoe.org","myrddin.knoe.org","retropie.knoe.org","merlin.knoe.org","gandalf.knoe.org"],"ssl_hosts":["myrddin.knoe.org"],"mariadb_primary":["merlin.knoe.org"],"mariadb_replica":["raspberry.knoe.org"],"mariadb:children":["mariadb_primary","mariadb_replica"],"merlin_bootstrap":["merlin"],"k3s_hosts":["gandalf.knoe.org"]},"hosts":{"merlin":"10.0.0.6","merlin.knoe.org":"10.0.0.6","myrddin.knoe.org":"10.0.0.3","pi.knoe.org":"10.0.0.5","raspberry.knoe.org":"10.0.0.4","retropie.knoe.org":"10.0.0.207"},"unmapped_hosts":["gandalf.knoe.org","k3s_agents","k3s_servers","mariadb_primary","mariadb_replica"]}
-KDC_ANSIBLE_DETECTED = 10.0.0.3
-KDC_AUTO_DETECTED = 10.0.0.3
-KERBEROS_AUTO_ENABLED = True
+KERBEROS_AUTO_ENABLED = False
[Port Forwards]
; No configuration values captured yet for this section.
[System Environment]
-KNOE_CONF = $HOME/dev/knoe/conf
-PROLE_DATA = $HOME/dev/knoe/data
-KNOE_HOME = $HOME/dev/knoe
-PROLE_LOGS = $HOME/dev/knoe/logs
-KNOE_SERVICE = $HOME/dev/knoe/etc
+; No configuration values captured yet for this section.
[Monitoring]
-MONITORING_STORAGE_CLASS = local-path
+; No configuration values captured yet for this section.
[Kerberos Authentication]
; No configuration values captured yet for this section.
[Ollama]
-OLLAMA_SERVERS = 10.0.0.208:11434,fairyland.knoe.org:11434,k3d.localhost:11434,morgoth.knoe.org:11434
+; No configuration values captured yet for this section.
[Optional Features]
-AT_REST_ENCRYPTION_ENABLED = true
-GITOPS_ENABLED = True
-GITOPS_PROVIDER = GitLab
-KERBEROS_ENABLED = true
-SUPABASE_ENABLED = false
+; No configuration values captured yet for this section.
[GitOps]
; No configuration values captured yet for this section.
[Database Creation]
-APP_CLUSTER_NAME = knoe-dev-0
-DB_CLUSTER_NAME = knoe-cnpg-0
-DB_USER = root
+; No configuration values captured yet for this section.
[Initialize Cluster]
-ENVIRONMENT = dev
-K3S_SERVER_URL = https://myrddin.knoe.org:6443
-K3S_TOKEN = ${KNOE_SECRET:v1:ozzcomisjsQYIkSH:Ytp91WR_iP4tJyTAmdH_SRhcKycgzea0zLAgTBNxDsQaBPM-pR_VK3u9wc5QkFzszdAHZGBhVN2HKyqnz-cqDR0WAus88DFbF4zWlgvl6gKEAynaXbdMwAa6vYLUGi8ZE0u1pRiO4KJyiulhBIpfoMReM1Wu6Mj1-20hXw==}
+; No configuration values captured yet for this section.
[Dev Cluster (k3d)]
CLUSTER_ENV = dev
DISPLAY_NAME = knoe-dev-cluster
-KUBECTL_CONTEXT = dev
MODE = k3d
[Service Cluster (k3s)]
CLUSTER_ENV = knoe-service-cluster
DISPLAY_NAME = knoe-service-cluster
-K3S_SERVER_URL = https://myrddin.knoe.org:6443
+K3S_SERVER_URL = https://myrddin.prole.org:6443
K3S_TOKEN = ${KNOE_SECRET:v1:-cslrAhG8WhxxJLY:vAx5MGOBcU1NBMjf4U-3y1djMDmwwOjiWkrutxPa4Li5P8RBjCBhEOCEdGP2CiPJJ6UQK-ietX-mu_5nO3yNNjpwDququT4U6lWHPEInSvUNH6ImU-HzPvm_diL2FwJtZm3sY5HgecIy2dwXB_vLnYaA_7VXt9zf0T70rw==}
MODE = k3s
+PIPELINE_URL = http://127.0.0.1:8080
[GCP]
-BILLING_ACCOUNT = 01193C-25783B-3211AD
-BILLING_PROJECT = plenary-truck-485623-p7
-ORG_ID = 584001916389
-PROJECT_ID = plenary-truck-485623-p7
+; No configuration values captured yet for this section.
[Prod Cluster (k8s)]
-ARTIFACTS_DIR = $HOME/dev/knoe/data/staging
+ARTIFACTS_DIR = $HOME/dev/knoe-db/data/staging
CLUSTER_ENV = knoe-prod-cluster
DISPLAY_NAME = knoe-prod-cluster
MODE = k8s
+PIPELINE_URL = http://127.0.0.1:8080
[Docker Build]
-LOCAL_REGISTRY = localhost:5000
-LOCAL_REGISTRY_INTERNAL = k3d-knoe-registry.localhost:5000
+; No configuration values captured yet for this section.
[Initialization Scripts]
; No configuration values captured yet for this section.
@@ -219,4 +172,4 @@ MODE = k3d
TARGET = knoe-dev-cluster
[Install]
-STATUS = Failed
+; No configuration values captured yet for this section.
diff --git a/conf/k3s.cfg b/conf/k3s.cfg
index 9a2840e..eb7df8e 100644
--- a/conf/k3s.cfg
+++ b/conf/k3s.cfg
@@ -76,7 +76,7 @@ init_cluster.db_cluster_region =
init_cluster.db_cluster_zones =
init_cluster.deployment_target = knoe-service-cluster
init_cluster.gitops_enabled = true
-init_cluster.k3s_server_url = https://myrddin.knoe.org:6443
+init_cluster.k3s_server_url = https://myrddin.prole.org:6443
init_cluster.k3s_token = ${KNOE_SECRET:v1:-cslrAhG8WhxxJLY:vAx5MGOBcU1NBMjf4U-3y1djMDmwwOjiWkrutxPa4Li5P8RBjCBhEOCEdGP2CiPJJ6UQK-ietX-mu_5nO3yNNjpwDququT4U6lWHPEInSvUNH6ImU-HzPvm_diL2FwJtZm3sY5HgecIy2dwXB_vLnYaA_7VXt9zf0T70rw==}
init_cluster.kerberos_enabled = true
init_cluster.mode = k3s
@@ -87,7 +87,7 @@ init_cluster.supabase_enabled = false
init_cluster.supabase_meta_enabled = true
init_cluster.supabase_realtime_enabled = true
init_cluster.supabase_studio_enabled = false
-init_cluster.supabase_studio_url = db.0.knoe.dev
+init_cluster.supabase_studio_url = db.0.prole.org
init_cnpg_deploy.force_rollout = false
init_cnpg_deploy.run_deploy = true
init_db_build.run_build = true
@@ -113,24 +113,24 @@ ollama_config.model =
ollama_config.server_host =
ollama_config.server_port = 11434
supabase_config.pv_base_dir = /synology/d005
-supabase_config.pv_node = gandalf.knoe.org
+supabase_config.pv_node = gandalf.prole.org
[Global]
; Variables used by name in more than one place or assumed global scope
ARGOCD_NAMESPACE = argocd
ARTIFACT_REGISTRY = us-west3-docker.pkg.dev/plenary-truck-485623-p7/knoe-system
AUTHORITY_ENABLED = true
-AUTH_HOSTNAME = api.knoe.org
+AUTH_HOSTNAME = api.prole.org
AUTH_LOGIN_PATH = /auth/login
AUTH_RESPONSE_HEADERS = X-Knoe-User,X-Knoe-Email,X-Knoe-Groups
AUTH_VERIFY_PATH = /auth/verify
CLUSTER_ENV = service
CLUSTER_NAME = knoe-db
-CNPG_ELIGIBLE_NODES = gandalf.knoe.org,merlin.knoe.org,myrddin.knoe.org
+CNPG_ELIGIBLE_NODES = gandalf.prole.org,merlin.prole.org,myrddin.prole.org
CNPG_PLACEMENT_PLAN_FILE = $HOME/dev/knoe/conf/cnpg-placement/knoe-system-knoe-db.json
CNPG_PLACEMENT_PLAN_HASH = 962fb2e7bfd2a48b
CNPG_PLACEMENT_PLAN_ID = cnpg-placement-962fb2e7bfd2a48b
-CNPG_STAGE1_NODE = gandalf.knoe.org
+CNPG_STAGE1_NODE = gandalf.prole.org
DATABASE_NAMESPACE = knoe-db
DB_HOST_PORT = 5432
DB_PASSWORD = ${KNOE_SECRET:v1:Vc5Sow_MQksbOtOJ:bvD1ABxenFlo0304dhf0Me_nzBX0SvLJ7oFvE_TkHGqc0YF8}
@@ -138,30 +138,30 @@ DEPLOYMENT_MODE = k3s
DEPLOYMENT_TARGET = knoe-service-cluster
DOCKER_IMPORT_DIR =
DOCKER_PRELOAD = false
-GITEA_HOSTNAME = git-internal.knoe.org
-GITLAB_PUBLIC_HOSTS = git.knoe.org
+GITEA_HOSTNAME = git-internal.prole.org
+GITLAB_PUBLIC_HOSTS = git.prole.org
GITLAB_REPAIR_BLOCKED_AUTOCLEAN = 1
-K3S_SERVER = https://myrddin.knoe.org:6443
+K3S_SERVER = https://myrddin.prole.org:6443
K3S_TOKEN = ${KNOE_SECRET:v1:CWWf3RHFdbUrmfrY:It8a2G8QUUIsqVwMsm3LsI4UvSSChEc_uAdESwzYplZLOCiSsCbOKuT9FbPpIwQvEaG_gLz9ZAfkD0EQxJp81KAtpk_X3K_nxVUa0RPRlbt_wdeXXoMoFFpN5BqXXz2HZwKgh_gpK1hjVbsJQHKAbTqWfu8u_LTmYYg4ag==}
KNOE_DB_USER = root
-KNOE_IMAGE_REGISTRY = registry.knoe.org
+KNOE_IMAGE_REGISTRY = registry.prole.org
MONITORING_STORAGE_CLASS = local-path
OPENTOFU_URL = http://127.0.0.1:8080
OPTIONAL_WORKLOADS_MIN_READY_SCHEDULABLE_NODES = 2
KNOE_HOME = $HOME/dev/knoe
-PROLE_K3S_SERVER = https://myrddin.knoe.org:6443
+PROLE_K3S_SERVER = https://myrddin.prole.org:6443
PROLE_K3S_TOKEN = ${KNOE_SECRET:v1:-cslrAhG8WhxxJLY:vAx5MGOBcU1NBMjf4U-3y1djMDmwwOjiWkrutxPa4Li5P8RBjCBhEOCEdGP2CiPJJ6UQK-ietX-mu_5nO3yNNjpwDququT4U6lWHPEInSvUNH6ImU-HzPvm_diL2FwJtZm3sY5HgecIy2dwXB_vLnYaA_7VXt9zf0T70rw==}
-PROTECTED_DB_HOSTS = db.knoe.org
-PROTECTED_GIT_HOSTS = git.knoe.org
+PROTECTED_DB_HOSTS = db.prole.org
+PROTECTED_GIT_HOSTS = git.prole.org
REDIS_HOST = redis-master.knoe-system.svc.cluster.local
REGISTRY_NAMESPACE = knoe-system
-SERVICE_HOSTNAME = svc.knoe.org
+SERVICE_HOSTNAME = svc.prole.org
SERVICE_NAMESPACE = knoe-system
-SUPABASE_API_HOSTNAME = supabase.knoe.org
+SUPABASE_API_HOSTNAME = supabase.prole.org
SUPABASE_PV_BASE = /synology/d005
SUPABASE_PV_BASE_DIR = /synology/d005
-SUPABASE_PV_NODE = gandalf.knoe.org
-SUPABASE_STUDIO_HOSTNAME = db.knoe.org
+SUPABASE_PV_NODE = gandalf.prole.org
+SUPABASE_STUDIO_HOSTNAME = db.prole.org
SYNOLOGY_ROOTS = /synology/d001,/synology/d002,/synology/d004,/synology/d005
[Welcome]
@@ -171,13 +171,13 @@ SYNOLOGY_ROOTS = /synology/d001,/synology/d002,/synology/d004,/synology/d005
STATUS = All installed
[Network]
-AD_DC_HOST = myrddin.knoe.org
+AD_DC_HOST = myrddin.prole.org
AD_DC_IP = 10.0.0.3
-ANSIBLE_DOMAIN = knoe.org
+ANSIBLE_DOMAIN = prole.org
ANSIBLE_INFRASTRUCTURE = $HOME/dev/knoe/infrastructure
ANSIBLE_INVENTORY = $HOME/dev/knoe/infrastructure/inventory
ANSIBLE_REALM = PROLE.ORG
-ANSIBLE_TOPOLOGY = {"domain":"knoe.org","realm":"PROLE.ORG","internal_records":{"aventage.knoe.org":"10.0.0.206","fairyland.knoe.org":"10.0.0.208","loghost.knoe.org":"10.0.0.3","merlin.knoe.org":"10.0.0.6","morana.knoe.org":"10.0.0.66","morgoth.knoe.org":"10.0.0.204","myrddin.knoe.org":"10.0.0.3","pi.knoe.org":"10.0.0.5","raspberry.knoe.org":"10.0.0.4","retropie.knoe.org":"10.0.0.207","synology.knoe.org":"10.0.0.203","zinfandel.knoe.org":"10.0.0.205"},"ad_dc":{"host":"myrddin.knoe.org","ip":"10.0.0.3"},"k3s":{"server_url":"https://myrddin.knoe.org:6443","server_host":"myrddin.knoe.org","token_present":true},"groups":{"iscsi":["pi.knoe.org","raspberry.knoe.org","myrddin.knoe.org","retropie.knoe.org","merlin.knoe.org","gandalf.knoe.org"],"pihole":["pi.knoe.org","raspberry.knoe.org"],"ad_dc":["myrddin.knoe.org"],"k3s_servers":["myrddin.knoe.org"],"k3s_agents":["merlin.knoe.org","gandalf.knoe.org"],"k3s_hosts:children":["k3s_servers","k3s_agents"],"linux_hosts":["pi.knoe.org","raspberry.knoe.org","myrddin.knoe.org","retropie.knoe.org","merlin.knoe.org","gandalf.knoe.org"],"ssl_hosts":["myrddin.knoe.org"],"mariadb_primary":["merlin.knoe.org"],"mariadb_replica":["raspberry.knoe.org"],"mariadb:children":["mariadb_primary","mariadb_replica"],"merlin_bootstrap":["merlin"],"k3s_hosts":["gandalf.knoe.org"]},"hosts":{"merlin":"10.0.0.6","merlin.knoe.org":"10.0.0.6","myrddin.knoe.org":"10.0.0.3","pi.knoe.org":"10.0.0.5","raspberry.knoe.org":"10.0.0.4","retropie.knoe.org":"10.0.0.207"},"unmapped_hosts":["gandalf.knoe.org","k3s_agents","k3s_servers","mariadb_primary","mariadb_replica"]}
+ANSIBLE_TOPOLOGY = {"domain":"prole.org","realm":"PROLE.ORG","internal_records":{"aventage.prole.org":"10.0.0.206","fairyland.prole.org":"10.0.0.208","loghost.prole.org":"10.0.0.3","merlin.prole.org":"10.0.0.6","morana.prole.org":"10.0.0.66","morgoth.prole.org":"10.0.0.204","myrddin.prole.org":"10.0.0.3","pi.prole.org":"10.0.0.5","raspberry.prole.org":"10.0.0.4","retropie.prole.org":"10.0.0.207","synology.prole.org":"10.0.0.203","zinfandel.prole.org":"10.0.0.205"},"ad_dc":{"host":"myrddin.prole.org","ip":"10.0.0.3"},"k3s":{"server_url":"https://myrddin.prole.org:6443","server_host":"myrddin.prole.org","token_present":true},"groups":{"iscsi":["pi.prole.org","raspberry.prole.org","myrddin.prole.org","retropie.prole.org","merlin.prole.org","gandalf.prole.org"],"pihole":["pi.prole.org","raspberry.prole.org"],"ad_dc":["myrddin.prole.org"],"k3s_servers":["myrddin.prole.org"],"k3s_agents":["merlin.prole.org","gandalf.prole.org"],"k3s_hosts:children":["k3s_servers","k3s_agents"],"linux_hosts":["pi.prole.org","raspberry.prole.org","myrddin.prole.org","retropie.prole.org","merlin.prole.org","gandalf.prole.org"],"ssl_hosts":["myrddin.prole.org"],"mariadb_primary":["merlin.prole.org"],"mariadb_replica":["raspberry.prole.org"],"mariadb:children":["mariadb_primary","mariadb_replica"],"merlin_bootstrap":["merlin"],"k3s_hosts":["gandalf.prole.org"]},"hosts":{"merlin":"10.0.0.6","merlin.prole.org":"10.0.0.6","myrddin.prole.org":"10.0.0.3","pi.prole.org":"10.0.0.5","raspberry.prole.org":"10.0.0.4","retropie.prole.org":"10.0.0.207"},"unmapped_hosts":["gandalf.prole.org","k3s_agents","k3s_servers","mariadb_primary","mariadb_replica"]}
KDC_ANSIBLE_DETECTED = 10.0.0.3
KDC_AUTO_DETECTED = 10.0.0.3
KERBEROS_AUTO_ENABLED = True
@@ -226,7 +226,7 @@ DB_USER = root
[Initialize Cluster]
ENVIRONMENT = service
-K3S_SERVER_URL = https://myrddin.knoe.org:6443
+K3S_SERVER_URL = https://myrddin.prole.org:6443
K3S_TOKEN = ${KNOE_SECRET:v1:-cslrAhG8WhxxJLY:vAx5MGOBcU1NBMjf4U-3y1djMDmwwOjiWkrutxPa4Li5P8RBjCBhEOCEdGP2CiPJJ6UQK-ietX-mu_5nO3yNNjpwDququT4U6lWHPEInSvUNH6ImU-HzPvm_diL2FwJtZm3sY5HgecIy2dwXB_vLnYaA_7VXt9zf0T70rw==}
[Dev Cluster (k3d)]
@@ -238,7 +238,7 @@ MODE = k3d
[Service Cluster (k3s)]
CLUSTER_ENV = knoe-service-cluster
DISPLAY_NAME = knoe-service-cluster
-K3S_SERVER_URL = https://myrddin.knoe.org:6443
+K3S_SERVER_URL = https://myrddin.prole.org:6443
K3S_TOKEN = ${KNOE_SECRET:v1:-cslrAhG8WhxxJLY:vAx5MGOBcU1NBMjf4U-3y1djMDmwwOjiWkrutxPa4Li5P8RBjCBhEOCEdGP2CiPJJ6UQK-ietX-mu_5nO3yNNjpwDququT4U6lWHPEInSvUNH6ImU-HzPvm_diL2FwJtZm3sY5HgecIy2dwXB_vLnYaA_7VXt9zf0T70rw==}
KUBECTL_CONTEXT = knoe-service-cluster
MODE = k3s
diff --git a/deploy.sh b/deploy.sh
index d101a47..84bfdc4 100755
--- a/deploy.sh
+++ b/deploy.sh
@@ -132,7 +132,7 @@ def get_runtime_config(path):
gitlab_public_hosts_raw = _cfg_first(g, e, i, "GITLAB_PUBLIC_HOSTS", "gitlab_public_hosts")
gitlab_domain = _cfg_first(g, e, i, "GITLAB_DOMAIN", "GITLAB_HOSTNAME", "gitlab_domain", "gitlab_hostname")
if not gitlab_domain:
- gitlab_domain = "git.knoe.dev" if mode == "k8s" else "git.knoe.org"
+ gitlab_domain = "git.knoe.dev" if mode == "k8s" else "git.prole.org"
gitlab_public_hosts = [h.strip() for h in str(gitlab_public_hosts_raw or "").split(",") if h.strip()]
if not gitlab_public_hosts:
gitlab_public_hosts = [gitlab_domain]
@@ -145,11 +145,11 @@ def get_runtime_config(path):
auth_host = _cfg_first(g, e, i, "AUTH_HOSTNAME", "auth_hostname")
if not auth_host:
- auth_host = "api.knoe.dev" if mode == "k8s" else "api.knoe.org"
+ auth_host = "api.knoe.dev" if mode == "k8s" else "api.prole.org"
service_host = _cfg_first(g, e, i, "SERVICE_HOSTNAME", "service_hostname", "GRAFANA_HOSTNAME", "grafana_hostname")
if not service_host:
- service_host = "svc.knoe.dev" if mode == "k8s" else "svc.knoe.org"
+ service_host = "svc.knoe.dev" if mode == "k8s" else "svc.prole.org"
service_ns = _cfg_first(g, e, i, "SERVICE_NAMESPACE", "service_namespace") or "knoe-system"
diff --git a/deploy/gcp/gke/knoe-auth-deployment.yaml b/deploy/gcp/gke/knoe-auth-deployment.yaml
new file mode 100644
index 0000000..5b1849f
--- /dev/null
+++ b/deploy/gcp/gke/knoe-auth-deployment.yaml
@@ -0,0 +1,307 @@
+---
+# knoe-auth-deployment.yaml
+# Deploys the knoe-auth pod (Spring Boot + KDC sidecar) to knoe-dev-0 / knoe-system.
+# Based on deploy/opentofu/k3s/manifests/knoe/prole-auth-deployment.yaml.
+# Realm: KNOE.DEV (not PROLE.LOCAL)
+# Image: pulled from Artifact Registry — built by knoe-auth CI pipeline.
+#
+# Apply: kubectl -n knoe-system apply -f deploy/gcp/gke/knoe-auth-deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+ name: knoe-auth
+ namespace: knoe-system
+ labels:
+ app: knoe-auth
+spec:
+ replicas: 1
+ selector:
+ matchLabels:
+ app: knoe-auth
+ template:
+ metadata:
+ labels:
+ app: knoe-auth
+ spec:
+ initContainers:
+ # keytab-bootstrap: runs kadmin.local inside the shared KDC data volume
+ # to create the HTTP service principal and export the keytab before the
+ # Spring Boot container starts.
+ - name: keytab-bootstrap
+ image: us-west3-docker.pkg.dev/plenary-truck-485623-p7/knoe-system/knoe-authority:latest
+ imagePullPolicy: Always
+ command:
+ - /bin/bash
+ - -lc
+ - |
+ set -euo pipefail
+ export DEBIAN_FRONTEND=noninteractive
+
+ realm="${KNOE_KDC_REALM:-KNOE.DEV}"
+ admin_principal="${KNOE_KDC_ADMIN_PRINCIPAL:-admin/admin}"
+ if [[ "${admin_principal}" != *"@"* ]]; then
+ admin_principal="${admin_principal}@${realm}"
+ fi
+
+ svc_principal="${KNOE_KERBEROS_SERVICE_PRINCIPAL:?Missing KNOE_KERBEROS_SERVICE_PRINCIPAL}"
+ if [[ "${svc_principal}" != *"@"* ]]; then
+ svc_principal="${svc_principal}@${realm}"
+ fi
+
+ keytab_out="/etc/knoe/keytabs/http.keytab"
+ mkdir -p "$(dirname "${keytab_out}")"
+
+ # If a pre-provisioned keytab is provided as a Secret, use it directly.
+ if [[ -f /mnt/keytab-secret/http.keytab ]]; then
+ cp /mnt/keytab-secret/http.keytab "${keytab_out}"
+ chmod 0400 "${keytab_out}" || true
+ exit 0
+ fi
+
+ if ! command -v kadmin.local >/dev/null 2>&1; then
+ echo "Installing Kerberos packages..."
+ echo "krb5-config krb5-config/default_realm string ${realm}" | debconf-set-selections || true
+ echo "krb5-config krb5-config/kerberos_servers string 127.0.0.1" | debconf-set-selections || true
+ echo "krb5-config krb5-config/admin_server string 127.0.0.1" | debconf-set-selections || true
+ apt-get update -qq
+ apt-get install -y --no-install-recommends krb5-kdc krb5-admin-server krb5-user dnsutils ca-certificates
+ rm -rf /var/lib/apt/lists/*
+ fi
+
+ mkdir -p /etc/krb5kdc /var/lib/krb5kdc
+ [[ -f /opt/knoe-kdc/krb5.conf ]] && cp /opt/knoe-kdc/krb5.conf /etc/krb5.conf
+ [[ -f /opt/knoe-kdc/kdc.conf ]] && cp /opt/knoe-kdc/kdc.conf /etc/krb5kdc/kdc.conf
+ [[ -f /opt/knoe-kdc/kadm5.acl ]] && cp /opt/knoe-kdc/kadm5.acl /etc/krb5kdc/kadm5.acl
+
+ if [[ -z "${KNOE_KDC_MASTER_PASSWORD:-}" ]]; then
+ echo "ERROR: Missing KNOE_KDC_MASTER_PASSWORD" >&2; exit 1
+ fi
+ if [[ -z "${KNOE_KDC_ADMIN_PASSWORD:-}" ]]; then
+ echo "ERROR: Missing KNOE_KDC_ADMIN_PASSWORD" >&2; exit 1
+ fi
+
+ if [[ ! -f /var/lib/krb5kdc/principal ]]; then
+ echo "Initializing realm database for ${realm}..."
+ kdb5_util create -s -r "${realm}" -P "${KNOE_KDC_MASTER_PASSWORD}"
+ fi
+
+ if ! kadmin.local -q "get_principal ${admin_principal}" >/dev/null 2>&1; then
+ kadmin.local -q "addprinc -pw ${KNOE_KDC_ADMIN_PASSWORD} ${admin_principal}"
+ fi
+
+ if ! kadmin.local -q "get_principal ${svc_principal}" >/dev/null 2>&1; then
+ echo "Creating service principal ${svc_principal}..."
+ kadmin.local -q "addprinc -randkey ${svc_principal}"
+ fi
+
+ kadmin.local -q "ktadd -k ${keytab_out} -norandkey ${svc_principal}"
+ chmod 0400 "${keytab_out}" || true
+ echo "Keytab written to ${keytab_out}"
+ env:
+ - name: KNOE_KDC_REALM
+ value: "KNOE.DEV"
+ - name: KNOE_KDC_ADMIN_PRINCIPAL
+ value: "admin/admin"
+ - name: KNOE_KDC_MASTER_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: knoe-kdc-secrets
+ key: master_password
+ - name: KNOE_KDC_ADMIN_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: knoe-kdc-secrets
+ key: admin_password
+ - name: KNOE_KERBEROS_SERVICE_PRINCIPAL
+ value: "HTTP/auth.knoe.dev"
+ volumeMounts:
+ - name: keytab
+ mountPath: /etc/knoe/keytabs
+ - name: keytab-secret
+ mountPath: /mnt/keytab-secret
+ readOnly: true
+ - name: knoe-kdc-config
+ mountPath: /opt/knoe-kdc
+ - name: knoe-kdc-data
+ mountPath: /var/lib/krb5kdc
+ - name: knoe-kdc-etc
+ mountPath: /etc/krb5kdc
+
+ containers:
+ # ── Spring Boot / knoe-auth ──────────────────────────────────────────
+ - name: knoe-auth
+ image: us-west3-docker.pkg.dev/plenary-truck-485623-p7/knoe-system/knoe-authority:latest
+ imagePullPolicy: Always
+ ports:
+ - name: http
+ containerPort: 8080
+ readinessProbe:
+ httpGet:
+ path: /health
+ port: 8080
+ initialDelaySeconds: 20
+ periodSeconds: 10
+ livenessProbe:
+ httpGet:
+ path: /health
+ port: 8080
+ initialDelaySeconds: 60
+ periodSeconds: 30
+ env:
+ - name: KNOE_AUTH_COOKIE_DOMAIN
+ value: ".knoe.dev"
+ - name: KNOE_AUTH_SESSION_SECRET
+ valueFrom:
+ secretKeyRef:
+ name: knoe-auth-secrets
+ key: sessionSecret
+ # ── Kerberos ───────────────────────────────────────────────────
+ - name: KNOE_KERBEROS_SERVICE_PRINCIPAL
+ value: "HTTP/auth.knoe.dev@KNOE.DEV"
+ - name: KNOE_KERBEROS_KEYTAB_PATH
+ value: "/etc/knoe/keytabs/http.keytab"
+ - name: KNOE_KERBEROS_REALM
+ value: "KNOE.DEV"
+ # ── Google OAuth2 (enrollment corroboration) ───────────────────
+ - name: GOOGLE_CLIENT_ID
+ valueFrom:
+ secretKeyRef:
+ name: knoe-auth-google-oidc
+ key: client_id
+ optional: true
+ - name: GOOGLE_CLIENT_SECRET
+ valueFrom:
+ secretKeyRef:
+ name: knoe-auth-google-oidc
+ key: client_secret
+ optional: true
+ # ── Database (CNPG via cluster-internal service) ───────────────
+ - name: KNOE_DB_URL
+ value: "jdbc:postgresql://knoe-db-rw.knoe-db-0.svc.cluster.local:5432/knoe"
+ - name: KNOE_DB_USER
+ value: "knoe"
+ - name: KNOE_DB_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: knoe-db-app
+ key: password
+ optional: true
+ # ── Enrollment ────────────────────────────────────────────────
+ - name: KNOE_ENROLL_INVITE_TTL_HOURS
+ value: "72"
+ - name: KNOE_ENROLL_OTP_TTL_MINUTES
+ value: "10"
+ - name: KNOE_ENROLL_OTP_MAX_ATTEMPTS
+ value: "3"
+ - name: KNOE_ENROLL_TOTP_ISSUER
+ value: "Knoe.DEV"
+ - name: KNOE_AUTH_BASE_URL
+ value: "https://auth.knoe.dev"
+ # ── Provisioning ─────────────────────────────────────────────
+ - name: KNOE_PROVISIONING_POLL_INTERVAL_MS
+ value: "10000"
+ - name: KNOE_GITEA_URL
+ value: "https://git.knoe.dev"
+ - name: KNOE_GITEA_TOKEN
+ valueFrom:
+ secretKeyRef:
+ name: knoe-gitea-admin
+ key: token
+ optional: true
+ volumeMounts:
+ - name: keytab
+ mountPath: /etc/knoe/keytabs
+ readOnly: true
+ - name: knoe-kdc-config
+ mountPath: /etc/krb5.conf
+ subPath: krb5.conf
+ readOnly: true
+
+ # ── MIT Kerberos KDC sidecar ─────────────────────────────────────────
+ - name: kdc
+ image: us-west3-docker.pkg.dev/plenary-truck-485623-p7/knoe-system/knoe-authority:latest
+ imagePullPolicy: Always
+ command: ["/bin/bash", "/opt/knoe-kdc/entrypoint.sh"]
+ env:
+ - name: KNOE_KDC_REALM
+ value: "KNOE.DEV"
+ - name: KNOE_KDC_ADMIN_PRINCIPAL
+ value: "admin/admin"
+ - name: KNOE_KDC_MASTER_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: knoe-kdc-secrets
+ key: master_password
+ - name: KNOE_KDC_ADMIN_PASSWORD
+ valueFrom:
+ secretKeyRef:
+ name: knoe-kdc-secrets
+ key: admin_password
+ ports:
+ - name: krb5-udp
+ containerPort: 88
+ protocol: UDP
+ - name: krb5-tcp
+ containerPort: 88
+ protocol: TCP
+ - name: kpasswd-udp
+ containerPort: 464
+ protocol: UDP
+ - name: kpasswd-tcp
+ containerPort: 464
+ protocol: TCP
+ - name: kadmin
+ containerPort: 749
+ protocol: TCP
+ volumeMounts:
+ - name: knoe-kdc-config
+ mountPath: /opt/knoe-kdc
+ - name: knoe-kdc-data
+ mountPath: /var/lib/krb5kdc
+ - name: knoe-kdc-etc
+ mountPath: /etc/krb5kdc
+
+ volumes:
+ - name: keytab
+ emptyDir: {}
+ - name: keytab-secret
+ secret:
+ secretName: knoe-auth-keytab
+ optional: true
+ - name: knoe-kdc-config
+ configMap:
+ name: knoe-kdc-config
+ defaultMode: 0755
+ - name: knoe-kdc-data
+ emptyDir: {}
+ - name: knoe-kdc-etc
+ emptyDir: {}
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+ name: knoe-auth
+ namespace: knoe-system
+ labels:
+ app: knoe-auth
+spec:
+ selector:
+ app: knoe-auth
+ ports:
+ - name: http
+ port: 80
+ targetPort: 8080
+ - name: krb5-tcp
+ port: 88
+ targetPort: 88
+ protocol: TCP
+ - name: krb5-udp
+ port: 88
+ targetPort: 88
+ protocol: UDP
+ - name: kadmin
+ port: 749
+ targetPort: 749
+ protocol: TCP
+ type: ClusterIP
diff --git a/deploy/gcp/gke/knoe-kdc-configmap.yaml b/deploy/gcp/gke/knoe-kdc-configmap.yaml
new file mode 100644
index 0000000..b5ac7c3
--- /dev/null
+++ b/deploy/gcp/gke/knoe-kdc-configmap.yaml
@@ -0,0 +1,108 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+ name: knoe-kdc-config
+ namespace: knoe-system
+data:
+ krb5.conf: |
+ [libdefaults]
+ default_realm = KNOE.DEV
+ dns_lookup_realm = false
+ dns_lookup_kdc = false
+ ticket_lifetime = 10h
+ renew_lifetime = 7d
+ forwardable = true
+
+ [realms]
+ KNOE.DEV = {
+ kdc = 127.0.0.1
+ admin_server = 127.0.0.1
+ }
+
+ [domain_realm]
+ .knoe.dev = KNOE.DEV
+ knoe.dev = KNOE.DEV
+
+ kdc.conf: |
+ [kdcdefaults]
+ kdc_ports = 88
+ kdc_tcp_ports = 88
+ [realms]
+ KNOE.DEV = {
+ database_name = /var/lib/krb5kdc/principal
+ admin_keytab = FILE:/etc/krb5kdc/kadm5.keytab
+ acl_file = /etc/krb5kdc/kadm5.acl
+ key_stash_file = /etc/krb5kdc/stash
+ max_life = 10h 0m 0s
+ max_renewable_life = 7d 0h 0m 0s
+ default_principal_flags = +preauth
+ }
+
+ kadm5.acl: |
+ admin/admin@KNOE.DEV *
+
+ entrypoint.sh: |
+ #!/usr/bin/env bash
+ set -euo pipefail
+ export DEBIAN_FRONTEND=noninteractive
+
+ realm="${KNOE_KDC_REALM:-KNOE.DEV}"
+ admin_principal="${KNOE_KDC_ADMIN_PRINCIPAL:-admin/admin}"
+ if [[ "${admin_principal}" != *"@"* ]]; then
+ admin_principal="${admin_principal}@${realm}"
+ fi
+
+ if ! command -v krb5kdc >/dev/null 2>&1; then
+ echo "Installing Kerberos packages..."
+ echo "krb5-config krb5-config/default_realm string ${realm}" | debconf-set-selections || true
+ echo "krb5-config krb5-config/kerberos_servers string 127.0.0.1" | debconf-set-selections || true
+ echo "krb5-config krb5-config/admin_server string 127.0.0.1" | debconf-set-selections || true
+ apt-get update -qq
+ apt-get install -y --no-install-recommends krb5-kdc krb5-admin-server krb5-user dnsutils ca-certificates
+ rm -rf /var/lib/apt/lists/*
+ fi
+
+ mkdir -p /etc/krb5kdc /var/lib/krb5kdc
+ if [[ -f /opt/knoe-kdc/krb5.conf ]]; then
+ cp /opt/knoe-kdc/krb5.conf /etc/krb5.conf
+ fi
+ if [[ -f /opt/knoe-kdc/kdc.conf ]]; then
+ cp /opt/knoe-kdc/kdc.conf /etc/krb5kdc/kdc.conf
+ fi
+ if [[ -f /opt/knoe-kdc/kadm5.acl ]]; then
+ cp /opt/knoe-kdc/kadm5.acl /etc/krb5kdc/kadm5.acl
+ fi
+
+ if [[ -z "${KNOE_KDC_MASTER_PASSWORD:-}" ]]; then
+ echo "ERROR: Missing required env KNOE_KDC_MASTER_PASSWORD" >&2
+ exit 1
+ fi
+ if [[ -z "${KNOE_KDC_ADMIN_PASSWORD:-}" ]]; then
+ echo "ERROR: Missing required env KNOE_KDC_ADMIN_PASSWORD" >&2
+ exit 1
+ fi
+
+ if [[ ! -f /var/lib/krb5kdc/principal ]]; then
+ echo "Initializing realm database for ${realm}..."
+ kdb5_util create -s -r "${realm}" -P "${KNOE_KDC_MASTER_PASSWORD}"
+ fi
+
+ if ! kadmin.local -q "get_principal ${admin_principal}" >/dev/null 2>&1; then
+ echo "Creating admin principal ${admin_principal}..."
+ kadmin.local -q "addprinc -pw ${KNOE_KDC_ADMIN_PASSWORD} ${admin_principal}"
+ fi
+
+ # system admin user principal
+ if ! kadmin.local -q "get_principal admin@${realm}" >/dev/null 2>&1; then
+ echo "Creating admin user principal admin@${realm}..."
+ kadmin.local -q "addprinc -pw ${KNOE_KDC_MASTER_PASSWORD} admin@${realm}"
+ fi
+
+ echo "Starting krb5kdc and kadmind ..."
+ krb5kdc -n &
+ sleep 0.5
+ if ! pgrep -x krb5kdc >/dev/null 2>&1; then
+ echo "ERROR: krb5kdc failed to start." >&2
+ exit 1
+ fi
+ exec kadmind -nofork
diff --git a/deploy/gcp/gke/knoe-kdc-secrets.yaml b/deploy/gcp/gke/knoe-kdc-secrets.yaml
new file mode 100644
index 0000000..cc04113
--- /dev/null
+++ b/deploy/gcp/gke/knoe-kdc-secrets.yaml
@@ -0,0 +1,28 @@
+---
+# knoe-kdc-secrets.yaml
+# Placeholder / example structure. Real values are created by init_knoe_auth.sh
+# using 1Password (op) and applied directly — this file is NOT committed with
+# real secrets.
+#
+# To create manually:
+# kubectl -n knoe-system create secret generic knoe-kdc-secrets \
+# --from-literal=master_password="$(op item get 'knoe-kdc-master' --fields password)" \
+# --from-literal=admin_password="$(op item get 'knoe-kdc-admin' --fields password)"
+#
+# Fields:
+# master_password — KDC database master key (kdb5_util -P)
+# admin_password — admin/admin@KNOE.DEV principal password (kadmin)
+#
+# Secret is referenced by:
+# - knoe-kdc (KDC sidecar container)
+# - keytab-bootstrap (initContainer)
+
+apiVersion: v1
+kind: Secret
+metadata:
+ name: knoe-kdc-secrets
+ namespace: knoe-system
+type: Opaque
+stringData:
+ master_password: "REPLACE_WITH_STRONG_RANDOM_VALUE"
+ admin_password: "REPLACE_WITH_STRONG_RANDOM_VALUE"
diff --git a/deploy/opentofu/k3s/manifests/knoe/garage-statefulset.yaml b/deploy/opentofu/k3s/manifests/knoe/garage-statefulset.yaml
index c34477d..7566deb 100644
--- a/deploy/opentofu/k3s/manifests/knoe/garage-statefulset.yaml
+++ b/deploy/opentofu/k3s/manifests/knoe/garage-statefulset.yaml
@@ -16,7 +16,7 @@ spec:
app: garage
spec:
nodeSelector:
- kubernetes.io/hostname: myrddin.knoe.org
+ kubernetes.io/hostname: myrddin.prole.org
containers:
- name: garage
image: dxflrs/garage:v1.3.1
diff --git a/deploy/opentofu/k3s/manifests/knoe/prole-auth-deployment.yaml b/deploy/opentofu/k3s/manifests/knoe/prole-auth-deployment.yaml
index f05e7a9..787183e 100644
--- a/deploy/opentofu/k3s/manifests/knoe/prole-auth-deployment.yaml
+++ b/deploy/opentofu/k3s/manifests/knoe/prole-auth-deployment.yaml
@@ -16,7 +16,7 @@ spec:
spec:
initContainers:
- name: keytab-bootstrap
- image: myrddin.knoe.org:5000/knoe-authority:latest
+ image: myrddin.prole.org:5000/knoe-authority:latest
imagePullPolicy: IfNotPresent
command:
- /bin/bash
@@ -202,7 +202,7 @@ spec:
subPath: krb5.conf
readOnly: true
- name: kdc
- image: myrddin.knoe.org:5000/knoe-authority:latest
+ image: myrddin.prole.org:5000/knoe-authority:latest
imagePullPolicy: IfNotPresent
command: ["/bin/bash", "/opt/knoe-kdc/entrypoint.sh"]
env:
diff --git a/deploy/opentofu/k3s/manifests/knoe/prole-kdc-configmap.yaml b/deploy/opentofu/k3s/manifests/knoe/prole-kdc-configmap.yaml
index 32a7d24..ff83fc9 100644
--- a/deploy/opentofu/k3s/manifests/knoe/prole-kdc-configmap.yaml
+++ b/deploy/opentofu/k3s/manifests/knoe/prole-kdc-configmap.yaml
@@ -15,8 +15,8 @@ data:
admin_server = 127.0.0.1
}
PROLE.ORG = {
- kdc = myrddin.knoe.org
- admin_server = myrddin.knoe.org
+ kdc = myrddin.prole.org
+ admin_server = myrddin.prole.org
}
[capaths]
diff --git a/deploy/opentofu/k3s/manifests/opentofu/deployment.yaml b/deploy/opentofu/k3s/manifests/opentofu/deployment.yaml
index 27f789f..15c222f 100644
--- a/deploy/opentofu/k3s/manifests/opentofu/deployment.yaml
+++ b/deploy/opentofu/k3s/manifests/opentofu/deployment.yaml
@@ -56,7 +56,7 @@ spec:
app: opentofu
spec:
nodeSelector:
- kubernetes.io/hostname: myrddin.knoe.org
+ kubernetes.io/hostname: myrddin.prole.org
containers:
- name: opentofu-ui
image: nginx:1.27-alpine
diff --git a/docs/pipeline-phases.md b/docs/pipeline-phases.md
new file mode 100644
index 0000000..f5d99a0
--- /dev/null
+++ b/docs/pipeline-phases.md
@@ -0,0 +1,775 @@
+# Knoe.DB Autobuild & Test Pipeline — Phase Reference
+
+> **How to use this document**
+> Each phase has a **Status** line, a **Commit Summary** section (filled in after the phase lands), and a **Resumption Checklist** so any developer can pick up where we left off without needing context from a previous session. Update the Status and Commit Summary before starting the next phase.
+
+---
+
+## Context
+
+The project has **four deployment modes** that must each produce a stable, reproducible build:
+
+| Mode | What it is | CI tool |
+|---|---|---|
+| `min` | Single `knoe-db` container via containerd, no Kubernetes | Gitea Actions (bare macOS runner) |
+| `k3d` | k3s-in-Docker local cluster — CNPG + optional Supabase / ArgoCD / Gitea / GitLab | Gitea Actions (Docker-enabled runner) |
+| `k3s` | Homelab multi-node k3s on physical hardware | Deferred (evaluate after GitLab) |
+| `gke` | Dual GKE clusters on Google Cloud (production) | GitLab CI |
+
+**Primary goal:** auto-build on every push to `main` so we have confidence that builds are stable before we touch anything else.
+
+**Secondary goal:** once we have stable builds, identify unused code with `vulture` + coverage diff, then prune toward an *instructable* codebase — a project a junior developer can read and fully understand.
+
+---
+
+## Phase 0 — Foundation
+
+**Status:** ✅ Complete
+**Branch / PRs:** landed directly on `main`; pushed to `origin` (`git-ssh.knoe.dev:knoe.dev/knoe-db`)
+
+### What this phase does
+
+Fixes the broken test infrastructure so IntelliJ can discover tests and `make test` actually measures the right code. No new tests are written here — just scaffolding that every subsequent phase depends on.
+
+### Deliverables
+
+| File | Change |
+|---|---|
+| `pyproject.toml` | Single source of truth for pytest config + coverage config. Replaces the broken `.coveragerc` (which pointed to `installer/` — a directory that no longer exists) |
+| `requirements-test.txt` | Explicit test dependencies (pytest, coverage, vulture, etc.) separated from runtime deps |
+| `.idea/runConfigurations/pytest_all.xml` | IntelliJ: run all tests with coverage |
+| `.idea/runConfigurations/pytest_unit.xml` | IntelliJ: run unit-only tests (fast, no external deps) |
+| `.idea/runConfigurations/pytest_min.xml` | IntelliJ: run tests tagged `@pytest.mark.min` |
+| `.idea/runConfigurations/pytest_k3d.xml` | IntelliJ: run tests tagged `@pytest.mark.k3d` |
+| `.idea/runConfigurations/pytest_gke.xml` | IntelliJ: run tests tagged `@pytest.mark.gke` |
+| `tests/run_tests.sh` | Fix `--cov` source from `install` to `knoe` |
+
+### Commit Summary
+
+```
+97575b9 docs: update Phase 0 commit summary and resumption checklist
+0052a4d Phase 0: test pipeline foundation — pyproject.toml, IntelliJ run configs, coverage fix, welcome mode selector
+```
+
+The following commits landed on the same branch as part of the Cowork+Code thread consolidation (WIP that had accumulated alongside Phase 0):
+
+```
+837da27 docs: update README; IntelliJ run config picks up Python 3.14 SDK
+52fe440 chore(k3s): script and hostprobe updates, temp maintenance scripts
+dd8c9d1 chore(scripts): init script updates — gitea, gitlab, kong, monitoring, registry
+a754659 chore(deploy): cluster config and k3s manifest updates
+4995c86 chore(build): Maven version and authority module updates
+ca469aa chore(installer): core Python updates — env, milestones, monitoring
+5cd9c12 feat(auth): init scripts and k3s/k8s auth manifests for knoe-auth
+2a80df8 feat(auth): land Round 1 — invite-OTP enrollment, kadmin client, GKE manifests
+6c72c76 docs(plans): add platform architecture plans — deployment-modes, knoe-auth round 1
+```
+
+### Known pre-existing issues (fix in Phase 1, not Phase 0)
+
+`knoe/core/ops/cloudnative_pg.py:1372` contains:
+```python
+f"jsonpath={{.data.{field.replace('.', '\\.')}}}",
+```
+Python ≥ 3.12 allows backslashes in f-strings (PEP 701) but this still triggers a `SyntaxError` on Python 3.14 under certain parse modes. This causes **30 test collection errors** — the tests themselves are not broken. Fix: extract the replacement to a variable before the f-string. Tagged as Phase 1 work.
+
+### Resumption Checklist
+
+Before picking up work on Phase 1, verify:
+
+- [x] `pytest tests/` collects 441+ tests from the project root
+- [x] `pytest -m unit` runs and reports a coverage number against `knoe/`
+- [x] IntelliJ shows the five run configs in the Run/Debug Configurations dropdown
+- [x] `python -c "from knoe.ui.screens import KnoeInstaller"` succeeds
+- [x] The 30 collection errors in `cloudnative_pg.py` are logged as Phase 1 work
+
+---
+
+## Phase 1 — `min` Mode Pipeline
+
+**Status:** 🔲 Not started — ready to begin
+**Depends on:** Phase 0 complete ✅
+**First task:** fix `knoe/core/ops/cloudnative_pg.py:1372` f-string syntax (30 collection errors, see Phase 0 known issues)
+
+### What this phase does
+
+Establishes the first green autobuild. The `min` pipeline is the simplest possible CI: a bare macOS runner (no Docker, no Kubernetes) running pytest. It exercises the welcome-screen mode selector, the min-mode navigation fast-path, and the `init_min.sh` script. Trigger: push to `main` on the Gitea remote.
+
+### Architecture
+
+```
+push to main (Gitea)
+ │
+ ▼
+Gitea Actions
+ │
+ ▼
+act_runner ←── bare macOS (dev machine or Mac mini)
+ │ labels: [self-hosted, macos, min]
+ ▼ requires: Homebrew + Python 3.11
+pytest -m "min or unit"
+ │
+ ▼
+coverage.xml ──► uploaded as artifact
+```
+
+**Runner setup (one-time, not in CI):**
+```bash
+# On the macOS runner machine:
+brew install gitea-act-runner
+act_runner register \
+ --instance https:/// \
+ --token \
+ --labels "self-hosted,macos,min" \
+ --name "knoe-min-runner"
+act_runner daemon
+```
+
+### Deliverables
+
+| File | Purpose |
+|---|---|
+| `.gitea/workflows/ci-min.yml` | Gitea Actions workflow — push-triggered, runs on bare macOS runner |
+| `tests/modes/__init__.py` | Package marker |
+| `tests/modes/test_min_mode.py` | Mode-specific tests for min path |
+| `tests/modes/conftest.py` | Mode fixtures (mock containerd, mock 1Password CLI) |
+
+### `.gitea/workflows/ci-min.yml`
+
+```yaml
+name: CI — min mode
+
+on:
+ push:
+ branches: [main]
+
+jobs:
+ min-unit:
+ runs-on: [self-hosted, macos, min]
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Set up Python
+ uses: actions/setup-python@v5
+ with:
+ python-version: "3.11"
+
+ - name: Install dependencies
+ run: |
+ pip install -r requirements.txt -r requirements-test.txt
+
+ - name: Run min + unit tests
+ run: |
+ pytest -m "min or unit" \
+ --cov=knoe \
+ --cov-report=xml \
+ --cov-report=term-missing \
+ -v \
+ tests/
+ env:
+ PYTHONPATH: ${{ github.workspace }}
+ KNOE_MODE: min
+
+ - name: Upload coverage artifact
+ uses: actions/upload-artifact@v4
+ with:
+ name: coverage-min
+ path: coverage.xml
+ retention-days: 14
+```
+
+### Tests to write in `tests/modes/test_min_mode.py`
+
+Each test name is intentionally human-readable — they become living documentation for junior developers.
+
+| Test | What it proves |
+|---|---|
+| `test_welcome_mode_selector_starts_with_no_selection` | `deployment_mode` defaults to `""` on fresh install — forces explicit choice |
+| `test_clicking_min_card_sets_cluster_env_to_min` | Card click wires `cluster_env = "min"` correctly |
+| `test_clicking_min_card_enables_next_button` | Welcome Next is disabled until a card is clicked |
+| `test_min_nav_env_setup_goes_to_init_password_not_cluster` | Verifies min fast-path in `on_next` |
+| `test_min_nav_init_scripts_goes_to_security_not_kerberos` | Min skips Kerberos, ArgoCD, GitOps, Supabase |
+| `test_min_nav_prev_from_init_password_returns_to_env_setup` | Symmetric back-navigation |
+| `test_min_nav_prev_from_security_returns_to_init_scripts` | Symmetric back-navigation |
+| `test_normalize_cluster_env_min_returns_min` | `_normalize_cluster_env("min") == "min"` |
+| `test_deployment_mode_from_env_min_returns_min` | `_deployment_mode_from_env("min") == "min"` |
+| `test_init_min_sh_runs_without_error` | `subprocess` call to `init_min.sh initialize` exits 0 (macOS only, `@pytest.mark.min`) |
+
+### Commit Summary
+
+*(Fill in after phase lands)*
+
+```
+# example:
+# abc1234 Phase 1: add .gitea/workflows/ci-min.yml
+# def5678 Phase 1: add tests/modes/test_min_mode.py
+# ghi9012 Phase 1: add tests/modes/conftest.py
+```
+
+### Resumption Checklist
+
+- [ ] Push to `main` triggers `ci-min` workflow in Gitea Actions UI
+- [ ] `pytest -m "min or unit"` exits 0 locally
+- [ ] All 10 tests in `test_min_mode.py` pass
+- [ ] Coverage artifact appears in the Gitea Actions run summary
+- [ ] Badge shows green on Gitea repo homepage (optional but nice)
+
+---
+
+## Phase 2 — `k3d` Mode Pipeline
+
+**Status:** 🔲 Not started
+**Depends on:** Phase 1 complete
+
+### What this phase does
+
+Adds the k3d integration pipeline — a Docker-enabled runner that creates a real k3d cluster, deploys CNPG, verifies the database is reachable, then tears it down. This is the first pipeline that proves an actual database cluster starts correctly. Estimated runtime: 8–15 minutes.
+
+### Architecture
+
+```
+push to main (Gitea)
+ │
+ ▼
+Gitea Actions
+ │
+ ├─ job: k3d-unit (fast, no cluster) ─────────────► coverage-k3d-unit.xml
+ │
+ └─ job: k3d-integration (depends on unit) ──────► coverage-k3d-integration.xml
+ │
+ ├── k3d cluster create knoe-ci
+ ├── apply CNPG operator
+ ├── apply knoe-db Cluster CR
+ ├── pytest -m "k3d and integration"
+ └── k3d cluster delete knoe-ci (always)
+```
+
+**Runner setup (one-time):**
+Same `act_runner` binary but registered with labels `self-hosted,macos,k3d` on a Docker-enabled machine (Docker Desktop or Colima).
+
+### Deliverables
+
+| File | Purpose |
+|---|---|
+| `.gitea/workflows/ci-k3d.yml` | Two-job workflow: unit then integration |
+| `tests/modes/test_k3d_mode.py` | k3d unit + integration tests |
+| `tests/modes/fixtures/knoe-db-test.yaml` | Minimal CNPG `Cluster` CR for test use (single instance, tiny storage) |
+| `tests/modes/fixtures/cnpg-operator-values.yaml` | Minimal Helm values for CNPG operator in CI |
+
+### `.gitea/workflows/ci-k3d.yml`
+
+```yaml
+name: CI — k3d mode
+
+on:
+ push:
+ branches: [main]
+
+jobs:
+ k3d-unit:
+ runs-on: [self-hosted, macos, k3d]
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with: { python-version: "3.11" }
+ - run: pip install -r requirements.txt -r requirements-test.txt
+ - name: Unit tests (k3d, no cluster)
+ run: pytest -m "k3d and unit" --cov=knoe --cov-report=xml tests/
+ env:
+ PYTHONPATH: ${{ github.workspace }}
+ KNOE_MODE: k3d
+ - uses: actions/upload-artifact@v4
+ with: { name: coverage-k3d-unit, path: coverage.xml }
+
+ k3d-integration:
+ runs-on: [self-hosted, macos, k3d]
+ needs: k3d-unit
+ timeout-minutes: 25
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-python@v5
+ with: { python-version: "3.11" }
+ - run: pip install -r requirements.txt -r requirements-test.txt
+
+ - name: Install k3d + kubectl
+ run: |
+ brew install k3d kubectl
+
+ - name: Create test cluster
+ run: |
+ k3d cluster create knoe-ci \
+ --agents 1 \
+ --k3s-arg '--disable=traefik@server:0' \
+ --wait
+ kubectl cluster-info --context k3d-knoe-ci
+
+ - name: Deploy CNPG operator
+ run: |
+ kubectl apply --server-side \
+ -f https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/releases/cnpg-1.23.0.yaml
+ kubectl wait --for=condition=Available \
+ deployment/cnpg-controller-manager \
+ -n cnpg-system --timeout=120s
+
+ - name: Integration tests (live cluster)
+ run: |
+ pytest -m "k3d and integration" \
+ --cov=knoe \
+ --cov-report=xml \
+ -v \
+ tests/
+ env:
+ PYTHONPATH: ${{ github.workspace }}
+ KNOE_MODE: k3d
+ KUBECONFIG: ${{ env.HOME }}/.kube/config
+
+ - name: Tear down cluster
+ if: always()
+ run: k3d cluster delete knoe-ci
+
+ - uses: actions/upload-artifact@v4
+ with: { name: coverage-k3d-integration, path: coverage.xml }
+```
+
+### Tests to write in `tests/modes/test_k3d_mode.py`
+
+**Unit tests** (`@pytest.mark.k3d @pytest.mark.unit`):
+
+| Test | What it proves |
+|---|---|
+| `test_k3d_cluster_env_normalizes_to_dev` | `_normalize_cluster_env("dev") == "dev"` |
+| `test_welcome_k3d_card_sets_cluster_env_dev` | Card click → `cluster_env = "dev"` |
+| `test_k3d_nav_proceeds_through_cluster_screens` | k3d mode does NOT skip `init_cluster` |
+| `test_k3d_supabase_option_visible` | Supabase toggle is reachable in k3d nav flow |
+| `test_cluster_lifecycle_milestone_uses_k3d_script` | `ClusterLifecycleMilestone` calls k3d cluster-create command for `dev` env |
+
+**Integration tests** (`@pytest.mark.k3d @pytest.mark.integration`):
+
+| Test | What it proves |
+|---|---|
+| `test_k3d_cluster_api_is_reachable` | kubectl can reach `k3d-knoe-ci` API server |
+| `test_cnpg_operator_crds_registered` | `Cluster` CRD exists after operator deploy |
+| `test_knoe_db_cluster_pod_starts` | Apply test CR → at least one PostgreSQL pod reaches `Running` |
+| `test_database_accepts_connections` | psql `SELECT 1` succeeds against the CNPG service |
+| `test_cluster_delete_is_clean` | After delete, no k3d cluster named `knoe-ci` remains |
+
+### Commit Summary
+
+*(Fill in after phase lands)*
+
+### Resumption Checklist
+
+- [ ] Push to `main` triggers both `k3d-unit` and `k3d-integration` jobs in Gitea
+- [ ] `k3d-integration` passes (PostgreSQL pod reaches Running state)
+- [ ] Both coverage artifacts appear in the run summary
+- [ ] `k3d cluster list` shows no leftover `knoe-ci` cluster after the run
+
+---
+
+## Phase 3 — GKE Pipeline (GitLab CI, expanded)
+
+**Status:** 🔲 Not started
+**Depends on:** Phase 2 complete
+
+### What this phase does
+
+Replaces the current single-job `.gitlab-ci.yml` (which only runs `install.sh -S`) with a proper multi-stage pipeline: lint → unit tests → GKE integration tests → dead-code report → deploy. The unit test gate runs on every push; GKE integration runs on `main` only.
+
+### Architecture
+
+```
+push to any branch
+ │
+ ├─ stage: lint → python syntax + imports check
+ ├─ stage: test → pytest -m "unit" (every push)
+ │
+push to main only:
+ ├─ stage: test → pytest -m "gke and integration" (real GKE cluster)
+ ├─ stage: test → vulture dead-code report (allow_failure: true)
+ └─ stage: deploy → ./install.sh -S -c conf/service/prod.cfg
+```
+
+### Deliverables
+
+| File | Purpose |
+|---|---|
+| `.gitlab-ci.yml` | Full multi-stage pipeline replacing current single-job version |
+| `tests/modes/test_gke_mode.py` | GKE unit + integration tests |
+| `scripts/dead_code_analysis.py` | Cross-references coverage.json with vulture-report.txt, outputs three-tier report |
+
+### Required GitLab CI variables (project settings → CI/CD → Variables)
+
+| Variable | Value | Protected | Masked |
+|---|---|---|---|
+| `GCP_SA_KEY` | GCP service account JSON with `container.viewer` + `storage.objectViewer` on both clusters | ✅ | ✅ |
+| `GKE_REGION` | `us-west3` | | |
+| `GKE_APP_CLUSTER` | `knoe-dev-0` | | |
+| `GKE_DB_CLUSTER` | `knoe-cnpg-0` | | |
+
+### `.gitlab-ci.yml` (full replacement)
+
+```yaml
+stages:
+ - lint
+ - test
+ - report
+ - deploy
+
+variables:
+ PYTHON_VERSION: "3.11"
+ PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+cache:
+ paths: [.cache/pip]
+
+# ── Stage: lint ───────────────────────────────────────────────────────────────
+
+lint:
+ stage: lint
+ image: python:3.11-slim
+ script:
+ - pip install -r requirements-test.txt -q
+ - python -m py_compile knoe/**/*.py
+ - python -c "from knoe.ui.screens import KnoeInstaller"
+ rules:
+ - if: '$CI_PIPELINE_SOURCE == "push"'
+
+# ── Stage: test (unit — every push) ──────────────────────────────────────────
+
+unit-tests:
+ stage: test
+ image: python:3.11-slim
+ script:
+ - pip install -r requirements.txt -r requirements-test.txt -q
+ - pytest -m "unit and not integration"
+ --cov=knoe
+ --cov-report=xml
+ --cov-report=term-missing
+ -q
+ tests/
+ coverage: '/TOTAL.*\s+(\d+\%)/'
+ artifacts:
+ reports:
+ coverage_report:
+ coverage_format: cobertura
+ path: coverage.xml
+ paths: [coverage.xml]
+ expire_in: 7 days
+ rules:
+ - if: '$CI_PIPELINE_SOURCE == "push"'
+
+# ── Stage: test (GKE integration — main only) ─────────────────────────────────
+
+gke-integration:
+ stage: test
+ image: google/cloud-sdk:slim
+ timeout: 30 minutes
+ before_script:
+ - pip install -r requirements.txt -r requirements-test.txt -q
+ - echo "$GCP_SA_KEY" | gcloud auth activate-service-account --key-file=-
+ - gcloud config set project plenary-truck-485623-p7
+ - gcloud container clusters get-credentials $GKE_APP_CLUSTER
+ --region $GKE_REGION
+ - gcloud container clusters get-credentials $GKE_DB_CLUSTER
+ --region $GKE_REGION
+ script:
+ - pytest -m "gke and integration"
+ --cov=knoe
+ --cov-report=xml
+ -v
+ tests/
+ coverage: '/TOTAL.*\s+(\d+\%)/'
+ artifacts:
+ reports:
+ coverage_report:
+ coverage_format: cobertura
+ path: coverage.xml
+ paths: [coverage.xml]
+ expire_in: 30 days
+ rules:
+ - if: '$CI_COMMIT_BRANCH == "main"'
+
+# ── Stage: report (dead code — main only, never blocks build) ─────────────────
+
+dead-code:
+ stage: report
+ image: python:3.11-slim
+ allow_failure: true
+ script:
+ - pip install vulture -q
+ - vulture knoe/ --min-confidence 80 | tee vulture-report.txt
+ - python scripts/dead_code_analysis.py
+ --vulture vulture-report.txt
+ --coverage coverage.xml
+ --output dead-code-report.md
+ artifacts:
+ paths:
+ - vulture-report.txt
+ - dead-code-report.md
+ expire_in: 30 days
+ rules:
+ - if: '$CI_COMMIT_BRANCH == "main"'
+
+# ── Stage: deploy (main only) ─────────────────────────────────────────────────
+
+deploy-service:
+ stage: deploy
+ rules:
+ - if: '$CI_COMMIT_BRANCH == "main"'
+ script:
+ - ./install.sh -S -c conf/service/prod.cfg
+ environment:
+ name: production
+```
+
+### Tests to write in `tests/modes/test_gke_mode.py`
+
+**Unit tests** (`@pytest.mark.gke @pytest.mark.unit`):
+
+| Test | What it proves |
+|---|---|
+| `test_gke_cluster_env_normalizes_to_prod` | `_normalize_cluster_env("prod") == "prod"` |
+| `test_welcome_gke_card_sets_cluster_env_prod` | Card click → `cluster_env = "prod"` |
+| `test_gke_split_cluster_detected` | When `app_ctx != db_ctx`, split-cluster mode activates |
+| `test_garage_not_deployed_to_db_cluster` | CNPG cluster does not include Garage in GKE mode |
+| `test_gke_storage_class_validation` | `standard-rwo` raises quota error hint; `standard` passes |
+
+**Integration tests** (`@pytest.mark.gke @pytest.mark.integration`):
+
+| Test | What it proves |
+|---|---|
+| `test_gke_app_cluster_reachable` | kubectl can reach `knoe-dev-0` |
+| `test_gke_db_cluster_reachable` | kubectl can reach `knoe-cnpg-0` |
+| `test_cnpg_cluster_knoe_db_0_running` | `knoe-db` cluster in `knoe-db-0` namespace has 3 Ready instances |
+| `test_barman_backup_schedule_exists` | ScheduledBackup CR exists in `knoe-db-0` |
+| `test_garage_only_in_app_cluster` | No Garage pods in `knoe-cnpg-0` namespace |
+
+### Commit Summary
+
+*(Fill in after phase lands)*
+
+### Resumption Checklist
+
+- [ ] GitLab pipeline shows four stages: lint → test → report → deploy
+- [ ] `unit-tests` job passes on every push (not just main)
+- [ ] `gke-integration` passes on main (3 CNPG pods Running)
+- [ ] `dead-code` job produces a `dead-code-report.md` artifact
+- [ ] Deploy stage still works (`install.sh -S` exits 0)
+- [ ] GitLab shows coverage percentage on the merge request widget
+
+---
+
+## Phase 4 — Dead Code Identification
+
+**Status:** 🔲 Not started
+**Depends on:** Phase 3 complete (all three stable builds achieved)
+
+### What this phase does
+
+Runs the first systematic dead code analysis across the full codebase. This is not a cleanup sprint — it is *reconnaissance*. We generate a prioritised report and review it before deleting anything. The report becomes the input for Phase 5.
+
+### Why this matters
+
+The project has undergone several major renames (`prole` → `knoe`, various directory restructures). Code written for old layouts is likely still present. `knoe/core/actions.py` alone is 7,740 lines and almost certainly contains branches that no deployment mode ever exercises.
+
+### Tools
+
+| Tool | Role |
+|---|---|
+| `vulture` | Static analysis — finds unused functions, classes, imports |
+| `pytest --cov --cov-branch` | Dynamic analysis — lines/branches never executed during tests |
+| `scripts/dead_code_analysis.py` | Cross-references both outputs to produce a tiered report |
+
+### Three-tier output format
+
+```markdown
+## 🔴 Definite dead code (vulture-flagged AND 0% coverage)
+- knoe/core/ops/legacy_shell.py:47 — function `_old_prole_exec` (unused, 0% coverage)
+- ...
+
+## 🟡 Suspect (vulture-flagged OR 0% coverage, not both)
+- knoe/core/actions.py:4201 — function `_k8s_node_drain` (0% coverage, not flagged by vulture)
+- ...
+
+## 🟢 Live (covered by tests and vulture-clean)
+- (omitted from report for brevity)
+```
+
+### How to run locally
+
+```bash
+# 1. Full coverage run across all modes
+KNOE_MODE=min pytest -m min --cov=knoe --cov-append tests/
+KNOE_MODE=k3d pytest -m k3d --cov=knoe --cov-append tests/
+KNOE_MODE=gke pytest -m gke --cov=knoe --cov-append tests/
+coverage json # produces coverage.json
+
+# 2. Vulture scan
+vulture knoe/ --min-confidence 70 > vulture-report.txt
+
+# 3. Cross-reference
+python scripts/dead_code_analysis.py \
+ --vulture vulture-report.txt \
+ --coverage coverage.json \
+ --output dead-code-report.md
+
+# 4. Review
+open dead-code-report.md
+```
+
+### Deliverables
+
+| File | Purpose |
+|---|---|
+| `scripts/dead_code_analysis.py` | Cross-reference script (coverage.json + vulture output → tiered report) |
+| `dead-code-report.md` | Generated output — committed to repo for review, not production |
+| `docs/dead-code-review.md` | Human review notes — which 🔴 items are safe to delete vs accidentally flagged |
+
+### Commit Summary
+
+*(Fill in after phase lands)*
+
+### Resumption Checklist
+
+- [ ] `python scripts/dead_code_analysis.py` runs without error
+- [ ] `dead-code-report.md` contains all three tiers
+- [ ] The 🔴 list has been manually reviewed and each item categorised as "safe to delete" or "keep" in `docs/dead-code-review.md`
+- [ ] No production code deleted yet — this phase is report-only
+
+---
+
+## Phase 5 — Pruning and the Instructable Codebase
+
+**Status:** 🔲 Not started
+**Depends on:** Phase 4 report reviewed and approved
+
+### What this phase does
+
+This is the refactoring sprint. Using the Phase 4 report, we delete dead code in small, test-verified commits, raising the `fail_under` coverage threshold after each deletion. The end state is a codebase that a junior developer can read from top to bottom and fully understand.
+
+### Target metrics
+
+| Metric | Today (est.) | Target |
+|---|---|---|
+| Test coverage (unit) | ~40% | ≥ 80% |
+| Test coverage (integration) | ~10% | ≥ 60% |
+| `vulture --min-confidence 80` warnings | Unknown | 0 |
+| Lines in `knoe/core/actions.py` | 7,740 | < 2,000 |
+| Modules with zero test coverage | ~17 (`knoe/core/ops/`) | 0 |
+| `fail_under` in `pyproject.toml` | 0 | 75 |
+
+### Deletion protocol
+
+For each 🔴 item from the Phase 4 report:
+
+1. Write a test that would fail if the code were still needed (proves it's safe to delete)
+2. Delete the code
+3. Run `pytest` — all tests pass
+4. Commit with message: `prune: remove — dead code (vulture + 0% coverage)`
+5. Raise `fail_under` by 1–2 points
+
+This protocol means every deletion is backed by a test. The test suite grows *because* we prune.
+
+### The instructable codebase standard
+
+A module is "instructable" when:
+- Every public function has at least one test whose name reads as a plain English sentence
+- The test file for the module is shorter than the module itself
+- A junior developer can understand the module's purpose from the test names alone without reading the source
+
+Example of instructable test names:
+```python
+def test_min_mode_only_needs_homebrew_and_1password(): ...
+def test_k3d_mode_creates_cnpg_cluster_in_docker(): ...
+def test_welcome_card_click_routes_to_correct_nav_flow(): ...
+def test_kerberos_is_only_enabled_in_k3s_and_gke_modes(): ...
+```
+
+### Commit Summary
+
+*(Fill in after each deletion sprint)*
+
+### Resumption Checklist
+
+- [ ] `fail_under` has been raised at least once since Phase 4
+- [ ] Zero 🔴 items remain in `dead-code-report.md`
+- [ ] All modules in `knoe/core/ops/` have at least one test
+- [ ] CI passes on all three pipelines (min, k3d, gke)
+
+---
+
+## k3s Phase — Homelab Pipeline
+
+**Status:** ⏸ Deferred
+**Trigger:** Evaluate after GitLab CI (Phase 3) is stable
+
+### Notes for when this is ready
+
+- Runner: one of the physical k3s nodes (`myrddin.prole.org`, `gandalf.prole.org`, or `merlin.prole.org`) registered as a Gitea act_runner with labels `self-hosted,linux,k3s`
+- Integration tests will need `kubeconfig` for the k3s cluster and iSCSI storage access for CNPG
+- Kerberos integration is the unique test target here — `knoe-auth` deployment with embedded KDC
+- The `CNPG_ELIGIBLE_NODES` config var maps directly to tests that verify node affinity placement
+
+---
+
+## Appendix A — Pytest Marker Reference
+
+| Marker | When to use |
+|---|---|
+| `@pytest.mark.unit` | No external services, no file system writes, runs anywhere |
+| `@pytest.mark.integration` | Requires a running cluster, database, or network service |
+| `@pytest.mark.min` | Tests the min (containerd) deployment path |
+| `@pytest.mark.k3d` | Tests the k3d (local Docker cluster) deployment path |
+| `@pytest.mark.k3s` | Tests the k3s (homelab) deployment path |
+| `@pytest.mark.gke` | Tests the GKE (production) deployment path |
+
+Combining markers is the norm: `@pytest.mark.k3d @pytest.mark.integration` means "requires a live k3d cluster".
+
+---
+
+## Appendix B — Runner Registration Quick Reference
+
+### Gitea act_runner (macOS)
+
+```bash
+# Install
+brew install act-runner
+
+# Register (run once per machine)
+act_runner register \
+ --instance https:/// \
+ --token \
+ --labels "self-hosted,macos,min" # or min,k3d for the Docker machine \
+ --name "knoe-min-runner" # human-readable name in Gitea UI
+
+# Start as a service
+brew services start act-runner
+```
+
+### GitLab runner (existing)
+
+The existing GitLab runner is assumed to have `gcloud` CLI available. If not:
+```bash
+# On the runner host:
+curl https://sdk.cloud.google.com | bash
+gcloud components install gke-gcloud-auth-plugin
+```
+
+---
+
+## Appendix C — Coverage Increment Strategy
+
+Rather than setting an ambitious `fail_under` up front and having CI permanently broken, we raise it in steps as each phase lands:
+
+| After phase | `fail_under` |
+|---|---|
+| Phase 0 (foundation) | 0 (measure only) |
+| Phase 1 (min tests) | 15 |
+| Phase 2 (k3d tests) | 25 |
+| Phase 3 (gke tests) | 35 |
+| Phase 4 (dead code pruned) | 50 |
+| Phase 5 (full prune) | 75 |
+
+Each increment is a one-line change to `pyproject.toml` committed at the end of the phase.
diff --git a/docs/plans/README.md b/docs/plans/README.md
index 4b96ed7..2e64976 100644
--- a/docs/plans/README.md
+++ b/docs/plans/README.md
@@ -1,24 +1,43 @@
-# Plans (prole — customer deploy)
+# Plans
-This directory holds **plans specific to the prole.org customer deployment** of the knoe.dev platform.
+Engineering plans for the **knoe.dev** platform. Each document scopes one initiative — its strategic context, design, schema, and the components it adds — and is intended to outlive the implementation work itself: when the work ships, the plan stays as the architectural reference.
+
+## Who this is for
+
+You are a junior or mid-level engineer who has been invited to contribute to knoe.dev. These documents are written for you. They assume:
+
+- You are comfortable reading code and skimming a Maven `pom.xml`.
+- You have used Kubernetes at least casually (`kubectl get pods`, helm charts).
+- You may **not** have prior Kerberos, OIDC, or CNPG experience — relevant terms are defined inline or in the glossary section of each plan.
+- You have not seen this repo before. Each plan starts with the strategic context and links to existing code before it asks you to write any.
+
+If a sentence in a plan assumes knowledge you don't have, that's a bug in the plan — open an issue.
## What lives here
-| File | Purpose |
-| --- | --- |
-| [`customer-deploy-resync.md`](customer-deploy-resync.md) | The active plan to converge this working tree onto `knoe-db/main` as a long-lived customer branch. |
+| File | Initiative | When you should read it |
+| --- | --- | --- |
+| [`knoe-auth-round-1.md`](knoe-auth-round-1.md) | Identity backbone for the platform: MIT Kerberos KDC + invite-anchored web enrollment + TOTP 2FA. Round 1 of N. **Shipped.** | Before touching `authority/`, `etc/init_kdc.sh`, `etc/init_knoe_users.sh`, anything in `deploy/gcp/gke/knoe-auth-*` or `knoe-kdc-*`, or the `knoe.*` database schema. |
+| [`deployment-modes.md`](deployment-modes.md) | Four-mode installer (`min` / `k3d` / `k3s` / `gke`) with a welcome-screen mode selector and a `min`-mode fast-path through the wizard. **Shipped in Phase 0.** | Before touching `knoe/ui/screens/welcome.py`, `knoe/ui/screens/navigation.py`, or adding any new wizard screen. |
-## What does **not** live here
+Each plan follows the same shape: **Context → How it's wired (file references) → Architecture → Schema / API → Step-by-step → Verification → Glossary.**
-Platform-level plans live upstream in `~/dev/knoe-db/docs/plans/`:
+## Status conventions
-- [`knoe-auth-round-1.md`](../../../knoe-db/docs/plans/knoe-auth-round-1.md) — Kerberos identity + invite-OTP enrollment + TOTP. Architectural reference.
-- [`deployment-modes.md`](../../../knoe-db/docs/plans/deployment-modes.md) — Four-mode installer + welcome-screen selector. Architectural reference.
+A plan in this directory has one of three statuses, declared at the top:
-(Paths above are relative to your `~/dev/` root. If you're reading this on the file server, navigate to the `knoe-db` checkout.)
+- **Active plan. Not yet implemented.** — the design is agreed, the code isn't there yet. Read deliverables top-to-bottom.
+- **Implemented and operational. Architectural reference.** — the work shipped. The doc explains how it works and *why*; cross-references point at real files. Read the context and the rationale; jump to specific sections when you have a question.
+- **Archived.** — superseded by a later round or a different approach. Lives in `archive/` with a one-line "see X instead" pointer.
-## Why the split
+## Customer deploys
-`prole` is being converged into a customer-deploy branch in `knoe-db`, not a separate fork. Platform docs travel with the platform code (in `knoe-db`); customer-deploy-specific docs travel with the customer branch (here). When the customer branch is published in `knoe-db`, this directory will move with it.
+The knoe.dev platform supports per-customer deployments — currently the most active is `prole.org`. The convention is **branches in this repo**, not separate forks. Customer-specific divergence (config, branding, on-prem manifests, kubeconfig handling) lives on a branch named after the customer; platform changes always land on `main` and customer branches rebase or merge from main on a regular cadence. See the customer's own `docs/plans/` for resync notes — for example, `~/dev/prole/docs/plans/customer-deploy-resync.md` if you have that working tree checked out.
-See the upstream `~/dev/knoe-db/docs/plans/README.md` for the full conventions on writing plans, plan statuses, and how customer deploys are structured.
+## How to propose a new plan
+
+1. Copy `knoe-auth-round-1.md` as a template — the section structure is the convention.
+2. Lead with **why** (one or two paragraphs). Half the value of a plan is forcing the author to articulate the motivation.
+3. Cite real files with paths relative to the repo root. If you reference something that doesn't exist yet, label it **(net-new)** so a reader doesn't go hunting.
+4. End with a **Verification** section — a short checklist a reviewer can run to decide whether the plan is done, or — once shipped — that the implementation still matches the spec.
+5. Open an MR. Plans are reviewed like code.
diff --git a/docs/plans/deployment-modes.md b/docs/plans/deployment-modes.md
new file mode 100644
index 0000000..9a70640
--- /dev/null
+++ b/docs/plans/deployment-modes.md
@@ -0,0 +1,188 @@
+# Deployment Modes — Welcome Screen + Wizard Fast-Path
+
+**Status:** Implemented and operational. Architectural reference. Welcome-screen mode selector and `min`-mode fast-path shipped in Phase 0.
+**Owner:** chrisfu
+**Audience:** Jr/mid engineer onboarding to knoe.dev. Familiarity with Tk/tkinter helps but is not required.
+
+---
+
+## 1. Context
+
+The knoe-db installer (`./install.sh` / `./knoe.sh install`, driven by the Tk UI in `knoe/ui/screens/`) supports four ways to deploy the platform. Different audiences, different hardware, but **the same architecture underneath**.
+
+Earlier installer revisions assumed the engineer already knew which mode they wanted, presented a welcome screen that was a wall of text, and shipped a sidebar tab strip (`k3d` / `k3s` / `k8s`) that didn't reliably refresh state across screens. Phase 0 replaced all of that with a first-screen mode selector that teaches the engineer what each mode *is* before asking them to choose, and added a `min`-mode fast-path that skips wizard screens irrelevant to a single-container deployment.
+
+### The four modes
+
+| Mode | What it is | Who it's for | Required tools |
+| --- | --- | --- | --- |
+| **min** | A single `knoe-db` container under `containerd` — no Kubernetes, no Docker. The Spring Boot app runs locally on the host. | Engineers running a Spring app on a laptop and wanting a CNPG-compatible Postgres without a full cluster. | Homebrew, 1Password |
+| **k3d** | A Docker-based local k3s cluster. Full CNPG + optional Supabase / ArgoCD / Gitea / GitLab. | Local development with the full platform. | Docker, Homebrew, 1Password |
+| **k3s** | A multi-node k3s cluster on real hardware. Full Kerberos auth stack, Garage S3, monitoring. Mirrors the GKE shape. | Homelab contributors with their own hardware (e.g. a 3-node Pi cluster). | k3sup, Homebrew, 1Password |
+| **gke** | The production dual-cluster on Google Cloud (`knoe-dev-0` + `knoe-cnpg-0` in `us-west3`). | Production. | gcloud, kubectl, 1Password |
+
+The architectural commitment matters: **all four modes are scaled-down mirrors of the GKE shape.** Not parallel implementations of the same idea, not divergent forks — the same components composed at different scales. CNPG runs in all four. The Spring Boot `authority` service runs in all four. `knoe.user` lives in the same schema in all four. The only thing that changes is what platform the components run on and which optional services are enabled.
+
+### Mode → cluster_env mapping
+
+| `cluster_env` | `KNOE_MODE` | Target |
+| --- | --- | --- |
+| `dev` | `k3d` | Local K3d cluster |
+| `service` | `k3s` | On-prem K3s cluster |
+| `prod` | `k8s` (alias `gke`) | GKE (or other cloud) |
+| `min` | `min` | Local containerd (no Kubernetes) |
+
+The conversion lives in `knoe/core/env.py` (`_deployment_mode_from_env()`).
+
+### Config file mapping
+
+`knoe/knoe_conf.py` maps environments to config files under `conf/`:
+
+| Mode | Config file |
+| --- | --- |
+| `min` | `conf/min.cfg` |
+| `k3d` (`dev`) | `conf/k3d.cfg` |
+| `k3s` (`service`) | `conf/k3s.cfg` |
+| `gke` (`prod`) | `conf/gke.cfg` |
+
+Config is layered: env-specific file overrides base. `KNOE_CONF` env var or `conf/service/` subdirs point to the active config.
+
+---
+
+## 2. How it's wired — file map
+
+| Component | Location | What's there |
+| --- | --- | --- |
+| Welcome screen with mode selector | `knoe/ui/screens/welcome.py` | `WelcomeScreenMixin._render_welcome_page()` renders the four mode cards. Click handler updates `deployment_mode` and `cluster_env`, redraws card borders, re-evaluates the Next gate. |
+| Sidebar nav | `knoe/ui/screens/navigation.py` | `_create_sidebar_nav()` no longer renders the old `k3d/k3s/k8s` tab strip — the welcome card selector replaces it. `_set_deployment_mode` is still called from the welcome handler. |
+| Mode/state initialization | `knoe/ui/screens/__init__.py` | `nav_items` list, `deployment_mode = tk.StringVar(...)`, `cluster_env = tk.StringVar(...)`. |
+| Wizard transitions | `knoe/ui/screens/navigation.py` `on_next` / `on_prev` | Min-mode fast-path skips screens that don't apply (network scan, cluster init, Kerberos, ArgoCD, Supabase, common services). |
+| Update-footer Next-button gate | `knoe/ui/screens/navigation.py` `update_footer` | Welcome screen disables Next until a mode is selected. |
+| Min-mode bootstrap | `etc/init_min.sh` | Idempotent: ensures Homebrew + containerd, pulls and runs the `knoe-db` container locally, runs schema bootstrap, prints connection info. Invoked from `init_scripts` step in min mode. |
+| Min-mode config | `conf/min.cfg` | Modeled on `conf/k3d.cfg`. Just what `init_min.sh` needs. |
+| Min-mode lifecycle | `knoe.sh` (`start` / `stop` / `restart` subcommands) | Manages the local containerd `knoe-db` instance for users who don't want to run the wizard every time. |
+
+---
+
+## 3. UI layout — welcome screen
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ │
+│ knoe.dev │
+│ infrastructure.auto() │
+│ │
+│ Welcome │
+│ ─────── │
+│ Knoe.DB sets up a production-grade PostgreSQL cluster with │
+│ Kerberos authentication. Pick the mode that matches your │
+│ hardware — we'll walk you through every step. │
+│ │
+│ ┌────────────┬────────────┬────────────┬────────────┐ │
+│ │ min │ k3d │ k3s │ gke │ │
+│ │ Just a │ Local │ Homelab │ Production│ │
+│ │ Database │ Cluster │ │ │ │
+│ │ One knoe-db│ k3s-in- │ Multi-node │ Dual GKE │ │
+│ │ container │ Docker │ k3s on real│ clusters on│ │
+│ │ via │ cluster on │ hardware. │ Google │ │
+│ │ containerd.│ your Mac. │ Full │ Cloud. │ │
+│ │ No K8s. │ Full CNPG │ Kerberos │ CNPG + │ │
+│ │ Perfect for│ database — │ auth stack,│ GCS backups│ │
+│ │ a Spring │ add │ Garage S3, │ + Workload │ │
+│ │ app on your│ Supabase, │ monitoring.│ Identity. │ │
+│ │ laptop. │ ArgoCD, │ │ │ │
+│ │ │ Gitea, or │ │ │ │
+│ │ │ GitLab. │ │ │ │
+│ │ Homebrew + │ Docker + │ k3sup + │ gcloud + │ │
+│ │ 1Password │ Homebrew + │ Homebrew + │ 1Password │ │
+│ │ │ 1Password │ 1Password │ │ │
+│ └────────────┴────────────┴────────────┴────────────┘ │
+│ │
+│ You'll need: Docker · Homebrew · 1Password │
+│ │
+│ [ Next → ] │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Behavior:
+
+- The four cards are clickable.
+- The selected card gets a colored border in the mode's accent color (`_MODE_COLORS`: `min` purple, `k3d` blue, `k3s` green, `gke` orange).
+- The "You'll need:" line below the cards updates to reflect the selected mode's tools.
+- The Next button is **disabled** until a mode is selected.
+- Selecting a card also sets `cluster_env` via the mode-to-cluster_env map.
+- On Next, mode is persisted to `knoe_cfg_data["Global"]["DEPLOYMENT_MODE"]`.
+
+---
+
+## 4. Wizard transitions — `min`-mode fast-path
+
+### Default flow (k3d / k3s / gke)
+
+```
+welcome → network_scan → env_setup → init_cluster → cluster_nodes →
+init_password → init_scripts → kerberos_config → knoe_users →
+argocd_config → gitops_config → supabase_config → common_services →
+… → security
+```
+
+### Min-mode flow
+
+```
+welcome → dependencies → environment → init_password → init_scripts → security
+```
+
+Skipped in min: `network_scan`, `init_cluster`, `cluster_nodes`, `kerberos_config`, `knoe_users`, `argocd_config`, `gitops_config`, `supabase_config`, `common_services`. None of them apply when there's no Kubernetes cluster and no Kerberos KDC. `init_scripts` invokes `etc/init_min.sh` instead of the cluster-mode init scripts.
+
+The fast-path is implemented as a `_min_mode_next` dictionary in `knoe/ui/screens/navigation.py` consulted from `on_next` / `on_prev`. The override is only active when `_is_min_mode()` returns true.
+
+---
+
+## 5. Verification
+
+Run after any change touching the wizard or mode logic.
+
+1. `./install.sh` opens. The welcome screen shows four mode cards. The sidebar has **no** k3d/k3s/k8s tab strip.
+2. With no mode selected, the Next button is disabled.
+3. Click the **min** card. Next becomes enabled. Click Next.
+ - The wizard skips the network-scan screen.
+ - It skips `init_cluster` and `cluster_nodes`.
+ - It skips `kerberos_config`, `knoe_users`, `argocd_config`, `gitops_config`, `supabase_config`, `common_services`.
+ - It runs `init_min.sh` at the `init_scripts` step.
+ - It lands on the `security` screen.
+ - Going back through `on_prev` walks the same trimmed sequence in reverse without hitting any skipped screens.
+4. Click the **k3d** card on a fresh run. The wizard follows the existing k3d flow exactly as before.
+5. `python3 -c "from knoe.ui.screens import KnoeInstaller"` — no import errors.
+6. After completing min mode, `nerdctl ps` shows the `knoe-db` container running locally and `psql "${printed_conn_string}" -c '\dt knoe.*'` lists the `knoe.user` table.
+7. `./knoe.sh stop` and `./knoe.sh start` cleanly stop/restart the local containerd instance.
+
+---
+
+## 6. Out of scope
+
+- A `min`-mode equivalent of the full Kerberos auth stack. Min is "just a database". Auth in min is a follow-up.
+- Migrating an existing `k3d` deployment to `min` (or any other mode-to-mode migration). Each mode is an independent target.
+- A unified package format that produces all four mode-specific installers from one `pyinstaller` build. The current per-mode build is fine.
+- Letting one wizard run install *multiple* modes (e.g. set up `k3d` and `gke` from the same session). One mode per run.
+
+---
+
+## 7. Glossary
+
+**k3s** — A lightweight Kubernetes distribution by Rancher Labs. Single binary, runs comfortably on a Raspberry Pi. The same project, two delivery shapes: `k3d` is k3s wrapped in Docker; bare k3s is k3s on actual hardware.
+
+**k3d** — A wrapper that runs k3s clusters inside Docker containers. Useful for local dev because it gives you a "real" Kubernetes cluster without having to provision VMs.
+
+**GKE (Google Kubernetes Engine)** — Google Cloud's managed Kubernetes. We use Standard for `knoe-dev-0` and `knoe-cnpg-0`. See `CLAUDE.md` for cluster topology.
+
+**containerd** — A container runtime. Speaks the OCI image and runtime specs. Both Docker and Kubernetes use containerd under the hood. In `min` mode we talk to it directly via `nerdctl`, skipping Docker entirely.
+
+**nerdctl** — A Docker-CLI-compatible client for `containerd`. If you know `docker run`, you know `nerdctl run`.
+
+**CNPG (CloudNativePG)** — The Postgres operator we use for `knoe-db`. See `CLAUDE.md` for which cluster runs it in production.
+
+**`cluster_env`** — A label the installer carries internally that picks which `conf/*.cfg` file to read and which downstream config branches to take. Maps from `deployment_mode` per the table in §1. Don't reuse this name for new variables — it's already overloaded enough.
+
+**Tk / tkinter** — Python's standard GUI toolkit. The installer is built on it. Canvas-based rendering means we draw text and shapes directly rather than using Tk's widget hierarchy for the welcome screen.
+
+**Wizard / pid** — The installer is a multi-screen wizard. Each screen has a "page id" (`pid`) — `welcome`, `network_scan`, `init_cluster`, etc. `nav_items` is the ordered list; `on_next` / `on_prev` decide transitions based on the current `pid` and the user's state.
diff --git a/docs/plans/knoe-auth-round-1.md b/docs/plans/knoe-auth-round-1.md
new file mode 100644
index 0000000..1428bb9
--- /dev/null
+++ b/docs/plans/knoe-auth-round-1.md
@@ -0,0 +1,483 @@
+# knoe-auth Round 1 — Durable Kerberos Identity + Contributor Onboarding
+
+**Status:** Implemented and operational. Architectural reference.
+**Owner:** chrisfu
+**Audience:** Jr/mid engineer onboarding to knoe.dev. No prior Kerberos or OIDC experience assumed.
+
+---
+
+## 1. Context
+
+`knoe-auth` is the identity system for the knoe.dev platform — the thing that decides who you are, what you can access, and how new contributors come on board. It is a long-term, multi-round initiative. This document is the architectural reference for **Round 1**, which is shipped.
+
+### The chicken-and-egg problem
+
+To build a sophisticated identity provider safely, the team needs to be able to authenticate themselves against *something* trustworthy in the meantime. We needed a working auth store *before* we could safely build the better one.
+
+Round 1 leans on a tool that has been doing this job for thirty-five years: **MIT Kerberos**. It is unfashionable but well-understood, cryptographically sound, and we already had it running in our k3s homelab cluster. We extended it to GKE, wrapped a small enrollment portal around it, and use that to onboard contributing engineers while Round 2 (a full OIDC provider) is being built.
+
+### Why Kerberos
+
+Kerberos *principals* are durable, DNS-like identifiers. `chrisfu@KNOE.DEV` is a stable cryptographic identity that survives any change to our web stack, our database, or our cloud provider. Once a principal exists in the KDC, it can issue tickets that any kerberized service trusts — Spring Boot via SPNEGO, Postgres via `gss` auth, SSH, NFS — without each of those services needing its own user table.
+
+That's the asset Round 1 builds on.
+
+### Two independent Google Workspaces — do not conflate
+
+| Workspace | Role |
+| --- | --- |
+| `knoe.dev` | Internal Google Workspace for the platform. Has zero pre-knowledge of any contributor's home org. |
+| `prole.org` | Workspace of the first contributing engineer's organization. Independently operated. |
+
+`knoe.dev` does **not** trust `prole.org` as a domain. `prole.org` is just one engineer's email provider, no different from `gmail.com` or any other workspace a future contributor might use. Trust between knoe.dev and a new contributor is bootstrapped by the **invite**, not by the contributor's home Google domain.
+
+### Trust model — the most important paragraph in this document
+
+When a new engineer enrolls, the trust sequence is:
+
+1. **An admin sends an invite to a specific email address or phone number.** That contact channel — and only that channel — is the trust anchor. The admin's choice of who to invite **is** the policy.
+2. **The engineer proves they control that contact** by entering a one-time password (OTP) delivered to it. Until the OTP verifies, no further steps are possible.
+3. **Only after the OTP gate** is the engineer offered a Google sign-in to *corroborate* their identity. The Google sign-in is welcomed in *after* trust is already established by the invite — it is not the source of trust.
+4. **TOTP** (the rotating six-digit code from Google Authenticator / Authy) is set up as the ongoing 2FA credential.
+5. **Only then** is a Kerberos principal minted, a `knoe.user` row inserted, and downstream provisioning jobs (GitLab account, Gitea account) queued.
+
+This means knoe.dev never needs to pre-configure trust with any external workspace. The OAuth2 app does **not** restrict by Google `hd` (hosted domain) — any verified Google account works. The contributor's home domain is *recorded* for audit (`knoe.identity.provider_hd`) but never used to gate access.
+
+If you remember nothing else: **the invite OTP is the trust anchor. Google is corroboration. TOTP is the ongoing factor.**
+
+---
+
+## 2. How it's wired — file map
+
+The actual files that implement Round 1. Verify with `git ls-files` before assuming any of the below has rotted.
+
+### Java application — `authority/`
+
+The Spring Boot service that implements the enrollment flow, the admin API, and SPNEGO-protected endpoints. Multi-module Maven build (`authority/pom.xml`); the application package is `org.prole.authority` (kept as-is across the prole→knoe rebrand for compatibility).
+
+| File | Responsibility |
+| --- | --- |
+| `authority/src/main/java/org/prole/authority/KnoeAuthApplication.java` | `@SpringBootApplication` entry point. |
+| `authority/src/main/java/org/prole/authority/HealthController.java` | `/health` endpoint. |
+| `authority/src/main/java/org/prole/authority/web/LoginController.java` | Form-login + SPNEGO challenge for browsers without a ticket. |
+| `authority/src/main/java/org/prole/authority/web/VerifyController.java` | Token-verify endpoint for downstream services. |
+| `authority/src/main/java/org/prole/authority/session/SessionTokenService.java` | Issues HMAC-SHA256 JWT cookies after successful auth. |
+| `authority/src/main/java/org/prole/authority/session/SessionUser.java` | Authenticated principal carried in the security context. |
+| `authority/src/main/java/org/prole/authority/user/PrincipalNormalizer.java` | Strips realm/instance from a Kerberos principal (`alice/admin@KNOE.DEV` → `alice`). |
+| `authority/src/main/java/org/prole/authority/kerberos/KerberosSpnegoService.java` | SPNEGO challenge/response handling. |
+| `authority/src/main/java/org/prole/authority/kerberos/KerberosPasswordService.java` | Password-style auth fallback for browsers that can't do SPNEGO. |
+| `authority/src/main/java/org/prole/authority/kerberos/KadminClient.java` | Shells out to `kadmin.local` (in the KDC sidecar) to `addprinc` and `cpw`. **Sanitizes input.** |
+| `authority/src/main/java/org/prole/authority/enroll/EnrollmentController.java` | Web endpoints: `GET /auth/enroll`, `POST /auth/enroll/verify-otp`, `POST /auth/enroll/identity/start`, `GET /auth/enroll/google-callback`, `GET /auth/enroll/totp`, `POST /auth/enroll/totp/verify`, `POST /auth/enroll/complete`. |
+| `authority/src/main/java/org/prole/authority/enroll/InviteService.java` | CRUD + validation against `knoe.invitation`. OTP hashing (bcrypt) and rate limiting (3 attempts). |
+| `authority/src/main/java/org/prole/authority/enroll/GoogleOAuthService.java` | Exchange OAuth2 code → ID token, validate `email_verified`, return a `GoogleIdentity` record. **No `hd` allowlist.** |
+| `authority/src/main/java/org/prole/authority/enroll/TotpService.java` | Generate TOTP secret, produce `otpauth://` URI, verify codes. |
+| `authority/src/main/java/org/prole/authority/enroll/UserProvisioningService.java` | Transactional orchestrator: inserts user/identity/totp rows, calls `KadminClient`, queues provisioning jobs. |
+| `authority/src/main/java/org/prole/authority/admin/AdminController.java` | `POST /auth/admin/invites`, `GET /auth/admin/users`, `POST /auth/admin/grants`. SPNEGO + admin-role gated. |
+| `authority/src/main/java/org/prole/authority/admin/KnobjectService.java` | CRUD on `knoe.knobject` and `knoe.access_grant`; enqueues `provisioning_job` rows. |
+| `authority/src/main/java/org/prole/authority/provisioning/ProvisioningWorker.java` | `@Scheduled` poller for `knoe.provisioning_job WHERE status = 'pending'`. Dispatches to GitLab/Gitea/CNPG. |
+| `authority/src/main/java/org/prole/authority/config/AuthProperties.java` | Typed binding for `knoe.auth.*` keys. |
+| `authority/src/main/java/org/prole/authority/config/KerberosProperties.java` | Typed binding for `knoe.auth.kerberos.*` keys. |
+
+Tests for the above live under `authority/src/test/java/org/prole/authority/` — notably `web/VerifyControllerTest.java` and `session/SessionTokenServiceTest.java`.
+
+### Kubernetes manifests — GKE
+
+| File | Purpose |
+| --- | --- |
+| `deploy/gcp/gke/knoe-kdc-configmap.yaml` | `krb5.conf` + `kdc.conf` for the `KNOE.DEV` realm. |
+| `deploy/gcp/gke/knoe-kdc-secrets.yaml` | Master key + admin password references. Production values come from OpenBao. |
+| `deploy/gcp/gke/knoe-auth-deployment.yaml` | KDC sidecar + Spring Boot pod. Service principal `HTTP/auth.knoe.dev@KNOE.DEV`. |
+| `deploy/gcp/gke/knoe-auth-google-oidc-secret.example.yaml` | Templated Secret with `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` placeholders. Real values are not committed. |
+| `deploy/gcp/gke/workload-identity.yaml` | KSA↔GSA bindings for any GCP-backed secret access. |
+
+### Kubernetes manifests — k3s (homelab and customer deploys)
+
+| File | Purpose |
+| --- | --- |
+| `deploy/opentofu/k3s/manifests/prole/prole-kdc-configmap.yaml` | The `PROLE.LOCAL` realm KDC for the homelab cluster. The pattern the GKE configmap was modeled on. |
+| `deploy/opentofu/k3s/manifests/prole/prole-kdc-secrets.example.yaml` | Templated secrets for the same. |
+| `deploy/opentofu/k3s/manifests/prole/prole-auth-deployment.yaml` | KDC + Spring Boot for the homelab. |
+| `deploy/opentofu/k3s/manifests/prole/prole-auth-kerberos-configmap.yaml` | `krb5.conf` for the auth pod's Kerberos client. |
+
+### Bootstrap scripts — `etc/`
+
+| File | Purpose |
+| --- | --- |
+| `etc/init_kdc.sh` | Provisions the in-cluster KDC. Idempotent. Read this end-to-end before writing anything that interacts with the KDC. |
+| `etc/init_knoe_users.sh` | Creates `knoe.user`, `knoe.user_role`, and (per Round 1) the additional auth tables; seeds initial principals via `kadmin.local`. |
+| `etc/init_kerberos.sh` | Cluster-wide krb5.conf wiring for kerberized services (Postgres, etc.). |
+
+---
+
+## 3. Architecture
+
+### The invite-to-enrolled flow at a glance
+
+```
+Invite URL
+https://auth.knoe.dev/enroll?token=
+ │
+ ├─ Step 1: Enter OTP (delivered to invite email/phone)
+ │ ─ Trust anchor. Without this, no further steps.
+ │
+ ├─ Step 2: Pick a username, link with Google (any account, any hd)
+ │ ─ Corroboration. Records provider_sub + provider_hd for audit.
+ │
+ ├─ Step 3: Scan QR with authenticator app, verify TOTP code
+ │ ─ Sets up the ongoing 2FA factor.
+ │
+ └─ Step 4: System provisions:
+ ├─ Kerberos principal: @KNOE.DEV
+ ├─ knoe.user row + knoe.identity link to Google subject
+ ├─ knoe.totp_credential row (encrypted secret)
+ └─ Async queue: GitLab account, Gitea account, …
+```
+
+### Cluster topology
+
+Round 1 lives in the GKE app cluster (`knoe-dev-0`) in the `knoe-system` namespace. The database stays where it already is — the dedicated CNPG cluster `knoe-cnpg-0`. See `CLAUDE.md` for the cluster layout and storage-quota rules.
+
+```
+knoe-dev-0 / knoe-system namespace:
+ ┌─ knoe-auth (Spring Boot) ─────────────────────────────────────────┐
+ │ /health │
+ │ /auth/login, /auth/spnego, /auth/verify │
+ │ /auth/enroll/* (invite → OTP → Google → TOTP → provision) │
+ │ /auth/admin/* (create invites, manage knobjects) │
+ └────────────────────────────────────────────────────────────────────┘
+ │ kadmin.local calls (KDC is a sidecar in the same pod)
+ ▼
+ ┌─ knoe-kdc (MIT Kerberos, KNOE.DEV realm) ─────────────────────────┐
+ │ Container pattern from prole-kdc-configmap.yaml │
+ │ Realm: KNOE.DEV │
+ │ Cross-realm trust with PROLE.LOCAL: deferred to Round 2 │
+ └────────────────────────────────────────────────────────────────────┘
+ │
+ ▼
+ ┌─ CNPG / knoe-db (in knoe-cnpg-0) ─────────────────────────────────┐
+ │ knoe.user (base table) │
+ │ knoe.user_role (base table) │
+ │ knoe.invitation (Round 1) │
+ │ knoe.identity (Round 1 — Google sub → knoe user) │
+ │ knoe.totp_credential (Round 1 — encrypted TOTP secret + backups) │
+ │ knoe.knobject (Round 1 — platform resources) │
+ │ knoe.access_grant (Round 1 — user → knobject grants) │
+ │ knoe.provisioning_job (Round 1 — async outbox) │
+ └────────────────────────────────────────────────────────────────────┘
+```
+
+The KDC runs as a sidecar in the same pod as the Spring Boot app. They share the pod network namespace, so `kadmin.local` calls reach the KDC over loopback — no Kubernetes Service required between them. This is the same pattern the k3s deployment uses.
+
+---
+
+## 4. Schema
+
+The `knoe.*` schema lives in CNPG (`knoe-cnpg-0` namespace `knoe-db-0`). Base tables (`knoe.user`, `knoe.user_role`) are created by `etc/init_knoe_users.sh` lines 482–510. Round 1 added the six tables below; they are created by the same script later in its run.
+
+```sql
+-- ────────────────────────────────────────────────────────────────────
+-- knoe.invitation — admin creates one of these per invited engineer.
+-- The (contact, otp_hash) pair IS the trust anchor for that engineer.
+-- ────────────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS knoe.invitation (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ token TEXT NOT NULL UNIQUE, -- URL token (long, random)
+ contact TEXT NOT NULL, -- email or phone the invite was sent to
+ contact_type TEXT NOT NULL DEFAULT 'email',-- 'email' | 'sms'
+ name_hint TEXT, -- optional display-name hint from admin
+ otp_hash TEXT NOT NULL, -- bcrypt of the 6-digit OTP
+ otp_expires_at TIMESTAMPTZ NOT NULL, -- short TTL (10 min)
+ otp_attempts INT NOT NULL DEFAULT 0, -- max 3 before invalidation
+ otp_verified_at TIMESTAMPTZ, -- set when OTP passes — gate for steps 2-4
+ created_by TEXT NOT NULL, -- admin username
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ expires_at TIMESTAMPTZ NOT NULL, -- invite URL TTL (72h)
+ used_at TIMESTAMPTZ, -- set at step-4 completion
+ used_by TEXT -- knoe username after use
+);
+
+-- ────────────────────────────────────────────────────────────────────
+-- knoe.identity — external identity corroborations.
+-- Round 1 only writes Google rows here; future providers reuse the table.
+-- ────────────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS knoe.identity (
+ id SERIAL PRIMARY KEY,
+ user_id INT NOT NULL REFERENCES knoe.user(id) ON DELETE CASCADE,
+ provider TEXT NOT NULL, -- 'google'
+ provider_sub TEXT NOT NULL, -- Google subject ID (stable per user)
+ provider_email TEXT,
+ provider_hd TEXT, -- 'prole.org' | 'gmail.com' | NULL — audit only
+ verified_at TIMESTAMPTZ NOT NULL,
+ UNIQUE(provider, provider_sub)
+);
+
+-- ────────────────────────────────────────────────────────────────────
+-- knoe.totp_credential — the rotating 2FA factor for ongoing logins.
+-- ────────────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS knoe.totp_credential (
+ user_id INT PRIMARY KEY REFERENCES knoe.user(id) ON DELETE CASCADE,
+ secret TEXT NOT NULL, -- AES-GCM encrypted, key in OpenBao
+ verified_at TIMESTAMPTZ, -- NULL until first successful verification
+ backup_codes TEXT[], -- bcrypt-hashed one-time recovery codes
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- ────────────────────────────────────────────────────────────────────
+-- knoe.knobject — platform-managed resources (a "knobbed object",
+-- something an admin can hand to a user).
+-- ────────────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS knoe.knobject (
+ id SERIAL PRIMARY KEY,
+ type TEXT NOT NULL, -- 'gitea_repo' | 'gitlab_project' | 'cnpg_role' | 'openbao_policy'
+ name TEXT NOT NULL,
+ platform_id TEXT, -- external identifier on target platform
+ metadata JSONB,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ UNIQUE(type, name)
+);
+
+-- ────────────────────────────────────────────────────────────────────
+-- knoe.access_grant — user ← knobject with role.
+-- ────────────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS knoe.access_grant (
+ id SERIAL PRIMARY KEY,
+ user_id INT NOT NULL REFERENCES knoe.user(id),
+ knobject_id INT NOT NULL REFERENCES knoe.knobject(id),
+ role TEXT NOT NULL, -- 'owner' | 'developer' | 'viewer'
+ granted_by TEXT NOT NULL,
+ granted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ revoked_at TIMESTAMPTZ,
+ UNIQUE(user_id, knobject_id)
+);
+
+-- ────────────────────────────────────────────────────────────────────
+-- knoe.provisioning_job — async outbox.
+-- A worker bean inside knoe-auth polls this table.
+-- ────────────────────────────────────────────────────────────────────
+CREATE TABLE IF NOT EXISTS knoe.provisioning_job (
+ id SERIAL PRIMARY KEY,
+ user_id INT NOT NULL REFERENCES knoe.user(id),
+ job_type TEXT NOT NULL, -- 'create_gitlab_user' | 'create_gitea_user' | 'grant_cnpg_role'
+ status TEXT NOT NULL DEFAULT 'pending', -- 'pending' | 'running' | 'done' | 'failed'
+ payload JSONB,
+ result JSONB,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+```
+
+---
+
+## 5. Configuration
+
+### `authority/.../application.properties` — relevant keys
+
+```properties
+knoe.auth.google.client-id=${GOOGLE_CLIENT_ID}
+knoe.auth.google.client-secret=${GOOGLE_CLIENT_SECRET}
+knoe.auth.google.redirect-uri=https://auth.knoe.dev/auth/enroll/google-callback
+
+# No allowed-domains list. Trust is established by invite OTP, not by the
+# developer's home Google domain. provider_hd is recorded in knoe.identity
+# for audit, never used for access control.
+
+knoe.auth.enroll.invite-ttl-hours=72
+knoe.auth.enroll.otp-ttl-minutes=10
+knoe.auth.enroll.otp-max-attempts=3
+knoe.auth.enroll.totp-issuer=knoe.dev
+
+knoe.auth.provisioning.poll-interval-ms=10000
+```
+
+### `pom.xml` — relevant dependencies
+
+```xml
+
+
+ dev.samstevens.totp
+ totp-spring-boot-starter
+ 1.7.1
+
+
+
+
+ com.google.api-client
+ google-api-client
+ 2.4.0
+
+```
+
+### Google OAuth2 app
+
+Configured by hand in the GCP console under project `plenary-truck-485623-p7`.
+
+- **Authorized redirect URIs:**
+ - `https://auth.knoe.dev/auth/enroll/google-callback` (Round 1 enrollment)
+ - `https://git.knoe.dev/...` (Gitea OIDC, future round)
+ - `https://git.prole.org/...` (GitLab OIDC, future round)
+- **No `hd=` restriction** at the OAuth app level. Deliberate.
+- Client ID and secret stored in a Kubernetes Secret modeled on `deploy/gcp/gke/knoe-auth-google-oidc-secret.example.yaml`.
+
+---
+
+## 6. Step-by-step enrollment flow
+
+This is what the engineer being onboarded actually experiences, what the server actually does, and where the trust transitions live.
+
+### Step 0 — Admin creates the invite
+
+```
+POST /auth/admin/invites
+Body: { contact: "chrisfu@prole.org", contact_type: "email", name_hint: "Chris Fu" }
+
+Server:
+ generate invite_token (UUID v4)
+ generate otp (6-digit numeric, 10-min TTL)
+ hash otp with bcrypt → otp_hash
+ insert into knoe.invitation
+ send email to chrisfu@prole.org:
+ Subject: "You've been invited to knoe.dev"
+ Body: invite URL + "Your verification code: 847291"
+```
+
+The OTP is delivered through the **same channel** as the invite URL. Both arrive in the engineer's inbox. The OTP is *not* sent to a side channel — its purpose is to prove possession of that inbox.
+
+### Step 1 — Engineer proves contact ownership (the trust gate)
+
+```
+GET /auth/enroll?token=
+ → InviteService validates token is not expired/used
+ → renders landing.html with the OTP entry form
+
+POST /auth/enroll/verify-otp { otp: "847291" }
+ → InviteService compares bcrypt(otp) with otp_hash, checks expiry
+ → on success: set otp_verified_at=now(), advance session to step 2
+ → on failure: increment otp_attempts; if >= 3, invalidate the invite and return 403
+```
+
+After this step, the session is gated. The remaining steps are unreachable without a verified OTP. **This is where the trust transition happens.**
+
+### Step 2 — Engineer picks a username and links Google
+
+```
+GET /auth/enroll/identity
+ → renders identity.html — username field + display-name field +
+ "Sign in with Google" button
+
+POST /auth/enroll/identity/start { username: "chrisfu", display_name: "Chris Fu" }
+ → store proposed username + display name in session
+ → redirect to Google OAuth2 authorize URL
+ (state=, nonce=, NO hd parameter)
+
+GET /auth/enroll/google-callback?code=&state=
+ → GoogleOAuthService exchanges code for ID token
+ → validates id_token.email_verified == true (REQUIRED)
+ → records provider_sub, provider_email, provider_hd
+ (provider_hd is whatever Google reports — prole.org, gmail.com, etc.)
+ → stores GoogleIdentity in session, advances to step 3
+```
+
+This step is **corroboration**, not authorization. The engineer's home Google workspace is not a trust source. We accept any verified Google account and record which domain it came from for audit purposes.
+
+### Step 3 — Engineer sets up TOTP
+
+```
+GET /auth/enroll/totp
+ → TotpService.generateSecret() — 160-bit base32 secret
+ → store the encrypted secret in the session (NOT yet in the DB)
+ → render totp-setup.html with:
+ • a QR code encoding otpauth://totp/knoe.dev:?secret=...&issuer=knoe.dev
+ • the 16-character manual key for users with no QR scanner
+ • "Open Google Authenticator / Authy and scan this code"
+
+POST /auth/enroll/totp/verify { code: "123456" }
+ → TotpService.verify(sessionSecret, code) — validates within ±1 30-second window
+ → on success: advance to step 4
+ → on failure: re-render with the same secret (don't rotate yet)
+```
+
+### Step 4 — System provisions
+
+```
+POST /auth/enroll/complete
+ → UserProvisioningService.provision(session) runs in a single transaction:
+ 1. INSERT INTO knoe.user (username, realm='KNOE.DEV', email, display_name)
+ 2. INSERT INTO knoe.identity (provider='google', sub, email, hd)
+ 3. INSERT INTO knoe.totp_credential (AES-encrypted secret, verified_at=now())
+ 4. KadminClient.addPrincipal("@KNOE.DEV")
+ 5. UPDATE knoe.invitation SET used_at=now(), used_by=
+ 6. INSERT INTO knoe.provisioning_job (job_type='create_gitea_user', payload={...})
+ 7. INSERT INTO knoe.provisioning_job (job_type='create_gitlab_user', payload={...})
+ → render complete.html with the engineer's new username and a "what happens next"
+ summary (their dev environment is being set up async, they'll get a follow-up email).
+```
+
+### Properties of this flow you can rely on
+
+- The OTP delivery channel is the identity proof. If the OTP arrives, the engineer owns that inbox.
+- knoe.dev never trusted `prole.org`. It trusted the admin's choice to send the invite to a `prole.org` address. Different thing.
+- The Google link captures the engineer's home workspace as audit data, but does not gate access.
+- TOTP becomes the ongoing 2FA factor. The Google sign-in is a one-time corroboration; logins after enrollment use Kerberos + TOTP.
+- `knoe.identity.provider_hd` records the home domain without pre-judging it.
+
+---
+
+## 7. Verification
+
+Run this end-to-end after any change touching the auth/Kerberos surface.
+
+1. `kubectl -n knoe-system get pods` — `knoe-auth` and `knoe-kdc` both Running.
+2. `curl https://auth.knoe.dev/health` returns 200.
+3. Hit `POST /auth/admin/invites` from an admin SPNEGO session, receive an invite URL.
+4. Open the enrollment URL in a fresh browser, complete all four steps using a real Google account in a non-`knoe.dev` workspace (e.g. `gmail.com`).
+5. `psql … -c "SELECT username, realm FROM knoe.user WHERE username = '';"` returns the row.
+6. `kinit @KNOE.DEV` from a machine that trusts the realm — succeeds.
+7. `psql … -c "SELECT job_type, status FROM knoe.provisioning_job WHERE user_id = (SELECT id FROM knoe.user WHERE username = '');"` shows `create_gitea_user` and `create_gitlab_user` rows.
+8. After the polling interval, those rows transition to `status = 'done'` and the corresponding accounts exist on the platforms.
+
+---
+
+## 8. Out of scope for Round 1
+
+Real, named items the team has discussed. They are **not** in Round 1 — when the team gets to them, each becomes its own plan in this directory.
+
+- Cross-realm trust between `KNOE.DEV` and `PROLE.LOCAL` (so a `chrisfu@PROLE.LOCAL` ticket can talk to a `KNOE.DEV` service). Round 2.
+- A full OIDC provider hosted by knoe-auth, replacing the dependence on Google for downstream services. Round 2.
+- SSO into kerberized Postgres roles (`gss` auth) so `knoe.user` rows map directly to database principals.
+- A "knobject inspector" admin UI. Right now the admin API is JSON-only.
+- Phone/SMS-based OTP delivery. Round 1 covers email; the `contact_type` column is already present on `knoe.invitation` so adding SMS later is additive.
+- Self-service password rotation, recovery flows, and deactivation. Admin-only for Round 1.
+
+---
+
+## 9. Glossary
+
+**KDC** — Key Distribution Center. The Kerberos server. Holds the master key for the realm; issues TGTs (ticket-granting tickets) and service tickets.
+
+**Kerberos principal** — A named identity in a realm. Format: `name@REALM` (or `service/host@REALM`). Example: `chrisfu@KNOE.DEV`. Long-lived, cryptographic, decoupled from any particular service's user table.
+
+**Realm** — A Kerberos administrative domain. Independent KDCs each own their own realm. `PROLE.LOCAL` and `KNOE.DEV` are two realms; cross-realm trust is configured separately.
+
+**Keytab** — A file containing one or more principals' long-term keys, used by services to authenticate to the KDC without an interactive password. Spring Boot reads its service principal's keytab at startup.
+
+**SPNEGO** — Simple and Protected GSSAPI Negotiation Mechanism. The HTTP-layer protocol that lets a browser holding a Kerberos ticket authenticate to a web app over the wire. RFC 4178. Spring Security has built-in support.
+
+**kadmin / kadmin.local** — The KDC's administration tool. `kadmin` runs over the network with admin credentials; `kadmin.local` runs on the KDC host itself, bypassing the network protocol. Round 1 calls `kadmin.local` from a sidecar container.
+
+**TGT (Ticket-Granting Ticket)** — The first ticket the KDC issues to a user after they prove their identity. Used to request further service tickets without re-entering credentials.
+
+**TOTP** — Time-based One-Time Password. RFC 6238. The rotating six-digit code Google Authenticator and Authy show. A shared secret + the current Unix time bucketed into 30-second windows produces the code.
+
+**OAuth2** — Authorization framework. Lets a user grant an app limited access to their account at another service. Concerns *delegation*, not *identity*.
+
+**OIDC (OpenID Connect)** — An identity layer on top of OAuth2. Adds the `id_token` (a signed JWT with claims about the user). When we say "Google sign-in" we mean OIDC over Google's OAuth2.
+
+**`hd` claim** — In a Google OIDC `id_token`, the user's hosted-domain (i.e. their Google Workspace). Optional, present only for Workspace accounts. We *record* it in `knoe.identity.provider_hd` for audit but do **not** gate access on it.
+
+**Workload Identity** — GKE feature that binds a Kubernetes ServiceAccount to a Google Cloud IAM service account. Lets pods talk to GCP APIs (e.g. KMS for our master key) without long-lived JSON keyfiles.
+
+**CNPG** — CloudNativePG. The Postgres operator we use for `knoe-db`. Runs in `knoe-cnpg-0`. See `CLAUDE.md` for cluster topology.
+
+**knobject** — A platform-managed resource that an admin can hand out to a user — a Gitea repo, a Postgres role, an OpenBao policy. The name is a portmanteau of "knoe" + "object". Modeled by `knoe.knobject`; granted via `knoe.access_grant`.
+
+**Round 1, Round 2, …** — Versioning convention for the auth roadmap. Each round is a self-contained, shippable increment. Round 1 stops where the platform can safely onboard contributing engineers; Round 2 introduces the OIDC provider; later rounds tighten the screws.
diff --git a/etc/hostprobe-myrddin.yaml b/etc/hostprobe-myrddin.yaml
index fb41747..2522f7b 100644
--- a/etc/hostprobe-myrddin.yaml
+++ b/etc/hostprobe-myrddin.yaml
@@ -4,7 +4,7 @@ metadata:
name: knoe-hostprobe-myrddin
namespace: kube-system
spec:
- nodeName: myrddin.knoe.org
+ nodeName: myrddin.prole.org
hostNetwork: true
hostPID: true
tolerations:
diff --git a/etc/hostprobe-pi.yaml b/etc/hostprobe-pi.yaml
index 058e6c6..b10fe89 100644
--- a/etc/hostprobe-pi.yaml
+++ b/etc/hostprobe-pi.yaml
@@ -4,7 +4,7 @@ metadata:
name: knoe-hostprobe-pi
namespace: kube-system
spec:
- nodeName: pi.knoe.org
+ nodeName: pi.prole.org
hostNetwork: true
hostPID: true
tolerations:
diff --git a/etc/hosts.txt b/etc/hosts.txt
index 905ae78..4e73115 100644
--- a/etc/hosts.txt
+++ b/etc/hosts.txt
@@ -1,15 +1,15 @@
-myrddin.knoe.org 10.0.0.3
-raspberry.knoe.org 10.0.0.4
-pi.knoe.org 10.0.0.5
-synology.knoe.org 10.0.0.203
-morgoth.knoe.org 10.0.0.204
-zinfandel.knoe.org 10.0.0.205
-aventage.knoe.org 10.0.0.206
-retropie.knoe.org 10.0.0.207
-fairyland.knoe.org 10.0.0.208
-k8s.knoe.org zinfandel.knoe.org
-mc.knoe.org 73.15.20.166
-morana.knoe.org 10.0.0.66
-ollama.knoe.org 73.15.20.166
-svc.knoe.org 73.15.20.166
-www.knoe.org ghs.googlehosted.com
\ No newline at end of file
+myrddin.prole.org 10.0.0.3
+raspberry.prole.org 10.0.0.4
+pi.prole.org 10.0.0.5
+synology.prole.org 10.0.0.203
+morgoth.prole.org 10.0.0.204
+zinfandel.prole.org 10.0.0.205
+aventage.prole.org 10.0.0.206
+retropie.prole.org 10.0.0.207
+fairyland.prole.org 10.0.0.208
+k8s.prole.org zinfandel.prole.org
+mc.prole.org 73.15.20.166
+morana.prole.org 10.0.0.66
+ollama.prole.org 73.15.20.166
+svc.prole.org 73.15.20.166
+www.prole.org ghs.googlehosted.com
\ No newline at end of file
diff --git a/etc/init_gitea.sh b/etc/init_gitea.sh
index 669bb99..523999d 100755
--- a/etc/init_gitea.sh
+++ b/etc/init_gitea.sh
@@ -88,7 +88,7 @@ GITEA_PV_NODE_SELECTOR_KEY="${GITEA_PV_NODE_SELECTOR_KEY:-${NODE_SELECTOR_KEY}}"
GITEA_PV_NODE="${GITEA_PV_NODE:-${GITEA_NODE_SELECTOR:-}}"
GITEA_PV_BASE_DIR="${GITEA_PV_BASE_DIR:-/synology/d005}"
GITEA_STORAGE_CLASS="${GITEA_STORAGE_CLASS:-gitea-local-d005}"
-GITEA_DOMAIN="${GITEA_DOMAIN:-git.knoe.org}"
+GITEA_DOMAIN="${GITEA_DOMAIN:-git.prole.org}"
GITEA_SSH_DOMAIN="${GITEA_SSH_DOMAIN:-$GITEA_DOMAIN}"
KNOE_DB_NAMESPACE="${KNOE_DB_NAMESPACE:-${DATABASE_NAMESPACE:-knoe-db}}"
KNOE_DB_CLUSTER="${KNOE_DB_CLUSTER:-${CLUSTER_NAME:-knoe-db}}"
diff --git a/etc/init_gitlab.sh b/etc/init_gitlab.sh
index 78898c2..6b5143c 100755
--- a/etc/init_gitlab.sh
+++ b/etc/init_gitlab.sh
@@ -1699,9 +1699,9 @@ check_gitlab_post_apply_blocked() {
log "Desired Gitaly state (from CR): nodeSelector=[${desired_gitaly_node_selector}], rendered.global.persistence.storageClass=[${rendered_global_sc:-}], rendered.gitlab.gitaly.persistence.storageClass=[${rendered_gitlab_gitaly_sc:-}], rendered.gitaly.persistence.storageClass=[${rendered_chart_gitaly_sc:-}]"
log "Internal script GITALY_STORAGE_CLASS=[${GITALY_STORAGE_CLASS:-}]"
- if [[ "$desired_cr" == *"gandalf.knoe.org"* ]]; then
+ if [[ "$desired_cr" == *"gandalf.prole.org"* ]]; then
repair_blocked "GitLab CR contains legacy nodeSelector" \
- "Desired GitLab CR still contains gandalf.knoe.org. This is a configuration bug."
+ "Desired GitLab CR still contains gandalf.prole.org. This is a configuration bug."
fi
if [[ "$desired_cr" == *"gitlab-gitaly-static"* ]]; then
repair_blocked "GitLab CR contains legacy storageClass" \
@@ -1733,7 +1733,7 @@ check_gitlab_post_apply_blocked() {
live_sts_yaml=$(kubectl -n "$NAMESPACE" get statefulset "$gitaly_sts_name" -o yaml 2>/dev/null || true)
if [[ -z "$live_sts_yaml" ]]; then
log "Gitaly StatefulSet not found (awaiting operator action)..."
- elif [[ "$live_sts_yaml" != *"gandalf.knoe.org"* && "$live_sts_yaml" != *"gitlab-gitaly-static"* ]]; then
+ elif [[ "$live_sts_yaml" != *"gandalf.prole.org"* && "$live_sts_yaml" != *"gitlab-gitaly-static"* ]]; then
log "Gitaly StatefulSet converged to corrected state (clean nodeSelector/storageClass)."
local _live_sc
_live_sc=$(echo "$live_sts_yaml" | grep "storageClassName:" | cut -d: -f2 | xargs || true)
@@ -1760,7 +1760,7 @@ check_gitlab_post_apply_blocked() {
if [[ "$converged" == "0" ]]; then
local live_sts_yaml
live_sts_yaml=$(kubectl -n "$NAMESPACE" get statefulset "$gitaly_sts_name" -o yaml 2>/dev/null || true)
- if [[ -n "$live_sts_yaml" && ( "$live_sts_yaml" == *"gandalf.knoe.org"* || "$live_sts_yaml" == *"gitlab-gitaly-static"* ) ]]; then
+ if [[ -n "$live_sts_yaml" && ( "$live_sts_yaml" == *"gandalf.prole.org"* || "$live_sts_yaml" == *"gitlab-gitaly-static"* ) ]]; then
log "Live StatefulSet still legacy after grace period. Performing explicit replacement..."
# We already confirmed desired CR is corrected at the start of this function.
kubectl -n "$NAMESPACE" delete statefulset "$gitaly_sts_name" --wait=true 2>/dev/null || true
@@ -1912,9 +1912,9 @@ check_gitlab_post_apply_blocked() {
cleanup_gitlab_wrong_gitaly_template_storage "${GITALY_STORAGE_CLASS:-}" "$live_gitaly_repo_data_template_sc" "$gitaly_pvc_mismatches" "$desired_cr"
fi
- if [[ "$gitaly_sts_yaml" == *"gandalf.knoe.org"* ]]; then
+ if [[ "$gitaly_sts_yaml" == *"gandalf.prole.org"* ]]; then
repair_blocked "Gitaly using legacy Synology storage" \
- "Resource: statefulset/${gitaly_sts_name}. Value: nodeSelector contains gandalf.knoe.org. Fix: Ensure GITLAB_STORAGE_NODE is not set in k8s mode."
+ "Resource: statefulset/${gitaly_sts_name}. Value: nodeSelector contains gandalf.prole.org. Fix: Ensure GITLAB_STORAGE_NODE is not set in k8s mode."
fi
if [[ "$gitaly_sts_yaml" == *"gitlab-gitaly-static"* ]]; then
repair_blocked "Gitaly using legacy Synology storage" \
@@ -2380,7 +2380,7 @@ REDIS_HOST="${GITLAB_REDIS_HOST:-redis-master.${REDIS_NAMESPACE}.svc.cluster.loc
REDIS_PORT="${GITLAB_REDIS_PORT:-6379}"
# GitLab public domain (configurable; default follows deployment mode)
-_default_gitlab_domain="git.knoe.org"
+_default_gitlab_domain="git.prole.org"
if [[ "$MODE" == "k8s" ]]; then
_default_gitlab_domain="git.knoe.dev"
fi
@@ -2418,7 +2418,7 @@ PRIMARY_GITLAB_HOST="${GITLAB_PUBLIC_HOSTS[0]}"
GITLAB_DOMAIN="$PRIMARY_GITLAB_HOST"
PRIMARY_GITLAB_DOMAIN_ROOT="${PRIMARY_GITLAB_HOST#*.}"
if [[ "$PRIMARY_GITLAB_DOMAIN_ROOT" == "$PRIMARY_GITLAB_HOST" || -z "$PRIMARY_GITLAB_DOMAIN_ROOT" ]]; then
- PRIMARY_GITLAB_DOMAIN_ROOT="knoe.org"
+ PRIMARY_GITLAB_DOMAIN_ROOT="prole.org"
fi
# Public ingress class (k8s/GKE defaults to gce; local clusters keep kong)
@@ -2513,7 +2513,7 @@ fi
# Requires k8s secret 'gitlab-google-oidc' in GITLAB_NAMESPACE with Google
# OAuth2 client credentials (client_id, client_secret, redirect_uri).
# To disable OIDC: unset FRONTDOOR_HOST before running.
-_default_auth_hostname="api.knoe.org"
+_default_auth_hostname="api.prole.org"
if [[ "$MODE" == "k8s" ]]; then
_default_auth_hostname="api.knoe.dev"
fi
@@ -2891,7 +2891,7 @@ setup_knoe_db_for_gitlab() {
}
# ---------------------------------------------------------------------------
-# Clean up any pre-existing Gitea / git.knoe.org configurations
+# Clean up any pre-existing Gitea / git.prole.org configurations
# ---------------------------------------------------------------------------
cleanup_gitea() {
log "Checking for pre-existing Gitea deployment to remove before GitLab install..."
@@ -2908,13 +2908,13 @@ cleanup_gitea() {
kubectl -n "$gitea_ns" delete deploy/gitea svc/gitea-http svc/gitea-ssh \
>/dev/null 2>&1 || true
- # Remove Kong routes/services registered for git.knoe.org (best-effort)
+ # Remove Kong routes/services registered for git.prole.org (best-effort)
local kong_ns="${KONG_NAMESPACE:-${NAMESPACE:-kong}}"
for res_type in kongplugins kongingresses; do
kubectl -n "$gitea_ns" delete "$res_type" --all >/dev/null 2>&1 || true
done
- # Remove gitea namespace Ingress objects that route git.knoe.org
+ # Remove gitea namespace Ingress objects that route git.prole.org
kubectl -n "$gitea_ns" delete ingress \
-l "app.kubernetes.io/name=gitea" >/dev/null 2>&1 || true
kubectl -n "$gitea_ns" delete ingress \
@@ -2945,7 +2945,7 @@ fi
# ---------------------------------------------------------------------------
# Always remove gitea if its helm release exists (non-destructive path)
-# gitea and gitlab both claim git.knoe.org; they cannot coexist.
+# gitea and gitlab both claim git.prole.org; they cannot coexist.
# ---------------------------------------------------------------------------
if helm -n "${GITEA_NAMESPACE:-gitea}" status gitea >/dev/null 2>&1; then
warn "Gitea release detected — removing to free git.knoe.org for GitLab..."
@@ -3070,7 +3070,7 @@ fi
if [[ "$MODE" == "k8s" ]]; then
# In k8s/GKE mode, we do NOT use static storage nodes or nodeSelectors.
STORAGE_NODE=""
- if [[ "$NODE_SELECTOR" == *"gandalf.knoe.org"* ]]; then
+ if [[ "$NODE_SELECTOR" == *"gandalf.prole.org"* ]]; then
warn "Stripping legacy nodeSelector '${NODE_SELECTOR}' in k8s mode."
NODE_SELECTOR=""
fi
@@ -3719,7 +3719,7 @@ setup_gitlab_storage() {
local gitaly_sts_yaml
gitaly_sts_yaml=$(kubectl -n "$NAMESPACE" get statefulset "$gitaly_sts_name" -o yaml 2>/dev/null || true)
if [[ -n "$gitaly_sts_yaml" ]]; then
- if [[ "$gitaly_sts_yaml" == *"gandalf.knoe.org"* || "$gitaly_sts_yaml" == *"gitlab-gitaly-static"* ]]; then
+ if [[ "$gitaly_sts_yaml" == *"gandalf.prole.org"* || "$gitaly_sts_yaml" == *"gitlab-gitaly-static"* ]]; then
has_legacy=1
fi
fi
@@ -3743,7 +3743,7 @@ setup_gitlab_storage() {
# Give it a moment to process deletions
sleep 2
else
- repair_blocked "Legacy Gitaly PV/PVC still bound to gitlab-gitaly-static / gandalf.knoe.org" \
+ repair_blocked "Legacy Gitaly PV/PVC still bound to gitlab-gitaly-static / gandalf.prole.org" \
"Set GITLAB_REPAIR_BLOCKED_AUTOCLEAN=1 to automatically repair by deleting legacy PVC/PV, or run:
kubectl -n $NAMESPACE scale sts ${GITLAB_RELEASE}-gitaly --replicas=0
kubectl -n $NAMESPACE delete pvc repo-data-gitlab-gitaly-0
diff --git a/etc/init_knoe_auth.sh b/etc/init_knoe_auth.sh
index 632a8dc..d257ef8 100755
--- a/etc/init_knoe_auth.sh
+++ b/etc/init_knoe_auth.sh
@@ -1,885 +1,376 @@
#!/usr/bin/env bash
+# init_knoe_auth.sh
+# Provision knoe-auth (Kerberos KDC + Spring Boot enrollment service) on GKE.
+#
+# Usage:
+# ./etc/init_knoe_auth.sh [--context KUBECONTEXT] [--namespace NAMESPACE] [--project PROJECT_ID]
+# ./etc/init_knoe_auth.sh initialize # full setup
+# ./etc/init_knoe_auth.sh schema # schema only (idempotent)
+# ./etc/init_knoe_auth.sh invite EMAIL # create first admin invite
+# ./etc/init_knoe_auth.sh status # check pod + principal state
+#
+# Prerequisites:
+# kubectl, op (1Password CLI), psql (or kubectl exec fallback)
+#
+# Env vars (override args):
+# APP_CLUSTER_KUBECONTEXT, KNOE_NAMESPACE, GCP_PROJECT_ID,
+# KNOE_DB_HOST, KNOE_DB_PORT, KNOE_DB_NAME, KNOE_DB_SUPERUSER
set -euo pipefail
-# init_knoe_auth.sh
-# Purpose:
-# - Provision the knoe-auth service (cluster-internal KDC + SSO gateway) in the
-# service namespace (knoe-system by default)
-# - knoe-auth acts as the authentication server trusted by CNPG and other cluster
-# services, and hosts the SSO gateway pod
-# - Optionally configure cross-realm trust to an external realm when credentials are provided
-# - Must complete before init_cloudnative_pg.sh so the database can depend on it
-#
-# Usage:
-# ./init_knoe_auth.sh initialize|update # create/update knoe-auth resources
-# ./init_knoe_auth.sh status # show knoe-auth status
-# ./init_knoe_auth.sh cleanup # remove knoe-auth resources
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+GKE_DIR="$REPO_ROOT/deploy/gcp/gke"
-SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+# ── Defaults ────────────────────────────────────────────────────────────────
+APP_CTX="${APP_CLUSTER_KUBECONTEXT:-gke_plenary-truck-485623-p7_us-west3_knoe-dev-0}"
+NAMESPACE="${KNOE_NAMESPACE:-knoe-system}"
+GCP_PROJECT="${GCP_PROJECT_ID:-plenary-truck-485623-p7}"
+DB_HOST="${KNOE_DB_HOST:-}" # resolved from CNPG svc if blank
+DB_PORT="${KNOE_DB_PORT:-5432}"
+DB_NAME="${KNOE_DB_NAME:-knoe}"
+DB_SUPERUSER="${KNOE_DB_SUPERUSER:-postgres}"
+REALM="KNOE.DEV"
+AUTH_HOST="${KNOE_AUTH_HOST:-https://auth.knoe.dev}"
-# shellcheck disable=SC1090
-source "$SCRIPT_DIR/knoe_cfg.sh"
+log() { echo "[init_knoe_auth] $*"; }
+info() { log "INFO $*"; }
+warn() { log "WARN $*" >&2; }
+die() { log "ERROR $*" >&2; exit 1; }
-if [[ "${1:-}" == "--mode" || "${1:-}" == "-m" ]]; then
- knoe_set_mode "${2:-}"
- shift 2
-elif [[ "${1:-}" == --mode=* || "${1:-}" == -m=* ]]; then
- knoe_set_mode "${1#*=}"
- shift
-fi
+kube() { kubectl --context="$APP_CTX" "$@"; }
-knoe_ensure_kubeconfig >/dev/null 2>&1 || true
-ensure_kube_context || exit 1
+# ── Argument parsing ─────────────────────────────────────────────────────────
+COMMAND="${1:-initialize}"
+shift || true
-ACTION=${1:-initialize}
-
-KNOE_AUTH_NAMESPACE=${KNOE_AUTH_NAMESPACE:-${SERVICE_NAMESPACE:-${NAMESPACE:-default}}}
-KDC_NAMESPACE="$KNOE_AUTH_NAMESPACE"
-KNOE_AUTH_ENABLED=${KNOE_AUTH_ENABLED:-${PROLE_KDC_ENABLED:-1}}
-KNOE_AUTH_NAME=${KNOE_AUTH_NAME:-knoe-auth}
-KNOE_AUTH_SERVICE=${KNOE_AUTH_SERVICE:-knoe-auth}
-KNOE_AUTH_IMAGE=${KNOE_AUTH_IMAGE:-${PROLE_KDC_IMAGE:-}}
-# If the user provided an explicit image, we should not require Docker unless
-# they explicitly opt into building.
-KNOE_AUTH_IMAGE_EXPLICIT=0
-if [[ -n "${KNOE_AUTH_IMAGE:-}" ]]; then
- KNOE_AUTH_IMAGE_EXPLICIT=1
-fi
-KNOE_AUTH_IMAGE_NAME=${KNOE_AUTH_IMAGE_NAME:-${PROLE_KDC_IMAGE_NAME:-knoe-authority}}
-KNOE_AUTH_IMAGE_TAG=${KNOE_AUTH_IMAGE_TAG:-${PROLE_KDC_IMAGE_TAG:-latest}}
-KNOE_AUTH_REGISTRY_HOST=${KNOE_AUTH_REGISTRY_HOST:-${PROLE_KDC_REGISTRY_HOST:-${LOCAL_REGISTRY:-localhost:5000}}}
-KNOE_AUTH_REGISTRY_INTERNAL=${KNOE_AUTH_REGISTRY_INTERNAL:-${PROLE_KDC_REGISTRY_INTERNAL:-${LOCAL_REGISTRY_INTERNAL:-}}}
-KNOE_AUTH_BUILD_IMAGE_SET=0
-if [[ -n "${KNOE_AUTH_BUILD_IMAGE+x}" ]]; then
- KNOE_AUTH_BUILD_IMAGE_SET=1
-elif [[ -n "${PROLE_KDC_BUILD_IMAGE+x}" ]]; then
- KNOE_AUTH_BUILD_IMAGE_SET=1
-fi
-KNOE_AUTH_BUILD_IMAGE=${KNOE_AUTH_BUILD_IMAGE:-${PROLE_KDC_BUILD_IMAGE:-1}}
-KNOE_AUTH_ROLLOUT_TIMEOUT=${KNOE_AUTH_ROLLOUT_TIMEOUT:-${PROLE_KDC_ROLLOUT_TIMEOUT:-5}}
-KNOE_AUTH_DEPLOY_TIMEOUT=${KNOE_AUTH_DEPLOY_TIMEOUT:-${PROLE_KDC_DEPLOY_TIMEOUT:-60}}
-KNOE_AUTH_HOST_NETWORK=${KNOE_AUTH_HOST_NETWORK:-${PROLE_KDC_HOST_NETWORK:-}}
-PROLE_KDC_REALM=${PROLE_KDC_REALM:-}
-PROLE_KDC_DOMAIN=${PROLE_KDC_DOMAIN:-}
-PROLE_KDC_ADMIN_PRINCIPAL=${PROLE_KDC_ADMIN_PRINCIPAL:-admin/admin}
-PROLE_KDC_ADMIN_PASSWORD=${PROLE_KDC_ADMIN_PASSWORD:-}
-PROLE_KDC_MASTER_PASSWORD=${PROLE_KDC_MASTER_PASSWORD:-}
-PROLE_KDC_TRUST_REALM=${PROLE_KDC_TRUST_REALM:-${KRB5_REALM:-}}
-PROLE_KDC_TRUST_ADMIN=${PROLE_KDC_TRUST_ADMIN:-${KRB5_USER:-}}
-PROLE_KDC_TRUST_PASSWORD=${PROLE_KDC_TRUST_PASSWORD:-${KRB5_PASSWORD:-}}
-PROLE_KDC_TRUST_SHARED_PASSWORD=${PROLE_KDC_TRUST_SHARED_PASSWORD:-}
-KRB5_KDC=${KRB5_KDC:-}
-KRB5_ADMIN=${KRB5_ADMIN:-}
-
-local_registry_enabled() {
- local raw="${PROLE_ENABLE_LOCAL_REGISTRY:-${ENABLE_LOCAL_REGISTRY:-}}"
- if [[ -n "$raw" ]]; then
- case "$raw" in
- 1|true|TRUE|True|yes|YES|Yes|on|ON|On) return 0 ;;
- esac
- return 1
- fi
-
- local mode=""
- if command -v knoe_normalize_mode >/dev/null 2>&1; then
- mode=$(knoe_normalize_mode "${KNOE_MODE:-${DEPLOYMENT_MODE:-${CLUSTER_ENV:-}}}")
- else
- mode="${KNOE_MODE:-${DEPLOYMENT_MODE:-${CLUSTER_ENV:-}}}"
- fi
- [[ "$mode" == "k3d" || "$mode" == "k3s" ]]
-}
-
-if ! local_registry_enabled; then
- # Only clear default local-registry settings; preserve explicit registry host values.
- _default_host="${LOCAL_REGISTRY:-localhost:5000}"
- if [[ -z "${KNOE_AUTH_REGISTRY_HOST:-}" || "${KNOE_AUTH_REGISTRY_HOST:-}" == "$_default_host" ]]; then
- KNOE_AUTH_REGISTRY_HOST=""
- fi
- KNOE_AUTH_REGISTRY_INTERNAL=""
- unset _default_host
-fi
-
-log() { printf '%s\n' "$*"; }
-err() { printf '%s\n' "$*" >&2; }
-
-ensure_tools() {
- for t in kubectl; do
- command -v "$t" >/dev/null || { err "Missing required tool: $t"; exit 1; }
- done
-}
-
-ensure_docker() {
- command -v docker >/dev/null || { err "Missing required tool: docker"; exit 1; }
- if ! docker info >/dev/null 2>&1; then
- err "Docker is not running or not accessible."
- err "This is required to build/push the knoe-auth image."
- err "Start Docker (e.g. Docker Desktop), or set KNOE_AUTH_IMAGE to a prebuilt image and/or set KNOE_AUTH_BUILD_IMAGE=0."
- exit 1
- fi
-}
-
-docker_available() {
- command -v docker >/dev/null 2>&1 || return 1
- docker info >/dev/null 2>&1
-}
-
-resolve_knoe_auth_image() {
- # Ensure we have a deterministic image reference even when skipping local builds.
- if [[ -n "${KNOE_AUTH_IMAGE:-}" ]]; then
- return 0
- fi
- if [[ -n "${KNOE_AUTH_REGISTRY_INTERNAL:-}" ]]; then
- KNOE_AUTH_IMAGE="${KNOE_AUTH_REGISTRY_INTERNAL}/${KNOE_AUTH_IMAGE_NAME}:${KNOE_AUTH_IMAGE_TAG}"
- return 0
- fi
- if [[ -n "${KNOE_AUTH_REGISTRY_HOST:-}" ]]; then
- KNOE_AUTH_IMAGE="${KNOE_AUTH_REGISTRY_HOST}/${KNOE_AUTH_IMAGE_NAME}:${KNOE_AUTH_IMAGE_TAG}"
- return 0
- fi
- KNOE_AUTH_IMAGE="${KNOE_AUTH_IMAGE_NAME}:${KNOE_AUTH_IMAGE_TAG}"
-}
-
-ensure_namespace() {
- if ! kubectl get namespace "$KNOE_AUTH_NAMESPACE" >/dev/null 2>&1; then
- log "Creating namespace '$KNOE_AUTH_NAMESPACE' ..."
- kubectl create namespace "$KNOE_AUTH_NAMESPACE" >/dev/null 2>&1 || true
- fi
-}
-
-normalized_mode() {
- if command -v knoe_normalize_mode >/dev/null 2>&1; then
- knoe_normalize_mode "${KNOE_MODE:-}"
- return 0
- fi
- printf '%s' "${KNOE_MODE:-}"
-}
-
-is_k3d_mode() {
- [[ "$(normalized_mode)" == "k3d" ]]
-}
-
-get_kdc_pods_with_containers() {
- kubectl -n "$KNOE_AUTH_NAMESPACE" get pods -l "app=${KNOE_AUTH_NAME}" \
- -o jsonpath='{range .items[*]}{.metadata.name}{"|"}{range .spec.containers[*]}{.name}{" "}{end}{"\n"}{end}' 2>/dev/null || true
-}
-
-kdc_pods_missing_container() {
- local rows line containers found c
- rows=$(get_kdc_pods_with_containers)
- [[ -z "$rows" ]] && return 1
- while IFS= read -r line; do
- [[ -z "$line" ]] && continue
- containers="${line#*|}"
- found=0
- for c in $containers; do
- if [[ "$c" == "kdc" ]]; then
- found=1
- break
- fi
- done
- if [[ "$found" -eq 0 ]]; then
- return 0
- fi
- done <<< "$rows"
- return 1
-}
-
-kdc_multiple_active_replicasets() {
- local rows line spec status count
- rows=$(kubectl -n "$KNOE_AUTH_NAMESPACE" get rs -l "app=${KNOE_AUTH_NAME}" \
- -o jsonpath='{range .items[*]}{.metadata.name}{"|"}{.spec.replicas}{"|"}{.status.replicas}{"\n"}{end}' 2>/dev/null || true)
- [[ -z "$rows" ]] && return 1
- count=0
- while IFS= read -r line; do
- [[ -z "$line" ]] && continue
- spec=$(printf '%s' "$line" | awk -F'|' '{print $2}')
- status=$(printf '%s' "$line" | awk -F'|' '{print $3}')
- spec=${spec:-0}
- status=${status:-0}
- if [[ "$spec" -gt 0 || "$status" -gt 0 ]]; then
- count=$((count+1))
- fi
- done <<< "$rows"
- (( count > 1 ))
-}
-
-kdc_deployment_not_ready() {
- local desired ready updated
- desired=$(kubectl -n "$KNOE_AUTH_NAMESPACE" get deploy "$KNOE_AUTH_NAME" -o jsonpath='{.spec.replicas}' 2>/dev/null || true)
- ready=$(kubectl -n "$KNOE_AUTH_NAMESPACE" get deploy "$KNOE_AUTH_NAME" -o jsonpath='{.status.readyReplicas}' 2>/dev/null || true)
- updated=$(kubectl -n "$KNOE_AUTH_NAMESPACE" get deploy "$KNOE_AUTH_NAME" -o jsonpath='{.status.updatedReplicas}' 2>/dev/null || true)
- desired=${desired:-0}
- ready=${ready:-0}
- updated=${updated:-0}
- if [[ "$ready" -lt "$desired" || "$updated" -lt "$desired" ]]; then
- return 0
- fi
- return 1
-}
-
-kdc_stale_deployment() {
- if ! kdc_deployment_not_ready; then
- return 1
- fi
- kdc_pods_missing_container && return 0
- kdc_multiple_active_replicasets && return 0
- return 1
-}
-
-maybe_cleanup_stale_kdc() {
- local reason="${1:-stale}"
- local policy="${2:-broad}"
- if ! is_k3d_mode; then
- return 1
- fi
- if ! kubectl -n "$KNOE_AUTH_NAMESPACE" get deploy "$KNOE_AUTH_NAME" >/dev/null 2>&1; then
- return 1
- fi
- if [[ "$policy" == "strict" ]]; then
- if ! kdc_deployment_not_ready; then
- return 1
- fi
- if ! kdc_pods_missing_container; then
- return 1
- fi
- elif ! kdc_stale_deployment; then
- return 1
- fi
- err "WARN: Detected stale knoe-auth KDC deployment (${reason}). Cleaning up..."
- cleanup_knoe_auth
- return 0
-}
-
-lowercase() {
- printf '%s' "${1:-}" | tr '[:upper:]' '[:lower:]'
-}
-
-registry_host_from_url() {
- local value="${1:-}"
- value="${value#http://}"
- value="${value#https://}"
- value="${value%%/*}"
- value="${value%%:*}"
- printf '%s' "$value"
-}
-
-gen_password() {
- if command -v openssl >/dev/null 2>&1; then
- openssl rand -base64 18
- return 0
- fi
- if command -v python3 >/dev/null 2>&1; then
- python3 - <<'PY'
-import secrets, string
-alphabet = string.ascii_letters + string.digits
-print(''.join(secrets.choice(alphabet) for _ in range(24)))
-PY
- return 0
- fi
- date +%s
-}
-
-b64_decode() {
- if base64 --decode /dev/null 2>&1; then
- base64 --decode
- return 0
- fi
- if base64 -d /dev/null 2>&1; then
- base64 -d
- return 0
- fi
- base64 -D
-}
-
-get_secret_value() {
- local secret="$1"
- local key="$2"
- kubectl -n "$KNOE_AUTH_NAMESPACE" get secret "$secret" -o "jsonpath={.data.${key}}" 2>/dev/null | b64_decode 2>/dev/null || true
-}
-
-resolve_knoe_auth_defaults() {
- if [[ -z "$PROLE_KDC_REALM" ]]; then
- PROLE_KDC_REALM="PROLE.LOCAL"
- fi
- if [[ -z "$PROLE_KDC_DOMAIN" ]]; then
- PROLE_KDC_DOMAIN=$(lowercase "$PROLE_KDC_REALM")
- fi
- local mode=""
- if command -v knoe_normalize_mode >/dev/null 2>&1; then
- mode=$(knoe_normalize_mode "${KNOE_MODE:-}")
- else
- mode="${KNOE_MODE:-}"
- fi
- local k3s_host=""
- if local_registry_enabled; then
- if [[ "$mode" == "k3s" ]]; then
- k3s_host=$(registry_host_from_url "${PROLE_K3S_SERVER:-${K3S_SERVER_URL:-}}")
- if [[ -n "$k3s_host" ]] && ([[ -z "${KNOE_AUTH_REGISTRY_HOST:-}" ]] || [[ "$KNOE_AUTH_REGISTRY_HOST" == "localhost:5000" ]] || [[ "$KNOE_AUTH_REGISTRY_HOST" == *"k3d"* ]]); then
- KNOE_AUTH_REGISTRY_HOST="${k3s_host}:5000"
- fi
- fi
- if [[ -z "$KNOE_AUTH_REGISTRY_INTERNAL" ]]; then
- local reg_ns="${REGISTRY_NAMESPACE:-${SERVICE_NAMESPACE:-${NAMESPACE:-default}}}"
- KNOE_AUTH_REGISTRY_INTERNAL="registry.${reg_ns}.svc.cluster.local:5000"
- unset reg_ns
- fi
- else
- KNOE_AUTH_REGISTRY_INTERNAL=""
- fi
- if [[ -z "$KNOE_AUTH_IMAGE" ]]; then
- if [[ -n "$KNOE_AUTH_REGISTRY_INTERNAL" ]]; then
- KNOE_AUTH_IMAGE="${KNOE_AUTH_REGISTRY_INTERNAL}/${KNOE_AUTH_IMAGE_NAME}:${KNOE_AUTH_IMAGE_TAG}"
- else
- KNOE_AUTH_IMAGE="${KNOE_AUTH_IMAGE_NAME}:${KNOE_AUTH_IMAGE_TAG}"
- fi
- fi
-}
-
-resolve_kdc_docker_dir() {
- if [[ -n "${PROLE_KDC_DOCKER_DIR:-}" && -d "$PROLE_KDC_DOCKER_DIR" ]]; then
- echo "$PROLE_KDC_DOCKER_DIR"
- return 0
- fi
- if [[ -n "${KNOE_HOME:-}" && -d "$KNOE_HOME/knoe/authority" ]]; then
- echo "$KNOE_HOME/knoe/authority"
- return 0
- fi
- if [[ -n "${KNOE_HOME:-}" && -d "$KNOE_HOME/authority" ]]; then
- echo "$KNOE_HOME/authority"
- return 0
- fi
- if [[ -d "$SCRIPT_DIR/../knoe/authority" ]]; then
- echo "$SCRIPT_DIR/../knoe/authority"
- return 0
- fi
- if [[ -d "$SCRIPT_DIR/../authority" ]]; then
- echo "$SCRIPT_DIR/../authority"
- return 0
- fi
- return 1
-}
-
-is_truthy() {
- case "${1:-}" in
- 1|true|TRUE|True|yes|YES|Yes|on|ON|On) return 0 ;;
+while [[ $# -gt 0 ]]; do
+ case "$1" in
+ --context) APP_CTX="$2"; shift 2 ;;
+ --namespace) NAMESPACE="$2"; shift 2 ;;
+ --project) GCP_PROJECT="$2"; shift 2 ;;
+ --db-host) DB_HOST="$2"; shift 2 ;;
+ *) break ;;
esac
- return 1
+done
+
+# ── Helpers ──────────────────────────────────────────────────────────────────
+
+require_tool() {
+ command -v "$1" >/dev/null 2>&1 || die "Required tool not found: $1 — install it and retry."
}
-build_knoe_auth_image() {
- # If the user explicitly sets KNOE_AUTH_BUILD_IMAGE, honor it.
- # Otherwise, skip building when an explicit image was provided.
- if [[ "$KNOE_AUTH_BUILD_IMAGE_SET" == "1" ]]; then
- if ! is_truthy "${KNOE_AUTH_BUILD_IMAGE:-0}"; then
- resolve_knoe_auth_image
- return 0
- fi
+wait_for_pods() {
+ local label="$1"
+ local timeout="${2:-180}"
+ info "Waiting up to ${timeout}s for pods with label ${label} in ${NAMESPACE}..."
+ kube -n "$NAMESPACE" wait pod \
+ -l "$label" \
+ --for=condition=Ready \
+ --timeout="${timeout}s"
+}
+
+op_secret() {
+ # Retrieve a 1Password secret; fall back to prompting if op isn't authed.
+ local item="$1" field="${2:-password}"
+ if command -v op >/dev/null 2>&1; then
+ op item get "$item" --fields "$field" 2>/dev/null || {
+ warn "1Password: could not read $item/$field — prompting."
+ read -rsp "Enter value for $item/$field: " val; echo
+ printf '%s' "$val"
+ }
else
- if [[ "$KNOE_AUTH_IMAGE_EXPLICIT" == "1" ]]; then
- log "Using preconfigured KNOE_AUTH_IMAGE='${KNOE_AUTH_IMAGE}'; skipping local image build."
- return 0
- fi
+ read -rsp "Enter value for $item/$field: " val; echo
+ printf '%s' "$val"
fi
+}
- if ! docker_available; then
- # If the user forced a build, we must fail with a clear error.
- if [[ "$KNOE_AUTH_BUILD_IMAGE_SET" == "1" ]]; then
- ensure_docker
- fi
+resolve_db_host() {
+ if [[ -n "$DB_HOST" ]]; then return; fi
+ # Try to resolve CNPG primary service from the DB cluster context
+ DB_CTX="${DB_CLUSTER_KUBECONTEXT:-gke_plenary-truck-485623-p7_us-west3_knoe-cnpg-0}"
+ DB_HOST=$(kubectl --context="$DB_CTX" -n knoe-db-0 \
+ get svc knoe-db-rw -o jsonpath='{.spec.clusterIP}' 2>/dev/null || echo "")
+ [[ -z "$DB_HOST" ]] && die "Cannot resolve KNOE DB host. Set KNOE_DB_HOST or ensure knoe-db-rw svc exists."
+ info "Resolved DB host: $DB_HOST"
+}
- log "[WARN] Docker is not available; skipping knoe-auth image build."
- log " Set KNOE_AUTH_BUILD_IMAGE=1 to force building (requires Docker), or set KNOE_AUTH_IMAGE to a prebuilt image."
- resolve_knoe_auth_image
- return 0
- fi
-
- local docker_dir
- docker_dir=$(resolve_kdc_docker_dir || true)
- if [[ -z "$docker_dir" ]]; then
- err "ERROR: knoe/authority Docker context not found."
- exit 1
- fi
-
- ensure_docker
-
- local local_tag="${KNOE_AUTH_IMAGE_NAME}:${KNOE_AUTH_IMAGE_TAG}"
- log "Building authority image: ${local_tag} (context: ${docker_dir}) ..."
- docker build -t "$local_tag" "$docker_dir"
-
- if [[ -n "$KNOE_AUTH_REGISTRY_HOST" ]]; then
- local remote_tag="${KNOE_AUTH_REGISTRY_HOST}/${KNOE_AUTH_IMAGE_NAME}:${KNOE_AUTH_IMAGE_TAG}"
- log "Tagging authority image for registry: ${remote_tag}"
- docker tag "$local_tag" "$remote_tag"
- log "Pushing authority image to registry: ${remote_tag}"
- if ! docker push "$remote_tag"; then
- if command -v skopeo >/dev/null 2>&1; then
- log "Docker push failed; retrying with skopeo (insecure registry) ..."
- skopeo copy --dest-tls-verify=false "docker-daemon:${local_tag}" "docker://${remote_tag}"
- else
- err "ERROR: docker push failed and skopeo is not available."
- exit 1
- fi
- fi
- fi
-
- if [[ -z "$KNOE_AUTH_REGISTRY_HOST" && "$(normalized_mode)" == "k3d" ]]; then
- if command -v k3d >/dev/null 2>&1; then
- local cluster_name="${K3D_CLUSTER_NAME:-knoe-dev-cluster}"
- log "Importing authority image into k3d cluster: ${cluster_name}"
- k3d image import "$local_tag" -c "$cluster_name" >/dev/null 2>&1 || true
- fi
- fi
-
- if [[ -z "$KNOE_AUTH_REGISTRY_HOST" && "$(normalized_mode)" == "k3s" ]]; then
- err "ERROR: No registry host configured for k3s; cannot publish authority image."
- err " Set PROLE_K3S_SERVER (so the script can infer :5000) or set KNOE_AUTH_REGISTRY_HOST explicitly."
- exit 1
- fi
-
- if [[ -n "$KNOE_AUTH_REGISTRY_INTERNAL" ]]; then
- KNOE_AUTH_IMAGE="${KNOE_AUTH_REGISTRY_INTERNAL}/${KNOE_AUTH_IMAGE_NAME}:${KNOE_AUTH_IMAGE_TAG}"
- elif [[ -n "$KNOE_AUTH_REGISTRY_HOST" ]]; then
- KNOE_AUTH_IMAGE="${KNOE_AUTH_REGISTRY_HOST}/${KNOE_AUTH_IMAGE_NAME}:${KNOE_AUTH_IMAGE_TAG}"
+psql_file() {
+ local file="$1"
+ if command -v psql >/dev/null 2>&1 && [[ -n "${PGPASSWORD:-}" ]]; then
+ psql -h "$DB_HOST" -p "$DB_PORT" -U "$DB_SUPERUSER" -d "$DB_NAME" -f "$file"
else
- KNOE_AUTH_IMAGE="${local_tag}"
+ # Fallback: exec into CNPG primary pod
+ DB_CTX="${DB_CLUSTER_KUBECONTEXT:-gke_plenary-truck-485623-p7_us-west3_knoe-cnpg-0}"
+ local pod
+ pod=$(kubectl --context="$DB_CTX" -n knoe-db-0 \
+ get pod -l cnpg.io/cluster=knoe-db,role=primary \
+ -o jsonpath='{.items[0].metadata.name}' 2>/dev/null)
+ [[ -z "$pod" ]] && die "Cannot find CNPG primary pod. Set PGPASSWORD and KNOE_DB_HOST for direct psql."
+ kubectl --context="$DB_CTX" -n knoe-db-0 cp "$file" "${pod}:/tmp/knoe_auth_schema.sql"
+ kubectl --context="$DB_CTX" -n knoe-db-0 exec "$pod" -- \
+ psql -U "$DB_SUPERUSER" -d "$DB_NAME" -f /tmp/knoe_auth_schema.sql
fi
}
-ensure_knoe_auth_secrets() {
- local secret_name="knoe-auth-secrets"
- if [[ -z "$PROLE_KDC_ADMIN_PASSWORD" ]]; then
- PROLE_KDC_ADMIN_PASSWORD=$(get_secret_value "$secret_name" "admin_password")
- fi
- if [[ -z "$PROLE_KDC_MASTER_PASSWORD" ]]; then
- PROLE_KDC_MASTER_PASSWORD=$(get_secret_value "$secret_name" "master_password")
- fi
- if [[ -z "$PROLE_KDC_TRUST_SHARED_PASSWORD" ]]; then
- PROLE_KDC_TRUST_SHARED_PASSWORD=$(get_secret_value "$secret_name" "trust_shared_password")
- fi
- if [[ -z "$PROLE_KDC_TRUST_PASSWORD" ]]; then
- PROLE_KDC_TRUST_PASSWORD=$(get_secret_value "$secret_name" "trust_password")
- fi
+# ── Schema ───────────────────────────────────────────────────────────────────
- if [[ -z "$PROLE_KDC_ADMIN_PASSWORD" ]]; then
- PROLE_KDC_ADMIN_PASSWORD=$(gen_password)
- fi
- if [[ -z "$PROLE_KDC_MASTER_PASSWORD" ]]; then
- PROLE_KDC_MASTER_PASSWORD=$(gen_password)
- fi
- if [[ -z "$PROLE_KDC_TRUST_SHARED_PASSWORD" ]]; then
- PROLE_KDC_TRUST_SHARED_PASSWORD="$PROLE_KDC_MASTER_PASSWORD"
- fi
+run_schema() {
+ info "Applying knoe-auth schema additions..."
+ resolve_db_host
- kubectl -n "$KNOE_AUTH_NAMESPACE" create secret generic "$secret_name" \
- --from-literal=admin_password="$PROLE_KDC_ADMIN_PASSWORD" \
- --from-literal=master_password="$PROLE_KDC_MASTER_PASSWORD" \
- --from-literal=trust_shared_password="$PROLE_KDC_TRUST_SHARED_PASSWORD" \
- --from-literal=trust_password="$PROLE_KDC_TRUST_PASSWORD" \
- --dry-run=client -o yaml | kubectl apply -f - >/dev/null
+ local tmpfile
+ tmpfile=$(mktemp /tmp/knoe_auth_schema_XXXX.sql)
+
+ cat > "$tmpfile" <<'ENDSQL'
+-- ── knoe-auth Round 1 schema additions ───────────────────────────────────────
+-- Idempotent: all CREATE TABLE ... IF NOT EXISTS
+
+-- Invite tokens (admin creates, single-use)
+-- contact is the email/phone the invite was sent to — the OTP trust anchor.
+-- knoe.dev starts with ZERO pre-knowledge of the developer's home org.
+CREATE TABLE IF NOT EXISTS knoe.invitation (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ token TEXT NOT NULL UNIQUE,
+ contact TEXT NOT NULL,
+ contact_type TEXT NOT NULL DEFAULT 'email',
+ name_hint TEXT,
+ otp_hash TEXT NOT NULL,
+ otp_expires_at TIMESTAMPTZ NOT NULL,
+ otp_attempts INT NOT NULL DEFAULT 0,
+ otp_verified_at TIMESTAMPTZ,
+ created_by TEXT NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ expires_at TIMESTAMPTZ NOT NULL,
+ used_at TIMESTAMPTZ,
+ used_by TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_invitation_token ON knoe.invitation(token);
+CREATE INDEX IF NOT EXISTS idx_invitation_contact ON knoe.invitation(contact);
+
+-- External identity corroborations (Google sub → knoe user)
+-- provider_hd records the developer's home domain (prole.org, gmail.com, etc.)
+-- for audit purposes only — it is NOT used for access control.
+CREATE TABLE IF NOT EXISTS knoe.identity (
+ id SERIAL PRIMARY KEY,
+ user_id INT NOT NULL REFERENCES knoe.user(id) ON DELETE CASCADE,
+ provider TEXT NOT NULL,
+ provider_sub TEXT NOT NULL,
+ provider_email TEXT,
+ provider_hd TEXT,
+ verified_at TIMESTAMPTZ NOT NULL,
+ UNIQUE(provider, provider_sub)
+);
+CREATE INDEX IF NOT EXISTS idx_identity_user ON knoe.identity(user_id);
+
+-- TOTP 2FA credentials (encrypted secret, backup codes)
+CREATE TABLE IF NOT EXISTS knoe.totp_credential (
+ user_id INT PRIMARY KEY REFERENCES knoe.user(id) ON DELETE CASCADE,
+ secret TEXT NOT NULL,
+ verified_at TIMESTAMPTZ,
+ backup_codes TEXT[],
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+
+-- Platform-managed resources (repos, db roles, policies, etc.)
+CREATE TABLE IF NOT EXISTS knoe.knobject (
+ id SERIAL PRIMARY KEY,
+ type TEXT NOT NULL,
+ name TEXT NOT NULL,
+ platform_id TEXT,
+ metadata JSONB,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ UNIQUE(type, name)
+);
+
+-- Access grants (user → knobject with role)
+CREATE TABLE IF NOT EXISTS knoe.access_grant (
+ id SERIAL PRIMARY KEY,
+ user_id INT NOT NULL REFERENCES knoe.user(id),
+ knobject_id INT NOT NULL REFERENCES knoe.knobject(id),
+ role TEXT NOT NULL,
+ granted_by TEXT NOT NULL,
+ granted_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ revoked_at TIMESTAMPTZ,
+ UNIQUE(user_id, knobject_id)
+);
+
+-- Async provisioning job queue (GitLab user, Gitea user, CNPG role, etc.)
+CREATE TABLE IF NOT EXISTS knoe.provisioning_job (
+ id SERIAL PRIMARY KEY,
+ user_id INT NOT NULL REFERENCES knoe.user(id),
+ job_type TEXT NOT NULL,
+ status TEXT NOT NULL DEFAULT 'pending',
+ payload JSONB,
+ result JSONB,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS idx_provisioning_job_status
+ ON knoe.provisioning_job(status, created_at);
+
+-- Seed well-known knobjects
+INSERT INTO knoe.knobject (type, name, metadata) VALUES
+ ('gitea_org', 'knoe.dev', '{"description": "Knoe.DEV Gitea organisation"}'),
+ ('gitlab_group','knoe.dev', '{"description": "Knoe.DEV GitLab group"}')
+ON CONFLICT (type, name) DO NOTHING;
+
+SELECT 'knoe-auth schema v1 applied.' AS status;
+ENDSQL
+
+ psql_file "$tmpfile"
+ rm -f "$tmpfile"
+ info "Schema applied."
}
-ensure_knoe_auth() {
- if [[ "$KNOE_AUTH_ENABLED" == "0" || "$KNOE_AUTH_ENABLED" == "false" || "$KNOE_AUTH_ENABLED" == "False" ]]; then
- log "knoe-auth disabled (KNOE_AUTH_ENABLED=$KNOE_AUTH_ENABLED)."
- return 0
- fi
-
- if [[ -z "${KNOE_AUTH_HOST_NETWORK}" && "$(normalized_mode)" == "k3d" ]]; then
- KNOE_AUTH_HOST_NETWORK=1
- fi
-
- resolve_knoe_auth_defaults
- build_knoe_auth_image
- ensure_knoe_auth_secrets
- local deployment_present=0
- if kubectl -n "$KNOE_AUTH_NAMESPACE" get deploy "$KNOE_AUTH_NAME" >/dev/null 2>&1; then
- deployment_present=1
- fi
-
- # Clean up legacy knoe-auth / old KDC names when switching to knoe-auth.
- kubectl -n "$KNOE_AUTH_NAMESPACE" delete deployment auth --ignore-not-found >/dev/null 2>&1 || true
- kubectl -n "$KNOE_AUTH_NAMESPACE" delete service auth --ignore-not-found >/dev/null 2>&1 || true
- kubectl -n "$KNOE_AUTH_NAMESPACE" delete deployment dog --ignore-not-found >/dev/null 2>&1 || true
- kubectl -n "$KNOE_AUTH_NAMESPACE" delete service authority --ignore-not-found >/dev/null 2>&1 || true
-
- local admin_acl_principal="$PROLE_KDC_ADMIN_PRINCIPAL"
- if [[ "$admin_acl_principal" != *"@"* ]]; then
- admin_acl_principal="${admin_acl_principal}@${PROLE_KDC_REALM}"
- fi
-
- local trust_block=""
- if [[ -n "$PROLE_KDC_TRUST_REALM" && "$PROLE_KDC_TRUST_REALM" != "$PROLE_KDC_REALM" && -n "$KRB5_KDC" ]]; then
- local trust_admin_server="${KRB5_ADMIN:-$KRB5_KDC}"
- trust_block=$(cat <&2
- env | sed -E 's/(PASSWORD|TOKEN|SECRET)=.*/\1=****/g' >&2 || true
- fi
- export DEBIAN_FRONTEND=noninteractive
-
- if ! command -v krb5kdc >/dev/null 2>&1; then
- echo "Installing Kerberos packages..."
- echo "krb5-config krb5-config/default_realm string ${PROLE_KDC_REALM}" | debconf-set-selections || true
- echo "krb5-config krb5-config/kerberos_servers string 127.0.0.1" | debconf-set-selections || true
- echo "krb5-config krb5-config/admin_server string 127.0.0.1" | debconf-set-selections || true
- apt-get update
- apt-get install -y --no-install-recommends krb5-kdc krb5-admin-server krb5-user dnsutils ca-certificates
- rm -rf /var/lib/apt/lists/*
- fi
-
- mkdir -p /etc/krb5kdc /var/lib/krb5kdc
- if [[ -f /opt/knoe-auth-kdc/krb5.conf ]]; then
- cp /opt/knoe-auth-kdc/krb5.conf /etc/krb5.conf
- fi
- if [[ -f /opt/knoe-auth-kdc/kdc.conf ]]; then
- cp /opt/knoe-auth-kdc/kdc.conf /etc/krb5kdc/kdc.conf
- fi
- if [[ -f /opt/knoe-auth-kdc/kadm5.acl ]]; then
- cp /opt/knoe-auth-kdc/kadm5.acl /etc/krb5kdc/kadm5.acl
- fi
-
- # Validate required secrets early to avoid silent crashes
- if [[ -z "${PROLE_KDC_MASTER_PASSWORD:-}" ]]; then
- echo "ERROR: Missing required env PROLE_KDC_MASTER_PASSWORD (secret 'knoe-auth-secrets/master_password')." >&2
- exit 1
- fi
- if [[ -z "${PROLE_KDC_ADMIN_PASSWORD:-}" ]]; then
- echo "ERROR: Missing required env PROLE_KDC_ADMIN_PASSWORD (secret 'knoe-auth-secrets/admin_password')." >&2
- exit 1
- fi
-
- # Optionally generate a minimal Samba configuration if a child realm is provided
- realm="\${PROLE_CHILD_REALM:-}"
- if [[ -z "\$realm" ]]; then
- realm="\${PROLE_KDC_REALM}"
- fi
- if [[ -n "\$realm" ]]; then
- workgroup="\${PROLE_CHILD_WORKGROUP:-}"
- if [[ -z "\$workgroup" ]]; then
- workgroup="\${realm%%.*}"
- fi
- netbios="\${PROLE_CHILD_NETBIOS_NAME:-}"
- if [[ -z "\$netbios" ]]; then
- netbios="\$workgroup"
- fi
- server_string="\${PROLE_CHILD_SERVER_STRING:-}"
- if [[ -z "\$server_string" ]]; then
- server_string="\${realm} AD DC"
- fi
- server_role="\${PROLE_SAMBA_SERVER_ROLE:-}"
- if [[ -z "\$server_role" ]]; then
- server_role='active directory domain controller'
- fi
- mkdir -p /etc/samba
- # Write minimal Samba config without using a here‑doc to avoid YAML indentation issues
- # when this script is embedded in a ConfigMap. Variables are expanded at container runtime.
- {
- printf '%s\n' "[global]"
- printf '%s\n' " workgroup = \${workgroup}"
- printf '%s\n' " realm = \${realm}"
- printf '%s\n' " netbios name = \${netbios}"
- printf '%s\n' " server string = \${server_string}"
- printf '%s\n' " server role = \${server_role}"
- } > /etc/samba/smb.conf
- fi
-
- realm="\${PROLE_KDC_REALM}"
- admin_principal="\${PROLE_KDC_ADMIN_PRINCIPAL}"
- if [[ "\${admin_principal}" != *"@"* ]]; then
- admin_principal="\${admin_principal}@\${PROLE_KDC_REALM}"
- fi
-
- if [[ ! -f /var/lib/krb5kdc/principal ]]; then
- echo "Initializing realm database for \${PROLE_KDC_REALM}..."
- kdb5_util create -s -r "\${realm}" -P "\${PROLE_KDC_MASTER_PASSWORD}"
- fi
-
- if ! kadmin.local -q "get_principal \${admin_principal}" >/dev/null 2>&1; then
- echo "Creating admin principal \${admin_principal}..."
- kadmin.local -q "addprinc -pw \${PROLE_KDC_ADMIN_PASSWORD} \${admin_principal}"
- fi
-
- if [[ -n "\${PROLE_KDC_TRUST_REALM:-}" && "\${PROLE_KDC_TRUST_REALM}" != "\${PROLE_KDC_REALM}" ]]; then
- shared_pw="\${PROLE_KDC_TRUST_SHARED_PASSWORD:-\${PROLE_KDC_MASTER_PASSWORD}}"
- if ! kadmin.local -q "get_principal krbtgt/\${PROLE_KDC_TRUST_REALM}@\${PROLE_KDC_REALM}" >/dev/null 2>&1; then
- echo "Creating trust principal krbtgt/\${PROLE_KDC_TRUST_REALM}@\${PROLE_KDC_REALM}..."
- kadmin.local -q "addprinc -pw \${shared_pw} krbtgt/\${PROLE_KDC_TRUST_REALM}@\${PROLE_KDC_REALM}"
- fi
-
- if [[ -n "\${PROLE_KDC_TRUST_ADMIN:-}" && -n "\${PROLE_KDC_TRUST_PASSWORD:-}" ]]; then
- echo "Creating reciprocal trust principal in \${PROLE_KDC_TRUST_REALM}..."
- kadmin -r "\${PROLE_KDC_TRUST_REALM}" -p "\${PROLE_KDC_TRUST_ADMIN}" -w "\${PROLE_KDC_TRUST_PASSWORD}" \
- -q "addprinc -pw \${shared_pw} krbtgt/\${PROLE_KDC_REALM}@\${PROLE_KDC_TRUST_REALM}" || true
- else
- echo "WARN: Missing PROLE_KDC_TRUST_ADMIN/PROLE_KDC_TRUST_PASSWORD; skipping external trust principal."
- fi
- fi
-
- # Start daemons. Keep kadmind in PID 1; run krb5kdc in background and verify it binds.
- echo "Starting krb5kdc and kadmind ..."
- krb5kdc -n &
- sleep 0.5
- if ! pgrep -x krb5kdc >/dev/null 2>&1; then
- echo "ERROR: krb5kdc failed to start. Check /var/log/ (syslog) for details." >&2
- exit 1
- fi
- exec kadmind -nofork
----
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- name: ${KNOE_AUTH_NAME}
- namespace: ${KNOE_AUTH_NAMESPACE}
-spec:
- replicas: 1
- selector:
- matchLabels:
- app: ${KNOE_AUTH_NAME}
- template:
- metadata:
- labels:
- app: ${KNOE_AUTH_NAME}
- spec:
-${host_net_block}
-${dns_policy_block}
- containers:
- - name: kdc
- image: ${KNOE_AUTH_IMAGE}
- imagePullPolicy: IfNotPresent
- command: ["/bin/bash", "/opt/knoe-auth-kdc/entrypoint.sh"]
- env:
- - name: PROLE_KDC_REALM
- value: "${PROLE_KDC_REALM}"
- - name: PROLE_KDC_ADMIN_PRINCIPAL
- value: "${PROLE_KDC_ADMIN_PRINCIPAL}"
- - name: PROLE_KDC_MASTER_PASSWORD
- valueFrom:
- secretKeyRef:
- name: knoe-auth-secrets
- key: master_password
- - name: PROLE_KDC_ADMIN_PASSWORD
- valueFrom:
- secretKeyRef:
- name: knoe-auth-secrets
- key: admin_password
- - name: PROLE_KDC_TRUST_SHARED_PASSWORD
- valueFrom:
- secretKeyRef:
- name: knoe-auth-secrets
- key: trust_shared_password
- - name: PROLE_KDC_TRUST_REALM
- value: "${PROLE_KDC_TRUST_REALM}"
- - name: PROLE_KDC_TRUST_ADMIN
- value: "${PROLE_KDC_TRUST_ADMIN}"
- - name: PROLE_KDC_TRUST_PASSWORD
- valueFrom:
- secretKeyRef:
- name: knoe-auth-secrets
- key: trust_password
- - name: PROLE_CHILD_REALM
- value: "${PROLE_CHILD_REALM:-}"
- - name: PROLE_CHILD_WORKGROUP
- value: "${PROLE_CHILD_WORKGROUP:-}"
- - name: PROLE_CHILD_NETBIOS_NAME
- value: "${PROLE_CHILD_NETBIOS_NAME:-}"
- - name: PROLE_CHILD_SERVER_STRING
- value: "${PROLE_CHILD_SERVER_STRING:-}"
- - name: PROLE_SAMBA_SERVER_ROLE
- value: "${PROLE_SAMBA_SERVER_ROLE:-}"
- ports:
- - name: krb5-udp
- containerPort: 88
- protocol: UDP
- - name: krb5-tcp
- containerPort: 88
- protocol: TCP
- - name: kpasswd-udp
- containerPort: 464
- protocol: UDP
- - name: kpasswd-tcp
- containerPort: 464
- protocol: TCP
- - name: kadmin
- containerPort: 749
- protocol: TCP
- volumeMounts:
- - name: knoe-auth-kdc-config
- mountPath: /opt/knoe-auth-kdc
- - name: knoe-auth-kdc-data
- mountPath: /var/lib/krb5kdc
- - name: knoe-auth-kdc-data
- mountPath: /etc/krb5kdc
- volumes:
- - name: knoe-auth-kdc-config
- configMap:
- name: knoe-auth-kdc-config
- - name: knoe-auth-kdc-data
- emptyDir: {}
----
-apiVersion: v1
-kind: Service
-metadata:
- name: ${KNOE_AUTH_SERVICE}
- namespace: ${KNOE_AUTH_NAMESPACE}
-spec:
- selector:
- app: ${KNOE_AUTH_NAME}
- ports:
- - name: krb5-udp
- port: 88
- targetPort: 88
- protocol: UDP
- - name: krb5-tcp
- port: 88
- targetPort: 88
- protocol: TCP
- - name: kpasswd-udp
- port: 464
- targetPort: 464
- protocol: UDP
- - name: kpasswd-tcp
- port: 464
- targetPort: 464
- protocol: TCP
- - name: kadmin
- port: 749
- targetPort: 749
- protocol: TCP
-EOF
- }
-
- apply_knoe_auth_manifest
-
- local rollout_timeout="$KNOE_AUTH_ROLLOUT_TIMEOUT"
- if [[ "$deployment_present" -eq 0 ]]; then
- rollout_timeout="$KNOE_AUTH_DEPLOY_TIMEOUT"
- fi
- if ! kubectl -n "$KNOE_AUTH_NAMESPACE" rollout status deploy/${KNOE_AUTH_NAME} --timeout="${rollout_timeout}s"; then
- err "WARN: knoe-auth rollout did not complete within ${rollout_timeout}s. Collecting diagnostics..."
- latest_pod=$(kubectl -n "$KNOE_AUTH_NAMESPACE" get pod -l "app=${KNOE_AUTH_NAME}" --sort-by=.metadata.creationTimestamp -o jsonpath='{.items[-1].metadata.name}' 2>/dev/null || true)
- if [[ -n "${latest_pod:-}" ]]; then
- err "--- describe pod ${latest_pod} ---"
- kubectl -n "$KNOE_AUTH_NAMESPACE" describe pod "$latest_pod" 1>&2 || true
- err "--- last 200 log lines from ${latest_pod} ---"
- kubectl -n "$KNOE_AUTH_NAMESPACE" logs "$latest_pod" --tail=200 1>&2 || true
- else
- err "[WARN] No pods found for app=${KNOE_AUTH_NAME} to collect logs from."
- fi
- if maybe_cleanup_stale_kdc "rollout timeout"; then
- log "Re-applying knoe-auth after cleanup..."
- apply_knoe_auth_manifest
- kubectl -n "$KNOE_AUTH_NAMESPACE" rollout status deploy/${KNOE_AUTH_NAME} --timeout="${KNOE_AUTH_DEPLOY_TIMEOUT}s" || true
- fi
+# ── KDC secrets ──────────────────────────────────────────────────────────────
+
+create_kdc_secrets() {
+ if kube -n "$NAMESPACE" get secret knoe-kdc-secrets >/dev/null 2>&1; then
+ info "knoe-kdc-secrets already exists — skipping."
+ return
fi
+ info "Creating knoe-kdc-secrets from 1Password..."
+ local master admin
+ master=$(op_secret "knoe-kdc-master" "password")
+ admin=$(op_secret "knoe-kdc-admin" "password")
+ kube -n "$NAMESPACE" create secret generic knoe-kdc-secrets \
+ --from-literal=master_password="$master" \
+ --from-literal=admin_password="$admin"
+ info "knoe-kdc-secrets created."
}
-cleanup_knoe_auth() {
- log "Removing knoe-auth resources (if present)..."
- kubectl -n "$KNOE_AUTH_NAMESPACE" delete service "$KNOE_AUTH_SERVICE" --ignore-not-found
- kubectl -n "$KNOE_AUTH_NAMESPACE" delete deployment "$KNOE_AUTH_NAME" --ignore-not-found
- kubectl -n "$KNOE_AUTH_NAMESPACE" delete configmap knoe-auth-kdc-config --ignore-not-found
- kubectl -n "$KNOE_AUTH_NAMESPACE" delete secret knoe-auth-secrets --ignore-not-found
-}
-
-status() {
- log "--- init_knoe_auth status ---"
- log "Namespace: $KNOE_AUTH_NAMESPACE"
- log "knoe-auth enabled: ${KNOE_AUTH_ENABLED:-0}"
- log "KDC realm: ${PROLE_KDC_REALM:-}"
- log "knoe-auth service: ${KNOE_AUTH_SERVICE:-}"
- log "knoe-auth image: ${KNOE_AUTH_IMAGE:-}"
- if kubectl -n "$KNOE_AUTH_NAMESPACE" get deploy "$KNOE_AUTH_NAME" >/dev/null 2>&1; then
- log "[OK] knoe-auth deployment present"
- if maybe_cleanup_stale_kdc "status check" "strict"; then
- log "[INFO] Stale knoe-auth deployment removed. Re-run init_knoe_auth.sh update to recreate."
- fi
- else
- log "[INFO] knoe-auth deployment not present"
+create_google_oidc_secret() {
+ if kube -n "$NAMESPACE" get secret knoe-auth-google-oidc >/dev/null 2>&1; then
+ info "knoe-auth-google-oidc already exists — skipping."
+ return
fi
+ info "Creating knoe-auth-google-oidc secret..."
+ local client_id client_secret
+ client_id=$(op_secret "knoe-google-oidc" "client_id")
+ client_secret=$(op_secret "knoe-google-oidc" "client_secret")
+ kube -n "$NAMESPACE" create secret generic knoe-auth-google-oidc \
+ --from-literal=client_id="$client_id" \
+ --from-literal=client_secret="$client_secret"
+ info "knoe-auth-google-oidc created."
}
-case "$ACTION" in
- initialize|init|update|deploy|start)
- ensure_tools
- ensure_namespace
- ensure_knoe_auth
- ;;
- status)
- ensure_tools
- status
- ;;
- cleanup|delete|remove)
- ensure_tools
- ensure_namespace
- cleanup_knoe_auth
- ;;
+create_session_secret() {
+ if kube -n "$NAMESPACE" get secret knoe-auth-secrets >/dev/null 2>&1; then
+ info "knoe-auth-secrets already exists — skipping."
+ return
+ fi
+ info "Creating knoe-auth-secrets (session HMAC key)..."
+ local session_secret
+ session_secret=$(op_secret "knoe-auth-session" "password")
+ kube -n "$NAMESPACE" create secret generic knoe-auth-secrets \
+ --from-literal=sessionSecret="$session_secret"
+ info "knoe-auth-secrets created."
+}
+
+# ── Manifests ────────────────────────────────────────────────────────────────
+
+apply_manifests() {
+ info "Applying KDC ConfigMap..."
+ kube apply -f "$GKE_DIR/knoe-kdc-configmap.yaml"
+
+ info "Applying knoe-auth Deployment..."
+ kube apply -f "$GKE_DIR/knoe-auth-deployment.yaml"
+}
+
+# ── Invite helper ─────────────────────────────────────────────────────────────
+
+create_first_invite() {
+ local contact="${1:-}"
+ [[ -z "$contact" ]] && { read -rp "Invite contact (email or phone): " contact; }
+ local name_hint=""
+ read -rp "Display name hint (optional, press Enter to skip): " name_hint || true
+
+ info "Creating invite for: $contact"
+ local admin_token
+ admin_token=$(op_secret "knoe-admin-token" "credential" 2>/dev/null || \
+ { read -rsp "Admin token: " t; echo; printf '%s' "$t"; })
+
+ local response
+ response=$(curl -sf -X POST \
+ -H "Content-Type: application/json" \
+ -H "Authorization: Bearer $admin_token" \
+ -d "{\"contact\":\"$contact\",\"contactType\":\"email\",\"nameHint\":\"$name_hint\"}" \
+ "${AUTH_HOST}/auth/admin/invites") || {
+ warn "Admin API call failed. knoe-auth may not be ready yet."
+ warn "Retry: POST ${AUTH_HOST}/auth/admin/invites"
+ return 1
+ }
+
+ local invite_url
+ invite_url=$(printf '%s' "$response" | grep -o '"enrollUrl":"[^"]*"' | sed 's/"enrollUrl":"//;s/"//')
+ printf '\n\033[1;32mInvite URL:\033[0m %s\n\n' "$invite_url"
+ info "Send the above URL to: $contact"
+}
+
+# ── Status ────────────────────────────────────────────────────────────────────
+
+show_status() {
+ info "=== Pod status ==="
+ kube -n "$NAMESPACE" get pods -l app=knoe-auth 2>/dev/null || true
+ info "=== Secrets ==="
+ kube -n "$NAMESPACE" get secret \
+ knoe-kdc-secrets knoe-auth-google-oidc knoe-auth-secrets 2>/dev/null || true
+ info "=== Services ==="
+ kube -n "$NAMESPACE" get svc knoe-auth 2>/dev/null || true
+ info "=== Enrollment endpoint ==="
+ info "${AUTH_HOST}/auth/enroll"
+}
+
+# ── Full initialization ───────────────────────────────────────────────────────
+
+cmd_initialize() {
+ require_tool kubectl
+
+ info "=== knoe-auth initialization ==="
+ info " Realm: $REALM"
+ info " Cluster: $APP_CTX"
+ info " NS: $NAMESPACE"
+ info ""
+
+ # 1. Ensure namespace exists
+ kube get namespace "$NAMESPACE" >/dev/null 2>&1 || \
+ kube create namespace "$NAMESPACE"
+
+ # 2. Secrets
+ create_kdc_secrets
+ create_google_oidc_secret
+ create_session_secret
+
+ # 3. Apply ConfigMap + Deployment
+ apply_manifests
+
+ # 4. Wait for pods
+ wait_for_pods "app=knoe-auth" 240
+
+ # 5. Schema
+ run_schema
+
+ # 6. Done
+ info ""
+ info "=== knoe-auth is ready ==="
+ info "Enrollment URL: ${AUTH_HOST}/auth/enroll?token="
+ info ""
+ info "Next: create first admin invite:"
+ info " $0 invite chrisfu@prole.org"
+ info ""
+ show_status
+}
+
+# ── Dispatch ──────────────────────────────────────────────────────────────────
+
+case "$COMMAND" in
+ initialize) cmd_initialize ;;
+ schema) run_schema ;;
+ invite) create_first_invite "${1:-}" ;;
+ status) show_status ;;
*)
- err "Usage: $0 {initialize|update|status|cleanup}"
- exit 2
+ echo "Usage: $0 {initialize|schema|invite EMAIL|status} [--context CTX] [--namespace NS]" >&2
+ exit 1
;;
esac
diff --git a/etc/init_knoe_users.sh b/etc/init_knoe_users.sh
index 2df32bc..3f1bee0 100755
--- a/etc/init_knoe_users.sh
+++ b/etc/init_knoe_users.sh
@@ -7,14 +7,14 @@ set -euo pipefail
# - Provision Kerberos principals and database accounts for knoe-system users
# - Creates: admin@PROLE.LOCAL (master password), guest@PROLE.LOCAL (read-only),
# postgres service principal (keytab for GSS auth), developer group role
-# - Cross-realm trust with myrddin.knoe.org PROLE.ORG is activated via
+# - Cross-realm trust with myrddin.prole.org PROLE.ORG is activated via
# PROLE_KDC_TRUST_REALM=PROLE.ORG in init_kdc.sh / init_knoe_auth.sh
# - Sets up service admin access: ArgoCD RBAC, Gitea, GitLab
#
# Prerequisites:
# init_kdc.sh initialize (with PROLE_KDC_REALM=PROLE.LOCAL,
# PROLE_KDC_TRUST_REALM=PROLE.ORG,
-# KRB5_KDC=myrddin.knoe.org)
+# KRB5_KDC=myrddin.prole.org)
# init_cnpg_backup.sh (CNPG cluster must exist)
# init_argocd.sh (ArgoCD must be running)
#
@@ -93,8 +93,8 @@ KNOE_DEPLOYMENT_MODE="${KNOE_DEPLOYMENT_MODE:-$(resolve_knoe_mode)}"
KNOE_AUTH_DEPLOYMENT="${KNOE_AUTH_DEPLOYMENT:-${PROLE_KDC_NAME:-$(default_knoe_auth_deployment)}}"
KNOE_ADMIN_PRINCIPAL="${KNOE_ADMIN_PRINCIPAL:-admin}"
PROLE_KDC_REALM="${PROLE_KDC_REALM:-PROLE.LOCAL}"
-GITEA_HOST="${GITEA_HOST:-git.knoe.org}"
-GITLAB_HOST="${GITLAB_HOST:-gitlab.knoe.org}"
+GITEA_HOST="${GITEA_HOST:-git.prole.org}"
+GITLAB_HOST="${GITLAB_HOST:-gitlab.prole.org}"
GITEA_NAMESPACE="${GITEA_NAMESPACE:-gitea}"
GITLAB_NAMESPACE="${GITLAB_NAMESPACE:-gitlab}"
ARGOCD_NAMESPACE="${ARGOCD_NAMESPACE:-argocd}"
@@ -455,8 +455,8 @@ SQL
# 8. Create knoe.user schema tables and bootstrap users
if [[ -n "$primary" ]]; then
create_knoe_schema "$primary"
- provision_user "$primary" "chrisfu" "chrisfu@knoe.org" "Chris Fu" "admin"
- provision_user "$primary" "ron" "ron@knoe.org" "Ron" "developer"
+ provision_user "$primary" "chrisfu" "chrisfu@prole.org" "Chris Fu" "admin"
+ provision_user "$primary" "ron" "ron@prole.org" "Ron" "developer"
else
warn "CNPG primary not found — skipping knoe.user schema and user provisioning"
fi
@@ -473,7 +473,7 @@ SQL
log "=== Initialization complete ==="
log ""
log "Next steps:"
- log " 1. On myrddin.knoe.org: add krbtgt/PROLE.LOCAL@PROLE.ORG trust principal"
+ log " 1. On myrddin.prole.org: add krbtgt/PROLE.LOCAL@PROLE.ORG trust principal"
log " (samba-tool domain trust or equivalent, using trust_shared_password from knoe-kdc-secrets)"
log " 2. Confirm Grafana auth.proxy configured with: headers = Role:X-Knoe-Groups"
log " 3. After admin logs in to Gitea/GitLab for the first time, re-run: $0 initialize"
diff --git a/etc/init_kong.sh b/etc/init_kong.sh
index 1924677..c4138fe 100755
--- a/etc/init_kong.sh
+++ b/etc/init_kong.sh
@@ -137,9 +137,9 @@ if [[ "${KNOE_MODE:-}" == "k8s" ]]; then
else
KONG_NAME="${KONG_NAME:-knoe-svc-kong}"
KONG_CONFIG_NAME="${KONG_CONFIG_NAME:-knoe-svc-kong-config}"
- SERVICE_HOSTNAME="${SERVICE_HOSTNAME:-svc.knoe.org}"
- AUTH_HOSTNAME="${AUTH_HOSTNAME:-api.knoe.org}"
- GITEA_HOSTNAME="${GITEA_HOSTNAME:-${GITEA_DOMAIN:-git.knoe.org}}"
+ SERVICE_HOSTNAME="${SERVICE_HOSTNAME:-svc.prole.org}"
+ AUTH_HOSTNAME="${AUTH_HOSTNAME:-api.prole.org}"
+ GITEA_HOSTNAME="${GITEA_HOSTNAME:-${GITEA_DOMAIN:-git.prole.org}}"
SERVICE_INGRESS_TLS_ENABLED="${SERVICE_INGRESS_TLS_ENABLED:-1}"
fi
KONG_PROXY_PORT="${KONG_PROXY_PORT:-8000}"
diff --git a/etc/init_monitoring.sh b/etc/init_monitoring.sh
index 789d051..f80de7e 100755
--- a/etc/init_monitoring.sh
+++ b/etc/init_monitoring.sh
@@ -198,7 +198,7 @@ validate_monitoring_storage_classes() {
}
monitoring_nodes_available() {
- kubectl get nodes -l "knoe.org/node-role=general" -o name 2>/dev/null | grep -q .
+ kubectl get nodes -l "prole.org/node-role=general" -o name 2>/dev/null | grep -q .
}
resolve_monitoring_primary_node() {
@@ -207,11 +207,11 @@ resolve_monitoring_primary_node() {
printf '%s' "${MONITORING_PRIMARY_NODE}"
return 0
fi
- if kubectl get node merlin.knoe.org >/dev/null 2>&1; then
- printf '%s' "merlin.knoe.org"
+ if kubectl get node merlin.prole.org >/dev/null 2>&1; then
+ printf '%s' "merlin.prole.org"
return 0
fi
- node=$(kubectl get nodes -l "knoe.org/node-role=general" -o jsonpath='{.items[0].metadata.name}' 2>/dev/null || true)
+ node=$(kubectl get nodes -l "prole.org/node-role=general" -o jsonpath='{.items[0].metadata.name}' 2>/dev/null || true)
if [[ -n "${node:-}" ]]; then
printf '%s' "$node"
return 0
@@ -461,7 +461,7 @@ render_node_selector() {
local indent="$1"
cat <
+
+
+
\ No newline at end of file
diff --git a/knoe/core/env.py b/knoe/core/env.py
index 559fa33..e7b4922 100644
--- a/knoe/core/env.py
+++ b/knoe/core/env.py
@@ -814,7 +814,7 @@ def _detect_ansible_storage_mounts(inventory_path: Path) -> dict[str, dict[str,
Returns a mapping like:
{
- "d001": {"host": "myrddin.knoe.org", "path": "/synology/d001"},
+ "d001": {"host": "myrddin.prole.org", "path": "/synology/d001"},
...
}
diff --git a/knoe/core/milestones.py b/knoe/core/milestones.py
index 1e1a7ff..9a72dff 100644
--- a/knoe/core/milestones.py
+++ b/knoe/core/milestones.py
@@ -836,7 +836,7 @@ class DockerBuildMilestone(Milestone):
registry = (state.config_data.get("Global", {}) or {}).get("KNOE_IMAGE_REGISTRY", "").strip()
if not registry or registry == "localhost:5000":
- server = state.inputs.get("init_cluster.k3s_server_url", "myrddin.knoe.org")
+ server = state.inputs.get("init_cluster.k3s_server_url", "myrddin.prole.org")
if "://" in server:
server = server.split("://")[1]
if ":" in server:
diff --git a/knoe/core/ops/monitoring.py b/knoe/core/ops/monitoring.py
index 9118699..cb19973 100644
--- a/knoe/core/ops/monitoring.py
+++ b/knoe/core/ops/monitoring.py
@@ -227,7 +227,7 @@ def _values_yaml_k3s(grafana_password: str, env: dict | None) -> str:
sc_alert = f"merlin-local-iscsi-{volume_id}-alertmanager"
sc_grafana = f"merlin-local-iscsi-{volume_id}-grafana"
- monitoring_node = str((env or {}).get("MONITORING_PRIMARY_NODE") or "merlin.knoe.org")
+ monitoring_node = str((env or {}).get("MONITORING_PRIMARY_NODE") or "merlin.prole.org")
excluded_nodes = str((env or {}).get("MONITORING_NODE_EXPORTER_EXCLUDE_NODES") or "pi.knoe.org")
excluded_list = [n.strip() for n in excluded_nodes.split(",") if n.strip()]
diff --git a/knoe/ui/screens/__init__.py b/knoe/ui/screens/__init__.py
index d762f60..74c2e6b 100644
--- a/knoe/ui/screens/__init__.py
+++ b/knoe/ui/screens/__init__.py
@@ -390,6 +390,8 @@ class KnoeInstaller(
)
self.project_root = PROJECT_ROOT
self.cfg_path = resolved_cfg
+ from knoe.core.env import DEFAULT_ACTION_FLAGS
+ self._action_flags: dict[str, bool] = DEFAULT_ACTION_FLAGS.copy()
self._init_shared_state()
self._init_database_options_state()
self.screens = None
@@ -525,7 +527,7 @@ class KnoeInstaller(
]
self.nav_widgets = {}
self._mode_tab_widgets: dict = {}
- self.deployment_mode = tk.StringVar(value=__import__("os").environ.get("KNOE_MODE", "k3s"))
+ self.deployment_mode = tk.StringVar(value=__import__("os").environ.get("KNOE_MODE", ""))
self._create_sidebar_nav()
# Validation attributes
diff --git a/knoe/ui/screens/navigation.py b/knoe/ui/screens/navigation.py
index 8490825..2e7cbd5 100644
--- a/knoe/ui/screens/navigation.py
+++ b/knoe/ui/screens/navigation.py
@@ -262,44 +262,23 @@ class NavigationMixin:
except Exception:
pass
- _MODE_COLORS = {"k3d": "#4A90D9", "k3s": "#27AE60", "k8s": "#E67E22"}
+ _MODE_COLORS = {"min": "#8E44AD", "k3d": "#4A90D9", "k3s": "#27AE60", "gke": "#E67E22"}
def _set_deployment_mode(self, mode: str) -> None:
"""Switch the active deployment mode and persist it to the environment."""
self.deployment_mode.set(mode)
os.environ["KNOE_MODE"] = mode
- self._refresh_mode_tabs()
def _refresh_mode_tabs(self) -> None:
- """Update tab highlight colours to reflect the active deployment mode."""
- active = self.deployment_mode.get()
- for value, widget in self._mode_tab_widgets.items():
- if value == active:
- widget.configure(bg=self._MODE_COLORS.get(value, "#888"), fg="white")
- else:
- widget.configure(bg="#D5D5C5", fg="#555")
+ """No-op: mode tabs replaced by welcome screen card selector."""
+ pass
+
+ def _is_min_mode(self) -> bool:
+ """Return True when the user has selected minimal (containerd-only) mode."""
+ return self.deployment_mode.get() == "min"
def _create_sidebar_nav(self):
"""Create the left-hand navigation menu."""
- # ── Deployment mode tab strip ────────────────────────────────────
- mode_frame = tk.Frame(self.sidebar, bg="#F5F5DC")
- mode_frame.pack(fill="x", padx=12, pady=(14, 4))
- for label, value in [("k3d", "k3d"), ("k3s", "k3s"), ("k8s", "k8s")]:
- btn = tk.Label(
- mode_frame,
- text=label,
- bg="#D5D5C5",
- fg="#555",
- font=("SF Pro Text", 9, "bold"),
- padx=8,
- pady=3,
- cursor="hand2",
- )
- btn.pack(side="left", padx=2)
- btn.bind("", lambda e, v=value: self._set_deployment_mode(v))
- self._mode_tab_widgets[value] = btn
- self._refresh_mode_tabs()
-
# ── INSTALLER label ──────────────────────────────────────────────
tk.Label(
self.sidebar,
@@ -375,7 +354,10 @@ class NavigationMixin:
self.show_page(seq[-1] if seq else "deps_summary")
return
if current_id == "env_setup":
- self.show_page("network_scan")
+ if self._is_min_mode():
+ self.show_page("deps_summary")
+ else:
+ self.show_page("network_scan")
return
if current_id == "init_cluster":
if getattr(self, "_showing_service_overlay", False):
@@ -397,7 +379,10 @@ class NavigationMixin:
self.show_page("common_services")
return
if current_id == "init_password":
- self.show_page("init_db_build")
+ if self._is_min_mode():
+ self.show_page("env_setup")
+ else:
+ self.show_page("init_db_build")
return
if current_id == "init_db_build":
self.show_page("database_options")
@@ -426,6 +411,10 @@ class NavigationMixin:
if current_id == "init_cnpg_deploy":
self.show_page("supabase_config")
return
+ if current_id == "security":
+ if self._is_min_mode():
+ self.show_page("init_scripts")
+ return
if current_id == "create_installer":
self.show_page("init_cnpg_deploy")
return
@@ -492,6 +481,9 @@ class NavigationMixin:
return
if current_id == "network_scan":
+ if self._is_min_mode():
+ self.show_page("env_setup")
+ return
# Capture network scan info
try:
self.knoe_cfg_data["Network"][
@@ -593,7 +585,10 @@ class NavigationMixin:
except Exception:
pass
return
- self.show_page("init_cluster")
+ if self._is_min_mode():
+ self.show_page("init_password")
+ else:
+ self.show_page("init_cluster")
return
if current_id == "init_password":
@@ -678,7 +673,9 @@ class NavigationMixin:
"Completed" if getattr(self, "_scripts_success", False) else "Attempted"
)
self._save_knoe_cfg()
- if self.kerberos_enabled.get():
+ if self._is_min_mode():
+ self.show_page("security")
+ elif self.kerberos_enabled.get():
self.show_page("kerberos_config")
else:
self.show_page("argocd_config")
@@ -885,7 +882,12 @@ class NavigationMixin:
# Page-specific adjustments
pid = self.pages[self.page_index][0]
- if pid == "build":
+ if pid == "welcome":
+ if not self.deployment_mode.get():
+ self.next_button.configure(state="disabled")
+ else:
+ self.next_button.configure(state="normal")
+ elif pid == "build":
# Build page: show Build or Next depending on state
if getattr(self, "_built_success", False):
self.next_button.configure(text="Next")
diff --git a/knoe/ui/screens/welcome.py b/knoe/ui/screens/welcome.py
index 2adcbda..496f688 100644
--- a/knoe/ui/screens/welcome.py
+++ b/knoe/ui/screens/welcome.py
@@ -1,68 +1,198 @@
"""Welcome / splash screen."""
+import os
import threading
import time
import tkinter as tk
from tkinter import ttk, messagebox, filedialog
from knoe import screen as ui
+_WELCOME_CARDS = [
+ {
+ "mode": "min",
+ "title": "Just a Database",
+ "body": "One knoe-db container via containerd.\nNo Kubernetes needed. Perfect for\ndeveloping a Spring app locally.",
+ "badge": "Homebrew + 1Password",
+ "color": "#8E44AD",
+ },
+ {
+ "mode": "k3d",
+ "title": "Local Cluster",
+ "body": "k3s-in-Docker cluster on your Mac.\nFull CNPG database — add Supabase,\nArgoCD, Gitea or GitLab.",
+ "badge": "Docker + Homebrew + 1Password",
+ "color": "#4A90D9",
+ },
+ {
+ "mode": "k3s",
+ "title": "Homelab",
+ "body": "Multi-node k3s on real hardware.\nFull Kerberos auth stack, Garage S3\nand monitoring.",
+ "badge": "k3sup + Homebrew + 1Password",
+ "color": "#27AE60",
+ },
+ {
+ "mode": "gke",
+ "title": "Production",
+ "body": "Dual GKE clusters on Google Cloud.\nCNPG + GCS backups and Workload\nIdentity.",
+ "badge": "gcloud + 1Password",
+ "color": "#E67E22",
+ },
+]
+
+_MODE_TO_CLUSTER_ENV = {"min": "min", "k3d": "dev", "k3s": "service", "gke": "prod"}
+
+_MODE_NEEDS = {
+ "min": "You'll need: Homebrew + 1Password",
+ "k3d": "You'll need: Docker, Homebrew + 1Password",
+ "k3s": "You'll need: k3sup, Homebrew + 1Password",
+ "gke": "You'll need: gcloud CLI + 1Password",
+}
+
class WelcomeScreenMixin:
"""Welcome / splash screen."""
def _render_welcome_page(self):
- # Letterhead at top right
- content_width = self.bg_canvas.winfo_width() or 975 # 1300 * 0.75 approx
+ content_width = self.bg_canvas.winfo_width() or 975
right_margin = content_width - 48
- ui.canvas_text(
- self,
- right_margin,
- 40,
- "knoe.dev",
- fill="#6e6e73",
- font=("SF Pro Text", 32, "bold"),
- anchor="ne",
- )
- ui.canvas_text(
- self,
- right_margin,
- 85,
- "infrastructure.auto()",
- fill="#6e6e73",
- font=("SF Pro Text", 18),
- anchor="ne",
- )
+ # Letterhead
+ ui.canvas_text(self, right_margin, 40, "knoe.dev",
+ fill="#6e6e73", font=("SF Pro Text", 32, "bold"), anchor="ne")
+ ui.canvas_text(self, right_margin, 85, "infrastructure.auto()",
+ fill="#6e6e73", font=("SF Pro Text", 18), anchor="ne")
- # Welcome title
- self._render_title("Welcome", y=150)
+ self._render_title("Welcome to Knoe.DB", y=145)
- welcome_text = (
- "This installer will guide you through the process of setting up the Knoe Database and its supporting "
- "infrastructure. We have designed this process to be as automated as possible, ensuring that your "
- "deployment is secure, efficient, and tailored to your specific network environment.\n\n"
- "What to expect:\n"
- "• Network Environment Discovery: We'll scan for existing services like Active Directory and DNS.\n"
- "• System Configuration: Setting up local paths and environment variables.\n"
- "• Dependency Management: Ensuring all required tools (Docker, k3d, etc.) are ready.\n"
- "• Database Initialization: Configuring passwords, Kerberos authentication, and deploying the database cluster.\n\n"
- "We are excited to have you join our community and start building with us. "
- "Welcome to the neighborhood! Let's get started by preparing your system for the Knoe experience."
+ intro = (
+ "Knoe.DB Installer sets up a production-grade PostgreSQL cluster with Kerberos "
+ "authentication.\nPick the mode that matches your hardware — we'll walk you through every step."
)
+ ui.canvas_text(self, 48, 200, intro,
+ fill="#1d1d1f", font=("SF Pro Text", 13), width=800)
- ui.canvas_text(
- self,
- 48,
- 220,
- welcome_text,
- fill="black",
- font=("SF Pro Text", 13),
- width=750,
+ # Mode selector cards
+ card_w = 185
+ card_h = 200
+ card_gap = 18
+ card_x0 = 48
+ card_y0 = 265
+
+ self._welcome_card_rects = {}
+
+ for i, card in enumerate(_WELCOME_CARDS):
+ x0 = card_x0 + i * (card_w + card_gap)
+ x1 = x0 + card_w
+ y0 = card_y0
+ y1 = card_y0 + card_h
+
+ bg = self.bg_canvas.create_rectangle(
+ x0, y0, x1, y1, fill="white", outline="#CCCCCC", width=2,
+ )
+ self._canvas_items.append(bg)
+
+ bar = self.bg_canvas.create_rectangle(
+ x0 + 1, y0 + 1, x1 - 1, y0 + 6, fill=card["color"], outline="",
+ )
+ self._canvas_items.append(bar)
+
+ mode_lbl = self.bg_canvas.create_text(
+ x0 + 14, y0 + 18, text=card["mode"].upper(),
+ fill=card["color"], font=("SF Pro Text", 9, "bold"), anchor="nw",
+ )
+ self._canvas_items.append(mode_lbl)
+
+ title_lbl = self.bg_canvas.create_text(
+ x0 + 14, y0 + 36, text=card["title"],
+ fill="#1d1d1f", font=("SF Pro Text", 13, "bold"), anchor="nw",
+ )
+ self._canvas_items.append(title_lbl)
+
+ body_lbl = self.bg_canvas.create_text(
+ x0 + 14, y0 + 62, text=card["body"],
+ fill="#555555", font=("SF Pro Text", 11), anchor="nw",
+ width=card_w - 28,
+ )
+ self._canvas_items.append(body_lbl)
+
+ badge_lbl = self.bg_canvas.create_text(
+ x0 + 14, y1 - 26, text=card["badge"],
+ fill=card["color"], font=("SF Pro Text", 9), anchor="nw",
+ width=card_w - 28,
+ )
+ self._canvas_items.append(badge_lbl)
+
+ self._welcome_card_rects[card["mode"]] = bg
+
+ mode = card["mode"]
+ for item_id in (bg, bar, mode_lbl, title_lbl, body_lbl, badge_lbl):
+ self.bg_canvas.tag_bind(
+ item_id, "",
+ lambda e, m=mode: self._on_welcome_card_click(m),
+ )
+ self.bg_canvas.tag_bind(
+ item_id, "",
+ lambda e, r=bg, m=mode: self.bg_canvas.itemconfig(
+ r, outline=self._MODE_COLORS.get(m, "#4A90D9")
+ if self.deployment_mode.get() != m else None
+ ),
+ )
+ self.bg_canvas.tag_bind(
+ item_id, "",
+ lambda e, r=bg, m=mode: self.bg_canvas.itemconfig(
+ r, outline=self._MODE_COLORS.get(m, "#4A90D9")
+ if self.deployment_mode.get() == m else "#CCCCCC"
+ ),
+ )
+
+ # "You'll need" status line
+ status_y = card_y0 + card_h + 20
+ self._splash_status_item = self.bg_canvas.create_text(
+ 48, status_y,
+ text="← Select a mode above to continue",
+ fill="#8B8B7A", font=("SF Pro Text", 12, "italic"), anchor="nw",
)
+ self._canvas_items.append(self._splash_status_item)
+
+ # Restore highlight if a mode was already chosen (e.g. loaded from config)
+ current = self.deployment_mode.get()
+ if current and current in self._welcome_card_rects:
+ self._highlight_welcome_card(current)
+ try:
+ self.bg_canvas.itemconfig(
+ self._splash_status_item,
+ text=_MODE_NEEDS.get(current, ""),
+ )
+ except Exception:
+ pass
- # Ensure footer is updated (Next button visible)
self.update_footer()
+ def _on_welcome_card_click(self, mode: str) -> None:
+ self.deployment_mode.set(mode)
+ os.environ["KNOE_MODE"] = mode
+ try:
+ self.cluster_env.set(_MODE_TO_CLUSTER_ENV.get(mode, "dev"))
+ except Exception:
+ pass
+ self._highlight_welcome_card(mode)
+ try:
+ if self._splash_status_item is not None:
+ self.bg_canvas.itemconfig(
+ self._splash_status_item,
+ text=_MODE_NEEDS.get(mode, ""),
+ )
+ except Exception:
+ pass
+ self.update_footer()
+
+ def _highlight_welcome_card(self, selected_mode: str) -> None:
+ for m, rect_id in getattr(self, "_welcome_card_rects", {}).items():
+ if m == selected_mode:
+ color = self._MODE_COLORS.get(m, "#4A90D9")
+ self.bg_canvas.itemconfig(rect_id, outline=color, width=3)
+ else:
+ self.bg_canvas.itemconfig(rect_id, outline="#CCCCCC", width=2)
+
def _start_welcome_dependency_scan(self):
self.splash_scan_running = True
self.splash_scan_done_at = None
diff --git a/pom.xml b/pom.xml
index e5c001e..7c05069 100644
--- a/pom.xml
+++ b/pom.xml
@@ -20,7 +20,9 @@
24
1.0.0
false
- false
+
+ true
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..8996e5d
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,36 @@
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-ra --tb=short"
+
+markers = [
+ "unit: pure unit test — no external services, no cluster, runs anywhere",
+ "integration: requires a running service, cluster, or network dependency",
+ "min: tests the min (containerd) deployment path",
+ "k3d: tests the k3d (local Docker cluster) deployment path",
+ "k3s: tests the k3s (homelab) deployment path",
+ "gke: tests the GKE (production) deployment path",
+]
+
+[tool.coverage.run]
+source = ["knoe"]
+branch = true
+omit = [
+ "tests/*",
+ "*/__init__.py",
+ "knoe/ui/*", # UI layer tested via integration only
+]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = false
+# Raised incrementally as each pipeline phase lands — see docs/pipeline-phases.md Appendix C
+fail_under = 0
+
+[tool.coverage.xml]
+output = "coverage.xml"
+
+[tool.coverage.html]
+directory = "htmlcov"
diff --git a/requirements-test.txt b/requirements-test.txt
new file mode 100644
index 0000000..094a6a6
--- /dev/null
+++ b/requirements-test.txt
@@ -0,0 +1,8 @@
+# Test-only dependencies — install alongside requirements.txt in CI and local dev
+# pip install -r requirements.txt -r requirements-test.txt
+
+pytest>=7.4
+pytest-cov>=4.1
+pytest-mock>=3.11
+coverage[toml]>=7.3
+vulture>=2.10
diff --git a/tests/run_tests.sh b/tests/run_tests.sh
index 500e688..15d31f8 100755
--- a/tests/run_tests.sh
+++ b/tests/run_tests.sh
@@ -1,17 +1,25 @@
#!/bin/bash
-# Run all unit tests and generate a coverage report
+# Run all unit tests and generate a coverage report.
+# Coverage config is in pyproject.toml [tool.coverage.*].
-export PYTHONPATH=$PYTHONPATH:.
+set -euo pipefail
-# Check if pytest-cov is installed
-if pytest --trace-config | grep -q "pytest_cov"; then
+export PYTHONPATH="${PYTHONPATH:+$PYTHONPATH:}."
+
+if python -c "import pytest_cov" 2>/dev/null; then
echo "Running tests with coverage..."
- pytest --cov=knoe --cov=install --cov-report=term-missing --cov-report=html tests/
+ pytest \
+ --cov=knoe \
+ --cov-report=term-missing \
+ --cov-report=html \
+ --cov-report=xml \
+ tests/
RET=$?
- echo "Coverage report (HTML) generated in htmlcov/index.html"
+ echo "HTML coverage report: htmlcov/index.html"
+ echo "XML coverage report: coverage.xml"
exit $RET
else
echo "Warning: pytest-cov not found. Running tests without coverage."
- echo "To enable coverage, install it via: pip install pytest-cov"
+ echo "Install it with: pip install -r requirements-test.txt"
pytest tests/
fi
diff --git a/tmp/create_synology_dirs.sh b/tmp/create_synology_dirs.sh
index fed6411..978dece 100644
--- a/tmp/create_synology_dirs.sh
+++ b/tmp/create_synology_dirs.sh
@@ -2,14 +2,14 @@
set -euo pipefail
export KUBECONFIG=/Users/chrisfu/dev/knoe/knoe-k3s.kubeconfig
-echo "==> Creating /synology/d005/gitlab/{minio,gitaly} on gandalf.knoe.org..."
+echo "==> Creating /synology/d005/gitlab/{minio,gitaly} on gandalf.prole.org..."
kubectl -n gitlab run synology-mkdir \
--image=alpine:latest \
--restart=Never \
--rm --attach \
--overrides='{
"spec":{
- "nodeName":"gandalf.knoe.org",
+ "nodeName":"gandalf.prole.org",
"tolerations":[{"operator":"Exists"}],
"volumes":[{"name":"synology","hostPath":{"path":"/synology/d005","type":"Directory"}}],
"containers":[{
diff --git a/tmp/fix_pv_and_buckets_v3.sh b/tmp/fix_pv_and_buckets_v3.sh
index b1b452e..4c54ad1 100644
--- a/tmp/fix_pv_and_buckets_v3.sh
+++ b/tmp/fix_pv_and_buckets_v3.sh
@@ -26,7 +26,7 @@ spec:
- matchExpressions:
- key: kubernetes.io/hostname
operator: In
- values: [gandalf.knoe.org]
+ values: [gandalf.prole.org]
PVYAML
echo "==> Waiting 20s for gitaly PVC to bind..."
@@ -42,7 +42,7 @@ kubectl -n gitea run minio-init \
--image=quay.io/minio/mc:RELEASE.2022-10-20T23-30-35Z \
--restart=Never \
--overrides="{
- \"spec\":{\"nodeName\":\"gandalf.knoe.org\",\"tolerations\":[{\"operator\":\"Exists\"}],
+ \"spec\":{\"nodeName\":\"gandalf.prole.org\",\"tolerations\":[{\"operator\":\"Exists\"}],
\"containers\":[{\"name\":\"minio-init\",
\"image\":\"quay.io/minio/mc:RELEASE.2022-10-20T23-30-35Z\",
\"command\":[\"sh\",\"-c\",
diff --git a/tmp/fix_pvs.sh b/tmp/fix_pvs.sh
index 958f8b3..3d82e2b 100644
--- a/tmp/fix_pvs.sh
+++ b/tmp/fix_pvs.sh
@@ -30,7 +30,7 @@ spec:
- matchExpressions:
- key: kubernetes.io/hostname
operator: In
- values: [gandalf.knoe.org]
+ values: [gandalf.prole.org]
---
apiVersion: v1
kind: PersistentVolume
@@ -50,7 +50,7 @@ spec:
- matchExpressions:
- key: kubernetes.io/hostname
operator: In
- values: [gandalf.knoe.org]
+ values: [gandalf.prole.org]
PVYAML
echo "==> Waiting 15s for binding..."
diff --git a/tmp/sim_installer_ns.sh b/tmp/sim_installer_ns.sh
index ff57f07..9684ddb 100644
--- a/tmp/sim_installer_ns.sh
+++ b/tmp/sim_installer_ns.sh
@@ -25,8 +25,8 @@ export CLUSTER_NAME="knoe-db"
# Replicate milestones.py GitOpsMilestone.execute() lines 965-977
export GITLAB_NAMESPACE="gitlab" # line 971: env["GITLAB_NAMESPACE"] = ns (ns="gitlab")
-export GITLAB_NODE_SELECTOR="gandalf.knoe.org" # line 976
-export NODE_SELECTOR="gandalf.knoe.org" # line 977
+export GITLAB_NODE_SELECTOR="gandalf.prole.org" # line 976
+export NODE_SELECTOR="gandalf.prole.org" # line 977
echo " Pre-call env: NAMESPACE='$NAMESPACE' GITLAB_NAMESPACE='$GITLAB_NAMESPACE'"
echo ""