@effected/github 0.15.1 → 0.17.0

package/index.d.ts

@@ -1,9 +1,160 @@
 import { BareLineReference, CLOSING_KEYWORDS, ClosingKeyword, IssueReference, harvestIssueReferences, parseBareLineReference } from "@effected/github-references";
-import { Config, Context, Duration, Effect, Layer, Option, Redacted, Result, Schedule, Schema, Scope, Stream } from "effect";
+import { JwksResolver, JwtError } from "@effected/jwt";
+import { Cause, Config, Context, Duration, Effect, Layer, Option, Redacted, Result, Schedule, Schema, Scope, Stream } from "effect";
 import { PaginatingEndpoints } from "@octokit/plugin-paginate-rest";
 import { Endpoints, RequestHeaders } from "@octokit/types";
 import { SemVer } from "@effected/semver";
 //#endregion
+//#region src/ActionsOidc.d.ts
+declare const ActionsOidcClaims_base: Schema.Class<ActionsOidcClaims, Schema.Struct<{
+  /** The issuer: always {@link ActionsOidc.issuer} once verified. */
+  readonly iss: Schema.String;
+  /** The subject, e.g. `repo:octo-org/octo-repo:ref:refs/heads/main`. */
+  readonly sub: Schema.String;
+  /** The audience or audiences the token was minted for. */
+  readonly aud: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>;
+  /** Expiry, in seconds since the epoch. */
+  readonly exp: Schema.Number;
+  /** Issued at, in seconds since the epoch. */
+  readonly iat: Schema.Number;
+  /** Not before, in seconds since the epoch. */
+  readonly nbf: Schema.optionalKey<Schema.Number>;
+  /** The token's unique id. */
+  readonly jti: Schema.optionalKey<Schema.String>;
+  /** The repository, `owner/name`. */
+  readonly repository: Schema.String;
+  /** The repository's numeric id (wire key `repository_id`). */
+  readonly repositoryId: Schema.decodeTo<Schema.Int, Schema.String, never, never>;
+  /** The repository owner's login (wire key `repository_owner`). */
+  readonly repositoryOwner: Schema.String;
+  /** The repository owner's numeric id (wire key `repository_owner_id`). */
+  readonly repositoryOwnerId: Schema.decodeTo<Schema.Int, Schema.String, never, never>;
+  /** The workflow run's id (wire key `run_id`). */
+  readonly runId: Schema.decodeTo<Schema.Int, Schema.String, never, never>;
+  /** The run attempt, from 1 (wire key `run_attempt`). */
+  readonly runAttempt: Schema.decodeTo<Schema.Int, Schema.String, never, never>;
+  /** The calling workflow's ref, e.g. `octo-org/octo-repo/.github/workflows/ci.yml@refs/heads/main` (wire key `workflow_ref`). */
+  readonly 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`). */
+  readonly jobWorkflowRef: Schema.String;
+  /** The git ref the run is for. */
+  readonly ref: Schema.String;
+  /** The commit SHA the run is for. */
+  readonly sha: Schema.String;
+  /** The event that triggered the run, e.g. `push` (wire key `event_name`). */
+  readonly eventName: Schema.String;
+  /** The login of the user who triggered the run. */
+  readonly actor: Schema.String;
+  /** That user's numeric id (wire key `actor_id`). */
+  readonly actorId: Schema.decodeTo<Schema.Int, Schema.String, never, never>;
+  /** The deployment environment, when the job names one. */
+  readonly environment: Schema.optionalKey<Schema.String>;
+  /** `github-hosted` or `self-hosted` (wire key `runner_environment`). */
+  readonly runnerEnvironment: Schema.String;
+}>, {}>;
+/**
+ * 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
+ */
+export declare class ActionsOidcClaims extends ActionsOidcClaims_base {}
+/**
+ * Options for {@link ActionsOidc.verify}.
+ *
+ * @public
+ */
+interface ActionsOidcVerifyOptions {
+  /**
+   * The audience the token must have been minted for: what the workflow
+   * passed to `core.getIDToken(audience)`. Required and non-empty, because
+   * GitHub's one JWKS signs tokens for every relying party; without an
+   * audience check, any workflow's token for any service would verify.
+   */
+  readonly audience: string;
+  /** Allowed clock skew for `exp`, `nbf` and `iat`; 60 seconds by default. */
+  readonly clockTolerance?: Duration.Input | undefined;
+}
+/**
+ * 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
+ */
+export declare const ActionsOidc: {
+  /** The Actions OIDC issuer, `https://token.actions.githubusercontent.com`. */
+  readonly issuer: "https://token.actions.githubusercontent.com";
+  /** Verify a runner-issued OIDC token: signature against GitHub's JWKS, iss, aud, exp/nbf, then typed claims. */
+  readonly verify: (token: string, options: ActionsOidcVerifyOptions) => Effect.Effect<ActionsOidcClaims, JwtError, JwksResolver>;
+  /**
+   * A valid claims payload for tests, overridable field by field.
+   *
+   * @remarks
+   * Wire-shaped (snake_case keys, string ids) and complete except for the
+   * time claims `iat` and `exp`, which depend on the clock: a signer stamps
+   * them, as `TestIssuer.sign` from `@effected/jwt/testing` does. `iss` is
+   * {@link ActionsOidc.issuer}; `aud` is a placeholder to override with the
+   * audience under test.
+   */
+  readonly testClaims: (overrides?: Readonly<Record<string, unknown>>) => Record<string, unknown>;
+};
+//#endregion
 //#region src/GitHubError.d.ts
 /**
  * Why a GitHub call failed, as a value you can branch on.
@@ -133,6 +284,27 @@ export declare class GitHubError extends GitHubError_base {
    * under test.
    */
   static fromOctokit(operation: string, error: unknown, nowMillis: number): GitHubError;
