@m-kopa/launchpad-cli 0.65.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.65.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';
@@ -198,9 +232,55 @@ if (me.authenticated) {
198
232
  }
199
233
  ```
200
234
 
235
+ ## Container apps (`type: container`, `auth: gateway`)
236
+
237
+ Container apps behind the gateway (AIO-811) get the same signed-in identity. The path is gateway → `launchpad-container-router` → your app's container Worker, and the gateway still sends `X-Launchpad-User-Assertion`.
238
+
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.
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.
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.
242
+ - Same rules as other apps: identity is for attribution, not authorization. Enforce who may open the app through `access.allowed_entra_group`.
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`.
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
+
201
278
  ## The two app shapes
202
279
 
203
- ### (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).
204
284
 
205
285
  A build-less static app has **no `package.json` and no install step at
206
286
  deploy**, so its Pages Functions cannot `import` an npm package by name. The
@@ -220,10 +300,10 @@ ESM bundle; the recipe lives in
220
300
  > it once it lands; until then, vendoring is the documented reality — with
221
301
  > this staleness caveat attached.
222
302
 
223
- ### (b) `react+api` / any app with a build — import the package
303
+ ### (b) `react+api` / any app with a build - import the package
224
304
 
225
- If your app has a build step, drop the vendored file and import the package
226
- 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:
227
307
 
228
308
  ```js
229
309
  import { verifyAccessJwt, createJwksCache } from '@m-kopa/platform-auth';
@@ -232,11 +312,18 @@ import { verifyAccessJwt, createJwksCache } from '@m-kopa/platform-auth';
232
312
  Everything else — the header, the verify call, the fail-closed shape, the env
233
313
  vars — is identical to the example above.
234
314
 
235
- ## Required env vars — `secret_text`, MANDATORY
315
+ ## Required env vars
236
316
 
237
317
  Verification needs three values on your app: the gateway **issuer**, **your
238
- app's audience**, and the **JWKS URL**. Two things trip people up — a value
239
- 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.
240
327
 
241
328
  **The value contract (identical whichever key names you use):**
242
329
 
@@ -253,18 +340,20 @@ how it was created:
253
340
  | Convention | Keys | Where it comes from |
254
341
  |---|---|---|
255
342
  | **Canonical** (this guide) | `GATEWAY_ISSUER` / `GATEWAY_AUD` / `GATEWAY_JWKS_URL` | the name set we are standardising on |
256
- | **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`) |
257
-
258
- > ⚠️ **Do NOT assume `GATEWAY_*` are "already live."** A `react+api` app
259
- > scaffolded by the platform is born with the **`CF_ACCESS_*` / `JWKS_URL`**
260
- > keys — the engine reuses the pre-gateway Cloudflare-Access names for the
261
- > gateway values. If your verifier reads **only** `GATEWAY_*`, those keys are
262
- > `undefined`, the `if (!jwksUrl || !issuer || !audience) return anonymous()`
263
- > guard fires, and **every** user silently goes anonymous: the gateway signs
264
- > you in, but your app renders its own "not signed in" screen. **This is the #1
265
- > cause of that symptom.** The verifier snippet above already reads both name
266
- > sets via `||` — keep the fallback and you are immune to the mismatch,
267
- > 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.
268
357
 
269
358
  > **This is the gateway, not Cloudflare Access.** Despite the name,
270
359
  > `CF_ACCESS_TEAM_DOMAIN` here holds the **gateway** issuer
@@ -275,7 +364,7 @@ how it was created:
275
364
  > `GATEWAY_AUD`, **not** `GATEWAY_AUDIENCE`; and ignore the illustrative
276
365
  > `AUTH_ISS` / `APP_AUD` names in older contract-doc snippets.)
277
366
 
278
- **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.**
279
368
 
280
369
  > ⚠️ **`secret_text` + same-deploy, or identity goes dark.** Plain-text env is
281
370
  > silently dropped by Cloudflare Pages under partial-PATCH, and env only binds
@@ -303,7 +392,11 @@ An unverified payload can be forged by anyone who can reach your origin
303
392
 
304
393
  ## Checklist before you ship
305
394
 
306
- - [ ] 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.
307
400
  - [ ] Reads `X-Launchpad-User-Assertion` and **verifies** with
308
401
  `verifyAccessJwt` (signature + issuer + **audience pinned to your host**).
309
402
  - [ ] **Fails closed** to anonymous on missing token, missing env, or any
@@ -311,10 +404,13 @@ An unverified payload can be forged by anyone who can reach your origin
311
404
  - [ ] No unsigned `decodeJwtPayload` on the auth path.
312
405
  - [ ] Verifier reads **both** name sets via `||` (`GATEWAY_ISSUER ||
313
406
  CF_ACCESS_TEAM_DOMAIN`, etc.) so it works whichever set your app carries.
314
- - [ ] Confirmed which env var **names** are actually live on your deployed
315
- project (`CF_ACCESS_*` on an engine-scaffolded react+api app, `GATEWAY_*`
316
- if you hand-set them), set as **`secret_text`**, shipped in the **same**
317
- 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.
318
414
  - [ ] `aud` is your **bare host** (`<slug>.launchpad.m-kopa.us`), no scheme/port.
319
415
  - [ ] No authorization decision is made from `/api/me` — attribution only.
320
416
 
@@ -323,6 +419,7 @@ An unverified payload can be forged by anyone who can reach your origin
323
419
  - Do **not** confuse `launchpad whoami` (your CLI session) with in-app
324
420
  identity. This skill is about the **end-user signed into your deployed
325
421
  app**, read server-side from the forwarded token.
422
+ - Do **not** read identity from `X-User-*` headers in a container unless `auth: gateway` or `auth: access` is set on the app; they are only trustworthy because the container Worker verified the token first.
326
423
  - Do **not** trust the header without verifying the signature, and do **not**
327
424
  omit the audience check — both open you to forgery / cross-app replay.
328
425
  - Do **not** gate access on `/api/me` claims — they are attribution, not
@@ -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.65.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.65.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.65.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) -->