Portal procurement: enterprise licence-key mechanism (generate at trial, upgrade on subscription, view/download) (Stirling-Tools#6902)

Builds on the procurement vertical slice (Stirling-Tools#6861). Adds the **enterprise
licence-key mechanism**: a Keygen licence is generated at trial,
upgraded in place when the committed subscription is created, and is
viewable/downloadable in the portal. Flag-gated — ships with the mock as
default until Keygen env vars are wired.

### What it does
- **Offline / air-gapped licence** is a new **priced add-on** on the
quote ($12k/yr, flat, alongside indemnification / training / QBR).
- **Licence key visible from the trial step** — the portal shows the key
with **Copy**, and (when the offline add-on is bought) a **Download
offline licence (.lic)** button.
- **Real Keygen client, called directly from Java**
(`KeygenEnterpriseLicenseService`), behind `stirling.keygen.enabled`;
`MockEnterpriseLicenseService` stays the default. All creds are env vars
(`STIRLING_KEYGEN_*`) — nothing committed.
- **Provisioning is driven by the Stripe `customer.subscription.created`
event** (source of truth), not a UI action — so a sales-led deal entered
manually in Stripe provisions a licence too. The webhook calls a new
admin `POST /api/v1/procurement/provision`, which upgrades the trial
licence **in place** to the committed annual term, **valid immediately**
(no wait for payment). The deal stays in the payment step so the
outstanding invoice remains visible.
- Offline `.lic` is checked out `base64+ed25519` (signed, unencrypted)
so the self-hosted `KeygenLicenseVerifier` validates it fully offline.

### Not in scope (deliberate, follow-ups)
- Cloud entitlement flip — a **cloud** customer sees/downloads the key
but the running cloud product doesn't unlock yet (self-hosted/air-gap
**are** unlocked by the key). Immediate next PR.
- `invoice.paid → fully-live` / `payment_failed → suspend` webhook
safety-net.

### Companion change (separate repo)
- The Stripe-webhook wiring that calls `/provision` lives in the
**Stirling-PDF-SaaS** repo (committed on `v3`, not part of this PR):
`stripe-webhook` routes enterprise-committed `subscription.created` →
`provisionProcurement()` → the Java admin endpoint.

### Prod setup required
- Create the committed-enterprise **Keygen policy with
`scheme=ed25519`** under the existing account, set
`STIRLING_KEYGEN_ENABLED=true` + account/token/policy env vars.

### Verified
saas `:saas:test` (procurement) · portal typecheck / eslint / prettier ·
82 portal tests · `deno check` on the webhook handler.

### Review follow-ups (PR review, tracked)
Low-hardening fixes applied in `85369633ed`: keep Keygen response bodies
out of thrown/logged messages; fail-fast at startup when the flag is on
but creds are missing; gate the offline `.lic` on the *accepted* quote
(not the latest draft).

Deliberately deferred, tracked here:
- **Pre-flag verification.** Before `stirling.keygen.enabled=true`,
confirm the id-vs-key addressing against live Keygen. (The shipping
self-hosted edge addresses licences by URL-safe key in the path and
Keygen docs allow it, so the client mirrors that — but confirm
empirically with the real committed-enterprise policy.)
- **No auto-revoke on non-payment.** Provision issues an
immediately-valid annual licence before payment settles; `invoice.paid →
live` and `payment_failed → suspend` are out of scope here. Note the
offline `.lic`, once downloaded, verifies offline for the full term and
**can't be revoked** — so the real mitigation for the offline case is a
shorter bridge term until `invoice.paid`, not just wiring `suspend`.
Enterprise is sales-led/ADMIN-gated, so this is a collections concern,
not mass abuse.

Author: ConnorYoh

app/saas/src/main/java/stirling/software/saas/procurement/api/ProcurementController.java

@@ -2,16 +2,20 @@
 
 import java.util.List;
 import java.util.Objects;
+import java.util.Optional;
 
 import org.springframework.context.annotation.Profile;
+import org.springframework.http.HttpHeaders;
 import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestBody;
 import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
 
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -72,24 +76,28 @@ public ProcurementController(
     public record QuoteRequest(
             long volume,
             int users,
+            int intensity, // policy posture (runs/PDF): 2 / 4 / 7; 0 → default Governed
             String deployment,
             int termYears,
             String serviceLevel,
             boolean indemnification,
             boolean training,
             boolean qbr,
+            boolean offlineLicense,
             String currency,
             String businessName) {
         QuoteConfig toConfig() {
             return new QuoteConfig(
                     volume,
                     users,
+                    intensity,
                     deployment,
                     termYears,
                     serviceLevel,
                     indemnification,
                     training,
                     qbr,
+                    offlineLicense,
                     currency);
         }
     }
@@ -115,12 +123,14 @@ public record QuoteResponse(
     public record QuoteConfigEcho(
             long volume,
             int users,
+            int intensity,
             String deployment,
             int termYears,
             String serviceLevel,
             boolean indemnification,
             boolean training,
             boolean qbr,
+            boolean offlineLicense,
             String currency,
             String businessName) {}
 
@@ -131,6 +141,7 @@ public record SnapshotResponse(
             String trialEndsAt,
             int trialExtensionsUsed,
             boolean licensed,
+            String licenseKey,
             QuoteResponse latestQuote) {}
 
     // ---- endpoints ----------------------------------------------------------
@@ -143,21 +154,49 @@ public record SnapshotResponse(
     @GetMapping
     @PreAuthorize("isAuthenticated()")
     public ResponseEntity<SnapshotResponse> snapshot(Authentication auth) {
-        Long teamId = resolveTeam(auth);
-        if (teamId == null) return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+        Optional<TeamMembership> membership = primaryMembership(auth);
+        if (membership.isEmpty()) return ResponseEntity.status(HttpStatus.UNAUTHORIZED).build();
+        Long teamId = membership.get().getTeam().getId();
+        // The licence key is the team's secret entitlement — leader-only. Members still see the
+        // journey (stage, trial, quote) but the key is withheld; the .lic file is likewise gated.
+        boolean leader = membership.get().getRole() == TeamRole.LEADER;
         return ResponseEntity.ok(
-                procurement.getDeal(teamId).map(this::toSnapshot).orElse(EMPTY_SNAPSHOT));
+                procurement.getDeal(teamId).map(d -> toSnapshot(d, leader)).orElse(EMPTY_SNAPSHOT));
     }
 
     private static final SnapshotResponse EMPTY_SNAPSHOT =
-            new SnapshotResponse(null, null, null, null, 0, false, null);
+            new SnapshotResponse(null, null, null, null, 0, false, null, null);
+
+    /**
+     * Download the offline / air-gapped licence file (.lic) for the team, when the paid offline
+     * add-on was purchased. 404 when there's no licence or the add-on wasn't taken — we don't leak
+     * that a licence exists to a team without the add-on.
+     */
+    @GetMapping("/license/file")
+    @PreAuthorize("isAuthenticated()")
+    public ResponseEntity<String> licenseFile(Authentication auth) {
+        // Leader-only: the offline .lic is the team's portable entitlement, not a member artefact.
+        Long teamId = requireLeader(auth);
+        if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
+        return procurement
+                .offlineLicenseFile(teamId)
+                .<ResponseEntity<String>>map(
+                        cert ->
+                                ResponseEntity.ok()
+                                        .header(
+                                                HttpHeaders.CONTENT_DISPOSITION,
+                                                "attachment; filename=\"stirling-enterprise.lic\"")
+                                        .contentType(MediaType.TEXT_PLAIN)
+                                        .body(cert))
+                .orElseGet(() -> ResponseEntity.notFound().build());
+    }
 
     @PostMapping("/trial/start")
     @PreAuthorize("isAuthenticated()")
     public ResponseEntity<SnapshotResponse> startTrial(Authentication auth) {
         Long teamId = requireLeader(auth);
         if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
-        return ResponseEntity.ok(toSnapshot(procurement.startTrial(teamId)));
+        return ResponseEntity.ok(toSnapshot(procurement.startTrial(teamId), true));
     }
 
     @PostMapping("/trial/extend")
@@ -166,7 +205,7 @@ public ResponseEntity<SnapshotResponse> extendTrial(Authentication auth) {
         Long teamId = requireLeader(auth);
         if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
         try {
-            return ResponseEntity.ok(toSnapshot(procurement.extendTrial(teamId)));
+            return ResponseEntity.ok(toSnapshot(procurement.extendTrial(teamId), true));
         } catch (IllegalStateException e) {
             return ResponseEntity.status(HttpStatus.CONFLICT).build();
         }
@@ -197,8 +236,26 @@ public ResponseEntity<SnapshotResponse> startAgreement(Authentication auth) {
         Long teamId = requireLeader(auth);
         if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
         try {
-            return ResponseEntity.ok(toSnapshot(procurement.startAgreement(teamId)));
+            return ResponseEntity.ok(toSnapshot(procurement.startAgreement(teamId), true));
+        } catch (IllegalStateException e) {
+            return ResponseEntity.status(HttpStatus.CONFLICT).build();
+        }
+    }
+
+    /**
+     * Provision on accept: upgrade the team's licence to the committed annual term, valid
+     * immediately. Called server-side by the accept edge function (ROLE_ADMIN via X-API-Key) once
+     * the subscription + invoice exist, so the buyer is licensed the moment they accept — the deal
+     * stays in the payment step until the invoice settles. Idempotent.
+     */
+    @PostMapping("/provision")
+    @PreAuthorize("hasRole('ADMIN')")
+    public ResponseEntity<Void> provision(@RequestParam("teamId") long teamId) {
+        try {
+            procurement.provisionLicense(teamId);
+            return ResponseEntity.ok().build();
         } catch (IllegalStateException e) {
+            log.warn("[procurement] provision rejected team={}: {}", teamId, e.getMessage());
             return ResponseEntity.status(HttpStatus.CONFLICT).build();
         }
     }
@@ -214,7 +271,7 @@ public ResponseEntity<SnapshotResponse> goLive(Authentication auth) {
         Long teamId = requireLeader(auth);
         if (teamId == null) return ResponseEntity.status(HttpStatus.FORBIDDEN).build();
         try {
-            return ResponseEntity.ok(toSnapshot(procurement.markLive(teamId)));
+            return ResponseEntity.ok(toSnapshot(procurement.markLive(teamId), true));
         } catch (IllegalStateException e) {
             return ResponseEntity.status(HttpStatus.CONFLICT).build();
         }
@@ -233,34 +290,31 @@ public ResponseEntity<SnapshotResponse> reset(Authentication auth) {
 
     // ---- helpers ------------------------------------------------------------
 
-    /**
-     * Resolve the caller's team from their primary membership; null when unauthenticated/teamless.
-     */
-    private Long resolveTeam(Authentication auth) {
+    /** The caller's primary team membership; empty when unauthenticated/teamless. */
+    private Optional<TeamMembership> primaryMembership(Authentication auth) {
         User user;
         try {
             user = AuthenticationUtils.getCurrentUser(auth, userRepository);
         } catch (SecurityException e) {
-            return null;
+            return Optional.empty();
         }
-        List<TeamMembership> rows = memberRepo.findPrimaryMembership(user.getId());
-        return rows.isEmpty() ? null : rows.get(0).getTeam().getId();
+        return memberRepo.findPrimaryMembership(user.getId()).stream().findFirst();
     }
 
     /** Team id only when the caller is the team leader; null otherwise (commercial actions). */
     private Long requireLeader(Authentication auth) {
-        User user;
-        try {
-            user = AuthenticationUtils.getCurrentUser(auth, userRepository);
-        } catch (SecurityException e) {
-            return null;
-        }
-        List<TeamMembership> rows = memberRepo.findPrimaryMembership(user.getId());
-        if (rows.isEmpty() || rows.get(0).getRole() != TeamRole.LEADER) return null;
-        return rows.get(0).getTeam().getId();
+        return primaryMembership(auth)
+                .filter(m -> m.getRole() == TeamRole.LEADER)
+                .map(m -> m.getTeam().getId())
+                .orElse(null);
     }
 
-    private SnapshotResponse toSnapshot(ProcurementDeal deal) {
+    /**
+     * Build the snapshot for a deal. {@code includeLicenseKey} is true only for the team leader; a
+     * member sees {@code licensed} but not the key itself (see {@link #snapshot}). Mutation
+     * endpoints are leader-gated, so they always pass true.
+     */
+    private SnapshotResponse toSnapshot(ProcurementDeal deal, boolean includeLicenseKey) {
         QuoteResponse latest =
                 procurement.quotesForDeal(deal.getDealId()).stream()
                         .findFirst()
@@ -273,6 +327,7 @@ private SnapshotResponse toSnapshot(ProcurementDeal deal) {
                 str(deal.getTrialEndsAt()),
                 deal.getTrialExtensionsUsed(),
                 deal.getLicenseRef() != null,
+                includeLicenseKey ? deal.getLicenseRef() : null,
                 latest);
     }
 
@@ -291,12 +346,14 @@ private QuoteResponse toQuote(ProcurementQuote q) {
                 new QuoteConfigEcho(
                         q.getVolume(),
                         0,
+                        q.getIntensity(),
                         q.getDeployment(),
                         q.getTermYears(),
                         q.getServiceLevel(),
                         q.isIndemnification(),
                         q.isTraining(),
                         q.isQbr(),
+                        q.isOfflineLicense(),
                         q.getCurrency(),
                         q.getBusinessName()));
     }

app/saas/src/main/java/stirling/software/saas/procurement/config/KeygenConfigurationProperties.java

@@ -0,0 +1,55 @@
+package stirling.software.saas.procurement.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.context.annotation.Profile;
+import org.springframework.stereotype.Component;
+
+import lombok.Getter;
+import lombok.Setter;
+
+/**
+ * Keygen credentials + policy for issuing enterprise procurement licences directly from Java.
+ * Prefix {@code stirling.keygen}. All secrets come from the environment (relaxed binding: {@code
+ * STIRLING_KEYGEN_ACCOUNT_ID}, {@code STIRLING_KEYGEN_API_TOKEN}, …) — never committed.
+ *
+ * <p>{@code enabled} is the switch between {@code MockEnterpriseLicenseService} (default) and the
+ * real {@code KeygenEnterpriseLicenseService}; the mock stays in place until the env vars are
+ * wired.
+ */
+@Getter
+@Setter
+@Component
+@Profile("saas")
+@ConfigurationProperties(prefix = "stirling.keygen")
+public class KeygenConfigurationProperties {
+
+    /** Master switch: when true, the real Keygen client replaces the mock licence service. */
+    private boolean enabled = false;
+
+    /** Keygen account id (UUID or slug). From {@code STIRLING_KEYGEN_ACCOUNT_ID}. */
+    private String accountId;
+
+    /** Keygen admin API token. From {@code STIRLING_KEYGEN_API_TOKEN}. Never log this. */
+    private String apiToken;
+
+    /** Policy the committed-enterprise licences are created under. From {@code ..._POLICY_ID}. */
+    private String policyId;
+
+    /** API base; overridable for self-hosted Keygen, defaults to the hosted service. */
+    private String apiBase = "https://api.keygen.sh/v1";
+
+    /**
+     * License-file check-out algorithm. Must stay {@code base64+ed25519} — the self-hosted {@code
+     * KeygenLicenseVerifier} only verifies that scheme (signed, unencrypted) offline.
+     */
+    private String licenseFileAlgorithm = "base64+ed25519";
+
+    /** True when the credentials needed to talk to Keygen are all present. */
+    public boolean isConfigured() {
+        return notBlank(accountId) && notBlank(apiToken) && notBlank(policyId);
+    }
+
+    private static boolean notBlank(String s) {
+        return s != null && !s.isBlank();
+    }
+}

app/saas/src/main/java/stirling/software/saas/procurement/license/EnterpriseLicenseService.java

@@ -11,15 +11,37 @@
  */
 public interface EnterpriseLicenseService {
 
-    /** Issue a time-boxed trial licence for the team; returns the licence reference. */
-    String issueTrialLicense(Long teamId, LocalDateTime expiresAt);
+    /**
+     * Issue a time-boxed trial licence for the team, owned by {@code ownerEmail} (the team leader);
+     * returns the licence reference (the Keygen key, stored on the deal).
+     */
+    String issueTrialLicense(Long teamId, String ownerEmail, LocalDateTime expiresAt);
 
     /** Move a licence's expiry out (trial extension). */
     void extendLicense(String licenseRef, LocalDateTime newExpiry);
 
-    /** Issue/upgrade to a committed annual licence with the quote's entitlements. */
-    String issueAnnualLicense(Long teamId, String deployment, LocalDateTime expiresAt);
+    /**
+     * Issue/upgrade to a committed annual licence carrying the deal's {@link LicenseEntitlements}
+     * ({@code seats} = 0 means unlimited). When {@code existingRef} is non-null (the team already
+     * has a trial licence), that licence is upgraded in place so the key the buyer already holds
+     * keeps working; otherwise a new licence is created. Owned by {@code ownerEmail}; returns the
+     * licence reference.
+     */
+    String issueAnnualLicense(
+            Long teamId,
+            String ownerEmail,
+            LocalDateTime expiresAt,
+            String existingRef,
+            LicenseEntitlements entitlements);
 
     /** Suspend a licence (e.g. payment failed, deal lost). */
     void suspendLicense(String licenseRef);
+
+    /**
+     * Check out a signed, offline-verifiable licence file (a {@code -----BEGIN LICENSE FILE-----}
+     * certificate) for the given licence, for an air-gapped self-hosted instance. The paid offline
+     * add-on gates whether this is offered; the certificate itself is generated on demand and never
+     * stored.
+     */
+    String checkOutLicenseFile(String licenseRef);
 }