@m-kopa/launchpad-cli 0.66.0 → 0.67.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-identity
3
- 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.
4
- version: 0.66.0
3
+ 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 the app's server code (functions/ on a react+api app, compiled into its Worker on dispatch, or a Pages Function on a legacy Pages app), 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.
4
+ version: 0.67.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -43,20 +43,50 @@ A Launchpad app behind the Entra-OIDC gateway receives the signed-in user's
43
43
  **already-verified** identity as a signed token on every request; your app
44
44
  verifies that token and reads `{ sub, email, name }`. That is the whole job.
45
45
 
46
- ## Prerequisite — you need a Pages Function (not bare static HTML)
46
+ ## Prerequisite - you need server code (not bare static HTML)
47
47
 
48
48
  **Bare static HTML cannot read request headers**, so it cannot see the
49
- identity token. To read identity your app needs a server-side **Pages
50
- Function** (a file under `functions/`). Two app shapes qualify:
51
-
52
- - **`type: static` with a `functions/` directory** — a build-less static app
49
+ identity token. To read identity your app needs server-side code: a
50
+ handler under `functions/` in the normal case. There is no client-only way
51
+ to read the verified identity.
52
+
53
+ First check which origin the app is on: `spec.origin: dispatch` in a v2
54
+ `launchpad.yaml` means Workers dispatch, the default for new apps. A v1
55
+ manifest, or a v2 one without `spec.origin: dispatch`, means legacy Pages.
56
+ `launchpad status <slug> --json` shows `deployment.origin: "dispatch"` for a dispatch app.
57
+
58
+ **Dispatch (default for new apps)** - **`react+api`** is the app type for
59
+ server code. Its `functions/` directory is compiled by the app repo's build
60
+ into a single Worker module, which runs for the routes its functions claim
61
+ (normally `/api/*`). The handler code below works unchanged; follow
62
+ § Dispatch rules.
63
+
64
+ A dispatch `react` app whose own build emits a single bundled `_worker.js`
65
+ into its build output also gets that Worker uploaded, with the verifier env
66
+ and `/api/*` routing. That is a hand-rolled path: it runs without
67
+ `nodejs_compat`, and `launchpad migrate` refuses a committed `_worker.js`
68
+ at conversion. Use `react+api` unless you already maintain your own Worker.
69
+
70
+ A dispatch `static` or `react` app **cannot ship functions**.
71
+ `launchpad migrate` and the first-deploy conversion refuse a `functions/`
72
+ directory on those types, and on an app that is already on dispatch the
73
+ build only compiles `functions/` for `react+api`, so a `functions/` tree
74
+ added to a static or React app ships but never runs (`/api/me` 404s). If a
75
+ static or React app needs the signed-in user:
76
+
77
+ - **New app:** scaffold it as `react+api` (`launchpad init --type
78
+ react+api`) and put the handler at `functions/api/me.js`.
79
+ - **Existing app:** do not just flip `appType` or drop a `functions/`
80
+ directory in. Changing what runtime an app has is a platform change, so
81
+ raise it with `/launchpad-report` and let the platform team plan it.
82
+
83
+ **Pages (legacy)** - two app shapes qualify:
84
+
85
+ - **`type: static` with a `functions/` directory** - a build-less static app
53
86
  that still ships Pages Functions (this is what peoplemgr does).
54
- - **`react+api`** (or any app with a build) — your `/api/*` is already a
87
+ - **`react+api`** (or any app with a build) - your `/api/*` is already a
55
88
  Pages Function.
56
89
 
57
- If your app is pure HTML/CSS/JS with no `functions/`, you must add a Pages
58
- Function first. There is no client-only way to read the verified identity.
59
-
60
90
  ## The contract (read this before copying code)
61
91
 
62
92
  The platform gateway authenticates the user against Entra, then forwards its
@@ -90,11 +120,15 @@ the source of truth. If they ever disagree, the contract doc wins.
90
120
  one audience across apps, a token minted for app A is **replayable** against
91
121
  app B (cross-app token replay). Audience-pinning is what stops that.
92
122
 
93
- ## The canonical Pages Function — `functions/api/me.js`
123
+ ## The canonical handler - `functions/api/me.js`
94
124
 
95
125
  Lifted from the **deployed-and-verified** peoplemgr app
96
126
  (`repos/m-kopa-peoplemgr-hub/functions/api/me.js`). Copy it; change only the
97
- app-specific bits called out below.
127
+ app-specific bits called out below. It uses the Pages Functions
128
+ `onRequestGet` shape, which both origins accept: Pages runs it directly,
129
+ and the dispatch build compiles it into the app's Worker. On a `react+api`
130
+ app, import from `@m-kopa/platform-auth` instead of the vendored file (see
131
+ § The two app shapes).
98
132
 
