@effected/github-actions 0.1.0

package/index.js

@@ -0,0 +1,22 @@
+import { ActionEnvironment, ActionEnvironmentError, GitHubContext, RunnerContext } from "./ActionEnvironment.js";
+import { ActionInput } from "./ActionInput.js";
+import { WorkflowCommand } from "./WorkflowCommand.js";
+import { ActionLogger } from "./ActionLogger.js";
+import { ActionOutputError, ActionOutputs } from "./ActionOutputs.js";
+import { ActionState, ActionStateError } from "./ActionState.js";
+import { Action, ActionRuntime, describeCause } from "./Action.js";
+import { BlobTransferError } from "./BlobTransfer.js";
+import { ActionCache, ActionCacheError } from "./ActionCache.js";
+import { Artifact, ArtifactError } from "./Artifact.js";
+import { BlobEnvelope, BlobEnvelopeError } from "./BlobEnvelope.js";
+import { Secret } from "./Secret.js";
+import { BlobStore, BlobStoreError } from "./BlobStore.js";
+import { GitHubCacheBlobStore } from "./BlobStore.githubCache.js";
+import { CacheKey, CacheKeyError } from "./CacheKey.js";
+import { DetachedProcess, DetachedProcessError, ProcessId } from "./DetachedProcess.js";
+import { DryRun } from "./DryRun.js";
+import { GitHubToken, GitHubTokenError } from "./GitHubToken.js";
+import { OidcClaims, OidcTokenError, OidcTokenIssuer } from "./OidcTokenIssuer.js";
+import { ToolInstaller, ToolInstallerError } from "./ToolInstaller.js";
+
+export { Action, ActionCache, ActionCacheError, ActionEnvironment, ActionEnvironmentError, ActionInput, ActionLogger, ActionOutputError, ActionOutputs, ActionRuntime, ActionState, ActionStateError, Artifact, ArtifactError, BlobEnvelope, BlobEnvelopeError, BlobStore, BlobStoreError, BlobTransferError, CacheKey, CacheKeyError, DetachedProcess, DetachedProcessError, DryRun, GitHubCacheBlobStore, GitHubContext, GitHubToken, GitHubTokenError, OidcClaims, OidcTokenError, OidcTokenIssuer, ProcessId, RunnerContext, Secret, ToolInstaller, ToolInstallerError, WorkflowCommand, describeCause };

package/internal/actionsResults.js

