@effected/github 0.15.1 → 0.17.0

package/GitHubApp.js

@@ -2,8 +2,9 @@ import { GitHubError } from "./GitHubError.js";
 import { GitHubGraphQLError } from "./GraphQL.js";
 import { GitHubClient, makeClientShape } from "./GitHubClient.js";
 import { numericId } from "./internal/ids.js";
-import { Clock, Context, DateTime, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Stream } from "effect";
-import githubAppJwt from "universal-github-app-jwt";
+import { InstallationTokenStore } from "./InstallationTokenStore.js";
+import { Jwt, JwtKey } from "@effected/jwt";
+import { Cause, Clock, Context, DateTime, Duration, Effect, Layer, Option, Redacted, Ref, Schema, Semaphore, Stream } from "effect";
 
 //#region src/GitHubApp.ts
 /**
@@ -80,7 +81,7 @@ var InstallationToken = class extends Schema.Class("InstallationToken")({
 	* rather than answering 401 mid-request.
 	*/
 	isExpired(nowMillis, skew = DEFAULT_SKEW) {
-		return DateTime.toEpochMillis(this.expiresAt) - Duration.toMillis(skew) <= nowMillis;
+		return isSpent(DateTime.toEpochMillis(this.expiresAt), nowMillis, skew);
 	}
 	/** The committer identity a commit made with this token should carry. */
 	botIdentity() {
@@ -92,6 +93,8 @@ var InstallationToken = class extends Schema.Class("InstallationToken")({
 };
 /** Re-mint a minute before GitHub would start refusing the token. */
 const DEFAULT_SKEW = Duration.seconds(60);
+/** Whether a credential expiring at `expiresAtMillis` should be replaced at `nowMillis`. */
+const isSpent = (expiresAtMillis, nowMillis, skew = DEFAULT_SKEW) => expiresAtMillis - Duration.toMillis(skew) <= nowMillis;
 /**
 * Who a bot commits as.
 *
@@ -160,16 +163,52 @@ var AppIdentity = class extends Schema.Class("AppIdentity")({
 		});
 	}
 };
+/** `suspended_at` as GitHub sends it: an ISO string, or `null` while active. */
+const SuspendedAt = Schema.OptionFromNullOr(Schema.DateTimeUtcFromString);
+/**
+* One optional field read leniently: `{ [key]: decoded }` when the value
+* decodes, `{}` otherwise. An absent key reads as `undefined`, which none of
+* the schemas this is called with accepts, so absence and an unreadable value
+* alike omit the field rather than failing the installation.
+*/
+const readField = (key, schema, value) => {
+	const decoded = Schema.decodeUnknownOption(schema)(value);
+	return Option.isSome(decoded) ? { [key]: decoded.value } : {};
+};
 /**
 * One installation of the app.
 *
+* @remarks
+* Every field but `id` is filled only when GitHub's response carries it and
+* it reads cleanly; an unreadable field is omitted rather than failing the
+* listing. A test double built with `Installation.make({ id })` stays valid.
+* An enterprise account carries `accountId` and `accountType` without a
+* login `account`. Encodable:
+* the dates encode to ISO strings and `suspendedAt` to an ISO string or
+* `null`, the same shape GitHub sends.
+*
 * @public
 */
 var Installation = class extends Schema.Class("Installation")({
 	/** The installation id, which is what a token is minted against. */
 	id: Schema.Int,
-	/** The account the app is installed on, when GitHub reported one. */
-	account: Schema.optionalKey(Schema.String)
+	/** The account the app is installed on (its login), when GitHub reported one. */
+	account: Schema.optionalKey(Schema.String),
+	/** The account kind, e.g. "Organization" or "User"; open-ended, because GitHub adds kinds. */
+	accountType: Schema.optionalKey(Schema.String),
+	/**
+	* The account's numeric id.
+	*
+	* @remarks
+	* Not paired with `account`: an enterprise installation carries
+	* `accountId` (and may carry `accountType`) but has no login, so `account`
+	* is absent.
+	*/
+	accountId: Schema.optionalKey(Schema.Int),
+	/** When the installation was suspended; `Option.none()` when it is active. */
+	suspendedAt: Schema.optionalKey(SuspendedAt),
+	/** When GitHub last changed the installation. */
+	updatedAt: Schema.optionalKey(Schema.DateTimeUtcFromString)
 }) {};
 /**
 * GitHub App authentication: mint, revoke and identify.
@@ -187,8 +226,8 @@ var Installation = class extends Schema.Class("Installation")({
 * already — `@effected/workspaces` ships `localExecLayer`, which builds
 * `@effected/commands`' service, for the same reason.
 *
-* The JWT signer is `universal-github-app-jwt` — zero dependencies, and
-* `@octokit/auth-app`'s own JWT dependency.
+* The JWT signer is `@effected/jwt` — WebCrypto RS256 with no runtime
+* dependencies, so App auth runs on any runtime that has `crypto.subtle`.
 *
 * @example
 * ```ts
@@ -243,7 +282,135 @@ var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitH
 	* authorization failure, and widening every method's error channel to say so
 	* would tax every caller for a case only this layer can produce.
 	*/
-	static clientLayer = (request, options = {}) => Layer.effect(GitHubClient, Effect.flatMap(GitHubApp, (app) => makeRotatingClient(app, request, options))).pipe(Layer.provide(GitHubApp.layerWith(options)));
+	static clientLayer = (request, options = {}) => Layer.effect(GitHubClient, Effect.flatMap(GitHubApp, (app) => makeRotatingClient(Effect.map(app.token(request), (minted) => ({
+		token: minted.token,
+		expiresAtMillis: DateTime.toEpochMillis(minted.expiresAt)
+	})), app.revoke, options, "GitHubApp.clientLayer"))).pipe(Layer.provide(GitHubApp.layerWith(options)));
+	/**
+	* A {@link GitHubClient} authenticated as the app itself, with an App JWT.
+	*
+	* @remarks
+	* An App JWT authenticates only the app-level routes: `/app` and everything
+	* under `/app/*` (the app's installations and their token mint, its webhook
+	* configuration and deliveries), plus the three installation lookups that
+	* require a JWT: `GET /repos/{owner}/{repo}/installation`,
+	* `GET /orgs/{org}/installation` and `GET /users/{username}/installation`.
+	* Installation-scoped routes (a repository's contents, issues, pulls and the
+	* rest) answer 401 to it; reach those through {@link GitHubApp.clientLayer}
+	* with an installation token instead.
+	*
+	* The motivating use is a webhook redelivery sweep, which lists recent
+	* deliveries with `GET /app/hook/deliveries` and redelivers a failed one
+	* with `POST /app/hook/deliveries/{delivery_id}/attempts`.
+	*
+	* The JWT is signed locally, never fetched, so building the layer makes no
+	* request; a key that will not sign fails construction with
+	* `GitHubAppError { kind: "jwt" }`. A JWT lives nine minutes and is
+	* re-signed a minute before it expires, so a long-running sweep keeps
+	* authenticating; calls in between reuse it. It cannot be revoked, so
+	* release does nothing. A later signing failure surfaces to the caller as
+	* `GitHubError { kind: "unauthorized" }` carrying the `GitHubAppError` as
+	* its cause, as with {@link GitHubApp.clientLayer}.
+	*
+	* @example
+	* ```ts
+	* import { GitHubApp, GitHubClient } from "@effected/github";
+	* import { Effect, Redacted } from "effect";
+	*
+	* const sweep = Effect.gen(function* () {
+	*   const client = yield* GitHubClient;
+	*   const deliveries = yield* client.request("GET /app/hook/deliveries", { per_page: 100 });
+	*   for (const delivery of deliveries) {
+	*     if (delivery.status_code >= 400) {
+	*       yield* client.request("POST /app/hook/deliveries/{delivery_id}/attempts", {
+	*         // octokit types a delivery id as number | bigint; the route takes a number.
+	*         delivery_id: Number(delivery.id),
+	*       });
+	*     }
+	*   }
+	* });
+	*
+	* const layer = GitHubApp.appClientLayer({
+	*   appId: "12345",
+	*   privateKey: Redacted.make("-----BEGIN RSA PRIVATE KEY-----\n..."),
+	* });
+	*
+	* Effect.runPromise(Effect.provide(sweep, layer));
+	* ```
+	*/
+	static appClientLayer = (credentials, options = {}) => Layer.effect(GitHubClient, makeRotatingClient(mintJwt(credentials), () => Effect.void, options, "GitHubApp.appClientLayer"));
+	/**
+	* An installation token, reused from an {@link InstallationTokenStore}
+	* while it has `margin` (five minutes by default) left to live.
+	*
+	* @remarks
+	* For a program that authenticates per request scope (a Worker handling a
+	* webhook, say) and would otherwise mint a fresh token every time. The store
+	* is keyed by installation id. A stored value that will not decode, or a
+	* token within `margin` of expiry, is a miss: the token is minted with
+	* {@link GitHubAppShape.token} and written back with a TTL of its expiry
+	* minus `margin`. A token minted with less than `margin` to live is returned
+	* but not stored.
+	*
+	* The store never fails this call: a `get` that fails or dies is a miss and
+	* a `set` that fails or dies is ignored. Only interruption propagates.
+	*
+	* **A cached token is never revoked**: another scope or isolate may be using
+	* it. It expires on its own, within the hour.
+	*
+	* Two concurrent calls that both miss will both mint, and the later write
+	* wins. That is expected: the store may span isolates, so the kit cannot
+	* lock it, and an extra token costs one call and expires on its own.
+	*
+	* The encoded value written to the store contains the raw token, so
+	* encrypting it at rest is the store's job.
+	*/
+	static cachedToken = (request) => cachedTokenFor(request);
+	/**
+	* A {@link GitHubClient} authenticated with {@link GitHubApp.cachedToken}.
+	*
+	* @remarks
+	* Built per request scope: provide it where the request is handled, over a
+	* `GitHubApp` and an `InstallationTokenStore` provided once at the edge.
+	* Unlike {@link GitHubApp.clientLayer} it **never revokes** the token, not
+	* even on release, because the token is shared through the store, and it
+	* does not rotate, so set `margin` longer than the scope's work can take;
+	* the token is good for at least `margin` unless GitHub issued it with less
+	* (see {@link CachedTokenRequest.margin}).
+	*
+	* `options` configures this client's transport only, not the mint: the
+	* token is minted by whichever `GitHubApp` the edge provides. On GitHub
+	* Enterprise, build that with the same API root, for example
+	* `GitHubApp.layerWith({ baseUrl })`, or the mint goes to github.com.
+	*
+	* @example
+	* ```ts
+	* import { GitHubApp, GitHubClient, InstallationTokenStore } from "@effected/github";
+	* import { Effect, Layer, Redacted } from "effect";
+	*
+	* const handle = (installationId: number) =>
+	*   Effect.flatMap(GitHubClient, (client) =>
+	*     client.request("GET /repos/{owner}/{repo}", { owner: "acme", repo: "widgets" }),
+	*   ).pipe(
+	*     Effect.provide(
+	*       GitHubApp.cachedClientLayer({
+	*         appId: "12345",
+	*         privateKey: Redacted.make("-----BEGIN RSA PRIVATE KEY-----\n..."),
+	*         installationId,
+	*       }),
+	*     ),
+	*   );
+	*
+	* // Once, at the edge. On GitHub Enterprise, use GitHubApp.layerWith({ baseUrl }).
+	* const Live = Layer.mergeAll(GitHubApp.layer, InstallationTokenStore.layerMemory);
+	*
+	* Effect.runPromise(Effect.provide(handle(42), Live));
+	* ```
+	*/
+	static cachedClientLayer = (request, options = {}) => Layer.unwrap(Effect.map(cachedTokenFor(request), (cached) => GitHubClient.layerFromToken({
+		...options,
+		token: cached.token.token
+	})));
 	/** An in-memory double; unstubbed members die naming themselves. */
 	static makeTest = (overrides = {}) => ({
 		token: overrides.token ?? (() => unstubbed("token")),
@@ -255,21 +422,61 @@ var GitHubApp = class GitHubApp extends Context.Service()("@effected/github/GitH
 	/** {@link GitHubApp.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubApp, GitHubApp.makeTest(overrides));
 };
+/** The cached-token margin when a request names none. */
+const DEFAULT_CACHE_MARGIN = Duration.minutes(5);
+/** `InstallationToken` as the JSON string an {@link InstallationTokenStore} holds. */
+const StoredToken = Schema.fromJsonString(InstallationToken);
+/** A store call that can never fail its caller: failures and defects become `fallback`; interruption propagates. */
+const swallowStore = (effect, fallback) => Effect.catchCause(effect, (cause) => Cause.hasInterruptsOnly(cause) ? Effect.failCause(cause) : Effect.succeed(fallback));
+const cachedTokenFor = Effect.fn("GitHubApp.cachedToken")(function* (request) {
+	const input = request.margin ?? DEFAULT_CACHE_MARGIN;
+	const margin = typeof input === "number" && !Number.isFinite(input) ? Option.none() : Option.filter(Duration.fromInput(input), (duration) => Duration.isFinite(duration) && !Duration.isNegative(duration));
+	if (Option.isNone(margin)) return yield* GitHubAppError.of("token", "the cache margin must be a finite, non-negative duration");
+	const app = yield* GitHubApp;
+	const store = yield* InstallationTokenStore;
+	const stored = yield* swallowStore(store.get(request.installationId), Option.none());
+	if (Option.isSome(stored)) {
+		const decoded = yield* Effect.option(Schema.decodeUnknownEffect(StoredToken)(stored.value));
+		const now = yield* Clock.currentTimeMillis;
+		if (Option.isSome(decoded) && decoded.value.installationId === request.installationId && !decoded.value.isExpired(now, margin.value)) return {
+			token: decoded.value,
+			source: "cached"
+		};
+	}
+	const minted = yield* app.token(request);
+	const now = yield* Clock.currentTimeMillis;
+	const ttlMillis = DateTime.toEpochMillis(minted.expiresAt) - Duration.toMillis(margin.value) - now;
+	if (ttlMillis > 0) {
+		const encoded = yield* Effect.option(Schema.encodeUnknownEffect(StoredToken)(minted));
+		if (Option.isSome(encoded)) yield* swallowStore(store.set(request.installationId, encoded.value, Duration.millis(ttlMillis)), void 0);
+	}
+	return {
+		token: minted,
+		source: "minted"
+	};
+});
 const unstubbed = (member) => {
 	throw new Error(`GitHubApp.makeTest: ${member}() was called but not stubbed — pass an override.`);
 };
-/** Mint an app JWT. The only cryptography in this package, and it is a leaf call. */
-const mintJwt = (credentials) => Effect.tryPromise({
-	try: () => githubAppJwt({
-		id: credentials.appId,
-		privateKey: Redacted.value(credentials.privateKey)
-	}),
-	catch: (error) => GitHubAppError.of("jwt", error instanceof Error ? error.message : "could not sign the app JWT", error)
-}).pipe(Effect.map((result) => Redacted.make(result.token)));
+/** Mint an app JWT: iat 60 s in the past (clock drift), exp 9 minutes after now (GitHub caps at 10). */
+const mintJwt = (credentials) => Effect.gen(function* () {
+	const key = yield* JwtKey.fromPkcs8Pem(credentials.privateKey, { alg: "RS256" });
+	const now = Math.floor((yield* Clock.currentTimeMillis) / 1e3);
+	const exp = now + 540;
+	const token = yield* Jwt.sign({
+		iat: now - 60,
+		exp,
+		iss: credentials.appId
+	}, key);
+	return {
+		token: Redacted.make(token),
+		expiresAtMillis: exp * 1e3
+	};
+}).pipe(Effect.catchTag("JwtError", (error) => Effect.fail(GitHubAppError.of("jwt", error.detail, error))));
 /** A client speaking as the app itself. */
-const asApp = (credentials, options) => Effect.flatMap(mintJwt(credentials), (jwt) => makeClientShape({
+const asApp = (credentials, options) => Effect.flatMap(mintJwt(credentials), ({ token }) => makeClientShape({
 	...options,
-	token: jwt
+	token
 }));
 /** A client speaking as a holder of `token`, or as nobody when there is none. */
 const asBearer = (token, options) => makeClientShape({
@@ -280,10 +487,17 @@ const appFailure = (kind) => (error) => Effect.fail(GitHubAppError.of(kind, erro
 function makeApp(options) {
 	return Effect.sync(() => {
 		const installations = Effect.fn("GitHubApp.installations")(function* (credentials) {
-			return (yield* (yield* asApp(credentials, options)).paginate("GET /app/installations", {}).pipe(Effect.catch(appFailure("installation")))).map((entry) => Installation.make({
-				id: numericId(entry.id),
-				...entry.account !== null && entry.account !== void 0 && "login" in entry.account ? { account: entry.account.login } : {}
-			}));
+			return (yield* (yield* asApp(credentials, options)).paginate("GET /app/installations", {}).pipe(Effect.catch(appFailure("installation")))).map((entry) => {
+				const account = entry.account ?? void 0;
+				return Installation.make({
+					id: numericId(entry.id),
+					...account !== void 0 && typeof account.login === "string" ? { account: account.login } : {},
+					...readField("accountType", Schema.String, account?.type),
+					...readField("accountId", Schema.Int, typeof account?.id === "bigint" ? numericId(account.id) : account?.id),
+					...readField("suspendedAt", SuspendedAt, entry.suspended_at),
+					...readField("updatedAt", Schema.DateTimeUtcFromString, entry.updated_at)
+				});
+			});
 		});
 		const resolveInstallationId = (request) => request.installationId !== void 0 ? Effect.succeed(request.installationId) : Effect.gen(function* () {
 			const all = yield* installations(request);
@@ -339,48 +553,52 @@ const normalizePermissions = (raw) => {
 	return out;
 };
 /**
-* A client shape that re-mints its installation token before it expires.
+* A client shape that re-mints its credential before it expires.
 *
 * @remarks
 * The rotation is invisible to a caller: each member resolves the current
 * client first, and "current" means "minted, and not within a minute of
-* expiry". Rotating revokes the token it replaces, so at most one live token
-* exists at a time and the scope's release revokes the last of them.
+* expiry" (the same skew as {@link InstallationToken.isExpired}). Rotating
+* releases the credential it replaces, so at most one live credential exists
+* at a time and the scope's release releases the last of them. An
+* installation token is released by revoking it; an App JWT has nothing to
+* release.
 */
-const makeRotatingClient = (app, request, options) => Effect.gen(function* () {
+const makeRotatingClient = (mint, release, options, operation) => Effect.gen(function* () {
 	const held = yield* Ref.make(Option.none());
-	const revokeHeld = Effect.flatMap(Ref.get(held), (current) => Option.isSome(current) ? Effect.ignore(app.revoke(current.value.token.token)) : Effect.void);
+	const revokeHeld = Effect.flatMap(Ref.get(held), (current) => Option.isSome(current) ? Effect.ignore(release(current.value.credential.token)) : Effect.void);
 	const rotate = Effect.gen(function* () {
 		yield* revokeHeld;
-		const minted = yield* app.token(request);
+		const minted = yield* mint;
 		const client = yield* makeClientShape({
 			...options,
 			token: minted.token
 		});
 		yield* Ref.set(held, Option.some({
-			token: minted,
+			credential: minted,
 			client
 		}));
 		return client;
 	});
 	yield* rotate;
 	yield* Effect.addFinalizer(() => revokeHeld);
-	/** The live client, re-minting first if the held token is spent. */
-	const fresh = Effect.gen(function* () {
+	const live = Effect.gen(function* () {
 		const now = yield* Clock.currentTimeMillis;
 		const state = yield* Ref.get(held);
-		if (Option.isSome(state) && !state.value.token.isExpired(now)) return state.value.client;
-		return yield* rotate;
+		return Option.isSome(state) && !isSpent(state.value.credential.expiresAtMillis, now) ? Option.some(state.value.client) : Option.none();
 	});
+	const lock = yield* Semaphore.make(1);
+	/** The live client, re-minting first if the held credential is spent. */
+	const fresh = Effect.flatMap(live, (current) => Option.isSome(current) ? Effect.succeed(current.value) : lock.withPermit(Effect.flatMap(live, (rechecked) => Option.isSome(rechecked) ? Effect.succeed(rechecked.value) : rotate)));
 	const current = fresh.pipe(Effect.catchTag("GitHubAppError", (error) => Effect.fail(new GitHubError({
 		kind: "unauthorized",
-		operation: "GitHubApp.clientLayer",
+		operation,
 		reason: error.reason,
 		cause: error
 	}))));
 	const currentForGraphQL = fresh.pipe(Effect.catchTag("GitHubAppError", (error) => Effect.fail(new GitHubGraphQLError({
 		kind: "unauthorized",
-		operation: "GitHubApp.clientLayer",
+		operation,
 		reason: error.reason,
 		errors: [],
 		cause: error

package/GitHubClient.js

@@ -3,11 +3,49 @@ import { GitHubGraphQLError } from "./GraphQL.js";
 import { RetryPolicy } from "./Resilience.js";
 import { makeTransport } from "./internal/octokit.js";
 import { fromArray, paginate } from "./internal/paginate.js";
-import { Config, Context, Effect, Layer, Option, Schema, Stream } from "effect";
+import { Clock, Config, Context, Effect, Layer, Option, Schema, Stream } from "effect";
 
 //#region src/GitHubClient.ts
 /** GitHub's own maximum page size, and the default this package requests. */
 const DEFAULT_PER_PAGE = 100;
+/**
+* A raw HTTP failure recorded for {@link GitHubClient.layerFixture}, made by
+* {@link (GitHubFixtures:variable).failure}.
+*
+* @remarks
+* Branded, so a fixture's data payload that happens to have a `status` and a
+* `body` is never mistaken for a failure: only a value built by
+* `GitHubFixtures.failure` fails the call. The brand is a registered symbol
+* rather than the class identity, so a failure built by another resolved copy
+* of this package is still recognized.
+*
+* @public
+*/
+var RawFailure = class {
+	/** The HTTP status. */
+	status;
+	/** The response headers, in any case. */
+	headers;
+	/** The JSON body GitHub would send. */
+	body;
+	/** @internal */
+	constructor(response) {
+		this.status = response.status;
+		this.headers = response.headers;
+		this.body = response.body;
+	}
+};
+/** The brand every {@link RawFailure} carries; registered, so it is shared across package copies. */
+const RawFailureBrand = Symbol.for("@effected/github/RawFailure");
+Object.defineProperty(RawFailure.prototype, RawFailureBrand, { value: true });
+/** Whether `value` is a {@link RawFailure}, from this copy of the package or another. */
+const isRawFailure = (value) => typeof value === "object" && value !== null && value[RawFailureBrand] === true;
+/**
+* Builders for {@link (GitHubFixtures:interface)} entries.
+*
+* @public
+*/
+const GitHubFixtures = { failure: (response) => new RawFailure(response) };
 const resolvePolicy = (retry) => retry === void 0 ? RetryPolicy.default : retry === "off" ? RetryPolicy.none : retry;
 const perPageOf = (options) => options?.perPage ?? DEFAULT_PER_PAGE;
 const unstubbed = (member) => {
@@ -108,7 +146,14 @@ var GitHubClient = class GitHubClient extends Context.Service()("@effected/githu
 	* `perPage` and `maxPages` cannot behave differently here than in production.
 	*
 	* `fixtures.requested` is appended to as the test runs, so a suite can assert
-	* which routes were walked and at what page size.
+	* which routes were walked, with what params and at what page size.
+	*
+	* **It records every call it serves, including one that fails.** A call
+	* answered by a recorded `GitHubError` or a
+	* {@link (GitHubFixtures:variable).failure} is recorded before it fails, so
+	* one fixture both records the calls and classifies a raw failure the way
+	* the live client would; there is no need to classify by hand inside a
+	* {@link GitHubClient.layerTest} handler.
 	*/
 	static layerFixture = (fixtures) => Layer.succeed(GitHubClient, makeFixture(fixtures));
 };
@@ -175,6 +220,7 @@ const makeFixture = (fixtures) => {
 		});
 		const recorded = fixtures.paginate?.[route];
 		if (recorded instanceof GitHubError) return Stream.fail(recorded);
+		if (isRawFailure(recorded)) return Stream.fromEffect(failWith(route, recorded));
 		const items = recorded;
 		if (items === void 0) switch (fixtures.unstubbed ?? "die") {
 			case "fail": return Stream.fail(GitHubError.notFound("GitHubClient.paginate", `fixture for ${route}`));
@@ -183,6 +229,7 @@ const makeFixture = (fixtures) => {
 		}
 		return paginate(() => fromArray(items, perPage), options?.maxPages);
 	};
+	const failWith = (route, failure) => Effect.flatMap(Clock.currentTimeMillis, (now) => Effect.fail(GitHubError.fromResponse(route, failure, now)));
 	const missing = (method, route) => {
 		switch (fixtures.unstubbed ?? "die") {
 			case "fail": return Effect.fail(GitHubError.notFound(method, `fixture for ${route}`));
@@ -199,6 +246,7 @@ const makeFixture = (fixtures) => {
 			});
 			const data = fixtures.request?.[route];
 			if (data === void 0) return missing("GitHubClient.request", route);
+			if (isRawFailure(data)) return failWith(route, data);
 			return data instanceof GitHubError ? Effect.fail(data) : Effect.succeed(data);
 		},
 		requestDecoded: (route, params, schema) => {
@@ -210,6 +258,7 @@ const makeFixture = (fixtures) => {
 			const data = fixtures.request?.[route];
 			if (data === void 0) return missing("GitHubClient.requestDecoded", route);
 			if (data instanceof GitHubError) return Effect.fail(data);
+			if (isRawFailure(data)) return failWith(route, data);
 			return Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode(route, "fixture did not match its schema", error))));
 		},
 		paginate: (route, params, options) => Stream.runCollect(paginateStream(route, params, options)),
@@ -228,4 +277,4 @@ const makeFixture = (fixtures) => {
 };
 
 //#endregion
-export { GitHubClient, makeClientShape };
+export { GitHubClient, GitHubFixtures, RawFailure, makeClientShape };

package/GitHubContent.js

@@ -1,10 +1,16 @@
 import { GitHubError } from "./GitHubError.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
-import { Context, Effect, Layer, Option } from "effect";
+import { Context, Effect, Layer, Option, Result } from "effect";
+import * as Base64 from "effect/encoding/Base64";
 
 //#region src/GitHubContent.ts
 /**
+* Non-fatal, matching `Buffer`'s lenient decode of a non-UTF-8 file; `ignoreBOM`
+* keeps a leading BOM, since it is the file's content rather than framing.
+*/
+const utf8 = new TextDecoder("utf-8", { ignoreBOM: true });
+/**
 * Read a text file out of a repository at a ref, with absence as an `Option`
 * when you want it.
 *
@@ -58,7 +64,9 @@ const make = (client) => {
 		if (Array.isArray(content)) return yield* Effect.fail(GitHubError.rejected("GitHubContent.getFile", 422, `${path} is a directory`));
 		if (content.type !== "file") return yield* Effect.fail(GitHubError.rejected("GitHubContent.getFile", 422, `${path} is a ${content.type}, not a file`));
 		if (content.encoding !== "base64") return yield* Effect.fail(GitHubError.rejected("GitHubContent.getFile", 422, `${path} came back with encoding ${JSON.stringify(content.encoding)} — it is probably too large for the contents API`));
-		return Buffer.from(content.content.replace(/\s/g, ""), "base64").toString("utf8");
+		const bytes = Base64.decode(content.content.replace(/\s/g, ""));
+		if (Result.isFailure(bytes)) return yield* Effect.fail(GitHubError.decode("GitHubContent.getFile", `${path} did not come back as valid base64`, bytes.failure));
+		return utf8.decode(bytes.success);
 	});
 	return {
 		getFile,

package/GitHubError.js

@@ -175,18 +175,28 @@ var GitHubError = class GitHubError extends Schema.TaggedError()("GitHubError",
 	* under test.
 	*/
 	static fromOctokit(operation, error, nowMillis) {
-		const facts = readThrowable(error);
-		const retryAfterMillis = retryAfterMillisFrom(facts.headers, nowMillis);
-		const kind = classify(facts, retryAfterMillis);
-		return new GitHubError({
-			kind,
-			operation,
-			reason: facts.reason,
-			...facts.status !== void 0 ? { status: facts.status } : {},
-			...retryAfterMillis !== void 0 ? { retryAfterMillis } : {},
-			...facts.validation.length > 0 ? { validation: facts.validation } : {},
-			cause: error
-		});
+		return fromFacts(operation, readThrowable(error), nowMillis, error);
+	}
+	/**
+	* Classify a raw HTTP response: a status, its headers and its JSON body.
+	*
+	* @remarks
+	* For a response that never went through octokit, such as one a test
+	* records with `GitHubFixtures.failure` or one a consumer fetched itself. It
+	* reads the same facts {@link GitHubError.fromOctokit} reads (`reason` from
+	* `body.message`, else `HTTP <status>`, sanitized the same way; `validation`
+	* from `body.errors`) and runs the same classifier, so a raw response and
+	* the octokit error for it classify identically.
+	*
+	* Header names are matched in any case. `nowMillis` is required, as in
+	* {@link GitHubError.fromOctokit}: it turns an absolute rate-limit reset
+	* (an epoch second) into a delay, so it must be the real current time,
+	* usually `Clock.currentTimeMillis`. A zero would make the delay decades.
+	*/
+	static fromResponse(operation, response, nowMillis) {
+		const body = asRecord(response.body);
+		const message = typeof body?.message === "string" ? body.message : `HTTP ${response.status}`;
+		return fromFacts(operation, factsFrom(response.status, lowercaseKeys(response.headers), message, body), nowMillis, void 0);
 	}
 	/**
 	* A predicate over one or more kinds, for `Effect.catchIf`.
@@ -251,15 +261,35 @@ const readThrowable = (error) => {
 	};
 	const record = error;
 	const response = asRecord(record.response);
-	const headers = asRecord(response?.headers);
-	const data = asRecord(response?.data);
-	return {
-		status: typeof record.status === "number" ? record.status : void 0,
-		headers,
-		reason: sanitizeReason(typeof record.message === "string" ? record.message : String(error)),
-		validation: readValidation(data)
-	};
+	return factsFrom(typeof record.status === "number" ? record.status : void 0, asRecord(response?.headers), typeof record.message === "string" ? record.message : String(error), asRecord(response?.data));
+};
+/**
+* The classification facts from a response's parts: the half shared by
+* {@link GitHubError.fromOctokit} and {@link GitHubError.fromResponse}.
+* `headers` must already be lowercase-keyed.
+*/
+const factsFrom = (status, headers, message, data) => ({
+	status,
+	headers,
+	reason: sanitizeReason(message),
+	validation: readValidation(data)
+});
+/** Classify `facts` and build the error: the one place a `GitHubError` is classified. */
+const fromFacts = (operation, facts, nowMillis, cause) => {
+	const retryAfterMillis = retryAfterMillisFrom(facts.headers, nowMillis);
+	const kind = classify(facts, retryAfterMillis);
+	return new GitHubError({
+		kind,
+		operation,
+		reason: facts.reason,
+		...facts.status !== void 0 ? { status: facts.status } : {},
+		...retryAfterMillis !== void 0 ? { retryAfterMillis } : {},
+		...facts.validation.length > 0 ? { validation: facts.validation } : {},
+		...cause !== void 0 ? { cause } : {}
+	});
 };
+/** Header names as octokit delivers them: lowercase. A caller may write `Retry-After`. */
+const lowercaseKeys = (headers) => headers === void 0 ? void 0 : Object.fromEntries(Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value]));
 const asRecord = (value) => typeof value === "object" && value !== null ? value : void 0;
 /**
 * GitHub answers some requests with an HTML error page whose body becomes a

package/InstallationTokenStore.js

@@ -0,0 +1,51 @@
+import { Clock, Context, Duration, Effect, Layer, Option, Ref } from "effect";
+
+//#region src/InstallationTokenStore.ts
+/**
+* Where `GitHubApp.cachedToken` keeps installation tokens between request
+* scopes.
+*
+* @remarks
+* Entries are keyed by installation id, never by token text. The value is an
+* `InstallationToken` encoded as JSON, and it **contains the raw token**, so
+* encrypting it at rest is the store's job, not the caller's.
+*
+* {@link InstallationTokenStore.layerMemory} keeps tokens in process. A
+* Cloudflare Worker, whose isolates do not share memory, backs the store with
+* KV, a Durable Object or D1 instead. A store's own failures should be
+* swallowed by the store (a miss on `get`, a no-op on `set`): a cache must
+* never fail the call it serves. `cachedToken` also guards against a store
+* that fails or dies anyway; only interruption propagates.
+*
+* This module imports nothing but `effect`, so a store implementation never
+* links the JWT signer.
+*
+* @public
+*/
+var InstallationTokenStore = class InstallationTokenStore extends Context.Service()("@effected/github/InstallationTokenStore") {
+	/** An in-process store over a `Ref`, expiring entries against `Clock`. */
+	static layerMemory = Layer.effect(this, Effect.map(Ref.make(/* @__PURE__ */ new Map()), (entries) => ({
+		get: (installationId) => Effect.gen(function* () {
+			const now = yield* Clock.currentTimeMillis;
+			const entry = (yield* Ref.get(entries)).get(installationId);
+			return entry !== void 0 && now < entry.expiresAtMillis ? Option.some(entry.encoded) : Option.none();
+		}),
+		set: (installationId, encoded, ttl) => Effect.gen(function* () {
+			const expiresAtMillis = (yield* Clock.currentTimeMillis) + Duration.toMillis(ttl);
+			yield* Ref.update(entries, (map) => new Map(map).set(installationId, {
+				encoded,
+				expiresAtMillis
+			}));
+		})
+	})));
+	/** An in-memory double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		get: overrides.get ?? (() => Effect.die(/* @__PURE__ */ new Error("InstallationTokenStore.makeTest: get() was called but not stubbed"))),
+		set: overrides.set ?? (() => Effect.die(/* @__PURE__ */ new Error("InstallationTokenStore.makeTest: set() was called but not stubbed")))
+	});
+	/** {@link InstallationTokenStore.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(InstallationTokenStore, InstallationTokenStore.makeTest(overrides));
+};
+
+//#endregion
+export { InstallationTokenStore };