# 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.