feat(billing-docker): affiliates connect their own payouts; fix argv leak; role labels in public docs

ncimino · ncimino · commit 5b25aed314bf · 2026-08-04T16:52:51.000-06:00
Payout dead-end (found in the rehearsal): after signing, an affiliate was told 'WeOwn will send your onboarding link' and nothing happened — the link had to be minted by an operator. Onboarding links are single-use and expire in minutes, so emailing them ahead of time cannot work either. The affiliate page now shows a real button that creates their Express account on demand and drops them into Stripe's hosted onboarding, plus accurate state (connected / unfinished / not started) read from Stripe, and a 'Manage payout account' link into the Express dashboard once complete. Review fixes from PR #158: the minted OpenRouter key was passed as a command line argument — visible in ps/proc for the life of the call, contradicting the script's own 'never on argv' header. Now uses the repo's established NAME=@file pattern (umask 077 temp file, shredded by the EXIT trap). Public handoff docs now use role labels instead of naming individuals.
diff --git a/billing-docker/sites/billing/app/billing/urls.py b/billing-docker/sites/billing/app/billing/urls.py
@@ -16,6 +16,7 @@
     path("suspended/", views.suspended, name="suspended"),
     path("affiliate/", views.affiliate_home, name="affiliate_home"),
     path("affiliate/join/", views.affiliate_join, name="affiliate_join"),
+    path("affiliate/payouts/", views.connect_payouts, name="connect_payouts"),
     path("affiliate/check/", views.check_affiliate_code, name="check_affiliate_code"),
     path("affiliate/contract/", views.affiliate_contract, name="affiliate_contract"),
     path("webhooks/stripe/", views.stripe_webhook, name="stripe_webhook"),
diff --git a/billing-docker/sites/billing/app/core/stripe_svc.py b/billing-docker/sites/billing/app/core/stripe_svc.py
@@ -123,3 +123,42 @@ def pay_affiliate_splits(invoice: dict, subscription) -> None:
             log.info("Split paid: %s T%s -> %s (%s%% of profit %sc = %sc)",
                      invoice["id"], tier, leg_aff.code, pct, profit, cut)
         row.save()
+
+
+def connect_account_status(affiliate) -> dict:
+    """What Stripe thinks of this affiliate's payout account. Cheap enough to
+    call on the affiliate page; degrades to 'unknown' rather than erroring."""
+    if not affiliate.stripe_connect_account_id:
+        return {"exists": False, "payouts_enabled": False, "details_submitted": False}
+    try:
+        acct = _client().Account.retrieve(affiliate.stripe_connect_account_id)
+        return {"exists": True,
+                "payouts_enabled": bool(acct.get("payouts_enabled")),
+                "details_submitted": bool(acct.get("details_submitted"))}
+    except Exception:  # noqa: BLE001 — never break the page over a Stripe hiccup
+        log.exception("Connect account lookup failed for %s", affiliate.code)
+        return {"exists": True, "payouts_enabled": False, "details_submitted": False}
+
+
+def connect_onboarding_url(affiliate, return_url: str) -> str:
+    """Create the affiliate's Express account if needed and return a fresh
+    onboarding link. Links are single-use and expire in minutes, which is
+    exactly why this is generated on demand from a button rather than emailed."""
+    s = _client()
+    if not affiliate.stripe_connect_account_id:
+        acct = s.Account.create(
+            type="express", email=affiliate.user.email,
+            capabilities={"transfers": {"requested": True}},
+            business_type="individual", metadata={"affiliate_code": affiliate.code},
+        )
+        affiliate.stripe_connect_account_id = acct["id"]
+        affiliate.save(update_fields=["stripe_connect_account_id"])
+        log.info("Connect account created for %s", affiliate.code)
+    status = connect_account_status(affiliate)
+    if status["details_submitted"]:
+        # Already onboarded — send them to their Express dashboard instead.
+        return s.Account.create_login_link(affiliate.stripe_connect_account_id)["url"]
+    return s.AccountLink.create(
+        account=affiliate.stripe_connect_account_id,
+        refresh_url=return_url, return_url=return_url, type="account_onboarding",
+    )["url"]
diff --git a/billing-docker/sites/billing/app/core/templates/core/affiliate.html b/billing-docker/sites/billing/app/core/templates/core/affiliate.html
@@ -13,12 +13,17 @@ <h1>Affiliate dashboard</h1>
       <div class="card">
         <p>✅ Agreement signed. Your referral link:</p>
         <p><code>https://{{ request.get_host }}/?ref={{ affiliate.code }}</code></p>