+  /**
+   * 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: string, response: {
+    readonly status: number;
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    readonly body?: unknown;
+  }, nowMillis: number): GitHubError;
   /**
    * A predicate over one or more kinds, for `Effect.catchIf`.
    *
@@ -650,7 +822,7 @@ interface GitHubClientOptions {
 }
 /**
  * One call served by {@link GitHubClient.layerFixture}, as recorded in
- * {@link GitHubFixtures.requested}.
+ * {@link (GitHubFixtures:interface).requested}.
  *
  * @public
  */
@@ -664,12 +836,80 @@ interface RecordedCall {
   /** The page size asked for; paginated reads only. */
   readonly perPage?: number;
 }
+/**
+ * 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
+ */
+export declare class RawFailure {
+  /** The HTTP status. */
+  readonly status: number;
+  /** The response headers, in any case. */
+  readonly headers: Readonly<Record<string, string>> | undefined;
+  /** The JSON body GitHub would send. */
+  readonly body: unknown;
+  /** @internal */
+  constructor(response: {
+    readonly status: number;
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    readonly body?: unknown;
+  });
+}
+/**
+ * Builders for {@link (GitHubFixtures:interface)} entries.
+ *
+ * @public
+ */
+export declare const GitHubFixtures: {
+  /**
+   * A raw failure: what GitHub answered, classified at call time by the same
+   * classifier the live client uses.
+   *
+   * @remarks
+   * Record it wherever a fixture accepts a `GitHubError` (`request`, and so
+   * `requestDecoded`, and `paginate`). Each call fails with
+   * `GitHubError.fromResponse(route, response, now)`, `now` read from `Clock`,
+   * so a rate-limit reset header is measured against the `TestClock`. Prefer it
+   * to a hand-built `GitHubError` when the test is about GitHub's actual
+   * response: the classification is then the package's, not the test's.
+   *
+   * @example
+   * ```ts
+   * import { GitHubClient, GitHubFixtures } from "@effected/github";
+   *
+   * const layer = GitHubClient.layerFixture({
+   *   request: {
+   *     "POST /repos/{owner}/{repo}/releases": GitHubFixtures.failure({
+   *       status: 422,
+   *       body: {
+   *         message: "Validation Failed",
+   *         errors: [{ resource: "Release", code: "already_exists", field: "tag_name" }],
+   *       },
+   *     }),
+   *   },
+   * });
+   * ```
+   */
+  readonly failure: (response: {
+    readonly status: number;
+    readonly headers?: Readonly<Record<string, string>> | undefined;
+    readonly body?: unknown;
+  }) => RawFailure;
+};
 /**
  * A recorded response table for {@link GitHubClient.layerFixture}.
  *
  * @public
  */
