@opengeni/core 0.28.0 → 1.0.0

package/src/domain/github-action-policies.ts

@@ -0,0 +1,169 @@
+import type {
+  GitHubActionPolicyActor,
+  GitHubActionPolicyActorState,
+  GitHubActionPolicyDecision,
+  GitHubActionPolicyEffectiveDecision,
+  GitHubActionPolicyGroup,
+} from "@opengeni/contracts";
+import {
+  listConnectorActionPolicies,
+  resolveConnectorActionPolicy,
+  upsertConnectorActionPolicies,
+  type ConnectorActionPolicySnapshotEntry,
+  type Database,
+} from "@opengeni/db";
+import {
+  GITHUB_REST_MCP_APP_SERVER_ID,
+  GITHUB_REST_MCP_PERSONAL_SERVER_ID,
+  GITHUB_REST_WRITE_TOOL_NAMES,
+} from "@opengeni/runtime/github-rest-mcp";
+
+export const GITHUB_ACTION_POLICY_GROUP_TOOL_NAMES = {
+  routine: GITHUB_REST_WRITE_TOOL_NAMES.filter(
+    (toolName) => toolName !== "pull_request_review_submit" && toolName !== "pull_request_merge",
+  ),
+  review: ["pull_request_review_submit"],
+  merge: ["pull_request_merge"],
+} as const satisfies Record<GitHubActionPolicyGroup, readonly string[]>;
+
+const groupedToolNames = Object.values(GITHUB_ACTION_POLICY_GROUP_TOOL_NAMES).flat();
+if (
+  groupedToolNames.length !== new Set(groupedToolNames).size ||
+  GITHUB_REST_WRITE_TOOL_NAMES.some((toolName) => !groupedToolNames.includes(toolName))
+) {
+  throw new Error("GitHub action policy groups must cover every write tool exactly once");
+}
+
+export type GitHubActionPolicyActorBinding = {
+  actor: GitHubActionPolicyActor;
+  label: string;
+  connectionId: string;
+  serverId: typeof GITHUB_REST_MCP_APP_SERVER_ID | typeof GITHUB_REST_MCP_PERSONAL_SERVER_ID;
+};
+
+function effectiveToolDecision(
+  policies: readonly ConnectorActionPolicySnapshotEntry[],
+  actor: GitHubActionPolicyActorBinding,
+  toolName: string,
+): GitHubActionPolicyDecision {
+  const resolved = resolveConnectorActionPolicy(policies, {
+    connectionId: actor.connectionId,
+    serverId: actor.serverId,
+    toolName,
+    actionName: toolName,
+  });
+  // Match connector_write admission: absent policy inherits repository capability.
+  // This is a policy projection, not a grant of repository or provider access.
+  if (!resolved.managed) return "allow";
+  if (resolved.entry) return resolved.entry.policy;
+  return resolved.decision;
+}
+
+function effectiveGroupDecision(
+  policies: readonly ConnectorActionPolicySnapshotEntry[],
+  actor: GitHubActionPolicyActorBinding,
+  group: GitHubActionPolicyGroup,
+): GitHubActionPolicyEffectiveDecision {
+  const decisions = new Set(
+    GITHUB_ACTION_POLICY_GROUP_TOOL_NAMES[group].map((toolName) =>
+      effectiveToolDecision(policies, actor, toolName),
+    ),
+  );
+  return decisions.size === 1 ? decisions.values().next().value! : "mixed";
+}
+
+export function projectGitHubActionPolicyActor(
+  policies: readonly ConnectorActionPolicySnapshotEntry[],
+  binding: GitHubActionPolicyActorBinding,
+): GitHubActionPolicyActorState {
+  const groups = {
+    routine: effectiveGroupDecision(policies, binding, "routine"),
+    review: effectiveGroupDecision(policies, binding, "review"),
+    merge: effectiveGroupDecision(policies, binding, "merge"),
+  };
+  return binding.actor.kind === "workspace_app"
+    ? {
+        kind: "workspace_app",
+        installationId: binding.actor.installationId,
+        label: binding.label,
+        groups,
+      }
+    : {
+        kind: "personal",
+        connectionId: binding.actor.connectionId,
+        label: binding.label,
+        groups,
+      };
+}
+
+export async function listGitHubActionPolicyActors(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    actors: readonly GitHubActionPolicyActorBinding[];
+  },
+): Promise<GitHubActionPolicyActorState[]> {
+  const policies = await listConnectorActionPolicies(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    connectionIds: input.actors.map((actor) => actor.connectionId),
+  });
+  return input.actors.map((actor) => projectGitHubActionPolicyActor(policies, actor));
+}
+
+export async function updateGitHubActionPolicyGroup(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    subjectId: string;
+    actor: GitHubActionPolicyActorBinding;
+    group: GitHubActionPolicyGroup;
+    decision: GitHubActionPolicyDecision;
+  },
+): Promise<GitHubActionPolicyActorState> {
+  await upsertConnectorActionPolicies(
+    db,
+    GITHUB_ACTION_POLICY_GROUP_TOOL_NAMES[input.group].map((toolName) => ({
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      subjectId: input.subjectId,
+      connectionId: input.actor.connectionId,
+      serverId: input.actor.serverId,
+      toolName,
+      actionName: toolName,
+      policy: input.decision,
+    })),
+  );
+  const policies = await listConnectorActionPolicies(db, {
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    connectionIds: [input.actor.connectionId],
+  });
+  return projectGitHubActionPolicyActor(policies, input.actor);
+}
+
+export function githubAppActionPolicyActor(input: {
+  installationId: number;
+  accountLogin: string | null;
+}): GitHubActionPolicyActorBinding {
+  return {
+    actor: { kind: "workspace_app", installationId: input.installationId },
+    label: input.accountLogin ? `OpenGeni bot on ${input.accountLogin}` : "OpenGeni bot",
+    connectionId: `github-app:${input.installationId}`,
+    serverId: GITHUB_REST_MCP_APP_SERVER_ID,
+  };
+}
+
+export function personalGitHubActionPolicyActor(input: {
+  connectionId: string;
+  githubLogin: string;
+}): GitHubActionPolicyActorBinding {
+  return {
+    actor: { kind: "personal", connectionId: input.connectionId },
+    label: `@${input.githubLogin}`,
+    connectionId: input.connectionId,
+    serverId: GITHUB_REST_MCP_PERSONAL_SERVER_ID,
+  };
+}

