@openparachute/app 0.2.0-rc.4

package/src/auth.ts

@@ -0,0 +1,212 @@
+/**
+ * Bearer-token auth for parachute-app's HTTP admin endpoints.
+ *
+ * Mirrors `parachute-runner/src/auth.ts` deliberately — same trust kernel
+ * (`@openparachute/scope-guard`), same hub-origin resolution, same shape for
+ * the 401/403 responses. The single difference is the audience: `aud === "app"`.
+ *
+ * Two scopes apps defines:
+ *   - `app:read`  — list UIs, read per-UI info. Read-only.
+ *   - `app:admin` — add / remove / reload UIs + DCR registration on add.
+ *
+ * Endpoints that stay unauthenticated:
+ *   - `/healthz`, `/app/healthz` (liveness, hub probes)
+ *   - `/.parachute/info`, `/.parachute/config/schema` (open module-protocol
+ *     surface — module identity + schema shape leak nothing)
+ *   - Per-UI bundle serving under `/app/<name>/*` (static assets; hub gates
+ *     these at the reverse-proxy layer per design doc section 9)
+ *   - `/app/<name>/oauth-client` (UIs need this at page load before they
+ *     have any token — public OAuth client_id is by definition public)
+ *
+ * Admin endpoints take `app:admin`. Read-only admin endpoints accept
+ * `app:admin` OR `app:read` per design doc section 13.
+ *
+ * Hub-origin resolution follows the same shape every other module uses:
+ *   - `PARACHUTE_HUB_ORIGIN` env var when set
+ *   - `config.hub_url` from `loadConfig()` as the daemon-config-aware override
+ *   - `http://127.0.0.1:1939` loopback fallback (v0.6 single-container)
+ *
+ * `getHubOrigin()` re-resolves on every call so tests can swap the env
+ * mid-run; production callers set the env once at boot.
+ */
+
+import { HubJwtError, type ScopeGuard, createScopeGuard } from "@openparachute/scope-guard";
+
+export const SCOPE_ADMIN = "app:admin" as const;
+export const SCOPE_READ = "app:read" as const;
+
+/** Hub loopback for v0.6 single-container; deploys override via env. */
+const DEFAULT_HUB_LOOPBACK = "http://127.0.0.1:1939";
+
+/** Audience the daemon declares — hub#300 mints with `aud: "app"` for our endpoints. */
+export const AUDIENCE = "app" as const;
+
+/**
+ * Resolve the hub origin used for JWT validation.
+ *
+ * Honors `PARACHUTE_HUB_ORIGIN` first (the canonical override every committed-
+ * core module respects), then `hubUrl` (the runtime config field), then falls
+ * back to the loopback. `hubUrl` is the same string `config.hub_url` carries —
+ * callers in `http-server.ts` pass `state.config.hub_url` so a runtime config
+ * change (Phase 1.3 admin SPA toggles) takes effect without a daemon restart.
+ */
+export function getHubOrigin(hubUrl?: string): string {
+  const env = process.env.PARACHUTE_HUB_ORIGIN?.replace(/\/$/, "");
+  if (env && env.length > 0) return env;
+  if (hubUrl && hubUrl.length > 0) return hubUrl.replace(/\/$/, "");
+  return DEFAULT_HUB_LOOPBACK;
+}
+
+let guard: ScopeGuard | null = null;
+let guardHubOrigin: string | null = null;
+
+/**
+ * Lazy process-wide guard. The resolver form lets tests flip
+ * `PARACHUTE_HUB_ORIGIN` between cases without restarting the harness; the
+ * lib re-resolves on every `validateHubJwt` call. JWKS + revocation caches
+ * live inside the guard and survive across requests in production.
+ *
+ * If `hubUrl` is supplied and differs from the cached guard's origin, the
+ * cached guard is replaced — daemon-config writes can change `hub_url` at
+ * runtime and we want subsequent validations to track the new origin.
+ */
+function getGuard(hubUrl?: string): ScopeGuard {
+  const wanted = getHubOrigin(hubUrl);
+  if (!guard || guardHubOrigin !== wanted) {
+    guard = createScopeGuard({ hubOrigin: () => wanted });
+    guardHubOrigin = wanted;
+  }
+  return guard;
+}
+
+/**
+ * Test seam: forget the cached guard so a beforeEach that swaps the
+ * `PARACHUTE_HUB_ORIGIN` env var picks up the new origin on the next call.
+ */
+export function resetGuard(): void {
+  if (guard) {
+    guard.resetJwksCache();
+    guard.resetRevocationCache();
+  }
+  guard = null;
+  guardHubOrigin = null;
+}
+
+export function extractBearer(authHeader: string | null | undefined): string | undefined {
+  if (!authHeader) return undefined;
+  const m = authHeader.match(/^Bearer\s+(.+)$/i);
+  return m?.[1]?.trim() || undefined;
+}
+
+export type AuthResult =
+  | { ok: true; scopes: readonly string[] }
+  | { ok: false; status: 401 | 403; body: { error: string; message: string } };
+
+/**
+ * Validate the presented bearer against the hub. Returns the granted scope
+ * list on success; on failure returns a typed 401 or 403 the caller forwards
+ * verbatim.
+ *
+ * `aud === "app"` enforced via `expectedAudience` — a token minted for a
+ * different module can't reach our admin surface even if its bearer carries
+ * `app:admin` (which it can't, but defense-in-depth).
+ */
+export async function validateBearer(
+  token: string | undefined,
+  opts: { hubUrl?: string } = {},
+): Promise<AuthResult> {
+  if (!token) {
+    return {
+      ok: false,
+      status: 401,
+      body: { error: "unauthorized", message: "Authorization: Bearer <token> required" },
+    };
+  }
+  try {
+    const claims = await getGuard(opts.hubUrl).validateHubJwt(token, {
+      expectedAudience: AUDIENCE,
+    });
+    return { ok: true, scopes: claims.scopes };
+  } catch (err) {
+    if (err instanceof HubJwtError && err.code === "revoked") {
+      console.warn(`[app-auth] hub JWT rejected: ${err.message}`);
+      return {
+        ok: false,
+        status: 401,
+        body: { error: "unauthorized", message: "token has been revoked" },
+      };
+    }
+    if (err instanceof HubJwtError && err.code === "revocation_unavailable") {
+      console.warn(`[app-auth] hub JWT rejected: ${err.message}`);
+      return {
+        ok: false,
+        status: 401,
+        body: {
+          error: "unauthorized",
+          message: "token cannot be validated: revocation list unavailable",
+        },
+      };
+    }
+    const message =
+      err instanceof HubJwtError
+        ? err.message
+        : err instanceof Error
+          ? err.message
+          : "JWT validation failed";
+    return {
+      ok: false,
+      status: 401,
+      body: { error: "unauthorized", message },
+    };
+  }
+}
+
+/** Exact-match scope check. Non-vault scopes don't inherit per oauth-scopes.md. */
+export function hasScope(granted: readonly string[], required: string): boolean {
+  return granted.includes(required);
+}
+
+/**
+ * Pass-through scope check that treats `app:admin` as implying `app:read`.
+ * Read-only admin endpoints (GET /app/list, GET /app/<name>/info) accept
+ * either scope; admin endpoints (add/remove/reload) require `app:admin`
+ * exactly.
+ */
+export function hasReadAccess(granted: readonly string[]): boolean {
+  return granted.includes(SCOPE_READ) || granted.includes(SCOPE_ADMIN);
+}
+
+/**
+ * Resolve auth + scope. Returns either a Response to forward (401/403) or
+ * the granted scopes for the caller to use in finer-grained checks.
+ *
+ * `requiredScope` is one of:
+ *   - `app:admin` — exact match required
+ *   - `app:read`  — accepts `app:read` OR `app:admin` (admin implies read)
+ */
+export async function enforceScope(
+  req: Request,
+  requiredScope: typeof SCOPE_ADMIN | typeof SCOPE_READ,
+  opts: { hubUrl?: string } = {},
+): Promise<Response | { scopes: readonly string[] }> {
+  const token = extractBearer(req.headers.get("authorization"));
+  const result = await validateBearer(token, opts);
+  if (!result.ok) {
+    return Response.json(result.body, { status: result.status });
+  }
+  const granted = result.scopes;
+  const ok = requiredScope === SCOPE_READ ? hasReadAccess(granted) : hasScope(granted, SCOPE_ADMIN);
+  if (!ok) {
+    return Response.json(
+      {
+        error: "Forbidden",
+        error_type: "insufficient_scope",
+        message: `This endpoint requires the '${requiredScope}' scope.`,
+        required_scope: requiredScope,
+        granted_scopes: granted,
+      },
+      { status: 403 },
+    );
+  }
+  return { scopes: granted };
+}

