@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.
- package/CHANGELOG.md +10 -0
- package/dist/bundle/upload.d.ts +4 -0
- package/dist/bundle/upload.d.ts.map +1 -1
- package/dist/cli.js +269 -66
- package/dist/commands/deploy.d.ts +15 -4
- package/dist/commands/deploy.d.ts.map +1 -1
- package/dist/commands/migrate.d.ts +15 -0
- package/dist/commands/migrate.d.ts.map +1 -1
- package/dist/commands/status.d.ts +14 -0
- package/dist/commands/status.d.ts.map +1 -1
- package/dist/manifest/migrate-dispatch.d.ts +7 -3
- package/dist/manifest/migrate-dispatch.d.ts.map +1 -1
- package/dist/manifest/wrangler-config.d.ts +9 -2
- package/dist/manifest/wrangler-config.d.ts.map +1 -1
- package/dist/version.d.ts +1 -1
- package/package.json +1 -1
- package/skills/launchpad-content-pr/SKILL.md +130 -50
- package/skills/launchpad-deploy/SKILL.md +7 -4
- package/skills/launchpad-deploy-status/SKILL.md +1 -1
- package/skills/launchpad-destroy/SKILL.md +1 -1
- package/skills/launchpad-identity/SKILL.md +125 -39
- package/skills/launchpad-onboard/SKILL.md +3 -2
- package/skills/launchpad-report/SKILL.md +1 -1
- package/skills/launchpad-status/SKILL.md +1 -1
|
@@ -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
|
|
4
|
-
version: 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
|
|
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
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
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)
|
|
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
|
|
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
|
|
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`
|
|
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
|
|
303
|
+
### (b) `react+api` / any app with a build - import the package
|
|
234
304
|
|
|
235
|
-
|
|
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
|
|
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**.
|
|
249
|
-
|
|
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**
|
|
267
|
-
|
|
268
|
-
> ⚠️ **Do NOT assume `GATEWAY_*` are "already live
|
|
269
|
-
> scaffolded
|
|
270
|
-
>
|
|
271
|
-
>
|
|
272
|
-
>
|
|
273
|
-
>
|
|
274
|
-
>
|
|
275
|
-
>
|
|
276
|
-
>
|
|
277
|
-
>
|
|
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
|
-
**
|
|
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
|
|
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
|
-
- [ ]
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
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.
|
|
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`;
|
|
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.
|
|
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.
|
|
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) -->
|