@openparachute/hub 0.6.5-rc.8 → 0.7.1

package/src/module-manifest.ts

@@ -65,6 +65,170 @@ export interface ConfigSchema {
   readonly required?: readonly string[];
 }
 
+/**
+ * Discovery tier (2026-06-09 modular-UI architecture). `core` modules are the
+ * product surface (vault / scribe / hub / surface); `experimental` modules
+ * (channel / runner / others) render in a de-emphasized group on the Modules
+ * screen. **Show all; never hide** — `focus` only sorts + labels.
+ *
+ * Absent in a `module.json` ⇒ the hub falls back to its default map (see
+ * `service-spec.focusForShort`), which defaults unlisted modules to
+ * `experimental`.
+ */
+export type ModuleFocus = "core" | "experimental";
+
+/**
+ * An event a module EMITS — the left-hand side of a Connection (2026-06-09
+ * modular-UI architecture, P5). Declared in `module.json`; the hub's
+ * Connections surface lists these so an operator can wire
+ * "when [event] in [module] → do [action] in [module]". `filterSchema` is an
+ * optional JSON-Schema describing the per-event filter an operator can set
+ * (e.g. a tag filter on `vault.note.created`). Minimal at P1 — the hub only
+ * needs to round-trip the declaration; richer typing lands with P5.
+ */
+export interface ModuleEvent {
+  /** Event identifier within the module, e.g. `note.created`. */
+  readonly key: string;
+  /** Operator-facing label. */
+  readonly title: string;
+  /** Optional JSON-Schema for the per-event filter an operator may set. */
+  readonly filterSchema?: unknown;
+}
+
+/**
+ * An action a module ACCEPTS — the right-hand side of a Connection (2026-06-09
+ * modular-UI architecture, P5). `inputSchema` is an optional JSON-Schema for
+ * the action's input; `provision` is an opaque (at P1) descriptor of how the
+ * hub wires the action when a Connection is created (e.g. register a vault
+ * trigger). Both are passed through untyped here — the hub only round-trips
+ * the declaration at P1; P5 gives them structure.
+ */
+export interface ModuleAction {
+  /** Action identifier within the module, e.g. `message.send`. */
+  readonly key: string;
+  /** Operator-facing label. */
+  readonly title: string;
+  /** Optional JSON-Schema for the action's input. */
+  readonly inputSchema?: unknown;
+  /**
+   * The module-relative HTTP endpoint the hub's Connections engine calls when
+   * this action fires (P5). For a `vault-trigger` provision, this becomes the
+   * vault trigger's `action.webhook`, hub-proxied under the module's mount:
+   * `<hub-origin>/<mount><endpoint>`. Declaring it here — rather than
+   * hardcoding a per-module path in the hub — is what makes the engine general.
+   * Channel ships `"/api/vault/inbound"`.
+   */
+  readonly endpoint?: string;
+  /**
+   * The OAuth scope the hub mints into the action webhook's `Authorization:
+   * Bearer` (P5). For a `vault-trigger`, this is persisted as the trigger's
+   * long-lived `action.auth.bearer` scope — the credential the sink module
+   * validates on every callback. Sourced from the action declaration so the
+   * hub never hardcodes a per-module scope. Channel ships `"channel:send"`.
+   */
+  readonly scope?: string;
+  /** Opaque (P1) descriptor of how the hub provisions this action. */
+  readonly provision?: unknown;
+}
+
+/**
+ * A standing CREDENTIAL a module declares it can hold (H4, surface-runtime
+ * design / credential connections). Where an action's `scope` is a scope in
+ * the module's OWN namespace (minted for callbacks INTO the module), a
+ * credential declaration asks the hub to mint the module a standing
+ * tag-scoped token on a VAULT — operator-approved via
+ * `POST /admin/connections` with `kind: "credential"`.
+ *
+ * The `scope` field is a TEMPLATE, not a literal: `vault:{vault}:read` or
+ * `vault:{vault}:write` — the `{vault}` placeholder is filled by the
+ * operator's approval (which vault, which tags). Validation enforces the
+ * privilege-escalation guard at declaration time: ONLY the `vault` namespace,
+ * ONLY `read`/`write` verbs — never `admin`, never another module's
+ * namespace. (The POST handler re-checks the same rule, so a manifest read
+ * through a non-validating path can't smuggle a broader template.)
+ */
+export interface ModuleCredential {
+  /** Credential identifier within the module, e.g. `vault`. */
+  readonly key: string;
+  /** Operator-facing label. */
+  readonly title: string;
+  readonly description?: string;
+  /**
+   * Scope template: `vault:{vault}:read` | `vault:{vault}:write`. The
+   * operator approval fills `{vault}` and supplies the tag scope.
+   */
+  readonly scope: string;
+  /**
+   * Daemon-root-relative HTTP endpoint (leading `/`) the hub POSTs the
+   * minted credential to over loopback (like the engine's channel-config
+   * delivery), authenticated with a short-lived `<module>:admin` bearer.
+   * Also receives the best-effort removal payload on teardown.
+   */
+  readonly endpoint: string;
+}
+
+/** The validated shape of a credential scope template. */
+export const CREDENTIAL_SCOPE_TEMPLATE_RE = /^vault:\{vault\}:(read|write)$/;
+
+/**
+ * One declared parameter of a {@link ConnectionTemplate} — the operator-chosen
+ * blank in the template (e.g. WHICH vault, the channel name).
+ */
+export interface ConnectionTemplateParameter {
+  /** Parameter identifier within the template, e.g. `vault`, `channel`. */
+  readonly key: string;
+  /**
+   * Where the chosen value lands on the connection body, e.g. `source.vault`
+   * or `sink.params.channel`. Opaque to the hub at P1 — builder UIs interpret
+   * the two shapes above; anything else rides through for future targets.
+   */
+  readonly target: string;
+  /** Operator-facing label. */
+  readonly title?: string;
+  readonly description?: string;
+  /** Optional pre-fill example a builder UI may show for this parameter. */
+  readonly example?: string;
+}
+
+/**
+ * A connection PRESET a module declares in `module.json` (boundary D2).
+ *
+ * Two shapes ship today, discriminated by presence of `source` + `sink`:
+ *   - **event→action preset** (channel's `link-to-vault`): `source` (a module
+ *     event + optional filter) + `sink` (a module action). The hub's
+ *     Connections builder offers these as one-click pre-fills.
+ *   - **config link** (scribe's `link-to-vault`, `kind: "config"`): no
+ *     `source`/`sink` — a module-owned config flow described by other fields
+ *     (`provider`/`target`, which ride through `extra`-style and are NOT
+ *     interpreted by the hub). These are consumed by the module's own UI,
+ *     not the hub builder.
+ *
+ * Declaration-driven so the hub SPA never hardcodes a per-module preset (the
+ * charter's per-module-view test); the hub only round-trips these through
+ * `/api/connections/catalog` (event→action presets only).
+ */
+export interface ConnectionTemplate {
+  /** Template identifier within the module, e.g. `link-to-vault`. */
+  readonly key: string;
+  /** Operator-facing label. */
+  readonly title: string;
+  readonly description?: string;
+  /** Provenance label for connections created from this template. */
+  readonly requestedBy?: string;
+  /** Optional discriminator — scribe ships `"config"`. Absent = event→action. */
+  readonly kind?: string;
+  /** The source event the template pre-fills (+ optional filter, opaque). */
+  readonly source?: {
+    readonly module: string;
+    readonly event: string;
+    readonly filter?: unknown;
+  };
+  /** The sink action the template pre-fills. */
+  readonly sink?: { readonly module: string; readonly action: string };
+  /** Operator-chosen blanks. */
+  readonly parameters?: readonly ConnectionTemplateParameter[];
+}
+
 export interface ModuleManifest {
   /** Stable ecosystem identifier — `[a-z][a-z0-9-]*`, also the services.json key. */
   readonly name: string;
@@ -99,12 +263,18 @@ export interface ModuleManifest {
    * Where the module's admin UI lives. Hub renders a "Manage" link when set
    * (see `parachute-patterns/patterns/module-json-extensibility.md`).
    *
-   * Two shapes:
-   *   - A relative path (e.g. `"/admin"`) — hub resolves against the module's
-   *     mounted URL: `<module-url><managementUrl>`. Most first-party modules
-   *     take this path so the admin UI rides the same Tailscale Funnel cap.
-   *   - A full absolute URL — hub uses verbatim. Escape hatch for modules
-   *     whose admin UI is hosted off-origin.
+   * Three shapes (unified URL-resolution semantics — B4 of the 2026-06-09
+   * hub-module-boundary migration):
+   *   - A full http(s) URL — used verbatim. Escape hatch for modules whose
+   *     admin UI is hosted off-origin.
+   *   - A leading-`/` path (e.g. `"/scribe/admin"`) — ORIGIN-ABSOLUTE, used
+   *     verbatim against the hub origin.
+   *   - A relative path (e.g. `"admin/"`) — the PER-INSTANCE form; hub joins
+   *     it under the module's mounted URL: `<module-url>/<managementUrl>`.
+   *
+   * COMPAT SHIM (one release): the literal legacy `"/admin"`/`"/admin/"` on a
+   * vault entry is treated as the old per-instance relative form (mount-join)
+   * — deployed vaults still declare it until the vault wave ships.
    *
    * Absent = no link rendered (CLI-only management). Same back-compat rule
    * as `hasAuth` / `init` / `urlForEntry`.
@@ -140,6 +310,45 @@ export interface ModuleManifest {
    * per-module rationale.
    */
   readonly stripPrefix?: boolean;
+  /**
+   * When `true`, the module's daemon accepts WebSocket upgrades and the hub's
+   * Bun-native upgrade bridge (H1, surface-runtime design) forwards
+   * `Upgrade: websocket` requests on the module's mounts. DENY BY DEFAULT:
+   * absent/false refuses upgrades (426) before they reach the daemon. The
+   * canonical capability declaration; modules also carry it onto their
+   * self-registered services.json row (`ServiceEntry.websocket`), and the hub
+   * honors either source.
+   */
+  readonly websocket?: boolean;
+  /**
+   * Discovery tier (2026-06-09 modular-UI architecture). When a module
+   * declares `focus`, the hub's Modules screen uses it verbatim; otherwise it
+   * falls back to `service-spec.focusForShort` (vault/scribe/hub/surface →
+   * `core`, everything else → `experimental`). **Show all; never hide** —
+   * `focus` only groups + de-emphasizes. Additive + back-compatible.
+   */
+  readonly focus?: ModuleFocus;
+  /**
+   * Where the module's OWN config/admin surface lives — the module renders it,
+   * the hub frames/links it (2026-06-09 modular-UI architecture, P3). Same
+   * path-or-absolute-URL shape as `managementUrl` (distinct field: `managementUrl`
+   * predates this; `configUiUrl` is the canonical config-surface declaration the
+   * config shell consumes). Optional + back-compatible.
+   */
+  readonly configUiUrl?: string;
+  /**
+   * Free-form capability hints for the config shell, e.g. `["config",
+   * "credentials", "logs"]`. Metadata only at P1 — the hub round-trips it.
+   */
+  readonly adminCapabilities?: readonly string[];
+  /** Events this module EMITS — Connections left-hand side (P5). */
+  readonly events?: readonly ModuleEvent[];
+  /** Actions this module ACCEPTS — Connections right-hand side (P5). */
+  readonly actions?: readonly ModuleAction[];
+  /** Connection presets this module declares — see {@link ConnectionTemplate}. */
+  readonly connectionTemplates?: readonly ConnectionTemplate[];
+  /** Standing vault credentials this module can hold — see {@link ModuleCredential} (H4). */
+  readonly credentials?: readonly ModuleCredential[];
 }
 
 export class ModuleManifestError extends Error {
@@ -395,6 +604,16 @@ export function validateModuleManifest(
   const configSchema = asConfigSchema(m.configSchema, where);
   const managementUrl = asManagementUrl(m.managementUrl, where);
   const uiUrl = asUiUrl(m.uiUrl, where);
+  const focus = asFocus(m.focus, where);
+  const configUiUrl = asPathOrUrl(m.configUiUrl, where, "configUiUrl");
+  const adminCapabilities =
+    m.adminCapabilities === undefined
+      ? undefined
+      : asStringArray(m.adminCapabilities, where, "adminCapabilities");
+  const events = asEvents(m.events, where);
+  const actions = asActions(m.actions, where, name);
+  const connectionTemplates = asConnectionTemplates(m.connectionTemplates, where);
+  const credentials = asCredentials(m.credentials, where);
   let stripPrefix: boolean | undefined;
   if (m.stripPrefix !== undefined) {
     if (typeof m.stripPrefix !== "boolean") {
@@ -402,6 +621,13 @@ export function validateModuleManifest(
     }
     stripPrefix = m.stripPrefix;
   }
+  let websocket: boolean | undefined;
+  if (m.websocket !== undefined) {
+    if (typeof m.websocket !== "boolean") {
+      throw new ModuleManifestError(`${where}: "websocket" must be a boolean if present`);
+    }
+    websocket = m.websocket;
+  }
 
   const out: ModuleManifest = { name, manifestName, port, paths, health };
   if (displayName !== undefined) (out as { displayName?: string }).displayName = displayName;
@@ -423,9 +649,252 @@ export function validateModuleManifest(
   if (stripPrefix !== undefined) {
     (out as { stripPrefix?: boolean }).stripPrefix = stripPrefix;
   }
+  if (websocket !== undefined) {
+    (out as { websocket?: boolean }).websocket = websocket;
+  }
+  if (focus !== undefined) (out as { focus?: ModuleFocus }).focus = focus;
+  if (configUiUrl !== undefined) (out as { configUiUrl?: string }).configUiUrl = configUiUrl;
+  if (adminCapabilities !== undefined) {
+    (out as { adminCapabilities?: readonly string[] }).adminCapabilities = adminCapabilities;
+  }
+  if (events !== undefined) (out as { events?: readonly ModuleEvent[] }).events = events;
+  if (actions !== undefined) (out as { actions?: readonly ModuleAction[] }).actions = actions;
+  if (connectionTemplates !== undefined) {
+    (out as { connectionTemplates?: readonly ConnectionTemplate[] }).connectionTemplates =
+      connectionTemplates;
+  }
+  if (credentials !== undefined) {
+    (out as { credentials?: readonly ModuleCredential[] }).credentials = credentials;
+  }
   return out;
 }
 
+/**
+ * Validate the optional `credentials` declaration (H4). The scope template
+ * is the privilege-escalation guard's declaration-time half: ONLY
+ * `vault:{vault}:read` / `vault:{vault}:write` — a module can never declare
+ * its way to `admin`, to a literal vault name (the operator picks the vault
+ * at approval), or to another module's namespace. The POST handler re-checks
+ * the same rule (defense in depth for manifests read through paths that skip
+ * this validator).
+ */
+function asCredentials(v: unknown, where: string): readonly ModuleCredential[] | undefined {
+  if (v === undefined) return undefined;
+  if (!Array.isArray(v)) {
+    throw new ModuleManifestError(`${where}: "credentials" must be an array if present`);
+  }
+  return v.map((raw, i) => {
+    const at = `credentials[${i}]`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new ModuleManifestError(`${where}: "${at}" must be an object`);
+    }
+    const c = raw as Record<string, unknown>;
+    const scope = asString(c.scope, where, `${at}.scope`);
+    if (!CREDENTIAL_SCOPE_TEMPLATE_RE.test(scope)) {
+      throw new ModuleManifestError(
+        `${where}: "${at}.scope" "${scope}" must be "vault:{vault}:read" or "vault:{vault}:write" — credential connections never grant admin or another namespace`,
+      );
+    }
+    const endpoint = asString(c.endpoint, where, `${at}.endpoint`);
+    if (!endpoint.startsWith("/")) {
+      throw new ModuleManifestError(`${where}: "${at}.endpoint" must start with "/"`);
+    }
+    const out: ModuleCredential = {
+      key: asString(c.key, where, `${at}.key`),
+      title: asString(c.title, where, `${at}.title`),
+      scope,
+      endpoint,
+    };
+    const description = asOptionalString(c.description, where, `${at}.description`);
+    if (description !== undefined) (out as { description?: string }).description = description;
+    return out;
+  });
+}
+
+const MODULE_FOCUS_VALUES = new Set<ModuleFocus>(["core", "experimental"]);
+
+function asFocus(v: unknown, where: string): ModuleFocus | undefined {
+  if (v === undefined) return undefined;
+  if (typeof v !== "string" || !MODULE_FOCUS_VALUES.has(v as ModuleFocus)) {
+    throw new ModuleManifestError(`${where}: "focus" must be "core" | "experimental" if present`);
+  }
+  return v as ModuleFocus;
+}
+
+function asEvents(v: unknown, where: string): readonly ModuleEvent[] | undefined {
+  if (v === undefined) return undefined;
+  if (!Array.isArray(v)) {
+    throw new ModuleManifestError(`${where}: "events" must be an array if present`);
+  }
+  return v.map((raw, i) => {
+    const at = `events[${i}]`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new ModuleManifestError(`${where}: "${at}" must be an object`);
+    }
+    const e = raw as Record<string, unknown>;
+    const out: ModuleEvent = {
+      key: asString(e.key, where, `${at}.key`),
+      title: asString(e.title, where, `${at}.title`),
+    };
+    if (e.filterSchema !== undefined) {
+      (out as { filterSchema?: unknown }).filterSchema = e.filterSchema;
+    }
+    return out;
+  });
+}
+
+function asActions(
+  v: unknown,
+  where: string,
+  /** Declaring module's name — enforces the `action.scope` namespace rule. */
+  name: string,
+): readonly ModuleAction[] | undefined {
+  if (v === undefined) return undefined;
+  if (!Array.isArray(v)) {
+    throw new ModuleManifestError(`${where}: "actions" must be an array if present`);
+  }
+  return v.map((raw, i) => {
+    const at = `actions[${i}]`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new ModuleManifestError(`${where}: "${at}" must be an object`);
+    }
+    const a = raw as Record<string, unknown>;
+    const out: ModuleAction = {
+      key: asString(a.key, where, `${at}.key`),
+      title: asString(a.title, where, `${at}.title`),
+    };
+    if (a.inputSchema !== undefined) (out as { inputSchema?: unknown }).inputSchema = a.inputSchema;
+    if (a.endpoint !== undefined) {
+      const ep = asString(a.endpoint, where, `${at}.endpoint`);
+      if (!ep.startsWith("/")) {
+        throw new ModuleManifestError(`${where}: "${at}.endpoint" must start with "/"`);
+      }
+      (out as { endpoint?: string }).endpoint = ep;
+    }
+    if (a.scope !== undefined) {
+      const scope = asString(a.scope, where, `${at}.scope`);
+      // Scope-namespace rule (mirrors `scopes.defines` above): an action's
+      // `scope` is minted by the hub into a 90-day webhook bearer presented to
+      // THIS module's own endpoint, which validates `aud:<name>` + a scope in
+      // its own namespace. A legitimate `action.scope` is therefore always in
+      // the declaring module's namespace (channel.message.deliver → channel:send).
+      // Enforcing `<ns> === name` blocks a malicious module declaring e.g.
+      // `vault:default:admin` and tricking the hub into minting a cross-module
+      // privilege-escalating token when an operator wires a Connection to it.
+      // Cross-module tokens a sink legitimately needs for OTHER purposes (e.g.
+      // channel's reply path needs `vault:write`) are minted separately by the
+      // engine, NOT declared here.
+      const colon = scope.indexOf(":");
+      if (colon <= 0) {
+        throw new ModuleManifestError(
+          `${where}: "${at}.scope" "${scope}" must be namespaced as "<name>:<verb>"`,
+        );
+      }
+      const ns = scope.slice(0, colon);
+      if (ns !== name) {
+        throw new ModuleManifestError(
+          `${where}: "${at}.scope" "${scope}" namespace "${ns}" does not match module name "${name}"`,
+        );
+      }
+      (out as { scope?: string }).scope = scope;
+    }
+    if (a.provision !== undefined) (out as { provision?: unknown }).provision = a.provision;
+    return out;
+  });
+}
+
+/**
+ * Validate the optional `connectionTemplates` declaration (boundary D2).
+ * Light-touch like `events`/`actions` at P1 — the hub only round-trips these
+ * to `/api/connections/catalog`; `filter` rides through opaque (it's the same
+ * shape the connection body's `source.filter` takes).
+ *
+ * `source`/`sink` are OPTIONAL: scribe ships a `kind: "config"` template with
+ * neither (a module-owned config flow, not an event→action preset) — a strict
+ * requirement here would make every real-manifest read throw for scribe.
+ * When present, their inner shapes are validated.
+ */
+function asConnectionTemplates(
+  v: unknown,
+  where: string,
+): readonly ConnectionTemplate[] | undefined {
+  if (v === undefined) return undefined;
+  if (!Array.isArray(v)) {
+    throw new ModuleManifestError(`${where}: "connectionTemplates" must be an array if present`);
+  }
+  return v.map((raw, i) => {
+    const at = `connectionTemplates[${i}]`;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new ModuleManifestError(`${where}: "${at}" must be an object`);
+    }
+    const t = raw as Record<string, unknown>;
+    let outSource: NonNullable<ConnectionTemplate["source"]> | undefined;
+    if (t.source !== undefined) {
+      const source = t.source;
+      if (!source || typeof source !== "object" || Array.isArray(source)) {
+        throw new ModuleManifestError(`${where}: "${at}.source" must be an object if present`);
+      }
+      const src = source as Record<string, unknown>;
+      outSource = {
+        module: asString(src.module, where, `${at}.source.module`),
+        event: asString(src.event, where, `${at}.source.event`),
+        ...(src.filter !== undefined ? { filter: src.filter } : {}),
+      };
+    }
+    let outSink: NonNullable<ConnectionTemplate["sink"]> | undefined;
+    if (t.sink !== undefined) {
+      const sink = t.sink;
+      if (!sink || typeof sink !== "object" || Array.isArray(sink)) {
+        throw new ModuleManifestError(`${where}: "${at}.sink" must be an object if present`);
+      }
+      const snk = sink as Record<string, unknown>;
+      outSink = {
+        module: asString(snk.module, where, `${at}.sink.module`),
+        action: asString(snk.action, where, `${at}.sink.action`),
+      };
+    }
+    const out: ConnectionTemplate = {
+      key: asString(t.key, where, `${at}.key`),
+      title: asString(t.title, where, `${at}.title`),
+    };
+    if (outSource !== undefined) {
+      (out as { source?: ConnectionTemplate["source"] }).source = outSource;
+    }
+    if (outSink !== undefined) (out as { sink?: ConnectionTemplate["sink"] }).sink = outSink;
+    const kind = asOptionalString(t.kind, where, `${at}.kind`);
+    if (kind !== undefined) (out as { kind?: string }).kind = kind;
+    const description = asOptionalString(t.description, where, `${at}.description`);
+    if (description !== undefined) (out as { description?: string }).description = description;
+    const requestedBy = asOptionalString(t.requestedBy, where, `${at}.requestedBy`);
+    if (requestedBy !== undefined) (out as { requestedBy?: string }).requestedBy = requestedBy;
+    if (t.parameters !== undefined) {
+      if (!Array.isArray(t.parameters)) {
+        throw new ModuleManifestError(`${where}: "${at}.parameters" must be an array if present`);
+      }
+      const parameters = t.parameters.map((p, j) => {
+        const pat = `${at}.parameters[${j}]`;
+        if (!p || typeof p !== "object" || Array.isArray(p)) {
+          throw new ModuleManifestError(`${where}: "${pat}" must be an object`);
+        }
+        const pr = p as Record<string, unknown>;
+        const param: ConnectionTemplateParameter = {
+          key: asString(pr.key, where, `${pat}.key`),
+          target: asString(pr.target, where, `${pat}.target`),
+        };
+        const title = asOptionalString(pr.title, where, `${pat}.title`);
+        if (title !== undefined) (param as { title?: string }).title = title;
+        const pdesc = asOptionalString(pr.description, where, `${pat}.description`);
+        if (pdesc !== undefined) (param as { description?: string }).description = pdesc;
+        const example = asOptionalString(pr.example, where, `${pat}.example`);
+        if (example !== undefined) (param as { example?: string }).example = example;
+        return param;
+      });
+      (out as { parameters?: readonly ConnectionTemplateParameter[] }).parameters = parameters;
+    }
+    return out;
+  });
+}
+
 function asManagementUrl(v: unknown, where: string): string | undefined {
   return asPathOrUrl(v, where, "managementUrl");
 }
@@ -435,33 +904,77 @@ function asUiUrl(v: unknown, where: string): string | undefined {
 }
 
 /**
- * Validate a "path or http(s) URL" field. Both `managementUrl` and `uiUrl`
- * follow the same shape per the module-json-extensibility pattern doc;
- * factored so the next URL-shaped field doesn't have to copy-paste.
+ * Validate a "path or http(s) URL" field. `managementUrl`, `uiUrl`, and
+ * `configUiUrl` follow the same shape per the module-json-extensibility
+ * pattern doc; factored so the next URL-shaped field doesn't have to
+ * copy-paste.
+ *
+ * Three valid shapes (unified URL-resolution semantics, B4 of the 2026-06-09
+ * hub-module-boundary migration):
+ *   - a full http(s) URL — resolvers use it verbatim;
+ *   - an origin-absolute path starting with a single "/" — resolvers use it
+ *     verbatim against the hub origin;
+ *   - a RELATIVE path (no leading slash, e.g. `"admin/"`) — the per-instance
+ *     form; resolvers join it under the module's mount. Constrained so it can
+ *     only deepen its mount: no `..` segments, no URL scheme.
+ *
+ * Rejected: protocol-relative forms like `"//evil.com"` — they start with "/"
+ * but `new URL("//evil.com", base)` resolves to the foreign origin, which
+ * would let a malicious module render an off-origin tile and turn the
+ * discovery page into an open-redirect surface.
  */
 function asPathOrUrl(v: unknown, where: string, field: string): string | undefined {
   if (v === undefined) return undefined;
   if (typeof v !== "string" || v.length === 0) {
     throw new ModuleManifestError(`${where}: "${field}" must be a non-empty string if present`);
   }
-  // Two valid shapes: an absolute path starting with a single "/" or a full
-  // http(s) URL. Reject protocol-relative forms like "//evil.com" — they
-  // start with "/" but `new URL("//evil.com", base)` resolves to the foreign
-  // origin, which would let a malicious module render an off-origin tile and
-  // turn the discovery page into an open-redirect surface.
-  if (v.startsWith("/") && !v.startsWith("//")) return v;
-  try {
-    const u = new URL(v);
-    if (u.protocol !== "http:" && u.protocol !== "https:") {
-      throw new ModuleManifestError(`${where}: "${field}" absolute form must use http: or https:`);
+  if (v.startsWith("//")) {
+    throw new ModuleManifestError(
+      `${where}: "${field}" must not be protocol-relative ("//..." resolves off-origin)`,
+    );
+  }
+  // Origin-absolute path — verbatim.
+  if (v.startsWith("/")) return v;
+  // Scheme-bearing string — must be a well-formed http(s) URL. Anything else
+  // ("ftp://...", "javascript:...") is rejected rather than smuggled through
+  // as a "relative path".
+  if (/^[a-z][a-z0-9+.-]*:/i.test(v)) {
+    try {
+      const u = new URL(v);
+      if (u.protocol !== "http:" && u.protocol !== "https:") {
+        throw new ModuleManifestError(
+          `${where}: "${field}" absolute form must use http: or https:`,
+        );
+      }
+      return v;
+    } catch (err) {
+      if (err instanceof ModuleManifestError) throw err;
+      throw new ModuleManifestError(
+        `${where}: "${field}" must be a relative path, a path starting with "/", or a full http(s) URL`,
+      );
     }
-    return v;
-  } catch (err) {
-    if (err instanceof ModuleManifestError) throw err;
+  }
+  // Relative (per-instance, mount-joined) form. Forbid `..` traversal so a
+  // declared value can only deepen the module's own mount, never escape it.
+  if (v.split("/").some((segment) => segment === "..")) {
     throw new ModuleManifestError(
-      `${where}: "${field}" must be a path starting with "/" or a full http(s) URL`,
+      `${where}: "${field}" relative form must not contain ".." segments`,
     );
   }
+  // Forbid backslashes anywhere in the relative form — the simplest closure
+  // of the backslash-traversal quirk: WHATWG URL parsing treats `\` as `/`
+  // in special (http/https) schemes, so `a\..\b` joined under a mount would
+  // normalize to `a/../b` and pop a segment, escaping the `..`-segment check
+  // above. Percent-encoded forms (`..%2f`) need no equivalent guard:
+  // `new URL()` does NOT decode percent-escapes during base-join, so a
+  // `..%2f` stays a literal three-char segment and never traverses (pinned
+  // in module-manifest.test.ts).
+  if (v.includes("\\")) {
+    throw new ModuleManifestError(
+      `${where}: "${field}" relative form must not contain backslashes`,
+    );
+  }
+  return v;
 }
 
 /**