`2c82cd2`

Harden org entitlement decisions

Authored by mfwolffe <wolffemf@dukes.jmu.edu> yesterday

SHA: 2c82cd28286b8ac350cdc90e66541e39dc816ba4
Parents: fd6b7b3
Tree: d9f0787

4 changed files

Status	File	+	-
M	`docs/internal/billing.md`	24	0
M	`docs/internal/permissions.md`	7	0
M	`internal/entitlements/entitlements.go`	164	18
M	`internal/entitlements/entitlements_test.go`	135	31

docs/internal/billing.mdmodified

  store and scan the plan value, but product behavior should ask the
  entitlement package whether a feature key is available.
 +The package entrypoint is `entitlements.ForOrg(ctx, deps, orgID)`,
 +which loads the local `org_billing_states` projection and returns a
 +request-scoped entitlement set. Callers then use `CanUse(feature)` for
 +feature decisions and `Limit(name)` for paid limit metadata. The legacy
 +`CheckOrgFeature` helper is a thin wrapper for handlers that need only
 +one feature. These calls are deterministic and never call Stripe.
++
  Expected feature keys:
  - `org.secret_teams`
  must preserve existing `policy.Maybe404` behavior where existence leaks
  matter.
 +Entitlement outcomes are:
++
 +- Free organizations receive `upgrade_required` for Team features.
 +- Team organizations with `active` or `trialing` subscriptions receive
 +  the feature.
 +- Team organizations in `past_due` remain usable only while their local
 +  grace window has not expired.
 +- Team organizations with incomplete, unpaid, paused, canceled, or
 +  expired-grace billing receive `billing_action_needed`.
 +- Enterprise remains a contact-sales stub and receives
 +  `enterprise_contact_sales` until a later Enterprise sprint defines a
 +  real feature set.
++
 +Handler upgrade helpers map paid-feature denials to HTTP 402 metadata
 +and a billing-settings path, but handlers must still perform normal
 +authorization first and preserve 404 masking for private resources.
++
  ## Downgrade behavior
  Downgrades must preserve customer data. Moving from Team to Free should

docs/internal/permissions.mdmodified

  packaging, and makes downgrades/grace periods possible without
  rewriting role checks.
 +For paid-feature UI, handlers should use the entitlement decision's
 +upgrade metadata instead of inventing per-surface billing state. A
 +missing Team feature maps to HTTP 402 semantics and a billing-settings
 +path after the normal authorization result has already been accepted.
 +Enterprise is not implicitly Team-plus; it is a contact-sales
 +entitlement result until the Enterprise product contract ships.
++
  ## Existence-leak guard
  `policy.Maybe404(decision, repo, actor)` maps a denial to a status

internal/entitlements/entitlements.gomodified

  import (
  	"context"
  	"errors"
 +	"net/http"
 +	"net/url"
  	"time"
  	"github.com/jackc/pgx/v5/pgxpool"
  	FeatureOrgActionsMinutesQuota      Feature = "org.actions_minutes_quota"
+ )
 +type Limit string
++
 +const (
 +	LimitOrgPrivateCollaboration Limit = "org.private_collaboration_limit"
 +	LimitOrgStorageQuota         Limit = "org.storage_quota"
 +	LimitOrgActionsMinutesQuota  Limit = "org.actions_minutes_quota"
 +)
++
  type Reason string
  const (
 -	ReasonNone                Reason = ""
 -	ReasonUpgradeRequired     Reason = "upgrade_required"
 -	ReasonBillingActionNeeded Reason = "billing_action_needed"
 +	ReasonNone                   Reason = ""
 +	ReasonUpgradeRequired        Reason = "upgrade_required"
 +	ReasonBillingActionNeeded    Reason = "billing_action_needed"
 +	ReasonEnterpriseContactSales Reason = "enterprise_contact_sales"
 +	ReasonUnknownFeature         Reason = "unknown_feature"
+ )
  type Deps struct {
  	Reason       Reason
+ }
 +type LimitValue struct {
 +	Name         Limit
 +	Feature      Feature
 +	Allowed      bool
 +	Defined      bool
 +	Unlimited    bool
 +	Value        int64
 +	Unit         string
 +	RequiredPlan billing.Plan
 +	Reason       Reason
 +}
