gitea-mcp-forward-auth/.github/copilot-instructions.md

GitHub Copilot Instructions

This repository contains a small Go-based Traefik ForwardAuth service for gitea-mcp access control. Keep changes minimal, infrastructure-aware, and aligned with the deployment and CI conventions below.

Project Purpose

• This service validates Authorization: Bearer <token> for Traefik ForwardAuth.
• The service is intentionally small and should prefer the Go standard library over additional frameworks.
• Authentication is hash-only: the service stores and loads only SHA-256 token hashes, never plaintext tokens.

Go and Build Conventions

• Use Go 1.26 unless the repository is explicitly updated to a newer version.
• Keep the module path aligned with the self-hosted Gitea instance: gitea.nehmer.net/torben/gitea-mcp-forward-auth.
• Prefer standard library packages such as net/http, log/slog, and crypto/subtle.
• Keep code testable: separate token validation logic from HTTP handler behavior.

Security Requirements

• Never log plaintext bearer tokens.
• Only log a short token fingerprint or derived identifier that does not reveal the original token.
• Token comparisons must remain constant-time.
• Token configuration must stay hash-based:
  • AUTH_PROXY_TOKEN_HASHES_DIR
  • AUTH_PROXY_TOKEN_HASHES
• Do not reintroduce plaintext token configuration or examples.
• /healthz does not need to be world-readable. Prefer internal-only exposure for k3s probes and Prometheus.

Kubernetes and Deployment Assumptions

• Kubernetes manifests under deploy/k3s/ are reference examples only.
• Actual cluster deployment and rollout automation happen in a separate FluxCD repository.
• Do not add FluxCD deployment logic to this repository unless explicitly requested.
• Keep the Service internal (ClusterIP) unless the user explicitly asks otherwise.
• NetworkPolicy changes must preserve the assumption that only trusted in-cluster components should reach this service.
• If labels or namespaces for Traefik or Prometheus are assumed, mark them explicitly as assumptions in comments or docs.

CI/CD Conventions

• Gitea Actions are the target, not GitHub Actions cloud defaults.
• Container build jobs must use:
  • runs-on: container-builder
  • container.image: debian:trixie-slim
• If a workflow uses Node-based actions such as actions/checkout or actions/setup-go, install required tools first inside the runner container.
• Prefer Debian Trixie package names and behavior when editing workflows.
• The Go package registry is the self-hosted Gitea registry:
  • https://gitea.nehmer.net/api/packages/torben/go
• Preserve GOPROXY usage with the Gitea registry first, then public fallback if already used by the repo.

Container Release Conventions

• Release images are published to gitea.nehmer.net/torben.
• The image name is gitea-mcp-auth-proxy unless the user changes it explicitly.
• Release builds use a remote BuildKit daemon, not a local Docker daemon.
• Preserve the remote builder pattern:
  • determine host IP from the default route
  • connect to tcp://$HOST_IP:1234
• Keep the 1Password secret-loading pattern for registry credentials.
• Stable tags (vX.Y.Z) may publish latest; prerelease tags must not publish latest.

Repo Hygiene

• Ignore only the root build artifact /authproxy; do not ignore cmd/authproxy.
• When changing workflows, prefer explicit artifact paths like dist/... over implicit binary output in the repo root.
• Check README.md on updates and expand usage instructions where necessary. The file should be targeted for using the proxy, not for developing it.

Documentation Style

• Call out infrastructure-specific behavior as Assumption: when it depends on the user's environment.
• Keep examples consistent with the current security model, especially hash-only token configuration.
• Do not describe this repository as the deployment source of truth; it only builds the service and related reference manifests.