@agentshouse/kit 0.0.1 → 0.1.0-alpha.10

package/src/channel.js

@@ -0,0 +1,37 @@
+import { BRIDGE_LINE_MAX_BYTES } from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+
+export function writeFrame(stream, frame) {
+  stream.write(`${JSON.stringify(frame)}\n`);
+}
+
+export function readFrames(stream, handlers) {
+  const maximum = handlers.maxBytes ?? BRIDGE_LINE_MAX_BYTES;
+  let buffered = "";
+  stream.setEncoding("utf8");
+  stream.on("data", (chunk) => {
+    buffered += chunk;
+    for (;;) {
+      const boundary = buffered.indexOf("\n");
+      if (boundary < 0) break;
+      const line = buffered.slice(0, boundary);
+      buffered = buffered.slice(boundary + 1);
+      if (line.trim() === "") continue;
+      let frame;
+      try {
+        frame = JSON.parse(line);
+      } catch {
+        handlers.onRefusal(new KitRefusal("kit_channel_frame_invalid"));
+        return;
+      }
+      if (typeof frame !== "object" || frame === null || Array.isArray(frame)) {
+        handlers.onRefusal(new KitRefusal("kit_channel_frame_invalid"));
+        return;
+      }
+      handlers.onFrame(frame);
+    }
+    if (Buffer.byteLength(buffered, "utf8") <= maximum) return;
+    buffered = "";
+    handlers.onRefusal(new KitRefusal("kit_channel_frame_exceeded"));
+  });
+}

package/src/command.js

