@framers/agentos-ext-github 0.2.1 → 0.3.0

package/README.md

@@ -2,15 +2,15 @@
 
 This pack gives an agent tools for repository search, issues, pull requests, files, branches, commits, releases, workflow dispatch, gists, and repository indexing. It uses the GitHub API through `@octokit/rest`.
 
-Its second entry, `@framers/agentos-ext-github/documents`, is for a server that reads people's repositories through a GitHub App: the app's JWT and installation tokens, the user's web flow, the installations and repositories a person can reach, webhook signatures, a daily reconcile, and `GitHubDocumentsConnector`, which reads a repository's documentation as account sources. See [GitHub App installation mode](#github-app-installation-mode).
+Its second entry, `@framers/agentos-ext-github/documents`, is for a server that reads people's repositories through a GitHub App: the app's JWT and installation tokens, the user's web flow, the installations and repositories a person can reach, webhook deliveries checked and read as typed events, a daily reconcile, and `GitHubDocumentsConnector`, which reads a repository's documentation as account sources. See [GitHub App installation mode](#github-app-installation-mode).
 
 ## Installation
 
 ```bash
-npm install @framers/agentos-ext-github
+npm install @framers/agentos-ext-github @framers/agentos @framers/agentos-ext-account-sources
 ```
 
-Peer dependency: `@framers/agentos` with range `>=0.13.40`, the first release whose auth module has `RedirectOAuthFlow`.
+Peer dependencies: `@framers/agentos` with range `>=0.13.144`, whose auth module's `RedirectOAuthFlow` refuses a token answer that is JSON but not an object, and `@framers/agentos-ext-account-sources` with range `>=0.7.0`, whose connector types, capped reads and retry timing the `./documents` entry uses. A host keeps one copy of each; only the `./documents` entry loads `@framers/agentos-ext-account-sources`.
 
 ## Usage
 
@@ -343,7 +343,7 @@ List and search tools fetch a page of results and cap `per_page` as described in
 
 Top-level pull request comments use the issues API. `github_pr_comment_list` returns inline review comments; `github_comment_list` returns top-level comments.
 
-`GitHubRepoIndexer` indexes the repositories its constructor is given, `new GitHubRepoIndexer(service, { repositories: [{ owner, repo }] })`, and the six repositories of `ECOSYSTEM_REPOS` when it is given none.
+`GitHubRepoIndexer` indexes the repositories its constructor is given, `new GitHubRepoIndexer(service, { repositories: [{ owner, repo }] })`, and the six repositories of `ECOSYSTEM_REPOS` when it is given none. The package's entry exports both, with the types `IndexedRepository` and `GitHubRepoIndexerOptions`.
 
 ## GitHub App installation mode
 
@@ -391,29 +391,63 @@ for (const repository of repositories) {
 }
 ```
 
-A push arrives at the app's webhook. Check its signature on the raw body before parsing it, then compare the tree at the push's `after` commit with the blobs read before:
+A delivery arrives at the app's webhook. `readWebhookRequest` reads its body under a cap, checks its signature on the raw bytes, reads its id, and only then parses it into a typed event. Answer GitHub at once (it expects a 2xx within 10 seconds), apply each delivery id once (a redelivery carries the id of the delivery it repeats), and do the reading in a job:
 
 ```ts
-import { verifyWebhookSignature } from '@framers/agentos-ext-github/documents';
+import { readWebhookRequest, WebhookDeliveryRefused } from '@framers/agentos-ext-github/documents';
 
-if (!verifyWebhookSignature(rawBody, request.headers.get('x-hub-signature-256'), webhookSecret)) return new Response(null, { status: 401 });
-const push = JSON.parse(new TextDecoder().decode(rawBody));
-const changes = await connector.changesSince(cursor, { ids: [String(push.repository.id)], after: push.after, ref: push.ref });
+const REFUSALS = { too_large: 413, signature: 401, delivery: 400, body: 400 } as const;
+
+export async function POST(request: Request): Promise<Response> {
+  let delivery;
+  try {
+    delivery = await readWebhookRequest(request, webhookSecret, { maxBytes: 5 * 1024 * 1024 });
+  } catch (error) {
+    if (error instanceof WebhookDeliveryRefused) return new Response(null, { status: REFUSALS[error.reason] });
+    throw error;
+  }
+  if (!(await firstSight(delivery.id))) return new Response(null, { status: 200 });
+  const event = delivery.event;
+  if (event.kind === 'push' && event.toDefaultBranch) await owe(event.installationId, event.repository.id, event.after);
+  if (event.kind === 'installation' && event.action === 'deleted') await unlink(event.installationId);
+  if (event.kind === 'installation_repositories') await drop(event.installationId, event.removed.map((repository) => repository.id));
+  return new Response(null, { status: 200 });
+}
+
+// The job compares the tree at the push's after commit with the blobs read before.
+const changes = await connector.changesSince(cursor, { ids: [String(repositoryId)], after });
 // Read changes.changed again, delete changes.gone, keep changes.cursor for the next push.
 ```
 
+| Event | Answered as |
+| --- | --- |
+| `push` | `{ kind: 'push', installationId, repository: { id, fullName, defaultBranch }, ref, before, after, created, deleted, forced, toDefaultBranch }`; `toDefaultBranch` is true when `ref` is `refs/heads/<default branch>` and the push did not delete it |
+| `installation` | `{ kind: 'installation', action, installationId, account, repositories }` for `created`, `deleted`, `suspend`, `unsuspend` and `new_permissions_accepted`; `repositories` lists what a new installation on selected repositories can access |
+| `installation_repositories` | `{ kind: 'installation_repositories', action: 'added' \| 'removed', installationId, selection: 'all' \| 'selected', added, removed }`; when an installation goes from all repositories to a selection, GitHub lists none of the repositories that left, so read the installation's repositories again |
+| `installation_target` | `{ kind: 'installation_target', action: 'renamed', installationId, account }`, the account under its new login or slug |
+| `ping` | `{ kind: 'ping' }` |
+| anything else | `{ kind: 'other' }`, as is a payload without the fields above; `delivery.name` holds the event's name |
+
+A delivery is refused with `WebhookDeliveryRefused`, checked in this order: `too_large` past `maxBytes` (25 MiB by default; the request's stream is cancelled at the cap, and a `Content-Length` past it is refused unread), `signature` when `X-Hub-Signature-256` does not hold under the secret, `delivery` without a usable `X-GitHub-Delivery`, `body` for a signed body that is not a JSON object. An empty secret throws a `TypeError`. `readWebhookDelivery({ headers, body }, secret, options)` does the same for a body already read. No error quotes a payload.
+
+Every call runs under a deadline, 30 seconds by default (`GITHUB_TIMEOUT_MS`), its answer's body included, joined with the caller's signal where a method takes one. The functions that take `{ fetchImpl, apiBase }` take `timeoutMs` beside them, and `GitHubAppUserFlow` takes `{ timeoutMs }` as its fourth argument; the credential's token requests and the connector's reads keep the default. A call that gets no answer throws `GitHubNoAnswer` with its `reason`: `timeout`, `cancelled` or `network`. A JSON answer is read under 16 MiB (`GITHUB_MAX_ANSWER_BYTES`). An answer outside 2xx throws `GitHubApiError` with `status`, `rateLimited` and `retryAt`, following GitHub's [rules for a refused call](https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#exceeding-the-rate-limit): a 429, or a 403 with `retry-after`, `x-ratelimit-remaining: 0` or a body naming a rate limit, is a rate limit, and `retryAt` (epoch milliseconds) is `retry-after` first, then `x-ratelimit-reset` when the remaining count is 0, else a minute on. Do not call again before `retryAt`: GitHub may ban an integration that keeps calling while rate limited. A 5xx's `retry-after` sets `retryAt` too.
+
 | Export | What it does |
 | --- | --- |
 | `appJwt(identity, nowSeconds?)` | The app's JWT: RS256, `iat` 60 seconds back, `exp` nine minutes ahead, `iss` the client id |
-| `GitHubAppCredential` | Mints installation tokens narrowed to the repositories asked for (`repository_ids`) and holds each until five minutes before its hour ends |
-| `GitHubAppUserFlow` | The user's web flow on the auth module's `RedirectOAuthFlow`: GitHub's authorize address with `state` and PKCE and no `scope`, and the code exchange; it has no store, so the user token is used once |
+| `GitHubAppCredential` | Mints installation tokens narrowed to the repositories asked for (`repository_ids`) and holds each until five minutes before its hour ends; an empty list throws a `TypeError`, since GitHub answers it with a token for every repository of the installation |
+| `GitHubAppUserFlow` | The user's web flow on the auth module's `RedirectOAuthFlow`: GitHub's authorize address with `state` and PKCE and no `scope`, and the code exchange under a deadline (`new GitHubAppUserFlow(client, fetchImpl, endpoints, { timeoutMs })`), which never follows a redirect from the token address: the redirect is refused with `OAuthGrantRefused` and its status, so the code and the client secret reach that address alone; it has no store, so the user token is used once |
 | `userOfToken`, `installationsOfUser`, `repositoriesOfUser` | The person a user token belongs to, the app's installations they can access, and the repositories of an installation they can read, across every page |
 | `listInstallations`, `uninstallInstallation` | The app's installations, and its uninstall, which takes 202 (GitHub removes it in the background), 204 and 404 as done |
-| `verifyWebhookSignature(body, header, secret)` | Checks `X-Hub-Signature-256` against the HMAC SHA-256 of the raw body in constant time |
-| `reconcileInstallations(credential, links, { since })` | Answers the linked installations GitHub no longer lists, the repositories whose default branch moved past the head last read, the repositories it could not read, and asks again for each event since `since` that no delivery attempt delivered |
+| `verifyWebhookSignature(body, header, secret)` | Checks `X-Hub-Signature-256` against the HMAC SHA-256 of the raw body in constant time; an empty or missing secret throws a `TypeError`, since anyone can sign a delivery under an empty key |
+| `readWebhookRequest(request, secret, { maxBytes })`, `readWebhookDelivery({ headers, body }, secret, { maxBytes })` | Read a delivery under a cap, check its signature and id, and answer it as a typed event, or throw `WebhookDeliveryRefused` with its reason |
+| `reconcileInstallations(credential, links, { since })` | Answers the linked installations GitHub no longer lists, the repositories whose default branch moved past the head last read, the repositories it could not read, and asks again for each event since `since` that no delivery attempt delivered, reporting GitHub's refusals of that step in `deliveries` |
 | `GitHubDocumentsConnector` | An `AccountSourceConnector` of `@framers/agentos-ext-account-sources` over one installation's linked repositories |
 | `readTree`, `pathFilter`, `TreeTooLarge` | A tree at a commit within a request budget, and the filter that keeps documentation |
-| `GitHubApiError` | An answer outside 2xx; carries the status and nothing of the body |
+| `GitHubApiError` | An answer outside 2xx; carries the status, `rateLimited` and `retryAt`, and nothing of the body |
+| `GitHubNoAnswer` | A call that got no answer, by its `reason`: `timeout`, `cancelled` or `network` |
+
+The reconcile leaves failed a delivery whose newest attempt the receiving route answered with a 4xx other than 408 and 429, such as a 413 for a body past the route's size cap: that refusal answers the same on every attempt. A 408, a 429, a 5xx or any other failed attempt is asked for again. When GitHub answers the deliveries listing outside 2xx, `deliveries.listingStatus` holds its status and no delivery is asked for again, since a delivery's other attempts may lie on the pages not read; a redelivery GitHub refuses is listed in `deliveries.refused` with its status, and the others are still asked for. Either way the outcome carries `gone`, `moved` and `unreadable`.
 
 The connector's filter, `new GitHubDocumentsConnector(credential, installationId, repositories, filter)`:
 
@@ -425,7 +459,7 @@ The connector's filter, `new GitHubDocumentsConnector(credential, installationId
 | `maxFileBytes` | `10485760` (10 MiB): larger files are left out of a listing, and a read past it is answered gone |
 | `maxTreeRequests` | `50` tree requests to list one commit |
 
-An item's id is `<repositoryId>:<path>` and its version `<blob>@<commit>`. A tree is asked for recursively; when GitHub answers it truncated (past 100,000 entries or 7 MB), its top level is read and each subtree is asked for the same way, never walking a skipped folder, and `TreeTooLarge` is thrown rather than pass `maxTreeRequests`. Files are read through the contents endpoint's raw media type as a stream cut at `maxFileBytes`: PDF, Word and HTML as bytes with their media type, the rest as UTF-8 text, each with a `github` source reference whose `url` is the file at the commit. `changesSince` takes the cursor it answered last (each documentation path's blob), never reads a push's commit list, so a force push is read like any other, and answers a push to another branch than the default with no change. `listing(repositoryId, commit)` lets a caller keep a commit's listing and pass it to `changesSince` as `listing`, which then reads no tree.
+An item's id is `<repositoryId>:<path>` and its version `<blob>@<commit>`. A tree is asked for recursively; when GitHub answers it truncated (past 100,000 entries or 7 MB), its top level is read and each subtree is asked for the same way, never walking a skipped folder, and `TreeTooLarge` is thrown rather than pass `maxTreeRequests`. Files are read through the contents endpoint's raw media type as a stream cut at `maxFileBytes`: PDF, Word and HTML as bytes with their media type, the rest as UTF-8 text, each with a `github` source reference whose `url` is the file at the commit. `changesSince` takes the cursor it answered last (each documentation path's blob), never reads a push's commit list, so a force push is read like any other, and answers a push to another branch than the default with no change. `listing(repositoryId, commit)` lets a caller keep a commit's listing and pass it to `changesSince` as `listing`, which then reads no tree. A cursor `changesSince` did not answer throws a `TypeError` that quotes none of it, and a file read GitHub refuses for a rate limit throws `GitHubApiError` with its `retryAt`, never an answer that the file is gone.
 
 ## License
 

package/dist/__tests__/app.test.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview The GitHub App half of the `./documents` entry, driven over a fetch stand-in that records each
  * request: the app's JWT, installation tokens, the user's web flow, a user's installations and repositories, the
- * webhook signature, the daily reconcile and the uninstall.
+ * webhook signature, the daily reconcile and the uninstall, and the REST calls under them.
  */
 export {};
 //# sourceMappingURL=app.test.d.ts.map

package/dist/__tests__/app.test.js

@@ -1,11 +1,12 @@
 /**
  * @fileoverview The GitHub App half of the `./documents` entry, driven over a fetch stand-in that records each
  * request: the app's JWT, installation tokens, the user's web flow, a user's installations and repositories, the
- * webhook signature, the daily reconcile and the uninstall.
+ * webhook signature, the daily reconcile and the uninstall, and the REST calls under them.
  */
 import { createHash, createHmac, createVerify, generateKeyPairSync } from 'node:crypto';
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { appJwt, GitHubApiError, GitHubAppCredential, GitHubAppUserFlow, installationsOfUser, reconcileInstallations, repositoriesOfUser, uninstallInstallation, userOfToken, verifyWebhookSignature, } from '../documents/index.js';
+import { githubFetch } from '../app/http.js';
+import { appJwt, GITHUB_OAUTH_ENDPOINTS, GitHubApiError, GitHubAppCredential, GitHubAppUserFlow, GitHubNoAnswer, installationsOfUser, reconcileInstallations, repositoriesOfUser, uninstallInstallation, userOfToken, verifyWebhookSignature, } from '../documents/index.js';
 /** A fetch that answers from `route` and records every request. */
 function standIn(route) {
     const seen = [];
@@ -26,6 +27,33 @@ function standIn(route) {
 function json(body, status = 200, headers = {}) {
     return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...headers } });
 }
+/** A fetch that never answers, rejecting with its signal's reason when the signal aborts, as fetch does. */
+const neverAnswers = async (_input, init) => {
+    const signal = init?.signal ?? undefined;
+    return new Promise((_resolve, reject) => {
+        if (signal === undefined)
+            return;
+        if (signal.aborted)
+            reject(signal.reason);
+        else
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+    });
+};
+/**
+ * A fetch that answers 200 with the start of a body and then stalls, erroring the body when its signal aborts, as
+ * fetch does to a body still streaming.
+ */
+const stallsInBody = async (_input, init) => {
+    const signal = init?.signal ?? undefined;
+    const body = new ReadableStream({
+        start(controller) {
+            controller.enqueue(new TextEncoder().encode('{"login":'));
+            if (signal !== undefined)
+                signal.addEventListener('abort', () => controller.error(signal.reason), { once: true });
+        },
+    });
+    return new Response(body, { status: 200, headers: { 'content-type': 'application/json' } });
+};
 const BASE = 'https://stand-in.test';
 const CLIENT_ID = 'Iv23liTESTCLIENT';
 const keys = generateKeyPairSync('rsa', {
@@ -42,6 +70,48 @@ function appClaims(authorization) {
     const verified = createVerify('RSA-SHA256').update(`${head}.${body}`).verify(keys.publicKey, Buffer.from(signature, 'base64url'));
     return verified ? JSON.parse(Buffer.from(body, 'base64url').toString('utf8')) : null;
 }
+const HEAD_BEFORE = 'a'.repeat(40);
+const HEAD_NOW = 'b'.repeat(40);
+/** Two links: installation 21, whose repository 7 moved and whose repository 9 left it, and installation 22, gone. */
+const RECONCILE_LINKS = [
+    {
+        installationId: 21,
+        repositories: [
+            { id: 7, fullName: 'first-team/handbook', defaultBranch: 'main', headCommit: HEAD_BEFORE },
+            { id: 9, fullName: 'first-team/removed', defaultBranch: 'main', headCommit: HEAD_BEFORE },
+        ],
+    },
+    { installationId: 22, repositories: [{ id: 30, fullName: 'gone-team/docs', defaultBranch: 'main', headCommit: HEAD_BEFORE }] },
+];
+/** What a reconcile of {@link RECONCILE_LINKS} finds before its deliveries step. */
+const RECONCILED = {
+    gone: [22],
+    moved: [{ installationId: 21, repositoryId: 7, head: HEAD_NOW }],
+    unreadable: [{ installationId: 21, repositoryId: 9, status: 422 }],
+};
+/**
+ * A stand-in for a reconcile of {@link RECONCILE_LINKS}: GitHub lists installation 21 alone, mints a token for
+ * repository 7 and refuses one for repository 9 with 422, answers repository 7's head as {@link HEAD_NOW}, and leaves
+ * the app's hook routes to `hooks`.
+ */
+function reconcileStandIn(hooks) {
+    return standIn((request) => {
+        const url = new URL(request.url);
+        if (url.pathname === '/app/installations')
+            return json([{ id: 21, account: { login: 'first-team', id: 901 } }]);
+        if (url.pathname === '/app/installations/21/access_tokens') {
+            const ids = JSON.parse(request.body ?? '{}').repository_ids;
+            if (ids.includes(9))
+                return json({ message: 'There is at least one repository that does not exist' }, 422);
+            return json({ token: `ghs_repo${ids.join('_')}`, expires_at: new Date(Date.now() + 3_600_000).toISOString() }, 201);
+        }
+        if (url.pathname === '/repos/first-team/handbook/branches/main')
+            return json({ name: 'main', commit: { sha: HEAD_NOW } });
+        if (url.pathname.startsWith('/app/hook/'))
+            return hooks(request, url);
+        return json({ message: 'Not Found' }, 404);
+    });
+}
 afterEach(() => {
     vi.useRealTimers();
 });
@@ -78,6 +148,12 @@ describe('the GitHub App', () => {
         expect(await credential.installationToken(42, [3, 7])).toBe('ghs_test2');
         expect(seen).toHaveLength(2);
     });
+    it('refuses an empty repository list before any request, since GitHub would answer a token for every repository', async () => {
+        const { fetchImpl, seen } = standIn(() => json({ token: 'ghs_every', expires_at: new Date(Date.now() + 3_600_000).toISOString() }, 201));
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        await expect(credential.installationToken(42, [])).rejects.toThrow(TypeError);
+        expect(seen).toHaveLength(0);
+    });
     it("begins the user's web flow with state and PKCE and no scope, and completes it into a token it never stores", async () => {
         const { fetchImpl, seen } = standIn(() => json({ access_token: 'ghu_testuser', expires_in: 28_800, refresh_token: 'ghr_testuser', refresh_token_expires_in: 15_897_600, scope: '', token_type: 'bearer' }));
         const flow = new GitHubAppUserFlow({ clientId: CLIENT_ID, clientSecret: 'test-client-secret' }, fetchImpl);
@@ -105,6 +181,52 @@ describe('the GitHub App', () => {
         expect(form.get('redirect_uri')).toBe(redirectUri);
         await expect(flow.keep('person', tokens)).rejects.toThrow('this flow has no store');
     });
+    it("ends the user's code exchange at its deadline, and names a token address that cannot be reached", async () => {
+        const redirectUri = 'https://app.example/sources/github/callback';
+        const late = new GitHubAppUserFlow({ clientId: CLIENT_ID, clientSecret: 'test-client-secret' }, neverAnswers, GITHUB_OAUTH_ENDPOINTS, { timeoutMs: 50 });
+        const begun = late.begin({ redirectUri });
+        const timedOut = await late
+            .complete({ code: 'test-code', state: begun.state, expectedState: begun.state, codeVerifier: begun.codeVerifier, redirectUri })
+            .catch((error) => error);
+        expect(timedOut).toBeInstanceOf(GitHubNoAnswer);
+        expect(timedOut.reason).toBe('timeout');
+        const unreachable = async () => {
+            throw new TypeError('fetch failed');
+        };
+        const offline = new GitHubAppUserFlow({ clientId: CLIENT_ID, clientSecret: 'test-client-secret' }, unreachable);
+        const second = offline.begin({ redirectUri });
+        const failed = await offline
+            .complete({ code: 'test-code', state: second.state, expectedState: second.state, codeVerifier: second.codeVerifier, redirectUri })
+            .catch((error) => error);
+        expect(failed).toBeInstanceOf(GitHubNoAnswer);
+        expect(failed.reason).toBe('network');
+    });
+    it('refuses a redirect from the token address, so the code and the client secret are never sent anywhere else', async () => {
+        const elsewhere = 'https://elsewhere.test/collect';
+        const seen = [];
+        // Redirects as fetch does: a 307 is followed with the same method and body unless the call asks for `manual`,
+        // which answers the redirect itself, or `error`, which fails the call.
+        const redirecting = async function follow(input, init) {
+            const url = typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+            seen.push({ url, body: typeof init?.body === 'string' ? init.body : null });
+            if (url !== GITHUB_OAUTH_ENDPOINTS.token)
+                return json({ access_token: 'ghu_elsewhere', token_type: 'bearer' });
+            const moved = new Response(null, { status: 307, headers: { location: elsewhere } });
+            if (init?.redirect === 'manual')
+                return moved;
+            if (init?.redirect === 'error')
+                throw new TypeError('fetch failed');
+            return follow(elsewhere, init);
+        };
+        const flow = new GitHubAppUserFlow({ clientId: CLIENT_ID, clientSecret: 'test-client-secret' }, redirecting);
+        const redirectUri = 'https://app.example/sources/github/callback';
+        const begun = flow.begin({ redirectUri });
+        const refused = await flow
+            .complete({ code: 'test-code', state: begun.state, expectedState: begun.state, codeVerifier: begun.codeVerifier, redirectUri })
+            .catch((error) => error);
+        expect(refused).toMatchObject({ name: 'OAuthGrantRefused', reason: 'exchange', status: 307 });
+        expect(seen.map((request) => request.url)).toEqual([GITHUB_OAUTH_ENDPOINTS.token]);
+    });
     it("reads a user token's person, its installations across pages and an installation's repositories at the API base given", async () => {
         const { fetchImpl, seen } = standIn((request) => {
             const url = new URL(request.url);
@@ -153,6 +275,13 @@ describe('the GitHub App', () => {
         expect(verifyWebhookSignature(body, `${right}00`, secret)).toBe(false);
         expect(verifyWebhookSignature(body, `sha1=${createHmac('sha1', secret).update(body).digest('hex')}`, secret)).toBe(false);
     });
+    it('refuses an empty or missing secret, under which anyone can sign a delivery', () => {
+        const body = new TextEncoder().encode('Hello, World!');
+        const signedWithoutKey = `sha256=${createHmac('sha256', '').update(body).digest('hex')}`;
+        expect(() => verifyWebhookSignature(body, signedWithoutKey, '')).toThrow(TypeError);
+        expect(() => verifyWebhookSignature(body, null, '')).toThrow(TypeError);
+        expect(() => verifyWebhookSignature(body, signedWithoutKey, undefined)).toThrow(TypeError);
+    });
     it("reconciles links: an installation gone, a repository's head moved, a day's failed deliveries asked for again", async () => {
         const now = Date.now();
         const hours = (count) => new Date(now - count * 3_600_000).toISOString();
@@ -212,6 +341,7 @@ describe('the GitHub App', () => {
             moved: [{ installationId: 21, repositoryId: 7, head: headNow }],
             redelivered: [9001],
             unreadable: [{ installationId: 21, repositoryId: 9, status: 422 }],
+            deliveries: { listingStatus: null, refused: [] },
         });
         const branchRead = seen.find((request) => request.url === `${BASE}/repos/first-team/handbook/branches/main`);
         expect(branchRead?.headers.get('authorization')).toBe('Bearer ghs_repo7');
@@ -221,6 +351,69 @@ describe('the GitHub App', () => {
         expect(appCalls.length).toBeGreaterThan(0);
         expect(appCalls.every((request) => appClaims(request.headers.get('authorization')) !== null)).toBe(true);
     });
+    it('keeps the lists it computed when GitHub answers a page of the deliveries 500, asking for no delivery again', async () => {
+        const now = Date.now();
+        const { fetchImpl, seen } = reconcileStandIn((_request, url) => {
+            if (url.pathname === '/app/hook/deliveries' && url.searchParams.get('cursor') === null) {
+                return json([{ id: 9001, guid: 'guid-1', delivered_at: new Date(now - 3_600_000).toISOString(), status_code: 500 }], 200, {
+                    link: `<${BASE}/app/hook/deliveries?per_page=100&cursor=page2>; rel="next"`,
+                });
+            }
+            if (url.pathname === '/app/hook/deliveries')
+                return json({ message: 'Server Error' }, 500);
+            return new Response(null, { status: 202 });
+        });
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const outcome = await reconcileInstallations(credential, RECONCILE_LINKS, { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE });
+        expect(outcome).toEqual({ ...RECONCILED, redelivered: [], deliveries: { listingStatus: 500, refused: [] } });
+        expect(seen.some((request) => request.url.endsWith('/attempts'))).toBe(false);
+    });
+    it('goes on past a redelivery GitHub refuses with 403, reporting it beside the lists it computed', async () => {
+        const now = Date.now();
+        const { fetchImpl, seen } = reconcileStandIn((_request, url) => {
+            if (url.pathname === '/app/hook/deliveries') {
+                return json([
+                    { id: 9001, guid: 'guid-1', delivered_at: new Date(now - 600_000).toISOString(), status_code: 500 },
+                    { id: 9002, guid: 'guid-2', delivered_at: new Date(now - 1_200_000).toISOString(), status_code: 502 },
+                ]);
+            }
+            if (url.pathname === '/app/hook/deliveries/9001/attempts')
+                return json({ message: 'Forbidden' }, 403);
+            return new Response(null, { status: 202 });
+        });
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const outcome = await reconcileInstallations(credential, RECONCILE_LINKS, { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE });
+        expect(outcome).toEqual({ ...RECONCILED, redelivered: [9002], deliveries: { listingStatus: null, refused: [{ id: 9001, status: 403 }] } });
+        expect(seen.filter((request) => request.url.endsWith('/attempts')).map((request) => new URL(request.url).pathname)).toEqual([
+            '/app/hook/deliveries/9001/attempts',
+            '/app/hook/deliveries/9002/attempts',
+        ]);
+    });
+    it('asks again for a delivery its route answered 408, 429 or 5xx, never for one it refused with another 4xx', async () => {
+        const now = Date.now();
+        // Newest first, as GitHub lists them: guid-e failed with 404 and then 503, guid-f with 500 and then 422.
+        const attempts = [
+            [9101, 'guid-a', 10, 413],
+            [9106, 'guid-e', 20, 503],
+            [9107, 'guid-f', 30, 422],
+            [9102, 'guid-b', 40, 400],
+            [9109, 'guid-g', 50, 500],
+            [9103, 'guid-c', 60, 408],
+            [9104, 'guid-d', 70, 429],
+            [9105, 'guid-e', 80, 404],
+            [9108, 'guid-f', 90, 500],
+        ];
+        const { fetchImpl, seen } = reconcileStandIn((_request, url) => {
+            if (url.pathname === '/app/hook/deliveries') {
+                return json(attempts.map(([id, guid, minutesAgo, statusCode]) => ({ id, guid, delivered_at: new Date(now - minutesAgo * 60_000).toISOString(), status_code: statusCode })));
+            }
+            return new Response(null, { status: 202 });
+        });
+        const credential = new GitHubAppCredential({ clientId: CLIENT_ID, privateKey: keys.privateKey }, fetchImpl, BASE);
+        const outcome = await reconcileInstallations(credential, [], { since: new Date(now - 86_400_000), fetchImpl, apiBase: BASE });
+        expect(outcome.redelivered).toEqual([9106, 9109, 9103, 9104]);
+        expect(seen.filter((request) => request.method === 'POST').map((request) => new URL(request.url).pathname)).toEqual([9106, 9109, 9103, 9104].map((id) => `/app/hook/deliveries/${id}/attempts`));
+    });
     it('uninstalls with the JWT, taking 202, 204 and 404 as done and throwing other answers without their body', async () => {
         const { fetchImpl, seen } = standIn((request) => {
             const id = new URL(request.url).pathname.split('/').pop();
@@ -245,4 +438,115 @@ describe('the GitHub App', () => {
         expect(seen.every((request) => appClaims(request.headers.get('authorization')) !== null)).toBe(true);
     });
 });
+describe('the REST calls', () => {
+    it('refuses a next page on another origin, so the bearer never goes there', async () => {
+        const { fetchImpl, seen } = standIn(() => json({ total_count: 2, installations: [{ id: 11, account: { login: 'first-team', id: 901 } }] }, 200, {
+            link: '<https://elsewhere.example.com/user/installations?per_page=100&page=2>; rel="next"',
+        }));
+        await expect(installationsOfUser('ghu_testuser', { fetchImpl, apiBase: BASE })).rejects.toThrow('GitHub named a next page on another origin');
+        expect(seen.map((request) => request.url)).toEqual([`${BASE}/user/installations?per_page=100`]);
+    });
+    it('answers a body that is not JSON with an error that does not quote it', async () => {
+        const { fetchImpl } = standIn(() => new Response('<html>upstream detail</html>', { status: 200, headers: { 'content-type': 'text/html' } }));
+        const failure = await userOfToken('ghu_testuser', { fetchImpl, apiBase: BASE }).catch((error) => error);
+        expect(failure).toBeInstanceOf(Error);
+        expect(failure.message).toBe('GitHub answered a body that is not JSON');
+    });
+    it('answers undefined for a 202 or a 204 without a body', async () => {
+        const { fetchImpl, seen } = standIn((request) => new Response(null, { status: request.method === 'POST' ? 202 : 204 }));
+        await expect(githubFetch(fetchImpl, `${BASE}/app/hook/deliveries/9001/attempts`, { token: 'ghs_test', method: 'POST' })).resolves.toBeUndefined();
+        await expect(githubFetch(fetchImpl, `${BASE}/app/installations/31`, { token: 'ghs_test', method: 'DELETE' })).resolves.toBeUndefined();
+        expect(seen.map((request) => `${request.method} ${new URL(request.url).pathname}`)).toEqual(['POST /app/hook/deliveries/9001/attempts', 'DELETE /app/installations/31']);
+    });
+    it("sends the pack's User-Agent beside the bearer, the media type and the pinned API version", async () => {
+        const { fetchImpl, seen } = standIn(() => json({ login: 'test-person', id: 501 }));
+        await userOfToken('ghu_testuser', { fetchImpl, apiBase: BASE });
+        expect(seen).toHaveLength(1);
+        expect(seen[0].headers.get('user-agent')).toBe('agentos-ext-github');
+        expect(seen[0].headers.get('authorization')).toBe('Bearer ghu_testuser');
+        expect(seen[0].headers.get('accept')).toBe('application/vnd.github+json');
+        expect(seen[0].headers.get('x-github-api-version')).toBe('2026-03-10');
+    });
+    it('says when a rate-limited call may be made again: retry-after first, then the window reset, else a minute', async () => {
+        vi.useFakeTimers({ toFake: ['Date'] });
+        vi.setSystemTime(new Date('2026-10-15T12:00:00Z'));
+        const now = Date.now();
+        const reset = Math.floor(now / 1000) + 1800;
+        // The answers of https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#exceeding-the-rate-limit
+        const { fetchImpl } = standIn((request) => {
+            switch (request.headers.get('authorization')) {
+                case 'Bearer primary':
+                    return json({ message: 'API rate limit exceeded for installation ID 5.' }, 403, { 'x-ratelimit-remaining': '0', 'x-ratelimit-reset': String(reset) });
+                case 'Bearer primary-429':
+                    return json({ message: 'API rate limit exceeded for installation ID 5.' }, 429, { 'x-ratelimit-remaining': '0', 'x-ratelimit-reset': String(reset) });
+                case 'Bearer secondary-after':
+                    return json({ message: 'You have exceeded a secondary rate limit.' }, 429, { 'retry-after': '30', 'x-ratelimit-remaining': '0', 'x-ratelimit-reset': String(reset) });
+                case 'Bearer secondary-long':
+                    return json({ message: 'You have exceeded a secondary rate limit.' }, 403, { 'retry-after': '7200' });
+                case 'Bearer secondary-date':
+                    return json({ message: 'You have exceeded a secondary rate limit.' }, 429, { 'retry-after': new Date(now + 90_000).toUTCString() });
+                case 'Bearer secondary-bare':
+                    return json({ message: 'You have exceeded a secondary rate limit. Please wait a few minutes before you try again.' }, 403);
+                case 'Bearer forbidden':
+                    return json({ message: 'Resource not accessible by integration', documentation_url: 'https://docs.github.com/rest/users/users' }, 403);
+                case 'Bearer unavailable':
+                    return json({ message: 'Unicorn detail of an outage' }, 503, { 'retry-after': '120' });
+                default:
+                    return json({ message: 'Not Found' }, 404);
+            }
+        });
+        const refusalOf = async (token) => {
+            const failure = await userOfToken(token, { fetchImpl, apiBase: BASE }).catch((error) => error);
+            expect(failure).toBeInstanceOf(GitHubApiError);
+            return failure;
+        };
+        const timing = (failure) => [failure.status, failure.rateLimited, failure.retryAt];
+        expect(timing(await refusalOf('primary'))).toEqual([403, true, reset * 1000]);
+        expect(timing(await refusalOf('primary-429'))).toEqual([429, true, reset * 1000]);
+        expect(timing(await refusalOf('secondary-after'))).toEqual([429, true, now + 30_000]);
+        // A wait GitHub names is kept whole, however long, as delay-seconds or as an HTTP date.
+        expect(timing(await refusalOf('secondary-long'))).toEqual([403, true, now + 7_200_000]);
+        expect(timing(await refusalOf('secondary-date'))).toEqual([429, true, now + 90_000]);
+        expect(timing(await refusalOf('secondary-bare'))).toEqual([403, true, now + 60_000]);
+        expect(timing(await refusalOf('forbidden'))).toEqual([403, false, null]);
+        expect(timing(await refusalOf('unavailable'))).toEqual([503, false, now + 120_000]);
+        expect(timing(await refusalOf('missing'))).toEqual([404, false, null]);
+        const quoted = await refusalOf('secondary-bare');
+        expect(quoted.message).toBe('GitHub answered 403');
+        expect((await refusalOf('unavailable')).message).not.toContain('Unicorn');
+    });
+    it('ends a call at its deadline, its body included, and names a cancelled call and a failed connection', async () => {
+        const timedOut = await userOfToken('ghu_testuser', { fetchImpl: neverAnswers, apiBase: BASE, timeoutMs: 50 }).catch((error) => error);
+        expect(timedOut).toBeInstanceOf(GitHubNoAnswer);
+        expect(timedOut.reason).toBe('timeout');
+        expect(timedOut.message).toBe('GitHub gave no answer: timeout');
+        const stalled = await userOfToken('ghu_testuser', { fetchImpl: stallsInBody, apiBase: BASE, timeoutMs: 50 }).catch((error) => error);
+        expect(stalled).toBeInstanceOf(GitHubNoAnswer);
+        expect(stalled.reason).toBe('timeout');
+        const controller = new AbortController();
+        const pending = githubFetch(neverAnswers, `${BASE}/user`, { token: 'ghu_testuser', signal: controller.signal }).catch((error) => error);
+        controller.abort();
+        const cancelled = await pending;
+        expect(cancelled).toBeInstanceOf(GitHubNoAnswer);
+        expect(cancelled.reason).toBe('cancelled');
+        const refusing = async () => {
+            throw new TypeError('fetch failed');
+        };
+        const offline = await installationsOfUser('ghu_testuser', { fetchImpl: refusing, apiBase: BASE }).catch((error) => error);
+        expect(offline).toBeInstanceOf(GitHubNoAnswer);
+        expect(offline.reason).toBe('network');
+    });
+    it('refuses an answer whose body states more than the cap before reading it', async () => {
+        let pulled = false;
+        const oversized = async () => new Response(new ReadableStream({
+            pull() {
+                pulled = true;
+            },
+        }, { highWaterMark: 0 }), { status: 200, headers: { 'content-type': 'application/json', 'content-length': String(64 * 1024 * 1024) } });
+        const failure = await userOfToken('ghu_testuser', { fetchImpl: oversized, apiBase: BASE }).catch((error) => error);
+        expect(failure).toBeInstanceOf(Error);
+        expect(failure.message).toBe('GitHub answered a body past the size cap');
+        expect(pulled).toBe(false);
+    });
+});
 //# sourceMappingURL=app.test.js.map