++
 +type UpgradeBanner struct {
 +	Message    string
 +	ActionText string
 +	ActionHref string
 +	StatusCode int
 +}
++
 +type Loader struct {
 +	deps Deps
 +}
++
 +type Set struct {
 +	OrgID int64
 +	State billing.State
 +	now   time.Time
 +}
++
  var (
  	ErrPoolRequired   = errors.New("entitlements: pool is required")
  	ErrOrgIDRequired  = errors.New("entitlements: org id is required")
  	ErrUnknownFeature = errors.New("entitlements: unknown feature")
 +	ErrUnknownLimit   = errors.New("entitlements: unknown limit")
+ )
 -func CheckOrgFeature(ctx context.Context, deps Deps, orgID int64, feature Feature) (Decision, error) {
 -	if deps.Pool == nil {
 -		return Decision{}, ErrPoolRequired
 +func New(deps Deps) Loader {
 +	return Loader{deps: deps}
 +}
++
 +func ForOrg(ctx context.Context, deps Deps, orgID int64) (Set, error) {
 +	return New(deps).ForOrg(ctx, orgID)
 +}
++
 +func (l Loader) ForOrg(ctx context.Context, orgID int64) (Set, error) {
 +	if l.deps.Pool == nil {
 +		return Set{}, ErrPoolRequired
+ 	}
  	if orgID == 0 {
 -		return Decision{}, ErrOrgIDRequired
 +		return Set{}, ErrOrgIDRequired
 +	}
 +	state, err := billing.GetOrgBillingState(ctx, billing.Deps{Pool: l.deps.Pool}, orgID)
 +	if err != nil {
 +		return Set{}, err
 +	}
 +	now := time.Now().UTC()
 +	if l.deps.Now != nil {
 +		now = l.deps.Now().UTC()
+ 	}
 -	if requiredPlanForFeature(feature) == "" {
 +	return Set{OrgID: orgID, State: state, now: now}, nil
 +}
++
 +func CheckOrgFeature(ctx context.Context, deps Deps, orgID int64, feature Feature) (Decision, error) {
 +	if !KnownFeature(feature) {
  		return Decision{}, ErrUnknownFeature
+ 	}
 -	state, err := billing.GetOrgBillingState(ctx, billing.Deps{Pool: deps.Pool}, orgID)
 +	set, err := ForOrg(ctx, deps, orgID)
  	if err != nil {
  		return Decision{}, err
+ 	}
 -	now := time.Now().UTC()
 -	if deps.Now != nil {
 -		now = deps.Now().UTC()
 +	return set.CanUse(feature), nil
 +}
++
 +func (s Set) CanUse(feature Feature) Decision {
 +	return decideFeature(s.now, s.State, feature)
 +}
++
 +func (s Set) Limit(name Limit) (LimitValue, error) {
 +	feature, unit, ok := limitFeature(name)
 +	if !ok {
 +		return LimitValue{
 +			Name:   name,
 +			Reason: ReasonUnknownFeature,
 +		}, ErrUnknownLimit
 +	}
 +	decision := s.CanUse(feature)
 +	value := LimitValue{
 +		Name:         name,
 +		Feature:      feature,
 +		Allowed:      decision.Allowed,
 +		Unit:         unit,
 +		RequiredPlan: decision.RequiredPlan,
 +		Reason:       decision.Reason,
 +	}
 +	if !decision.Allowed {
 +		return value, nil
 +	}
 +	switch name {
 +	case LimitOrgPrivateCollaboration:
 +		value.Defined = true
 +		value.Unlimited = true
 +	case LimitOrgStorageQuota, LimitOrgActionsMinutesQuota:
 +		// SP08 owns usage accounting and concrete quota numbers. Until
 +		// then, expose entitlement state without pretending metering is enforced.
 +		value.Defined = false
 +	}
 +	return value, nil
 +}
++
 +func KnownFeature(feature Feature) bool {
 +	return requiredPlanForFeature(feature) != ""
 +}
++
 +func KnownLimit(name Limit) bool {
 +	_, _, ok := limitFeature(name)
 +	return ok
 +}
++
 +func (d Decision) HTTPStatus() int {
 +	if d.Allowed {
 +		return http.StatusOK
 +	}
 +	return http.StatusPaymentRequired
 +}
++
 +func (d Decision) BillingPath(orgSlug string) string {
 +	return "/organizations/" + url.PathEscape(orgSlug) + "/settings/billing"
 +}
++
 +func (d Decision) UpgradeBanner(label, orgSlug string) UpgradeBanner {
 +	banner := UpgradeBanner{
 +		ActionText: "Manage billing and plans",
 +		ActionHref: d.BillingPath(orgSlug),
 +		StatusCode: d.HTTPStatus(),
 +	}
 +	switch d.Reason {
 +	case ReasonBillingActionNeeded:
 +		banner.Message = label + " are read-only until Team billing is brought back into good standing."
 +	case ReasonEnterpriseContactSales:
 +		banner.Message = label + " require a supported enterprise plan. Contact sales to continue."
 +	default:
 +		banner.Message = label + " require Team billing. Upgrade this organization to continue."
+ 	}
 -	return decideFeature(now, state, feature), nil
 +	return banner
+ }
  func requiredPlanForFeature(feature Feature) billing.Plan {
+ 	}
+ }
 +func limitFeature(name Limit) (Feature, string, bool) {
 +	switch name {
 +	case LimitOrgPrivateCollaboration:
 +		return FeatureOrgPrivateCollaboration, "collaborators", true
 +	case LimitOrgStorageQuota:
 +		return FeatureOrgStorageQuota, "bytes", true
 +	case LimitOrgActionsMinutesQuota:
 +		return FeatureOrgActionsMinutesQuota, "minutes", true
 +	default:
 +		return "", "", false
 +	}
 +}
++
  func decideFeature(now time.Time, state billing.State, feature Feature) Decision {
  	decision := Decision{
  		Feature:      feature,
  		RequiredPlan: requiredPlanForFeature(feature),
  		Reason:       ReasonUpgradeRequired,
+ 	}
 +	if decision.RequiredPlan == "" {
 +		decision.Reason = ReasonUnknownFeature
 +		return decision
 +	}
  	switch state.Plan {
  	case billing.PlanEnterprise:
 -		decision.Allowed = true
 -		decision.Reason = ReasonNone
 +		decision.Reason = ReasonEnterpriseContactSales
  		return decision
  	case billing.PlanTeam:
  		switch state.SubscriptionStatus {
  		case billing.SubscriptionStatusActive,
 -			billing.SubscriptionStatusTrialing,
 -			billing.SubscriptionStatusIncomplete:
 +			billing.SubscriptionStatusTrialing:
  			decision.Allowed = true
  			decision.Reason = ReasonNone
  			return decision
  		case billing.SubscriptionStatusPastDue:
 -			if !state.GraceUntil.Valid || !now.After(state.GraceUntil.Time) {
 +			if state.GraceUntil.Valid && !now.After(state.GraceUntil.Time) {
  				decision.Allowed = true
  				decision.Reason = ReasonNone
  				return decision

internal/entitlements/entitlements_test.gomodified

  import (
  	"context"
 +	"errors"
  	"io"
  	"log/slog"
 +	"net/http"
 +	"strings"
  	"testing"
  	"time"
+ 		{
  			name: "team active allows feature",
  			mutate: func(ctx context.Context, deps billing.Deps, orgID int64, now time.Time) error {
 -				_, err := billing.ApplySubscriptionSnapshot(ctx, deps, billing.SubscriptionSnapshot{
 -					OrgID:                    orgID,
 -					Plan:                     billing.PlanTeam,
 -					Status:                   billing.SubscriptionStatusActive,
 -					StripeSubscriptionID:     "sub_active",
 -					StripeSubscriptionItemID: "si_active",
 -					CurrentPeriodStart:       now,
 -					CurrentPeriodEnd:         now.Add(30 * 24 * time.Hour),
 -					LastWebhookEventID:       "evt_active",
 -				})
 -				return err
 +				return setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusActive, "active")
 +			},
 +			want:   true,
 +			reason: entitlements.ReasonNone,
 +		},
 +		{
 +			name: "team trialing allows feature",
 +			mutate: func(ctx context.Context, deps billing.Deps, orgID int64, now time.Time) error {
 +				return setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusTrialing, "trialing")
  			},
  			want:   true,
  			reason: entitlements.ReasonNone,
  		},
 +		{
 +			name: "team incomplete needs billing action",
 +			mutate: func(ctx context.Context, deps billing.Deps, orgID int64, now time.Time) error {
 +				return setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusIncomplete, "incomplete")
 +			},
 +			want:   false,
 +			reason: entitlements.ReasonBillingActionNeeded,
 +		},
+ 		{
  			name: "team past due within grace still allows feature",
  			mutate: func(ctx context.Context, deps billing.Deps, orgID int64, now time.Time) error {
 -				if _, err := billing.ApplySubscriptionSnapshot(ctx, deps, billing.SubscriptionSnapshot{
 -					OrgID:                    orgID,
 -					Plan:                     billing.PlanTeam,
 -					Status:                   billing.SubscriptionStatusActive,
 -					StripeSubscriptionID:     "sub_grace",
 -					StripeSubscriptionItemID: "si_grace",
 -					CurrentPeriodStart:       now,
 -					CurrentPeriodEnd:         now.Add(30 * 24 * time.Hour),
 -					LastWebhookEventID:       "evt_active",
 -				}); err != nil {
 +				if err := setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusActive, "grace"); err != nil {
  					return err
+ 				}
  				_, err := billing.MarkPastDue(ctx, deps, orgID, now.Add(24*time.Hour), "evt_past_due")
+ 		{
  			name: "team past due after grace needs billing action",
  			mutate: func(ctx context.Context, deps billing.Deps, orgID int64, now time.Time) error {
 -				if _, err := billing.ApplySubscriptionSnapshot(ctx, deps, billing.SubscriptionSnapshot{
 -					OrgID:                    orgID,
 -					Plan:                     billing.PlanTeam,
 -					Status:                   billing.SubscriptionStatusActive,
 -					StripeSubscriptionID:     "sub_lapsed",
 -					StripeSubscriptionItemID: "si_lapsed",
 -					CurrentPeriodStart:       now,
 -					CurrentPeriodEnd:         now.Add(30 * 24 * time.Hour),
 -					LastWebhookEventID:       "evt_active",
 -				}); err != nil {
 +				if err := setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusActive, "lapsed"); err != nil {
  					return err
+ 				}
  				_, err := billing.MarkPastDue(ctx, deps, orgID, now.Add(24*time.Hour), "evt_past_due")
  			want:   false,
  			reason: entitlements.ReasonBillingActionNeeded,
  		},
 +		{
 +			name: "team locked without grace needs billing action",
 +			mutate: func(ctx context.Context, deps billing.Deps, orgID int64, now time.Time) error {
 +				return setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusPastDue, "locked")
 +			},
 +			want:   false,
 +			reason: entitlements.ReasonBillingActionNeeded,
 +		},
 +		{
 +			name: "enterprise stub does not unlock team features",
 +			mutate: func(ctx context.Context, deps billing.Deps, orgID int64, now time.Time) error {
 +				return setSubscription(ctx, deps, orgID, now, billing.PlanEnterprise, billing.SubscriptionStatusActive, "enterprise")
 +			},
 +			want:   false,
 +			reason: entitlements.ReasonEnterpriseContactSales,
 +		},
+ 	}
  	for _, tt := range tests {
+ 	}
+ }
 +func TestForOrgCanUseAndLimit(t *testing.T) {
 +	t.Parallel()
 +	ctx := context.Background()
 +	pool, orgID := setupEntitlementOrg(t)
 +	now := time.Now().UTC().Truncate(time.Second)
 +	if err := setSubscription(ctx, billing.Deps{Pool: pool}, orgID, now, billing.PlanTeam, billing.SubscriptionStatusActive, "limits"); err != nil {
 +		t.Fatalf("set subscription: %v", err)
 +	}
++
 +	set, err := entitlements.ForOrg(ctx, entitlements.Deps{
 +		Pool: pool,
 +		Now:  func() time.Time { return now },
 +	}, orgID)
 +	if err != nil {
 +		t.Fatalf("ForOrg: %v", err)
 +	}
 +	for _, feature := range []entitlements.Feature{
 +		entitlements.FeatureOrgSecretTeams,
 +		entitlements.FeatureOrgAdvancedBranchProtection,
 +		entitlements.FeatureOrgRequiredReviewers,
 +		entitlements.FeatureOrgActionsSecrets,
 +		entitlements.FeatureOrgActionsVariables,
 +		entitlements.FeatureOrgPrivateCollaboration,
 +		entitlements.FeatureOrgStorageQuota,
 +		entitlements.FeatureOrgActionsMinutesQuota,
 +	} {
 +		if decision := set.CanUse(feature); !decision.Allowed {
 +			t.Fatalf("feature %s decision=%+v, want allowed", feature, decision)
 +		}
 +	}
 +	collab, err := set.Limit(entitlements.LimitOrgPrivateCollaboration)
 +	if err != nil {
 +		t.Fatalf("Limit private collaboration: %v", err)
 +	}
 +	if !collab.Allowed || !collab.Defined || !collab.Unlimited || collab.Unit != "collaborators" {
 +		t.Fatalf("private collaboration limit = %+v", collab)
 +	}
 +	storage, err := set.Limit(entitlements.LimitOrgStorageQuota)
 +	if err != nil {
 +		t.Fatalf("Limit storage: %v", err)
 +	}
 +	if !storage.Allowed || storage.Defined || storage.Unit != "bytes" {
 +		t.Fatalf("storage limit = %+v, want allowed but deferred concrete quota", storage)
 +	}
 +}
++
 +func TestUnknownFeatureAndLimit(t *testing.T) {
 +	t.Parallel()
 +	ctx := context.Background()
 +	pool, orgID := setupEntitlementOrg(t)
 +	_, err := entitlements.CheckOrgFeature(ctx, entitlements.Deps{Pool: pool}, orgID, entitlements.Feature("org.mystery"))
 +	if !errors.Is(err, entitlements.ErrUnknownFeature) {
 +		t.Fatalf("CheckOrgFeature unknown err=%v, want ErrUnknownFeature", err)
 +	}
 +	set, err := entitlements.ForOrg(ctx, entitlements.Deps{Pool: pool}, orgID)
 +	if err != nil {
 +		t.Fatalf("ForOrg: %v", err)
 +	}
 +	_, err = set.Limit(entitlements.Limit("org.mystery_limit"))
 +	if !errors.Is(err, entitlements.ErrUnknownLimit) {
 +		t.Fatalf("Limit unknown err=%v, want ErrUnknownLimit", err)
 +	}
 +}
++
 +func TestDecisionUpgradeBanner(t *testing.T) {
 +	t.Parallel()
 +	decision := entitlements.Decision{
 +		Feature:      entitlements.FeatureOrgSecretTeams,
 +		RequiredPlan: billing.PlanTeam,
 +		Reason:       entitlements.ReasonUpgradeRequired,
 +	}
 +	banner := decision.UpgradeBanner("Secret teams", "acme inc")
 +	if banner.StatusCode != http.StatusPaymentRequired {
 +		t.Fatalf("status=%d, want 402", banner.StatusCode)
 +	}
 +	if banner.ActionHref != "/organizations/acme%20inc/settings/billing" {
 +		t.Fatalf("href=%q", banner.ActionHref)
 +	}
 +	if !strings.Contains(banner.Message, "require Team billing") {
 +		t.Fatalf("message=%q", banner.Message)
 +	}
 +}
++
 +func setSubscription(ctx context.Context, deps billing.Deps, orgID int64, now time.Time, plan billing.Plan, status billing.SubscriptionStatus, suffix string) error {
 +	_, err := billing.ApplySubscriptionSnapshot(ctx, deps, billing.SubscriptionSnapshot{
 +		OrgID:                    orgID,
 +		Plan:                     plan,
 +		Status:                   status,
 +		StripeSubscriptionID:     "sub_" + suffix,
 +		StripeSubscriptionItemID: "si_" + suffix,
 +		CurrentPeriodStart:       now,
 +		CurrentPeriodEnd:         now.Add(30 * 24 * time.Hour),
 +		LastWebhookEventID:       "evt_" + suffix,
 +	})
 +	return err
 +}
++
  func setupEntitlementOrg(t *testing.T) (*pgxpool.Pool, int64) {
  	t.Helper()
  	pool := dbtest.NewTestDB(t)