@openparachute/hub 0.5.0 → 0.5.2

package/src/hub-server.ts

@@ -147,40 +147,39 @@ export function findVaultUpstream(
 }
 
 /**
- * Reverse-proxy a `/vault/<name>/*` request onto the vault backend's loopback
- * port. The path is preserved end-to-end (vault since paraclaw#18 expects
- * requests at `/vault/<name>/...` not stripped to `/...`), so the upstream URL
- * mirrors the incoming pathname exactly.
+ * Forward a request to a loopback service on `127.0.0.1:<port>`. By default
+ * the incoming pathname + query are preserved verbatim; pass `targetPath` to
+ * rewrite the path (e.g. when the caller has stripped a mount prefix because
+ * the backend serves bare routes). Query string is always preserved from the
+ * incoming URL.
  *
- * `manifestPath` is the services.json path from `HubFetchDeps`. Read on every
- * proxied request so a vault created seconds ago is reachable without a
- * re-expose — same dynamism as the well-known doc (#135).
+ * Note: this is **not** equivalent to the tailscale convention. `tailscale
+ * serve <mount>=<target>` strips the mount before forwarding, so
+ * `serviceProxyTarget` in `commands/expose.ts` works by making mount and
+ * target byte-equal. The hub's fetch-based proxy does no stripping unless the
+ * caller asks; per-service preferences vary (scribe wants bare paths, notes
+ * / agent / vault want the prefix), so the decision lives one layer up in
+ * `proxyToService` / `proxyToVault`.
  *
- * Returns `undefined` when no vault is currently mounted at this pathname so
- * the caller falls through to the catch-all 404. Returns a 502 response when
- * the upstream connection fails (vault crashed, port shifted) — the upstream
- * URL was valid; we just couldn't reach it.
+ * Returns 502 when the loopback fetch fails — port valid, target unreachable
+ * (service crashed, port shifted, mid-restart). `serviceLabel` is folded into
+ * the error message so 502 bodies say `vault upstream unreachable` /
+ * `scribe upstream unreachable` etc.
  *
  * Hop-by-hop notes: WebSocket upgrades and HTTP/2 trailers don't traverse
- * fetch-based proxies cleanly. Vault uses neither today; if a future service
- * needs them, switch to a Node http.IncomingMessage / http.request pair.
+ * fetch-based proxies cleanly. No on-box service uses either today; if one
+ * eventually needs them, switch to a Node http.IncomingMessage / http.request
+ * pair.
  */
