every-plugin 3.0.0-rc.15 → 3.0.0-rc.17

package/src/client.ts

@@ -1,117 +1,20 @@
-import { createORPCClient, onError } from "@orpc/client";
+import { createORPCClient } from "@orpc/client";
 import { RPCLink } from "@orpc/client/fetch";
 import type { ContractRouterClient, RouterContract } from "@orpc/contract";
 
-export type RpcConnectionErrorCopy = () => { title: string; description: string };
-
-export interface RpcClientConfig {
-  hostUrl: string;
-  path: `/${string}`;
-  connectionError?: RpcConnectionErrorCopy;
-}
-
-const RATE_LIMIT_MAX_RETRIES = 3;
-const RATE_LIMIT_RETRY_CAP_MS = 2_000;
-const browserClients = new Map<string, unknown>();
-type FetchInput = Parameters<typeof fetch>[0];
-
-async function fetchWithRateLimitRetry(
-  fetchUrl: FetchInput,
-  options?: RequestInit,
-): Promise<Response> {
-  let response = await fetch(fetchUrl, options);
-  for (let attempt = 1; attempt <= RATE_LIMIT_MAX_RETRIES && response.status === 429; attempt++) {
-    const retryAfterSeconds = Number(response.headers.get("retry-after"));
-    const delay =
-      Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
-        ? Math.min(retryAfterSeconds * 1000, RATE_LIMIT_RETRY_CAP_MS)
-        : 100 * attempt;
-    await new Promise((resolve) => setTimeout(resolve, delay));
-    response = await fetch(fetchUrl, options);
-  }
-
-  return response;
-}
-
-function mergeHeaders(base: Headers, overrides?: RequestInit["headers"]): Headers {
-  const merged = new Headers(base);
-  new Headers(overrides).forEach((value, key) => {
-    merged.set(key, value);
-  });
-  return merged;
-}
-
-function createRpcLink(config: RpcClientConfig, headers?: Headers) {
-  return new RPCLink({
-    origin: config.hostUrl,
-    url: config.path,
-    interceptors: [
-      onError((error: unknown) => {
-        const browserWindow = (globalThis as { window?: unknown }).window;
-        if (typeof browserWindow === "undefined") {
-          return;
-        }
-
-        if (error && typeof error === "object" && "message" in error) {
-          const message = String(error.message).toLowerCase();
-          if (
-            message.includes("fetch") ||
-            message.includes("network") ||
-            message.includes("failed to fetch")
-          ) {
-            void import("sonner")
-              .then(({ toast }) => {
-                const message = config.connectionError?.() ?? {
-                  title: "Unable to connect to API",
-                  description: "The API is currently unavailable. Please try again later.",
-                };
-                toast.error(message.title, {
-                  id: "api-connection-error",
-                  description: message.description,
-                });
-              })
-              .catch(() => {});
-          }
-        }
-      }),
-    ],
-    fetch(fetchUrl: FetchInput, options?: RequestInit) {
-      return fetchWithRateLimitRetry(fetchUrl, {
-        ...options,
-        credentials: "include",
-        headers: headers ? mergeHeaders(headers, options?.headers) : options?.headers,
-      });
-    },
-  });
-}
-
-function buildRpcClient<T extends RouterContract>(
-  config: RpcClientConfig,
-  headers?: Headers,
-): ContractRouterClient<T> {
-  if (!config.hostUrl) {
-    throw new Error("Missing runtime host URL");
-  }
-
-  return createORPCClient(createRpcLink(config, headers)) as ContractRouterClient<T>;
-}
-
+/**
+ * Bare typed oRPC client over the RPC protocol — a thin convenience over
+ * `createORPCClient(new RPCLink({ origin, url }))`.
+ *
+ * Promise-native, so async/await callers call it directly and Effect callers
+ * lift calls with `Effect.tryPromise` (owning timeout/retry/cache in their
+ * service layer). Transport customization (headers, timeouts, retries, test
+ * doubles) is RPCLink's native surface — construct the link yourself and pass
+ * it to `createORPCClient` instead of growing config here.
+ */
 export function createRpcClient<T extends RouterContract = RouterContract>(
-  config: RpcClientConfig,
-  headers?: Headers,
+  hostUrl: string,
+  path: `/${string}` = "/api/rpc",
 ): ContractRouterClient<T> {
-  const browserWindow = (globalThis as { window?: unknown }).window;
-  if (typeof browserWindow !== "undefined" && !headers) {
-    const key = `${config.hostUrl}${config.path}`;
-    const memoized = browserClients.get(key);
-    if (memoized) {
-      return memoized as ContractRouterClient<T>;
-    }
-
-    const client = buildRpcClient<T>(config, headers);
-    browserClients.set(key, client);
-    return client;
-  }
-
-  return buildRpcClient<T>(config, headers);
+  return createORPCClient(new RPCLink({ origin: hostUrl, url: path })) as ContractRouterClient<T>;
 }

