Initial commit

Author: jb3

.github/workflows/docker-publish.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+    tags: [ 'v*' ]
+  pull_request:
+    branches: [ main ]
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Log in to the Container registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest,enable={{github.event_name != 'pull_request'}}
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -0,0 +1,34 @@
+### Go ###
+# If you prefer the allow list template instead of the deny list, see community template:
+# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore
+#
+# Binaries for programs and plugins
+*.exe
+*.exe~
+*.dll
+*.so
+*.dylib
+
+# Test binary, built with `go test -c`
+*.test
+
+# Output of the go coverage tool, specifically when used with LiteIDE
+*.out
+
+# Dependency directories (remove the comment below to include it)
+# vendor/
+
+# Go workspace file
+go.work
+
+# Project Specific
+reference/
+
+# Environment
+.env
+
+# Binaries
+/hafnium
+
+# Config
+mappings.toml

Dockerfile

@@ -0,0 +1,23 @@
+# Build stage
+FROM golang:1.24-alpine AS builder
+
+WORKDIR /app
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+RUN CGO_ENABLED=0 GOOS=linux go build -o hafnium ./cmd/hafnium
+
+# Final stage
+FROM alpine:latest
+
+RUN apk --no-cache add ca-certificates
+
+WORKDIR /root/
+
+COPY --from=builder /app/hafnium .
+
+# Example command, but should be overridden or use env vars
+CMD ["./hafnium"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Owl Corp
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,83 @@
+# Hafnium
+
+Hafnium is a standalone Go daemon that synchronizes Keycloak role memberships with GitHub organization and team memberships. It replaces the legacy Discord bot implementation with a more efficient, concurrent, and observable service.
+
+## Features
+
+- **Concurrent Sync:** Optimized data fetching from Keycloak and GitHub using Go's concurrency primitives.
+- **Organization Sync:** Automatically adds/removes members from the GitHub organization based on Keycloak linked identities.
+- **Team Sync:** Synchronizes Keycloak roles to GitHub team memberships using a configurable mapping.
+- **Invitation Management:**
+  - Sends Discord DMs for new organization invitations.
+  - Automatically cleans up and notifies users about failed/expired invitations.
+- **Observability:**
+  - Prometheus metrics (`/metrics`) for monitoring sync performance and state.
+  - Structured logging for easy troubleshooting.
+- **Configuration:** Flexible configuration via environment variables and TOML mapping files.
+
+## Configuration
+
+Hafnium is configured via environment variables (prefixed with `HAFNIUM_`), CLI flags, or a configuration file.
+
+### CLI Help
+
+For a full list of configuration options and flags, run:
+
+```bash
+./hafnium --help
+```
+
+### Keycloak & GitHub URLs
+
+- **GitHub Invitation Link:** Automatically generated as `https://github.com/orgs/{org}/invitation`.
+- **Keycloak Account Link:** Automatically generated as `https://id.pydis.wtf/realms/{realm}/account/account-security/linked-accounts`.
+
+### Role Mapping (`mappings.toml`)
+
+Create a TOML file to map Keycloak roles to GitHub team slugs and Discord roles:
+
+```toml
+[mappings]
+helpers = { github_team_slug = "helpers", discord_role_id = 267630620367257601 }
+devops = { github_team_slug = "devops", discord_role_id = 409416496733880320 }
+```
+
+## Metrics
+
+Hafnium exposes the following Prometheus metrics:
+
+- `hafnium_org_members_total`: Total organization members.
+- `hafnium_team_members_total{team="slug"}`: Total members in a specific team.
+- `hafnium_keycloak_users_total`: Total users found in Keycloak.
+- `hafnium_org_added_total`: Counter for users added to the org.
+- `hafnium_org_removed_total`: Counter for users removed from the org.
+- `hafnium_team_added_total{team="slug"}`: Counter for users added to a team.
+- `hafnium_team_removed_total{team="slug"}`: Counter for users removed from a team.
+- `hafnium_sync_duration_seconds`: Histogram of sync task duration.
+
+## Development
+
+### Building Locally
+
+```bash
+go build -o hafnium ./cmd/hafnium
+```
+
+### Running with Docker
+
+```bash
+docker build -t hafnium .
+docker run --env-file .env hafnium
+```
+
+### CLI Help
+
+You can view usage information and configuration details by running:
+
+```bash
+./hafnium --help
+```
+
+## License
+
+[MIT](LICENSE)

cmd/hafnium/main.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"context"
+	"log"
+	"net/http"
+	"os"
+	"os/signal"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus/promhttp"
+	"github.com/spf13/cobra"
+	"github.com/spf13/viper"
+
+	"github.com/owl-corp/hafnium/config"
+	"github.com/owl-corp/hafnium/pkg/discord"
+	"github.com/owl-corp/hafnium/pkg/github"
+	"github.com/owl-corp/hafnium/pkg/keycloak"
+	"github.com/owl-corp/hafnium/pkg/sync"
+)
+
+var (
+	v = viper.New()
+)
+
+func main() {
+	rootCmd := &cobra.Command{
+		Use:   "hafnium",
+		Short: "Keycloak to GitHub Sync Daemon",
+		Long:  "A standalone daemon that synchronizes Keycloak role memberships with GitHub organization and team memberships.",
+		Run:   run,
+	}
+
+	config.BindFlags(rootCmd.Flags(), v)
+
+	// Environment variable setup
+	v.SetEnvPrefix("HAFNIUM")
+	v.SetEnvKeyReplacer(strings.NewReplacer(".", "_"))
+	v.AutomaticEnv()
+
+	if err := rootCmd.Execute(); err != nil {
+		os.Exit(1)
+	}
+}
+
+func run(cmd *cobra.Command, args []string) {
+	log.Println("Starting Hafnium...")
+
+	cfg, err := config.LoadConfig(v)
+	if err != nil {
+		log.Fatalf("Configuration error: %v", err)
+	}
+
+	kcClient := keycloak.NewClient(cfg.Keycloak.URL, cfg.Keycloak.Realm, cfg.Keycloak.Username, cfg.Keycloak.Password)
+	ghClient := github.NewClient(cfg.Github.Token, cfg.Github.Org)
+	dcClient, err := discord.NewClient(cfg.Discord.Token)
+	if err != nil {
+		log.Fatalf("Failed to initialize Discord client: %v", err)
+	}
+	defer dcClient.Close()
+
+	engine := sync.NewEngine(cfg, kcClient, ghClient, dcClient)
+
+	// Metrics server
+	go func() {
+		log.Printf("Starting metrics server on %s", cfg.Metrics.Addr)
+		http.Handle("/metrics", promhttp.Handler())
+		if err := http.ListenAndServe(cfg.Metrics.Addr, nil); err != nil {
+			log.Printf("Metrics server error: %v", err)
+		}
+	}()
+
+	// Sync loop
+	ctx, cancel := context.WithCancel(context.Background())
+	defer cancel()
+
+	ticker := time.NewTicker(cfg.Sync.Interval)
+	defer ticker.Stop()
+
+	// Run initial sync
+	runSync(ctx, engine)
+
+	sigChan := make(chan os.Signal, 1)
+	signal.Notify(sigChan, syscall.SIGINT, syscall.SIGTERM)
+
+	for {
+		select {
+		case <-ticker.C:
+			runSync(ctx, engine)
+		case sig := <-sigChan:
+			log.Printf("Received signal %v, shutting down...", sig)
+			return
+		case <-ctx.Done():
+			return
+		}
+	}
+}
+
+func runSync(ctx context.Context, engine *sync.Engine) {
+	log.Println("Starting sync run...")
+	if err := engine.Sync(ctx); err != nil {
+		log.Printf("Sync error: %v", err)
+	}
+	log.Println("Sync run complete.")
+}