@@ -0,0 +1,109 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { COMMAND_INPUT_MAX_BYTES } from "./contract.js";
+import { KitRefusal } from "./refusal.js";
+
+const INHERITED_ENVIRONMENT = ["PATH"];
+const HOUSE_CREDENTIAL = /^(ahk_|ahl_)/;
+const STDERR_KEPT_BYTES = 8 * 1024;
+
+export function withoutHouseCredentials(environment) {
+  for (const [name, value] of Object.entries(environment)) {
+    if (HOUSE_CREDENTIAL.test(value)) throw new KitRefusal("kit_house_credential_refused", name);
+  }
+  return environment;
+}
+
+export function inheritedEnvironment(names) {
+  const inherited = {};
+  for (const name of names) {
+    const value = process.env[name];
+    if (value !== undefined) inherited[name] = value;
+  }
+  return inherited;
+}
+
+function childEnvironment(environment) {
+  return {
+    ...inheritedEnvironment(INHERITED_ENVIRONMENT),
+    ...withoutHouseCredentials(environment),
+  };
+}
+
+async function resolvedSecret(name, reference) {
+  if (reference.environment !== undefined) {
+    return process.env[reference.environment] ?? "";
+  }
+  try {
+    return await readFile(reference.file, "utf8");
+  } catch {
+    throw new KitRefusal("kit_secret_unresolved", name);
+  }
+}
+
+export async function resolveEnvironment(declaration) {
+  const environment = { ...declaration.environment };
+  for (const [name, reference] of Object.entries(declaration.secrets ?? {})) {
+    const value = (await resolvedSecret(name, reference)).trim();
+    if (value === "") throw new KitRefusal("kit_secret_unresolved", name);
+    environment[name] = value;
+  }
+  return environment;
+}
+
+export async function runCommand(options) {
+  const environment = childEnvironment(options.environment);
+  const stdin = Buffer.from(options.stdin, "utf8");
+  if (stdin.length > COMMAND_INPUT_MAX_BYTES) {
+    throw new KitRefusal("kit_command_input_exceeded");
+  }
+  const [program, ...args] = options.command;
+  return new Promise((resolve, reject) => {
+    const child = spawn(program, args, { env: environment, stdio: ["pipe", "pipe", "pipe"] });
+    const output = [];
+    const errors = [];
+    let outputBytes = 0;
+    let errorBytes = 0;
+    let refusal = null;
+    const abandon = (code) => {
+      refusal ??= code;
+      child.kill("SIGKILL");
+    };
+    const timer = setTimeout(() => abandon("kit_command_timeout"), options.timeoutMs);
+    const cancel = () => abandon("kit_command_cancelled");
+    if (options.signal?.aborted) abandon("kit_command_cancelled");
+    options.signal?.addEventListener("abort", cancel, { once: true });
+    const settled = () => {
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", cancel);
+    };
+    child.stdout.on("data", (chunk) => {
+      outputBytes += chunk.length;
+      if (options.outputMaxBytes !== undefined && outputBytes > options.outputMaxBytes) {
+        abandon("kit_command_output_exceeded");
+        return;
+      }
+      output.push(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      if (errorBytes >= STDERR_KEPT_BYTES) return;
+      errorBytes += chunk.length;
+      errors.push(chunk);
+    });
+    child.on("error", () => {
+      settled();
+      reject(new KitRefusal("kit_command_unavailable", program));
+    });
+    child.on("close", (status) => {
+      settled();
+      const stderr = Buffer.concat(errors).toString("utf8").slice(0, STDERR_KEPT_BYTES);
+      if (refusal !== null) {
+        reject(new KitRefusal(refusal, stderr.trim() === "" ? null : stderr.trim()));
+        return;
+      }
+      resolve({ status, stdout: Buffer.concat(output).toString("utf8"), stderr });
+    });
+    child.stdin.on("error", () => undefined);
+    child.stdin.end(stdin);
+  });
+}

package/src/configuration.js

@@ -0,0 +1,465 @@
+import { readFile } from "node:fs/promises";
+import {
+  CONNECTOR_TIMEOUT_MS,
+  DECLARED_ID,
+  EXECUTION_AUTHORITIES,
+  MIGRATOR_CATEGORY,
+  MIGRATOR_TIMEOUT_MS,
+} from "./contract.js";
+import { declarationReader } from "./declaration.js";
+import { GOOGLE_DRIVE_ID } from "./google/id.js";
+import { KitRefusal } from "./refusal.js";
+
+const PRESETS = new Set(["custom", "google"]);
+const AGENT_CLIENTS = new Set(["claude-code"]);
+const GOOGLE_CURATED_SERVICES = new Set(["gmail", "calendar", "drive"]);
+const ENVIRONMENT_VALUE_MAX = 4096;
+const GOOGLE_API_HOST = /^[a-z0-9-]+(?:\.[a-z0-9-]+)*\.googleapis\.com$/;
+const GOOGLE_API_PATH = /^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]+$/;
+const GOOGLE_API_SCOPE = /^https:\/\/www\.googleapis\.com\/auth\/[A-Za-z0-9._-]+$/;
+const EXTRACTION_PATH = /^(?:[A-Za-z_][A-Za-z0-9_-]*|\d+)(?:\.(?:[A-Za-z_][A-Za-z0-9_-]*|\d+))*$/;
+const QUERY_NAME = /^[A-Za-z][A-Za-z0-9_.-]{0,127}$/;
+
+const { refuse, plain, closed, text, positiveCount, filled } = declarationReader(
+  "kit_configuration_invalid",
+);
+
+function declaredId(value, declaration) {
+  if (typeof value !== "string" || !DECLARED_ID.test(value)) refuse(declaration);
+  return value;
+}
+
+function environmentOf(value, declaration) {
+  if (value === undefined) return {};
+  const environment = {};
+  for (const [name, entry] of Object.entries(plain(value, declaration))) {
+    if (typeof entry !== "string" || entry.length > ENVIRONMENT_VALUE_MAX) {
+      refuse(`${declaration}.${name}`);
+    }
+    environment[name] = entry;
+  }
+  return environment;
+}
+
+function secretReference(value, declaration) {
+  const reference = closed(value, ["environment", "file"], declaration);
+  const named = Object.keys(reference);
+  if (named.length !== 1) refuse(declaration);
+  return { [named[0]]: text(reference[named[0]], declaration, 4096) };
+}
+
+function secretsOf(value, declaration, environment) {
+  if (value === undefined) return {};
+  const secrets = {};
+  for (const [name, entry] of Object.entries(plain(value, declaration))) {
+    if (name in environment) refuse(`${declaration}.${name}`);
+    secrets[name] = secretReference(entry, `${declaration}.${name}`);
+  }
+  return secrets;
+}
+
+function connectorOf(value, declaration) {
+  if (value === undefined) refuse(declaration);
+  const connector = closed(
+    value,
+    ["command", "timeout_ms", "environment", "secrets"],
+    declaration,
+  );
+  const command = filled(connector.command, `${declaration}.command`);
+  const environment = environmentOf(connector.environment, `${declaration}.environment`);
+  return {
+    command: command.map((argument, position) =>
+      text(argument, `${declaration}.command[${position}]`, 4096),
+    ),
+    timeoutMs:
+      connector.timeout_ms === undefined
+        ? CONNECTOR_TIMEOUT_MS
+        : positiveCount(connector.timeout_ms, `${declaration}.timeout_ms`, CONNECTOR_TIMEOUT_MS),
+    environment,
+    secrets: secretsOf(connector.secrets, `${declaration}.secrets`, environment),
+  };
+}
+
+function migratorOf(value, declaration) {
+  const declared = closed(
+    value,
+    ["id", "category", "command", "timeout_ms", "environment", "secrets"],
+    declaration,
+  );
+  if (declared.category !== MIGRATOR_CATEGORY) refuse(`${declaration}.category`);
+  const command = filled(declared.command, `${declaration}.command`);
+  const environment = environmentOf(declared.environment, `${declaration}.environment`);
+  return {
+    id: declaredId(declared.id, `${declaration}.id`),
+    category: declared.category,
+    command: command.map((argument, position) =>
+      text(argument, `${declaration}.command[${position}]`, 4096),
+    ),
+    timeoutMs:
+      declared.timeout_ms === undefined
+        ? MIGRATOR_TIMEOUT_MS
+        : positiveCount(declared.timeout_ms, `${declaration}.timeout_ms`, MIGRATOR_TIMEOUT_MS),
+    environment,
+    secrets: secretsOf(declared.secrets, `${declaration}.secrets`, environment),
+  };
+}
+
+function backfillOf(value, declaration) {
+  if (value === undefined) refuse(declaration);
+  const backfill = closed(value, ["days", "count", "all"], declaration);
+  const named = Object.keys(backfill);
+  if (named.length !== 1) refuse(declaration);
+  if (named[0] === "all") {
+    if (backfill.all !== true) refuse(declaration);
+    return { kind: "all" };
+  }
+  return { kind: named[0], bound: positiveCount(backfill[named[0]], declaration) };
+}
+
+function textList(value, declaration) {
+  return filled(value, declaration).map((entry, position) =>
+    text(entry, `${declaration}[${position}]`, 512),
+  );
+}
+
+function textArray(value, declaration) {
+  if (!Array.isArray(value)) refuse(declaration);
+  return value.map((entry, position) => text(entry, `${declaration}[${position}]`, 512));
+}
+
+function googleSelectionOf(value, declaration, service) {
+  if (service === "gmail") {
+    const selection = closed(value, ["labels"], declaration);
+    return { labels: textList(selection.labels, `${declaration}.labels`) };
+  }
+  if (service === "calendar") {
+    const selection = closed(value, ["calendars"], declaration);
+    return { calendars: textList(selection.calendars, `${declaration}.calendars`) };
+  }
+  if (service === "drive") {
+    const selection = closed(value, ["files", "folders"], declaration);
+    const files =
+      selection.files === undefined ? [] : textArray(selection.files, `${declaration}.files`);
+    const folders =
+      selection.folders === undefined ? [] : textArray(selection.folders, `${declaration}.folders`);
+    if (files.length + folders.length === 0) refuse(declaration);
+    files.forEach((id, position) => {
+      if (!GOOGLE_DRIVE_ID.test(id)) refuse(`${declaration}.files[${position}]`);
+    });
+    folders.forEach((id, position) => {
+      if (!GOOGLE_DRIVE_ID.test(id)) refuse(`${declaration}.folders[${position}]`);
+    });
+    return { files, folders };
+  }
+  refuse(declaration);
+}
+
+function extractionPath(value, declaration) {
+  const path = text(value, declaration, 512);
+  if (!EXTRACTION_PATH.test(path)) refuse(declaration);
+  return path;
+}
+
+function queryOf(value, declaration) {
+  const query = plain(value, declaration);
+  const parsed = {};
+  for (const [name, entry] of Object.entries(query)) {
+    if (!QUERY_NAME.test(name) || typeof entry !== "string" || entry.length > 2048) {
+      refuse(`${declaration}.${name}`);
+    }
+    parsed[name] = entry;
+  }
+  return parsed;
+}
+
+function declaredServiceOf(value, declaration) {
+  const declared = closed(
+    value,
+    ["host", "path", "query", "page_size", "page_token", "items", "fields", "scopes"],
+    declaration,
+  );
+  const host = text(declared.host, `${declaration}.host`, 253);
+  if (!GOOGLE_API_HOST.test(host)) refuse(`${declaration}.host`);
+  const path = text(declared.path, `${declaration}.path`, 2048);
+  if (!GOOGLE_API_PATH.test(path) || path.includes("..") || path.includes("//")) {
+    refuse(`${declaration}.path`);
+  }
+  const tokens = closed(
+    declared.page_token,
+    ["request", "response", "checkpoint_request", "checkpoint_response"],
+    `${declaration}.page_token`,
+  );
+  const pageToken = {
+    request: text(tokens.request, `${declaration}.page_token.request`, 128),
+    response: extractionPath(tokens.response, `${declaration}.page_token.response`),
+    checkpointRequest: text(
+      tokens.checkpoint_request,
+      `${declaration}.page_token.checkpoint_request`,
+      128,
+    ),
+    checkpointResponse: extractionPath(
+      tokens.checkpoint_response,
+      `${declaration}.page_token.checkpoint_response`,
+    ),
+  };
+  if (
+    !QUERY_NAME.test(pageToken.request) ||
+    !QUERY_NAME.test(pageToken.checkpointRequest) ||
+    pageToken.request === pageToken.checkpointRequest
+  ) {
+    refuse(`${declaration}.page_token`);
+  }
+  const fields = closed(
+    declared.fields,
+    [
+      "native_id",
+      "native_version",
+      "provider_modified_at",
+      "observed_at",
+      "body",
+      "container",
+      "author",
+      "url",
+    ],
+    `${declaration}.fields`,
+  );
+  const pageSize = text(declared.page_size, `${declaration}.page_size`, 128);
+  if (!QUERY_NAME.test(pageSize)) refuse(`${declaration}.page_size`);
+  const scopes = textList(declared.scopes, `${declaration}.scopes`).map((scope, position) => {
+    if (!GOOGLE_API_SCOPE.test(scope)) refuse(`${declaration}.scopes[${position}]`);
+    return scope;
+  });
+  return {
+    host,
+    path,
+    query: queryOf(declared.query, `${declaration}.query`),
+    pageSize,
+    scopes: [...new Set(scopes)],
+    pageToken,
+    items: extractionPath(declared.items, `${declaration}.items`),
+    fields: {
+      nativeId: extractionPath(fields.native_id, `${declaration}.fields.native_id`),
+      nativeVersion:
+        fields.native_version === undefined
+          ? null
+          : extractionPath(fields.native_version, `${declaration}.fields.native_version`),
+      providerModifiedAt:
+        fields.provider_modified_at === undefined
+          ? null
+          : extractionPath(
+              fields.provider_modified_at,
+              `${declaration}.fields.provider_modified_at`,
+            ),
+      observedAt: extractionPath(fields.observed_at, `${declaration}.fields.observed_at`),
+      body: textList(fields.body, `${declaration}.fields.body`).map((path, position) =>
+        extractionPath(path, `${declaration}.fields.body[${position}]`),
+      ),
+      container: extractionPath(fields.container, `${declaration}.fields.container`),
+      author:
+        fields.author === undefined
+          ? null
+          : extractionPath(fields.author, `${declaration}.fields.author`),
+      url:
+        fields.url === undefined ? null : extractionPath(fields.url, `${declaration}.fields.url`),
+    },
+  };
+}
+
+function serviceOf(value, declaration, preset) {
+  const service = closed(
+    value,
+    ["service", "source_ref", "rooms", "backfill", "connector", "selection", "declaration"],
+    declaration,
+  );
+  const name = declaredId(service.service, `${declaration}.service`);
+  if (preset === "custom" && service.connector === undefined) refuse(`${declaration}.connector`);
+  if (preset === "custom" && service.selection !== undefined) refuse(`${declaration}.selection`);
+  if (preset === "custom" && service.declaration !== undefined) refuse(`${declaration}.declaration`);
+  if (preset === "google" && service.connector !== undefined) refuse(`${declaration}.connector`);
+  if (preset === "google" && GOOGLE_CURATED_SERVICES.has(name) && service.declaration !== undefined) {
+    refuse(`${declaration}.declaration`);
+  }
+  if (preset === "google" && !GOOGLE_CURATED_SERVICES.has(name)) {
+    if (service.selection !== undefined) refuse(`${declaration}.selection`);
+    if (service.declaration === undefined) refuse(`${declaration}.declaration`);
+  }
+  return {
+    service: name,
+    sourceRef: text(service.source_ref, `${declaration}.source_ref`, 512),
+    rooms: filled(service.rooms, `${declaration}.rooms`).map((room, position) =>
+      text(room, `${declaration}.rooms[${position}]`, 512),
+    ),
+    backfill: backfillOf(service.backfill, `${declaration}.backfill`),
+    selection:
+      preset === "google" && GOOGLE_CURATED_SERVICES.has(name)
+        ? googleSelectionOf(service.selection, `${declaration}.selection`, name)
+        : null,
+    connector: preset === "custom" ? connectorOf(service.connector, `${declaration}.connector`) : null,
+    declaration:
+      preset === "google" && !GOOGLE_CURATED_SERVICES.has(name)
+        ? declaredServiceOf(service.declaration, `${declaration}.declaration`)
+        : null,
+  };
+}
+
+function instanceOf(value, declaration) {
+  const instance = closed(value, ["id", "preset", "services", "scopes"], declaration);
+  const preset = declaredId(instance.preset, `${declaration}.preset`);
+  if (!PRESETS.has(preset)) refuse(`${declaration}.preset`);
+  if (preset !== "google" && instance.scopes !== undefined) refuse(`${declaration}.scopes`);
+  const scopes =
+    instance.scopes === undefined
+      ? []
+      : textList(instance.scopes, `${declaration}.scopes`).map((scope, position) => {
+          if (!GOOGLE_API_SCOPE.test(scope)) refuse(`${declaration}.scopes[${position}]`);
+          return scope;
+        });
+  const services = filled(instance.services, `${declaration}.services`).map((service, position) =>
+    serviceOf(service, `${declaration}.services[${position}]`, preset),
+  );
+  services.forEach((service, position) => {
+    const first = services.findIndex((candidate) => candidate.service === service.service);
+    if (first !== position) refuse(`${declaration}.services[${position}].service`);
+  });
+  services.forEach((service, position) => {
+    if (
+      service.declaration !== null &&
+      service.declaration.scopes.some((scope) => !scopes.includes(scope))
+    ) {
+      refuse(`${declaration}.services[${position}].declaration.scopes`);
+    }
+  });
+  return {
+    id: declaredId(instance.id, `${declaration}.id`),
+    preset,
+    services,
+    ...(preset === "google" ? { scopes: [...new Set(scopes)] } : {}),
+  };
+}
+
+function absolutePath(value, declaration) {
+  const path = text(value, declaration, 2048);
+  if (!path.startsWith("/")) refuse(declaration);
+  return path;
+}
+
+function ceilingOf(value, declaration) {
+  return value === undefined ? null : positiveCount(value, declaration);
+}
+
+function maximaOf(value, declaration) {
+  if (value === null) return null;
+  const maxima = closed(value, ["cpu_millicores", "memory_bytes", "disk_bytes"], declaration);
+  if (Object.keys(maxima).length === 0) refuse(declaration);
+  return {
+    cpuMillicores: ceilingOf(maxima.cpu_millicores, `${declaration}.cpu_millicores`),
+    memoryBytes: ceilingOf(maxima.memory_bytes, `${declaration}.memory_bytes`),
+    diskBytes: ceilingOf(maxima.disk_bytes, `${declaration}.disk_bytes`),
+  };
+}
+
+function hostOf(value, declaration) {
+  if (value === null) return null;
+  const host = closed(value, ["workspace", "maxima", "image"], declaration);
+  if (host.maxima === undefined) refuse(`${declaration}.maxima`);
+  return {
+    workspace: absolutePath(host.workspace, `${declaration}.workspace`),
+    maxima: maximaOf(host.maxima, `${declaration}.maxima`),
+    image: host.image === undefined || host.image === null ? null : text(host.image, `${declaration}.image`, 255),
+  };
+}
+
+function clientOf(value, declaration) {
+  const client = closed(value, ["kind", "settings"], declaration);
+  const kind = text(client.kind, `${declaration}.kind`, 64);
+  if (!AGENT_CLIENTS.has(kind)) refuse(`${declaration}.kind`);
+  return { kind, settings: absolutePath(client.settings, `${declaration}.settings`) };
+}
+
+export const AVAILABILITY_MODES = ["intermittent", "continuous"];
+
+export function parseConfiguration(document) {
+  const declared = closed(
+    document,
+    [
+      "availability",
+      "execution_authority",
+      "instances",
+      "migrators",
+      "clients",
+      "host",
+    ],
+    "configuration",
+  );
+  if (!AVAILABILITY_MODES.includes(declared.availability)) {
+    refuse("availability");
+  }
+  if (!EXECUTION_AUTHORITIES.includes(declared.execution_authority)) {
+    refuse("execution_authority");
+  }
+  if (!Array.isArray(declared.instances)) refuse("instances");
+  if (!Array.isArray(declared.migrators)) refuse("migrators");
+  const instances = declared.instances.map((instance, position) =>
+    instanceOf(instance, `instances[${position}]`),
+  );
+  instances.forEach((instance, position) => {
+    const first = instances.findIndex((candidate) => candidate.id === instance.id);
+    if (first !== position) refuse(`instances[${position}].id`);
+  });
+  const migrators = declared.migrators.map((migrator, position) =>
+    migratorOf(migrator, `migrators[${position}]`),
+  );
+  migrators.forEach((migrator, position) => {
+    const first = migrators.findIndex((candidate) => candidate.id === migrator.id);
+    if (first !== position) refuse(`migrators[${position}].id`);
+  });
+  if (!Array.isArray(declared.clients)) refuse("clients");
+  const clients = declared.clients.map((client, position) =>
+    clientOf(client, `clients[${position}]`),
+  );
+  clients.forEach((client, position) => {
+    const first = clients.findIndex((candidate) => candidate.settings === client.settings);
+    if (first !== position) refuse(`clients[${position}].settings`);
+  });
+  return {
+    availability: declared.availability,
+    executionAuthority: declared.execution_authority,
+    instances,
+    migrators,
+    clients,
+    host: hostOf(declared.host, "host"),
+  };
+}
+
+export async function readConfiguration(path) {
+  let document;
+  try {
+    document = JSON.parse(await readFile(path, "utf8"));
+  } catch {
+    throw new KitRefusal("kit_configuration_invalid", path);
+  }
+  return parseConfiguration(document);
+}
+
+export function appliedDocument(configuration) {
+  return { availability: configuration.availability };
+}
+
+export function sourceInstance(configuration, id) {
+  const instance = configuration.instances.find((candidate) => candidate.id === id);
+  if (instance === undefined) throw new KitRefusal("kit_instance_unknown", id);
+  return instance;
+}
+
+export function declaredMigrator(configuration, id) {
+  const migrator = configuration.migrators.find((candidate) => candidate.id === id);
+  if (migrator === undefined) throw new KitRefusal("kit_migrator_undeclared", id);
+  return migrator;
+}
+
+export function declaredServices(instance, service) {
+  if (service === null) return instance.services;
+  const named = instance.services.find((candidate) => candidate.service === service);
+  if (named === undefined) throw new KitRefusal("kit_service_unknown", service);
+  return [named];
+}

