@m-kopa/launchpad-cli 0.43.0 → 0.44.0

package/CHANGELOG.md

@@ -6,6 +6,31 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html);
 pre-1.0 minor bumps may carry breaking changes per ADR 0005.
 
+## 0.44.0 — 2026-07-05
+
+**Identity guide crystal-clarity — fixes the "gateway signs me in but the app
+says not signed in" class.** The `/launchpad-identity` skill told authors to read
+`GATEWAY_ISSUER / GATEWAY_AUD / GATEWAY_JWKS_URL` and (wrongly) that those are
+"what is live on Cloudflare" — but the platform engine actually provisions the
+gateway verifier values under the legacy names `CF_ACCESS_TEAM_DOMAIN /
+CF_ACCESS_AUD / JWKS_URL` for a `react+api` app. An app that followed the guide
+read only `GATEWAY_*`, found them undefined, and silently fail-closed every user
+to anonymous.
+
+- **Skill verifier snippet now reads BOTH name sets via `||`** (`GATEWAY_ISSUER
+  || CF_ACCESS_TEAM_DOMAIN`, etc.) — copy it and you are immune to the mismatch
+  whichever set your project carries.
+- **Corrected the false "GATEWAY_* are live on Cloudflare" claim**; added an
+  explicit two-convention name table, a gateway-vs-Cloudflare-Access note (the
+  issuer is `auth.launchpad.m-kopa.us`, **not** `*.cloudflareaccess.com`), the
+  bare-host `aud` rule, and the `secret_text` + same-deploy/redeploy requirement.
+- **`docs/guide/auth.md`**: banner correcting the gateway `/api/me` shape — it
+  carries `sub`/`email`/`name` only (**no `groups`** — never authorise from it),
+  and fail-closed is `200 {authenticated:false}`, not `401`.
+- **`@m-kopa/platform-auth` `types.ts`**: fixed the docstring that claimed
+  `preferredUsername` comes from a `preferred_username` claim — the runtime reads
+  the `email` claim (the IdP maps the Entra UPN into it).
+
 ## 0.43.0 — 2026-07-05
 
 **`launchpad deploy` now shows a pre-deploy config diff (PS-1920).** Before a

package/dist/cli.js

