Add Stripe billing configuration

Status	File	+	-
M	`.env.example`	16	0
M	`docs/internal/billing.md`	13	0
M	`docs/internal/config.md`	15	0
M	`go.mod`	1	0
M	`go.sum`	2	0
M	`internal/infra/config/config.go`	74	0
M	`internal/infra/config/config_test.go`	70	1

.env.examplemodified

  # anon keyed by remote IP. Zero falls back to the default.
  SHITHUB_RATELIMIT__API__AUTHED_PER_HOUR=5000
  SHITHUB_RATELIMIT__API__ANON_PER_HOUR=60
++
++# ----- billing (SP03) -----
++# Stripe Billing is disabled by default. Use Stripe test-mode keys for local
++# drills and keep live keys in the production EnvironmentFile only.
++SHITHUB_BILLING__ENABLED=false
++SHITHUB_BILLING__GRACE_PERIOD=336h
++# Required when billing is enabled:
++# SHITHUB_BILLING__STRIPE__SECRET_KEY=sk_test_...
++# SHITHUB_BILLING__STRIPE__WEBHOOK_SECRET=whsec_...
++# SHITHUB_BILLING__STRIPE__TEAM_PRICE_ID=price_...
++# Optional absolute override URLs; omitted values are derived from
++# SHITHUB_AUTH__BASE_URL.
++# SHITHUB_BILLING__STRIPE__SUCCESS_URL=https://shithub.example/organizations/{org}/billing/success
++# SHITHUB_BILLING__STRIPE__CANCEL_URL=https://shithub.example/organizations/{org}/billing/cancel
++# SHITHUB_BILLING__STRIPE__PORTAL_RETURN_URL=https://shithub.example/organizations/{org}/settings/billing
++SHITHUB_BILLING__STRIPE__AUTOMATIC_TAX=false

docs/internal/billing.mdmodified

  snapshot writes also keep `orgs.plan` synchronized as the
  human-facing summary.
++PAYMENTS SP03 adds the first Stripe operator contract:
++
++- `billing.enabled=false` keeps paid-org flows disabled while retaining
++  the local billing tables.
++- `billing.stripe.secret_key`, `billing.stripe.webhook_secret`, and
++  `billing.stripe.team_price_id` are required before Stripe routes are
++  mounted.
++- Checkout success, Checkout cancel, and Billing Portal return URLs may
++  be overridden explicitly; otherwise the web layer derives absolute
++  organization URLs from `auth.base_url`.
++- `billing.grace_period` controls how long failed-payment states may
++  remain unlocked before paid entitlements are cut off.
++
  ## Entitlement architecture
  Paid feature checks must live behind a central entitlement package, not

docs/internal/config.mdmodified

  | `auth.argon2.time` | uint32 | `3` | argon2id iterations. |
  | `auth.argon2.threads` | uint8 | `2` | argon2id parallelism. |
  | `auth.totp_key_b64` | string | `""` | Base64 32-byte AEAD key for at-rest TOTP secrets. Aliased by `SHITHUB_TOTP_KEY`. Empty disables 2FA enrollment routes. |
++| `billing.enabled` | bool | `false` | Enables paid-organization Stripe Billing flows. When false, org plan state is local-only. |
++| `billing.grace_period` | duration | `336h` | Lock grace window applied after failed subscription payments. |
++| `billing.stripe.secret_key` | string | `""` | Stripe secret API key. Required when `billing.enabled=true`. Redacted. |
++| `billing.stripe.webhook_secret` | string | `""` | Stripe webhook signing secret. Required when `billing.enabled=true`. Redacted. |
++| `billing.stripe.team_price_id` | string | `""` | Stripe recurring Price ID for the Team plan seat. Required when `billing.enabled=true`. |
++| `billing.stripe.success_url` | string | `""` | Optional absolute Checkout success URL override. Empty derives from `auth.base_url`. Redacted by `config print`. |
++| `billing.stripe.cancel_url` | string | `""` | Optional absolute Checkout cancel URL override. Empty derives from `auth.base_url`. Redacted by `config print`. |
++| `billing.stripe.portal_return_url` | string | `""` | Optional absolute Billing Portal return URL override. Empty derives from `auth.base_url`. Redacted by `config print`. |
++| `billing.stripe.automatic_tax` | bool | `false` | Enables Stripe Checkout automatic tax collection when the Stripe account is configured for it. |
  ## Env-var examples
  # Gate /metrics behind Basic auth
  export SHITHUB_METRICS__BASIC_AUTH_USER=prom
  export SHITHUB_METRICS__BASIC_AUTH_PASS=<long-random>