@@ -0,0 +1,98 @@
+import { Effect, Option, Redacted, Result } from "effect";
+
+//#region src/internal/actionsResults.ts
+/**
+* Reading the runner's *results backend* coordinates — the two variables the
+* cache, artifact and blob-store protocols all speak through.
+*
+* @remarks
+* Shared by `ActionCache`, `Artifact` and `BlobStore.githubCache`, and
+* deliberately free of `@azure/storage-blob`: an internal helper is exactly how
+* a heavy import leaks into a light module's graph, so the one piece those
+* three modules share is the piece with no dependencies.
+*
+* @internal
+*/
+/** The variable naming the backend. Absent outside a `uses:` step. */
+const RESULTS_URL = "ACTIONS_RESULTS_URL";
+/** The variable holding the run-scoped credential. Absent outside a `uses:` step. */
+const RUNTIME_TOKEN = "ACTIONS_RUNTIME_TOKEN";
+/**
+* Decode a JWT payload segment.
+*
+* @remarks
+* No signature verification, deliberately and for the same reason
+* `OidcTokenIssuer` gives: the token was handed to this process by the runner
+* that started it, and the claim read here scopes a request rather than
+* authorizing one.
+*/
+const payloadOf = (token) => {
+	const segments = token.split(".");
+	if (segments.length !== 3) throw new Error(`expected a three-segment JWT, got ${segments.length}`);
+	const json = Buffer.from(segments[1] ?? "", "base64url").toString("utf8");
+	return JSON.parse(json);
+};
+/**
+* The run and job ids the artifact protocol needs, from the runtime token's
+* `scp` claim.
+*
+* @remarks
+* The scope is space-separated and the interesting entry is
+* `Actions.Results:<run>:<job>`. Exported so its own failures are tested
+* directly rather than through four RPC round trips.
+*
+* @internal
+*/
+const backendIdsFrom = (token) => {
+	let payload;
+	try {
+		payload = payloadOf(token);
+	} catch (cause) {
+		return Result.fail(`the runtime token is not a readable JWT: ${cause instanceof Error ? cause.message : cause}`);
+	}
+	const scope = payload.scp;
+	if (typeof scope !== "string") return Result.fail("the runtime token carries no `scp` claim");
+	for (const entry of scope.split(" ")) {
+		const parts = entry.split(":");
+		if (parts[0] !== "Actions.Results") continue;
+		const run = parts[1];
+		const job = parts[2];
+		if (parts.length !== 3 || run === void 0 || run === "" || job === void 0 || job === "") return Result.fail(`the runtime token's Actions.Results scope is malformed: "${entry}"`);
+		return Result.succeed({
+			workflowRunBackendId: run,
+			workflowJobRunBackendId: job
+		});
+	}
+	return Result.fail("the runtime token carries no `Actions.Results` scope");
+};
+/**
+* Read the results-backend coordinates from the runner environment.
+*
+* @remarks
+* Fails with the *name* of whichever variable is missing. Both are injected
+* only into `uses:` steps, so their absence is the single most common way one
+* of these three services is misused — a caller that reads the name can say so.
+*
+* Takes the environment **shape**, not the service: the layer resolves
+* `ActionEnvironment` once at construction and every member's `R` stays
+* `never`, which is the same fix `ActionEnvironment.payload` got. The variables
+* themselves are read per call, because resolving them at construction would
+* make merely *composing* the layer fail outside Actions — including for an
+* action that never touches the cache.
+*
+* @internal
+*/
+const resultsBackend = (env) => Effect.gen(function* () {
+	const url = yield* env.getOptional(RESULTS_URL);
+	const token = yield* env.getOptional(RUNTIME_TOKEN);
+	if (Option.isNone(url)) return yield* Effect.fail(RESULTS_URL);
+	if (Option.isNone(token)) return yield* Effect.fail(RUNTIME_TOKEN);
+	return {
+		baseUrl: url.value.endsWith("/") ? url.value : `${url.value}/`,
+		token: Redacted.make(token.value),
+		backendIds: backendIdsFrom(token.value)
+	};
+});
+
+//#endregion
+export { RESULTS_URL, RUNTIME_TOKEN, backendIdsFrom, resultsBackend };

package/internal/sigv4.js

