Architecture

Trust boundary:

External Git client → Caddy → Sztab (auth) → Sztabina

Caddy configuration:

git.sztab.company.com forward_auth sztab:8080 uri /api/auth/validate-git-request copy_headers Authorization reverse_proxy sztabina:8085

Key properties:

• Caddy blocks unauthorized requests
• Sztabina never sees authentication failures
• Git protocol semantics remain unchanged

Authentication Contract

Validation endpoint implemented in Sztab:

/api/auth/validate-git-request

Requirements:

• Stateless
• Low latency
• Safe for repeated calls per Git operation
• No redirects, cookies, or HTML

Expected behavior:

• HTTP 200 → request allowed
• HTTP 401 / 403 → request denied

This endpoint acts as a gatekeeper, not a login flow.

Implementation Tasks

1. Define Personal Access Token (PAT) model and validation rules
2. Implement /api/auth/validate-git-request endpoint in Sztab
3. Integrate Caddy forward_auth with Sztab
4. Add external Git domain and TLS configuration
5. Verify correct behavior for:
   • git clone
   • git fetch
   • git push
6. Ensure clean failure modes (401/403)
7. Add minimal logging for auth failures

Testing

• Requests without PAT are rejected
• Requests with invalid or expired PAT are rejected
• Requests with valid PAT succeed
• Internal authless access continues to work
• No authentication logic exists in Sztabina
• Git operations behave correctly under repeated auth checks

Risks

• Auth endpoint latency affecting Git operations
• Misconfigured headers breaking Git HTTP semantics

Mitigation:

• Keep auth endpoint minimal and stateless
• Load-test with repeated Git operations
• Add explicit logging at the proxy and auth boundary

Acceptance Criteria

• External Git access requires a valid PAT
• Invalid or missing PAT always results in 401/403
• Internal Git access remains auth-free
• No authentication code exists in Sztabina
• Design is documented and reproducible

Time Estimate

• Auth design review: 0.5 h
• PAT validation logic (backend): 2.0 h
• Auth endpoint implementation: 1.5 h
• Caddy forward_auth integration: 1.0 h
• External domain + TLS setup: 1.0 h
• End-to-end Git testing: 2.0 h
• Documentation update: 0.5 h

Total estimate: 8.5 hours

end to end tested, merged into wolnosc