Version: 1.0.0

Zero Trust Security & Observability

Shyntr is built with a security-first mindset, adhering to strict industry standards. Every component is designed under Zero Trust principles—never trust, always verify.

Security Standards Compliance

OpenID Connect Core 1.0

Shyntr implements full OpenID Connect compliance:

Feature	Support
`prompt` parameter	`none`, `login`, `consent`, `select_account`
`max_age` parameter	Session age validation
`auth_time` claim	Authentication timestamp in ID Token
`acr` / `amr` claims	Authentication context and methods
Scope validation	Strict validation against client configuration
Nonce validation	Replay protection for implicit flows

Example: Force Re-authentication
# Using max_age=0 forces re-authentication
GET /authorize?
  client_id=app123&
  response_type=code&
  scope=openid%20profile&
  max_age=0&
  prompt=login

RP-Initiated Logout

Secure session termination following OpenID Connect RP-Initiated Logout 1.0:

Logout Request
GET /oauth2/logout?
  id_token_hint=eyJhbGciOiJSUzI1NiIs...&
  post_logout_redirect_uri=https://app.example.com/logged-out&
  state=xyz123

Validation	Description
`id_token_hint`	Required for identifying the session to terminate
`post_logout_redirect_uri`	Validated against pre-registered URIs
Session invalidation	All tokens for the session are revoked

Advanced Security Features

RFC 7523: Private Key JWT Authentication

For high-security clients, Shyntr supports client authentication using signed JWTs instead of client secrets:

Token Request with Private Key JWT
curl -X POST "https://auth.example.com/oauth2/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=auth_code_here" \
  -d "client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer" \
  -d "client_assertion=eyJhbGciOiJSUzI1NiIs..."

The client assertion JWT must contain:

Client Assertion JWT Claims
{
  "iss": "client_id",
  "sub": "client_id",
  "aud": "https://auth.example.com/oauth2/token",
  "jti": "unique-jwt-id",
  "exp": 1234567890,
  "iat": 1234567800
}

When to Use Private Key JWT

Use private_key_jwt authentication for:

Machine-to-machine (M2M) applications
Backend services
Scenarios where client secrets cannot be stored securely
Compliance requirements mandating asymmetric authentication

Replay Protection

Shyntr implements comprehensive replay protection across all protocols:

JWT ID (JTI) Tracking

Every JWT processed by Shyntr is checked against a replay cache:

┌─────────────────────────────────────────────────────────────┐
│                   JTI Replay Protection                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. Client sends JWT with jti="abc123"                      │
│  2. Shyntr checks: Is "abc123" in used_jti_cache?           │
│     └─ If yes: Reject request (replay detected)             │
│     └─ If no: Process request, add "abc123" to cache        │
│  3. Cache entry expires after JWT expiration + grace period │
│                                                             │
└─────────────────────────────────────────────────────────────┘

SAML Message ID Tracking

SAML assertions are protected similarly:

InResponseTo: "_abc123def456"
└─ Tracked and validated against pending AuthnRequests
└─ Prevents assertion injection attacks

Tenant Isolation

Strict validation prevents cross-tenant data leakage:

Tenant Validation (Conceptual)
func validateRequest(ctx context.Context, req *Request) error {
    // Extract tenant from request context
    tenantID := extractTenantID(req)
    
    // Validate resource belongs to tenant
    if resource.TenantID != tenantID {
        // Log security event
        audit.Log(ctx, AuditEvent{
            Type:     "cross_tenant_access_attempt",
            TenantID: tenantID,
            Resource: resource.ID,
            Severity: "HIGH",
        })
        return ErrAccessDenied
    }
    
    return nil
}

Cross-Tenant Access

Every API call, token validation, and resource access is checked against tenant boundaries. Attempting to use credentials from one tenant in another is logged as a security event and denied.

Refresh Token Rotation with Grace Period

Shyntr implements refresh token rotation with network-failure tolerance:

