@mutmutco/installer-launcher 0.1.0

package/README.md

@@ -0,0 +1,187 @@
+# launcher — single-executable installer for one product
+
+A small Node **>= 22**, **ESM**, **TypeScript + vitest** single-executable-application (SEA)
+launcher. One copy ships per product: the binary bakes a `product.json` asset, signs in the
+user, fetches the gated release payload, verifies its Ed25519 signature, and unpacks it under
+the product dir. Zero runtime dependencies — `node:` builtins only (`fetch` is global in
+Node 22). Dev dependencies: `typescript`, `vitest`, `@types/node`, `esbuild` (mirrors `cli/`).
+
+Reference: the google loopback PKCE flow is lifted from MM-Strategy's
+`src/cli/login.ts` (read-only reference) — same four steps (loopback listener, dynamic client
+registration, PKCE + browser, code exchange), adapted to the launcher's token store.
+
+## Commands
+
+```
+launcher login [--config <path>] [--dir <path>]    sign in (the ONLY command that opens a browser)
+launcher logout                                     wipe tokens AND payload
+launcher install                                    login if no token -> fetch+verify+unpack -> print next step
+launcher update                                     same fetch, re-checks manifest; no-op when current
+launcher doctor                                     config, token presence/expiry, payload version, paths
+launcher --run <file> [args…]                       run a payload ESM file with the launcher's own runtime
+launcher --version
+```
+
+`--run <file> [args…]` runs a payload file with the launcher's OWN embedded runtime — no Node on
+the machine. `<file>` resolves against the cwd and is loaded with `import()`; the file sees
+`process.argv = [execPath, <abs file>, ...args]` and its `process.exitCode` is propagated. A
+missing file prints one sentence on stderr and exits 1. `--run` never loads the product config and
+never reads the token store, so it works with no config and no login. The file must be
+**self-contained ESM**: bundled, with no `node_modules` resolution across the SEA boundary and no
+`require()` of anything that is not a `node:` builtin.
+
+`--config <path>` / `LAUNCHER_CONFIG` selects the product config; `--dir <path>` /
+`LAUNCHER_DIR` overrides the product dir. Flags work before or after the command.
+
+Only `login` (and the login half of `install`) opens a browser:
+
+- **github**: prints the `user_code` + `verification_uri` and opens the browser
+  (`verification_uri_complete` when the server sends one). Polls the device token endpoint per
+  `interval`; on `slow_down` adds 5s. Set `LAUNCHER_NO_OPEN=1` to print only (CI/tests).
+- **google**: loopback `127.0.0.1` redirect with PKCE; the browser opens automatically.
+
+The product dir defaults to `~/.<product>/` on mac/linux and `%LOCALAPPDATA%\<product>` on
+Windows, and holds `tokens.json` (0600), `state.json`, and `payload/`.
+
+## Config
+
+`config/product.template.json` per product:
+
+```json
+{
+  "product": "example-product",
+  "host": "https://gate.example.com",
+  "loginKind": "github",
+  "githubClientId": "EXAMPLE_CLIENT_ID",
+  "publicKey": "<base64 of the RAW 32-byte Ed25519 public key>",
+  "binName": "example-product"
+}
+```
+
+`loginKind` is `"github"` or `"google"`; `githubClientId` is required for the github kind.
+`publicKey` is the base64 of the raw 32-byte Ed25519 key the manifest signature verifies
+against. No secrets are committed — the client id and public key are public; the client
+secret (github) lives only on the gate server.
+
+## Build
+
+```sh
+npm install
+npm run build            # node build.mjs -> dist/launcher.js + dist/launcher.sea.cjs (+ dist/product.json staging)
+npm run typecheck        # tsc --noEmit
+npm test                 # vitest run (builds dist/ first for the integration test)
+node build.mjs --product-config ./config/my-product.json   # stage a real product asset
+node build.mjs --sea     # also stamp the SEA single-executable (needs postject)
+```
+
+Two bundles ship from one source: `dist/launcher.js` is **ESM** (run by `node` in dev and by the
+integration tests) and `dist/launcher.sea.cjs` is **CommonJS**, baked as the SEA main (see below).
+
+## How it meets the contract (wire contract v1)
+
+- **Device flow (github)**: `POST {host}/gate/device/code` body `{client_id}` ->
+  `200 {device_code, user_code, verification_uri, verification_uri_complete?, expires_in,
+  interval}`; `POST {host}/gate/device/token` body `{client_id, device_code}` ->
+  `200 {access_token, refresh_token, expires_in}` or `400 {error:
+  authorization_pending|slow_down|expired_token|denied}`. Implemented byte-identically in
+  `src/login-github.ts`.
+- **Refresh**: `POST {host}/gate/refresh` body `{refresh_token}` ->
+  `200 {access_token, expires_in}` or `403 {error}`. Every start refreshes the access token
+  before expiry (within 60s); token TTL is `<= 3600s`.
+- **Gated reads**: `Authorization: Bearer <access_token>` on `GET {host}/release/manifest`
+  (`200 {version, created, files: [{path, sha256, size}], signature}`) and
+  `GET {host}/release/<path>` (raw bytes, `404 {error}` when absent).
+- **Manifest signature**: base64 detached Ed25519 over exactly the UTF-8 bytes of canonical
+  JSON `{"created":…,"files":[{"path":…,"sha256":…,"size":…}],"version":…}` (keys sorted, no
+  whitespace; `created` used raw, never reformatted). Verified with the baked public key
+  BEFORE writing anything, through the ported `src/canonical.ts` (verbatim from
+  `installer/gate/src/canonical.ts`: UTF-16 code-unit key sort, arrays keep order, `undefined`
+  members dropped, non-finite numbers throw, strings `JSON.stringify`-escaped).
+- **Refusals**: `401 {error:"unauthorized"}` -> re-login (stored refresh is retried first,
+  then a fresh login); `403 {error:"forbidden"}` -> revoked/allowlist-miss, stops with the
+  plain sentence "this install is not allowed for your account — access was revoked or never
+  granted." The access token is opaque (server-side HMAC) — stored and relayed, never parsed.
+- **google loginKind**: no `/gate/device/*` endpoints; the loopback PKCE flow
+  (`src/login-google.ts`) yields the bearer directly, then the same `/release` reads apply.
+- **Behaviors**: `install` = login if no token -> fetch+verify+unpack under the product dir
+  (download to a temp staging dir, verify every size + SHA-256, then swap into `payload/`) ->
+  print next step; `update` = same fetch, re-checks manifest; `doctor` = config, token
+  presence/expiry, payload version, path wiring; `logout` = wipe tokens AND payload.
+
+## The last mile (`payload.json.entry`) and `$self`
+
+`install` ends by reading the payload's `payload.json` `entry` and running it with cwd on the
+payload dir (relative paths, no home-dir quoting hazard). `entry` is either a whitespace-separated
+string or a string array. Its first element may be the token **`$self`**, replaced at run time by
+`process.execPath` — the launcher binary itself. A product that must not require Node on the
+machine therefore declares:
+
+```json
+{ "entry": ["$self", "--run", "dist/index.mjs", "install", "--from-payload"] }
+```
+
+the launcher's embedded runtime then runs the payload's bundled ESM. Everything else in
+`defaultRunEntry` is unchanged: when the command cannot run (spawn error, non-zero exit) the
+launcher prints the exact command instead and still exits `0` (the command shown is the `$self`
+entry already resolved).
+
+## SEA: `import()` and the embedded runtime
+
+`launcher --run` relies on Node's dynamic `import()` of an on-disk ESM file inside the SEA binary.
+Proven locally on **Node v24.20.0** with `postject`:
+
+- A Node 22/24 SEA **main script is always CommonJS**: `mainFormat` exists only in Node >= 25.5,
+  and injecting the ESM `dist/launcher.js` as the main fails with
+  `SyntaxError: Cannot use import statement outside a module`. `build.mjs` therefore also bundles a
+  **CommonJS** `dist/launcher.sea.cjs` (target `esnext`) and bakes THAT as the SEA main;
+  `src/module-url.ts` bridges `__filename` (CJS) and `import.meta.url` (ESM).
+- `import()` of an on-disk `.mjs` from a **CommonJS** SEA main works: the probe imported the file,
+  the file saw `argv = [execPath, file, ...args]`, and the process exited with the file's code.
+- Node documents "`import()` does not work when `useCodeCache` is true", so the generated sea
+  config sets `useCodeCache: false`. (On 24.20 the probe also passed with it `true`; the flag stays
+  `false` so the feature never leans on that caveat.)
+- The postject sentinel fuse is a hash **embedded in the Node binary that changes between
+  releases** (24.20 carries `NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2`; older docs cited
+  `NODE_SEA_FUSE_fce680ab2cc467b6e840016ee2343c1a`). `build.mjs` reads it out of `process.execPath`
+  instead of hardcoding it.
+- `disableExperimentalSEAWarning` stays `true`.
+
+The reusable workflow `.github/workflows/launcher-build.yml` smoke-tests this end to end: after
+`--version` it runs `--run test/fixtures/run-hello.mjs a b` against the stamped binary and asserts
+the fixture's stdout.
+
+## Tests
+
+- Unit: `test/canonical.test.ts` (canonicalization + Ed25519 verify with a
+  `generateKeyPairSync('ed25519')` keypair), `test/flows.test.ts` (device-flow polling/backoff,
+  refresh, unpack to temp dir, refusal paths), `test/store-google.test.ts` (token store +
+  google loopback PKCE against a fake OAuth server), `test/last-mile.test.ts` (the `payload.json`
+  entry, the `$self` token, the manual-command fallback, and `--run` argv/exit-code/missing-file).
+- Integration: `test/integration.test.ts` runs the **built `dist/launcher.js`** through a full
+  `install -> doctor -> update -> logout` cycle against a localhost fake gate + release server
+  (device polling, refresh, signature verification, 403 revocation, payload swap) and spawns
+  `--run test/fixtures/run-hello.mjs a b` for a real stdout + exit-code assertion.
+
+## Release CI (SEA binary)
+
+`node build.mjs --sea` follows the Node SEA docs exactly:
+
+1. esbuild bundles `dist/launcher.js` (ESM, for `node`) **and** `dist/launcher.sea.cjs`
+   (CommonJS, the SEA main — Node 22/24 SEA main scripts are CommonJS-only);
+2. a `dist/sea-config.generated.json` is written with the baked `product.json` asset,
+   `useCodeCache: false` (the `import()` last mile), and `main` = `dist/launcher.sea.cjs`;
+3. `node --experimental-sea-config <generated>` produces `dist/sea-prep.blob`;
+4. `process.execPath` is copied to `dist/<platform>-<arch>` and stamped with
+   `postject <binary> NODE_SEA_BLOB <blob> --sentinel-fuse <fuse read from the Node binary>`.
+   The name is the EXACT download name the bootstrap scripts request
+   (`/dl/<product>/<platform>-<arch>`, platform `darwin|win`, arch `arm64|x64`; `win32` maps to `win`,
+   and there is no `.exe` suffix — `install.ps1` downloads `win-x64` and renames it to `<product>.exe`).
+
+The SEA binary must be stamped on a native runner for its target OS/architecture — the Node SEA
+blob embeds the host Node binary, so a macOS arm64 binary cannot be produced on Linux. The reusable
+workflow `.github/workflows/launcher-build.yml` implements exactly the steps above on the three
+supported lanes (`macos-14` arm64, `macos-13` x64, `windows-latest` x64): `npm ci`, install
+`postject`, `node build.mjs --product-config <cfg> --sea`, smoke `--version` then
+`--run test/fixtures/run-hello.mjs a b`, write the `.sha256`,
+and upload `launcher-<product>-<platform>-<arch>`. It is callable (`workflow_call`) and dispatchable,
+and it is the only supported path to a real SEA binary — nothing is faked in this lane.

package/config/product.template.json

@@ -0,0 +1,9 @@
+{
+  "$comment": "Copy to dist/product.json (via build.mjs --product-config) and edit per product. publicKey is the base64 of the RAW 32-byte Ed25519 public key.",
+  "product": "example-product",
+  "host": "https://gate.example.com",
+  "loginKind": "github",
+  "githubClientId": "EXAMPLE_CLIENT_ID",
+  "publicKey": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
+  "binName": "example-product"
+}