Enforce real GCP IAM policies before requests reach emulators — make local environments fail exactly like production.

This is the enforcement proxy component of the Blackwell Local IAM Control Plane. It sits between your application and service emulators (Secret Manager, KMS, etc.), checking permissions before allowing data access.

Unlike mocks (which allow everything) or observers (which record after the fact), this library actively denies unauthorized requests using real IAM policy evaluation.

Pre-flight enforcement catches permission bugs in development and CI, not production.

"A test that cannot fail due to a permission error is a test that has not fully validated the code's production readiness."

Standard GCP emulators give you a false sense of security. Your integration tests pass with flying colors locally, but the moment you deploy to production, you hit PermissionDenied errors because:

• You forgot to grant the service account the right role
• Your conditional policy doesn't match what you thought
• A permission was removed in a recent GCP update

This library solves that:

By enforcing IAM policies before data access, your tests fail during development the exact same way they would fail in production. This means:

• No more "Friday night IAM outages"
• Security reviews happen before merge, not after deploy
• Permission bugs are caught in CI, not in incident postmortems

This is the enforcement proxy that closes the hermetic seal on GCP testing.

┌─────────────────────────────────────────┐
│  Your Application Code                  │
│  (GCP client libraries)                 │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│  DATA PLANE                             │
│  Service Emulator (Secret Manager, KMS) │
│                                         │
│  Uses THIS LIBRARY to:                  │
│  1. Extract principal from request      │
│  2. Check permission                    │
│  3. Deny if unauthorized                │
└────────────────┬────────────────────────┘
                 │
                 │ CheckPermission(principal, resource, permission)
                 ▼
┌─────────────────────────────────────────┐
│  CONTROL PLANE                          │
│  IAM Emulator (Policy Engine)           │
│                                         │
│  - Role bindings                        │
│  - Group memberships                    │
│  - Policy inheritance                   │
└─────────────────────────────────────────┘

This library is used by all Blackwell service emulators to provide consistent IAM enforcement.

Service emulator developers: This library enforces IAM policies in your emulator.

End users: Use the control plane CLI instead — it manages the entire stack for you.

Currently integrated:

• GCP Secret Manager Emulator
• GCP KMS Emulator

Building a new emulator? See the Integration Contract.

go get github.com/blackwell-systems/gcp-emulator-auth

import (
    emulatorauth "github.com/blackwell-systems/gcp-emulator-auth"
)

func main() {
    // Load config from environment
    config := emulatorauth.LoadFromEnv()
    
    if config.Mode.IsEnabled() {
        // Connect to IAM emulator
        iamClient, err := emulatorauth.NewClient(config.Host, config.Mode)
        if err != nil {
            log.Fatal(err)
        }
        defer iamClient.Close()
        
        // Use in handlers...
    }
}

func (s *Server) GetSecret(ctx context.Context, req *pb.GetSecretRequest) (*pb.Secret, error) {
    // Extract principal from incoming request
    principal := emulatorauth.ExtractPrincipalFromContext(ctx)
    
    // Check permission if IAM is enabled
    if s.iamClient != nil {
        allowed, err := s.iamClient.CheckPermission(
            ctx,
            principal,
            req.Name, // resource
            "secretmanager.secrets.get", // permission
        )
        if err != nil {
            return nil, status.Error(codes.Internal, "IAM check failed")
        }
        if !allowed {
            return nil, status.Error(codes.PermissionDenied, "Permission denied")
        }
    }
    
    // Proceed with operation
    return s.storage.GetSecret(req.Name)
}

func (s *Server) handleGetSecret(w http.ResponseWriter, r *http.Request) {
    // Extract principal from HTTP header
    principal := emulatorauth.ExtractPrincipalFromRequest(r)
    
    // Check permission if IAM is enabled
    if s.iamClient != nil {
        allowed, err := s.iamClient.CheckPermission(
            r.Context(),
            principal,
            resourceName,
            "secretmanager.secrets.get",
        )
        if err != nil {
            http.Error(w, "IAM check failed", http.StatusInternalServerError)
            return
        }
        if !allowed {
            http.Error(w, "Permission denied", http.StatusForbidden)
            return
        }
    }
    
    // Proceed with operation
    // ...
}

