feat(observability): count bounded auth outcomes

[gnanirahulnutakki]

Closes #272

Parent: #28 (E10)

Summary

• expose exactly two preinitialized sith_auth_attempts_total{outcome="accepted|refused"} series through the existing optional loopback metrics endpoint
• emit accepted immediately after bearer-token or browser-session verifier success and before workspace authorization
• preserve the legacy unlabeled sith_auth_refusals_total, incremented exactly once per refusal
• keep the process audit observer and structured-log adapter strictly refusal-only
• document the privacy boundary, compatibility behavior, operator cost, and explicit nonclaims

Security and semantics

• authentication and authorization remain separate: a valid credential forbidden from a workspace counts as accepted authentication followed by denied authorization
• the event and metric contain no credential, reason, tenant, workspace, identity, token, network, route, request, error, trace, correlation, authorization, or handler-result dimension
• accepted observations cannot log, write an audit datagram, increment a refusal-delivery drop, or start child work
• this adds raw counter substrate only: no ratio, detector, alert, SLO, page, listener, exporter, persistence, remote write, or cloud resource

Verification

• focused package tests and focused race tests pass for hubserver, observability, auditdelivery, and hubruntime
• full make ci passes with zero lint issues, no reachable vulnerabilities, repository race/coverage, policy gates, alert-rule validation, latency guard, tagged e2e, and build; observability coverage is 94.7%
• PostgreSQL 18.4 forced-RLS suites pass at 76.2% hubdb coverage, plus both 50,000-execution cross-workspace fuzz campaigns
• reproducible multi-platform release, checksums, SPDX SBOMs, Homebrew metadata, and release-derived two-platform OCI layout pass
• pinned Helm 4.2.3 and standalone two-platform OCI contract gates pass
• real Kubernetes v1.36.1 two-cluster Kind gate passes in 238.997 seconds; independent cleanup finds zero Kind clusters and zero Sith/Kind test containers
• final 30,835-byte secret-signature scan has zero candidates
• three complete 16-file CodeRabbit reviews have zero findings
• README, E10 notes, Notion, Obsidian, and the EXTENDED session record are synchronized

Signed checkpoint

• base: 89cffa5cb6f4e51c8c5f4ef9410f323ee044f493
• head: fa22b073dc2870537ebff05b4f4bf83b19885b54
• verified ED25519 signature, DCO sign-off, and GSTACK-Checkpoint: 2026-07-18/e10-auth-outcome-counter#1

Exact-head hosted CI, CodeQL, and review remain required before merge. Exact post-merge dev CI and CodeQL remain required before closeout.

Summary by CodeRabbit

• New Features

  • Added bounded authentication-attempt metrics showing accepted and refused outcomes.
  • Successful authentication now records an accepted outcome before authorization.
  • Console authentication now reports accepted outcomes consistently.

• Bug Fixes

  • Authentication refusal audit records are emitted only for explicitly refused attempts.
  • Accepted authentication events no longer produce refusal logs or audit deliveries.
  • Authentication metrics and documentation now clarify fixed labels and privacy safeguards.

• Documentation

  • Updated runtime, chart, observability, and metrics documentation to describe the new authentication outcome counters.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: af30479f-0b2d-41a2-b367-111ee8880a2c

📥 Commits

Reviewing files that changed from the base of the PR and between 89cffa5 and fa22b07.

📒 Files selected for processing (16)

• README.md
• charts/sith-hub/README.md
• docs/EPICS.md
• docs/SITH-NOTION.md
• internal/auditdelivery/process.go
• internal/auditdelivery/process_test.go
• internal/hubserver/auth.go
• internal/hubserver/auth_observability.go
• internal/hubserver/auth_observability_test.go
• internal/hubserver/console.go
• internal/hubserver/console_test.go
• internal/observability/auth.go
• internal/observability/auth_test.go
• internal/observability/metrics.go
• internal/observability/metrics_test.go
• sessions/2026-07-18-e10-auth-outcome-counter.md

---

📝 Walkthrough

Walkthrough

Authentication verification now emits accepted and refused outcomes, exposes bounded Prometheus attempt counters, preserves the legacy refusal counter, and prevents accepted events from reaching audit or logging sinks. Documentation and tests cover the new boundaries.

Changes

Authentication outcome observability

Layer / File(s)	Summary
Outcome contracts and emission internal/hubserver/auth*.go, internal/hubserver/console.go, internal/hubserver/*_test.go	Authentication events accept only accepted or refused; successful bearer and console verification emits accepted before handler or workspace authorization.
Bounded authentication metrics internal/observability/metrics.go, internal/observability/metrics_test.go	Registers and preinitializes sith_auth_attempts_total for both outcomes, increments it from validated events, and increments the legacy refusal counter only for refused events.
Refusal-only audit and logging sinks internal/auditdelivery/*, internal/observability/auth*	Accepted events are ignored by audit datagram and structured logging observers, while refused events retain existing handling.
Boundary documentation and verification README.md, charts/sith-hub/README.md, docs/EPICS.md, docs/SITH-NOTION.md, sessions/*	Documentation describes outcome semantics, fixed labels, refusal compatibility, excluded telemetry dimensions, and verification results.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Authentication
  participant Observers
  participant Metrics
  Client->>Authentication: submit credentials
  Authentication->>Observers: emit accepted or refused AuthEvent
  Observers->>Metrics: increment outcome counter
  Observers-->>Client: preserve authentication response

Loading

Possibly related PRs

• ArdurAI/sith#142: Added the initial refusal-focused authentication observer plumbing extended by this PR.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 17.65% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately summarizes the main change: bounded auth outcome observability.
Linked Issues check	✅ Passed	The changes match the linked issue by adding accepted/refused auth attempts, preserving refusal-only observers, and updating docs and tests.
Out of Scope Changes check	✅ Passed	No clear out-of-scope changes are evident; the edits stay within auth outcome metrics, observers, tests, and related documentation.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch gnanirahulnutakki/feat/e10-auth-outcome-counter

---

_{Comment @coderabbitai help to get the list of available commands.}

[gnanirahulnutakki]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.