feat(bearerauth): add mixed credential example

[appleboy]

Summary

Add a complete go-bearerauth example using
github.com/go-signet/sdk-go/bearerauth v1.1.0.

The example demonstrates:

• One protected route accepting JWT access tokens and Signet Personal API Keys.
• A framework-neutral net/http adapter around bearerauth.Verifier.
• Shared issuer, Client App, audience, and scope policy.
• RFC 6750-compatible authentication error mapping.
• Safe credential handling, output redaction, redirect refusal, and bounded I/O.
• Default tokeninfo and optional RFC 7662 introspection flows.
• Detailed setup, execution, troubleshooting, and security documentation.

The root README now distinguishes this mixed-credential example from the
JWT-only and all-online resource-server examples.

Related issues

• Jira: N/A
• GitHub/Gitea: N/A

Architecture / flow

flowchart TD
    C["New client<br/>client/main.go"] -->|"GET + Authorization: Bearer"| A["New HTTP adapter<br/>server/main.go"]
    A -->|"Raw credential only"| V["sdk-go/bearerauth v1.1.0"]
    V -->|"JWT"| J["OIDC discovery and lazy JWKS verification"]
    V -->|"sgk_ Personal API Key"| P["Online tokeninfo or introspection"]
    J --> I["New normalized identity context"]
    P --> I
    I --> R["New /api/whoami JSON response"]
    V -->|"Typed verification error"| E["New 401 / 403 / 503 / 500 mapping"]

    style C fill:#dff0d8,stroke:#3c763d,color:#1d3b1d
    style A fill:#dff0d8,stroke:#3c763d,color:#1d3b1d
    style I fill:#dff0d8,stroke:#3c763d,color:#1d3b1d
    style R fill:#dff0d8,stroke:#3c763d,color:#1d3b1d
    style E fill:#dff0d8,stroke:#3c763d,color:#1d3b1d
    style V fill:#f5f5f5,stroke:#777,color:#222
    style J fill:#f5f5f5,stroke:#777,color:#222
    style P fill:#f5f5f5,stroke:#777,color:#222

Loading

AI authorship

• No AI was used
• AI was used
  • Tool / model: Codex, GPT-5 family
  • AI-authored files: README.md, plan.md, and go-bearerauth/**
  • Human line-by-line reviewed: README.md, plan.md, and go-bearerauth/**

Change classification

• Leaf change
• Core change

This is classified as Core because it demonstrates authentication policy,
credential handling, and an external HTTP authentication interface.

Plan reference

plan.md records the approved goal, scope boundaries, implementation design,
verification strategy, risks, and rollback plan.

Verification

• Automated:
  • go mod tidy -diff — passed
  • go mod verify — passed
  • test -z "$(gofmt -l client/*.go server/*.go)" — passed
  • go vet ./... — passed
  • go test -race -count=1 ./... — passed
  • go test -count=10 ./... — passed
  • GOSUMDB=sum.golang.org GOTOOLCHAIN=go1.25.10 go test -count=1 ./... — passed
  • go test -cover -count=1 ./... — client 83.3%, server 80.5%
  • go build ./... — passed
  • git diff --check and git diff --staged --check — passed
• Manual:
  • All AI-authored files received human line-by-line review.
  • Authentication behavior and documentation were reviewed against the pinned SDK.
• Not run:
  • Live Signet smoke testing with real JWT and Personal API Key credentials was not run because no live issuer credentials were available.

Security check

• No secrets in the diff
• External inputs are validated
• Permission checks are tested
• Errors do not leak internals
• N/A - no external or security-sensitive interface changed

Risk and rollback

• Risk:
  • Incorrect issuer, audience, Client App, or scope configuration can reject otherwise valid credentials.
  • Personal API Key verification depends on Signet availability.
  • Offline JWT verification does not observe revocation until expiry.
  • Future SDK behavior could drift from the pinned example.
• Rollback:
  • Revert commit 307df54623a8.
  • This removes the standalone example and root README additions without changing the SDK, CI configuration, or existing examples.

Reviewer guide

• Read carefully:
  • go-bearerauth/server/main.go: verifier construction, header parsing, identity propagation, and error mapping.
  • go-bearerauth/client/main.go: credential redaction, URL validation, redirect refusal, and bounded responses.
  • go-bearerauth/README.md: SDK behavior, tokeninfo/introspection guidance, and security claims.
• Spot-check:
  • Client and server tests.
  • .env.example, module dependency pin, root README, and implementation plan.

[Copilot]

Pull request overview

Adds a new standalone Go example (go-bearerauth/) demonstrating “mixed credential” API protection: the same protected route accepts either JWT access tokens (offline verification after discovery/JWKS) or Signet Personal API Keys (online tokeninfo/introspection per request), with explicit net/http integration and RFC 6750-style error mapping.

Changes:

• Added a complete go-bearerauth client/server example with bounded I/O, redirect refusal, context identity propagation, and typed error → HTTP mapping.
• Added comprehensive unit tests for both the server adapter and the client behavior (including redaction and redirect refusal).
• Updated root documentation to list and distinguish the new mixed-credential example; added an implementation/verification plan.

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
README.md	Adds go-bearerauth to the example matrix and documents required env vars + positioning vs other resource-server examples.
plan.md	New implementation plan and verification strategy for the go-bearerauth example.
go-bearerauth/server/main.go	Implements the net/http adapter around bearerauth.Verifier, config validation, identity context propagation, and RFC 6750-style error mapping.
go-bearerauth/server/main_test.go	Tests config validation, header parsing, error mapping, concurrency safety, and fail-closed behavior.
go-bearerauth/client/main.go	Implements a safe example client: URL validation, redirect refusal, bounded response reads, and credential redaction.
go-bearerauth/client/main_test.go	Tests client exit codes, request construction, safe output/redaction, truncation, and redirect refusal.
go-bearerauth/README.md	Adds detailed setup/run/troubleshooting/security documentation for the mixed-credential flow and tokeninfo vs introspection.
go-bearerauth/.env.example	Provides a documented env template for both server policy and client invocation.
go-bearerauth/go.mod	Introduces a standalone module pinned to github.com/go-signet/sdk-go v1.1.0 plus supporting deps.
go-bearerauth/go.sum	Adds checksums for the new module dependencies.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.