package/src/bootstrap.ts

@@ -0,0 +1,153 @@
+/**
+ * First-boot default-app bootstrap — Phase 2.1.
+ *
+ * On `parachute-app serve` startup, when `$PARACHUTE_HOME/app/uis/` is
+ * empty and `config.bootstrap_default_apps.enabled` is true, apps
+ * auto-installs each entry in `config.bootstrap_default_apps.apps` via
+ * the same npm-fetch pipeline `parachute-app add` uses.
+ *
+ * Friend-deploy story: spin up a hub + run `parachute-app serve`, and
+ * Notes is there waiting — no manual `add` step. The operator can
+ * always disable this by flipping `bootstrap_default_apps.enabled =
+ * false` or setting `apps: []`.
+ *
+ * Design rationale (design doc Section 16): Notes is the canonical
+ * first app installed under parachute-app. The bootstrap registry is
+ * the implementation of "Notes ships with app." Future committed-core
+ * apps may join the default list; today it's just notes-ui.
+ *
+ * Failure mode: if npm-fetch fails (network down, package not on
+ * registry, registry timeout), log a warning and continue. The
+ * operator can run `parachute-app add @openparachute/notes-ui` later
+ * to retry. We never block daemon startup on the bootstrap — the
+ * daemon's primary job is hosting whatever's in `uis/` already (which,
+ * in the empty case, is "nothing"), and a failed bootstrap is just
+ * "nothing got added."
+ */
+
+import { readdirSync, statSync } from "node:fs";
+
+import type { AppConfig } from "./config.ts";
+import type { NpmSpawnFn, fetchNpmPackage } from "./npm-fetch.ts";
+
+/**
+ * Minimal `add` surface bootstrap needs. The full admin handler does
+ * staging + meta-merge + DCR + state-swap + services.json refresh;
+ * bootstrap reuses that same flow by passing a callback that performs
+ * the equivalent (in practice, the caller in `index.ts` adapts the
+ * admin handler so bootstrap stays decoupled from admin-routes.ts's
+ * `AppState` mutation pattern).
+ */
+export type BootstrapAddFn = (source: string) => Promise<{ name: string; path: string }>;
+
+export type BootstrapOpts = {
+  config: AppConfig;
+  /** Resolved uis dir; allows tests to inject a tempdir. */
+  uisDir: string;
+  /** The npm-fetch entry-point — overridable for tests. */
+  npmFetch?: typeof fetchNpmPackage;
+  /** The `add` callback — orchestrator wires this to admin-routes' add path. */
+  add: BootstrapAddFn;
+  /** Logger override; default console. */
+  logger?: Pick<Console, "log" | "warn" | "error">;
+  /** npm-spawn override (tests). Passed to `npmFetch`. */
+  npmSpawnFn?: NpmSpawnFn;
+};
+
+export type BootstrapResult = {
+  /** npm specs of packages successfully added. */
+  bootstrapped: string[];
+  /** npm specs skipped (per-spec reason). */
+  skipped: Array<{ pkg: string; reason: string }>;
+  /** npm specs that failed (per-spec error). */
+  failed: Array<{ pkg: string; error: string }>;
+  /** Why the whole pass was skipped, if it was (else undefined). */
+  skipReason?: string;
+};
+
+/**
+ * Inspect `uisDir` + `config`, then maybe run bootstrap. Returns a
+ * summary the caller (`serve()` in index.ts) logs.
+ *
+ * Skip conditions (any one triggers an early return):
+ *   - `config.bootstrap_default_apps.enabled === false`
+ *   - `config.bootstrap_default_apps.apps` is empty
+ *   - `uisDir` exists AND contains at least one entry (we don't touch
+ *     installs the operator already manages)
+ *
+ * When none of the skip conditions fire: iterate `apps` and call
+ * `add(spec)` for each. Each call is independent — a failure on one
+ * doesn't stop the rest.
+ */
+export async function maybeBootstrapDefaultApps(opts: BootstrapOpts): Promise<BootstrapResult> {
+  const logger = opts.logger ?? console;
+  const result: BootstrapResult = {
+    bootstrapped: [],
+    skipped: [],
+    failed: [],
+  };
+
+  if (!opts.config.bootstrap_default_apps.enabled) {
+    result.skipReason = "config.bootstrap_default_apps.enabled is false";
+    return result;
+  }
+  if (opts.config.bootstrap_default_apps.apps.length === 0) {
+    result.skipReason = "config.bootstrap_default_apps.apps is empty";
+    return result;
+  }
+
+  if (uisDirHasEntries(opts.uisDir)) {
+    result.skipReason = "uisDir is non-empty (existing operator install)";
+    return result;
+  }
+
+  for (const spec of opts.config.bootstrap_default_apps.apps) {
+    try {
+      const added = await opts.add(spec);
+      result.bootstrapped.push(spec);
+      logger.log(`[app] bootstrap: installed ${spec} as ${added.name} at ${added.path}`);
+    } catch (e) {
+      const msg = (e as Error).message ?? String(e);
+      result.failed.push({ pkg: spec, error: msg });
+      logger.warn(`[app] bootstrap: failed to install ${spec}: ${msg}`);
+    }
+  }
+
+  if (result.bootstrapped.length > 0) {
+    logger.log(
+      `[app] bootstrap: installed ${result.bootstrapped.length} default app(s) — ${result.bootstrapped.join(", ")}`,
+    );
+  }
+  return result;
+}
+
+/**
+ * Predicate: does `uisDir` exist + contain at least one entry that
+ * looks like a UI install candidate? A pure missing-directory or a
+ * directory containing only hidden files (e.g. `.DS_Store`) counts as
+ * "empty" — operators don't deliberately seed UIs as dotfile dirs.
+ *
+ * We deliberately accept "exists + has at least one non-dotfile
+ * entry" — even an entry that doesn't pass `scanUis` (broken meta,
+ * missing dist/) signals "operator was here," and bootstrap shouldn't
+ * trample.
+ */
+function uisDirHasEntries(uisDir: string): boolean {
+  try {
+    const st = statSync(uisDir);
+    if (!st.isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  let entries: string[];
+  try {
+    entries = readdirSync(uisDir);
+  } catch {
+    return false;
+  }
+  for (const e of entries) {
+    if (e.startsWith(".")) continue;
+    return true;
+  }
+  return false;
+}

package/src/cache-headers.ts

@@ -0,0 +1,106 @@
+/**
+ * Smart cache headers per design doc section 18.
+ *
+ * The intent: solve [parachute-notes#151](https://github.com/ParachuteComputer/parachute-notes/issues/151)
+ * at the platform level so future apps inherit a clean default. The rules:
+ *
+ *   - `index.html` (SPA entrypoints): `no-cache, no-store, must-revalidate`.
+ *     Always-fresh; this is the document that points at the hashed assets.
+ *   - Content-hashed assets (Vite/Webpack/esbuild/Parcel default convention,
+ *     e.g. `app.a3b9f2.js`, `style.7e1c8d.css`): `public, max-age=31536000,
+ *     immutable`. Cache forever — the filename changes on rebuild.
+ *   - Non-hashed assets: `public, max-age=3600`. Sensible default.
+ *   - PWA service worker (when `meta.pwa === true` and `filename` matches
+ *     `meta.pwa_service_worker`): `no-cache`. SW updates need to propagate
+ *     immediately on rebuild.
+ *
+ * The hash detector is conservative: require ≥8 hex characters in the
+ * second-to-last dot-separated segment. This matches Vite/Webpack output
+ * (`app.a3b9f2c1.js`) without false-positiving on filenames like
+ * `vendor-1234.js` or `image-2024.png`. We deliberately reject 6-7 char
+ * hashes — Vite + Webpack both default to ≥8 — to keep the false-positive
+ * rate low.
+ */
+
+import type { UiMeta } from "./meta-schema.ts";
+
+/**
+ * Regex testing whether a filename looks content-hashed. Examples that pass:
+ *   - `app.a3b9f2c1.js`
+ *   - `vendor.7e1c8d.chunk.js`         (hash is in the middle)
+ *   - `style.deadbeef12345.css`
+ *
+ * Examples that don't pass (caching at the 1-hour default):
+ *   - `index.html` (handled separately)
+ *   - `app.js`
+ *   - `app-2024.js` (no hex run that long; "2024" is 4 chars)
+ *   - `vendor-1234.js`
+ *   - `app-20240101.js` (date stamp — 8 digits but pure-decimal, no a-f)
+ *   - `icon.svg`
+ *
+ * The match looks for a dot-separated segment of ≥8 hex chars anywhere in
+ * the filename, AND requires at least one a-f character in that segment.
+ * The lookahead `(?=[a-f0-9]*[a-f])` is the load-bearing line: it filters
+ * out pure-digit runs (date stamps like `20240101`) that would otherwise
+ * masquerade as hex hashes. Vite/Webpack hashes are random hex so they
+ * almost always contain at least one letter — and on the rare run that
+ * doesn't, the 1-hour fallback is harmless. False-positive avoidance wins.
+ */
+const HASHED_ASSET_REGEX = /(^|[.\-_])(?=[a-f0-9]*[a-f])[a-f0-9]{8,}(\.|$)/;
+
+/**
+ * Type signature exposed by section 5 of the brief — explicit per-asset
+ * shape for use anywhere we need to set headers. `filename` is the basename
+ * (e.g. `app.a3b9f2.js`) — pass the full URL path's basename, not the
+ * absolute filesystem path.
+ *
+ * `meta` is optional so caller can elide it for the `/.parachute/*` admin
+ * endpoints; those skip the PWA-aware branch.
+ *
+ * `devMode` (Phase 1.3) overrides every other branch with
+ * `no-cache, no-store, must-revalidate`. When the operator runs
+ * `parachute-app dev <name>` we want zero caching from any layer — index,
+ * hashed assets, SW, the lot. The smart-cache rules below are silent
+ * during dev iteration.
+ */
+export function cacheHeadersFor(
+  filename: string,
+  meta?: UiMeta,
+  devMode = false,
+): Record<string, string> {
+  // Dev mode trumps every other branch — no caching anywhere. Even
+  // content-hashed assets get no-cache so an operator who manually
+  // edits a hashed bundle (e.g. swapped from disk) sees the change
+  // without reasoning about the filename.
+  if (devMode) {
+    return { "Cache-Control": "no-cache, no-store, must-revalidate" };
+  }
+
+  // PWA service worker — always no-cache so updates propagate immediately
+  // on rebuild. The SW path is meta-driven so each UI controls its own.
+  if (meta?.pwa && meta.pwa_service_worker && filename === meta.pwa_service_worker) {
+    return { "Cache-Control": "no-cache" };
+  }
+
+  // index.html: always-fresh.
+  if (filename === "index.html") {
+    return { "Cache-Control": "no-cache, no-store, must-revalidate" };
+  }
+
+  // Content-hashed: cache forever.
+  if (HASHED_ASSET_REGEX.test(filename)) {
+    return { "Cache-Control": "public, max-age=31536000, immutable" };
+  }
+
+  // Non-hashed assets: 1-hour default.
+  return { "Cache-Control": "public, max-age=3600" };
+}
+
+/**
+ * Convenience predicate exposed for tests. Returns true when `filename`
+ * matches the hash-in-filename convention (used to confirm the regex stays
+ * tight as we extend it).
+ */
+export function looksContentHashed(filename: string): boolean {
+  return HASHED_ASSET_REGEX.test(filename);
+}