┌─────────────────────────────────────────────────────────────────┐
│             Refresh Token Rotation Flow                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Client sends refresh_token_v1                               │
│  2. Shyntr issues new access_token + refresh_token_v2           │
│  3. refresh_token_v1 enters grace period (not immediately       │
│     invalidated)                                                │
│                                                                 │
│  Grace Period Scenarios:                                        │
│                                                                 │
│  ✅ Normal: Client uses refresh_token_v2 → Success              │
│  ✅ Network failure: Client retries with refresh_token_v1       │
│     → Success (within grace period)                             │
│  ❌ Attack: Attacker uses refresh_token_v1 after v2 was used    │
│     → Fail (entire refresh token family revoked)                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Enterprise Observability

W3C Trace Context (OpenTelemetry)

Shyntr natively integrates with OpenTelemetry for distributed tracing:

Enable OpenTelemetry
# Environment configuration
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
OTEL_SERVICE_NAME=shyntr
OTEL_TRACES_SAMPLER=parentbased_traceidratio
OTEL_TRACES_SAMPLER_ARG=0.1

Every request includes trace context:

traceparent: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
tracestate: shyntr=tenant:acme;flow:authorization

This enables:

End-to-end request tracing across microservices
Performance bottleneck identification
Error correlation across distributed systems
Compliance audit trails

Structured Logging

Production logging uses JSON format for machine parsing:

Example Log Entry
{
  "level": "info",
  "ts": "2024-01-15T10:30:45.123Z",
  "caller": "oauth2/authorize.go:145",
  "msg": "authorization_code_issued",
  "trace_id": "0af7651916cd43dd8448eb211c80319c",
  "span_id": "b7ad6b7169203331",
  "tenant_id": "acme",
  "client_id": "dashboard-app",
  "subject": "user_12345",
  "scopes": ["openid", "profile", "email"],
  "response_type": "code",
  "duration_ms": 45
}

RFC 9457: Problem Details for HTTP APIs

All error responses follow the standard Problem Details format:

Standardized Error Response
{
  "type": "https://docs.shyntr.dev/errors/invalid_grant",
  "title": "Invalid Grant",
  "status": 400,
  "detail": "The refresh token has expired or been revoked.",
  "instance": "/oauth2/token",
  "trace_id": "0af7651916cd43dd8448eb211c80319c"
}

Benefits:

Predictable error structure across all endpoints
Machine-readable error types
Correlation with distributed traces
Secure—no internal details leaked

Security Checklist for Production

Production Deployment Checklist

Before deploying Shyntr to production, ensure:

APP_SECRET is a cryptographically random 32-byte string
COOKIE_SECURE=true is set (requires HTTPS)
SKIP_TLS_VERIFY=false is set (never true in production)
GO_ENV=production for JSON logging
GIN_MODE=release for performance optimization
Database connection uses SSL/TLS
Admin API is not publicly accessible
OpenTelemetry is configured for audit trails
Rate limiting is configured at the network layer

Cryptographic Standards

Algorithm	Usage	Specification
AES-256-GCM	Secret encryption at rest	NIST SP 800-38D
RSA-2048+	JWT signing, SAML signatures	RFC 7518
SHA-256	Token hashing, integrity	FIPS 180-4
ECDSA P-256	Alternative JWT signing	RFC 7518
PBKDF2	Key derivation (if needed)	RFC 2898

Security Standards Compliance​

OpenID Connect Core 1.0​

RP-Initiated Logout​

Advanced Security Features​

RFC 7523: Private Key JWT Authentication​

Replay Protection​

JWT ID (JTI) Tracking​

SAML Message ID Tracking​

Tenant Isolation​

Refresh Token Rotation with Grace Period​

Enterprise Observability​

W3C Trace Context (OpenTelemetry)​

Structured Logging​

RFC 9457: Problem Details for HTTP APIs​

Security Checklist for Production​

Cryptographic Standards​

Next Steps​