@michelj/context-guard 0.4.4 → 0.6.2

package/scripts/workbench/protocol-device.mjs

@@ -0,0 +1,316 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { Readable, Transform } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { atomicWrite, encode, hash, readJSON, withFileLock } from '../shared/io.mjs';
+import { canonical, fail, validateMessage, ProtocolError } from '../shared/protocol.mjs';
+import { sendMessage, ProjectMessagePump } from './protocol-client.mjs';
+
+const readTypes = new Set(['sync.heartbeat', 'sync.read', 'workbench.read', 'object.read', 'blob.get']);
+const messageScope = message => message.session?.id || message.payload.sessionId || 'project';
+// A single project host owns this connection. Agents never receive its credential.
+export class DeviceConnection {
+  constructor({ directory, origin, transport = sendMessage, allowLoopback = false }) {
+    this.directory = directory; this.origin = origin; this.transport = transport; this.allowLoopback = allowLoopback;
+    this.file = path.join(directory, 'device-connection.json'); this.outbox = path.join(directory, 'outbox'); this.inflight = new Map();
+  }
+  async connect(message, { repositoryId } = {}) {
+    validateMessage(message);
+    if (message.type !== 'auth.open') fail('INVALID_ARGUMENT', 'Expected auth.open');
+    const identity = await this.identity();
+    message = { ...message, payload: { ...message.payload, clientId: identity.clientId } };
+    let credential;
+    const result = await this.transport(this.origin, '', message, { allowLoopback: this.allowLoopback, receiveCredential: value => { credential = value; } });
+    return this.saveConnection(result, credential, { repositoryId });
+  }
+  async identity() {
+    const identityFile = path.join(this.directory, 'device-identity.json');
+    return withFileLock(`${identityFile}.lock`, async () => {
+      const prior = await readJSON(identityFile, null);
+      if (prior) return prior;
+      const created = { clientId: randomUUID() };
+      await atomicWrite(identityFile, encode(created));
+      return created;
+    });
+  }
+  async saveConnection(result, credential, { repositoryId } = {}) {
+    if (!credential) fail('UNAVAILABLE', 'Missing backend connection credential');
+    if (repositoryId && result.repositoryId !== repositoryId) {
+      await this.transport(this.origin, credential, { v: 2, id: randomUUID(), type: 'auth.close', payload: {} }, { allowLoopback: this.allowLoopback }).catch(() => {});
+      fail('FORBIDDEN', 'Cloud project does not match the verified GitHub repository');
+    }
+    const previous = await readJSON(this.file, null);
+    if (previous?.repositoryId && previous.repositoryId !== result.repositoryId) {
+      await this.transport(this.origin, credential, { v: 2, id: randomUUID(), type: 'auth.close', payload: {} }, { allowLoopback: this.allowLoopback }).catch(() => {});
+      fail('FORBIDDEN', 'Repository changed; preserve queues and migrate the project binding explicitly');
+    }
+    await withFileLock(`${this.file}.lock`, () => atomicWrite(this.file, encode({ origin: this.origin, credential, ...result })));
+    return result;
+  }
+  async transmit(message) {
+    const connection = await readJSON(this.file, null);
+    if (!connection?.credential || connection.origin !== this.origin) fail('UNAUTHORIZED', 'Local backend must connect first');
+    try {
+      return await this.transport(connection.origin, connection.credential, message, { allowLoopback: this.allowLoopback });
+    } catch (error) {
+      if (error?.code === 'UNAUTHORIZED') {
+        await withFileLock(`${this.file}.lock`, async () => {
+          const current = await readJSON(this.file, null);
+          if (current?.credential === connection.credential) await atomicWrite(this.file, encode({
+            origin: this.origin, disconnected: true, error: error.code, failedAt: new Date().toISOString(),
+          }));
+        });
+      }
+      throw error;
+    }
+  }
+  async connected() { const value = await readJSON(this.file, null); return value?.origin === this.origin && !!value.credential; }
+  async callCoordinatorTool(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) fail('INVALID_ARGUMENT', 'Coordinator tool request must be an object');
+    const connection = await readJSON(this.file, null);
+    if (!connection?.credential || connection.origin !== this.origin) fail('UNAUTHORIZED', 'Local backend must connect first');
+    const base = new URL(this.origin);
+    if (base.username || base.password || base.protocol !== 'https:' && !(this.allowLoopback && base.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(base.hostname))) fail('FORBIDDEN', 'Invalid coordinator tool origin');
+    const response = await fetch(new URL('/api/v2/coordinator-tools', base), {
+      method: 'POST',
+      headers: { Authorization: `Bearer ${connection.credential}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal: AbortSignal.timeout(40000),
+    });
+    let value = null;
+    try { value = await response.json(); } catch { fail('UNAVAILABLE', 'Coordinator tool response was not JSON'); }
+    if (!response.ok || value?.ok !== true) fail(value?.error?.code || 'UNAVAILABLE', value?.error?.message || 'Coordinator tool failed');
+    return value.data;
+  }
+  async recordCreationFailure(id, error) {
+    if (!/^[a-f0-9]{64}$/.test(id || '')) fail('INVALID_ARGUMENT', 'Invalid creation identity');
+    const file = path.join(this.directory, 'creation-results.json');
+    await withFileLock(file + '.lock', async () => {
+      const values = await readJSON(file, {});
+      values[id] ||= { id, error: /^[A-Z][A-Z0-9_]{0,79}$/.test(error || '') ? error : 'SESSION_CREATION_FAILED' };
+      await atomicWrite(file, encode(values));
+    });
+  }
+  async supports(capability) {
+    const value = await readJSON(this.file, null);
+    return value?.origin === this.origin && !!value.credential && value.capabilities?.includes(capability) === true;
+  }
+  async proxyBlob(req, res, session, blobId) {
+    if (!['GET', 'PUT'].includes(req.method) || !/^[a-f0-9]{64}$/.test(blobId)) fail('INVALID_ARGUMENT', 'Invalid binary request');
+    const connection = await readJSON(this.file, null), base = new URL(this.origin);
+    if (!connection?.credential || connection.origin !== this.origin) fail('UNAUTHORIZED', 'Backend is disconnected');
+    if (base.username || base.password || base.protocol !== 'https:' && !(this.allowLoopback && base.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(base.hostname))) fail('FORBIDDEN', 'Invalid binary transport origin');
+    let body;
+    if (req.method === 'PUT') {
+      const chunks = []; let size = 0;
+      for await (const bytes of req) { size += bytes.length; if (size > 1024 * 1024) fail('TOO_LARGE', 'Chunk exceeds 1 MiB'); chunks.push(bytes); }
+      body = Buffer.concat(chunks);
+    }
+    const headers = { Authorization: `Bearer ${connection.credential}`, 'X-Context-Guard-Session': session.id, 'X-Context-Guard-Generation': String(session.generation) };
+    for (const key of ['range', 'content-range']) if (req.headers[key]) headers[key] = req.headers[key];
+    const response = await fetch(new URL(`/api/v2/blobs/${blobId}`, base), { method: req.method, headers, body, redirect: 'error', signal: AbortSignal.timeout(30000) });
+    const expectedType = response.ok && req.method === 'GET' ? 'application/octet-stream' : 'application/json';
+    if (!response.headers.get('content-type')?.startsWith(expectedType)) {
+      await response.body?.cancel(); fail('UNAVAILABLE', 'Unexpected binary endpoint response; keep the upload for retry');
+    }
+    const returnedHeaders = { 'Cache-Control': 'no-store', 'X-Content-Type-Options': 'nosniff' };
+    for (const key of ['content-type', 'content-length', 'content-range', 'accept-ranges', 'etag']) if (response.headers.has(key)) returnedHeaders[key] = response.headers.get(key);
+    // Never forward cookies/credentials. Range retries use the registered digest,
+    // so an unknown upload result can be safely retried with the same bytes.
+    res.writeHead(response.status, returnedHeaders);
+    let received = 0;
+    const bound = new Transform({ transform(chunk, _encoding, callback) {
+      received += chunk.length;
+      if (received > (response.ok && req.method === 'GET' ? 64 * 1024 * 1024 : 256 * 1024)) callback(new Error('Binary response exceeds limit'));
+      else callback(null, chunk);
+    } });
+    if (!response.body) { res.end(); return; }
+    await pipeline(Readable.fromWeb(response.body), bound, res);
+  }
+  start({ sessions, apply, onError = () => {}, onSession, onSessionCreations = async () => {} }) {
+    if (this.runtime) return;
+    const pump = new ProjectMessagePump({ sessions, apply, onError: error => onError(error, 'heartbeat'), onSession, send: message => this.send(message) });
+      let pending, retrying, creating, settling;
+      this.runtime = {
+        prepare: async () => {
+          const connection = await readJSON(this.file, null);
+          if (!connection?.credential || connection.origin !== this.origin) fail('UNAUTHORIZED', 'Backend is disconnected');
+          const current = await sessions();
+          const creationResults = Object.values(await readJSON(path.join(this.directory, 'creation-results.json'), {})).slice(0, 20);
+          pending = { sessions: current, message: pump.request('sync.heartbeat', { sessions: current, ...(creationResults.length ? { creationResults } : {}) }) };
+          return { origin: this.origin, credential: connection.credential, message: pending.message };
+        },
+        accept: reply => {
+          if (!pending || reply?.id !== pending.message.id) fail('CONFLICT', 'Heartbeat receipt is no longer current');
+          const observed = pending; pending = null;
+          if (!reply.ok) { onError(new ProtocolError(reply.error?.code || 'UNAVAILABLE', 'Device heartbeat rejected'), 'heartbeat'); return; }
+          if (reply.data?.creationResults?.length) {
+            const receipts = reply.data.creationResults;
+            settling = Promise.resolve(settling).then(async () => {
+              const file = path.join(this.directory, 'creation-results.json');
+              await withFileLock(file + '.lock', async () => {
+                const values = await readJSON(file, {});
+                for (const receipt of receipts) if (typeof receipt.accepted === 'boolean' && values[receipt.id]?.error === receipt.error) {
+                  if (!receipt.accepted) onError(new ProtocolError(receipt.code, 'Creation result rejected'), 'session-create');
+                  delete values[receipt.id];
+                }
+                await atomicWrite(file, encode(values));
+              });
+            }).catch(onError);
+          }
+          for (const item of reply.data?.rejected || []) onError(new ProtocolError(item.code, 'Session heartbeat rejected', { sessionId: item.id }), 'heartbeat');
+          pump.poll({ sessions: observed.sessions, beat: reply.data }).catch(error => onError(error, 'heartbeat'));
+          retrying ||= this.retryPending().catch(onError).finally(() => { retrying = null; });
+          if (reply.data?.sessionCreations?.length) creating ||= Promise.resolve().then(() => onSessionCreations(reply.data.sessionCreations))
+            .catch(error => onError(error, 'session-create')).finally(() => { creating = null; });
+        },
+        close: async () => { await pump.close(); await retrying; await creating; await settling; },
+      };
+  }
+  async close() { const runtime = this.runtime; this.runtime = null; await runtime?.close(); await Promise.all([...(this.enrolling?.values() || [])]); }
+  async disconnect(message) {
+    const result = await this.transmit(message);
+    await this.close();
+    await withFileLock(`${this.file}.lock`, () => atomicWrite(this.file, encode({ origin: this.origin, disconnected: true })));
+    return result;
+  }
+  async bind(message, localBinding) {
+    const file = path.join(this.directory, 'bindings', `${hash(message.payload.sessionId)}.json`);
+    return withFileLock(`${file}.lock`, async () => {
+      const versions = await readJSON(file, {});
+      const remote = await this.send(message, wire => ({ ...wire, payload: { ...wire.payload,
+        expectedBindingVersion: versions[wire.payload.expectedBindingVersion] || '',
+      } }));
+      if (remote.session.id !== localBinding.session.id || remote.session.generation !== localBinding.session.generation) {
+        fail('STALE_SESSION', 'Cloud and local binding generations differ');
+      }
+      versions[localBinding.bindingVersion] = remote.bindingVersion;
+      await atomicWrite(file, encode(versions));
+      return localBinding;
+    });
+  }
+  async ensureBinding(binding) {
+    const versions = await readJSON(path.join(this.directory, 'bindings', `${hash(binding.sessionId)}.json`), {});
+    if (versions[binding.version]) return;
+    await this.bind({ v: 2, id: `bind:${hash(binding.version)}`, type: 'session.bind', payload: {
+      sessionId: binding.sessionId, worktreeId: binding.worktreeId, agentId: binding.agentId,
+      expectedBindingVersion: binding.version,
+    } }, { session: { id: binding.sessionId, generation: binding.generation }, bindingVersion: binding.version });
+  }
+  async bindingReady(binding) {
+    const versions = await readJSON(path.join(this.directory, 'bindings', `${hash(binding.sessionId)}.json`), {});
+    if (versions[binding.version]) return true;
+    this.enrolling ||= new Map();
+    if (!this.enrolling.has(binding.sessionId) && this.enrolling.size < 4) {
+      const job = this.ensureBinding(binding).catch(error => { this.lastError = error.code || 'UNAVAILABLE'; })
+        .finally(() => this.enrolling.delete(binding.sessionId));
+      this.enrolling.set(binding.sessionId, job);
+    }
+    return false;
+  }
+  async send(message, prepare = value => value) {
+    validateMessage(message);
+    if (message.type.startsWith('auth.')) fail('FORBIDDEN', 'Password and credential operations cannot enter the outbox');
+    if (readTypes.has(message.type)) return this.transmit(message);
+    const id = hash(message.id);
+    if (this.inflight.has(id)) {
+      if (this.inflight.get(id).fingerprint !== canonical(message)) fail('ID_REUSED', 'Concurrent request ID differs');
+      return this.inflight.get(id).promise;
+    }
+    const promise = this.deliver(message, prepare).finally(() => this.inflight.delete(id));
+    this.inflight.set(id, { fingerprint: canonical(message), promise });
+    return promise;
+  }
+  async savedMessage(id) {
+    return ((await readJSON(path.join(this.directory, 'outcomes', `${hash(id)}.json`), null)) || await readJSON(path.join(this.outbox, `${hash(id)}.json`), null))?.message || null;
+  }
+  async deliver(message, prepare) {
+    const file = path.join(this.outbox, `${hash(message.id)}.json`), fingerprint = canonical(message);
+    const outcomeFile = path.join(this.directory, 'outcomes', `${hash(message.id)}.json`);
+    const outcome = record => {
+      if (record.state === 'rejected') throw new ProtocolError(record.error.code, record.error.message, record.error.details);
+      return record.result;
+    };
+    const prior = await withFileLock(`${file}.lock`, async () => {
+      const completed = await readJSON(outcomeFile, null);
+      if (completed) {
+        if (canonical(completed.message) !== fingerprint) fail('ID_REUSED', 'Request ID differs from durable outcome');
+        await fs.unlink(file).catch(error => { if (error.code !== 'ENOENT') throw error; });
+        return completed;
+      }
+      const existing = await readJSON(file, null);
+      if (existing && canonical(existing.message) !== fingerprint) fail('ID_REUSED', 'Request ID differs from durable outbox');
+      if (existing) return existing;
+      const pending = { message, wire: prepare(structuredClone(message)), state: 'pending' };
+      validateMessage(pending.wire);
+      const sequenceFile = path.join(this.directory, 'outbox-sequence.json');
+      pending.sequence = await withFileLock(`${sequenceFile}.lock`, async () => {
+        const next = (await readJSON(sequenceFile, { value: 0 })).value + 1;
+        if (!Number.isSafeInteger(next)) fail('UNAVAILABLE', 'Outbox sequence is exhausted');
+        await atomicWrite(sequenceFile, encode({ value: next }));
+        return next;
+      });
+      await atomicWrite(file, encode(pending));
+      return pending;
+    });
+    if (['done', 'rejected'].includes(prior?.state)) return outcome(prior);
+    const scope = messageScope(message);
+    return withFileLock(path.join(this.directory, 'lanes', `${hash(scope)}.lock`), async () => {
+      const completed = await readJSON(outcomeFile, null);
+      if (completed) return outcome(completed);
+      const current = await readJSON(file);
+      if (current.state === 'done') return current.result;
+      // A fresh write must not overtake an older uncertain write in this Session.
+      for (const name of await fs.readdir(this.outbox)) {
+        if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+        const record = await readJSON(path.join(this.outbox, name), null);
+        if (!record) continue;
+        if (record.state === 'pending' && messageScope(record.message) === scope && (record.sequence || 0) < (current.sequence || 0)) fail('UNAVAILABLE', 'An earlier Session write must be recovered first');
+      }
+      const save = record => withFileLock(`${file}.lock`, async () => {
+        // Persist the retry receipt before removing the pending index entry.
+        await atomicWrite(outcomeFile, encode(record));
+        await fs.unlink(file).catch(error => { if (error.code !== 'ENOENT') throw error; });
+      });
+      try {
+        const result = await this.transmit(current.wire || message);
+        await save({ ...current, state: 'done', result });
+        return result;
+      } catch (error) {
+        // A same-ID retry returns the server's atomic receipt. A confirmed
+        // rejection resolves earlier transport uncertainty without claiming success.
+        if (error.confirmedRejection) await save({ ...current, state: 'rejected', error: { code: error.code, message: error.message, ...(error.details ? { details: error.details } : {}) } });
+        else if (!current.uncertain) await withFileLock(`${file}.lock`, () => atomicWrite(file, encode({ ...current, uncertain: true })));
+        throw error;
+      }
+    });
+  }
+  async retryPending() {
+    const files = await fs.readdir(this.outbox).catch(error => { if (error.code === 'ENOENT') return []; throw error; });
+    const groups = new Map();
+    for (const name of files.filter(name => /^[a-f0-9]{64}\.json$/.test(name))) {
+      const record = await readJSON(path.join(this.outbox, name), null);
+      if (!record) continue;
+      if (record.state !== 'pending') continue;
+      const scope = messageScope(record.message);
+      if (!groups.has(scope)) groups.set(scope, []);
+      groups.get(scope).push(record);
+    }
+    const queue = [...groups.values()], results = [];
+    await Promise.all(Array.from({ length: Math.min(4, queue.length) }, async () => {
+      while (queue.length) {
+        const records = queue.shift().sort((a, b) => (a.sequence || 0) - (b.sequence || 0));
+        for (const record of records) {
+          try { await this.send(record.message); results.push({ id: record.message.id, sent: true }); }
+          catch (error) {
+            results.push({ id: record.message.id, sent: false, code: error.code || 'UNAVAILABLE' });
+            break; // Keep dependent writes behind the failed operation, not behind other Sessions.
+          }
+        }
+      }
+    }));
+    return results;
+  }
+}

package/scripts/workbench/protocol-events.mjs

@@ -0,0 +1,53 @@
+import { fail, MAX_MESSAGE_BYTES, validateMessage } from '../shared/protocol.mjs';
+
+// SSE is only a hint. Independent heartbeats remain responsible for catching gaps.
+export async function readEvents(origin, credential, { signal, onEvent, fetcher = fetch, allowLoopback = false, idleMs = 25000 }) {
+  const base = new URL(origin);
+  if (base.username || base.password || (base.protocol !== 'https:' && !(allowLoopback && base.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(base.hostname)))) fail('FORBIDDEN', 'Invalid event transport origin');
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  signal?.addEventListener('abort', abort, { once: true });
+  if (signal?.aborted) abort();
+  let timer, reader;
+  const renew = () => { clearTimeout(timer); timer = setTimeout(abort, idleMs); timer.unref?.(); };
+  try {
+    renew();
+    const response = await fetcher(new URL('/api/v2/events', base), { redirect: 'error', signal: controller.signal,
+      headers: { Authorization: `Bearer ${credential}`, Accept: 'text/event-stream' } });
+    if (response.status === 401) fail('UNAUTHORIZED', 'Connection expired');
+    if (response.status === 403) fail('FORBIDDEN', 'Connection is not authorized');
+    if (!response.ok || !response.headers.get('content-type')?.includes('text/event-stream')) fail('UNAVAILABLE', 'Event stream unavailable');
+    reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let pending = '', data = [], size = 0;
+    while (!controller.signal.aborted) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      renew(); pending += decoder.decode(chunk.value, { stream: true });
+      let newline;
+      while ((newline = pending.indexOf('\n')) >= 0) {
+        const line = pending.slice(0, newline).replace(/\r$/, ''); pending = pending.slice(newline + 1);
+        if (!line) {
+          if (data.length) {
+            let message;
+            try { message = JSON.parse(data.join('\n')); } catch { fail('UNAVAILABLE', 'Malformed event hint'); }
+            validateMessage(message);
+            if (message.type !== 'sync.event') fail('UNAVAILABLE', 'Unexpected event hint');
+            await onEvent(message);
+          }
+          data = []; size = 0;
+        } else if (line.startsWith('data:')) {
+          const value = line.slice(5).replace(/^ /, ''); size += Buffer.byteLength(value);
+          if (size > MAX_MESSAGE_BYTES) fail('TOO_LARGE', 'Event hint exceeds limit');
+          data.push(value);
+        }
+      }
+      if (Buffer.byteLength(pending) + size > MAX_MESSAGE_BYTES) fail('TOO_LARGE', 'Event hint exceeds limit');
+    }
+    if (!signal?.aborted) fail('UNAVAILABLE', 'Event stream ended; heartbeat will recover missed changes');
+  } finally {
+    clearTimeout(timer); controller.abort();
+    signal?.removeEventListener('abort', abort);
+    await reader?.cancel().catch(() => {});
+  }
+}

package/scripts/workbench/protocol-repository.mjs

@@ -0,0 +1,58 @@
+import { fail } from '../shared/protocol.mjs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+
+async function keychainToken() {
+  try {
+    const { stdout } = await execFileAsync('gh', ['auth', 'token'], {
+      encoding: 'utf8', windowsHide: true, timeout: 5000, maxBuffer: 64 * 1024,
+    });
+    const token = stdout.trim();
+    return token && token.length <= 4096 ? token : '';
+  } catch { return ''; }
+}
+
+// GitHub's repository ID survives a repository/branch rename. Branch heads are
+// commits, not repository identities: https://docs.github.com/en/rest/repos/repos
+export async function lookupRepository(slug, {
+  fetcher = fetch,
+  token = process.env.GH_TOKEN || process.env.GITHUB_TOKEN,
+  tokenProvider = keychainToken,
+} = {}) {
+  if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(slug) || slug.split('/').some(part => ['.', '..'].includes(part))) fail('INVALID_ARGUMENT', 'Invalid GitHub repository');
+  let url = new URL(`https://api.github.com/repos/${slug}`);
+  let authorization = token || '', keychainChecked = !!authorization;
+  for (let attempt = 0; attempt < 4; attempt++) {
+    let response;
+    try { response = await fetcher(url, { redirect: 'manual', signal: AbortSignal.timeout(10000),
+      headers: { Accept: 'application/vnd.github+json', 'User-Agent': 'Context-Guard', ...(authorization ? { Authorization: `Bearer ${authorization}` } : {}) } }); }
+    catch { fail('UNAVAILABLE', 'GitHub repository identity could not be verified'); }
+    if ([301, 302, 307, 308].includes(response.status)) {
+      const location = response.headers.get('location'); await response.body?.cancel();
+      if (!location) fail('UNAVAILABLE', 'GitHub redirect is missing');
+      const next = new URL(location, url);
+      if (next.origin !== 'https://api.github.com' || next.username || next.password || !/^\/(repos\/[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+|repositories\/\d+)$/.test(next.pathname)) fail('FORBIDDEN', 'GitHub redirected outside the repository API');
+      url = next; continue;
+    }
+    if (!response.ok) {
+      await response.body?.cancel();
+      if (!authorization && !keychainChecked && [401, 403, 404].includes(response.status)) {
+        keychainChecked = true;
+        authorization = await tokenProvider();
+        if (authorization) { attempt -= 1; continue; }
+      }
+      fail(response.status === 404 ? 'NOT_FOUND' : [401, 403].includes(response.status) ? 'FORBIDDEN' : 'UNAVAILABLE', 'GitHub repository is unavailable to this backend');
+    }
+    let value;
+    try {
+      const chunks = []; let size = 0;
+      for await (const chunk of response.body) { size += chunk.length; if (size > 1024 * 1024) fail('TOO_LARGE', 'GitHub response exceeds limit'); chunks.push(chunk); }
+      value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    } catch { fail('UNAVAILABLE', 'GitHub returned an invalid repository identity'); }
+    if (!Number.isSafeInteger(value.id) || value.id <= 0 || typeof value.full_name !== 'string') fail('UNAVAILABLE', 'GitHub returned an invalid repository identity');
+    return { repositoryId: String(value.id), slug: value.full_name };
+  }
+  fail('UNAVAILABLE', 'Too many GitHub repository redirects');
+}