@effected/github 0.15.1 → 0.16.0

package/ActionsOidc.js

@@ -0,0 +1,180 @@
+import { JwksResolver, Jwt, JwtError } from "@effected/jwt";
+import { Effect, Schema, SchemaTransformation } from "effect";
+
+//#region src/ActionsOidc.ts
+/** The issuer of every GitHub Actions OIDC token on github.com. */
+const ISSUER = "https://token.actions.githubusercontent.com";
+/**
+* A numeric id as GitHub's OIDC tokens carry it: a string of decimal digits,
+* decoded to a safe integer. Anything else (an empty string, a sign, a
+* fraction, an exponent, surrounding space) does not decode.
+*/
+const IdFromString = Schema.String.check(Schema.isPattern(/^\d+$/)).pipe(Schema.decodeTo(Schema.Int, SchemaTransformation.numberFromString));
+/**
+* The claims of a verified GitHub Actions OIDC token.
+*
+* @remarks
+* Field names are camelCase; the token carries them in snake_case
+* (`repository_id`, `job_workflow_ref`, ...), and {@link ActionsOidc.verify}
+* maps between the two. GitHub sends the numeric ids (`repository_id`,
+* `repository_owner_id`, `run_id`, `run_attempt`, `actor_id`) as strings;
+* they decode to numbers here, and a non-numeric one fails verification as
+* `claims`.
+*
+* Claims GitHub adds that are not modelled here are dropped on decode.
+*
+* @public
+*/
+var ActionsOidcClaims = class extends Schema.Class("ActionsOidcClaims")({
+	/** The issuer: always {@link ActionsOidc.issuer} once verified. */
+	iss: Schema.String,
+	/** The subject, e.g. `repo:octo-org/octo-repo:ref:refs/heads/main`. */
+	sub: Schema.String,
+	/** The audience or audiences the token was minted for. */
+	aud: Schema.Union([Schema.String, Schema.Array(Schema.String)]),
+	/** Expiry, in seconds since the epoch. */
+	exp: Schema.Number,
+	/** Issued at, in seconds since the epoch. */
+	iat: Schema.Number,
+	/** Not before, in seconds since the epoch. */
+	nbf: Schema.optionalKey(Schema.Number),
+	/** The token's unique id. */
+	jti: Schema.optionalKey(Schema.String),
+	/** The repository, `owner/name`. */
+	repository: Schema.String,
+	/** The repository's numeric id (wire key `repository_id`). */
+	repositoryId: IdFromString,
+	/** The repository owner's login (wire key `repository_owner`). */
+	repositoryOwner: Schema.String,
+	/** The repository owner's numeric id (wire key `repository_owner_id`). */
+	repositoryOwnerId: IdFromString,
+	/** The workflow run's id (wire key `run_id`). */
+	runId: IdFromString,
+	/** The run attempt, from 1 (wire key `run_attempt`). */
+	runAttempt: IdFromString,
+	/** The calling workflow's ref, e.g. `octo-org/octo-repo/.github/workflows/ci.yml@refs/heads/main` (wire key `workflow_ref`). */
+	workflowRef: Schema.String,
+	/** The ref of the workflow file the job runs, which differs from `workflowRef` for a reusable workflow (wire key `job_workflow_ref`). */
+	jobWorkflowRef: Schema.String,
+	/** The git ref the run is for. */
+	ref: Schema.String,
+	/** The commit SHA the run is for. */
+	sha: Schema.String,
+	/** The event that triggered the run, e.g. `push` (wire key `event_name`). */
+	eventName: Schema.String,
+	/** The login of the user who triggered the run. */
+	actor: Schema.String,
+	/** That user's numeric id (wire key `actor_id`). */
+	actorId: IdFromString,
+	/** The deployment environment, when the job names one. */
+	environment: Schema.optionalKey(Schema.String),
+	/** `github-hosted` or `self-hosted` (wire key `runner_environment`). */
+	runnerEnvironment: Schema.String
+}) {};
+/** The claims as they arrive in the token: snake_case keys, decoding to {@link ActionsOidcClaims}. */
+const ClaimsFromWire = ActionsOidcClaims.pipe(Schema.encodeKeys({
+	repositoryId: "repository_id",
+	repositoryOwner: "repository_owner",
+	repositoryOwnerId: "repository_owner_id",
+	runId: "run_id",
+	runAttempt: "run_attempt",
+	workflowRef: "workflow_ref",
+	jobWorkflowRef: "job_workflow_ref",
+	eventName: "event_name",
+	actorId: "actor_id",
+	runnerEnvironment: "runner_environment"
+}));
+const verify = Effect.fn("ActionsOidc.verify")(function* (token, options) {
+	if (options.audience.length === 0) return yield* new JwtError({
+		reason: "wrongAudience",
+		detail: "no audience was given; an Actions OIDC token is never verified without one"
+	});
+	return yield* Jwt.verify(token, {
+		key: JwksResolver.forIssuer(ISSUER),
+		claims: ClaimsFromWire,
+		issuer: ISSUER,
+		audience: options.audience,
+		...options.clockTolerance !== void 0 ? { clockTolerance: options.clockTolerance } : {}
+	});
+});
+const testClaims = (overrides = {}) => ({
+	iss: ISSUER,
+	sub: "repo:octo-org/octo-repo:ref:refs/heads/main",
+	aud: "https://github.com/octo-org",
+	repository: "octo-org/octo-repo",
+	repository_id: "123456789",
+	repository_owner: "octo-org",
+	repository_owner_id: "987654",
+	run_id: "4242424242",
+	run_attempt: "1",
+	workflow_ref: "octo-org/octo-repo/.github/workflows/ci.yml@refs/heads/main",
+	job_workflow_ref: "octo-org/octo-repo/.github/workflows/ci.yml@refs/heads/main",
+	ref: "refs/heads/main",
+	sha: "0123456789abcdef0123456789abcdef01234567",
+	event_name: "push",
+	actor: "octocat",
+	actor_id: "583231",
+	runner_environment: "github-hosted",
+	...overrides
+});
+/**
+* Verify GitHub Actions OIDC tokens: a workflow proving to your service which
+* repository, workflow and run it is.
+*
+* @remarks
+* {@link ActionsOidc.verify} checks the signature against GitHub's published
+* JWKS (through `@effected/jwt`'s `JwksResolver`, which caches it), then `iss`,
+* `aud`, `exp`, `nbf` and `iat`, then decodes the payload into
+* {@link ActionsOidcClaims}. Every failure is a `JwtError`; route on its
+* `reason` (`wrongAudience`, `expired`, `claims`, ...), never on its message.
+*
+* Authorizing the caller is still yours: a verified token proves who is
+* calling, not that they may. Pin the **immutable ids**, `repositoryId` or
+* `repositoryOwnerId`, together with `jobWorkflowRef` (or `workflowRef`),
+* never the `repository` or `repositoryOwner` name alone: a deleted
+* repository's or account's name can be registered again by someone else,
+* whose workflows then mint tokens carrying the old name.
+*
+* Only the github.com issuer is accepted. A GitHub Enterprise Cloud
+* enterprise's unique issuer (`https://token.actions.githubusercontent.com/<enterprise>`)
+* and a GitHub Enterprise Server issuer (`https://<host>/_services/token`)
+* are refused as `wrongIssuer`.
+*
+* This module does not reach octokit: a service that only verifies tokens
+* links `@effected/jwt` and nothing else from this package.
+*
+* @example
+* ```ts
+* import { JwksResolver } from "@effected/jwt";
+* import { ActionsOidc } from "@effected/github";
+* import { Data, Effect } from "effect";
+*
+* class Forbidden extends Data.TaggedError("Forbidden")<{ readonly repositoryId: number }> {}
+*
+* // Pinned by id, which survives a rename and cannot be re-registered.
+* const ALLOWED_REPOSITORY_ID = 123456789;
+* const ALLOWED_WORKFLOW = "octo-org/octo-repo/.github/workflows/deploy.yml@refs/heads/main";
+*
+* const authorize = (bearer: string) =>
+*   Effect.gen(function* () {
+*     const claims = yield* ActionsOidc.verify(bearer, { audience: "https://my-service.example" });
+*     if (claims.repositoryId !== ALLOWED_REPOSITORY_ID || claims.jobWorkflowRef !== ALLOWED_WORKFLOW) {
+*       return yield* new Forbidden({ repositoryId: claims.repositoryId });
+*     }
+*     return claims;
+*   });
+*
+* // JwksResolver.layer needs an HttpClient and a JwksStore, provided once at the edge.
+* export const program = authorize("eyJ...").pipe(Effect.provide(JwksResolver.layer));
+* ```
+*
+* @public
+*/
+const ActionsOidc = {
+	issuer: ISSUER,
+	verify,
+	testClaims
+};
+
+//#endregion
+export { ActionsOidc, ActionsOidcClaims };