package/src/connector-login.js

@@ -0,0 +1,91 @@
+import { readConfiguration, sourceInstance } from "./configuration.js";
+import { authorizeCustom, customAuthorizationStatus } from "./custom/authorization.js";
+import { googleAuthorization, authorizeGoogle, GOOGLE_SCOPES } from "./google/oauth.js";
+import { KitRefusal } from "./refusal.js";
+
+function googleServiceScopes(service) {
+  const curated = GOOGLE_SCOPES[service.service];
+  return curated === undefined ? service.declaration.scopes : [curated];
+}
+
+function googleServiceAuthorized(authorization, scopes) {
+  return authorization.grants.some((grant) =>
+    scopes.every((scope) => grant.scopes.includes(scope)),
+  );
+}
+
+function googleConsent(service, context) {
+  return async ({ url }) => {
+    const collected = await context.present(
+      {
+        steps: [
+          { kind: "visit", label: `Sign in to Google and allow access for ${service.service}`, url },
+          {
+            kind: "collect",
+            label: "The address your browser ended on",
+            name: "address",
+            description:
+              "After you allow access, Google sends your browser to a 127.0.0.1 address that does not open. Copy that whole address from the address bar and paste it here.",
+          },
+        ],
+      },
+      context.signal,
+    );
+    return collected.address;
+  };
+}
+
+const CONNECTOR_LOGINS = {
+  custom: {
+    status: customAuthorizationStatus,
+    login: authorizeCustom,
+  },
+  google: {
+    status: async (instance, context) => {
+      const authorization = await googleAuthorization(context.directory, instance.id);
+      if (authorization === null) return false;
+      return instance.services.every((service) =>
+        googleServiceAuthorized(authorization, googleServiceScopes(service)),
+      );
+    },
+    guided: async (instance, context) => {
+      for (const service of instance.services) {
+        try {
+          await authorizeGoogle(
+            {
+              directory: context.directory,
+              instance: instance.id,
+              client: context.dependencies.googleOAuthClient(),
+              scopes: googleServiceScopes(service),
+              approve: googleConsent(service, context),
+            },
+            context.dependencies.googleDependencies ?? {},
+          );
+        } catch (error) {
+          if (context.signal.aborted) return "cancelled";
+          if (error instanceof KitRefusal && error.code === "google_authorization_declined") {
+            return "cancelled";
+          }
+          return "failed";
+        }
+      }
+      return "ready";
+    },
+  },
+};
+
+export function connectorLogin(instance, dependencies = {}) {
+  return { ...CONNECTOR_LOGINS, ...(dependencies.connectorLogins ?? {}) }[instance.preset];
+}
+
+export async function signInConnector(options, dependencies = {}) {
+  const configuration = await readConfiguration(options.configuration);
+  const instance = sourceInstance(configuration, options.instance);
+  const gateway = connectorLogin(instance, dependencies);
+  if (gateway.login === undefined) {
+    throw new KitRefusal("kit_connector_login_guided", `${instance.id} signs in through House setup`);
+  }
+  const context = { directory: options.directory, signal: options.signal };
+  if (await gateway.status(instance, context)) return "skipped";
+  return (await gateway.login(instance, context)) ? "ready" : "needs_attention";
+}