3.5 KiB

Raw Blame History

Clavitor Edition System

This directory implements build-time differentiation between Community (OSS) and Commercial (hosted) editions of Clavitor Vault.

Architecture

edition/
├── edition.go       # Interface definition (build-agnostic)
├── community.go     # Community Edition (default, !commercial build tag)
└── commercial.go    # Commercial Edition (commercial build tag)

Build Instructions

Community Edition (Default)

# Self-hosted, no telemetry, AGPL-compliant
go build -o clavitor ./cmd/clavitor/

Commercial Edition

# Managed by clavitor.ai, telemetry enabled, SCIM/SIEM support
go build -tags commercial -o clavitor ./cmd/clavitor/

Key Differences

Feature	Community	Commercial
Telemetry	Manual opt-in via CLI flags	Enabled by default, centralized
Operator Alerts	Local logs only	POSTs to `/v1/alerts` endpoint
Central Management	None	Multi-POP dashboard at clavitor.ai
SCIM/SIEM	No	Yes
License	AGPL	Commercial license

Usage in Code

Sending Operator Alerts

// Always use edition.Current.AlertOperator() instead of log.Printf
edition.Current.AlertOperator(ctx, "auth_error", "message", map[string]any{
    "key": "value",
})

Community behavior: Logs to stderr with OPERATOR ALERT [type]: message prefix.

Commercial behavior: Logs locally + POSTs JSON to {TelemetryHost}/v1/alerts.

Checking Edition

if edition.Current.Name() == "commercial" {
    // Commercial-only features
}

if edition.Current.IsTelemetryEnabled() {
    // Telemetry is active (commercial always, community if configured)
}

Commercial Configuration

Only valid for commercial builds. Community builds log a warning if called.

edition.SetCommercialConfig(&edition.CommercialConfig{
    TelemetryHost:  "https://hq.clavitor.com",
    TelemetryToken: "bearer-token",
    TelemetryFreq:  300, // 5 minutes
    POPRegion:      "us-east-1",
})

// Start periodic telemetry reporting
ctx := context.Background()
edition.StartTelemetry(ctx)

Environment Variables (Commercial)

Variable	Purpose
`TELEMETRY_HOST`	Base URL for telemetry (e.g., `https://hq.clavitor.com`)
`TELEMETRY_TOKEN`	Bearer token for authentication
`TELEMETRY_FREQ`	Seconds between POSTs (default: 300)
`POP_REGION`	POP identifier for dashboards

Alert Endpoint (Commercial)

Commercial builds POST to:

POST {TelemetryHost}/v1/alerts
Authorization: Bearer {TelemetryToken}
Content-Type: application/json

Payload:

{
  "edition": "commercial",
  "type": "auth_system_error",
  "message": "Agent lookup failed",
  "details": {"error": "..."},
  "hostname": "pop-us-east-1-03",
  "pop_region": "us-east-1",
  "timestamp": "2026-04-02T00:11:45Z"
}

Important Notes for Opus

Never remove the build tags — they're essential for the dual-license model.
Always use edition.Current — don't branch on build tags in application code.
Community is default — if someone builds without tags, they get OSS edition.
Commercial config is optional — commercial builds work without telemetry (just logs).
Telemetry is separate — the old lib/telemetry.go still exists for community opt-in.

Testing

# Test community
go test ./edition/...

# Test commercial
go test -tags commercial ./edition/...

# Build both
go build ./cmd/clavitor/ && go build -tags commercial ./cmd/clavitor/

3.5 KiB Raw Blame History