-        {% if not affiliate.stripe_connect_account_id %}
-          <p class="err">⚠️ Payouts not connected yet — your earnings below are accruing and
-             will transfer automatically once your Stripe payout account is connected.
-             WeOwn will send your onboarding link.</p>
+        {% if connect.payouts_enabled %}
+          <p class="muted">✅ Payouts connected — splits transfer automatically on each paid
+             invoice. <a href="{% url 'connect_payouts' %}">Manage payout account ↗</a></p>
+        {% elif connect.exists %}
+          <p class="err">⚠️ Payout setup unfinished — your earnings below are accruing safely
+             and will transfer as soon as Stripe has what it needs.</p>
+          <p><a class="btn" href="{% url 'connect_payouts' %}">Finish connecting payouts</a></p>
         {% else %}
-          <p class="muted">Payouts connected — splits transfer automatically on each paid invoice.</p>
+          <p class="err">⚠️ Payouts not connected yet — your earnings below are accruing and
+             will transfer automatically once you connect a payout account.</p>
+          <p><a class="btn" href="{% url 'connect_payouts' %}">Connect payouts</a></p>
         {% endif %}
       </div>
 
diff --git a/billing-docker/sites/billing/app/core/views.py b/billing-docker/sites/billing/app/core/views.py
@@ -106,6 +106,7 @@ def affiliate_home(request):
             "sub_affiliates": Affiliate.objects.filter(parent=aff).count(),
             "paid_dollars": f"{(agg['paid'] or 0) / 100:,.2f}",
             "pending_dollars": f"{(agg['pending'] or 0) / 100:,.2f}",
+            "connect": stripe_svc.connect_account_status(aff),
         })
     return render(request, "core/affiliate.html", ctx)
 
@@ -294,7 +295,7 @@ def new_instance(request):
     base = f"https://{settings.ALLOWED_HOSTS[0]}"
     session = stripe_svc.create_checkout_session(
         customer, success_url=f"{base}/subscribe/success/", cancel_url=f"{base}/",
-        instance=instance,
+        instance=instance, ref_code=ref,
     )
     return redirect(session.url, permanent=False)
 
@@ -368,3 +369,24 @@ def affiliate_join(request):
     log.info("AFFILIATE-JOIN code=%s user=%s sponsor=%s", aff.code, request.user.email,
              sponsor.code if sponsor else "-")
     return redirect("affiliate_home")
+
+
+@login_required
+def connect_payouts(request):
+    """Self-serve payout connection: the affiliate presses a button and lands in
+    Stripe's hosted onboarding. Replaces 'WeOwn will send your onboarding link',
+    which was a dead end — links expire in minutes so they cannot be emailed
+    ahead of time anyway."""
+    aff = Affiliate.objects.filter(user=request.user).first()
+    if not aff:
+        return redirect("affiliate_home")
+    base = f"https://{settings.ALLOWED_HOSTS[0]}"
+    try:
+        url = stripe_svc.connect_onboarding_url(aff, return_url=f"{base}/affiliate/")
+    except Exception:  # noqa: BLE001
+        log.exception("Connect onboarding failed for %s", aff.code)
+        return render(request, "core/affiliate.html",
+                      {"affiliate": aff, "signed": True,
+                       "error": "Could not reach Stripe just now — please try again in a moment."},
+                      status=502)
+    return redirect(url, permanent=False)
diff --git a/billing-docker/template/app/billing/urls.py b/billing-docker/template/app/billing/urls.py
@@ -16,6 +16,7 @@
     path("suspended/", views.suspended, name="suspended"),
     path("affiliate/", views.affiliate_home, name="affiliate_home"),
     path("affiliate/join/", views.affiliate_join, name="affiliate_join"),
+    path("affiliate/payouts/", views.connect_payouts, name="connect_payouts"),
     path("affiliate/check/", views.check_affiliate_code, name="check_affiliate_code"),
     path("affiliate/contract/", views.affiliate_contract, name="affiliate_contract"),
     path("webhooks/stripe/", views.stripe_webhook, name="stripe_webhook"),