-interface GitHubFixtures {
+export interface GitHubFixtures {
   /**
    * Keyed by route; the value is the `data` payload a request answers with.
    *
@@ -677,14 +917,19 @@ interface GitHubFixtures {
    * A recorded **`GitHubError` is the response**: the call fails with it. That
    * is how a suite stubs a 404 (or a rate-limit, or a 422) deliberately,
    * rather than relying on a route's absence to produce one — absence is a
-   * wiring mistake and {@link GitHubFixtures.unstubbed} treats it as such.
+   * wiring mistake and {@link (GitHubFixtures:interface).unstubbed} treats it as
+   * such. A {@link RawFailure} from {@link (GitHubFixtures:variable).failure}
+   * fails it too, classified from GitHub's raw response.
+   *
+   * A value of `undefined` counts as unstubbed, so stub a route that answers
+   * with no body (a 204) with `null`.
    */
   readonly request?: Readonly<Record<string, unknown>> | undefined;
   /**
    * Keyed by route; the value is the whole collection, paged on demand — or a
-   * `GitHubError` the paginated read fails with.
+   * `GitHubError` or {@link RawFailure} the paginated read fails with.
    */
-  readonly paginate?: Readonly<Record<string, ReadonlyArray<unknown> | GitHubError>> | undefined;
+  readonly paginate?: Readonly<Record<string, ReadonlyArray<unknown> | GitHubError | RawFailure>> | undefined;
   /** Keyed by document name; the value is the raw payload to decode. */
   readonly graphql?: Readonly<Record<string, unknown>> | undefined;
   /**
@@ -813,7 +1058,14 @@ export declare class GitHubClient extends GitHubClient_base {
    * `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 readonly layerFixture: (fixtures: GitHubFixtures) => Layer.Layer<GitHubClient>;
 }
@@ -840,6 +1092,15 @@ declare const RepoRef_base: Schema.Class<RepoRef, Schema.Struct<{
 /**
  * Which repository an operation acts on.
  *
+ * @remarks
+ * **`RepoRef.make` validates at construction and throws** on an empty `owner`
+ * or `repo`, so inside an `Effect` a bad value dies rather than failing. That
+ * is right for a coordinate the program itself spells out, and wrong for one
+ * built from data: for a slug read from a database row, a config file or a
+ * webhook, use {@link RepoRef.parse}, which fails with a typed
+ * {@link InvalidRepoRefError} instead (or {@link RepoRef.parseResult}
+ * outside an `Effect`).
+ *
  * @public
  */
 export declare class RepoRef extends RepoRef_base {
@@ -852,7 +1113,13 @@ export declare class RepoRef extends RepoRef_base {
    * constructor, which is why string parsing is named rather than overloaded.
    */
   static parseResult(slug: string): Result.Result<RepoRef, InvalidRepoRefError>;
-  /** Parse `"owner/repo"`. */
+  /**
+   * Parse `"owner/repo"`, failing with a typed {@link InvalidRepoRefError}.
+   *
+   * @remarks
+   * The typed path for building a `Repo` from stored data, such as a stored
+   * `full_name`: a malformed value fails here, where `make` would die.
+   */
   static readonly parse: (slug: string) => Effect.Effect<RepoRef, InvalidRepoRefError, never>;
   /** `"owner/repo"`. */
   get slug(): string;
@@ -1102,6 +1369,12 @@ declare const CheckRunRef_base: Schema.Class<CheckRunRef, Schema.Struct<{
   /** The web URL. */
   readonly url: Schema.String;
   readonly 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.
+   */
+  readonly externalId: Schema.optionalKey<Schema.String>;
 }>, {}>;
 /**
  * A check run as GitHub reports it.
@@ -1109,6 +1382,56 @@ declare const CheckRunRef_base: Schema.Class<CheckRunRef, Schema.Struct<{
  * @public
  */
 export declare class CheckRunRef extends CheckRunRef_base {}
+/**
+ * Options for {@link CheckRunShape.create}.
+ *
+ * @public
+ */
+interface CreateCheckRunOptions {
+  /**
+   * The run's initial state. Defaults to `"in_progress"`, which also stamps
+   * `started_at`; a `"queued"` run has not started, so it carries none.
+   * Completing a run goes through {@link CheckRunShape.complete}.
+   */
+  readonly status?: "queued" | "in_progress" | undefined;
+  /**
+   * Your own id for the run (wire `external_id`), for
+   * {@link CheckRunShape.findByExternalId}. An empty string is treated as no
+   * id and not sent, since that lookup never matches `""`.
+   */
+  readonly externalId?: string | undefined;
+  /** Where the integrator's full details live (wire `details_url`). */
+  readonly detailsUrl?: string | undefined;
+}
+/**
+ * Options for {@link CheckRunShape.update}.
+ *
+ * @public
+ */
+interface UpdateCheckRunOptions {
+  /**
+   * Move the run to `"queued"` or `"in_progress"`; `"in_progress"` also
+   * stamps `started_at`, as {@link CheckRunShape.create} does. Completing it
+   * goes through {@link CheckRunShape.complete}, which also records the
+   * conclusion.
+   */
+  readonly status?: "queued" | "in_progress" | undefined;
+  /** Where the integrator's full details live (wire `details_url`). */
+  readonly detailsUrl?: string | undefined;
+}
+/**
+ * Options for {@link CheckRunShape.complete}.
+ *
+ * @public
+ */
+interface CompleteCheckRunOptions {
+  /**
+   * Where the integrator's full details live (wire `details_url`) — for
+   * instance the workflow run that produced the verdict. Omitted, the run
+   * keeps whatever details URL it already had.
+   */
+  readonly detailsUrl?: string | undefined;
+}
 /**
  * Conclude the surrounding {@link CheckRunShape.withCheckRun} explicitly.
  *
@@ -1139,13 +1462,48 @@ type ConcludeCheckRun = (conclusion: (typeof CheckConclusion.literals)[number],
  * @public
  */
 interface CheckRunShape {
-  /** Start an in-progress check run against a commit. */
-  readonly create: (name: string, headSha: string) => Effect.Effect<CheckRunRef, GitHubError, Repo>;
+  /** Start a check run against a commit: in progress, unless `options.status` queues it. */
+  readonly create: (name: string, headSha: string, options?: CreateCheckRunOptions) => Effect.Effect<CheckRunRef, GitHubError, Repo>;
   readonly get: (id: number) => Effect.Effect<CheckRunRef, GitHubError, Repo>;
-  /** Update an in-flight run's output. */
-  readonly update: (id: number, output: CheckRunOutput) => Effect.Effect<void, GitHubError, Repo>;
-  /** Finish a run. */
-  readonly complete: (id: number, conclusion: (typeof CheckConclusion.literals)[number], output?: CheckRunOutput) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * Update an in-flight run: its output, its status, its details URL, or any
+   * combination.
+   *
+   * @remarks
+   * Omit `output` (pass `undefined`) to change only the status or details
+   * URL: no `output` key is sent, so the run keeps the output it has. That is
+   * how a queued run moves to `"in_progress"` without rewriting its output.
+   *
+   * `update(id)` with neither still sends **one** PATCH, carrying nothing but
+   * the run's coordinates. GitHub accepts it and changes nothing; it is not
+   * skipped, so every call is exactly one request and a caller's error
+   * handling sees a missing run or a revoked token the same way either way.
+   */
+  readonly update: (id: number, output?: CheckRunOutput, options?: UpdateCheckRunOptions) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * The newest run on `headSha` named `name` whose external id is
+   * `externalId`; none when there is no such run.
+   *
+   * @remarks
+   * Lists every run of the commit filtered by name on GitHub's side
+   * (`filter: "all"`, not GitHub's default of only the latest run per name),
+   * paging through all of them, then matches `external_id` here; "newest" is
+   * the highest id.
+   * An empty `externalId` is none without a request: GitHub reports a run
+   * created without an external id as `""`, so matching on it would find
+   * every such run.
+   */
+  readonly findByExternalId: (headSha: string, name: string, externalId: string) => Effect.Effect<Option.Option<CheckRunRef>, GitHubError, Repo>;
+  /**
+   * Finish a run, stamping `completed_at` from `Clock`.
+   *
+   * @remarks
+   * Omit `output` (pass `undefined`) to conclude without touching the run's
+   * rendered output; a given output is cut to GitHub's byte limits first.
+   * `options.detailsUrl` points the finished run somewhere, such as the
+   * workflow run that produced it.
+   */
+  readonly complete: (id: number, conclusion: (typeof CheckConclusion.literals)[number], output?: CheckRunOutput, options?: CompleteCheckRunOptions) => Effect.Effect<void, GitHubError, Repo>;
   /**
    * Run `use` inside a check run, concluding it however `use` exits.
    *
@@ -1636,6 +1994,52 @@ export declare class GitCommit extends GitCommit_base {
   static readonly layerTest: (overrides?: Partial<GitCommitShape>) => Layer.Layer<GitCommit>;
 }
 //#endregion
+//#region src/InstallationTokenStore.d.ts
+/**
+ * The operations of an {@link InstallationTokenStore}.
+ *
+ * @public
+ */
+interface InstallationTokenStoreShape {
+  /**
+   * The encoded installation token stored for `installationId`, if one is held
+   * and unexpired.
+   */
+  readonly get: (installationId: number) => Effect.Effect<Option.Option<string>>;
+  /** Hold `encoded` for `installationId` for `ttl`. */
+  readonly set: (installationId: number, encoded: string, ttl: Duration.Duration) => Effect.Effect<void>;
+}
+declare const InstallationTokenStore_base: Context.ServiceClass<InstallationTokenStore, "@effected/github/InstallationTokenStore", InstallationTokenStoreShape>;
+/**
+ * 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
+ */
+export declare class InstallationTokenStore extends InstallationTokenStore_base {
+  /** An in-process store over a `Ref`, expiring entries against `Clock`. */
+  static readonly layerMemory: Layer.Layer<InstallationTokenStore>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<InstallationTokenStoreShape>) => InstallationTokenStoreShape;
+  /** {@link InstallationTokenStore.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<InstallationTokenStoreShape>) => Layer.Layer<InstallationTokenStore>;
+}
+//#endregion
 //#region src/GitHubApp.d.ts
 declare const GitHubAppError_base: Schema.Class<GitHubAppError, Schema.TaggedStruct<"GitHubAppError", {
   /** Which step failed. */
@@ -1644,7 +2048,7 @@ declare const GitHubAppError_base: Schema.Class<GitHubAppError, Schema.TaggedStr
   readonly reason: Schema.String;
   /** The underlying failure, when there is one. */
   readonly cause: Schema.optionalKey<Schema.Defect>;
-}>, import("effect/Cause").YieldableError>;
+}>, Cause.YieldableError>;
 /**
  * A GitHub App call failed.
  *
@@ -1677,12 +2081,13 @@ interface AppCredentials {
    * The app's private key, in PEM.
    *
    * @remarks
-   * PKCS#1 (`-----BEGIN RSA PRIVATE KEY-----`, which is what github.com hands
-   * you) is converted to PKCS#8 automatically **on Node**. On a runtime without
-   * `node:crypto` a PKCS#1 key fails with an explicit `kind: "jwt"` error, and
-   * the fix is to convert the key once with
-   * `openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt`. This constraint is
-   * inherited from the JWT signer and is identical to `@octokit/auth-app`'s.
+   * Both PKCS#1 (`-----BEGIN RSA PRIVATE KEY-----`, which is what github.com
+   * hands you) and PKCS#8 (`-----BEGIN PRIVATE KEY-----`) are accepted on every
+   * runtime with WebCrypto, Node and workerd alike: a PKCS#1 key is wrapped to
+   * PKCS#8 in-process, so no conversion step is needed. Newlines may also
+   * arrive escaped as the two characters backslash and `n`, the one-line form
+   * an environment variable carries. The key must be RSA of at least 2048
+   * bits; anything else fails with a `kind: "jwt"` error.
    */
   readonly privateKey: Redacted.Redacted<string>;
 }
@@ -1705,6 +2110,41 @@ interface TokenRequest extends AppCredentials {
    */
   readonly owner?: string | undefined;
 }
+/**
+ * What to fetch a cached installation token for.
+ *
+ * @public
+ */
+interface CachedTokenRequest extends TokenRequest {
+  /**
+   * The installation. Required here: discovering it on every request would
+   * cost a JWT mint and a paginated walk, which defeats the cache.
+   */
+  readonly installationId: number;
+  /**
+   * How long before its expiry a stored token stops being served. Defaults to
+   * five minutes; must be finite and not negative.
+   *
+   * @remarks
+   * A served token has at least `margin` left to live unless GitHub issued it
+   * with less than that, in which case it is returned once and not stored.
+   * GitHub issues installation tokens for an hour, so a margin of an hour or
+   * more guarantees that case: every call mints and nothing is cached.
+   */
+  readonly margin?: Duration.Input | undefined;
+}
+/**
+ * An installation token from {@link GitHubApp.cachedToken}, and where it came
+ * from.
+ *
+ * @public
+ */
+interface CachedToken {
+  /** The token. */
+  readonly token: InstallationToken;
+  /** `"cached"` when it was read from the store, `"minted"` when GitHub issued it just now. */
+  readonly source: "cached" | "minted";
+}
 declare const InstallationToken_base: Schema.Class<InstallationToken, Schema.Struct<{
   /** The token. Decodes to `Redacted`, encodes back to the raw string. */
   readonly token: Schema.RedactedFromValue<Schema.String>;
@@ -1806,12 +2246,36 @@ export declare class AppIdentity extends AppIdentity_base {
 declare const Installation_base: Schema.Class<Installation, Schema.Struct<{
   /** The installation id, which is what a token is minted against. */
   readonly id: Schema.Int;
-  /** The account the app is installed on, when GitHub reported one. */
+  /** The account the app is installed on (its login), when GitHub reported one. */
   readonly account: Schema.optionalKey<Schema.String>;
+  /** The account kind, e.g. "Organization" or "User"; open-ended, because GitHub adds kinds. */
+  readonly 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.
+   */
+  readonly accountId: Schema.optionalKey<Schema.Int>;
+  /** When the installation was suspended; `Option.none()` when it is active. */
+  readonly suspendedAt: Schema.optionalKey<Schema.OptionFromNullOr<Schema.DateTimeUtcFromString>>;
+  /** When GitHub last changed the installation. */
+  readonly updatedAt: Schema.optionalKey<Schema.DateTimeUtcFromString>;
 }>, {}>;
 /**
  * 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
  */
 export declare class Installation extends Installation_base {}
@@ -1847,8 +2311,8 @@ declare const GitHubApp_base: Context.ServiceClass<GitHubApp, "@effected/github/
  * 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
@@ -1904,6 +2368,128 @@ export declare class GitHubApp extends GitHubApp_base {
    * would tax every caller for a case only this layer can produce.
    */
   static readonly clientLayer: (request: TokenRequest, options?: GitHubAppOptions) => Layer.Layer<GitHubClient, GitHubAppError>;
+  /**
+   * 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 readonly appClientLayer: (credentials: AppCredentials, options?: GitHubAppOptions) => Layer.Layer<GitHubClient, GitHubAppError>;
+  /**
+   * 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 readonly cachedToken: (request: CachedTokenRequest) => Effect.Effect<CachedToken, GitHubAppError, GitHubApp | InstallationTokenStore>;
+  /**
+   * 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 readonly cachedClientLayer: (request: CachedTokenRequest, options?: GitHubAppOptions) => Layer.Layer<GitHubClient, GitHubAppError, GitHubApp | InstallationTokenStore>;
   /** An in-memory double; unstubbed members die naming themselves. */
   static readonly makeTest: (overrides?: Partial<GitHubAppShape>) => GitHubAppShape;
   /** {@link GitHubApp.makeTest} behind a `Layer`. */
@@ -2105,6 +2691,12 @@ interface GitHubContentShape {
    * Fails `notFound` when the path does not exist, and `rejected` when it is a
    * directory, is not a regular file, or is too large for the contents API
    * (which answers an empty body above roughly a megabyte).
+   *
+   * Fails `decode` when the payload is not valid base64. Only **standard,
+   * padded** base64 is accepted, which is what the contents API sends; the
+   * line breaks it wraps the payload with are ignored. Unpadded or URL-safe
+   * (`-`/`_`) input is rejected rather than guessed at. The bytes decode as
+   * UTF-8, keeping a leading BOM as content.
    */
   readonly getFile: (path: string, options?: {
     readonly ref?: string | undefined;
@@ -3661,6 +4253,25 @@ export declare class WorkflowRunStatus extends WorkflowRunStatus_base {
   /** Has the run finished, whatever the outcome? */
   get isDone(): boolean;
 }
+declare const DispatchedRun_base: Schema.Class<DispatchedRun, Schema.Struct<{
+  /** The created run's numeric id. */
+  readonly runId: Schema.Int;
+  /** The run's API URL. */
+  readonly runUrl: Schema.String;
+  /** The run's web URL. */
+  readonly htmlUrl: Schema.String;
+}>, {}>;
+/**
+ * The run a `workflow_dispatch` created, as GitHub reports it when asked.
+ *
+ * @remarks
+ * Returned by {@link WorkflowDispatchShape.dispatchWithRun}. `runId` is usable
+ * directly with {@link WorkflowDispatchShape.runStatus} and
+ * {@link WorkflowDispatchShape.cancelRun}.
+ *
+ * @public
+ */
+export declare class DispatchedRun extends DispatchedRun_base {}
 /**
  * One workflow defined in the repository.
  *
@@ -3701,10 +4312,47 @@ interface PollOptions {
  * @public
  */
 interface WorkflowDispatchShape {
-  /** Fire a `workflow_dispatch` event. GitHub answers 204 with no run id. */
+  /**
+   * Fire a `workflow_dispatch` event and discard GitHub's answer; use
+   * {@link WorkflowDispatchShape.dispatchWithRun} when the run id is needed.
+   */
   readonly dispatch: (workflow: string, ref: string, inputs?: Record<string, string>) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * Fire a `workflow_dispatch` event and report the run it created.
+   *
+   * @remarks
+   * Sends the same request as {@link WorkflowDispatchShape.dispatch} with
+   * `return_run_details: true`. GitHub then answers 200 with the run's id and
+   * URLs, which arrive as `Option.some` of a {@link DispatchedRun}; a 200 body
+   * that does not have that shape fails with a `decode` `GitHubError`.
+   *
+   * A 204 with no body is `Option.none()`. That is what a GitHub Enterprise
+   * Server predating the field answers — it ignores `return_run_details` and
+   * still dispatches — so it is **not a failure**: the workflow was dispatched,
+   * the server just did not say which run it created.
+   *
+   * Under `GitHubClient.layerFixture`, stub the 204 the way every other
+   * no-body route is stubbed: answer the dispatch route with `null`. `""`
+   * (what octokit itself hands back for an empty body) works too.
+   *
+   * Every failure of the request itself (a 404 for an unknown workflow, a 422
+   * for a workflow without a `workflow_dispatch` trigger, …) is the
+   * `GitHubError` the client classified, passed through unchanged.
+   */
+  readonly dispatchWithRun: (workflow: string, ref: string, inputs?: Record<string, string>) => Effect.Effect<Option.Option<DispatchedRun>, GitHubError, Repo>;
   /** Read one workflow run's status. */
   readonly runStatus: (runId: number) => Effect.Effect<WorkflowRunStatus, GitHubError, Repo>;
+  /**
+   * Cancel a workflow run.
+   *
+   * @remarks
+   * `"cancelled"` when GitHub accepted the cancellation (202; the run stops
+   * shortly after, not necessarily before this returns). GitHub answers 409
+   * when the run has already finished, which is `"alreadyCompleted"` rather
+   * than a failure: the run is not running either way. Any other failure,
+   * such as a 404 for an unknown run, is a `GitHubError`.
+   */
+  readonly cancelRun: (runId: number) => Effect.Effect<"cancelled" | "alreadyCompleted", GitHubError, Repo>;
   /**
    * Every workflow defined in the repository.
    *
@@ -3727,8 +4375,15 @@ interface WorkflowDispatchShape {
    * The wait is `Effect.repeat` with a predicate over the **success** value, so
    * "not finished yet" is never an error. If the run is not found finished
    * within `poll.timeout`, it fails with a `rejected` `GitHubError` (status
-   * 408). The run is matched by branch, creation time and workflow path, so
-   * concurrent dispatches of the same workflow on the same ref can be confused.
+   * 408).
+   *
+   * The run is identified by {@link WorkflowDispatchShape.dispatchWithRun}:
+   * when GitHub reports the run it created, exactly that run is polled, so
+   * concurrent dispatches cannot be confused. When it does not (a 204 from a
+   * GitHub Enterprise Server predating `return_run_details`), the run is found
+   * instead by branch, creation time and workflow path — and on that fallback
+   * alone, concurrent dispatches of the same workflow on the same ref can be
+   * confused.
    */
   readonly dispatchAndWait: (workflow: string, ref: string, options?: {
     readonly inputs?: Record<string, string> | undefined;
@@ -3771,5 +4426,5 @@ export declare class WorkflowDispatch extends WorkflowDispatch_base {
   static readonly layerTest: (overrides?: Partial<WorkflowDispatchShape>) => Layer.Layer<WorkflowDispatch>;
 }
 //#endregion
-export { type AppCredentials, type AppliedSettings, type ArtifactMetadataShape, type AttestationShape, type BareLineReference, type BranchOutcome, CLOSING_KEYWORDS, type CheckRunShape, type ClosingKeyword, type CodeScanningSetup, type CodeScanningShape, type ConcludeCheckRun, type DeploymentEnvironmentInfo, type DeploymentEnvironmentShape, type GitBranchShape, type GitCommitShape, type GitHubAppOptions, type GitHubAppShape, type GitHubClientOptions, type GitHubClientShape, type GitHubCommitShape, type GitHubContentShape, type GitHubFixtures, type GitHubIssueShape, type GitHubReleaseShape, type GitHubRepositoryShape, type GitTagShape, type IssueReference, type LatestSemverOptions, type OwnerType, type PollOptions, type PullRequestCommentShape, type PullRequestShape, type RecordedCall, type RepositoryPatch, type RepositoryPatchDraft, type RepositorySecretShape, type RepositorySecurityShape, type RepositorySettings, type RepositoryVariableShape, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, type RetryableFailure, type RulesetInfo, type RulesetPayload, type RulesetShape, type SecretInfo, type SecretScope, type TokenRequest, type UpsertedPullRequest, type VariableInfo, type VersionFromTag, type WorkflowDispatchShape, type WorkflowInfo, harvestIssueReferences, parseBareLineReference };
+export { type ActionsOidcVerifyOptions, type AppCredentials, type AppliedSettings, type ArtifactMetadataShape, type AttestationShape, type BareLineReference, type BranchOutcome, CLOSING_KEYWORDS, type CachedToken, type CachedTokenRequest, type CheckRunShape, type ClosingKeyword, type CodeScanningSetup, type CodeScanningShape, type CompleteCheckRunOptions, type ConcludeCheckRun, type CreateCheckRunOptions, type DeploymentEnvironmentInfo, type DeploymentEnvironmentShape, type GitBranchShape, type GitCommitShape, type GitHubAppOptions, type GitHubAppShape, type GitHubClientOptions, type GitHubClientShape, type GitHubCommitShape, type GitHubContentShape, type GitHubIssueShape, type GitHubReleaseShape, type GitHubRepositoryShape, type GitTagShape, type InstallationTokenStoreShape, type IssueReference, type LatestSemverOptions, type OwnerType, type PollOptions, type PullRequestCommentShape, type PullRequestShape, type RecordedCall, type RepositoryPatch, type RepositoryPatchDraft, type RepositorySecretShape, type RepositorySecurityShape, type RepositorySettings, type RepositoryVariableShape, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, type RetryableFailure, type RulesetInfo, type RulesetPayload, type RulesetShape, type SecretInfo, type SecretScope, type TokenRequest, type UpdateCheckRunOptions, type UpsertedPullRequest, type VariableInfo, type VersionFromTag, type WorkflowDispatchShape, type WorkflowInfo, harvestIssueReferences, parseBareLineReference };
 //# sourceMappingURL=index.d.ts.map