@effected/github 0.25.1 → 0.27.0

package/index.d.ts

@@ -1,6 +1,7 @@
 import { BareLineReference, CLOSING_KEYWORDS, ClosingKeyword, IssueReference, harvestIssueReferences, parseBareLineReference } from "@effected/github-references";
 import { JwksResolver, JwtError } from "@effected/jwt";
 import { Cause, Config, Context, Duration, Effect, Layer, Option, Redacted, Result, Schedule, Schema, Scope, Stream } from "effect";
+import { Signature } from "effect/crypto";
 import { PaginatingEndpoints } from "@octokit/plugin-paginate-rest";
 import { Endpoints, RequestHeaders } from "@octokit/types";
 import { SemVer } from "@effected/semver";
@@ -126,7 +127,8 @@ interface ActionsOidcVerifyOptions {
  * @remarks
  * {@link ActionsOidc.verify} is `@effected/oidc`'s `Oidc.verify` pinned to the
  * Actions issuer: it checks the signature against GitHub's published JWKS
- * (through `@effected/jwt`'s `JwksResolver`, which caches it), then `iss`,
+ * (through `@effected/jwt`'s `JwksResolver`, which caches it; the signature
+ * itself runs on core `effect/jose` and needs core's `Signature` service), 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.
@@ -151,7 +153,8 @@ interface ActionsOidcVerifyOptions {
  * ```ts
  * import { JwksResolver } from "@effected/jwt";
  * import { ActionsOidc } from "@effected/github";
- * import { Data, Effect } from "effect";
+ * import { Data, Effect, Layer } from "effect";
+ * import { SecureRandom, Signature } from "effect/crypto";
  *
  * class Forbidden extends Data.TaggedError("Forbidden")<{ readonly repositoryId: number }> {}
  *
@@ -169,7 +172,8 @@ interface ActionsOidcVerifyOptions {
  *   });
  *
  * // JwksResolver.layer needs an HttpClient and a JwksStore, provided once at the edge.
- * export const program = authorize("eyJ...").pipe(Effect.provide(JwksResolver.layer));
+ * const CryptoLive = Signature.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto));
+ * export const program = authorize("eyJ...").pipe(Effect.provide(Layer.merge(JwksResolver.layer, CryptoLive)));
  * ```
  *
  * @public
@@ -178,8 +182,8 @@ export declare class ActionsOidc {
   private constructor();
   /** The Actions OIDC issuer, `https://token.actions.githubusercontent.com`. */
   static 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. */
-  static readonly verify: (token: string, options: ActionsOidcVerifyOptions) => Effect.Effect<ActionsOidcClaims, JwtError, JwksResolver>;
+  /** Verify a runner-issued OIDC token: signature against GitHub's JWKS, iss, aud, exp/nbf, then typed claims; requires `JwksResolver` and core `Signature`. */
+  static readonly verify: (token: string, options: ActionsOidcVerifyOptions) => Effect.Effect<ActionsOidcClaims, JwtError, JwksResolver | Signature.Signature>;
   /**
    * A valid claims payload for tests, overridable field by field.
    *
@@ -272,7 +276,7 @@ declare const GitHubError_base: Schema.Class<GitHubError, Schema.TaggedStruct<"G
    * 422s ("Update is not a fast forward") are prose only.
    */
   readonly validation: Schema.optionalKey<Schema.$Array<typeof GitHubValidationEntry>>;
-  /** The underlying throwable, when one exists. */
+  /** The underlying throwable, when one exists; an octokit throwable is kept as a credential-free copy. */
   readonly cause: Schema.optionalKey<Schema.Defect>;
 }>, import("effect/Cause").YieldableError>;
 /**
@@ -318,6 +322,16 @@ export declare class GitHubError extends GitHubError_base {
    * epoch second, and turning it into a delay needs a "now" the caller controls.
    * The client supplies `Clock.currentTimeMillis`, which is the `TestClock`
    * under test.
+   *
+   * The kept `cause` is a credential-free copy of the throwable, not the
+   * throwable itself. octokit redacts only the `authorization` credential and
+   * two query values; the copy also drops the request body (a webhook secret,
+   * GraphQL variables), the per-request options and the response body beyond
+   * its top-level `message` and `documentation_url`, drops `set-cookie`, and
+   * reads `REDACTED` for every other credential-bearing header. It keeps the
+   * prototype (so `instanceof` still answers), `name`, `message`, `status`,
+   * the method, the redacted url and the remaining headers. A throwable with
+   * no `request`, `response` or `headers` field is kept as it is.
    */
   static fromOctokit(operation: string, error: unknown, nowMillis: number): GitHubError;
   /**
@@ -437,6 +451,11 @@ export declare class GitHubGraphQLError extends GitHubGraphQLError_base {
    * failure with a `status`. Both arrive as throwables and both are read
    * structurally, for the same reason the REST classifier does it — the error
    * classes live in packages this one does not declare.
+   *
+   * The kept `cause` is the same credential-free copy
+   * {@link GitHubError.fromOctokit} keeps: the GraphQL document, its variables
+   * and any partial `data` are dropped with the rest of the request and response
+   * bodies.
    */
   static fromThrowable(operation: string, error: unknown, nowMillis: number): GitHubGraphQLError;
 }
@@ -649,17 +668,22 @@ export declare class RetryPolicy extends RetryPolicy_base {
  */
 type Route = keyof Endpoints;
 /**
- * Transport knobs octokit accepts on any route, narrowed to the three this
+ * Transport knobs octokit accepts on any route, narrowed to the two this
  * package allows.
  *
  * @remarks
  * octokit's own `RequestParameters` carries an `[parameter: string]: unknown`
  * index signature, so intersecting it would silently accept every misspelled
- * parameter. These three are the ones callers need:
- * `headers` for a release asset's `content-type` and the attestations API
- * version pin, `mediaType.format` for raw content reads, and `baseUrl` for the
- * `uploads.github.com` host that release-asset uploads go to. Everything else a
- * caller might reach for is a real endpoint parameter and is already typed.
+ * parameter. These two are the ones callers need: `headers` for a release
+ * asset's `content-type` and the attestations API version pin, and
+ * `mediaType.format` for raw content reads. Everything else a caller might
+ * reach for is a real endpoint parameter and is already typed.
+ *
+ * There is no knob that moves a request: **a client's token only ever goes to
+ * the host it was configured with.** octokit reads `baseUrl` and `url` off the
+ * flat parameters as the request's host, so the raw surface refuses either
+ * name, and an absolute-URL route, with a `rejected` `GitHubError` and nothing
+ * sent. A request to another GitHub host is a second client configured for it.
  *
  * @public
  */
@@ -670,16 +694,21 @@ interface RequestExtras {
   readonly mediaType?: {
     readonly format?: string;
   };
-  /** Overrides the API host for this one request. */
-  readonly baseUrl?: string;
 }
 /**
  * The parameters `Route` accepts — path, query and body parameters from
  * GitHub's OpenAPI description, plus the extras below.
  *
+ * @remarks
+ * `baseUrl` is typed `never`, so passing one is a compile error: the request
+ * goes to the client's configured host and nowhere else. One that arrives
+ * through a cast is refused at runtime.
+ *
  * @public
  */
-type Params<R extends Route> = Endpoints[R]["parameters"] & RequestExtras;
+type Params<R extends Route> = Endpoints[R]["parameters"] & RequestExtras & {
+  readonly baseUrl?: never;
+};
 /**
  * The full response `Route` returns, including `status`, `headers` and `data`.
  *
@@ -770,6 +799,12 @@ interface GitHubClientShape {
   /**
    * One request. The route types both the parameters and the returned `data`.
    *
+   * @remarks
+   * The request carries this client's token to the configured base URL and
+   * nowhere else. A `baseUrl` or `url` parameter (through a cast), or a
+   * route that resolves to another origin, fails `kind: "rejected"` with no
+   * status and nothing sent.
+   *
    * @example
    * ```ts
    * import { GitHubClient } from "@effected/github";
@@ -794,13 +829,29 @@ interface GitHubClientShape {
    * checked. The attestations read uses it, because pinning
    * `X-GitHub-Api-Version` puts the response on a contract the generated types
    * do not describe.
+   *
+   * The token goes to the configured base URL and nowhere else. An
+   * absolute-URL route (`"POST https://host/path"`, which octokit would send
+   * as written) on another origin, a `baseUrl`, `url`, `request` or `method`
+   * parameter, or a template that expands to another host fails
+   * `kind: "rejected"` with no status and nothing sent. A body field octokit
+   * would otherwise read as an option, such as a webhook configuration's
+   * `url`, goes inside `data`, which is sent as the whole body.
    */
-  readonly requestDecoded: <A, I>(route: string, params: Record<string, unknown> & RequestExtras, schema: Schema.Codec<A, I>) => Effect.Effect<A, GitHubError>;
+  readonly requestDecoded: <A, I>(route: string, params: Record<string, unknown> & RequestExtras & {
+    readonly baseUrl?: never;
+  }, schema: Schema.Codec<A, I>) => Effect.Effect<A, GitHubError>;
   /**
    * Collect every page of a paginating route, honoring {@link PageOptions}.
    *
    * @remarks
    * Handing this a non-paginating route is a compile error.
+   *
+   * Every page goes to the configured host. A route or parameter that
+   * resolves elsewhere is refused before the first request, and a `Link`
+   * header whose next page names another origin fails the walk
+   * `kind: "rejected"` before that page is requested, rather than sending the
+   * token there or ending the walk early as if the collection were complete.
    */
   readonly paginate: <R extends PaginatingRoute>(route: R, params: Params<R>, options?: PageOptions) => Effect.Effect<ReadonlyArray<Item<R>>, GitHubError>;
   /**
@@ -808,7 +859,8 @@ interface GitHubClientShape {
    *
    * @remarks
    * Lazy in requests: a downstream `Stream.take` stops the walk rather than
-   * filtering pages that were already fetched.
+   * filtering pages that were already fetched. Confined to the configured
+   * host exactly as {@link GitHubClientShape.paginate} is.
    */
   readonly paginateStream: <R extends PaginatingRoute>(route: R, params: Params<R>, options?: PageOptions) => Stream.Stream<Item<R>, GitHubError>;
   /** Run an owned GraphQL document and decode its answer. */
@@ -1116,6 +1168,12 @@ export declare class GitHubClient extends GitHubClient_base {
    * `rateLimit` answers `Option.none()` and `apiVersion` the live default,
    * because a real client legitimately answers both without a request.
    *
+   * It refuses what the live client refuses, before any override runs: a
+   * `baseUrl`, `url`, `request` or `method` parameter (a body field called
+   * `url` goes inside `data`), or a route that resolves off github.com's REST
+   * root, fails `kind: "rejected"` with no status. A double has no
+   * configured base, so an absolute-URL route must name `api.github.com`.
+   *
    * For recorded responses that page for real, use
    * {@link GitHubClient.layerFixture}.
    */
@@ -1140,6 +1198,11 @@ export declare class GitHubClient extends GitHubClient_base {
    * 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.
+   *
+   * It refuses what the live client refuses, exactly as
+   * {@link GitHubClient.makeTest} does. A refused call fails
+   * `kind: "rejected"` and is **not** recorded in `requested`: it is never
+   * served, as a refused live call never reaches the wire.
    */
   static readonly layerFixture: (fixtures: GitHubFixtures) => Layer.Layer<GitHubClient>;
 }
@@ -2090,6 +2153,14 @@ interface DeploymentEnvironmentShape {
    * `config` stays an open record because the protection-rule body is a moving
    * target: wait timers, reviewers, deployment-branch policies and whatever
    * GitHub adds next.
+   *
+   * It is sent as the request BODY and nothing else. octokit reads `baseUrl`,
+   * `url`, `method`, `headers`, `request` and `mediaType` off a call's flat
+   * parameters as the request itself, and a `data` key as the whole body, so a
+   * config spread beside the coordinates could send the authenticated `PUT` to
+   * another host with the token attached. A config naming one of those, the
+   * route's own `owner`, `repo` or `environment_name`, or `__proto__`, dies
+   * with a `RangeError` before any request is made.
    */
   readonly upsert: (name: string, config?: Record<string, unknown>) => Effect.Effect<void, GitHubError, Repo>;
   /** The repository's deployment environments. */
@@ -2781,7 +2852,7 @@ declare const GitHubApp_base: Context.ServiceClass<GitHubApp, "@effected/github/
  */
 export declare class GitHubApp extends GitHubApp_base {
   /** The default transport. Bind it once; layers are memoized by reference. */
-  static readonly layer: Layer.Layer<GitHubApp>;
+  static readonly layer: Layer.Layer<GitHubApp, never, Signature.Signature>;
   /**
    * A transport with custom settings.
    *
@@ -2790,7 +2861,7 @@ export declare class GitHubApp extends GitHubApp_base {
    * this at two provide sites builds two instances, because layers are
    * memoized by reference.
    */
-  static readonly layerWith: (options: GitHubAppOptions) => Layer.Layer<GitHubApp>;
+  static readonly layerWith: (options: GitHubAppOptions) => Layer.Layer<GitHubApp, never, Signature.Signature>;
   /**
    * A {@link GitHubClient} authenticated as an app installation.
    *
@@ -2809,7 +2880,7 @@ export declare class GitHubApp extends GitHubApp_base {
    * 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 readonly clientLayer: (request: TokenRequest, options?: GitHubAppOptions) => Layer.Layer<GitHubClient, GitHubAppError>;
+  static readonly clientLayer: (request: TokenRequest, options?: GitHubAppOptions) => Layer.Layer<GitHubClient, GitHubAppError, Signature.Signature>;
   /**
    * A {@link GitHubClient} authenticated as the app itself, with an App JWT.
    *
@@ -2862,7 +2933,7 @@ export declare class GitHubApp extends GitHubApp_base {
    * Effect.runPromise(Effect.provide(sweep, layer));
    * ```
    */
-  static readonly appClientLayer: (credentials: AppCredentials, options?: GitHubAppOptions) => Layer.Layer<GitHubClient, GitHubAppError>;
+  static readonly appClientLayer: (credentials: AppCredentials, options?: GitHubAppOptions) => Layer.Layer<GitHubClient, GitHubAppError, Signature.Signature>;
   /**
    * An installation token, reused from an {@link InstallationTokenStore}
    * while it has `margin` (five minutes by default) left to live.
@@ -3470,7 +3541,15 @@ declare const ReleaseInfo_base: Schema.Class<ReleaseInfo, Schema.Struct<{
   readonly prerelease: Schema.Boolean;
   /** The web URL. */
   readonly url: Schema.String;
-  /** The templated upload endpoint GitHub hands back for assets. */
+  /**
+   * The templated upload endpoint GitHub hands back for assets.
+   *
+   * @remarks
+   * {@link GitHubReleaseShape.uploadAsset} never routes by this value: it is
+   * response data. It only cross-checks that its origin is the upload host
+   * derived from the client's configured base URL, and refuses the upload
+   * when it is not.
+   */
   readonly uploadUrl: Schema.String;
 }>, {}>;
 /**
@@ -3528,9 +3607,9 @@ interface GitHubReleaseShape {
    *
    * @remarks
    * The one route in this package that is **not** in GitHub's generated
-   * endpoint map: asset upload goes to `uploads.github.com` with a raw binary
-   * body, and the map omits it. So it goes through `requestDecoded` with an
-   * owned schema — the escape hatch is from the route table, never from typing.
+   * endpoint map: asset upload goes to a separate upload host with a raw
+   * binary body, and the map omits it. So it is decoded against an owned
+   * schema — the escape hatch is from the route table, never from typing.
    *
    * Being outside the map cuts the other way too: octokit has no schema
    * saying `name` is a **query** parameter, so the route template must carry
@@ -3538,6 +3617,29 @@ interface GitHubReleaseShape {
    * `Invalid name for request` — a hand-written route owns its query
    * parameters in the template, always. `label` is the endpoint's optional
    * display label, shown in place of the file name on the release page.
+   *
+   * The upload host is derived from the base URL the client was **configured**
+   * with, so the token only goes where the caller pointed it: github.com
+   * (`https://api.github.com`, or no `baseUrl`) uploads to
+   * `https://uploads.github.com`, GitHub Enterprise Server
+   * (`https://<host>/api/v3`) to `https://<host>/api/uploads`, and any other
+   * base to itself. The release's own `uploadUrl` is response data, so it is
+   * never the route; its origin must equal the derived host's, or the call
+   * fails `kind: "rejected"` with no status and nothing is sent.
+   *
+   * The client's public `requestDecoded` cannot reach the upload host: it
+   * refuses every host but the configured API host. A client this package
+   * built uploads through a private channel it carries off its public type,
+   * which takes no host from anyone. A shape spread from a built client
+   * (`{ ...client, requestDecoded }`) keeps that channel, so its upload does
+   * **not** go through an overridden `requestDecoded`.
+   *
+   * A client shape this package did not build (`GitHubClient.makeTest`,
+   * `layerFixture`, a hand-written double) has no channel: it is read as
+   * github.com for the `uploadUrl` check, and the upload is handed to its own
+   * `requestDecoded`, so a double records and answers it as usual. Before
+   * these checks, a GitHub Enterprise Server client's upload sent its token to
+   * `uploads.github.com`.
    */
   readonly uploadAsset: (release: ReleaseInfo, asset: {
     readonly name: string;
@@ -3593,11 +3695,20 @@ export declare class GitHubRelease extends GitHubRelease_base {
  */
 type RepositorySettings = Data<"GET /repos/{owner}/{repo}">;
 /**
- * The fields `PATCH /repos/{owner}/{repo}` accepts, minus the coordinate.
+ * The fields `PATCH /repos/{owner}/{repo}` accepts, minus the coordinate and
+ * the per-request transport options.
+ *
+ * @remarks
+ * A patch is the request **body** and nothing else. `GitHubRepository`
+ * sends it as octokit's `data` option, so no key in it is ever read as a
+ * request option (`baseUrl`, `url`, `headers`, `request`, `mediaType`) or as
+ * the route's `owner` / `repo`. The transport knobs of `Rest.RequestExtras`
+ * are therefore left out of the type: carried in a patch they would be body
+ * fields, not the options they are named after.
  *
  * @public
  */
-type RepositoryPatch = Omit<Params<"PATCH /repos/{owner}/{repo}">, "owner" | "repo">;
+type RepositoryPatch = Omit<Params<"PATCH /repos/{owner}/{repo}">, "owner" | "repo" | keyof RequestExtras>;
 /**
  * A {@link RepositoryPatch} under construction, where an absent field may be
  * spelled as an explicit `undefined`.
@@ -3613,9 +3724,66 @@ type RepositoryPatch = Omit<Params<"PATCH /repos/{owner}/{repo}">, "owner" | "re
  * @public
  */
 type RepositoryPatchDraft = { readonly [K in keyof RepositoryPatch]?: RepositoryPatch[K] | undefined; };
+/**
+ * Repository settings the generated {@link RepositoryPatch} type does not know
+ * yet, for {@link RepositoryPatchOptions.extra}.
+ *
+ * @remarks
+ * An open map minus every key `RepositoryPatch` declares: a known key written
+ * here is a compile error, so it has to go in the draft, where its value is
+ * checked against octokit's type. Only what octokit has not caught up with
+ * travels unchecked. The guard holds for a literal; a value already typed
+ * `Record<string, unknown>` assigns anyway (an index signature does not meet an
+ * optional property), which is why {@link repositoryPatch} checks again at
+ * runtime.
+ *
+ * @public
+ */
+type RepositoryPatchExtra = {
+  readonly [key: string]: unknown;
+} & { readonly [K in keyof RepositoryPatch]?: never; } & { readonly [K in RepositoryPatchReservedKey]?: never; };
+/**
+ * Names {@link repositoryPatch} refuses in a draft or an extra.
+ *
+ * @remarks
+ * octokit takes a route's path parameters, body fields and transport options
+ * in one flat object, and `@octokit/endpoint` reads these names as the request
+ * itself: `baseUrl` and `url` pick the host the authenticated request goes to,
+ * `headers` its headers, `request` the fetch implementation, `data` the whole
+ * body, `method` the verb, and `owner` / `repo` the path of
+ * `PATCH /repos/{owner}/{repo}`. `__proto__` would set the patch's prototype
+ * instead of a field. None of them is a repository setting.
+ *
+ * @public
+ */
+type RepositoryPatchReservedKey = "method" | "baseUrl" | "url" | "headers" | "request" | "mediaType" | "data" | "owner" | "repo" | "__proto__";
+/**
+ * Options for {@link repositoryPatch}.
+ *
+ * @public
+ */
+interface RepositoryPatchOptions {
+  /**
+   * Settings GitHub accepts that octokit's generated types do not declare
+   * yet, sent verbatim.
+   *
+   * @remarks
+   * **GitHub may ignore them silently.** The REST `PATCH` answers 200 for a
+   * field it does not recognise, so a misspelled extra reads as applied while
+   * nothing changed: read the setting back when it matters. An `undefined`
+   * value is dropped, as in the draft. A key the PATCH body already declares,
+   * or a GraphQL-only setting (`has_sponsorships`, `has_pull_requests`,
+   * `has_discussions`, which this patch cannot set; use
+   * `GitHubRepository.applySettings`), throws a `RangeError` naming it, as
+   * does a {@link RepositoryPatchReservedKey}: an octokit request option
+   * (`baseUrl`, `url`, `headers`, `request`, `data`, and so on), the route's
+   * own `owner` / `repo`, or `__proto__`.
+   */
+  readonly extra?: RepositoryPatchExtra | undefined;
+}
 /**
  * A {@link RepositoryPatch} from a draft, dropping every explicitly-`undefined`
- * field.
+ * field, plus any settings octokit's types do not know yet.
  *
  * @remarks
  * The supported spelling for "apply only what was configured" — the natural
@@ -3625,6 +3793,13 @@ type RepositoryPatchDraft = { readonly [K in keyof RepositoryPatch]?: Repository
  * `PATCH` treats an absent field as "leave it alone", while an explicit `null`
  * or `undefined` is a value.
  *
+ * `options.extra` is the typed escape hatch for a setting GitHub accepts
+ * before octokit's generated types declare it: the draft stays checked, and
+ * only the extras ride unchecked. The result is still typed `RepositoryPatch`,
+ * and `GitHubRepository.updateSettings` sends every key it carries. A known key
+ * passed through `extra` throws a `RangeError` rather than skipping the draft's
+ * type check (see {@link RepositoryPatchOptions.extra}).
+ *
  * A key-by-key loop still defeats TypeScript's correlation between two indexed
  * accesses (`draft[key] = source[key]` over a union `key`), which no helper can
  * fix — build the draft as a literal where you can.
@@ -3634,19 +3809,24 @@ type RepositoryPatchDraft = { readonly [K in keyof RepositoryPatch]?: Repository
  * import { repositoryPatch } from "@effected/github";
  *
  * // `config.has_issues` is `boolean | undefined`; absent fields drop out.
- * const patch = repositoryPatch({
- *   has_issues: config.has_issues,
- *   has_wiki: config.has_wiki,
- *   description: config.description,
- * });
+ * const patch = repositoryPatch(
+ *   {
+ *     has_issues: config.has_issues,
+ *     has_wiki: config.has_wiki,
+ *     description: config.description,
+ *   },
+ *   // A setting GitHub accepts before octokit's types declare it.
+ *   { extra: { has_new_feature: true } },
+ * );
  * ```
  *
  * @param draft - The fields to apply, any of which may be `undefined`.
+ * @param options - `extra`: settings the generated type does not declare.
  * @returns A patch carrying only the fields that were actually set.
  *
  * @public
  */
-export declare const repositoryPatch: (draft: RepositoryPatchDraft) => RepositoryPatch;
+export declare const repositoryPatch: (draft: RepositoryPatchDraft, options?: RepositoryPatchOptions) => RepositoryPatch;
 /**
  * Whether an account is a user or an organization.
  *
@@ -3741,8 +3921,50 @@ interface AppliedSettings {
    * REST `PATCH` ignores unknown fields and answers 200, so the key would be
    * reported applied while the repository never changed. A caller that wants
    * an unknown key to fail the run checks this list.
+   *
+   * Under `unknownKeys: "send"` an undescribed key is sent instead and named
+   * in {@link AppliedSettings.unverified}; a key the api-version removed is
+   * still ignored, because the description says GitHub drops it.
+   *
+   * Under either mode, a name octokit reads as a request option rather than
+   * a body field (`baseUrl`, `url`, `headers`, `request`, `mediaType`,
+   * `method`, `data`), the route's own `owner` / `repo`, and `__proto__` are
+   * never sent and land here.
    */
   readonly ignored: ReadonlyArray<string>;
+  /**
+   * Keys sent on the REST patch that GitHub's description does not declare,
+   * so nothing confirms GitHub acted on them. Always a subset of
+   * {@link AppliedSettings.rest}, and empty unless the call passed
+   * `unknownKeys: "send"`.
+   *
+   * @remarks
+   * The REST `PATCH` answers 200 whether or not it recognised a field, so a
+   * key here may have changed the repository or done nothing. Read the setting
+   * back when it matters.
+   */
+  readonly unverified: ReadonlyArray<string>;
+}
+/**
+ * Options for {@link GitHubRepositoryShape.applySettings}.
+ *
+ * @public
+ */
+interface ApplySettingsOptions {
+  /**
+   * What to do with a key neither API declares. `"ignore"` (the default)
+   * leaves it unsent and reports it in {@link AppliedSettings.ignored};
+   * `"send"` forwards it on the REST patch verbatim and reports it in
+   * {@link AppliedSettings.rest} and {@link AppliedSettings.unverified}.
+   *
+   * @remarks
+   * `"send"` is for a sync tool applying settings a user declared that GitHub
+   * accepts before its OpenAPI description, and octokit's types, catch up.
+   * The cost is that a typo is sent too and answered 200, so it is only as
+   * safe as the caller's own validation. GraphQL-only keys still route to
+   * GraphQL, and a key the client's api-version removed is still ignored.
+   */
+  readonly unknownKeys?: "ignore" | "send" | undefined;
 }
 /**
  * Read and update a repository's settings and topics, and look up its default
@@ -3809,8 +4031,12 @@ interface GitHubRepositoryShape {
    * in `ignored`, rather than forwarded to a `PATCH` that would ignore it and
    * answer 200. It does not fail the call, so additive GitHub API growth never
    * breaks a run; a caller that owns a schema should still validate first.
+   *
+   * A setting GitHub accepts before its description declares it is sent with
+   * `{ unknownKeys: "send" }` ({@link ApplySettingsOptions}), and reported in
+   * `unverified` as well as `rest`, because a 200 does not say GitHub used it.
    */
-  readonly applySettings: (settings: Record<string, unknown>) => Effect.Effect<AppliedSettings, GitHubError | GitHubGraphQLError, Repo>;
+  readonly applySettings: (settings: Record<string, unknown>, options?: ApplySettingsOptions) => Effect.Effect<AppliedSettings, GitHubError | GitHubGraphQLError, Repo>;
   /**
    * The repository's topics, as GitHub stores them.
    *
@@ -4959,5 +5185,5 @@ export declare class WorkflowDispatch extends WorkflowDispatch_base {
   /** {@link WorkflowDispatch.makeTest} behind a `Layer`. */
   static readonly layerTest: (overrides?: Partial<WorkflowDispatchShape>) => Layer.Layer<WorkflowDispatch>;
 }
-export { type ActionsOidcVerifyOptions, type AppCredentials, type AppliedSettings, type ArtifactMetadataShape, type AttestationShape, type AuthenticatedAppShape, type BareLineReference, type BotUserRequest, type BranchOutcome, CLOSING_KEYWORDS, type CachedToken, type CachedTokenRequest, type CheckRunShape, type ClosingKeyword, type CodeScanningSetup, type CodeScanningShape, type CompleteCheckRunOptions, type ConcludeCheckRun, type CreateCheckRunOptions, type DeliveriesOptions, 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 ListCheckRunsOptions, 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 };
+export { type ActionsOidcVerifyOptions, type AppCredentials, type AppliedSettings, type ApplySettingsOptions, type ArtifactMetadataShape, type AttestationShape, type AuthenticatedAppShape, type BareLineReference, type BotUserRequest, type BranchOutcome, CLOSING_KEYWORDS, type CachedToken, type CachedTokenRequest, type CheckRunShape, type ClosingKeyword, type CodeScanningSetup, type CodeScanningShape, type CompleteCheckRunOptions, type ConcludeCheckRun, type CreateCheckRunOptions, type DeliveriesOptions, 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 ListCheckRunsOptions, type OwnerType, type PollOptions, type PullRequestCommentShape, type PullRequestShape, type RecordedCall, type RepositoryPatch, type RepositoryPatchDraft, type RepositoryPatchExtra, type RepositoryPatchOptions, type RepositoryPatchReservedKey, 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

package/internal/confinement.js

@@ -0,0 +1,62 @@
+import { GitHubError } from "../GitHubError.js";
+import { reservedRawParam } from "./requestOptions.js";
+import { originOf } from "./uploads.js";
+
+// src/internal/confinement.ts
+/**
+* Why one of the caller's parameters may not be sent, or `undefined`.
+*
+* @remarks
+* Checked against the CALLER's parameters, before anything the transport adds
+* (`per_page`, a signal, the upload base): `baseUrl` and `url` move the host,
+* `request` swaps the fetch, `method` rewrites the verb.
+*
+* @internal
+*/
+const reservedParamReason = (params) => {
+	for (const key of Object.keys(params)) {
+		const reason = reservedRawParam(key);
+		if (reason !== void 0) return `the parameter "${key}" ${reason}`;
+	}
+};
+/**
+* Why `route` with `params` may not be sent to the origin `allowed`, or
+* `undefined` when it may.
+*
+* @remarks
+* The URL checked is the one `expand` builds, which is the one octokit itself
+* would send, so no spelling of the route reaches a host this check did not
+* see.
+*
+* @internal
+*/
+const routeReason = (expand, route, params, allowed) => {
+	let url;
+	try {
+		url = expand(route, params).url;
+	} catch {
+		return "the route does not expand to a URL";
+	}
+	if (allowed === void 0) return "the configured base URL is not an absolute URL";
+	const origin = originOf(url);
+	return origin === allowed ? void 0 : `the route resolves to ${origin ?? "a URL that does not parse"}, not the configured host ${allowed}; refusing to send the token there`;
+};
+/**
+* Why a raw-surface call may not be sent to `allowed`, or `undefined`: a
+* reserved parameter first, then the route's resolved origin.
+*
+* @internal
+*/
+const rawRequestRefusal = (expand, route, params, allowed) => reservedParamReason(params) ?? routeReason(expand, route, params, allowed);
+/**
+* The error a refused call fails with: `kind: "rejected"`, no status.
+*
+* @internal
+*/
+const refusedRequest = (operation, reason) => new GitHubError({
+	kind: "rejected",
+	operation,
+	reason
+});
+
+export { rawRequestRefusal, refusedRequest, reservedParamReason, routeReason };