package/src/errors.ts

@@ -68,6 +68,14 @@ export const NOT_FOUND = {
   }),
 } as const;
 
+export const CONFLICT = {
+  status: 409,
+  data: z.object({
+    resource: z.string().optional(),
+    detail: z.string().optional(),
+  }),
+} as const;
+
 export const FORBIDDEN = {
   status: 403,
   data: z.object({
@@ -105,6 +113,7 @@ export const PluginErrors = {
   SERVICE_UNAVAILABLE,
   BAD_REQUEST,
   NOT_FOUND,
+  CONFLICT,
   FORBIDDEN,
   TIMEOUT,
   CONNECTION_ERROR,
@@ -123,6 +132,7 @@ export const PLUGIN_ERROR_STATUS_MAP: Record<string, number> = {
   ...COMMON_ERROR_STATUS_MAP,
   TIMEOUT: 504,
   CONNECTION_ERROR: 502,
+  CONFLICT: 409,
 } as const;
 
 export type { PluginLoadFailureInfo, PluginWarningInfo } from "./runtime/errors";

package/src/index.ts

@@ -12,6 +12,7 @@ export { getNormalizedRemoteName } from "./runtime/services/normalize";
 export type {
   AnyPlugin,
   EveryPlugin,
+  InferRegistryFromEntries,
   InitializedPlugin,
   LoadedPlugin,
   ModuleClientEntry,
@@ -27,6 +28,7 @@ export type {
   PluginInstance,
   PluginMetadata,
   PluginRegistry,
+  PluginRegistryEntry,
   PluginRouterType,
   PluginRuntimeConfig,
   PluginSecrets,

package/src/ui/manifest/construct.ts

@@ -1,9 +1,9 @@
 import type { AnyRoute } from "@tanstack/react-router";
-import { createRootRoute, createRoute, Outlet, redirect } from "@tanstack/react-router";
+import { createRootRoute, createRoute, Outlet } from "@tanstack/react-router";
 import { CORE_UI_PLUGIN_KEY } from "./contract";
 import { digestOf } from "./descriptor";
 import type { PluginManifest, RouteRecord } from "./manifest-schema";
-import { MOUNT_REGISTRY, type MountDef, type MountId, resolveMountSegment } from "./mount-registry";
+import { MOUNT_REGISTRY, type MountId, resolveMountSegment } from "./mount-registry";
 import { compareNavItems, type NavDeclaration, type NavItem, type NavManifest } from "./nav";
 import { ROUTE_OPTION_KEYS, type RouteConfigModule, type RouteOptionsBundle } from "./route-config";
 
@@ -11,9 +11,10 @@ import { ROUTE_OPTION_KEYS, type RouteConfigModule, type RouteOptionsBundle } fr
  * Host-side route-graph construction (ADR 0008 §1): manifests + route
  * configs in → host-built tree out. The host constructs ITS OWN Route
  * objects from validated manifest data via public `createRoute` APIs; no
- * foreign route object is ever mutated. Gates are attached HOST-side from
- * the mount registry — plugins cannot ship a route that escapes its
- * mount's gate because plugins never construct route objects.
+ * foreign route object is ever mutated. Mount guards are ordinary
+ * beforeLoads attached HOST-side from ConstructInput.guards — plugins
+ * cannot ship a route that escapes its mount's guard because plugins never
+ * construct route objects.
  *
  * Mounts are the ONLY cross-source parenting points: a root-level
  * pathless layout file (`_public.tsx`) declares the mount for the whole
@@ -34,57 +35,6 @@ function toAnyRoute(route: unknown): AnyRoute {
   return route as AnyRoute;
 }
 
-export interface GateUser {
-  id: string;
-  name?: string;
-  /** Better Auth user role — "admin" gates the admin mount. */
-  role?: string;
-}
-
-export interface HostContext {
-  user?: GateUser;
-  session?: { user?: GateUser };
-}
-
-type GateFn = (args: {
-  context: HostContext;
-  location: { pathname: string; searchStr: string };
-}) => void;
-
-/**
- * Gate redirects are absolute: gates attach to root-level mount routes, and
- * relatives would silently shift if a mount ever moved deeper in the tree.
- * The login surface is plugin-owned, never core-known.
- */
-const LOGIN_TO: string = "/login";
-const HOME_TO: string = "/";
-
-/**
- * Gate implementations by mount gate kind. Only `session` and `admin` are
- * implemented (ADR 0008 §3); unimplemented mounts are rejected during mount
- * declaration before any gate lookup, and gates are optional by type — a
- * mount without an entry (or `none`) renders ungated.
- */
-const GATES: Partial<Record<MountDef["gate"], GateFn>> = {
-  session: ({ context, location }) => {
-    const user = userOf(context);
-    if (!user) {
-      throw redirect({
-        to: LOGIN_TO,
-        search: { redirect: location.pathname + location.searchStr } as never,
-      });
-    }
-  },
-  admin: ({ context }) => {
-    const user = userOf(context);
-    if (!user) throw redirect({ to: LOGIN_TO });
-    if (user.role !== "admin") throw redirect({ to: HOME_TO });
-  },
-};
-
-const userOf = (context: HostContext | undefined): GateUser | undefined =>
-  context?.user ?? context?.session?.user;
-
 export interface ConstructPluginRef {
   /** composition identity — plugin key; participates in the digest */
   key: string;
@@ -104,6 +54,8 @@ export interface ConstructInput {
   resolve: (ref: ConstructPluginRef) => Promise<ResolvedPlugin>;
   /** core ui `__root` options — component/error/notFound + head baseline */
   rootOptions?: RouteOptionsBundle;
+  /** Guard per mount id — beforeLoads supplied by the composing framework. */
+  guards?: Partial<Record<MountId, RouteOptionsBundle["beforeLoad"]>>;
 }
 
 export interface ConstructedTree {
@@ -139,17 +91,17 @@ const navOf = (options: RouteOptionsBundle): NavDeclaration | undefined => {
 };
 
 /** Layout routes (mount or pathless) pass their authored options through,
- * like every other route kind. On mount routes the registry gate composes
+ * like every other route kind. On mount routes the mount's guard composes
  * BEFORE the declaration's own beforeLoad so a source can never escape its
- * mount's gate (ADR 0008 §3), while the declaration's return value still
+ * mount's guard (ADR 0008 §3), while the declaration's return value still
  * flows to children as route context. */
 function layoutBeforeLoad(
-  gate: GateFn | undefined,
+  guard: RouteOptionsBundle["beforeLoad"],
   declared: RouteOptionsBundle["beforeLoad"],
 ): RouteOptionsBundle["beforeLoad"] {
-  if (!gate) return declared;
-  return (args) => {
-    gate(args);
+  if (!guard) return declared;
+  return async (args) => {
+    await guard(args);
     return declared?.(args);
   };
 }
@@ -270,13 +222,16 @@ export async function constructTree(input: ConstructInput): Promise<ConstructedT
     const declaration = declarations.get(mountId);
     if (!declaration) continue;
     const def = MOUNT_REGISTRY[mountId]!;
-    const gate = GATES[def.gate];
+    const guard = input.guards?.[mountId];
+    if (def.guarded && !guard) {
+      throw new Error(`mount "${mountId}" requires a guard — add one to ConstructInput.guards`);
+    }
     const options = declaration.options;
     const route = createRoute({
       id: `__mount_${mountId}`,
       getParentRoute: () => rootRoute,
-      ...(gate || options.beforeLoad
-        ? { beforeLoad: layoutBeforeLoad(gate, options.beforeLoad) }
+      ...(guard || options.beforeLoad
+        ? { beforeLoad: layoutBeforeLoad(guard, options.beforeLoad) }
         : {}),
       ...authoredOptions(options),
       component: options.component ?? Outlet,

package/src/ui/manifest/index.ts

@@ -10,8 +10,6 @@ export {
   type ConstructInput,
   type ConstructPluginRef,
   constructTree,
-  type GateUser,
-  type HostContext,
   type ResolvedPlugin,
 } from "./construct";
 export * from "./contract";

package/src/ui/manifest/mount-registry.ts

@@ -1,40 +1,40 @@
 /**
- * Mount registry v2 — gates only, shape-free (ADR 0008 §3).
+ * Mount registry v2 — shape-free (ADR 0008 §3).
  *
- * A mount is a gate + a host-owned pathless layout position. It carries no
- * product semantics (no "dashboard", no shell, no chrome) — plugins bring
- * their own layouts and route freely inside their subtree. A mount is
- * declared by a ROOT-level pathless layout file whose `_`-prefixed segment
- * names the mount (`_public.tsx` → `public`); the generator derives it and
- * validates it against this registry; gates are attached HOST-side at
- * construction, so a plugin cannot ship a route that escapes its mount's
- * gate (plugins never construct route objects).
+ * A mount is a host-owned pathless layout position. It carries no product
+ * semantics (no "dashboard", no shell, no chrome) — plugins bring their own
+ * layouts and route freely inside their subtree. A mount is declared by a
+ * ROOT-level pathless layout file whose `_`-prefixed segment names the mount
+ * (`_public.tsx` → `public`); the generator derives it and validates it
+ * against this registry; guards are ordinary beforeLoads attached HOST-side
+ * at construction from ConstructInput.guards, so a plugin cannot ship a
+ * route that escapes its mount's guard (plugins never construct route
+ * objects).
  *
- * `org`/`team` are declared vocabulary (parameterized membership gates) but
+ * `org`/`team` are declared vocabulary (parameterized membership) but
  * unimplemented — construction rejects them until they land.
  */
 
 export interface MountDef {
-  label: string;
-  gate: "none" | "session" | "admin" | "organization" | "team";
-  parameterized?: boolean;
+  /** The composing framework supplies this mount's guard via ConstructInput.guards. */
+  guarded: boolean;
   implemented: boolean;
 }
 
 export const MOUNT_REGISTRY = {
-  public: { label: "public", gate: "none", implemented: true },
-  authenticated: { label: "authenticated", gate: "session", implemented: true },
-  admin: { label: "admin", gate: "admin", implemented: true },
-  org: { label: "org", gate: "organization", parameterized: true, implemented: false },
-  team: { label: "team", gate: "team", parameterized: true, implemented: false },
-} satisfies Record<string, MountDef>;
+  public: { guarded: false, implemented: true },
+  authenticated: { guarded: true, implemented: true },
+  admin: { guarded: true, implemented: true },
+  org: { guarded: true, implemented: false },
+  team: { guarded: true, implemented: false },
+} as const satisfies Record<string, MountDef>;
 
 export type MountId = Extract<keyof typeof MOUNT_REGISTRY, string>;
 
 export const MOUNTS = Object.keys(MOUNT_REGISTRY) as MountId[];
 
 /** Bump when the registry shape changes — invalidates all compose digests. */
-export const MOUNT_REGISTRY_VERSION = 5;
+export const MOUNT_REGISTRY_VERSION = 6;
 
 /** Migration aliases: legacy `_`-segment names → canonical mounts. */
 export const MOUNT_ALIASES: Record<string, MountId> = {

package/src/version-manifest.ts

@@ -12,10 +12,38 @@ import { z } from "zod";
 
 const SRI = z.string().regex(/^sha384-[A-Za-z0-9+/=]+$/);
 
+/** Slot-relative directory holding one deploy's immutable file copies (#826). */
+export const VERSION_DIR_PATTERN = /^versions\/[0-9a-f]{16}$/;
+
+/** The attribution block stored in the manifest's `signature` field. The
+ * verifying key rides along so a verifier can distinguish "wrong signature"
+ * from "signed by a key the config never registered" — both are
+ * `SignatureInvalid`, but the reasons name different compromises. */
+export const ManifestSignatureSchema = z.object({
+  algorithm: z.literal("ed25519"),
+  /** NEAR-format verifying key (`ed25519:<base58>`) — must equal the
+   * config's `publish.verification.publicKey`. */
+  publicKey: z.string().min(1),
+  /** base64 ed25519 signature over the canonical payload bytes. */
+  value: z.string().min(1),
+});
+export type ManifestSignature = z.infer<typeof ManifestSignatureSchema>;
+
 export const WorkspaceVersionManifestSchema = z.object({
   version: z.string().regex(/^[0-9a-f]{16}$/),
   builtAt: z.string().optional(),
   gitSha: z.string().optional(),
+  /**
+   * Slot-relative directory (`versions/<dirId>`) holding this deploy's
+   * byte-immutable copies of every dist file (#826). When present, all
+   * artifact coordinates below resolve against `<slotBase>/<dir>/` — so a
+   * pinned child's entry fetches its expose chunk and chunks from the same
+   * frozen directory instead of the mutable slot root. Absent on legacy
+   * manifests: coordinates resolve against the slot root exactly as before.
+   * Derived from the `files` map (see `versionDirPath`), so it participates
+   * in the version hash without circularity.
+   */
+  dir: z.string().regex(VERSION_DIR_PATTERN).optional(),
   entry: z.string().min(1),
   entryIntegrity: SRI,
   ssr: z
@@ -55,9 +83,47 @@ export const WorkspaceVersionManifestSchema = z.object({
       integrity: SRI,
     })
     .optional(),
+  /**
+   * Attribution (ADR 0046 ticket 05): the deploy train's ed25519 signature
+   * over `signaturePayloadOf(this document)` — SRI attests WHAT the bytes
+   * are, the signature attests WHO published them, with the verifying key
+   * anchored in the on-chain config (`publish.verification`). Absent on
+   * rollouts with attribution off; readers that predate the field ignore it
+   * (zod strips unknown keys). Excluded from the version-id derivation —
+   * like `builtAt`, it is not a coordinate of the build.
+   */
+  signature: ManifestSignatureSchema.optional(),
 });
 export type WorkspaceVersionManifest = z.infer<typeof WorkspaceVersionManifestSchema>;
 
+/** Canonical key-sorted JSON serialization — the same form the version-id
+ * derivation hashes (undefined-valued entries dropped). Exported so the
+ * signature payload and the version id can never disagree about what
+ * "canonical" means. */
+export function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.entries(value)
+      .filter(([, v]) => v !== undefined)
+      .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+      .sort()
+      .join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+
+/**
+ * The bytes a manifest signature attests: the document minus its reserved
+ * `signature` field, canonically serialized (key-sorted — the version-id
+ * rule). The signer signs this before the field exists; the verifier
+ * re-derives it from the parsed document, so the stored document's
+ * whitespace never matters.
+ */
+export function signaturePayloadOf(manifest: WorkspaceVersionManifest): string {
+  const { signature: _signature, ...payload } = manifest;
+  return stableStringify(payload);
+}
+
 /** A published-artifact coordinate: object path within the bundle namespace + its served SRI. */
 export type SourceRef = NonNullable<WorkspaceVersionManifest["source"]>;
 
@@ -67,6 +133,7 @@ export interface VersionManifestInput {
    * staged copy and the CDN's immutability for republished versions. */
   builtAt?: string;
   gitSha?: string;
+  dir?: string;
   entry: string;
   entryIntegrity: string;
   ssr?: { entry: string; integrity: string };
@@ -93,14 +160,14 @@ export function composeVersionManifest(input: VersionManifestInput): WorkspaceVe
   return WorkspaceVersionManifestSchema.parse({ ...input, version });
 }
 
-function stableStringify(value: unknown): string {
-  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
-  if (value && typeof value === "object") {
-    return `{${Object.entries(value)
-      .filter(([, v]) => v !== undefined)
-      .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
-      .sort()
-      .join(",")}}`;
-  }
-  return JSON.stringify(value) ?? "null";
+/**
+ * The content-addressed directory name for one dist's file set (#826): a
+ * 16-hex hash over the canonical files map. Identical bytes → identical
+ * directory → re-deploying unchanged content is a server-side no-op, and a
+ * published pin's directory can never be rewritten by a later deploy
+ * (the upload service refuses conflicting writes under `versions/`).
+ */
+export function versionDirPath(files: Record<string, string>): string {
+  const id = createHash("sha256").update(stableStringify(files)).digest("hex").slice(0, 16);
+  return `versions/${id}`;
 }