Stage 1: backend foundation (Postgres, sessions, accounts, OTel)

- internal/postgres: pgx-over-database/sql pool (otelsql), embedded goose
  migrations into schema 'backend', committed go-jet code + cmd/jetgen tool.
- internal/account: durable accounts + unified telegram/email identities
  (UUIDv7 keys), find-or-create provisioning with unique-conflict handling.
- internal/session: opaque 256-bit tokens stored as a SHA-256 hash, revoke-only
  (no TTL); write-through cache gating /readyz; store + service.
- internal/telemetry: OTel tracer/meter providers (none/stdout) + request-timing
  middleware; internal/config gains Postgres + OTel env loading.
- internal/server: /api/v1 {public,user,internal,admin} skeleton + X-User-ID
  middleware; /readyz checks DB ping + cache; main wires
  telemetry -> db+migrate -> warm cache -> server.
- Tests: unit + integration (build tag 'integration', testcontainers
  postgres:17) for migrations, accounts, sessions, readyz; new integration.yaml.
- Docs: ARCHITECTURE, TESTING, PLAN refinements, root + backend READMEs.

Session/account REST handlers deferred to Stage 6 (gateway); OTLP + dashboards
to Stage 11.

backend/internal/server/middleware.go

@@ -0,0 +1,41 @@
+package server
+
+import (
+	"context"
+	"net/http"
+
+	"github.com/gin-gonic/gin"
+	"github.com/google/uuid"
+)
+
+// headerUserID is the identity header the gateway injects after resolving a
+// session to an internal account.
+const headerUserID = "X-User-ID"
+
+// contextKey is an unexported type for request-context keys set by this package.
+type contextKey string
+
+const userIDContextKey contextKey = "scrabble.user_id"
+
+// RequireUserID returns middleware that requires a valid X-User-ID header and
+// stores the parsed account id in the request context. Requests without a
+// parseable UUID are rejected with 401. The backend treats X-User-ID as the
+// sole identity input and never derives identity from the request body.
+func RequireUserID() gin.HandlerFunc {
+	return func(c *gin.Context) {
+		id, err := uuid.Parse(c.GetHeader(headerUserID))
+		if err != nil {
+			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing or invalid X-User-ID"})
+			return
+		}
+		c.Request = c.Request.WithContext(context.WithValue(c.Request.Context(), userIDContextKey, id))
+		c.Next()
+	}
+}
+
+// UserIDFromContext returns the authenticated account id stored by
+// RequireUserID, and whether it was present.
+func UserIDFromContext(ctx context.Context) (uuid.UUID, bool) {
+	id, ok := ctx.Value(userIDContextKey).(uuid.UUID)
+	return id, ok
+}