package/CheckRun.js

@@ -1,7 +1,8 @@
+import { GitHubError } from "./GitHubError.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
 import { numericId } from "./internal/ids.js";
-import { Cause, Context, Effect, Exit, Layer, Ref, Schema } from "effect";
+import { Cause, Context, DateTime, Effect, Exit, Layer, Option, Ref, Schema } from "effect";
 
 //#region src/CheckRun.ts
 /** How a check run finished. @public */
@@ -81,6 +82,17 @@ var CheckRunOutput = class CheckRunOutput extends Schema.Class("CheckRunOutput")
 		});
 	}
 };
+/** UTF-8 encoder for the byte arithmetic; portable, unlike Node's `Buffer`. */
+const utf8 = new TextEncoder();
+/**
+* UTF-8 decoder for the cut. Non-fatal, so a code point split by the cut decodes
+* to U+FFFD for the trim loop to drop rather than throwing; `ignoreBOM` keeps a
+* leading BOM as content, as `Buffer` did.
+*/
+const utf8Lenient = new TextDecoder("utf-8", {
+	fatal: false,
+	ignoreBOM: true
+});
 /**
 * Cut `value` to GitHub's byte budget without leaving a broken code point.
 *
@@ -88,11 +100,15 @@ var CheckRunOutput = class CheckRunOutput extends Schema.Class("CheckRunOutput")
 * Slicing a UTF-8 buffer mid-character decodes to U+FFFD. Splitting a four-byte
 * code point can produce **more than one** replacement character, so the trim
 * loops rather than dropping a single one.
+*
+* `TextEncoder`/`TextDecoder` rather than `Buffer`, which is a Node global: a
+* Worker without `nodejs_compat` would throw a `ReferenceError` here.
 */
 const capBytes = (value) => {
-	if (Buffer.byteLength(value, "utf8") <= CheckRunOutput.LIMIT_BYTES) return value;
-	const budget = CheckRunOutput.LIMIT_BYTES - Buffer.byteLength(CheckRunOutput.NOTICE, "utf8");
-	let cut = Buffer.from(value, "utf8").subarray(0, budget).toString("utf8");
+	const bytes = utf8.encode(value);
+	if (bytes.length <= CheckRunOutput.LIMIT_BYTES) return value;
+	const budget = CheckRunOutput.LIMIT_BYTES - utf8.encode(CheckRunOutput.NOTICE).length;
+	let cut = utf8Lenient.decode(bytes.subarray(0, budget));
 	while (cut.endsWith("�")) cut = cut.slice(0, -1);
 	return `${cut}${CheckRunOutput.NOTICE}`;
 };