package/src/domain/github-repository-bindings.ts

@@ -0,0 +1,295 @@
+import type { RepositoryResourceRef, ResourceRef } from "@opengeni/contracts";
+import {
+  hasAuditableGitHubInstallationAuthority,
+  listGitHubInstallationAccessForWorkspace,
+  type Database,
+} from "@opengeni/db";
+
+/**
+ * GitHub App repository-binding resolution for bare repository resources.
+ *
+ * A repository resource that names a GitHub repository by URI alone (no
+ * `githubInstallationId`/`githubRepositoryId`) never mints an installation
+ * token, so the sandbox clones it anonymously and cannot push or use `gh`.
+ * The workspace allowlist (`github_installation_repositories`) stores only
+ * numeric repository ids, so resolving a URI needs the installation's owner
+ * login from the durable binding plus one provider read for the repository id.
+ * This module owns the pure parts: URI parsing, candidate selection under the
+ * workspace's auditable bindings, and the exactly-one-match stamping rule. The
+ * provider read is injected so the worker can supply the live GitHub lookup
+ * while tests stay deterministic.
+ */
+
+export type GitHubRepositoryCoordinates = { owner: string; name: string };
+
+const GITHUB_OWNER_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/u;
+const GITHUB_NAME_PATTERN = /^[A-Za-z0-9._-]+$/u;
+const GITHUB_HOSTS = new Set(["github.com", "www.github.com"]);
+const GITHUB_SCP_LIKE_PATTERN = /^git@(?:www\.)?github\.com:(.+)$/iu;
+
+function coordinatesFromPath(path: string): GitHubRepositoryCoordinates | null {
+  const segments = path.split("/").filter(Boolean);
+  if (segments.length !== 2) return null;
+  const owner = segments[0]!;
+  const name = segments[1]!.replace(/\.git$/u, "");
+  if (!GITHUB_OWNER_PATTERN.test(owner) || !name || !GITHUB_NAME_PATTERN.test(name)) {
+    return null;
+  }
+  return { owner, name };
+}
+
+/**
+ * Parse a GitHub repository reference into owner/name, else null. Accepts
+ * `https://github.com/<owner>/<repo>[.git][/]`, `www.github.com`,
+ * `ssh://git@github.com/<owner>/<repo>[.git]`, and the scp-like
+ * `git@github.com:<owner>/<repo>[.git]`.
+ */
+export function parseGitHubRepositoryCoordinates(uri: string): GitHubRepositoryCoordinates | null {
+  const trimmed = uri.trim();
+  const scpLike = GITHUB_SCP_LIKE_PATTERN.exec(trimmed);
+  if (scpLike) {
+    return coordinatesFromPath(scpLike[1]!);
+  }
+  let url: URL;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (!GITHUB_HOSTS.has(url.hostname.toLowerCase()) || url.search || url.hash) {
+    return null;
+  }
+  if (url.protocol === "https:" || url.protocol === "http:") {
+    if (url.username || url.password) return null;
+  } else if (url.protocol === "ssh:") {
+    if (url.password || (url.username && url.username !== "git")) return null;
+  } else {
+    return null;
+  }
+  return coordinatesFromPath(url.pathname);
+}
+
+export type UnboundGitHubRepositoryResource = {
+  resource: RepositoryResourceRef;
+  owner: string;
+  name: string;
+};
+
+/**
+ * Repository resources that name a github.com repository without any
+ * platform identity: no GitHub App ids, no credential binding, no personal
+ * connection, and either the explicit `github` provider or no provider at all.
+ * Resources that already carry ids, legacy provider ids, a binding, or a
+ * connection are someone else's authority and are never rewritten here.
+ */
+export function unboundGitHubRepositoryResources(
+  resources: readonly ResourceRef[],
+): UnboundGitHubRepositoryResource[] {
+  const out: UnboundGitHubRepositoryResource[] = [];
+  for (const resource of resources) {
+    if (resource.kind !== "repository") continue;
+    if (resource.provider !== undefined && resource.provider !== "github") continue;
+    if (
+      resource.githubInstallationId !== undefined ||
+      resource.githubRepositoryId !== undefined ||
+      resource.installationId !== undefined ||
+      resource.repositoryId !== undefined ||
+      resource.credentialBindingId !== undefined ||
+      resource.connectionId !== undefined ||
+      resource.connectionType !== undefined
+    ) {
+      continue;
+    }
+    const coordinates = parseGitHubRepositoryCoordinates(resource.uri);
+    if (!coordinates) continue;
+    out.push({ resource, ...coordinates });
+  }
+  return out;
+}
+
+export type GitHubRepositoryBindingCandidate = {
+  installationId: number;
+  accountLogin: string;
+  repositoryIds: number[];
+};
+
+/**
+ * The workspace's auditable GitHub App bindings, under workspace RLS. Only
+ * bindings that could authorize a token mint are candidates; legacy
+ * `unverified` rows never resolve a URI.
+ */
+export async function listGitHubRepositoryBindingCandidates(
+  db: Database,
+  workspaceId: string,
+): Promise<GitHubRepositoryBindingCandidate[]> {
+  const installations = await listGitHubInstallationAccessForWorkspace(db, workspaceId);
+  return installations
+    .filter((installation) => hasAuditableGitHubInstallationAuthority(installation))
+    .map((installation) => ({
+      installationId: installation.installationId,
+      accountLogin: installation.accountLogin ?? "",
+      repositoryIds: [...installation.repositoryIds],
+    }))
+    .filter((candidate) => candidate.accountLogin.length > 0);
+}
+
+export type GitHubRepositoryBindingLookup = (input: {
+  installationId: number;
+  owner: string;
+  name: string;
+}) => Promise<{ id: number } | null>;
+
+export type GitHubRepositoryBinding = { installationId: number; repositoryId: number };
+
+export type GitHubRepositoryBindingOutcome =
+  | { status: "resolved"; binding: GitHubRepositoryBinding }
+  /** No workspace binding owns this repository's account: anonymous, as before. */
+  | { status: "unbound" }
+  /** The account is bound, but no installation's allowlist holds this repository. */
+  | { status: "not_allowlisted"; installationIds: number[] }
+  /** More than one bound installation's allowlist holds this repository. */
+  | { status: "ambiguous"; installationIds: number[] }
+  /** The provider lookup failed (suspended/deleted installation, outage). */
+  | { status: "unavailable"; installationIds: number[]; message: string };
+
+export type GitHubRepositoryBindingResolution = {
+  uri: string;
+  owner: string;
+  name: string;
+  outcome: GitHubRepositoryBindingOutcome;
+};
+
+export type GitHubRepositoryBindingResolutionResult = {
+  resources: ResourceRef[];
+  bindings: Map<string, GitHubRepositoryBinding>;
+  resolutions: GitHubRepositoryBindingResolution[];
+};
+
+/**
+ * Resolve every bare github.com repository resource against the workspace's
+ * auditable bindings. A resource is stamped only when exactly one bound
+ * installation's allowlist contains the repository id GitHub reports for that
+ * URI through that installation. Every other case leaves the resource bare
+ * and reports why, so the caller can surface a warning without ever failing
+ * the turn or the session. Distinct URIs resolve concurrently, as do the
+ * candidate installations of one owner.
+ */
+export async function resolveGitHubRepositoryBindings(input: {
+  resources: readonly ResourceRef[];
+  candidates: readonly GitHubRepositoryBindingCandidate[];
+  lookup: GitHubRepositoryBindingLookup;
+}): Promise<GitHubRepositoryBindingResolutionResult> {
+  const unbound = unboundGitHubRepositoryResources(input.resources);
+  const bindings = new Map<string, GitHubRepositoryBinding>();
+  if (unbound.length === 0) {
+    return { resources: [...input.resources], bindings, resolutions: [] };
+  }
+  const candidatesByLogin = new Map<string, GitHubRepositoryBindingCandidate[]>();
+  for (const candidate of input.candidates) {
+    const key = candidate.accountLogin.toLowerCase();
+    const list = candidatesByLogin.get(key) ?? [];
+    list.push(candidate);
+    candidatesByLogin.set(key, list);
+  }
+  const distinct = new Map<string, UnboundGitHubRepositoryResource>();
+  for (const entry of unbound) {
+    if (!distinct.has(entry.resource.uri)) distinct.set(entry.resource.uri, entry);
+  }
+  const resolutions = await Promise.all(
+    [...distinct.values()].map(async (entry) => ({
+      uri: entry.resource.uri,
+      owner: entry.owner,
+      name: entry.name,
+      outcome: await resolveOne(
+        entry,
+        candidatesByLogin.get(entry.owner.toLowerCase()) ?? [],
+        input.lookup,
+      ),
+    })),
+  );
+  for (const resolution of resolutions) {
+    if (resolution.outcome.status === "resolved") {
+      bindings.set(resolution.uri, resolution.outcome.binding);
+    }
+  }
+  return {
+    resources: applyGitHubRepositoryBindings(input.resources, bindings),
+    bindings,
+    resolutions,
+  };
+}
+
+async function resolveOne(
+  entry: UnboundGitHubRepositoryResource,
+  installations: readonly GitHubRepositoryBindingCandidate[],
+  lookup: GitHubRepositoryBindingLookup,
+): Promise<GitHubRepositoryBindingOutcome> {
+  if (installations.length === 0) {
+    return { status: "unbound" };
+  }
+  const installationIds = installations.map((installation) => installation.installationId);
+  const results = await Promise.allSettled(
+    installations.map(async (installation) => {
+      const found = await lookup({
+        installationId: installation.installationId,
+        owner: entry.owner,
+        name: entry.name,
+      });
+      return found &&
+        Number.isSafeInteger(found.id) &&
+        found.id > 0 &&
+        installation.repositoryIds.includes(found.id)
+        ? { installationId: installation.installationId, repositoryId: found.id }
+        : null;
+    }),
+  );
+  const failure = results.find(
+    (result): result is PromiseRejectedResult => result.status === "rejected",
+  );
+  if (failure) {
+    return {
+      status: "unavailable",
+      installationIds,
+      message: failure.reason instanceof Error ? failure.reason.message : String(failure.reason),
+    };
+  }
+  const matches = results.flatMap((result) =>
+    result.status === "fulfilled" && result.value ? [result.value] : [],
+  );
+  if (matches.length === 1) {
+    return { status: "resolved", binding: matches[0]! };
+  }
+  if (matches.length === 0) {
+    return { status: "not_allowlisted", installationIds };
+  }
+  return {
+    status: "ambiguous",
+    installationIds: matches.map((match) => match.installationId),
+  };
+}
+
+/**
+ * Stamp resolved GitHub App ids onto the matching bare resources of any
+ * resource list (turn resources and runtime resources must agree, because the
+ * credential binding id and token filename derive from the installation id).
+ */
+export function applyGitHubRepositoryBindings(
+  resources: readonly ResourceRef[],
+  bindings: ReadonlyMap<string, GitHubRepositoryBinding>,
+): ResourceRef[] {
+  if (bindings.size === 0) return [...resources];
+  const stampable = new Set(
+    unboundGitHubRepositoryResources(resources).map((entry) => entry.resource),
+  );
+  return resources.map((resource) => {
+    if (resource.kind !== "repository" || !stampable.has(resource)) return resource;
+    const binding = bindings.get(resource.uri);
+    if (!binding) return resource;
+    return {
+      ...resource,
+      provider: "github",
+      githubInstallationId: binding.installationId,
+      githubRepositoryId: binding.repositoryId,
+    };
+  });
+}

