@patronage/factory-ci 0.2.0 → 1.0.0-alpha.4

package/src/github-app-token.ts

@@ -0,0 +1,162 @@
+import { createSign } from "node:crypto";
+import { readFileSync } from "node:fs";
+
+/**
+ * Minting a GitHub App installation token: the RS256 app JWT, the optional
+ * installation lookup, and the token exchange (#617).
+ *
+ * Two projects had grown the same three steps independently — the factory's
+ * check-run publisher and paitronage's proof-comment publisher — which is the
+ * admitted-on-repetition bar. Only the *mechanism* lives here. Where the
+ * private key comes from, how the app id is configured, and what the token is
+ * then used for stay with each consumer: this module is handed credentials and
+ * returns a token.
+ */
+
+/** The default request budget, matching the factory's other GitHub writes. */
+const DEFAULT_TIMEOUT_MS = 5000;
+
+/** Nine-minute JWT lifetime, backdated a minute against runner clock skew. */
+const JWT_BACKDATE_SECONDS = 60;
+const JWT_LIFETIME_SECONDS = 600;
+
+/**
+ * What a consumer must know to mint: the app id, where the private key is, and
+ * — when it has been recorded — which installation to mint against.
+ *
+ * `installationId` is optional because the installation is discoverable from
+ * the repository. `privateKeyPath` is a path rather than key material so no
+ * consumer has to hold a secret in memory to call this, and so the key-path
+ * convention stays the consumer's.
+ */
+export interface GithubAppCredentials {
+  appId: number | string;
+  installationId?: number;
+  privateKeyPath: string;
+}
+
+/** Carries the HTTP status so a caller can tell a retryable failure apart. */
+export class GitHubApiError extends Error {
+  readonly status: number;
+
+  constructor(status: number, statusText: string) {
+    super(`GitHub API ${status} ${statusText}`);
+    this.name = "GitHubApiError";
+    this.status = status;
+  }
+}
+
+export interface GithubAppTokenOptions {
+  /** Injectable `fetch` (tests, or a caller with its own instrumented one). */
+  fetch?: typeof fetch;
+  /** Wall clock in milliseconds; only the JWT's validity window uses it. */
+  now?: () => number;
+  /** Injectable key read, so a caller can hold the PEM itself if it must. */
+  readPrivateKey?: (privateKeyPath: string) => Buffer | string;
+  /** Per-request timeout; defaults to five seconds. */
+  timeoutMs?: number;
+}
+
+const base64url = (value: Buffer | string): string =>
+  Buffer.from(value).toString("base64url");
+
+/**
+ * The signed app JWT GitHub accepts as `Authorization: Bearer` for the App
+ * endpoints. `iss` is stringified because GitHub accepts either spelling and a
+ * numeric app id must not depend on JSON's number formatting.
+ *
+ * The signature is produced from the key on disk and returned; the key
+ * material itself never leaves this call.
+ */
+export const githubAppJwt = (
+  credentials: GithubAppCredentials,
+  options: Pick<GithubAppTokenOptions, "now" | "readPrivateKey"> = {}
+): string => {
+  const nowMs = (options.now ?? Date.now)();
+  const issuedAt = Math.floor(nowMs / 1000) - JWT_BACKDATE_SECONDS;
+  const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+  const payload = base64url(
+    JSON.stringify({
+      exp: issuedAt + JWT_LIFETIME_SECONDS,
+      iat: issuedAt,
+      iss: String(credentials.appId),
+    })
+  );
+  const unsigned = `${header}.${payload}`;
+  const readKey = options.readPrivateKey ?? readFileSync;
+  const signer = createSign("RSA-SHA256");
+  signer.update(unsigned);
+  signer.end();
+  return `${unsigned}.${signer.sign(readKey(credentials.privateKeyPath), "base64url")}`;
+};
+
+const githubAppJson = async (
+  request: typeof fetch,
+  url: string,
+  jwt: string,
+  method: "GET" | "POST",
+  timeoutMs: number
+): Promise<Record<string, unknown>> => {
+  const response = await request(url, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${jwt}`,
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+    method,
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!response.ok) {
+    throw new GitHubApiError(response.status, response.statusText);
+  }
+  return (await response.json()) as Record<string, unknown>;
+};
+
+/**
+ * Mint an installation access token for one repository.
+ *
+ * When the credentials omit `installationId`, the installation is discovered
+ * from the repository first — the same call every consumer had written for
+ * itself. Nothing is cached: the token is returned to the caller and this
+ * module keeps no copy.
+ */
+export const mintInstallationToken = async (
+  input: {
+    credentials: GithubAppCredentials;
+    owner: string;
+    repo: string;
+  },
+  options: GithubAppTokenOptions = {}
+): Promise<string> => {
+  const { credentials } = input;
+  const request = options.fetch ?? fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const jwt = githubAppJwt(credentials, options);
+
+  let { installationId } = credentials;
+  if (installationId === undefined) {
+    const installation = await githubAppJson(
+      request,
+      `https://api.github.com/repos/${input.owner}/${input.repo}/installation`,
+      jwt,
+      "GET",
+      timeoutMs
+    );
+    if (typeof installation.id !== "number") {
+      throw new TypeError("GitHub App installation response omitted id");
+    }
+    installationId = installation.id;
+  }
+
+  const minted = await githubAppJson(
+    request,
+    `https://api.github.com/app/installations/${installationId}/access_tokens`,
+    jwt,
+    "POST",
+    timeoutMs
+  );
+  if (typeof minted.token !== "string") {
+    throw new TypeError("GitHub App token response omitted token");
+  }
+  return minted.token;
+};