@@ -106,7 +122,13 @@ var CheckRunRef = class extends Schema.Class("CheckRunRef")({
 	name: Schema.String,
 	/** The web URL. */
 	url: Schema.String,
-	status: Schema.String
+	status: Schema.String,
+	/**
+	* The integrator's own id for the run (wire `external_id`), when it has
+	* one. GitHub reports a run created without one as `null` or `""`; both
+	* leave this absent.
+	*/
+	externalId: Schema.optionalKey(Schema.String)
 }) {};
 /**
 * Create, update and conclude GitHub check runs, including the
@@ -126,6 +148,7 @@ var CheckRun = class CheckRun extends Context.Service()("@effected/github/CheckR
 		create: overrides.create ?? (() => unstubbed("create")),
 		get: overrides.get ?? (() => unstubbed("get")),
 		update: overrides.update ?? (() => unstubbed("update")),
+		findByExternalId: overrides.findByExternalId ?? (() => unstubbed("findByExternalId")),
 		complete: overrides.complete ?? (() => unstubbed("complete")),
 		withCheckRun: overrides.withCheckRun ?? (() => unstubbed("withCheckRun"))
 	});
@@ -202,32 +225,49 @@ const concludeFor = (name, id, exit, recorded, complete) => {
 	const write = complete(id, settled.conclusion, settled.output);
 	return Exit.isSuccess(exit) ? write : Effect.ignore(write);
 };
-const refOf = (raw) => CheckRunRef.make({
+const decodeRef = Schema.decodeUnknownEffect(CheckRunRef);
+/**
+* Project a check-run response onto {@link CheckRunRef}, **decoding** it.
+*
+* @remarks
+* Decoded rather than built with `make`, which throws: a response missing a
+* field (a hand-written double, or GitHub changing shape) is input, and input
+* failures are a typed `decode` `GitHubError` naming the operation rather than
+* a defect.
+*/
+const refOf = (operation, raw) => decodeRef({
 	id: numericId(raw.id),
 	name: raw.name,
 	url: raw.html_url ?? "",
-	status: raw.status
-});
+	status: raw.status,
+	...raw.external_id ? { externalId: raw.external_id } : {}
+}).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode(operation, "GitHub returned an unexpected check run", error))));
+/** The current time as GitHub's ISO 8601 timestamp, from `Clock` so `TestClock` drives it. */
+const isoNow = Effect.map(DateTime.now, DateTime.formatIso);
 const make = (client) => {
-	const create = Effect.fn("CheckRun.create")(function* (name, headSha) {
+	const create = Effect.fn("CheckRun.create")(function* (name, headSha, options) {
 		const { owner, repo } = yield* Repo;
+		const status = options?.status ?? "in_progress";
 		yield* Effect.annotateCurrentSpan({
 			owner,
 			repo,
 			name,
-			headSha
+			headSha,
+			status
 		});
 		const created = yield* client.request("POST /repos/{owner}/{repo}/check-runs", {
 			owner,
 			repo,
 			name,
 			head_sha: headSha,
-			status: "in_progress",
-			started_at: (/* @__PURE__ */ new Date()).toISOString()
+			status,
+			...status === "in_progress" ? { started_at: yield* isoNow } : {},
+			...options?.externalId ? { external_id: options.externalId } : {},
+			...options?.detailsUrl !== void 0 ? { details_url: options.detailsUrl } : {}
 		});
-		return refOf(created);
+		return yield* refOf("CheckRun.create", created);
 	});
-	const complete = Effect.fn("CheckRun.complete")(function* (id, conclusion, output) {
+	const complete = Effect.fn("CheckRun.complete")(function* (id, conclusion, output, options) {
 		const { owner, repo } = yield* Repo;
 		yield* Effect.annotateCurrentSpan({
 			owner,
@@ -241,8 +281,9 @@ const make = (client) => {
 			check_run_id: id,
 			status: "completed",
 			conclusion,
-			completed_at: (/* @__PURE__ */ new Date()).toISOString(),
-			...output !== void 0 ? { output: wireOutput(output) } : {}
+			completed_at: yield* isoNow,
+			...output !== void 0 ? { output: wireOutput(output) } : {},
+			...options?.detailsUrl !== void 0 ? { details_url: options.detailsUrl } : {}
 		});
 	});
 	return {
@@ -260,9 +301,9 @@ const make = (client) => {
 				repo,
 				check_run_id: id
 			});
-			return refOf(raw);
+			return yield* refOf("CheckRun.get", raw);
 		}),
-		update: Effect.fn("CheckRun.update")(function* (id, output) {
+		update: Effect.fn("CheckRun.update")(function* (id, output, options) {
 			const { owner, repo } = yield* Repo;
 			yield* Effect.annotateCurrentSpan({
 				owner,
@@ -273,8 +314,35 @@ const make = (client) => {
 				owner,
 				repo,
 				check_run_id: id,
-				output: wireOutput(output)
+				...output !== void 0 ? { output: wireOutput(output) } : {},
+				...options?.status !== void 0 ? { status: options.status } : {},
+				...options?.status === "in_progress" ? { started_at: yield* isoNow } : {},
+				...options?.detailsUrl !== void 0 ? { details_url: options.detailsUrl } : {}
+			});
+		}),
+		findByExternalId: Effect.fn("CheckRun.findByExternalId")(function* (headSha, name, externalId) {
+			if (externalId === "") return Option.none();
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo,
+				headSha,
+				name,
+				externalId
+			});
+			const runs = yield* client.paginate("GET /repos/{owner}/{repo}/commits/{ref}/check-runs", {
+				owner,
+				repo,
+				ref: headSha,
+				check_name: name,
+				filter: "all"
 			});
+			let newest;
+			for (const run of runs) {
+				if (run.external_id !== externalId) continue;
+				if (newest === void 0 || numericId(run.id) > numericId(newest.id)) newest = run;
+			}
+			return newest === void 0 ? Option.none() : Option.some(yield* refOf("CheckRun.findByExternalId", newest));
 		}),
 		withCheckRun: (name, headSha, use) => Effect.gen(function* () {
 			const run = yield* create(name, headSha);