@valbuild/server 0.121.0 → 0.123.0

package/dist/declarations/src/valServerConfig.d.ts

@@ -36,22 +36,25 @@ export declare function initHandlerOptions(route: string, opts: ValApiOptions, c
 /**
  * Build the data layer a {@link ValServerConfig} calls for.
  *
- * `auth` decides *whose* credential the http backend sees. Left out, it is the
- * app's own API key — which is what the Studio wants, because there the app has
- * already verified a session cookie and is acting on the user's behalf under its
- * own authority.
+ * The http backend always sees the app's own API key. That is what the Studio
+ * wants — there the app has already verified a session cookie and is acting on
+ * the user's behalf under its own authority — and it is now the only shape:
+ * every caller that reaches here has been authenticated by the app itself, so
+ * there is no request left on which the app is a pipe rather than an authority.
  *
- * A caller acting for a user it has *not* authenticated itself must pass that
- * user's personal access token instead, so the backend is the one that decides
- * what the caller may do. That is the whole of `docs/plans/mcp.md` D.2: the app
- * stops being an authority and goes back to being a pipe. Passing the app's API
- * key on such a request is the D.6 confused deputy, and it is worth being blunt
- * about why it is tempting — it works, and it works for every project the key
- * can reach, including the ones the caller cannot.
+ * This took a parameter for the other case: a caller acting for a user it had
+ * *not* authenticated passed that user's personal access token, and the backend
+ * decided what the caller could do. `ValOpsHttp` still accepts such a token —
+ * the CLI's `debug` command uses the developer's own from `val login` — but no
+ * server request builds one any more, because a request the app cannot
+ * authenticate is now refused instead of relayed.
+ *
+ * What has not changed is why the API key must never stand in for a credential
+ * that was merely *absent*: it works, and it works for every project the key
+ * can reach, including the ones the caller cannot. Callers are refused for a
+ * missing credential well before this point.
  */
-export declare function createValOps(valModules: ValModules, options: ValServerConfig, auth?: {
-    pat: string;
-}): ValOpsFS | ValOpsHttp;
+export declare function createValOps(valModules: ValModules, options: ValServerConfig): ValOpsFS | ValOpsHttp;
 /**
  * Hosts we send credentials to, and what each one puts at risk. They differ:
  * only `valBuildUrl` hands back the app token that becomes the session cookie,
@@ -78,4 +81,41 @@ type CredentialBearingUrl = "valBuildUrl" | "valContentUrl";
  * internal http host today.
  */
 export declare function insecureUrlWarning(name: CredentialBearingUrl, url: string): string | null;
+/**
+ * Which credential talks to the content host about REMOTE FILES.
+ *
+ * A separate question from the one `createValOps` answers, and it has to be:
+ * `ValOps` is authenticated per caller, but remote files are project-level —
+ * looking up a project's public id and its buckets, and later pushing bytes to
+ * them, is the same operation whoever asked for it.
+ *
+ * The rule, in order:
+ *
+ * 1. The app's API key, if there is one. Proxy mode always has one; fs mode has
+ *    one when `VAL_API_KEY` is set.
+ * 2. In fs mode, the developer's own `val login` token, read off disk. This is
+ *    the same file `val validate --fix` reads, and it is why local remote
+ *    uploads work with no configuration beyond having logged in.
+ * 3. Nothing, which is an error rather than a fallback.
+ *
+ * Lives here rather than inside `createValServer` because the MCP image tool
+ * needs the same answer, and this is the file that exists so that two callers
+ * cannot disagree about how a project is configured. A registry that decided it
+ * had no credential while the Studio in the same process had one would be a
+ * genuinely confusing afternoon.
+ */
+export type RemoteFileAuth = {
+    apiKey: string;
+} | {
+    pat: string;
+};
+export type ResolveRemoteFileAuthResult = {
+    status: "success";
+    auth: RemoteFileAuth;
+} | {
+    status: "error";
+    errorCode: "project-not-configured" | "pat-error";
+    message: string;
+};
+export declare function resolveRemoteFileAuth(options: ValServerConfig): Promise<ResolveRemoteFileAuthResult>;
 export {};