Phase/9b subscription state entitlements

.claude/agents/mosaic-backend.md

@@ -1,7 +1,7 @@
 ---
 name: mosaic-backend
 description: Owns Mosaic's Go modular-monolith backend, REST APIs, persistence, publishing, telemetry, and workers. Use for any change under apps/api, apps/worker, or migrations.
-model: claude-fable-5
+model: claude-opus-5
 ---
 
 You are the Mosaic backend owner.

.claude/agents/mosaic-dashboard.md

@@ -1,7 +1,7 @@
 ---
 name: mosaic-dashboard
 description: Owns Mosaic Studio and dashboard using TanStack Start, Tailwind CSS, shadcn/ui, and Base UI. Use for any change under apps/dashboard or frontend documentation.
-model: claude-fable-5
+model: claude-opus-5
 ---
 
 You are the Mosaic dashboard owner.

.gitignore

@@ -2,3 +2,7 @@
 .env
 xcuserdata/
 *.xcuserstate
+
+# compiled binaries
+apps/api/worker
+apps/api/api

CHANGELOG.md

@@ -10,6 +10,20 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Added
 
+- **iOS SDK: authoritative customer entitlements** (Authoritative Entitlement
+  Contract v1, draft). `Mosaic.configure` gains an optional
+  `customerTokenProvider`; a new `MosaicCustomer…` surface reports what Mosaic
+  has validated for a Billing Customer, alongside — never replacing — the
+  existing provider-observed entitlement surface, which is unchanged.
+  `checkCustomerEntitlement(_:)`, `customerEntitlementSnapshot()`,
+  `customerEntitlementUpdates()`, `refreshCustomerEntitlements()`,
+  `customerEntitlementDiagnostics()`, `restoreAndSyncCustomerEntitlements()`,
+  and `clearCustomerState()`. Requires an application backend to mint Customer
+  Access Tokens; there is no anonymous mode. Tokens are memory-only, never
+  logged, never parsed. Bounded-grace offline policy with server-issued windows,
+  a per-customer backup-excluded cache, and the normative rule that any
+  rejection yields `unknown` and never `inactive`.
+
 - Protocol schemas are embedded in the API binary (`go:embed`), so a released
   image can no longer be built without them. Filesystem overrides still work for
   operators pinning a schema; a drift test fails the build if an embedded copy
@@ -32,6 +46,25 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   (including the 304 path) and analytics ingestion.
 - `healthcheck` probe binary, so the distroless image can answer container
   healthchecks.
+- iOS: transaction-observation submissions now carry the current Customer Access
+  Token in a `Mosaic-Customer-Token` header when one is held, binding an
+  identified user's purchase to their Billing Customer server-side. The token is
+  read at send time, never persisted with the queue, and never logged; without
+  one a submission still succeeds and anchors anonymously. The 9A observation
+  record is unchanged — this is transport-level only.
+- iOS: `MosaicDiagnosticStage` gains `entitlementTransport`,
+  `entitlementValidation`, `entitlementCache`, `entitlementAuthentication`, and
+  `entitlementRestore`. This is source-breaking for a host that switches
+  exhaustively over the enumeration, which is accepted at `0.1.0-dev`.
+- iOS: the StoreKit adapter now emits transaction observations on the **restore**
+  path from `Transaction.currentEntitlements`, not only on purchase. A
+  fresh-device restore previously submitted nothing, so a restored purchase was
+  never associated with a Billing Customer. Idempotent through the existing
+  acceptance store and submission-identifier de-duplication.
+- iOS: the StoreKit acceptance store and the identity store are now excluded from
+  backup. Restoring either onto a second device corrupted behaviour that is
+  supposed to be per-install: duplicate-delivery suppression and installation
+  identity.
 - Trusted-proxy middleware: `X-Forwarded-For`/`X-Real-IP` are honoured only from
   a peer inside `MOSAIC_TRUSTED_PROXY_CIDRS` (default: none).
 - Baseline rate limits for authenticated dashboard APIs and for Placement and

apps/api/cmd/api/main.go

