feat: build core API, fraud engine, notifier, and frontend

Phase 1 — Core API (Go): - Events, guests, tokens, RSVPs CRUD on PostgreSQL via pgx/v5 - HMAC-signed per-guest tokens with format validation - Health endpoint with DB ping, slog JSON logging, graceful shutdown Phase 2 — NATS + Fraud Engine: - NATS JetStream pub/sub with explicit-ack consumers - Python/FastAPI fraud engine with heuristic risk scoring (fingerprint mismatch, IP change, missing signals, repeated access) - gRPC sync scoring with 250ms fail-open timeout - Per-guest baseline tracking; risk bands low/medium/high/block Phase 3 — Notifications + Frontend: - Notification worker scaffolding (Twilio/SES stubs, retry/backoff) - Nuxt 3 frontend with Tailwind dark theme + brand green - Live monitor via WebSocket with auto-reconnect - Activity history endpoint backfills monitor with RSVPs + scored access checks (including blocked attempts) UX polish: - Marketing-friendly landing page (hero mockup, how-it-works, features, use cases, testimonials, FAQ, final CTA) - Animated layered card mockups on landing + new-event page - Plus-ones stepper, RSVP status badges, filter buttons - Friendly access-check labels (Verified/Review/Suspicious/Blocked) - Dashboard hydration fix via ClientOnly wrapper Infrastructure: - docker-compose for full local dev (postgres, nats, api, fraud-engine, notifier, frontend) - Multi-stage Dockerfiles, non-root UID 1000 - Integration tests with testcontainers-go Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-11 21:08:56 +01:00
parent f760fc3e21
commit 3f8bc58ca9
89 changed files with 22729 additions and 0 deletions
@@ -0,0 +1,27 @@
+FROM golang:1.26-alpine AS build
+WORKDIR /src
+
+RUN apk add --no-cache ca-certificates git
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+ARG VERSION=dev
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -ldflags="-s -w -X main.version=${VERSION}" \
+    -o /out/api ./cmd/api
+
+FROM alpine:3.20 AS runtime
+RUN apk add --no-cache ca-certificates tzdata && \
+    addgroup -g 1000 app && \
+    adduser -D -u 1000 -G app app
+
+WORKDIR /app
+COPY --from=build /out/api /app/api
+
+USER 1000:1000
+EXPOSE 8080
+
+ENTRYPOINT ["/app/api"]
@@ -0,0 +1,172 @@
+package main
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"log/slog"
+	"net/http"
+	"os"
+	"os/signal"
+	"syscall"
+	"time"
+
+	"github.com/alchemistkay/guestguard/internal/api"
+	"github.com/alchemistkay/guestguard/internal/config"
+	"github.com/alchemistkay/guestguard/internal/fraud"
+	"github.com/alchemistkay/guestguard/internal/natspub"
+	"github.com/alchemistkay/guestguard/internal/storage"
+)
+
+func main() {
+	if err := run(); err != nil {
+		slog.Error("fatal", "err", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	cfg, err := config.Load()
+	if err != nil {
+		return err
+	}
+
+	logger := newLogger(cfg.Env)
+	slog.SetDefault(logger)
+
+	rootCtx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	logger.Info("connecting to database")
+	db, err := storage.NewDB(rootCtx, cfg.DatabaseURL)
+	if err != nil {
+		return err
+	}
+	defer db.Close()
+
+	logger.Info("running migrations")
+	if err := db.Migrate(rootCtx); err != nil {
+		return err
+	}
+
+	logger.Info("connecting to nats", "url", cfg.NATSURL)
+	natsClient, err := natspub.Connect(rootCtx, cfg.NATSURL, logger)
+	if err != nil {
+		return err
+	}
+	defer natsClient.Close()
+
+	logger.Info("dialing fraud engine", "addr", cfg.FraudGRPCAddr)
+	fraudClient, err := fraud.Dial(rootCtx, cfg.FraudGRPCAddr, cfg.FraudGRPCTimeout, logger)
+	if err != nil {
+		return err
+	}
+	defer fraudClient.Close()
+
+	hub := api.NewHub(logger)
+
+	accessLogs := storage.NewAccessLogRepo(db)
+	fraudSub, err := natspub.NewFraudScoredSubscriber(
+		rootCtx, natsClient, "core-api-fraud-scored",
+		func(ctx context.Context, evt natspub.FraudScored) error {
+			if err := accessLogs.ApplyScore(ctx, storage.ApplyScoreParams{
+				AccessLogID: evt.AccessLogID,
+				Score:       evt.Score,
+				Reasons:     evt.Reasons,
+				Flagged:     evt.Score >= 60,
+			}); err != nil {
+				return err
+			}
+			payload, _ := json.Marshal(evt)
+			hub.Broadcast(api.WSEvent{
+				Type:    "fraud.scored",
+				EventID: evt.EventID,
+				Payload: payload,
+			})
+			return nil
+		},
+		logger,
+	)
+	if err != nil {
+		return err
+	}
+	fraudConsumeCtx, err := fraudSub.Start(rootCtx)
+	if err != nil {
+		return err
+	}
+	defer fraudConsumeCtx.Stop()
+
+	rsvpSub, err := natspub.NewRSVPConfirmedSubscriber(
+		rootCtx, natsClient, "core-api-rsvp-confirmed-ws",
+		func(ctx context.Context, evt natspub.RSVPConfirmed) error {
+			payload, _ := json.Marshal(evt)
+			hub.Broadcast(api.WSEvent{
+				Type:    "rsvp.confirmed",
+				EventID: evt.EventID,
+				Payload: payload,
+			})
+			return nil
+		},
+		logger,
+	)
+	if err != nil {
+		return err
+	}
+	rsvpConsumeCtx, err := rsvpSub.Start(rootCtx)
+	if err != nil {
+		return err
+	}
+	defer rsvpConsumeCtx.Stop()
+
+	srv := &http.Server{
+		Addr: cfg.HTTPAddr,
+		Handler: api.NewServer(api.ServerDeps{
+			Logger:          logger,
+			DB:              db,
+			Hub:             hub,
+			AccessPublisher: natsClient,
+			RSVPPublisher:   natsClient,
+			FraudScorer:     fraudClient,
+			TokenTTL:        cfg.TokenTTL,
+		}).Handler(),
+		ReadHeaderTimeout: 5 * time.Second,
+		ReadTimeout:       30 * time.Second,
+		WriteTimeout:      0, // 0 lets WS connections live; per-request handlers still bound by their own ctx
+		IdleTimeout:       60 * time.Second,
+	}
+
+	errCh := make(chan error, 1)
+	go func() {
+		logger.Info("http server starting", "addr", cfg.HTTPAddr, "env", cfg.Env)
+		if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+			errCh <- err
+		}
+		close(errCh)
+	}()
+
+	select {
+	case <-rootCtx.Done():
+		logger.Info("shutdown signal received")
+	case err := <-errCh:
+		if err != nil {
+			return err
+		}
+	}
+
+	shutdownCtx, cancel := context.WithTimeout(context.Background(), cfg.ShutdownTimeout)
+	defer cancel()
+	if err := srv.Shutdown(shutdownCtx); err != nil {
+		logger.Error("graceful shutdown failed", "err", err)
+		return err
+	}
+	logger.Info("shutdown complete")
+	return nil
+}
+
+func newLogger(env string) *slog.Logger {
+	level := slog.LevelInfo
+	if env == "development" {
+		level = slog.LevelDebug
+	}
+	return slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: level}))
+}
@@ -0,0 +1,26 @@
+FROM golang:1.26-alpine AS build
+WORKDIR /src
+
+RUN apk add --no-cache ca-certificates git
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+COPY . .
+
+ARG VERSION=dev
+RUN CGO_ENABLED=0 GOOS=linux go build \
+    -ldflags="-s -w -X main.version=${VERSION}" \
+    -o /out/notifier ./cmd/notifier
+
+FROM alpine:3.20 AS runtime
+RUN apk add --no-cache ca-certificates tzdata && \
+    addgroup -g 1000 app && \
+    adduser -D -u 1000 -G app app
+
+WORKDIR /app
+COPY --from=build /out/notifier /app/notifier
+
+USER 1000:1000
+
+ENTRYPOINT ["/app/notifier"]
@@ -0,0 +1,209 @@
+package main
+
+import (
+	"context"
+	"log/slog"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/alchemistkay/guestguard/internal/config"
+	"github.com/alchemistkay/guestguard/internal/natspub"
+	"github.com/alchemistkay/guestguard/internal/notification"
+	"github.com/alchemistkay/guestguard/internal/storage"
+)
+
+func main() {
+	if err := run(); err != nil {
+		slog.Error("fatal", "err", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	cfg, err := config.Load()
+	if err != nil {
+		return err
+	}
+
+	logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: levelFor(cfg.Env)}))
+	slog.SetDefault(logger)
+	logger = logger.With("service", "notifier")
+
+	rootCtx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	logger.Info("connecting to database")
+	db, err := storage.NewDB(rootCtx, cfg.DatabaseURL)
+	if err != nil {
+		return err
+	}
+	defer db.Close()
+
+	logger.Info("connecting to nats", "url", cfg.NATSURL)
+	natsClient, err := natspub.Connect(rootCtx, cfg.NATSURL, logger)
+	if err != nil {
+		return err
+	}
+	defer natsClient.Close()
+
+	repo := notification.NewRepo(db)
+	sender := notification.LogSender{}
+
+	rsvpSub, err := natspub.NewRSVPConfirmedSubscriber(
+		rootCtx, natsClient, "notifier-rsvp-confirmed",
+		func(ctx context.Context, evt natspub.RSVPConfirmed) error {
+			return handleRSVPConfirmed(ctx, logger, repo, sender, evt)
+		},
+		logger,
+	)
+	if err != nil {
+		return err
+	}
+	rsvpCC, err := rsvpSub.Start(rootCtx)
+	if err != nil {
+		return err
+	}
+	defer rsvpCC.Stop()
+
+	fraudSub, err := natspub.NewFraudScoredSubscriber(
+		rootCtx, natsClient, "notifier-fraud-scored",
+		func(ctx context.Context, evt natspub.FraudScored) error {
+			return handleFraudScored(ctx, logger, repo, sender, evt)
+		},
+		logger,
+	)
+	if err != nil {
+		return err
+	}
+	fraudCC, err := fraudSub.Start(rootCtx)
+	if err != nil {
+		return err
+	}
+	defer fraudCC.Stop()
+
+	logger.Info("notifier started")
+	<-rootCtx.Done()
+	logger.Info("notifier shutting down")
+	return nil
+}
+
+func handleRSVPConfirmed(
+	ctx context.Context,
+	logger *slog.Logger,
+	repo *notification.Repo,
+	sender notification.Sender,
+	evt natspub.RSVPConfirmed,
+) error {
+	msg := notification.OutboundMessage{
+		GuestID: evt.GuestID,
+		Channel: notification.ChannelEmail,
+		Type:    notification.TypeConfirmation,
+		Subject: "Your RSVP is confirmed",
+		Body:    "Thanks for your response.",
+		Metadata: map[string]any{
+			"rsvp_id":     evt.RSVPID,
+			"event_id":    evt.EventID,
+			"response":    evt.Response,
+			"plus_ones":   evt.PlusOnes,
+			"risk_score":  evt.RiskScore,
+			"submitted_at": evt.SubmittedAt,
+		},
+	}
+
+	providerID, sendErr := sender.Send(ctx, msg)
+	status := notification.StatusSent
+	errStr := ""
+	if sendErr != nil {
+		status = notification.StatusFailed
+		errStr = sendErr.Error()
+	}
+
+	id, err := repo.Record(ctx, notification.RecordParams{
+		GuestID:    evt.GuestID,
+		Channel:    msg.Channel,
+		Type:       msg.Type,
+		Status:     status,
+		ProviderID: providerID,
+		Error:      errStr,
+	})
+	if err != nil {
+		return err
+	}
+
+	logger.Info("notification dispatched",
+		"notification_id", id,
+		"guest_id", evt.GuestID,
+		"channel", msg.Channel,
+		"type", msg.Type,
+		"status", status,
+		"provider_id", providerID,
+	)
+	return nil
+}
+
+func handleFraudScored(
+	ctx context.Context,
+	logger *slog.Logger,
+	repo *notification.Repo,
+	sender notification.Sender,
+	evt natspub.FraudScored,
+) error {
+	// Only alert when the score crosses a meaningful threshold; low/medium
+	// scores are noise for the host.
+	if evt.Score < 60 {
+		return nil
+	}
+
+	msg := notification.OutboundMessage{
+		GuestID: evt.GuestID,
+		Channel: notification.ChannelEmail,
+		Type:    notification.TypeReminder, // reusing existing enum; a fraud_alert type would be nicer
+		Subject: "Suspicious access attempt detected",
+		Body:    "A flagged access attempt occurred for one of your guests.",
+		Metadata: map[string]any{
+			"event_id": evt.EventID,
+			"score":    evt.Score,
+			"risk":     evt.Risk,
+			"reasons":  evt.Reasons,
+		},
+	}
+
+	providerID, sendErr := sender.Send(ctx, msg)
+	status := notification.StatusSent
+	errStr := ""
+	if sendErr != nil {
+		status = notification.StatusFailed
+		errStr = sendErr.Error()
+	}
+
+	id, err := repo.Record(ctx, notification.RecordParams{
+		GuestID:    evt.GuestID,
+		Channel:    msg.Channel,
+		Type:       msg.Type,
+		Status:     status,
+		ProviderID: providerID,
+		Error:      errStr,
+	})
+	if err != nil {
+		return err
+	}
+
+	logger.Warn("fraud alert dispatched",
+		"notification_id", id,
+		"guest_id", evt.GuestID,
+		"score", evt.Score,
+		"risk", evt.Risk,
+		"reasons", evt.Reasons,
+		"status", status,
+		"provider_id", providerID,
+	)
+	return nil
+}
+
+func levelFor(env string) slog.Level {
+	if env == "development" {
+		return slog.LevelDebug
+	}
+	return slog.LevelInfo
+}