@@ -19,7 +19,7 @@ var __toESM = (mod, isNodeMode, target) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/version.ts
-var CLI_VERSION = "0.43.0";
+var CLI_VERSION = "0.44.0";
 
 // src/config.ts
 import * as os from "node:os";

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.43.0";
+export declare const CLI_VERSION = "0.44.0";
 //# sourceMappingURL=version.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@m-kopa/launchpad-cli",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Launchpad CLI — clone / deploy / review / merge against Launchpad-managed apps. Talks to the portal-bot endpoints (SCOPE-M-760 / T4).",
   "type": "module",
   "bin": {

package/skills/launchpad-content-pr/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-content-pr
 description: Push a content change to a Launchpad app via `launchpad deploy` and verify it shipped via `launchpad status`. Covers the post-first-deploy iteration loop (edit → deploy → verify) — subsequent deploys commit directly to the app repo's main and the Pages build runs asynchronously, so verification is its own step. Use when someone says "push a content change", "ship an update", "/launchpad-content-pr", "verify my deploy", or after `/launchpad-deploy` reports `done` and they want to follow up with an edit.
-version: 0.43.0
+version: 0.44.0
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->

package/skills/launchpad-deploy/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-deploy
 description: Walk a Launchpad user through deploying an app from their local working directory (Model A — `launchpad init` + `launchpad deploy`). Wraps the CLI verbs end-to-end: detects the app shape, scaffolds `launchpad.yaml`, resolves the allowed Entra group via `launchpad groups`, bundles the CWD via `launchpad deploy`, and watches the rollout via `launchpad status`. Use when someone says "deploy a new app", "ship my app to Launchpad", "/launchpad-deploy", "I have an app locally — get it on Launchpad", or any variant. Resume/abandon for legacy in-flight provisioning is at the bottom.
-version: 0.43.0
+version: 0.44.0
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->

package/skills/launchpad-deploy-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-deploy-status
 description: Show the current provisioning stage + failure reason for a Launchpad app via `launchpad status` (Model A drift + deployment_verified) and `launchpad apps` (lifecycle bucket), or watch provisioning live with `launchpad watch`. Renders the M-892 stage trace for in-flight provisioning, and is the canonical home for `launchpad recover` (repair a terminal-failed app record that is actually live). Use when someone says "what's the status of demo-X", "/launchpad-deploy-status", "is my deploy stuck", "watch my deploy go live", "watch provisioning", "my app says failed but it's serving", or after `/launchpad-deploy` reports a non-`done` terminal stage.
-version: 0.43.0
+version: 0.44.0
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->

package/skills/launchpad-destroy/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-destroy
 description: Tear down a Launchpad app end-to-end via `launchpad destroy` — Cloudflare Pages project, edge-auth wiring (gateway KV/audience entries, or the Access app for `auth: access` apps), custom hostname, platform-repo TF, and the app repo (archive-renamed). Owner-only verb with a two-step destructive confirmation. Use when someone says "destroy this app", "/launchpad-destroy", "tear down `<slug>`", "delete the app", or asks to clean up a smoke-test / orphan / retired app.
-version: 0.43.0
+version: 0.44.0
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->

package/skills/launchpad-identity/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-identity
 description: Teach an app author how to use the signed-in user's identity inside a Launchpad app — read the gateway-forwarded X-Launchpad-User-Assertion in a Pages Function, VERIFY it with @m-kopa/platform-auth (fail-closed), and show who's logged in (sub/email/name). Use when someone says "who is logged in", "show the current user", "get the user's email in my app", "auth in my launchpad app", "read the user identity", "/launchpad-identity", or is wiring up an /api/me for a gateway-fronted app.
-version: 0.43.0
+version: 0.44.0
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -130,10 +130,17 @@ export async function onRequestGet(context) {
   const token = request.headers.get(IDENTITY_HEADER);
   if (!token) return anonymous(); // no token → anonymous / public path
 
-  const issuer = env.GATEWAY_ISSUER; // gateway iss
-  const audience = env.GATEWAY_AUD; // this app's aud (pin to YOUR host)
+  // Read BOTH the canonical GATEWAY_* names AND the legacy CF_ACCESS_* / JWKS_URL
+  // names the platform engine currently provisions for react+api apps (identical
+  // gateway values, older key names). Tolerating both via `||` is what keeps this
+  // verifier working no matter which set your app was scaffolded with — skipping
+  // the fallback is the #1 cause of "gateway signs me in but the app says not
+  // signed in". See "Required env vars" below.
+  const issuer = env.GATEWAY_ISSUER || env.CF_ACCESS_TEAM_DOMAIN; // gateway iss
+  const audience = env.GATEWAY_AUD || env.CF_ACCESS_AUD; // this app's aud (your host)
   const jwksUrl =
     env.GATEWAY_JWKS_URL ||
+    env.JWKS_URL ||
     (issuer ? `${issuer.replace(/\/$/, '')}/.well-known/jwks.json` : null);
 
   // Misconfigured verify env → fail CLOSED. Never trust an unverifiable token.
@@ -227,30 +234,56 @@ vars — is identical to the example above.
 
 ## Required env vars — `secret_text`, MANDATORY
 
-Verification needs three env vars on your app. **Set them as `secret_text`,
-not plain text:**
+Verification needs three values on your app: the gateway **issuer**, **your
+app's audience**, and the **JWKS URL**. Two things trip people up — a value
+gotcha and a name gotcha. Read both.
 
-| Var | Value | Notes |
+**The value contract (identical whichever key names you use):**
+
+| Value | Set it to | Notes |
+|---|---|---|
+| issuer (`iss`) | `https://auth.launchpad.m-kopa.us` | the gateway token issuer — the **same for every app** |
+| audience (`aud`) | `<your-slug>.launchpad.m-kopa.us` | **your app's bare public host** — no `https://`, no port, no trailing slash. Exact-match replay guard: a wrong value fails closed. |
+| jwks | `https://auth.launchpad.m-kopa.us/.well-known/jwks.json` | optional — derived from the issuer if unset |
+
+**The name gotcha — read BOTH name sets.** There are currently **two** key-name
+conventions for these same three values, and which one your app has depends on
+how it was created:
+
+| Convention | Keys | Where it comes from |
 |---|---|---|
-| `GATEWAY_ISSUER` | `https://auth.launchpad.m-kopa.us` | the gateway token issuer (`iss`) |
-| `GATEWAY_AUD` | `<your-slug>.launchpad.m-kopa.us` | **your app's** audience (`aud`) — the replay guard |
-| `GATEWAY_JWKS_URL` | `https://auth.launchpad.m-kopa.us/.well-known/jwks.json` | optional — derived from `GATEWAY_ISSUER` if unset |
-
-> ⚠️ **Why `secret_text` is mandatory — the wipe → fail-closed chain.** If you
-> set these as **plain-text** env, the next `launchpad deploy` **wipes them**
-> (only `secret_text` vars survive a deploy — the CF-Access-env-vars-must-ship
-> runbook). With the env gone, `issuer`/`audience` are `undefined`, the
-> `if (!jwksUrl || !issuer || !audience) return anonymous()` guard fires, and
-> **every** user silently goes anonymous in production. The code is correct —
-> it fails *closed*, never open — but identity is dark until you re-add the
-> vars. Set them `secret_text` from the start and this never happens. Ship the
-> env in the **same** deploy as the consumer, or verification is dark.
-
-The canonical names are **`GATEWAY_ISSUER` / `GATEWAY_AUD` / `GATEWAY_JWKS_URL`**
-— what the deployed app reads and what is live on Cloudflare. (You may see the
-illustrative names `AUTH_ISS` / `APP_AUD` / `JWKS_URL` in older contract-doc
-snippets — the deployed convention is the `GATEWAY_*` set; use it. Note: it is
-`GATEWAY_AUD`, **not** `GATEWAY_AUDIENCE`.)
+| **Canonical** (this guide) | `GATEWAY_ISSUER` / `GATEWAY_AUD` / `GATEWAY_JWKS_URL` | the name set we are standardising on |
+| **Legacy** (auto-provisioned) | `CF_ACCESS_TEAM_DOMAIN` / `CF_ACCESS_AUD` / `JWKS_URL` | **what the platform engine actually sets on a `react+api` app today** — correct gateway values, older names (`per-app-workspace.ts`) |
+
+> ⚠️ **Do NOT assume `GATEWAY_*` are "already live."** A `react+api` app
+> scaffolded by the platform is born with the **`CF_ACCESS_*` / `JWKS_URL`**
+> keys — the engine reuses the pre-gateway Cloudflare-Access names for the
+> gateway values. If your verifier reads **only** `GATEWAY_*`, those keys are
+> `undefined`, the `if (!jwksUrl || !issuer || !audience) return anonymous()`
+> guard fires, and **every** user silently goes anonymous: the gateway signs
+> you in, but your app renders its own "not signed in" screen. **This is the #1
+> cause of that symptom.** The verifier snippet above already reads both name
+> sets via `||` — keep the fallback and you are immune to the mismatch,
+> whichever set your project carries.
+
+> **This is the gateway, not Cloudflare Access.** Despite the name,
+> `CF_ACCESS_TEAM_DOMAIN` here holds the **gateway** issuer
+> `https://auth.launchpad.m-kopa.us` — **not** a `*.cloudflareaccess.com`
+> domain. Any doc that tells you to point the issuer at `cloudflareaccess.com`
+> is describing the legacy Cloudflare-Access channel, not the
+> `X-Launchpad-User-Assertion` gateway channel these apps use. (Also: it is
+> `GATEWAY_AUD`, **not** `GATEWAY_AUDIENCE`; and ignore the illustrative
+> `AUTH_ISS` / `APP_AUD` names in older contract-doc snippets.)
+
+**Set them as `secret_text`, in the SAME deploy as the code that reads them.**
+
+> ⚠️ **`secret_text` + same-deploy, or identity goes dark.** Plain-text env is
+> silently dropped by Cloudflare Pages under partial-PATCH, and env only binds
+> on a **new** deployment. So if you set the vars as plain-text, **or** push
+> them *after* your last deploy, they are not live on the running deployment —
+> `issuer`/`audience` are `undefined`, the fail-closed guard fires, and identity
+> is dark until you re-add them `secret_text` and **redeploy**. Set them
+> `secret_text` and ship them in the same `launchpad deploy` as the consumer.
 
 ## Anti-pattern — do NOT do this
 
@@ -276,8 +309,13 @@ An unverified payload can be forged by anyone who can reach your origin
 - [ ] **Fails closed** to anonymous on missing token, missing env, or any
       verify error — never returns the unverified user.
 - [ ] No unsigned `decodeJwtPayload` on the auth path.
-- [ ] `GATEWAY_ISSUER` / `GATEWAY_AUD` / `GATEWAY_JWKS_URL` set as
-      **`secret_text`**, shipped in the **same** deploy.
+- [ ] Verifier reads **both** name sets via `||` (`GATEWAY_ISSUER ||
+      CF_ACCESS_TEAM_DOMAIN`, etc.) so it works whichever set your app carries.
+- [ ] Confirmed which env var **names** are actually live on your deployed
+      project (`CF_ACCESS_*` on an engine-scaffolded react+api app, `GATEWAY_*`
+      if you hand-set them), set as **`secret_text`**, shipped in the **same**
+      deploy — then `launchpad deploy` again if you added them after the last one.
+- [ ] `aud` is your **bare host** (`<slug>.launchpad.m-kopa.us`), no scheme/port.
 - [ ] No authorization decision is made from `/api/me` — attribution only.
 
 ## Don'ts

package/skills/launchpad-onboard/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-onboard
 description: One-time setup for the Launchpad CLI + Claude Code skill bundle. Verifies the `launchpad` CLI is installed and current, runs `launchpad whoami` to confirm the session is fresh, and checks the bundled skills are installed and in lock-step with the CLI. Idempotent — safe to re-run any time. Use when someone says "set me up for Launchpad", "I just got a new machine and want to use Launchpad", "/launchpad-onboard", or any of the other launchpad-* skills fails on a prereq check.
-version: 0.43.0
+version: 0.44.0
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->

package/skills/launchpad-report/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-report
 description: File a bug report or feature request to the Launchpad team's tracker from the CLI. Use when someone reports something broken, hits an error in a launchpad command, or wishes a feature existed — e.g. "this is broken", "report a bug", "can you file that", "I wish launchpad could…", "/launchpad-bug", "/launchpad-feature". Always confirm and show exactly what you'll send before filing; never file silently.
-version: 0.43.0
+version: 0.44.0
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->

package/skills/launchpad-status/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: launchpad-status
 description: Show whether a Launchpad app's local launchpad.yaml matches what's deployed, and read the deployed manifest. Wraps `launchpad pull` (fetch deployed YAML) and `launchpad status` (drift report). Use when someone says "is my app in sync", "what's deployed", "show drift", "/launchpad-status", "/launchpad-pull", or after `launchpad deploy` to verify the change landed.
-version: 0.43.0
+version: 0.44.0
 ---
 
 <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->