`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 = ""
++	ReasonNone                   Reason = ""
--	ReasonUpgradeRequired     Reason = "upgrade_required"
++	ReasonUpgradeRequired        Reason = "upgrade_required"
--	ReasonBillingActionNeeded Reason = "billing_action_needed"
++	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) {
++func New(deps Deps) Loader {
--	if deps.Pool == nil {
++	return Loader{deps: deps}
--		return Decision{}, ErrPoolRequired
++}
++
++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()
++	return set.CanUse(feature), nil
--	if deps.Now != nil {
++}
--		now = deps.Now().UTC()
++
++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 = ReasonEnterpriseContactSales
--		decision.Reason = ReasonNone
  		return decision
  	case billing.PlanTeam:
  		switch state.SubscriptionStatus {
  		case billing.SubscriptionStatusActive,
--			billing.SubscriptionStatusTrialing,
++			billing.SubscriptionStatusTrialing:
--			billing.SubscriptionStatusIncomplete:
  			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{
++				return setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusActive, "active")
--					OrgID:                    orgID,
++			},
--					Plan:                     billing.PlanTeam,
++			want:   true,
--					Status:                   billing.SubscriptionStatusActive,
++			reason: entitlements.ReasonNone,
--					StripeSubscriptionID:     "sub_active",
++		},
--					StripeSubscriptionItemID: "si_active",
++		{
--					CurrentPeriodStart:       now,
++			name: "team trialing allows feature",
--					CurrentPeriodEnd:         now.Add(30 * 24 * time.Hour),
++			mutate: func(ctx context.Context, deps billing.Deps, orgID int64, now time.Time) error {
--					LastWebhookEventID:       "evt_active",
++				return setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusTrialing, "trialing")
--				})
--				return err
  			},
  			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{
++				if err := setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusActive, "grace"); err != nil {
--					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 {
  					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{
++				if err := setSubscription(ctx, deps, orgID, now, billing.PlanTeam, billing.SubscriptionStatusActive, "lapsed"); err != nil {
--					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 {
  					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)