diff --git a/billing-docker/template/app/core/stripe_svc.py b/billing-docker/template/app/core/stripe_svc.py
@@ -123,3 +123,42 @@ def pay_affiliate_splits(invoice: dict, subscription) -> None:
             log.info("Split paid: %s T%s -> %s (%s%% of profit %sc = %sc)",
                      invoice["id"], tier, leg_aff.code, pct, profit, cut)
         row.save()
+
+
+def connect_account_status(affiliate) -> dict:
+    """What Stripe thinks of this affiliate's payout account. Cheap enough to
+    call on the affiliate page; degrades to 'unknown' rather than erroring."""
+    if not affiliate.stripe_connect_account_id:
+        return {"exists": False, "payouts_enabled": False, "details_submitted": False}
+    try:
+        acct = _client().Account.retrieve(affiliate.stripe_connect_account_id)
+        return {"exists": True,
+                "payouts_enabled": bool(acct.get("payouts_enabled")),
+                "details_submitted": bool(acct.get("details_submitted"))}
+    except Exception:  # noqa: BLE001 — never break the page over a Stripe hiccup
+        log.exception("Connect account lookup failed for %s", affiliate.code)
+        return {"exists": True, "payouts_enabled": False, "details_submitted": False}
+
+
+def connect_onboarding_url(affiliate, return_url: str) -> str:
+    """Create the affiliate's Express account if needed and return a fresh
+    onboarding link. Links are single-use and expire in minutes, which is
+    exactly why this is generated on demand from a button rather than emailed."""
+    s = _client()
+    if not affiliate.stripe_connect_account_id:
+        acct = s.Account.create(
+            type="express", email=affiliate.user.email,
+            capabilities={"transfers": {"requested": True}},
+            business_type="individual", metadata={"affiliate_code": affiliate.code},
+        )
+        affiliate.stripe_connect_account_id = acct["id"]
+        affiliate.save(update_fields=["stripe_connect_account_id"])
+        log.info("Connect account created for %s", affiliate.code)
+    status = connect_account_status(affiliate)
+    if status["details_submitted"]:
+        # Already onboarded — send them to their Express dashboard instead.
+        return s.Account.create_login_link(affiliate.stripe_connect_account_id)["url"]
+    return s.AccountLink.create(
+        account=affiliate.stripe_connect_account_id,
+        refresh_url=return_url, return_url=return_url, type="account_onboarding",
+    )["url"]
diff --git a/billing-docker/template/app/core/templates/core/affiliate.html b/billing-docker/template/app/core/templates/core/affiliate.html
@@ -13,12 +13,17 @@ <h1>Affiliate dashboard</h1>
       <div class="card">
         <p>✅ Agreement signed. Your referral link:</p>
         <p><code>https://{{ request.get_host }}/?ref={{ affiliate.code }}</code></p>
-        {% if not affiliate.stripe_connect_account_id %}
-          <p class="err">⚠️ Payouts not connected yet — your earnings below are accruing and
-             will transfer automatically once your Stripe payout account is connected.
-             WeOwn will send your onboarding link.</p>
+        {% if connect.payouts_enabled %}
+          <p class="muted">✅ Payouts connected — splits transfer automatically on each paid
+             invoice. <a href="{% url 'connect_payouts' %}">Manage payout account ↗</a></p>
+        {% elif connect.exists %}
+          <p class="err">⚠️ Payout setup unfinished — your earnings below are accruing safely
+             and will transfer as soon as Stripe has what it needs.</p>
+          <p><a class="btn" href="{% url 'connect_payouts' %}">Finish connecting payouts</a></p>
         {% else %}
-          <p class="muted">Payouts connected — splits transfer automatically on each paid invoice.</p>
+          <p class="err">⚠️ Payouts not connected yet — your earnings below are accruing and
+             will transfer automatically once you connect a payout account.</p>
+          <p><a class="btn" href="{% url 'connect_payouts' %}">Connect payouts</a></p>
         {% endif %}
       </div>
 
diff --git a/billing-docker/template/app/core/views.py b/billing-docker/template/app/core/views.py
@@ -106,6 +106,7 @@ def affiliate_home(request):
             "sub_affiliates": Affiliate.objects.filter(parent=aff).count(),
             "paid_dollars": f"{(agg['paid'] or 0) / 100:,.2f}",
             "pending_dollars": f"{(agg['pending'] or 0) / 100:,.2f}",
