@valbuild/cli 0.132.1 → 0.134.0

package/src/publish/credentials.test.ts

@@ -0,0 +1,348 @@
+import fs from "fs";
+import http from "http";
+import os from "os";
+import path from "path";
+import { resolvePublishCredential } from "./credentials";
+
+/**
+ * A fake content service.
+ *
+ * `val publish` talks to content and to nothing else, so a fake that answers
+ * content's routes is the whole world the command needs - no loader, no
+ * storage, no credential that has to be real. It records what it was asked so a
+ * test can assert on the headers, which is where the interesting rules live:
+ * the personal access token goes in `x-val-pat` and never anywhere else.
+ */
+type FakeContent = {
+  url: string;
+  requests: Array<{
+    method: string;
+    url: string;
+    headers: http.IncomingHttpHeaders;
+  }>;
+  close: () => Promise<void>;
+};
+
+async function startFakeContent(
+  handler: (req: http.IncomingMessage, res: http.ServerResponse) => void,
+): Promise<FakeContent> {
+  const requests: FakeContent["requests"] = [];
+  const server = http.createServer((req, res) => {
+    requests.push({
+      method: req.method ?? "",
+      url: req.url ?? "",
+      headers: req.headers,
+    });
+    handler(req, res);
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const address = server.address();
+  if (address === null || typeof address === "string") {
+    throw new Error("Fake content service did not get a port");
+  }
+  return {
+    url: `http://127.0.0.1:${address.port}`,
+    requests,
+    close: () =>
+      new Promise<void>((resolve, reject) =>
+        server.close((err) => (err ? reject(err) : resolve())),
+      ),
+  };
+}
+
+function json(res: http.ServerResponse, statusCode: number, body: unknown) {
+  res.writeHead(statusCode, { "Content-Type": "application/json" });
+  res.end(JSON.stringify(body));
+}
+
+/** A project root, optionally holding the file `val login` writes. */
+function makeRoot(pat?: string): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "val-publish-"));
+  if (pat !== undefined) {
+    fs.mkdirSync(path.join(root, ".val"), { recursive: true });
+    fs.writeFileSync(
+      path.join(root, ".val", "pat.json"),
+      JSON.stringify({ pat }),
+    );
+  }
+  return root;
+}
+
+const A_PAT = "a".repeat(64);
+
+describe("the publish credential", () => {
+  test("VAL_PROJECT_TOKEN is used as it is, without an exchange", async () => {
+    const content = await startFakeContent((_req, res) => {
+      json(res, 500, { statusCode: 500, message: "should not be called" });
+    });
+    try {
+      const resolved = await resolvePublishCredential({
+        root: makeRoot(A_PAT),
+        project: "acme/site",
+        env: {
+          VAL_PROJECT_TOKEN: "val_pt_deadbeef",
+          VAL_CONTENT_URL: content.url,
+        },
+      });
+
+      expect(resolved).toEqual({
+        status: "ok",
+        credential: {
+          token: "val_pt_deadbeef",
+          origin: "VAL_PROJECT_TOKEN",
+          expiresAt: null,
+        },
+      });
+      // The token names its project, so there is nothing to ask and nobody to
+      // ask it of. A repository that holds one secret holds no variables.
+      expect(content.requests).toEqual([]);
+    } finally {
+      await content.close();
+    }
+  });
+
+  test("an unset CI secret reads as no credential, not as a bad one", async () => {
+    // An unset secret reaches the job as "", and "" presented to content is a
+    // 401 that sends the reader looking for a revoked token.
+    const resolved = await resolvePublishCredential({
+      root: makeRoot(),
+      project: "acme/site",
+      env: { VAL_PROJECT_TOKEN: "   " },
+    });
+
+    expect(resolved.status).toBe("error");
+    if (resolved.status === "error") {
+      expect(resolved.message).toContain("VAL_PROJECT_TOKEN");
+      expect(resolved.message).toContain("val login");
+    }
+  });
+
+  test("a personal access token pasted into VAL_PROJECT_TOKEN is named as one", async () => {
+    const resolved = await resolvePublishCredential({
+      root: makeRoot(),
+      project: "acme/site",
+      env: { VAL_PROJECT_TOKEN: A_PAT },
+    });
+
+    expect(resolved.status).toBe("error");
+    if (resolved.status === "error") {
+      expect(resolved.message).toContain("personal access token");
+      expect(resolved.message).toContain("val_pt_");
+    }
+  });
+
+  test("a val login is exchanged for a project token, and the login stays here", async () => {
+    const content = await startFakeContent((req, res) => {
+      if (req.url === "/v1/acme/site/publish-token") {
+        json(res, 200, {
+          token: "val_pt_minted",
+          expiresAt: "2026-09-19T12:10:00.000Z",
+          publicProjectId: "p1",
+          productionUrl: "https://site.example",
+        });
+        return;
+      }
+      json(res, 404, { statusCode: 404, message: "no such route" });
+    });
+    try {
+      const resolved = await resolvePublishCredential({
+        root: makeRoot(A_PAT),
+        project: "acme/site",
+        env: { VAL_CONTENT_URL: content.url },
+      });
+
+      expect(resolved).toEqual({
+        status: "ok",
+        credential: {
+          token: "val_pt_minted",
+          origin: "val login",
+          expiresAt: "2026-09-19T12:10:00.000Z",
+        },
+      });
+      expect(content.requests).toHaveLength(1);
+      const [request] = content.requests;
+      expect(request.method).toBe("POST");
+      expect(request.url).toBe("/v1/acme/site/publish-token");
+      // The person's credential is presented to val.build and to nothing
+      // further: what publishes is the ten minute token that came back.
+      expect(request.headers["x-val-pat"]).toBe(A_PAT);
+      expect(request.headers.authorization).toBeUndefined();
+    } finally {
+      await content.close();
+    }
+  });
+
+  test("a trailing slash on VAL_CONTENT_URL does not double the path", async () => {
+    const content = await startFakeContent((req, res) => {
+      if (req.url === "/v1/acme/site/publish-token") {
+        // The whole answer, as `Api["/publish-token"]["POST"]["res"]` declares
+        // it. A fixture that sends less is a fixture testing a service that
+        // does not exist.
+        json(res, 200, {
+          token: "val_pt_minted",
+          expiresAt: null,
+          publicProjectId: "p1",
+          productionUrl: null,
+        });
+        return;
+      }
+      json(res, 404, { statusCode: 404, message: "no such route" });
+    });
+    try {
+      const resolved = await resolvePublishCredential({
+        root: makeRoot(A_PAT),
+        project: "acme/site",
+        env: { VAL_CONTENT_URL: `${content.url}/` },
+      });
+
+      expect(resolved.status).toBe("ok");
+      expect(content.requests[0].url).toBe("/v1/acme/site/publish-token");
+    } finally {
+      await content.close();
+    }
+  });
+
+  test("a login with no project says which of the two is missing", async () => {
+    const resolved = await resolvePublishCredential({
+      root: makeRoot(A_PAT),
+      project: null,
+      env: {},
+    });
+
+    expect(resolved.status).toBe("error");
+    if (resolved.status === "error") {
+      expect(resolved.message).toContain("VAL_PROJECT");
+      expect(resolved.message).toContain("val.config");
+    }
+  });
+
+  test("an expired login says to log in again, not that the project is wrong", async () => {
+    const content = await startFakeContent((_req, res) => {
+      json(res, 401, { statusCode: 401, message: "Invalid token" });
+    });
+    try {
+      const resolved = await resolvePublishCredential({
+        root: makeRoot(A_PAT),
+        project: "acme/site",
+        env: { VAL_CONTENT_URL: content.url },
+      });
+
+      expect(resolved.status).toBe("error");
+      if (resolved.status === "error") {
+        expect(resolved.message).toContain("val login");
+      }
+    } finally {
+      await content.close();
+    }
+  });
+
+  test("a refusal keeps the sentence content wrote", async () => {
+    const content = await startFakeContent((_req, res) => {
+      json(res, 403, {
+        statusCode: 403,
+        message: "Your role in this organization may not publish",
+      });
+    });
+    try {
+      const resolved = await resolvePublishCredential({
+        root: makeRoot(A_PAT),
+        project: "acme/site",
+        env: { VAL_CONTENT_URL: content.url },
+      });
+
+      expect(resolved.status).toBe("error");
+      if (resolved.status === "error") {
+        expect(resolved.message).toContain(
+          "Your role in this organization may not publish",
+        );
+        expect(resolved.message).toContain("acme/site");
+      }
+    } finally {
+      await content.close();
+    }
+  });
+
+  test("the old names are still read, after a login and before failing", async () => {
+    // This repository's own CI still passes VAL_APP_TOKEN, and a rename that
+    // breaks the publisher is a rename that gets reverted. Content says what
+    // it thinks of the value; that is not this function's call to make.
+    const resolved = await resolvePublishCredential({
+      root: makeRoot(),
+      project: "acme/site",
+      env: { VAL_APP_TOKEN: "val_pt_old" },
+    });
+
+    expect(resolved).toEqual({
+      status: "ok",
+      credential: {
+        token: "val_pt_old",
+        origin: "VAL_APP_TOKEN",
+        expiresAt: null,
+      },
+    });
+  });
+
+  test("a login is preferred to the old names", async () => {
+    const content = await startFakeContent((req, res) => {
+      if (req.url === "/v1/acme/site/publish-token") {
+        // The whole answer, as `Api["/publish-token"]["POST"]["res"]` declares
+        // it. A fixture that sends less is a fixture testing a service that
+        // does not exist.
+        json(res, 200, {
+          token: "val_pt_minted",
+          expiresAt: null,
+          publicProjectId: "p1",
+          productionUrl: null,
+        });
+        return;
+      }
+      json(res, 404, { statusCode: 404, message: "no such route" });
+    });
+    try {
+      const resolved = await resolvePublishCredential({
+        root: makeRoot(A_PAT),
+        project: "acme/site",
+        env: { VAL_APP_TOKEN: "val_pt_old", VAL_CONTENT_URL: content.url },
+      });
+
+      expect(resolved.status).toBe("ok");
+      if (resolved.status === "ok") {
+        expect(resolved.credential.token).toBe("val_pt_minted");
+      }
+    } finally {
+      await content.close();
+    }
+  });
+
+  test("no credential at all names both ways of having one", async () => {
+    const resolved = await resolvePublishCredential({
+      root: makeRoot(),
+      project: "acme/site",
+      env: {},
+    });
+
+    expect(resolved.status).toBe("error");
+    if (resolved.status === "error") {
+      expect(resolved.message).toContain("VAL_PROJECT_TOKEN");
+      expect(resolved.message).toContain("val login");
+    }
+  });
+
+  test("an unreadable login file is a fixable error, not a fall through", async () => {
+    const root = makeRoot();
+    fs.mkdirSync(path.join(root, ".val"), { recursive: true });
+    fs.writeFileSync(path.join(root, ".val", "pat.json"), "{ not json");
+
+    const resolved = await resolvePublishCredential({
+      root,
+      project: "acme/site",
+      env: {},
+    });
+
+    expect(resolved.status).toBe("error");
+    if (resolved.status === "error") {
+      expect(resolved.message).toContain("pat.json");
+      expect(resolved.message).toContain("val login");
+    }
+  });
+});