@@ -16,6 +16,14 @@ import (
 
 	"github.com/Mujhtech/mosaic/apps/api/internal/analytics"
 	"github.com/Mujhtech/mosaic/apps/api/internal/billing"
+	"github.com/Mujhtech/mosaic/apps/api/internal/billingaccess"
+	"github.com/Mujhtech/mosaic/apps/api/internal/billingcustomer"
+	"github.com/Mujhtech/mosaic/apps/api/internal/billingdiagnostics"
+	"github.com/Mujhtech/mosaic/apps/api/internal/billinggrant"
+	"github.com/Mujhtech/mosaic/apps/api/internal/billingoperator"
+	"github.com/Mujhtech/mosaic/apps/api/internal/billingprojection"
+	"github.com/Mujhtech/mosaic/apps/api/internal/billingrestore"
+	"github.com/Mujhtech/mosaic/apps/api/internal/billingwebhook"
 	"github.com/Mujhtech/mosaic/apps/api/internal/browserauth"
 	"github.com/Mujhtech/mosaic/apps/api/internal/cloudworkspace"
 	"github.com/Mujhtech/mosaic/apps/api/internal/experiment"
@@ -25,7 +33,17 @@ import (
 	"github.com/Mujhtech/mosaic/apps/api/internal/platform/appstorejws"
 	"github.com/Mujhtech/mosaic/apps/api/internal/platform/appstoreserver"
 	"github.com/Mujhtech/mosaic/apps/api/internal/platform/authn"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingaccesspostgres"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingcustomerpostgres"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingdiagnosticspostgres"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billinggrantpostgres"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingkeys"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingoperatorpostgres"
 	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingpostgres"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingprojectionpostgres"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingrestorepostgres"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingseam"
+	"github.com/Mujhtech/mosaic/apps/api/internal/platform/billingwebhookpostgres"
 	"github.com/Mujhtech/mosaic/apps/api/internal/platform/browserauthpostgres"
 	"github.com/Mujhtech/mosaic/apps/api/internal/platform/buildinfo"
 	"github.com/Mujhtech/mosaic/apps/api/internal/platform/cloudworkspacepostgres"
@@ -255,7 +273,15 @@ func run() (runErr error) {
 	analyticsEventLimiter := ratelimit.New(cfg.Analytics.KeyEventsPerMinute, cfg.Analytics.KeyEventBurst, cfg.Analytics.LimiterEntries)
 
 	var billingService *billing.Service
-	var billingIPLimiter, billingKeyLimiter *ratelimit.Limiter
+	var billingAccessService *billingaccess.Service
+	var billingDiagnosticsService *billingdiagnostics.Service
+	var billingGrantService *billinggrant.Service
+	var billingRestoreService *billingrestore.Service
+	var billingCustomerService *billingcustomer.Service
+	var billingOperatorService *billingoperator.Service
+	var billingProjectionService *billingprojection.Service
+	var billingWebhookService *billingwebhook.Service
+	var billingIPLimiter, billingKeyLimiter, entitlementSyncLimiter *ratelimit.Limiter
 	if cfg.Billing.Enabled {
 		billingCipher, err := providercredential.NewAESGCMCipher(cfg.Providers.CredentialKeyring, rand.Reader)
 		if err != nil {
@@ -287,12 +313,58 @@ func run() (runErr error) {
 		if err != nil {
 			return fmt.Errorf("configure Google Play client: %w", err)
 		}
+		billingIPLimiter = ratelimit.New(cfg.Billing.ObservationsPerMinute, cfg.Billing.ObservationBurst, cfg.Billing.LimiterEntries)
+		billingKeyLimiter = ratelimit.New(cfg.Billing.ObservationsPerMinute, cfg.Billing.ObservationBurst, cfg.Billing.LimiterEntries)
+		billingAccessService = billingaccess.NewService(
+			billingaccesspostgres.New(databasePool),
+			billingaccesspostgres.NewKeyAuthenticator(billingpostgres.New(databasePool)),
+			billingaccess.WithIssuer(cfg.Telemetry.ServiceName),
+			billingaccess.WithFreshness(billingaccess.Freshness{
+				RefreshAfter: cfg.Billing.EntitlementRefreshAfter,
+				ValidFor:     cfg.Billing.EntitlementValidFor,
+				StaleGrace:   cfg.Billing.EntitlementStaleGrace(),
+			}))
+		entitlementSyncLimiter = ratelimit.New(cfg.Billing.EntitlementSyncPerMinute,
+			cfg.Billing.EntitlementSyncBurst, cfg.Billing.LimiterEntries)
+		// The API process runs no projection jobs; it constructs the projection
+		// service only to enqueue triggers (identity movements) and to run
+		// bounded operator replays. Both go through the same command the worker
+		// runs, so there is no second write path.
+		projectionRepository := billingprojectionpostgres.New(databasePool)
+		billingProjectionService = billingprojection.NewService(projectionRepository)
+		billingDiagnosticsService = billingdiagnostics.NewService(
+			billingdiagnosticspostgres.New(databasePool),
+			billingdiagnostics.WithReplay(billingProjectionService, projectionRepository))
+		billingKeys := billingkeys.New(billingpostgres.New(databasePool))
+		billingRestoreService = billingrestore.NewService(
+			billingrestorepostgres.New(databasePool), billingKeys.Restore())
+		billingCustomerService = billingcustomer.NewService(
+			billingcustomerpostgres.New(databasePool), billingKeys.Identity(), billingProjectionService)
+		// The Phase 9A→9B seam. The ingestion service is constructed last
+		// because it depends on it: an observation submitted with a Customer
+		// Access Token records the association that lets a first purchase reach
+		// an identified customer, and a committed fact hands its lineage to the
+		// identity service. Without this the 9B read model is unreachable from a
+		// purchase, which was defect D-1.
 		billingService = billing.NewService(billingpostgres.New(databasePool), billingCipher, verifier,
 			billing.WithProviders(appleClient, googleClient),
 			billing.WithRetention(cfg.Billing.RawRetention()),
-			billing.WithNotificationBaseURL(cfg.Billing.NotificationBaseURL))
-		billingIPLimiter = ratelimit.New(cfg.Billing.ObservationsPerMinute, cfg.Billing.ObservationBurst, cfg.Billing.LimiterEntries)
-		billingKeyLimiter = ratelimit.New(cfg.Billing.ObservationsPerMinute, cfg.Billing.ObservationBurst, cfg.Billing.LimiterEntries)
+			billing.WithNotificationBaseURL(cfg.Billing.NotificationBaseURL),
+			billing.WithSeam(billingseam.New(billingCustomerService, billingAccessService),
+				billingseam.New(billingCustomerService, billingAccessService)))
+		billingGrantService = billinggrant.NewService(billinggrantpostgres.New(databasePool))
+		// The operator surface reads through the same repositories the trusted
+		// APIs read through, so the dashboard and an application backend see one
+		// answer derived once. Its own repository holds only the read model the
+		// dashboard needs and no writer at all.
+		billingOperatorService = billingoperator.NewService(
+			billingoperatorpostgres.New(databasePool),
+			billingaccesspostgres.New(databasePool),
+			billingCustomerService)
+		billingWebhookService = billingwebhook.NewService(
+			billingwebhookpostgres.New(databasePool), billingCipher,
+			billingwebhook.NewPolicy(billingwebhook.WithSelfHostedAllowlist(
+				cfg.Billing.WebhookAllowPrivateDestinations)))
 	}
 
 	readiness := health.NewReadiness(
@@ -320,27 +392,35 @@ func run() (runErr error) {
 		TrustedProxyCIDRs: cfg.HTTP.TrustedProxyCIDRs,
 		EnableHSTS:        cfg.ProductionLike(),
 	}, logger, httpserver.Dependencies{
-		BrowserAuth:           browserAuthService,
-		BrowserAuthConfig:     browserauthhttp.Config{CookieSecure: cfg.BrowserAuth.CookieSecure, CookieDomain: cfg.BrowserAuth.CookieDomain, AllowedOrigins: cfg.HTTP.CORSAllowedOrigins, RateLimiter: authenticationLimiter},
-		CloudWorkspace:        workspaceService,
-		HostedPublishing:      publishingService,
-		PlacementDecision:     placementDecisionService,
-		PrincipalResolver:     authn.NewBrowserSessionResolver(browserAuthService),
-		DeliveryLimiter:       deliveryLimiter,
-		Analytics:             analyticsService,
-		AnalyticsIPLimiter:    analyticsIPLimiter,
-		AnalyticsKeyLimiter:   analyticsKeyLimiter,
-		AnalyticsEventLimiter: analyticsEventLimiter,
-		Experiment:            experimentService,
-		Billing:               billingService,
-		BillingIPLimiter:      billingIPLimiter,
-		BillingKeyLimiter:     billingKeyLimiter,
-		APILimiter:            apiLimiter,
-		DecisionLimiter:       decisionLimiter,
-		UploadLimiter:         uploadLimiter,
-		ExportLimiter:         exportLimiter,
-		Readiness:             readiness,
-		ReadinessChecker:      database.HealthChecker{Pinger: databasePool},
+		BrowserAuth:            browserAuthService,
+		BrowserAuthConfig:      browserauthhttp.Config{CookieSecure: cfg.BrowserAuth.CookieSecure, CookieDomain: cfg.BrowserAuth.CookieDomain, AllowedOrigins: cfg.HTTP.CORSAllowedOrigins, RateLimiter: authenticationLimiter},
+		CloudWorkspace:         workspaceService,
+		HostedPublishing:       publishingService,
+		PlacementDecision:      placementDecisionService,
+		PrincipalResolver:      authn.NewBrowserSessionResolver(browserAuthService),
+		DeliveryLimiter:        deliveryLimiter,
+		Analytics:              analyticsService,
+		AnalyticsIPLimiter:     analyticsIPLimiter,
+		AnalyticsKeyLimiter:    analyticsKeyLimiter,
+		AnalyticsEventLimiter:  analyticsEventLimiter,
+		Experiment:             experimentService,
+		Billing:                billingService,
+		BillingAccess:          billingAccessService,
+		BillingDiagnostics:     billingDiagnosticsService,
+		BillingGrant:           billingGrantService,
+		BillingRestore:         billingRestoreService,
+		BillingCustomer:        billingCustomerService,
+		BillingOperator:        billingOperatorService,
+		BillingWebhook:         billingWebhookService,
+		BillingIPLimiter:       billingIPLimiter,
+		BillingKeyLimiter:      billingKeyLimiter,
+		EntitlementSyncLimiter: entitlementSyncLimiter,
+		APILimiter:             apiLimiter,
+		DecisionLimiter:        decisionLimiter,
+		UploadLimiter:          uploadLimiter,
+		ExportLimiter:          exportLimiter,
+		Readiness:              readiness,
+		ReadinessChecker:       database.HealthChecker{Pinger: databasePool},
 	})
 
 	server := &http.Server{