+            "connect": stripe_svc.connect_account_status(aff),
         })
     return render(request, "core/affiliate.html", ctx)
 
@@ -294,7 +295,7 @@ def new_instance(request):
     base = f"https://{settings.ALLOWED_HOSTS[0]}"
     session = stripe_svc.create_checkout_session(
         customer, success_url=f"{base}/subscribe/success/", cancel_url=f"{base}/",
-        instance=instance,
+        instance=instance, ref_code=ref,
     )
     return redirect(session.url, permanent=False)
 
@@ -368,3 +369,24 @@ def affiliate_join(request):
     log.info("AFFILIATE-JOIN code=%s user=%s sponsor=%s", aff.code, request.user.email,
              sponsor.code if sponsor else "-")
     return redirect("affiliate_home")
+
+
+@login_required
+def connect_payouts(request):
+    """Self-serve payout connection: the affiliate presses a button and lands in
+    Stripe's hosted onboarding. Replaces 'WeOwn will send your onboarding link',
+    which was a dead end — links expire in minutes so they cannot be emailed
+    ahead of time anyway."""
+    aff = Affiliate.objects.filter(user=request.user).first()
+    if not aff:
+        return redirect("affiliate_home")
+    base = f"https://{settings.ALLOWED_HOSTS[0]}"
+    try:
+        url = stripe_svc.connect_onboarding_url(aff, return_url=f"{base}/affiliate/")
+    except Exception:  # noqa: BLE001
+        log.exception("Connect onboarding failed for %s", aff.code)
+        return render(request, "core/affiliate.html",
+                      {"affiliate": aff, "signed": True,
+                       "error": "Could not reach Stripe just now — please try again in a moment."},
+                      status=502)
+    return redirect(url, permanent=False)
diff --git a/docs/handoff/HANDOFF-keycloak-gitea-integration.md b/docs/handoff/HANDOFF-keycloak-gitea-integration.md
@@ -0,0 +1,31 @@
+# HANDOFF — Keycloak + Gitea for the WeOwn stack (overnight drive)
+
+> Status: **handoff** · Author: ncimino (via Claude Code) · Date: 2026-07-17
+> `main` HEAD at handoff: **`50d298c`** (PR #96 merged — customer dashboard).
+> **Operating mode: Nik is ASLEEP.** Drive as far as you can autonomously
+> tonight; anything human-gated goes on the morning list (§6), not a blocker to
+> stop on. Check things before acting — do not get stuck on one path; if a path
+> needs Nik, park it and advance another. Public repo: no secrets, no real IPs
+> (RFC 5737), no customer identifiers. Commits: ncimino only, no AI trailers.
+> Land work as conformant branch → auto-PR → merge (§5 mechanics).
+
+## 1. Mission
+
+Stand up **Gitea + Keycloak (SSO) for WeOwn** in the `ai` repo pattern —
+Jason approved both **in writing** (vault D452). Requirements:
+
+1. **Same principles as Perpetuator Platform internal deployments**, but on the
+   WeOwn stack with **Infisical** as the secret store (not OpenBao): IaC-only
+   (tofu + ansible, Path C + Layer 2), runtime secret injection (no secrets on
+   disk), copier-template form (`<service>-docker/`), hardened per
+   SOP-INFRA-012 Phase-A (CIS play + encrypted data volume — both now in
+   `anythingllm-docker` as the reference), skinny GPG-encrypted backups,
+   OTel observability.
+2. **Evaluate Peter/MOT's deployed work for alignment** — his keycloak-SSO
+   (PRJ-003), owncloud-oCIS, and smoke-test code are MERGED but he offboarded
+   W28 (vault: `Projects/MOT Offboarding Runbook - 2026-07-06.md`). How close
+   is what he built to the principles above? What drifts? Are his live
+   instances findable/verifiable?
+3. **Tonight's concrete goal:** a **local docker-compose proof** that Gitea
+   authenticates against Keycloak via OIDC end-to-end (login → Gitea account
+   provisioned), using the repo's template
diff --git a/docs/handoff/MORNING-BRIEF-demo-readiness.md b/docs/handoff/MORNING-BRIEF-demo-readiness.md
@@ -69,7 +69,7 @@ flip.
 
 ## Docs that exist for the team
 
-- `docs/handoff/TESTER-GUIDE-billing-flow.md` — for Tyler, Patrick, Coach LFG.
+- `docs/handoff/TESTER-GUIDE-billing-flow.md` — for the testing team.
 - `docs/handoff/OWNER-GUIDE-stripe-connect-and-splits.md` — money model, COGS,
   attribution rules, tax questions.
 - `docs/handoff/OWNER-GUIDE-stripe-dashboard.md` — reading payments in Stripe.
diff --git a/docs/handoff/OWNER-GUIDE-stripe-connect-and-splits.md b/docs/handoff/OWNER-GUIDE-stripe-connect-and-splits.md
@@ -1,6 +1,6 @@
 # WeOwn payments & affiliate splits — owner's guide
 
-**For:** Tyler (business owner / founder) and whoever handles WeOwn finance ops.
+**For:** the business owner and whoever handles WeOwn finance ops.
 **Covers:** how money flows, the Stripe Connect decisions already made and why,
 what changes for the production account, how the affiliate splits and COGS
 work, who is allowed to change what, and what to watch for.
diff --git a/docs/handoff/OWNER-GUIDE-stripe-dashboard.md b/docs/handoff/OWNER-GUIDE-stripe-dashboard.md
@@ -1,6 +1,6 @@
 # Reading the money in Stripe — owner's walkthrough
 
-**For:** Tyler and whoever handles WeOwn finance ops.
+**For:** the business owner and whoever handles WeOwn finance ops.
 **Companion to:** the splits & Connect guide (how the money is *decided*). This
 one is about *seeing* it — where to log in, what each screen means, and how to
 answer "did this person pay, and what did we keep?"
diff --git a/docs/handoff/TESTER-GUIDE-billing-flow.md b/docs/handoff/TESTER-GUIDE-billing-flow.md
@@ -1,6 +1,6 @@
 # WeOwn billing + affiliate flow — tester guide
 
-**Who this is for:** Tyler (TYL), Patrick (PAT), Coach LFG — anyone testing the
+**Who this is for:** the WeOwn testing team — anyone testing the
 customer signup → payment → instance → affiliate-split flow.
 
 **Everything here is Stripe TEST mode.** No real money moves. Use the test card
diff --git a/scripts/provision-openrouter-key.sh b/scripts/provision-openrouter-key.sh
@@ -95,7 +95,8 @@ else
 fi
 
 # Clear every secret var no matter how we exit.
-trap 'unset PROV_KEY CUSTOMER_KEY EXISTING_KEY 2>/dev/null || true' EXIT
+# (an EXIT trap is installed later, once the temp file exists, so it can
+#  shred the file and clear the variables together)
 
 # ── refuse to clobber an existing key unless --force (avoid orphaning) ────────
 # `infisical secrets get` exits 0 even for a secret that does not exist (proven
@@ -172,7 +173,14 @@ if [[ -z "${CUSTOMER_KEY:-}" ]]; then
 fi
 
 # ── push into the site Infisical project (see SECURITY NOTE in header) ───────
-if infisical secrets set "OPENROUTER_API_KEY=${CUSTOMER_KEY}" \
+# The value goes via a private temp file (NAME=@path), never argv: an argument
+# is visible in `ps`/`/proc` for the life of the call, which contradicted this
+# script's own "never on argv" promise. Same pattern as
+# devbox-docker/.../setup-zed.sh. umask 077 + shred on every exit path.
+SECRET_TMP="$(umask 077; mktemp)"
+trap 'rm -f "$SECRET_TMP" 2>/dev/null || true; unset PROV_KEY CUSTOMER_KEY EXISTING_KEY 2>/dev/null || true' EXIT
+printf '%s' "$CUSTOMER_KEY" > "$SECRET_TMP"
+if infisical secrets set "OPENROUTER_API_KEY=@$SECRET_TMP" \
      --projectId="$PROJECT_ID" --env="$ENV_SLUG" --path="$SECRET_PATH" >/dev/null 2>&1 \
    && [[ -n "$(infisical secrets get OPENROUTER_API_KEY --projectId="$PROJECT_ID" \
         --env="$ENV_SLUG" --path="$SECRET_PATH" --plain 2>/dev/null || true)" ]]; then