99
133
  ```js
100
134
  import { verifyAccessJwt, createJwksCache } from '../_lib/platform-auth.mjs';
@@ -205,12 +239,48 @@ Container apps behind the gateway (AIO-811) get the same signed-in identity. The
205
239
  - **The container Worker verifies the assertion for you.** The generated `container-worker.ts` reads `X-Launchpad-User-Assertion`, verifies it with `@m-kopa/platform-auth` against `GATEWAY_ISSUER`, `GATEWAY_AUD` and `GATEWAY_JWKS_URL`, and returns 401 if it is missing or invalid. It is the only gate, because the container has no public hostname and no Cloudflare Access app.
206
240
  - **Your container process receives plain headers after that check:** `X-User-Sub` (Entra `oid`) and `X-User-Email` (tenant UPN), plus `X-User-Groups` when groups are present. Inbound `X-User-*` headers are stripped before the Worker sets its own, so a client cannot forge them.
207
241
  - **Do not re-verify in the container unless you need to.** The raw assertion is checked at the container Worker and your process sees only the `X-User-*` headers.
208
- - Same rules as Pages: identity is for attribution, not authorization. Enforce who may open the app through `access.allowed_entra_group`.
242
+ - Same rules as other apps: identity is for attribution, not authorization. Enforce who may open the app through `access.allowed_entra_group`.
209
243
  - The legacy `auth: access` container mode (Cloudflare Access JWT, `CF_ACCESS_*`) still works for existing apps but is limited by the Zero Trust seat cap. New container apps should use `auth: gateway`.
210
244
 
245
+ ## Dispatch rules (`spec.origin: dispatch`)
246
+
247
+ The verify code is the same on dispatch. What changes is how `functions/`
248
+ becomes a Worker, and that brings a few hard rules. `launchpad migrate`
249
+ refuses a root middleware or catch-all, and delivery refuses the `/*`
250
+ route one would compile to. The dispatch build refuses functions that
251
+ compile to more than one module, and the build and delivery both refuse a
252
+ `_worker.js` directory. Each refusal prints the reason. The third rule
253
+ is not checked; it just fails at runtime.
254
+
255
+ - **No root middleware or root catch-all.** A root `functions/_middleware`
256
+ or a root-level dynamic route such as `functions/[[path]].ts` would run
257
+ the Worker for every path, including static assets. Keep handlers under
258
+ a prefix: `functions/api/me.js`, `functions/api/[[path]].ts`.
259
+ - **Single module.** The functions must compile to one module. A
260
+ hand-written `_worker.js` is refused at conversion and a `_worker.js`
261
+ directory is refused at delivery. Normal `import`s of npm packages are
262
+ fine; they are bundled into that module.
263
+ - **No `next()` fallthrough.** The Worker only runs for the routes its
264
+ functions claim and has no fallback to static assets, so a function that
265
+ calls `next()` to serve an asset will not work. Return a response.
266
+ - **Verifier env is platform-set and reserved.** On every upload the
267
+ platform sets the issuer, audience and JWKS URL on the Worker under both
268
+ name sets (`GATEWAY_ISSUER` / `GATEWAY_AUD` / `GATEWAY_JWKS_URL` and
269
+ `CF_ACCESS_TEAM_DOMAIN` / `CF_ACCESS_AUD` / `JWKS_URL`). Do not set them
270
+ yourself: `launchpad secrets push` refuses those names with
271
+ `reserved_secret_name`, and a plain env var with one of those names is
272
+ replaced by the platform value. An app does not choose its own issuer.
273
+ - **JWKS fetch works.** The platform runs dispatch Workers with public
274
+ Internet routing for outbound `fetch()`, so `createJwksCache` can
275
+ retrieve `https://auth.launchpad.m-kopa.us/.well-known/jwks.json`. No
276
+ manifest change is needed.
277
+
211
278
  ## The two app shapes
212
279
 
213
- ### (a) build-less `type: static` — vendored verifier (INTERIM)
280
+ ### (a) build-less `type: static` - vendored verifier (INTERIM, Pages only)
281
+
282
+ This shape exists only on the legacy Pages origin. A dispatch static app
283
+ cannot ship functions at all (see § Prerequisite).
214
284
 
215
285
  A build-less static app has **no `package.json` and no install step at
216
286
  deploy**, so its Pages Functions cannot `import` an npm package by name. The
@@ -230,10 +300,10 @@ ESM bundle; the recipe lives in
230
300
  > it once it lands; until then, vendoring is the documented reality — with
231
301
  > this staleness caveat attached.
232
302
 
233
- ### (b) `react+api` / any app with a build — import the package
303
+ ### (b) `react+api` / any app with a build - import the package
234
304
 
235
- If your app has a build step, drop the vendored file and import the package
236
- directly:
305
+ This is the shape for dispatch, and for a Pages app with a build step. Drop
306
+ the vendored file and import the package directly:
237
307
 
238
308
  ```js
239
309
  import { verifyAccessJwt, createJwksCache } from '@m-kopa/platform-auth';
@@ -242,11 +312,18 @@ import { verifyAccessJwt, createJwksCache } from '@m-kopa/platform-auth';
242
312
  Everything else — the header, the verify call, the fail-closed shape, the env
243
313
  vars — is identical to the example above.
244
314
 
245
- ## Required env vars — `secret_text`, MANDATORY
315
+ ## Required env vars
246
316
 
247
317
  Verification needs three values on your app: the gateway **issuer**, **your
248
- app's audience**, and the **JWKS URL**. Two things trip people up — a value
249
- gotcha and a name gotcha. Read both.
318
+ app's audience**, and the **JWKS URL**.
319
+
320
+ **On dispatch, the platform sets all of them for you** on every upload,
321
+ under both name sets (§ Dispatch rules). Do not push or declare them. The
322
+ `||` fallback in the handler still costs nothing, so keep it.
323
+
324
+ **On a legacy Pages app**, they live on the Pages project as `secret_text`,
325
+ and two things trip people up - a value gotcha and a name gotcha. Read
326
+ both.
250
327
 
251
328
  **The value contract (identical whichever key names you use):**
252
329
 
@@ -263,18 +340,20 @@ how it was created:
263
340
  | Convention | Keys | Where it comes from |
264
341
  |---|---|---|
265
342
  | **Canonical** (this guide) | `GATEWAY_ISSUER` / `GATEWAY_AUD` / `GATEWAY_JWKS_URL` | the name set we are standardising on |
266
- | **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`) |
267
-
268
- > ⚠️ **Do NOT assume `GATEWAY_*` are "already live."** A `react+api` app
269
- > scaffolded by the platform is born with the **`CF_ACCESS_*` / `JWKS_URL`**
270
- > keys — the engine reuses the pre-gateway Cloudflare-Access names for the
271
- > gateway values. If your verifier reads **only** `GATEWAY_*`, those keys are
272
- > `undefined`, the `if (!jwksUrl || !issuer || !audience) return anonymous()`
273
- > guard fires, and **every** user silently goes anonymous: the gateway signs
274
- > you in, but your app renders its own "not signed in" screen. **This is the #1
275
- > cause of that symptom.** The verifier snippet above already reads both name
276
- > sets via `||` — keep the fallback and you are immune to the mismatch,
277
- > whichever set your project carries.
343
+ | **Legacy** | `CF_ACCESS_TEAM_DOMAIN` / `CF_ACCESS_AUD` / `JWKS_URL` | correct gateway values under older names. Pages `react+api` apps, and `react` apps that ship a Pages Function, provisioned before the engine started emitting both sets (5 July 2026, #472) and not regenerated since may carry **only** these; later Pages apps and every dispatch app get both sets (`per-app-workspace.ts`, `wfp-upload-plan.ts`) |
344
+
345
+ > ⚠️ **Do NOT assume `GATEWAY_*` are "already live" on a Pages app.** An
346
+ > older platform-scaffolded Pages `react+api` app (or a `react` app that
347
+ > ships a `functions/` handler) may have only the
348
+ > **`CF_ACCESS_*` / `JWKS_URL`** keys - the engine used to reuse the
349
+ > pre-gateway Cloudflare-Access names for the gateway values. If your verifier
350
+ > reads **only** `GATEWAY_*`, those keys are `undefined`, the
351
+ > `if (!jwksUrl || !issuer || !audience) return anonymous()` guard fires, and
352
+ > **every** user silently goes anonymous: the gateway signs you in, but your
353
+ > app renders its own "not signed in" screen. **This is the #1 cause of that
354
+ > symptom.** The verifier snippet above already reads both name sets via
355
+ > `||`, so keep the fallback and you are immune to the mismatch, whichever set
356
+ > your project carries.
278
357
 
279
358
  > **This is the gateway, not Cloudflare Access.** Despite the name,
280
359
  > `CF_ACCESS_TEAM_DOMAIN` here holds the **gateway** issuer
@@ -285,7 +364,7 @@ how it was created:
285
364
  > `GATEWAY_AUD`, **not** `GATEWAY_AUDIENCE`; and ignore the illustrative
286
365
  > `AUTH_ISS` / `APP_AUD` names in older contract-doc snippets.)
287
366
 
288
- **Set them as `secret_text`, in the SAME deploy as the code that reads them.**
367
+ **Pages only: set them as `secret_text`, in the SAME deploy as the code that reads them.**
289
368
 
290
369
  > ⚠️ **`secret_text` + same-deploy, or identity goes dark.** Plain-text env is
291
370
  > silently dropped by Cloudflare Pages under partial-PATCH, and env only binds
@@ -313,7 +392,11 @@ An unverified payload can be forged by anyone who can reach your origin
313
392
 
314
393
  ## Checklist before you ship
315
394
 
316
- - [ ] App has a **Pages Function** (not bare static HTML).
395
+ - [ ] App has server code (not bare static HTML): a `react+api` app's
396
+ `functions/` on dispatch, or a Pages Function on a legacy Pages app.
397
+ - [ ] On dispatch: handler sits under a prefix such as `functions/api/`
398
+ (no root `_middleware` or root catch-all), never calls `next()` to
399
+ reach a static asset, and compiles to a single module.
317
400
  - [ ] Reads `X-Launchpad-User-Assertion` and **verifies** with
318
401
  `verifyAccessJwt` (signature + issuer + **audience pinned to your host**).
319
402
  - [ ] **Fails closed** to anonymous on missing token, missing env, or any
@@ -321,10 +404,13 @@ An unverified payload can be forged by anyone who can reach your origin
321
404
  - [ ] No unsigned `decodeJwtPayload` on the auth path.
322
405
  - [ ] Verifier reads **both** name sets via `||` (`GATEWAY_ISSUER ||
323
406
  CF_ACCESS_TEAM_DOMAIN`, etc.) so it works whichever set your app carries.
324
- - [ ] Confirmed which env var **names** are actually live on your deployed
325
- project (`CF_ACCESS_*` on an engine-scaffolded react+api app, `GATEWAY_*`
326
- if you hand-set them), set as **`secret_text`**, shipped in the **same**
327
- deploy — then `launchpad deploy` again if you added them after the last one.
407
+ - [ ] On dispatch: did **not** set any verifier env yourself (the platform
408
+ sets both name sets and reserves them).
409
+ - [ ] On Pages: confirmed which env var **names** are actually live on your
410
+ deployed project (only `CF_ACCESS_*` on an older engine-scaffolded
411
+ react+api app, both sets on a newer one, `GATEWAY_*` if you hand-set
412
+ them), set as **`secret_text`**, shipped in the **same** deploy - then
413
+ `launchpad redeploy` if you added them after the last one.
328
414
  - [ ] `aud` is your **bare host** (`<slug>.launchpad.m-kopa.us`), no scheme/port.
329
415
  - [ ] No authorization decision is made from `/api/me` — attribution only.
330
416
 
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-onboard
3
3
  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.
4
- version: 0.66.0
4
+ version: 0.67.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -221,6 +221,7 @@ Use the normal `launchpad deploy` flow; authors do not create Cloudflare project
221
221
  The platform assigns new gateway-fronted apps to the configured gateway with the most free hostname slots, including pending reservations.
222
222
  Existing apps keep their assigned gateway, URL and access groups.
223
223
  Registered apps keep their current origin.
224
- An older manifest for an unregistered static, React or React API app is converted to dispatch on its first `launchpad deploy`; a React API app with KV, R2 or other unsupported wrangler bindings stays on Pages with the reason printed.
224
+ An older manifest with no origin set, for an unregistered static, React or React API app, is converted to dispatch on its first `launchpad deploy`; one that sets `origin: pages` (v1) or `spec.origin: pages` (v2) stays on Pages untouched.
225
+ A new app with no origin set and KV, R2 or other unsupported wrangler bindings stops before deploying with the reason printed.
225
226
  An explicit `--origin pages` is available when required.
226
227
  Dispatch apps declare secrets as `secret_text` env vars and set them with `launchpad secrets push` once the first deploy has been delivered.
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-report
3
3
  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.
4
- version: 0.66.0
4
+ version: 0.67.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  name: launchpad-status
3
3
  description: Safely refresh a Launchpad clone, show manifest drift, or read the deployed manifest. Wraps bare `launchpad pull` for source sync, `launchpad pull --manifest` for deployed YAML, and `launchpad status` for drift. Use for "sync my clone", "what's deployed", "show drift", "/launchpad-status", "/launchpad-pull", or post-deploy verification.
4
- version: 0.66.0
4
+ version: 0.67.0
5
5
  ---
6
6
 
7
7
  <!-- BEGIN shell-contract (managed by scripts/sync-skill-contract.sh — edit skills/_partials/shell-contract.md) -->