@@ -0,0 +1,117 @@
+import { createHash, createHmac } from "node:crypto";
+
+//#region src/internal/sigv4.ts
+/**
+* AWS Signature Version 4, for S3-compatible object stores.
+*
+* @remarks
+* **Pure**, and about a hundred lines, which is the whole argument for not
+* taking an `@aws-sdk/*` dependency to obtain it. Signing is a specified
+* algorithm over strings and HMACs; the SDK around it exists to manage
+* credentials, retries and a service catalogue this package does not want.
+*
+* `node:crypto` rather than core `Crypto` because core's `Crypto` is
+* random-number generation only at beta.101 — no digest, no HMAC. This package
+* is the one place in the kit where a `node:` import is sanctioned, and this is
+* one of the four reasons.
+*
+* @internal
+*/
+const ALGORITHM = "AWS4-HMAC-SHA256";
+const sha256Hex = (value) => createHash("sha256").update(value).digest("hex");
+const hmac = (key, value) => new Uint8Array(createHmac("sha256", key).update(value).digest());
+/**
+* Percent-encode one path segment the way SigV4 requires.
+*
+* @remarks
+* `encodeURIComponent` leaves `!'()*` alone and AWS does not, so a key
+* containing any of them signs one string and requests another — which fails as
+* an opaque `SignatureDoesNotMatch` rather than as anything that names the
+* character. The unreserved set is exactly `A-Za-z0-9-_.~`.
+*/
+const uriEncode = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+/** `20130524T000000Z` and `20130524`, the two forms the algorithm uses. */
+const timestamps = (now) => {
+	const amzDate = `${now.toISOString().replace(/[:-]|\.\d{3}/g, "").slice(0, 15)}Z`;
+	return {
+		amzDate,
+		dateStamp: amzDate.slice(0, 8)
+	};
+};
+/**
+* Assemble the headers that will be signed, and the canonical request over them.
+*
+* @remarks
+* Exported separately from {@link sign} so a test can pin it against AWS's
+* **own documented** canonical request rather than against this
+* implementation's output. That distinction is not pedantry: the first draft of
+* this module was checked against a remembered signature constant that turned
+* out to be from a different example, and the only thing that settled which side
+* was wrong was reproducing a value AWS publishes.
+*/
+const canonicalize = (request, credentials) => {
+	const { amzDate, dateStamp } = timestamps(request.now);
+	const payloadHash = sha256Hex(request.body);
+	const headers = {
+		...request.headers,
+		host: request.host,
+		"x-amz-date": amzDate,
+		"x-amz-content-sha256": payloadHash,
+		...credentials.sessionToken === void 0 ? {} : { "x-amz-security-token": credentials.sessionToken }
+	};
+	const lowered = new Map(Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]));
+	const canonicalNames = [...lowered.keys()].sort();
+	const canonicalHeaders = canonicalNames.map((name) => `${name}:${(lowered.get(name) ?? "").trim().replace(/\s+/g, " ")}\n`).join("");
+	const signedHeaders = canonicalNames.join(";");
+	const canonicalPath = `/${request.path.split("/").filter((segment) => segment !== "").map(uriEncode).join("/")}`;
+	return {
+		headers,
+		signedHeaders,
+		amzDate,
+		dateStamp,
+		canonicalRequest: [
+			request.method,
+			canonicalPath,
+			"",
+			canonicalHeaders,
+			signedHeaders,
+			payloadHash
+		].join("\n")
+	};
+};
+/**
+* Derive a signing key.
+*
+* @remarks
+* Four nested HMACs over date, region, service and the literal `aws4_request`.
+* Exported so a test can reproduce AWS's documented derivation example.
+*/
+const signingKey = (secretAccessKey, dateStamp, region, service) => hmac(hmac(hmac(hmac(`AWS4${secretAccessKey}`, dateStamp), region), service), "aws4_request");
+/**
+* Sign a request, returning the headers to send.
+*
+* @remarks
+* The returned record is the caller's headers **plus** everything signing added
+* — `host`, `x-amz-date`, `x-amz-content-sha256`, the optional
+* `x-amz-security-token` and `authorization` — so a caller sends exactly what
+* was signed rather than assembling a second, subtly different set.
+*/
+const sign = (request, credentials) => {
+	const { headers, canonicalRequest, signedHeaders, amzDate, dateStamp } = canonicalize(request, credentials);
+	const scope = `${dateStamp}/${credentials.region}/${credentials.service}/aws4_request`;
+	const stringToSign = [
+		ALGORITHM,
+		amzDate,
+		scope,
+		sha256Hex(canonicalRequest)
+	].join("\n");
+	const key = signingKey(credentials.secretAccessKey, dateStamp, credentials.region, credentials.service);
+	const signature = Buffer.from(hmac(key, stringToSign)).toString("hex");
+	return {
+		...headers,
+		authorization: `${ALGORITHM} Credential=${credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`
+	};
+};
+
+//#endregion
+export { canonicalize, sign, signingKey, uriEncode };

package/internal/twirp.js