package/src/domain/github-skill-source.ts

@@ -0,0 +1,233 @@
+import type { Settings } from "@opengeni/config";
+import { HTTPException } from "hono/http-exception";
+import type { GitHubSkillSourceClient, GitHubSkillTreeEntry } from "./skill-imports";
+import { pinnedFetch, readResponseJsonBounded, readResponseTextBounded } from "@opengeni/network";
+import {
+  PORTABLE_SKILL_MAX_FILES,
+  PORTABLE_SKILL_MAX_FILE_BYTES,
+  PORTABLE_SKILL_MAX_TOTAL_BYTES,
+  type SkillLibraryFile,
+} from "@opengeni/runtime/skill-library";
+
+const githubApiBase = "https://api.github.com";
+const githubRequestTimeoutMs = 15_000;
+const githubMetadataMaxBytes = 4 * 1024 * 1024;
+// GitHub blobs are base64-encoded JSON; allow framing and line wrapping.
+const githubBlobResponseMaxBytes = PORTABLE_SKILL_MAX_FILE_BYTES * 2;
+
+type GitHubJsonRequest = (path: string, maxBytes: number, label: string) => Promise<unknown>;
+
+export function createGitHubSkillSourceClient(
+  settings: Settings,
+  requestJson: GitHubJsonRequest = (path, maxBytes, label) =>
+    githubJson(settings, path, maxBytes, label),
+): GitHubSkillSourceClient {
+  const readJson = requestJson;
+  const cache = new Map<string, { expires: number; payload: unknown }>();
+  const pending = new Map<string, Promise<unknown>>();
+  requestJson = async (path, maxBytes, label) => {
+    const cached = cache.get(path);
+    if (cached && cached.expires > Date.now()) return cached.payload;
+    const existing = pending.get(path);
+    if (existing) return existing;
+    const task = readJson(path, maxBytes, label).then((payload) => {
+      if (cache.size >= 128) cache.delete(cache.keys().next().value!);
+      cache.set(path, {
+        payload,
+        expires: Date.now() + (path.includes("/commits/") ? 60_000 : 3_600_000),
+      });
+      return payload;
+    });
+    pending.set(path, task);
+    try {
+      return await task;
+    } finally {
+      pending.delete(path);
+    }
+  };
+  return {
+    downloadSnapshot: (owner, repository, slug) =>
+      downloadSkillSnapshot(settings, owner, repository, slug),
+    resolveCommit: async (owner, repository, ref) => {
+      const payload = recordValue(
+        await requestJson(
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/commits/${encodeURIComponent(ref)}`,
+          githubMetadataMaxBytes,
+          "GitHub Skill commit",
+        ),
+        "GitHub commit",
+      );
+      const sha = stringValue(payload.sha);
+      if (!sha) throw new Error("GitHub commit response omitted sha");
+      return sha.toLowerCase();
+    },
+    listTree: async (owner, repository, commit) => {
+      const payload = recordValue(
+        await requestJson(
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/git/trees/${encodeURIComponent(commit)}?recursive=1`,
+          githubMetadataMaxBytes,
+          "GitHub Skill tree",
+        ),
+        "GitHub tree",
+      );
+      if (payload.truncated === true) {
+        throw new Error("GitHub repository tree is too large to import safely");
+      }
+      if (!Array.isArray(payload.tree)) throw new Error("GitHub tree response omitted entries");
+      return payload.tree.map((entry, index): GitHubSkillTreeEntry => {
+        const record = recordValue(entry, `GitHub tree entry ${index}`);
+        const path = stringValue(record.path);
+        const type = stringValue(record.type);
+        const mode = stringValue(record.mode);
+        const sha = stringValue(record.sha);
+        const size = record.size;
+        if (
+          !path ||
+          (type !== "blob" && type !== "tree" && type !== "commit") ||
+          !mode ||
+          !sha ||
+          (size !== undefined &&
+            size !== null &&
+            (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0))
+        ) {
+          throw new Error(`GitHub tree entry ${index} is invalid`);
+        }
+        return { path, type, mode, sha, size: typeof size === "number" ? size : null };
+      });
+    },
+    readBlob: async (owner, repository, sha) => {
+      const payload = recordValue(
+        await requestJson(
+          `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repository)}/git/blobs/${encodeURIComponent(sha)}`,
+          githubBlobResponseMaxBytes,
+          "GitHub Skill file",
+        ),
+        "GitHub blob",
+      );
+      if (payload.encoding !== "base64" || typeof payload.content !== "string") {
+        throw new Error("GitHub Skill file did not use base64 encoding");
+      }
+      const normalized = payload.content.replace(/\s+/gu, "");
+      if (!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/u.test(normalized)) {
+        throw new Error("GitHub Skill file contained invalid base64");
+      }
+      const bytes = Uint8Array.from(Buffer.from(normalized, "base64"));
+      if (
+        typeof payload.size === "number" &&
+        Number.isSafeInteger(payload.size) &&
+        payload.size !== bytes.byteLength
+      ) {
+        throw new Error("GitHub Skill file size did not match its payload");
+      }
+      return bytes;
+    },
+  };
+}
+
+async function downloadSkillSnapshot(
+  settings: Settings,
+  owner: string,
+  repository: string,
+  slug: string,
+): Promise<readonly SkillLibraryFile[]> {
+  const signal = AbortSignal.timeout(githubRequestTimeoutMs);
+  const response = await pinnedFetch(
+    `https://skills.sh/api/download/${[owner, repository, slug].map(encodeURIComponent).join("/")}`,
+    { headers: { accept: "application/json" }, credentials: "omit", redirect: "manual", signal },
+    settings,
+    { label: "Skill download", requireHttpsOutsideLocalTest: true },
+  );
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new HTTPException(response.status === 429 ? 429 : 422, {
+      message:
+        response.status === 429
+          ? "skills.sh is busy. Try again shortly."
+          : response.status === 404
+            ? "This skill has no downloadable snapshot. Import its GitHub folder URL instead."
+            : "Could not download this skill from skills.sh. Try again shortly.",
+    });
+  }
+  // JSON escaping may expand the text payload. Artifact validation below applies
+  // the stricter limits to decoded files, paths, and total content size.
+  const payload = recordValue(
+    await readResponseJsonBounded(
+      response,
+      PORTABLE_SKILL_MAX_TOTAL_BYTES * 6 + 128_000,
+      "Skill download",
+      { signal },
+    ),
+    "Skill download",
+  );
+  if (
+    !Array.isArray(payload.files) ||
+    payload.files.length === 0 ||
+    payload.files.length > PORTABLE_SKILL_MAX_FILES
+  ) {
+    throw new HTTPException(422, { message: "The downloaded skill has an invalid file list" });
+  }
+  return payload.files.map((file) => {
+    if (
+      !file ||
+      typeof file !== "object" ||
+      typeof file.path !== "string" ||
+      typeof file.contents !== "string"
+    ) {
+      throw new HTTPException(422, { message: "The downloaded skill contains an invalid file" });
+    }
+    return { path: file.path, content: file.contents };
+  });
+}
+
+async function githubJson(
+  settings: Settings,
+  path: string,
+  maxBytes: number,
+  label: string,
+): Promise<unknown> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), githubRequestTimeoutMs);
+  try {
+    const response = await pinnedFetch(
+      `${githubApiBase}${path}`,
+      {
+        method: "GET",
+        headers: {
+          accept: "application/vnd.github+json",
+          "user-agent": "OpenGeni-Capabilities",
+          "x-github-api-version": "2022-11-28",
+        },
+        signal: controller.signal,
+      },
+      settings,
+      { label, requireHttpsOutsideLocalTest: true },
+    );
+    if (!response.ok) {
+      await readResponseTextBounded(response, 8_192, `${label} error`).catch(() => undefined);
+      if (response.status === 404) throw new Error(`${label} was not found or is not public`);
+      if (response.status === 403 || response.status === 429) {
+        throw new HTTPException(429, {
+          message:
+            "GitHub's public request limit has been reached. Skill search is still available; try previewing again after the limit resets.",
+        });
+      }
+      throw new Error(`${label} failed with HTTP ${response.status}`);
+    }
+    return await readResponseJsonBounded(response, maxBytes, label, {
+      signal: controller.signal,
+    });
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function recordValue(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} response is invalid`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function stringValue(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}