package/src/index.ts

@@ -36,6 +36,13 @@ export {
   type SetupNodeStepOptions,
   type WorkflowStep,
 } from "./factory-workflow.ts";
+export {
+  GitHubApiError,
+  type GithubAppCredentials,
+  githubAppJwt,
+  type GithubAppTokenOptions,
+  mintInstallationToken,
+} from "./github-app-token.ts";
 export {
   type ExecuteAlchemyEntryOptions,
   type ExecuteAlchemyEntryResult,
@@ -64,3 +71,9 @@ export {
   type ProofReuseCoverageReport,
   proofReuseRequiredCommands,
 } from "./proof-reuse-gate.ts";
+export {
+  assertWorkflowShellParses,
+  workflowRunBlocks,
+  type WorkflowShellParseFailure,
+  workflowShellParseFailures,
+} from "./workflow-shell-lint.ts";

package/src/proof-reuse-gate.ts

@@ -193,9 +193,11 @@ const isProofReuseCommand = (value: unknown): value is ProofReuseCommand => {
  *
  * `undefined` means the selection is unusable — not an array, empty, or
  * carrying an entry whose `command` is blank or whose `name` is not a plain
- * command identity. An empty required set would make *every* passing proof
- * trivially covering, so it is never silently treated as "requires nothing";
- * callers must refuse instead.
+ * command identity, or carrying duplicate names. A name is the executable
+ * authorization identity recorded in proof, so two commands may never collapse
+ * behind one. An empty required set would make *every* passing proof trivially
+ * covering, so it is never silently treated as "requires nothing"; callers
+ * must refuse instead.
  */
 export const proofReuseRequiredCommands = (
   commands: readonly ProofReuseCommand[]
@@ -206,7 +208,11 @@ export const proofReuseRequiredCommands = (
   if (!commands.every(isProofReuseCommand)) {
     return;
   }
-  return [...new Set(commands.map(({ name }) => name))].toSorted();
+  const names = commands.map(({ name }) => name);
+  if (new Set(names).size !== names.length) {
+    return;
+  }
+  return names.toSorted();
 };
 
 /**
@@ -579,10 +585,8 @@ export interface ProofReuseCoverageInput {
   /** The same selection handed to the gate for this surface. */
   readonly commands: readonly ProofReuseCommand[];
   /**
-   * Skipped work covered under a different command string, keyed by the
-   * skipped string with the reason as its value. Deliberately explicit: a
-   * prose rationale for why some narrower command is "equivalent enough" is
-   * exactly what this assertion exists to force into the open.
+   * @deprecated Ignored. Consumer prose cannot authorize executable coverage;
+   * retained only so the 0.2.1 security patch remains source-compatible.
    */
   readonly equivalents?: Readonly<Record<string, string>>;
   /**
@@ -617,7 +621,6 @@ export interface ProofReuseCoverageReport {
  */
 export const proofReuseCoverage = ({
   commands,
-  equivalents = {},
   skipped,
 }: ProofReuseCoverageInput): ProofReuseCoverageReport => {
   const requiredCommands = proofReuseRequiredCommands(commands) ?? [];
@@ -630,15 +633,7 @@ export const proofReuseCoverage = ({
     ...new Set(
       (Array.isArray(skipped) ? skipped : [])
         .map((command) => String(command).trim())
-        .filter(
-          (command) =>
-            command.length > 0 &&
-            // `Object.hasOwn`, never `in`: `in` walks the prototype chain, so
-            // a skipped command named `toString` or `constructor` would report
-            // itself as a declared equivalent of nothing. This assertion's only
-            // job is to fail loudly.
-            !(proven.has(command) || Object.hasOwn(equivalents, command))
-        )
+        .filter((command) => command.length > 0 && !proven.has(command))
     ),
   ].toSorted();