++
++# Enable Stripe Billing in test mode
++export SHITHUB_BILLING__ENABLED=true
++export SHITHUB_BILLING__STRIPE__SECRET_KEY=sk_test_...
++export SHITHUB_BILLING__STRIPE__WEBHOOK_SECRET=whsec_...
++export SHITHUB_BILLING__STRIPE__TEAM_PRICE_ID=price_...
  ```
  ## Secrets

go.modmodified


 	github.com/rs/xid v1.6.0 // indirect
 	github.com/sethvargo/go-retry v0.3.0 // indirect
 	github.com/spf13/pflag v1.0.9 // indirect
+	github.com/stripe/stripe-go/v85 v85.1.0 // indirect
 	github.com/tinylib/msgp v1.6.1 // indirect
 	github.com/zeebo/xxh3 v1.1.0 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect

go.summodified

  github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
  github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
  github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
++github.com/stripe/stripe-go/v85 v85.1.0 h1:MywWUmgw9M7cnwFFch9cyLmRZuAiYM5cZ27JxH3a5/s=
++github.com/stripe/stripe-go/v85 v85.1.0/go.mod h1:5P+HGFenpWgak27T5Is6JMsmDfUC1yJnjhhmquz7kXw=
  github.com/tinylib/msgp v1.6.1 h1:ESRv8eL3u+DNHUoSAAQRE50Hm162zqAnBoGv9PzScPY=
  github.com/tinylib/msgp v1.6.1/go.mod h1:RSp0LW9oSxFut3KzESt5Voq4GVWyS+PSulT77roAqEA=
  github.com/yuin/goldmark v1.8.2 h1:kEGpgqJXdgbkhcOgBxkC0X0PmoPG1ZyoZ117rDVp4zE=

internal/infra/config/config.gomodified

  import (
  	"errors"
  	"fmt"
++	"net/url"
  	"os"
  	"reflect"
  	"strconv"
  	Auth           AuthConfig           `toml:"auth"`
  	Notif          NotifConfig          `toml:"notif"`
  	RateLimit      RateLimitConfig      `toml:"ratelimit"`
++	Billing        BillingConfig        `toml:"billing"`
+ }
  // RateLimitConfig configures runtime rate-limit budgets for surfaces that
  	UnsubscribeKeyB64 string `toml:"unsubscribe_key_b64"`
+ }
++// BillingConfig controls paid-organization enforcement and the payment
++// processor integration. Stripe is the first supported processor and remains
++// optional until operators provide live or test-mode credentials.
++type BillingConfig struct {
++	Enabled     bool                `toml:"enabled"`
++	GracePeriod time.Duration       `toml:"grace_period"`
++	Stripe      StripeBillingConfig `toml:"stripe"`
++}
++
++// StripeBillingConfig holds Stripe Billing API settings. Checkout and portal
++// URLs are optional; when omitted the web layer derives them from auth.base_url.
++type StripeBillingConfig struct {
++	SecretKey       string `toml:"secret_key"`
++	WebhookSecret   string `toml:"webhook_secret"`
++	TeamPriceID     string `toml:"team_price_id"`
++	SuccessURL      string `toml:"success_url"`
++	CancelURL       string `toml:"cancel_url"`
++	PortalReturnURL string `toml:"portal_return_url"`
++	AutomaticTax    bool   `toml:"automatic_tax"`
++}
++
  // WebConfig holds HTTP server settings.
  type WebConfig struct {
  	Addr            string        `toml:"addr"`
  			SampleRate:  0.05,
  			ServiceName: "shithubd",
  		},
++		Billing: BillingConfig{
++			GracePeriod: 14 * 24 * time.Hour,
++		},
  		Session: SessionConfig{
  			MaxAge: 30 * 24 * time.Hour,
  			Secure: false,
  	if c.RateLimit.API.AnonPerHour == 0 {
  		c.RateLimit.API.AnonPerHour = 60
+ 	}
++	if err := validateBilling(c); err != nil {
++		return err
++	}
++	return nil
++}
++
++func validateBilling(c *Config) error {
++	if c.Billing.GracePeriod < 0 {
++		return fmt.Errorf("config: billing.grace_period: must be >= 0, got %v", c.Billing.GracePeriod)
++	}
++	for key, raw := range map[string]string{
++		"billing.stripe.success_url":       c.Billing.Stripe.SuccessURL,
++		"billing.stripe.cancel_url":        c.Billing.Stripe.CancelURL,
++		"billing.stripe.portal_return_url": c.Billing.Stripe.PortalReturnURL,
++	} {
++		if err := validateOptionalHTTPURL(key, raw); err != nil {
++			return err
++		}
++	}
++	if !c.Billing.Enabled {
++		return nil
++	}
++	if c.Billing.Stripe.SecretKey == "" {
++		return errors.New("config: billing.stripe.secret_key is required when billing.enabled=true")
++	}
++	if c.Billing.Stripe.WebhookSecret == "" {
++		return errors.New("config: billing.stripe.webhook_secret is required when billing.enabled=true")
++	}
++	if c.Billing.Stripe.TeamPriceID == "" {
++		return errors.New("config: billing.stripe.team_price_id is required when billing.enabled=true")
++	}
++	if err := validateOptionalHTTPURL("auth.base_url", c.Auth.BaseURL); err != nil {
++		return err
++	}
++	return nil
++}
++
++func validateOptionalHTTPURL(key, raw string) error {
++	if raw == "" {
++		return nil
++	}
++	u, err := url.Parse(raw)
++	if err != nil {
++		return fmt.Errorf("config: %s: parse: %w", key, err)
++	}
++	if (u.Scheme != "http" && u.Scheme != "https") || u.Host == "" {
++		return fmt.Errorf("config: %s: must be an absolute http(s) URL", key)
++	}
  	return nil
+ }

internal/infra/config/config_test.gomodified

+ 	}
+ }
++func TestValidate_BillingRequiresStripeSettings(t *testing.T) {
++	t.Parallel()
++	cfg := Defaults()
++	cfg.Billing.Enabled = true
++	if err := Validate(&cfg); err == nil || !strings.Contains(err.Error(), "billing.stripe.secret_key") {
++		t.Fatalf("Validate missing secret key: got %v", err)
++	}
++
++	cfg.Billing.Stripe.SecretKey = "sk_test_123"
++	if err := Validate(&cfg); err == nil || !strings.Contains(err.Error(), "billing.stripe.webhook_secret") {
++		t.Fatalf("Validate missing webhook secret: got %v", err)
++	}
++
++	cfg.Billing.Stripe.WebhookSecret = "whsec_123"
++	if err := Validate(&cfg); err == nil || !strings.Contains(err.Error(), "billing.stripe.team_price_id") {
++		t.Fatalf("Validate missing team price: got %v", err)
++	}
++
++	cfg.Billing.Stripe.TeamPriceID = "price_123"
++	if err := Validate(&cfg); err != nil {
++		t.Fatalf("Validate complete billing config: %v", err)
++	}
++}
++
++func TestValidate_BillingRejectsBadURLs(t *testing.T) {
++	t.Parallel()
++	cfg := Defaults()
++	cfg.Billing.Stripe.SuccessURL = "/relative"
++	if err := Validate(&cfg); err == nil || !strings.Contains(err.Error(), "billing.stripe.success_url") {
++		t.Fatalf("Validate bad success URL: got %v", err)
++	}
++
++	cfg = Defaults()
++	cfg.Billing.Enabled = true
++	cfg.Billing.Stripe.SecretKey = "sk_test_123"
++	cfg.Billing.Stripe.WebhookSecret = "whsec_123"
++	cfg.Billing.Stripe.TeamPriceID = "price_123"
++	cfg.Auth.BaseURL = "shithub.local"
++	if err := Validate(&cfg); err == nil || !strings.Contains(err.Error(), "auth.base_url") {
++		t.Fatalf("Validate bad auth base URL with billing enabled: got %v", err)
++	}
++}
++
  func TestMergeEnv_AppliesNestedKeys(t *testing.T) {
  	t.Parallel()
  	cfg := Defaults()
  		"SHITHUB_TRACING__ENABLED=true",
  		"SHITHUB_TRACING__ENDPOINT=http://otel:4318",
  		"SHITHUB_DB__CONNECT_TIMEOUT=8s",
++		"SHITHUB_BILLING__ENABLED=true",
++		"SHITHUB_BILLING__GRACE_PERIOD=240h",
++		"SHITHUB_BILLING__STRIPE__SECRET_KEY=sk_test_123",
++		"SHITHUB_BILLING__STRIPE__WEBHOOK_SECRET=whsec_123",
++		"SHITHUB_BILLING__STRIPE__TEAM_PRICE_ID=price_123",
++		"SHITHUB_BILLING__STRIPE__AUTOMATIC_TAX=true",
+ 	}
  	if err := mergeEnv(&cfg, env); err != nil {
  		t.Fatalf("mergeEnv: %v", err)
  	if cfg.DB.ConnectTimeout != 8*time.Second {
  		t.Errorf("DB.ConnectTimeout: got %v", cfg.DB.ConnectTimeout)
+ 	}
++	if !cfg.Billing.Enabled {
++		t.Errorf("Billing.Enabled: not set")
++	}
++	if cfg.Billing.GracePeriod != 240*time.Hour {
++		t.Errorf("Billing.GracePeriod: got %v", cfg.Billing.GracePeriod)
++	}
++	if cfg.Billing.Stripe.SecretKey != "sk_test_123" {
++		t.Errorf("Billing.Stripe.SecretKey: got %q", cfg.Billing.Stripe.SecretKey)
++	}
++	if cfg.Billing.Stripe.WebhookSecret != "whsec_123" {
++		t.Errorf("Billing.Stripe.WebhookSecret: got %q", cfg.Billing.Stripe.WebhookSecret)
++	}
++	if cfg.Billing.Stripe.TeamPriceID != "price_123" {
++		t.Errorf("Billing.Stripe.TeamPriceID: got %q", cfg.Billing.Stripe.TeamPriceID)
++	}
++	if !cfg.Billing.Stripe.AutomaticTax {
++		t.Errorf("Billing.Stripe.AutomaticTax: not set")
++	}
+ }
  func TestPrintRedacted_HidesSecrets(t *testing.T) {
  	cfg.Session.KeyB64 = "supersecretkey"
  	cfg.Metrics.BasicAuthPass = "metrics-pass"
  	cfg.ErrorReporting.DSN = "https://abc@sentry.example/1"
++	cfg.Billing.Stripe.SecretKey = "sk_live_secret"
++	cfg.Billing.Stripe.WebhookSecret = "whsec_secret"
  	out, err := PrintRedacted(cfg)
  	if err != nil {
  		t.Fatalf("PrintRedacted: %v", err)
+ 	}
--	for _, leak := range []string{"hunter2", "supersecretkey", "metrics-pass", "https://abc@sentry"} {
++	for _, leak := range []string{"hunter2", "supersecretkey", "metrics-pass", "https://abc@sentry", "sk_live_secret", "whsec_secret"} {
  		if strings.Contains(out, leak) {
  			t.Errorf("PrintRedacted leaked %q\noutput: %s", leak, out)
+ 		}

tenseleyflow/shithub / `8f753ab`

7 changed files

`@@ -61,6 +61,7 @@` require (
61	github.com/rs/xid v1.6.0 // indirect	61	github.com/rs/xid v1.6.0 // indirect
62	github.com/sethvargo/go-retry v0.3.0 // indirect	62	github.com/sethvargo/go-retry v0.3.0 // indirect
63	github.com/spf13/pflag v1.0.9 // indirect	63	github.com/spf13/pflag v1.0.9 // indirect
		64	+ github.com/stripe/stripe-go/v85 v85.1.0 // indirect
64	github.com/tinylib/msgp v1.6.1 // indirect	65	github.com/tinylib/msgp v1.6.1 // indirect
65	github.com/zeebo/xxh3 v1.1.0 // indirect	66	github.com/zeebo/xxh3 v1.1.0 // indirect
66	go.opentelemetry.io/auto/sdk v1.2.1 // indirect	67	go.opentelemetry.io/auto/sdk v1.2.1 // indirect