@@ -0,0 +1,97 @@
+import { Effect, Schedule } from "effect";
+import { HttpClientRequest } from "effect/unstable/http";
+
+//#region src/internal/twirp.ts
+/**
+* Returned instead of a failure when the backend answers HTTP 409.
+*
+* @remarks
+* A conflict means "this already exists", which is a success for a save and a
+* miss for a lookup — two different answers that the *caller* has to choose
+* between, so the transport hands back a sentinel rather than deciding.
+*
+* @internal
+*/
+const CONFLICT = Symbol.for("@effected/github-actions/twirp/conflict");
+/**
+* Whether retrying could plausibly help.
+*
+* @remarks
+* A transport fault never completed, so nothing was observed; `408`, `429` and
+* `5xx` are the backend saying "later". Everything else — a `400`, a `403`, a
+* body that is not JSON — is the backend saying "never", and retrying it four
+* times only makes a broken call take half a minute to fail.
+*
+* @internal
+*/
+const isRetryable = (failure) => {
+	if (failure.kind === "transport") return true;
+	if (failure.kind === "malformed" || failure.status === void 0) return false;
+	return failure.status >= 500 || failure.status === 408 || failure.status === 429;
+};
+/** How many times a retryable RPC is retried before giving up. */
+const RETRIES = 4;
+/**
+* A Twirp RPC: `POST <baseUrl>twirp/<service>/<method>` with a JSON body.
+*
+* @remarks
+* Retry is applied **here**, not by each caller, so no protocol can be shipped
+* without it. A non-retryable failure never sleeps, which is what keeps the
+* ordinary failure tests clock-free.
+*
+* @internal
+*/
+const twirpCall = (options) => {
+	const { baseUrl, body, http, method, service, token } = options;
+	return Effect.gen(function* () {
+		const request = HttpClientRequest.post(`${baseUrl}twirp/${service}/${method}`).pipe(HttpClientRequest.bearerToken(token), HttpClientRequest.bodyJsonUnsafe(body));
+		const response = yield* http.execute(request).pipe(Effect.mapError((cause) => ({
+			method,
+			kind: "transport",
+			cause
+		})));
+		if (response.status === 409) return CONFLICT;
+		if (response.status < 200 || response.status >= 300) return yield* Effect.fail({
+			method,
+			kind: "status",
+			status: response.status
+		});
+		return yield* response.json.pipe(Effect.mapError((cause) => ({
+			method,
+			kind: "malformed",
+			cause
+		})));
+	}).pipe(Effect.retry({
+		schedule: Schedule.exponential("3 seconds", 1.5),
+		times: RETRIES,
+		while: isRetryable
+	}));
+};
+/**
+* Read a Twirp JSON field under either spelling.
+*
+* @remarks
+* The backend is an internal GitHub protocol reverse-engineered from
+* `actions/toolkit`, and the two halves of it do not agree: protobuf JSON emits
+* `signedUploadUrl` while the cache RPCs have been observed emitting
+* `signed_upload_url`. Reading both costs one function and removes a class of
+* failure that presents as "the cache silently never hits".
+*
+* @internal
+*/
+const field = (body, name) => {
+	if (typeof body !== "object" || body === null) return;
+	const record = body;
+	const snake = name.replaceAll(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+	return record[name] ?? record[snake];
+};
+/** {@link field}, as a string, or `undefined` when absent or empty. @internal */
+const stringField = (body, name) => {
+	const value = field(body, name);
+	return typeof value === "string" && value !== "" ? value : void 0;
+};
+/** Whether a Twirp response carries `ok: true`. @internal */
+const isOk = (body) => field(body, "ok") === true;
+
+//#endregion
+export { CONFLICT, field, isOk, isRetryable, stringField, twirpCall };

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@effected/github-actions",
+	"version": "0.1.0",
+	"private": false,
+	"description": "The GitHub Actions runtime: env, inputs, outputs, state, logging, cache, artifacts, blob storage, OIDC and the token bridge.",
+	"keywords": [
+		"github-actions",
+		"actions",
+		"runtime",
+		"cache",
+		"oidc",
+		"effect",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/github-actions#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/github-actions"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@azure/storage-blob": "^12.33.0",
+		"@effected/github": "~0.1.0",
+		"@effected/glob": "~0.2.1"
+	},
+	"peerDependencies": {
+		"@effect/platform-node": "4.0.0-beta.101",
+		"effect": "4.0.0-beta.101"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.12"
+    }
+  ]
+}