@runuai/host 0.9.11 → 0.9.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runuai/host",
-  "version": "0.9.11",
+  "version": "0.9.12",
   "description": "Uai host — runs ephemeral AI coding tasks in Docker on a machine you control.",
   "license": "MIT",
   "author": "Diogo Perillo <diogo.perillo@gmail.com>",

package/src/main.ts

@@ -25,12 +25,17 @@ import {
 import { getHostTask } from "../lib/runtime-state";
 import { getOrchestrator, recoveryComplete } from "../lib/orchestrator";
 import {
+  claimGithubCredentialGeneration,
   connectedUserIds,
+  GitHubRepositoryAccessError,
   isTransientGithubError,
+  listUserInstallationIds,
+  listUserInstallationRepositoryIds,
   onConnectClear,
   onConnectSet,
   onGithubChange,
   reconcileTaskGitAuth,
+  rollbackClaimedGitHubCredentialSet,
   runGithubConnectionTransition,
   setAuthExpiredHandler,
 } from "../lib/github-tokens";
@@ -79,6 +84,9 @@ import { ensureStandardImage, standardRuntimes } from "../lib/standard-image";
 import { hostCommands, hostEvents } from "./index";
 import {
   HostErrorCode,
+  GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
+  GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
+  GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
   TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
   type CloudToHost,
@@ -90,6 +98,7 @@ import {
   type HostCommands,
   type HostToCloud,
   type PermissionDecision,
+  parseGitHubCredentialGeneration,
   parseChannelMode,
   parseTranscriptTargets,
   type TaskAgent,
@@ -225,6 +234,9 @@ function buildCapabilities(): HostCapabilities {
     version: packageVersion(),
     protocolFeatures: [
       TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
+      GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE,
+      GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE,
+      GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE,
       // The echo adapter cannot execute the in-task CLI. Advertising typed
       // dispatch in mock mode would let the composer create a Secretary that
       // has no way to wake crew.
@@ -353,24 +365,67 @@ function connect(): void {
       case "gh.connect.set": {
         // Account switches fence every host-side Git operation using the old
         // credential before the replacement grant is stored or reinjected.
-        void runGithubConnectionTransition(frame.userId, () =>
-          onConnectSet(frame, {
+        void runGithubConnectionTransition(frame.userId, async () => {
+          const claim = claimGithubCredentialGeneration(
+            frame.userId,
+            frame.generation,
+            "set",
+          );
+          if (!claim) {
+            return {
+              ok: false as const,
+              code: "stale_generation" as const,
+              error: "stale GitHub credential generation",
+            };
+          }
+          const transitionDeps = {
             invalidateCredentials: invalidateTaskGithubGitCredentials,
-            reconcile: (taskId, userId) =>
+            reconcile: (taskId: string, userId: string) =>
               getOrchestrator().runTaskLifecycle(taskId, () =>
                 reconcileTaskGitAuth(taskId, userId),
               ),
-          }),
-        ).then(
+          };
+          let result: Awaited<ReturnType<typeof onConnectSet>>;
+          try {
+            result = await onConnectSet(
+              { ...frame, generation: claim.generation },
+              transitionDeps,
+            );
+          } catch (err) {
+            result = {
+              ok: false,
+              error: err instanceof Error ? err.message : String(err),
+            };
+          }
+          if (!result.ok) {
+            // Storage can succeed before live-task reconciliation fails. Never
+            // emit a negative set ack while that untrusted credential remains
+            // active: persist the same-generation clear tombstone first, then
+            // best-effort scrub/revoke under the same serialized transition.
+            await rollbackClaimedGitHubCredentialSet(
+              frame.userId,
+              claim.generation,
+              transitionDeps,
+            );
+          }
+          return result;
+        }).then(
           (result) =>
             send(
               socket,
               result.ok
-                ? { kind: "gh.connect.ack", userId: frame.userId, ok: true }
+                ? {
+                    kind: "gh.connect.ack",
+                    opId: frame.opId,
+                    userId: frame.userId,
+                    ok: true,
+                  }
                 : {
                     kind: "gh.connect.ack",
+                    opId: frame.opId,
                     userId: frame.userId,
                     ok: false,
+                    code: "code" in result ? result.code : undefined,
                     error: result.error ?? "store failed",
                   },
             ),
@@ -379,6 +434,7 @@ function connect(): void {
             console.warn(`[github] connect.set failed: ${error}`);
             send(socket, {
               kind: "gh.connect.ack",
+              opId: frame.opId,
               userId: frame.userId,
               ok: false,
               error,
@@ -387,31 +443,130 @@ function connect(): void {
         );
         break;
       }
+      case "gh.installations.list": {
+        // Read-only: no token leaves the host, only the installation ids
+        // GitHub attests to for this user. A failure acks ok:false rather
+        // than an empty list — the cloud prunes bindings absent from the
+        // result, and "couldn't ask" must never be read as "installed
+        // nowhere".
+        void listUserInstallationIds(
+          frame.userId,
+          {},
+          frame.generation ?? 0,
+        ).then(
+          (installationIds) =>
+            send(socket, {
+              kind: "gh.installations.ack",
+              opId: frame.opId,
+              ok: true,
+              installationIds,
+            }),
+          (err) => {
+            const error = err instanceof Error ? err.message : String(err);
+            const code =
+              err instanceof GitHubRepositoryAccessError
+                ? err.code
+                : "github_unavailable";
+            console.warn(
+              `[github] installation list failed for ${frame.userId}: ${error}`,
+            );
+            send(socket, {
+              kind: "gh.installations.ack",
+              opId: frame.opId,
+              ok: false,
+              code,
+              error,
+            });
+          },
+        );
+        break;
+      }
+      case "gh.repositories.list": {
+        void listUserInstallationRepositoryIds(
+          frame.userId,
+          frame.installationId,
+          {},
+          frame.generation ?? 0,
+        ).then(
+          ({ repositoryIds, truncated }) =>
+            send(socket, {
+              kind: "gh.repositories.ack",
+              opId: frame.opId,
+              ok: true,
+              repositoryIds,
+              truncated,
+            }),
+          (err) => {
+            const error = err instanceof Error ? err.message : String(err);
+            const code =
+              err instanceof GitHubRepositoryAccessError
+                ? err.code
+                : "github_unavailable";
+            console.warn(
+              `[github] repository list failed for ${frame.userId}/${frame.installationId}: ${error}`,
+            );
+            send(socket, {
+              kind: "gh.repositories.ack",
+              opId: frame.opId,
+              ok: false,
+              code,
+              error,
+            });
+          },
+        );
+        break;
+      }
       case "gh.connect.clear": {
-        // Local deletion happens synchronously inside onConnectClear and the
-        // remote revoke starts immediately in the background. Delay the ack
-        // only for live-container logout + transport transition, so the UI
-        // cannot report Disconnected while a task can still use the old token.
-        void runGithubConnectionTransition(frame.userId, () =>
-          onConnectClear(frame.userId, {
+        // The serialized transition removes the local credential, waits for
+        // best-effort remote revocation, and scrubs live containers before it
+        // acknowledges. That keeps a delayed revoke from racing a later set.
+        void runGithubConnectionTransition(frame.userId, async () => {
+          const claim = claimGithubCredentialGeneration(
+            frame.userId,
+            frame.generation,
+            "clear",
+          );
+          if (!claim) {
+            return {
+              ok: false as const,
+              code: "stale_generation" as const,
+              error: "stale GitHub credential generation",
+            };
+          }
+          await onConnectClear(frame.userId, {
             invalidateCredentials: invalidateTaskGithubGitCredentials,
             reconcile: (taskId, userId) =>
               getOrchestrator().runTaskLifecycle(taskId, () =>
                 reconcileTaskGitAuth(taskId, userId),
               ),
-          }),
-        ).then(
-          () =>
-            send(socket, {
-              kind: "gh.connect.ack",
-              userId: frame.userId,
-              ok: true,
-            }),
+          });
+          return { ok: true as const };
+        }).then(
+          (result) =>
+            send(
+              socket,
+              result.ok
+                ? {
+                    kind: "gh.connect.ack",
+                    opId: frame.opId,
+                    userId: frame.userId,
+                    ok: true,
+                  }
+                : {
+                    kind: "gh.connect.ack",
+                    opId: frame.opId,
+                    userId: frame.userId,
+                    ok: false,
+                    code: result.code,
+                    error: result.error,
+                  },
+            ),
           (err) => {
             const error = err instanceof Error ? err.message : String(err);
             console.warn(`[github] connect.clear failed: ${error}`);
             send(socket, {
               kind: "gh.connect.ack",
+              opId: frame.opId,
               userId: frame.userId,
               ok: false,
               error,
@@ -1127,12 +1282,17 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
     typeof frame.installationId === "number" &&
     typeof frame.githubLogin === "string" &&
     (frame.targetType === "User" || frame.targetType === "Organization") &&
+    (frame.opId === undefined || typeof frame.opId === "string") &&
+    parseGitHubCredentialGeneration(frame.generation) !== null &&
     // Exactly one token kind: accessToken (ADR-033) or refreshToken (ADR-027).
     (typeof frame.accessToken === "string" ||
       typeof frame.refreshToken === "string")
   ) {
     return {
       kind: "gh.connect.set",
+      opId: typeof frame.opId === "string" ? frame.opId : undefined,
+      generation:
+        parseGitHubCredentialGeneration(frame.generation) ?? undefined,
       userId: frame.userId,
       installationId: frame.installationId,
       githubLogin: frame.githubLogin,
@@ -1147,8 +1307,51 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
           : undefined,
     };
   }
-  if (frame.kind === "gh.connect.clear" && typeof frame.userId === "string") {
-    return { kind: "gh.connect.clear", userId: frame.userId };
+  if (
+    frame.kind === "gh.connect.clear" &&
+    typeof frame.userId === "string" &&
+    (frame.opId === undefined || typeof frame.opId === "string") &&
+    parseGitHubCredentialGeneration(frame.generation) !== null
+  ) {
+    return {
+      kind: "gh.connect.clear",
+      opId: typeof frame.opId === "string" ? frame.opId : undefined,
+      generation:
+        parseGitHubCredentialGeneration(frame.generation) ?? undefined,
+      userId: frame.userId,
+    };
+  }
+  if (
+    frame.kind === "gh.installations.list" &&
+    typeof frame.opId === "string" &&
+    typeof frame.userId === "string" &&
+    parseGitHubCredentialGeneration(frame.generation) !== null
+  ) {
+    return {
+      kind: "gh.installations.list",
+      opId: frame.opId,
+      generation:
+        parseGitHubCredentialGeneration(frame.generation) ?? undefined,
+      userId: frame.userId,
+    };
+  }
+  if (
+    frame.kind === "gh.repositories.list" &&
+    typeof frame.opId === "string" &&
+    typeof frame.userId === "string" &&
+    typeof frame.installationId === "number" &&
+    Number.isSafeInteger(frame.installationId) &&
+    frame.installationId > 0 &&
+    parseGitHubCredentialGeneration(frame.generation) !== null
+  ) {
+    return {
+      kind: "gh.repositories.list",
+      opId: frame.opId,
+      generation:
+        parseGitHubCredentialGeneration(frame.generation) ?? undefined,
+      userId: frame.userId,
+      installationId: frame.installationId,
+    };
   }
   if (
     (frame.kind === "ssh.key.get" ||

package/src/protocol.ts

@@ -35,11 +35,23 @@ export type HostCommandResult<T> =
 export const TRANSCRIPT_TARGETS_PROTOCOL_FEATURE = "transcript-targets-v1";
 export const SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE =
   "secretary-typed-dispatch-v1";
+export const GITHUB_INSTALLATION_VERIFICATION_PROTOCOL_FEATURE =
+  "github-installation-verification-v1";
+export const GITHUB_REPOSITORY_ACCESS_PROTOCOL_FEATURE =
+  "github-repository-access-v1";
+export const GITHUB_CREDENTIAL_GENERATION_PROTOCOL_FEATURE =
+  "github-credential-generation-v1";
 export const COMMUNICATOR_EXECUTION_PROFILE = "communicator";
 export const MAX_AGENT_ID_CHARS = 128;
 export const MAX_SECRETARY_DISPATCH_RECIPIENTS = 16;
 export const MAX_SECRETARY_DISPATCH_INSTRUCTION_CHARS = 8_000;
 export const MAX_SECRETARY_DISPATCH_ID_CHARS = 256;
+// Wire and GitHub-call bounds for the host-assisted authorization snapshot.
+// Exceeding either bound fails the whole verification; a partial installation
+// list could cause destructive pruning, while a partial repository list is an
+// explicit false-negative allowlist and therefore carries `truncated: true`.
+export const MAX_GITHUB_INSTALLATIONS = 100;
+export const MAX_GITHUB_REPOSITORIES_PER_INSTALLATION = 1_000;
 
 export interface CommandContext {
   commandId: string;
@@ -133,6 +145,19 @@ export function parseChannelMode(
   throw new Error("invalid command args: expected channel mode");
 }
 
+/** Optional during rolling upgrades; `null` is the explicit invalid sentinel
+ * so generation zero remains a valid migrated credential generation. */
+export function parseGitHubCredentialGeneration(
+  value: unknown,
+): number | undefined | null {
+  if (value === undefined) return undefined;
+  return typeof value === "number" &&
+    Number.isSafeInteger(value) &&
+    value >= 0
+    ? value
+    : null;
+}
+
 /** Parse the appendTranscript wire argument. `undefined` alone is the legacy
  * three-argument command and maps to chat.md during a rolling deploy. */
 export function parseTranscriptTargets(value: unknown): TranscriptTarget[] {
@@ -468,6 +493,13 @@ export interface TunnelReqLine {
 
 export type TunnelTarget = "editor" | "preview";
 
+export type GitHubRepositoryAccessErrorCode =
+  | "token_missing"
+  | "reauth_required"
+  | "installation_inaccessible"
+  | "github_unavailable"
+  | "invalid_response";
+
 export type CloudToHost =
   | {
       kind: "command";
@@ -506,6 +538,12 @@ export type CloudToHost =
   //                      for short-lived access tokens (host→cloud HTTP POST).
   | {
       kind: "gh.connect.set";
+      /** Correlates the stored credential with the exact host acknowledgement.
+       * Optional only for rolling compatibility with pre-correlation clouds. */
+      opId?: string;
+      /** Monotonic cloud-issued mutation fence. Optional only for rolling
+       * compatibility; generation-aware clouds require the matching feature. */
+      generation?: number;
       userId: string;
       installationId: number;
       githubLogin: string;
@@ -516,7 +554,31 @@ export type CloudToHost =
     }
   // Delete the user's token on the host. ADR-033: the host first POSTs the
   // token to the cloud's /api/github/revoke (kill it at GitHub) before deleting.
-  | { kind: "gh.connect.clear"; userId: string }
+  | {
+      kind: "gh.connect.clear";
+      opId?: string;
+      generation?: number;
+      userId: string;
+    }
+  // Ask the host which installations GitHub currently lists for a user, using
+  // the token the host already holds. Used to prune historical owner
+  // misbindings before any legacy row is trusted.
+  | {
+      kind: "gh.installations.list";
+      opId: string;
+      generation?: number;
+      userId: string;
+    }
+  // Renew one installation's App ∩ user repository allowlist without sending
+  // the user's token to the cloud. Kept separate from installation listing so
+  // ordinary one-row lease renewal is bounded and independently retryable.
+  | {
+      kind: "gh.repositories.list";
+      opId: string;
+      generation?: number;
+      userId: string;
+      installationId: number;
+    }
   // Per-user SSH key lifecycle (ADR-029). Keys are generated + stored on the
   // host; only the public key crosses the bridge (ssh.key.ack). `get` fetches
   // without creating, `ensure` creates-if-absent, `delete` removes.
@@ -594,8 +656,45 @@ export type HostToCloud =
   | { kind: "tunnel.data"; tunnelId: string }
   | { kind: "tunnel.close"; tunnelId: string; reason?: string }
   // Ack for gh.connect.set / gh.connect.clear (ADR-027).
-  | { kind: "gh.connect.ack"; userId: string; ok: true }
-  | { kind: "gh.connect.ack"; userId: string; ok: false; error: string }
+  | { kind: "gh.connect.ack"; opId?: string; userId: string; ok: true }
+  | {
+      kind: "gh.connect.ack";
+      opId?: string;
+      userId: string;
+      ok: false;
+      code?: "stale_generation";
+      error: string;
+    }
+  // Ack for gh.installations.list. `installationIds` is GitHub's current
+  // verdict and is authoritative ONLY on ok:true. An error must never be read
+  // as "installed nowhere", which would delete every binding the user has.
+  | {
+      kind: "gh.installations.ack";
+      opId: string;
+      ok: true;
+      installationIds: number[];
+    }
+  | {
+      kind: "gh.installations.ack";
+      opId: string;
+      ok: false;
+      code: GitHubRepositoryAccessErrorCode;
+      error: string;
+    }
+  | {
+      kind: "gh.repositories.ack";
+      opId: string;
+      ok: true;
+      repositoryIds: number[];
+      truncated: boolean;
+    }
+  | {
+      kind: "gh.repositories.ack";
+      opId: string;
+      ok: false;
+      code: GitHubRepositoryAccessErrorCode;
+      error: string;
+    }
   // Ack for ssh.key.get / ssh.key.ensure / ssh.key.delete (ADR-029). publicKey
   // is null when the user has no key (after delete, or a get-miss).
   | { kind: "ssh.key.ack"; userId: string; ok: true; publicKey: string | null }