Go net/http Adapter

The Go net/http adapter wraps handlers with verify-engine verification and stores verified claims in the request context.

Use it for inbound net/http handlers. It does not create outbound Caracal context or replace the Go application SDK.

Install

go get github.com/garudex-labs/caracal/packages/adapters/nethttp/go

Middleware

import (
  "net/http"
  "time"

  nethttp "github.com/garudex-labs/caracal/packages/adapters/nethttp/go"
  revocation "github.com/garudex-labs/caracal/packages/revocation/go"
  verify "github.com/garudex-labs/caracal/packages/verify/go"
)

revocations := revocation.NewInMemoryStore(24 * time.Hour)

verifier := verify.NewVerifier(verify.Options{
  Issuer:          "https://sts.pipernet.example",
  Audience:        "https://api.pipernet.example",
  ZoneID:          "0195f2a9-1b22-7c3d-9e4f-5a6b7c8d9e0f",
  Revocations:     revocations,
})

handler := nethttp.VerifierMiddleware(verifier.Require(verify.Options{
  RequiredScopes:  []string{"pipernet:read"},
  RequiredTargets: []string{"resource://pipernet"},
  RequireSession:  true,
}))(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
  claims, ok := nethttp.ClaimsFromContext(r.Context())
  if !ok {
    http.Error(w, "missing claims", http.StatusUnauthorized)
    return
  }
  _, _ = w.Write([]byte(claims.Sub))
}))

APIs

API	Purpose
`Middleware(opts)`	Return middleware that verifies the bearer token and rejects failed requests.
`VerifierMiddleware(verifier)`	Return middleware backed by a reusable verifier with shared defaults.
`ClaimsFromContext(ctx)`	Retrieve verified Caracal claims inside a handler.

Middleware constructs a verifier from verify.Options; VerifierMiddleware reuses an existing verifier. A nil verifier produces a verifier with empty options and therefore cannot establish a properly configured production boundary; always pass trusted issuer, audience, zone, and revocation settings.

Failure behavior

The middleware maps verification errors to HTTP failures before the handler runs and includes a safe error_hint in JSON failures. Use a shared revocation store through verify.Options in production so revoked sessions are rejected consistently across service instances.