-async function proxyToVault(req: Request, manifestPath: string): Promise<Response | undefined> {
-  let services: readonly ServiceEntry[];
-  try {
-    services = readManifest(manifestPath).services;
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return new Response(JSON.stringify({ error: `vault routing failed: ${msg}` }), {
-      status: 500,
-      headers: { "content-type": "application/json" },
-    });
-  }
+async function proxyRequest(
+  req: Request,
+  port: number,
+  serviceLabel: string,
+  targetPath?: string,
+): Promise<Response> {
   const url = new URL(req.url);
-  const match = findVaultUpstream(services, url.pathname);
-  if (!match) return undefined;
-
-  const upstream = `http://127.0.0.1:${match.port}${url.pathname}${url.search}`;
+  const path = targetPath ?? url.pathname;
+  const upstream = `http://127.0.0.1:${port}${path}${url.search}`;
   const headers = new Headers(req.headers);
   // Host comes from the requester (tailnet FQDN); the loopback target wants
   // its own. Bun's fetch fills it in when omitted.
@@ -199,13 +198,104 @@ async function proxyToVault(req: Request, manifestPath: string): Promise<Respons
     return await fetch(upstream, init);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    return new Response(JSON.stringify({ error: `vault upstream unreachable: ${msg}` }), {
+    return new Response(JSON.stringify({ error: `${serviceLabel} upstream unreachable: ${msg}` }), {
       status: 502,
       headers: { "content-type": "application/json" },
     });
   }
 }
 
+/**
+ * Reverse-proxy a `/vault/<name>/*` request onto the vault backend.
+ * `manifestPath` is the services.json path from `HubFetchDeps`. Read on every
+ * proxied request so a vault created seconds ago is reachable without a
+ * re-expose — same dynamism as the well-known doc (#135).
+ *
+ * Returns `undefined` when no vault claims this pathname so the caller can
+ * fall through to the SPA shell fallback for unknown vault names (the seam
+ * #173 introduced).
+ */
+async function proxyToVault(req: Request, manifestPath: string): Promise<Response | undefined> {
+  let services: readonly ServiceEntry[];
+  try {
+    services = readManifest(manifestPath).services;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return new Response(JSON.stringify({ error: `vault routing failed: ${msg}` }), {
+      status: 500,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  const url = new URL(req.url);
+  const match = findVaultUpstream(services, url.pathname);
+  if (!match) return undefined;
+  return proxyRequest(req, match.port, "vault");
+}
+
+/**
+ * Resolve which (non-vault) ServiceEntry should handle a given request.
+ * Generic longest-prefix match across every service's `paths[]`. Vault
+ * entries are filtered out — they're routed by `findVaultUpstream` /
+ * `proxyToVault`, which encode the vault-specific SPA-fallback seam.
+ *
+ * Returns `undefined` when no service claims the pathname; the caller 404s.
+ */
+export function findServiceUpstream(
+  services: readonly ServiceEntry[],
+  pathname: string,
+): { port: number; mount: string; entry: ServiceEntry } | undefined {
+  let best: { port: number; mount: string; entry: ServiceEntry } | undefined;
+  for (const s of services) {
+    if (isVaultEntry(s)) continue;
+    for (const path of s.paths) {
+      if (pathname === path || pathname.startsWith(`${path}/`)) {
+        if (!best || path.length > best.mount.length) {
+          best = { port: s.port, mount: path, entry: s };
+        }
+      }
+    }
+  }
+  return best;
+}
+
+/**
+ * Reverse-proxy a request onto whichever non-vault service registers a
+ * matching `paths[]` prefix in services.json. Wired after every specific
+ * handler in `hubFetch` so the exclusion list (`/`, `/admin/*`, `/oauth/*`,
+ * `/.well-known/*`, `/hub/*`, `/vault/*`, `/api/*`) is enforced by ordering:
+ * those specific handlers run first and never reach this dispatch.
+ *
+ * Read services.json on every request so a `parachute install <svc>` made
+ * seconds ago is reachable without a hub restart — same dynamism as the
+ * well-known doc and `proxyToVault`.
+ *
+ * Honors `entry.stripPrefix`: when `true` the matched mount prefix is
+ * removed from the forwarded path so the backend sees a bare route
+ * (`/scribe/health` becomes `/health`). Default (`false` / absent) forwards
+ * the full path — matches what notes / agent / vault expect.
+ *
+ * Returns `undefined` when no service claims the pathname; caller 404s.
+ */
+async function proxyToService(req: Request, manifestPath: string): Promise<Response | undefined> {
+  let services: readonly ServiceEntry[];
+  try {
+    services = readManifest(manifestPath).services;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return new Response(JSON.stringify({ error: `service routing failed: ${msg}` }), {
+      status: 500,
+      headers: { "content-type": "application/json" },
+    });
+  }
+  const url = new URL(req.url);
+  const match = findServiceUpstream(services, url.pathname);
+  if (!match) return undefined;
+  const targetPath = match.entry.stripPrefix
+    ? url.pathname.slice(match.mount.length) || "/"
+    : undefined;
+  return proxyRequest(req, match.port, match.entry.name, targetPath);
+}
+
 export interface HubFetchDeps {
   /**
    * Lazily opens (or returns a cached handle to) the hub DB. Optional so
@@ -690,6 +780,13 @@ export function hubFetch(
       return serveSpa(spaDistDir, pathname, "/vault");
     }
 
+    // Generic services.json-driven dispatch for non-vault modules. Reaches
+    // here only after every hub-owned prefix above has had its turn — so
+    // `/`, `/admin/*`, `/oauth/*`, `/.well-known/*`, `/hub/*`, `/vault/*`,
+    // `/api/*` are excluded by ordering, not by an explicit denylist (#182).
+    const proxied = await proxyToService(req, manifestPath);
+    if (proxied) return proxied;
+
     return new Response("not found", { status: 404 });
   };
 }

package/src/jwt-audience.ts

@@ -0,0 +1,40 @@
+/**
+ * Audience derivation for hub-issued JWTs. Used by both:
+ *   - `/oauth/token` (auth_code redemption + refresh rotation)
+ *   - `parachute auth mint-token` (CLI shortcut for scope-narrow tokens)
+ *
+ * Per the vault-config-and-scopes design (Phase 1+2):
+ *   - A named `vault:<name>:<verb>` → `vault.<name>` (RFC 8707-style resource
+ *     binding; vault enforces this strict-equality against the URL-derived
+ *     vault name).
+ *   - An unnamed `<service>:<verb>` → `<service>` (legacy shape; vault's
+ *     strict-check rejects unnamed `vault:*` audiences, so the consent
+ *     picker rewrites those before this is reached).
+ *   - Fallback: `hub` (no namespaced scope).
+ *
+ * Named vault scopes win over unnamed ones — an OAuth flow that mixes
+ * `vault:work:read` + `scribe:transcribe` audiences is grounded on the vault
+ * (the more sensitive resource), and tokens are issued per-flow anyway.
+ *
+ * Hoisted from `oauth-handlers.ts` so CLI mints and OAuth mints can't diverge
+ * on audience semantics — a divergence here means tokens minted via CLI fail
+ * audience strict-check at the resource server even though scopes match.
+ */
+
+export const VAULT_VERBS = new Set(["read", "write", "admin"]);
+
+export function inferAudience(scopes: readonly string[]): string {
+  for (const s of scopes) {
+    const parts = s.split(":");
+    const name = parts[1];
+    const verb = parts[2];
+    if (parts.length === 3 && parts[0] === "vault" && name && verb && VAULT_VERBS.has(verb)) {
+      return `vault.${name}`;
+    }
+  }
+  for (const s of scopes) {
+    const colon = s.indexOf(":");
+    if (colon > 0) return s.slice(0, colon);
+  }
+  return "hub";
+}

package/src/module-manifest.ts

@@ -114,6 +114,15 @@ export interface ModuleManifest {
    * as `hasAuth` / `init` / `urlForEntry`.
    */
   readonly managementUrl?: string;
+  /**
+   * When `true`, the hub's `/<svc>/*` proxy strips the matched mount prefix
+   * before forwarding (so the backend sees `/health` rather than
+   * `/<name>/health`). Default `false` matches the prefix-aware convention
+   * notes / agent / vault already follow. Carried into services.json via
+   * `seedEntryFromManifest`. See `ServiceEntry.stripPrefix` for the full
+   * per-module rationale.
+   */
+  readonly stripPrefix?: boolean;
 }
 
 export class ModuleManifestError extends Error {
@@ -365,6 +374,13 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   const dependencies = asDependencies(m.dependencies, where);
   const configSchema = asConfigSchema(m.configSchema, where);
   const managementUrl = asManagementUrl(m.managementUrl, where);
+  let stripPrefix: boolean | undefined;
+  if (m.stripPrefix !== undefined) {
+    if (typeof m.stripPrefix !== "boolean") {
+      throw new ModuleManifestError(`${where}: "stripPrefix" must be a boolean if present`);
+    }
+    stripPrefix = m.stripPrefix;
+  }
 
   const out: ModuleManifest = { name, manifestName, kind, port, paths, health };
   if (displayName !== undefined) (out as { displayName?: string }).displayName = displayName;
@@ -380,6 +396,9 @@ export function validateModuleManifest(raw: unknown, where: string): ModuleManif
   if (managementUrl !== undefined) {
     (out as { managementUrl?: string }).managementUrl = managementUrl;
   }
+  if (stripPrefix !== undefined) {
+    (out as { stripPrefix?: boolean }).stripPrefix = stripPrefix;
+  }
   return out;
 }
 

package/src/oauth-handlers.ts

@@ -43,6 +43,7 @@ import {
 } from "./clients.ts";
 import { CSRF_FIELD_NAME, ensureCsrfToken, verifyCsrfToken } from "./csrf.ts";
 import { isCoveredByGrant, recordGrant } from "./grants.ts";
+import { VAULT_VERBS, inferAudience } from "./jwt-audience.ts";
 import {
   ACCESS_TOKEN_TTL_SECONDS,
   RefreshTokenInsertError,
@@ -69,8 +70,6 @@ import {
 import { getUserByUsername, verifyPassword } from "./users.ts";
 import { isVaultEntry, shortName, vaultInstanceNameFor } from "./well-known.ts";
 
-const VAULT_VERBS = new Set(["read", "write", "admin"]);
-
 /** Verbs whose unnamed `vault:<verb>` form needs picker disambiguation. */
 function unnamedVaultVerbs(scopes: string[]): string[] {
   const verbs: string[] = [];
@@ -1056,36 +1055,6 @@ function mapAuthCodeError(err: unknown): Response {
   return jsonResponse({ error: "server_error", error_description: msg }, 500);
 }
 
-/**
- * Picks the JWT `aud` claim based on the requested scopes. Per the
- * vault-config-and-scopes design (Phase 1+2):
- *   - A named `vault:<name>:<verb>` → `vault.<name>` (RFC 8707-style resource
- *     binding; vault enforces this strict-equality against the URL-derived
- *     vault name).
- *   - An unnamed `<service>:<verb>` → `<service>` (legacy shape; vault's
- *     strict-check rejects unnamed `vault:*` audiences, so the consent
- *     picker rewrites those before this is reached).
- *
- * Named vault scopes win over unnamed ones — an OAuth flow that mixes
- * `vault:work:read` + `scribe:transcribe` audiences is grounded on the vault
- * (the more sensitive resource), and tokens are issued per-flow anyway.
- */
-function inferAudience(scopes: string[]): string {
-  for (const s of scopes) {
-    const parts = s.split(":");
-    const name = parts[1];
-    const verb = parts[2];
-    if (parts.length === 3 && parts[0] === "vault" && name && verb && VAULT_VERBS.has(verb)) {
-      return `vault.${name}`;
-    }
-  }
-  for (const s of scopes) {
-    const colon = s.indexOf(":");
-    if (colon > 0) return s.slice(0, colon);
-  }
-  return "hub";
-}
-
 // --- /oauth/register -------------------------------------------------------
 
 interface RegisterRequestBody {

package/src/service-spec.ts

@@ -199,6 +199,7 @@ export function seedEntryFromManifest(manifest: ModuleManifest): ServiceEntry {
   };
   if (manifest.displayName !== undefined) entry.displayName = manifest.displayName;
   if (manifest.tagline !== undefined) entry.tagline = manifest.tagline;
+  if (manifest.stripPrefix !== undefined) entry.stripPrefix = manifest.stripPrefix;
   return entry;
 }
 
@@ -319,6 +320,13 @@ const SCRIBE_FALLBACK: FirstPartyFallback = {
     paths: ["/scribe"],
     health: "/scribe/health",
     startCmd: ["parachute-scribe", "serve"],
+    // Scribe's HTTP routes are bare (`/health`, `/v1/...`), unlike notes /
+    // agent which strip the mount themselves. Until scribe ships a `--mount`
+    // flag (tracked upstream in parachute-scribe), the hub strips the
+    // `/scribe` prefix before forwarding so a request to
+    // `hub:1939/scribe/v1/audio/transcriptions` reaches scribe as
+    // `/v1/audio/transcriptions`.
+    stripPrefix: true,
   },
   extras: {
     // No auth gate today. Scribe's launch PR adds optional SCRIBE_AUTH_TOKEN;

package/src/services-manifest.ts

@@ -45,6 +45,22 @@ export interface ServiceEntry {
    * can use clean relative paths in their `startCmd`.
    */
   installDir?: string;
+  /**
+   * When `true`, the hub's `/<svc>/*` proxy strips the matched mount prefix
+   * before forwarding so the backend sees a bare path (e.g. `/health` rather
+   * than `/scribe/health`). Default `false` keeps the prefix intact, which
+   * matches what notes / agent / vault expect today.
+   *
+   * Per-module rather than uniform because conventions differ:
+   *   - notes-serve.ts strips internally via `--mount`; expects the prefix.
+   *   - parachute-agent reads PARACHUTE_AGENT_WEB_MOUNT and strips itself.
+   *   - parachute-vault routes by `/vault/<name>/...` and expects the prefix.
+   *   - parachute-scribe serves bare paths (`/health`, `/v1/...`); the proxy
+   *     must strip. Eventually scribe should accept its own `--mount` flag
+   *     and join the always-prefixed convention; until then this opt-in
+   *     bridges the gap. Tracked in parachute-scribe (separate issue).
+   */
+  stripPrefix?: boolean;
 }
 
 export interface ServicesManifest {
@@ -105,11 +121,16 @@ function validateEntry(raw: unknown, where: string): ServiceEntry {
   if (installDir !== undefined && (typeof installDir !== "string" || installDir.length === 0)) {
     throw new ServicesManifestError(`${where}: "installDir" must be a non-empty string if present`);
   }
+  const stripPrefix = e.stripPrefix;
+  if (stripPrefix !== undefined && typeof stripPrefix !== "boolean") {
+    throw new ServicesManifestError(`${where}: "stripPrefix" must be a boolean if present`);
+  }
   const entry: ServiceEntry = { name, port, paths: paths as string[], health, version };
   if (displayName !== undefined) entry.displayName = displayName;
   if (tagline !== undefined) entry.tagline = tagline;
   if (publicExposure !== undefined) entry.publicExposure = publicExposure as PublicExposure;
   if (installDir !== undefined) entry.installDir = installDir;
+  if (stripPrefix !== undefined) entry.stripPrefix = stripPrefix;
   return entry;
 }