feat(billing): implement tenant subscription entitlements system (milestones 0-6)

scripts/billing/README_ROLLBACK.md

@@ -0,0 +1,42 @@
+# Rollback Plan: Billing Enforced Gating
+
+This document outlines the emergency procedure for disabling subscription-based entitlement gating in the Cloudlysis Control Plane.
+
+## Symptoms
+- Tenants receiving `402 Payment Required` errors even with valid active subscriptions.
+- `JobEngine` refusing valid configuration updates due to incorrect resource limit enforcement.
+- S3 Document Storage being inaccessible for authorized Pro/Enterprise tenants.
+
+## Emergency Rollback Steps
+
+### 1. Disable Global Enforcement
+The quickest way to restore service is to disable enforcement via the environment variable toggle. This preserves all billing data and synchronization logic but bypasses the "Payment Required" blocks.
+
+```bash
+# In your Swarm stack file (e.g. control-plane.yml):
+services:
+  control-api:
+    environment:
+      - CONTROL_BILLING_ENFORCEMENT_ENABLED=false
+```
+
+### 2. Deploy the Update
+Deploy the stack to apply the change:
+```bash
+docker stack deploy -c control-plane.yml control
+```
+
+### 3. Verify System State
+Confirm that tenants can now perform previously blocked operations (e.g., uploading documents or updating deployment configurations).
+
+## Forensic Analysis
+Once the system is stable, perform the following:
+1.  **Check Reconciliation Logs**: Look for `failed to fetch subscription` or `failed to apply reconciled billing event`.
+2.  **Verify Metrics**: Check `billing_webhook_requests_total{status="error"}` in Prometheus.
+3.  **Audit Drift**: Compare the `CONTROL_BILLING_STATE_PATH` file content against the Stripe Dashboard for the affected `tenant_id`.
+
+## Recovery
+To re-enable gating (after the root cause is resolved):
+1.  Set `CONTROL_BILLING_ENFORCEMENT_ENABLED=true`.
+2.  Redeploy the stack.
+3.  Monitor logs and metrics for 30 minutes.

scripts/billing/swarm-secrets-sample.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+set -e
+
+# sample-secrets.sh
+# This script demonstrates how to provision the necessary Swarm secrets 
+# for the billing system.
+
+# 1. Stripe Secret Key (from Stripe Dashboard -> Developers -> API keys)
+# Usage: echo "sk_test_..." | ./sample-secrets.sh
+if [ -t 0 ]; then
+  echo "Error: Please pipe the Stripe Secret Key into this script."
+  echo "Example: echo \"sk_test_...\" | $0"
+  exit 1
+fi
+
+STRIPE_SK=$(cat -)
+
+echo "Creating 'control_stripe_secret_key' secret..."
+echo "$STRIPE_SK" | docker secret create control_stripe_secret_key -
+
+# 2. Stripe Webhook Secret (from Stripe Dashboard -> Developers -> Webhooks -> [Endpoint])
+# Note: You get this after configuring the endpoint in the dashboard.
+echo "NOTE: Remember to also create 'control_stripe_webhook_secret' once you have it."
+# echo "whsec_..." | docker secret create control_stripe_webhook_secret -
+
+echo "Done. Update your stack file to reference these secrets:"
+echo "
+services:
+  control-api:
+    secrets:
+      - control_stripe_secret_key
+      - control_stripe_webhook_secret
+    environment:
+      - CONTROL_STRIPE_SECRET_KEY_FILE=/run/secrets/control_stripe_secret_key
+      - CONTROL_STRIPE_WEBHOOK_SECRET_FILE=/run/secrets/control_stripe_webhook_secret
+"