No IAM checks, all requests allowed (legacy behavior).

# Default - no environment variables needed
./server

IAM checks enabled with fail-open behavior:

• IAM reachable → enforce permissions
• IAM unreachable → allow (fail-open)
• Config errors → deny

IAM_MODE=permissive IAM_EMULATOR_HOST=localhost:8080 ./server

Use for: Development environments where IAM might not always be running.

IAM checks enabled with fail-closed behavior:

• IAM reachable → enforce permissions
• IAM unreachable → deny (fail-closed)
• Config errors → deny

IAM_MODE=strict IAM_EMULATOR_HOST=localhost:8080 ./server

Use for: CI/CD to catch permission issues before production.

Structured logging of authorization decisions for debugging and audit trails.

# Emit traces to file
IAM_TRACE_OUTPUT=./authz-trace.jsonl IAM_MODE=strict ./your-service

# Or to stdout
IAM_TRACE_OUTPUT=stdout IAM_MODE=strict ./your-service

Every CheckPermission call emits:

• authz_check event - permission check outcome (ALLOW/DENY)
• authz_error event - IAM failures (unreachable, timeout, config errors)

Debug Why Access Failed:

# See denied permissions
cat authz-trace.jsonl | jq 'select(.decision.outcome=="DENY")'

Audit What Was Accessed:

# List all resources accessed during test run
cat authz-trace.jsonl | \
  jq -r 'select(.decision.outcome=="ALLOW") | .target.resource' | sort -u

Performance Analysis:

# Check IAM call latency
cat authz-trace.jsonl | jq '.decision.latency_ms' | \
  awk '{sum+=$1; n++} END {print "Avg:", sum/n, "ms"}'

CI/CD Audit Trail:

# Archive traces for compliance
IAM_TRACE_OUTPUT=$CI_ARTIFACTS_DIR/authz-$(date +%Y%m%d).jsonl go test ./...

Events follow schema v1.0 from pkg/trace:

• JSONL format (one event per line)
• Schema-versioned for compatibility
• Includes principal, resource, permission, outcome, timing

See pkg/trace/types.go for complete schema definition.

The package classifies errors into three categories:

IAM evaluated and denied permission. Always deny.

IAM unreachable, timeout, or cancelled:

• Permissive mode: Allow (fail-open)
• Strict mode: Deny (fail-closed)

Invalid resource, bad permission format, internal errors:

• Both modes: Deny (indicates bug/misconfiguration)

Parse auth mode from string (case-insensitive).

Load configuration from environment variables.

Extract principal from gRPC incoming metadata.

Extract principal from HTTP request header.

Add principal to outgoing gRPC metadata.

Check if error is due to connectivity issues.

Check if error indicates configuration problem.

Authorization mode: off, permissive, or strict.

IAM emulator configuration.

IAM emulator client for permission checks.

Maintained by Dayna Blackwell — founder of Blackwell Systems, building reference infrastructure for cloud-native development.

GitHub · LinkedIn · Blog

Blackwell Systems™ and the Blackwell Systems logo are trademarks of Dayna Blackwell. You may use the name "Blackwell Systems" to refer to this project, but you may not use the name or logo in a way that suggests endorsement or official affiliation without prior written permission. See BRAND.md for usage guidelines.

• GCP Emulator Control Plane - CLI tool to run the emulator mesh
• GCP IAM Emulator - The IAM policy engine
• GCP Secret Manager Emulator - Secrets management
• GCP KMS Emulator - Key management and crypto operations

If you're integrating this library into your own emulator or service — I'd love to hear how it's working.

• What service are you building? (custom GCP emulator, internal IAM-aware service, testing framework)
• How smooth was the proxy integration? (wrapped existing gRPC in hours, or hit sharp edges)
• Which features do you rely on? (basic ALLOW/DENY, conditional policies, trace generation, group expansion)
• What's still friction? (principal extraction patterns, error handling, performance overhead)

Open an issue, start a discussion, or reach out directly:

📬 dayna@blackwell-systems.com

This helps shape the roadmap and ensures the library stays aligned with emulator developer needs.

Apache License 2.0 - See LICENSE for details.