package/src/publish/credentials.ts

@@ -0,0 +1,258 @@
+import fs from "fs";
+import {
+  getPersonalAccessTokenPath,
+  parsePersonalAccessTokenFile,
+} from "@valbuild/server";
+import { ContentHostError, getContentHost, postJson } from "./contentHost";
+import { PublishProtocolError, parsePublishToken } from "./protocol";
+
+/**
+ * The credential `val publish` presents to content, and where it came from.
+ *
+ * Whatever the publisher started with, this is a *project* token: it can do one
+ * thing to one project. A personal access token is a person's credential -
+ * org-wide, read and write on every project they can reach - so it never
+ * travels further than val.build, which exchanges it for one of these.
+ */
+export type PublishCredential = {
+  /** Presented as `Authorization: Bearer`. Never logged, never in argv. */
+  token: string;
+  /**
+   * Which of the ways below produced it. For messages only: "your login
+   * expired" and "the repository's token was revoked" have different fixes and
+   * different people to tell.
+   */
+  origin: "VAL_PROJECT_TOKEN" | "val login" | "VAL_APP_TOKEN";
+  /** ISO 8601, or null for a standing token that does not expire. */
+  expiresAt: string | null;
+};
+
+export type ResolvedCredential =
+  | { status: "ok"; credential: PublishCredential }
+  | { status: "error"; message: string };
+
+const NO_CREDENTIAL =
+  "Publishing needs a credential.\n\n" +
+  "  In CI:           set VAL_PROJECT_TOKEN as a repository secret.\n" +
+  "  On your machine: run\n\n" +
+  "      npx val login\n\n" +
+  "Neither is a command line flag, deliberately: an argument is visible to\n" +
+  "anyone who can list processes, and it is kept in shell history and in the\n" +
+  "log of every CI job that echoes its command line.";
+
+/**
+ * The credential, in the order the publisher should prefer them.
+ *
+ * 1. `VAL_PROJECT_TOKEN` from the environment - used as it is, no exchange.
+ *    This is what a repository created by `/new` holds, and the only secret it
+ *    needs: the token names its project, so content can answer *where* to
+ *    publish as well as *whether*.
+ * 2. The `val login` token in `<root>/.val/pat.json` - exchanged first, because
+ *    what publishes must be a project token. The exchange is addressed by org
+ *    and project, since a personal access token does not name one; that is why
+ *    this way needs `project` and the first does not.
+ * 3. Neither, which is not an error we can guess our way out of.
+ *
+ * Returns a result rather than throwing: "no credential" is one of the things a
+ * publisher has to say well, and the sentence differs by which half was missing.
+ */
+export async function resolvePublishCredential(options: {
+  /** Project root - where `.val/pat.json` is looked for. */
+  root: string;
+  /** `"<org>/<project>"`, from val.config or VAL_PROJECT. Only (2) needs it. */
+  project: string | null;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: typeof fetch;
+}): Promise<ResolvedCredential> {
+  const env = options.env ?? process.env;
+  // An unset secret reaches a CI job as the empty string rather than as absent,
+  // and an empty credential presented to content is a 401 that reads as "your
+  // token is bad" instead of "you never set one".
+  const projectToken = env.VAL_PROJECT_TOKEN?.trim();
+  if (projectToken) {
+    if (looksLikePersonalAccessToken(projectToken)) {
+      return {
+        status: "error",
+        message:
+          "VAL_PROJECT_TOKEN looks like a personal access token, not a project\n" +
+          "token. A project token begins with `val_pt_` and is made for one\n" +
+          "project; a personal access token belongs to a person and cannot\n" +
+          "publish. Mint a project token on the project's settings page.",
+      };
+    }
+    return {
+      status: "ok",
+      credential: {
+        token: projectToken,
+        origin: "VAL_PROJECT_TOKEN",
+        // A standing token need not expire, and nothing here has been told
+        // otherwise. Content is where an expiry would come from.
+        expiresAt: null,
+      },
+    };
+  }
+
+  const pat = readPersonalAccessToken(options.root);
+  if (pat.status === "error") {
+    return pat;
+  }
+  if (pat.status === "none") {
+    /*
+     * The old names, still read.
+     *
+     * This is where the api key used to be passed, and this platform's own CI
+     * still passes it: a rename that breaks the publisher is a rename that gets
+     * reverted. It will not be accepted for long - publishing is being taken
+     * out of what an api key may do - and content says so in its own words
+     * when it refuses one, which is a better sentence than a guess here.
+     */
+    const legacy = (env.VAL_APP_TOKEN ?? env.PLATFORM_TOKEN)?.trim();
+    if (legacy) {
+      return {
+        status: "ok",
+        credential: {
+          token: legacy,
+          origin: "VAL_APP_TOKEN",
+          expiresAt: null,
+        },
+      };
+    }
+    return { status: "error", message: NO_CREDENTIAL };
+  }
+
+  if (!options.project) {
+    return {
+      status: "error",
+      message:
+        "You are logged in, but nothing says which project to publish.\n\n" +
+        'Set `project` ("<org>/<project>") in val.config, or the VAL_PROJECT\n' +
+        "environment variable.\n\n" +
+        "A `val login` token belongs to you rather than to a project, so it\n" +
+        "cannot say which one you are standing in.",
+    };
+  }
+  const parts = options.project.split("/");
+  if (parts.length !== 2 || !parts[0] || !parts[1]) {
+    return {
+      status: "error",
+      message: `Invalid project: "${options.project}". Expected "<org>/<project>".`,
+    };
+  }
+  const [orgName, projectName] = parts;
+
+  return exchangePersonalAccessToken({
+    pat: pat.pat,
+    orgName,
+    projectName,
+    env,
+    ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+  });
+}
+
+/**
+ * Trade the token you have for the token that may publish.
+ *
+ * Ten minutes, one project, one scope. The person's identity survives the
+ * exchange even though the credential will not outlive the command, which is
+ * what gives "who published this" an answer afterwards.
+ */
+async function exchangePersonalAccessToken(options: {
+  pat: string;
+  orgName: string;
+  projectName: string;
+  env: NodeJS.ProcessEnv;
+  fetchImpl?: typeof fetch;
+}): Promise<ResolvedCredential> {
+  const host = getContentHost(options.env);
+  const url = `${host}/v1/${encodeURIComponent(
+    options.orgName,
+  )}/${encodeURIComponent(options.projectName)}/publish-token`;
+  let body: unknown;
+  try {
+    body = await postJson({
+      url,
+      headers: { "x-val-pat": options.pat },
+      ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+    });
+  } catch (err) {
+    if (err instanceof ContentHostError) {
+      return {
+        status: "error",
+        message: exchangeFailureMessage(err, options),
+      };
+    }
+    throw err;
+  }
+  let exchanged;
+  try {
+    exchanged = parsePublishToken(body, `POST ${url}`);
+  } catch (err) {
+    if (err instanceof PublishProtocolError) {
+      return { status: "error", message: err.message };
+    }
+    throw err;
+  }
+  return {
+    status: "ok",
+    credential: {
+      token: exchanged.token,
+      origin: "val login",
+      expiresAt: exchanged.expiresAt,
+    },
+  };
+}
+
+function exchangeFailureMessage(
+  err: ContentHostError,
+  options: { orgName: string; projectName: string },
+): string {
+  const project = `${options.orgName}/${options.projectName}`;
+  if (err.statusCode === 401) {
+    return (
+      "Your Val login is no longer valid - it may have expired. Log in again:\n\n" +
+      "    npx val login"
+    );
+  }
+  if (err.statusCode === 403) {
+    return `Your Val account may not publish ${project}: ${err.message}`;
+  }
+  if (err.statusCode === 404) {
+    return (
+      `No project ${project}. Check \`project\` in val.config (or VAL_PROJECT):\n` +
+      "it is the org and project as val.build names them, not the repository."
+    );
+  }
+  return (
+    `Could not get a publish token for ${project}: ${err.message}` +
+    (err.details ? `\n${err.details}` : "")
+  );
+}
+
+/** A personal access token is 32 random bytes as hex, and carries no prefix. */
+function looksLikePersonalAccessToken(token: string): boolean {
+  return /^[0-9a-f]{64}$/i.test(token);
+}
+
+function readPersonalAccessToken(
+  root: string,
+):
+  | { status: "ok"; pat: string }
+  | { status: "none" }
+  | { status: "error"; message: string } {
+  const patFile = getPersonalAccessTokenPath(root);
+  if (!fs.existsSync(patFile)) {
+    return { status: "none" };
+  }
+  const parsed = parsePersonalAccessTokenFile(
+    fs.readFileSync(patFile, "utf-8"),
+  );
+  if (!parsed.success) {
+    return {
+      status: "error",
+      message:
+        `Could not read the Val login at ${patFile}: ${parsed.error}.\n` +
+        "Log in again:\n\n    npx val login",
+    };
+  }
+  return { status: "ok", pat: parsed.data.pat };
+}