@runuai/host 0.9.149 → 0.9.151

package/lib/person-capture.ts

@@ -0,0 +1,327 @@
+/**
+ * ADR-154 §12 on the sign-in box: a person's GitHub sign-in and SSH key as
+ * revisions, the repository picker reading the exact revision the cloud
+ * names, and the revocation of a retired GitHub token.
+ *
+ * - GitHub: the cloud's callback obtained the token; the box writes it as the
+ *   revision the cloud named and answers with the name and version.
+ * - SSH: the box mints the key in memory, writes the private half to the
+ *   revision's parameter (its public half as a tag) and answers with the
+ *   public half. Nothing touches the box's disk. A mint retried for a
+ *   revision that already holds a key answers that key's public half, never
+ *   the one it just made, so the cloud always shows the key tasks use.
+ * - Each write ends at a deadline inside the cloud's answer deadline: the
+ *   AWS CLI is killed then, so nothing the cloud gave up on is sent later.
+ * - The box reads a GitHub revision back only to list the person's
+ *   installations and repositories for the picker, and to revoke a retired
+ *   token at GitHub with the App's client id and secret, which ride the
+ *   revoke frame and are kept nowhere.
+ */
+
+import { generateKeyPairSync, randomBytes } from "node:crypto";
+
+import {
+  isGithubToken,
+  isPersonGithubParameter,
+  parseLeaseParameterName,
+  parseLeasedValue,
+  serializeLeasedValue,
+  type CaptureResultWire,
+  type GithubCaptureFrame,
+  type GithubRevokeAckFrame,
+  type GithubRevokeFrame,
+  type PersonCaptureAckFrame,
+  type SshMintFrame,
+} from "../src/cloud-credentials";
+import { captureTags, parseCaptureFlow, writeCapture, type ParsedCaptureFlow } from "./capture-flow";
+import { ImmutableParameterConflictError, storeFailureKind, type CredentialStore } from "./credential-store";
+import { githubApiOrigin } from "./github-origin";
+
+export type PersonCaptureAnswer = Omit<PersonCaptureAckFrame, "kind" | "opId">;
+export type GithubRevokeAnswer = Omit<GithubRevokeAckFrame, "kind" | "opId">;
+
+/** One step's whole budget, inside the cloud's 30-second answer deadline. */
+export const PERSON_STEP_DEADLINE_MS = 25_000;
+/** The tag an SSH revision's public half rides on: the key blob, base64. */
+export const SSH_PUBLIC_KEY_TAG = "uai_ssh_public_key";
+
+function refused(error: string): PersonCaptureAnswer {
+  return { capture: null, publicKey: null, error };
+}
+
+function tookTooLong(): PersonCaptureAnswer {
+  return refused("The sign-in box took too long; nothing usable was kept. Try again.");
+}
+
+async function writePerson(
+  store: CredentialStore,
+  flow: ParsedCaptureFlow,
+  lease: string,
+  signal: AbortSignal,
+  leaseTags?: Record<string, string>,
+): Promise<CaptureResultWire> {
+  return writeCapture(store, flow, { lease, broker: null, expiresAt: null, leaseTags }, { signal });
+}
+
+/** Write the GitHub token the cloud's callback obtained as this revision. */
+export async function captureGithub(
+  frame: GithubCaptureFrame,
+  deps: { store: CredentialStore | null; deadlineMs?: number },
+): Promise<PersonCaptureAnswer> {
+  const flow = parseCaptureFlow(frame.flow);
+  if (!flow || flow.location.class !== "github" || flow.brokerParameter !== null) {
+    return refused("The sign-in's destination is invalid; nothing was kept.");
+  }
+  if (!deps.store) return refused("The sign-in box has no credential store.");
+  const signal = AbortSignal.timeout(deps.deadlineMs ?? PERSON_STEP_DEADLINE_MS);
+  try {
+    // A retry for this revision carries the same token: the cloud's callback
+    // spends its state once, so one revision never meets two sign-ins.
+    const capture = await writePerson(
+      deps.store,
+      flow,
+      serializeLeasedValue({ v: 1, part: "lease", location: flow.location, class: "github", token: frame.token }),
+      signal,
+    );
+    return { capture, publicKey: null, error: null };
+  } catch (err) {
+    if (signal.aborted) return tookTooLong();
+    console.warn(`[person-capture] github ${flow.credentialId}/${flow.revision}: write failed (${storeFailureKind(err)})`);
+    return refused("The credential store refused the write; nothing was kept.");
+  }
+}
+
+/** Mint an SSH key as this revision. */
+export async function mintSsh(
+  frame: SshMintFrame,
+  deps: { store: CredentialStore | null; keygen?: (comment: string) => OpenSshKeyPair; deadlineMs?: number },
+): Promise<PersonCaptureAnswer> {
+  const flow = parseCaptureFlow(frame.flow);
+  if (!flow || flow.location.class !== "ssh" || flow.brokerParameter !== null) {
+    return refused("The key's destination is invalid; nothing was kept.");
+  }
+  if (!deps.store) return refused("The sign-in box has no credential store.");
+  const signal = AbortSignal.timeout(deps.deadlineMs ?? PERSON_STEP_DEADLINE_MS);
+  const comment = sshComment(flow);
+  let key: OpenSshKeyPair;
+  try {
+    key = (deps.keygen ?? openSshEd25519)(comment);
+  } catch (err) {
+    console.warn(`[person-capture] ssh ${flow.credentialId}/${flow.revision}: no key was made (${storeFailureKind(err)})`);
+    return refused("The sign-in box could not make a key; nothing was kept.");
+  }
+  try {
+    const capture = await writePerson(
+      deps.store,
+      flow,
+      serializeLeasedValue({
+        v: 1,
+        part: "lease",
+        location: flow.location,
+        class: "ssh",
+        privateKey: key.privateKey,
+        publicKey: key.publicKey,
+      }),
+      signal,
+      { [SSH_PUBLIC_KEY_TAG]: publicKeyBlob(key.publicKey) },
+    );
+    return { capture, publicKey: key.publicKey, error: null };
+  } catch (err) {
+    if (signal.aborted) return tookTooLong();
+    if (err instanceof ImmutableParameterConflictError) {
+      // This revision already holds a key (an earlier attempt whose answer
+      // was lost): answer its public half. The key just made is dropped.
+      // Under the mint's own deadline: the recovery is part of the step.
+      const earlier = await keyAlreadyMinted(deps.store, flow, signal).catch(() => null);
+      if (signal.aborted) return tookTooLong();
+      if (earlier) {
+        return {
+          capture: { credentialId: flow.credentialId, revision: flow.revision, leaseVersion: 1, expiresAt: null },
+          publicKey: `ssh-ed25519 ${earlier} ${comment}`,
+          error: null,
+        };
+      }
+    }
+    console.warn(`[person-capture] ssh ${flow.credentialId}/${flow.revision}: write failed (${storeFailureKind(err)})`);
+    return refused("The credential store refused the write; nothing was kept.");
+  }
+}
+
+function sshComment(flow: ParsedCaptureFlow): string {
+  return `uai-${flow.location.ownerId}`;
+}
+
+/** The base64 key blob of an `ssh-ed25519 <blob> <comment>` line. */
+function publicKeyBlob(publicKey: string): string {
+  return publicKey.split(" ")[1] ?? "";
+}
+
+/** The key blob an SSH revision's parameter already carries, when that
+ *  parameter is exactly this revision's (every identity tag agrees) and
+ *  the blob is an ed25519 public key; null otherwise. Metadata only. */
+async function keyAlreadyMinted(
+  store: CredentialStore,
+  flow: ParsedCaptureFlow,
+  signal: AbortSignal,
+): Promise<string | null> {
+  const observed = await store.listTags(flow.leaseParameter, { signal });
+  for (const [tag, value] of Object.entries(captureTags(flow, "lease"))) {
+    if (observed[tag] !== value) return null;
+  }
+  const blob = observed[SSH_PUBLIC_KEY_TAG];
+  return typeof blob === "string" && isEd25519Blob(blob) ? blob : null;
+}
+
+function isEd25519Blob(blob: string): boolean {
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(blob)) return false;
+  const bytes = Buffer.from(blob, "base64");
+  const type = Buffer.from("ssh-ed25519");
+  return (
+    bytes.length === 4 + type.length + 4 + 32 &&
+    bytes.readUInt32BE(0) === type.length &&
+    bytes.subarray(4, 4 + type.length).equals(type) &&
+    bytes.readUInt32BE(4 + type.length) === 32
+  );
+}
+
+/**
+ * The token of the GitHub revision at `parameter`, which must be this
+ * person's: null when it is not there. Throws when the store cannot answer,
+ * so "could not read" is never taken for "signed out".
+ */
+export async function readGithubRevision(
+  store: CredentialStore,
+  parameter: string,
+  userId: string,
+  signal?: AbortSignal,
+): Promise<string | null> {
+  if (!isPersonGithubParameter(parameter, userId)) {
+    throw new Error("the revision named is not this person's GitHub sign-in");
+  }
+  const raw = await store.get(parameter, { signal });
+  if (raw === null) return null;
+  const location = parseLeaseParameterName(parameter)!;
+  const value = parseLeasedValue(raw, location);
+  if (!value || value.class !== "github") throw new Error("the GitHub revision is malformed");
+  return value.token;
+}
+
+/**
+ * Revoke a retired revision's token at GitHub. `absent` when the parameter
+ * is gone or GitHub no longer knows the token; `retry` for anything that
+ * might pass later. The answer never carries the token.
+ */
+export async function revokeGithub(
+  frame: GithubRevokeFrame,
+  deps: { store: CredentialStore | null; fetch?: typeof fetch; apiOrigin?: string; deadlineMs?: number },
+): Promise<GithubRevokeAnswer> {
+  if (!deps.store) return { outcome: "retry", error: "the sign-in box has no credential store" };
+  const location = parseLeaseParameterName(frame.parameter);
+  if (!location || location.class !== "github") {
+    return { outcome: "retry", error: "the revision named is not a GitHub sign-in" };
+  }
+  // One deadline over the whole revocation, the read and GitHub's answer
+  // together, inside the cloud's own: never two bounds stacked.
+  const signal = AbortSignal.timeout(deps.deadlineMs ?? PERSON_STEP_DEADLINE_MS);
+  let token: string | null;
+  try {
+    token = await readGithubRevision(deps.store, frame.parameter, location.ownerId, signal);
+  } catch (err) {
+    // The detail stays in the box's log; the cloud gets a fixed message.
+    console.warn(`[person-capture] revoke ${frame.parameter}: read failed (${storeFailureKind(err)})`);
+    return { outcome: "retry", error: "could not read the revision" };
+  }
+  if (token === null || !isGithubToken(token)) return { outcome: "absent", error: null };
+  const origin = deps.apiOrigin ?? githubApiOrigin();
+  const basic = Buffer.from(`${frame.clientId}:${frame.clientSecret}`).toString("base64");
+  let res: Response;
+  try {
+    res = await (deps.fetch ?? fetch)(`${origin}/applications/${encodeURIComponent(frame.clientId)}/token`, {
+      method: "DELETE",
+      headers: {
+        authorization: `Basic ${basic}`,
+        accept: "application/vnd.github+json",
+        "content-type": "application/json",
+        "user-agent": "uai-signin-box",
+        "x-github-api-version": "2022-11-28",
+      },
+      body: JSON.stringify({ access_token: token }),
+      redirect: "error",
+      signal,
+    });
+  } catch (err) {
+    console.warn(`[person-capture] revoke ${frame.parameter}: GitHub did not answer (${storeFailureKind(err)})`);
+    return { outcome: "retry", error: "GitHub did not answer" };
+  }
+  // Only the status matters; GitHub's words are not read, let alone relayed.
+  void res.body?.cancel().catch(() => {});
+  // 204: revoked. 404: GitHub knows no such token (revoked, expired, or its
+  // grant was removed): the same end state.
+  if (res.status === 204) return { outcome: "revoked", error: null };
+  if (res.status === 404) return { outcome: "absent", error: null };
+  return { outcome: "retry", error: `GitHub answered HTTP ${res.status}` };
+}
+
+
+
+// ---------------------------------------------------------------------------
+// An ed25519 key in OpenSSH's own formats, made in memory.
+// ---------------------------------------------------------------------------
+
+export interface OpenSshKeyPair {
+  /** `-----BEGIN OPENSSH PRIVATE KEY-----`, unencrypted. */
+  privateKey: string;
+  /** `ssh-ed25519 <base64> <comment>`. */
+  publicKey: string;
+}
+
+function sshString(bytes: Buffer): Buffer {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(bytes.length);
+  return Buffer.concat([length, bytes]);
+}
+
+function sshUint32(value: number): Buffer {
+  const out = Buffer.alloc(4);
+  out.writeUInt32BE(value >>> 0);
+  return out;
+}
+
+/**
+ * The openssh-key-v1 container (PROTOCOL.key in OpenSSH) for one unencrypted
+ * ed25519 key: what `ssh-keygen -t ed25519 -N ""` writes, without a file.
+ */
+export function openSshEd25519(comment: string): OpenSshKeyPair {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const pub = Buffer.from(publicKey.export({ format: "jwk" }).x!, "base64url");
+  const seed = Buffer.from(privateKey.export({ format: "jwk" }).d!, "base64url");
+  const keyType = Buffer.from("ssh-ed25519");
+  const publicBlob = Buffer.concat([sshString(keyType), sshString(pub)]);
+  const check = randomBytes(4).readUInt32BE();
+  let secret = Buffer.concat([
+    sshUint32(check),
+    sshUint32(check),
+    sshString(keyType),
+    sshString(pub),
+    // OpenSSH stores the 32-byte seed followed by the public key.
+    sshString(Buffer.concat([seed, pub])),
+    sshString(Buffer.from(comment)),
+  ]);
+  const padding: number[] = [];
+  for (let i = 1; (secret.length + padding.length) % 8 !== 0; i += 1) padding.push(i);
+  secret = Buffer.concat([secret, Buffer.from(padding)]);
+  const body = Buffer.concat([
+    Buffer.from("openssh-key-v1\0"),
+    sshString(Buffer.from("none")),
+    sshString(Buffer.from("none")),
+    sshString(Buffer.alloc(0)),
+    sshUint32(1),
+    sshString(publicBlob),
+    sshString(secret),
+  ]);
+  const lines = body.toString("base64").match(/.{1,70}/g) ?? [];
+  return {
+    privateKey: ["-----BEGIN OPENSSH PRIVATE KEY-----", ...lines, "-----END OPENSSH PRIVATE KEY-----", ""].join("\n"),
+    publicKey: `ssh-ed25519 ${publicBlob.toString("base64")} ${comment}`,
+  };
+}

package/lib/project-env-legacy-tags.ts

@@ -0,0 +1,130 @@
+/**
+ * ADR-154 §9: the sign-in box tags pinned legacy env parameters.
+ *
+ * ADR-153's backfill pinned `<prefix>/projects/<projectId>/env/<KEY>` by
+ * version and LastModifiedDate without checking its tags, and a v1 lease
+ * reads `/uai/projects/*` only where the `org` tag is the task's workspace.
+ * The box puts the project's `org` and `project` tags on each parameter the
+ * cloud names and reads them back, with `ssm:AddTagsToResource` and
+ * `ssm:ListTagsForResource`, which its policy already grants on
+ * `/uai/projects/*`. It never reads a value; the cloud checks each pin,
+ * before and after, from its own metadata reads.
+ */
+
+import {
+  isProjectEnvLegacyTagFrame,
+  type ProjectEnvLegacyTagAckFrame,
+  type ProjectEnvLegacyTagFrame,
+  type ProjectEnvLegacyTagOutcome,
+} from "../src/protocol";
+import {
+  CredentialStoreCommandError,
+  configuredCredentialStore,
+  credentialStorePrefix,
+  parameterName,
+  type CredentialStore,
+} from "./credential-store";
+import { PROJECT_ENV_STAGING_TAGS } from "./project-env-staging";
+
+/** A frame starts no key after this; the rest are asked again. With one
+ *  key's two CLI calls after it (30 seconds each at most), the answer still
+ *  reaches the cloud inside its 90-second wait (lib/host-bridge.ts), and a
+ *  managed restart, which waits for drained work, waits that long at most. */
+export const LEGACY_TAG_BUDGET_MS = 20_000;
+
+/** AWS's answers for a parameter that is not there. */
+const MISSING_CODES = new Set(["InvalidResourceId", "ParameterNotFound"]);
+/** AWS will put no more tags on it: nothing a retry changes. */
+const REFUSED_CODES = new Set(["TooManyTagsError"]);
+
+/** The legacy layout's name for one key, as the cloud's
+ *  `projectEnvCloudLegacyParameterName` writes it. */
+export function projectEnvLegacyParameterName(
+  projectId: string,
+  key: string,
+  prefix = credentialStorePrefix(),
+): string {
+  return parameterName(prefix, "projects", projectId, "env", key);
+}
+
+async function tagOne(
+  store: CredentialStore,
+  name: string,
+  tags: Record<string, string>,
+): Promise<ProjectEnvLegacyTagOutcome> {
+  try {
+    await store.tag(name, tags);
+    // Tags are eventually consistent: one not read back yet is a retry, and
+    // tagging again is harmless.
+    const read = await store.listTags(name);
+    return Object.entries(tags).every(([key, value]) => read[key] === value) ? "tagged" : "retry";
+  } catch (error) {
+    const code = error instanceof CredentialStoreCommandError ? error.awsCode : null;
+    if (code !== null && MISSING_CODES.has(code)) return "missing";
+    if (code !== null && REFUSED_CODES.has(code)) return "refused";
+    return "retry";
+  }
+}
+
+export interface ProjectEnvLegacyTagOptions {
+  store?: CredentialStore | null;
+  prefix?: string;
+  now?: () => number;
+  /** When the frame arrived: its budget runs from there. */
+  startedAt?: number;
+  budgetMs?: number;
+  stopping?: () => boolean;
+}
+
+/** Tag each named parameter in turn; one key's failure is its own. Keys
+ *  past the budget, or after the host begins shutting down, are asked again
+ *  without a call. */
+export async function tagProjectEnvLegacyParameters(
+  frame: ProjectEnvLegacyTagFrame,
+  options: ProjectEnvLegacyTagOptions = {},
+): Promise<ProjectEnvLegacyTagAckFrame["results"]> {
+  if (!isProjectEnvLegacyTagFrame(frame)) {
+    throw new Error("invalid legacy environment tag request");
+  }
+  const store = Object.prototype.hasOwnProperty.call(options, "store")
+    ? options.store
+    : configuredCredentialStore();
+  if (!store) return frame.keys.map((key) => ({ key, outcome: "retry" }));
+  const prefix = options.prefix ?? credentialStorePrefix();
+  const tags = {
+    [PROJECT_ENV_STAGING_TAGS.org]: frame.orgId,
+    [PROJECT_ENV_STAGING_TAGS.project]: frame.projectId,
+  };
+  const now = options.now ?? Date.now;
+  const startedAt = options.startedAt ?? now();
+  const budgetMs = options.budgetMs ?? LEGACY_TAG_BUDGET_MS;
+  const results: ProjectEnvLegacyTagAckFrame["results"] = [];
+  for (const key of frame.keys) {
+    if (now() - startedAt >= budgetMs || options.stopping?.() === true) {
+      results.push({ key, outcome: "retry" });
+      continue;
+    }
+    const name = projectEnvLegacyParameterName(frame.projectId, key, prefix);
+    results.push({ key, outcome: await tagOne(store, name, tags) });
+  }
+  return results;
+}
+
+let queue: Promise<unknown> = Promise.resolve();
+
+/**
+ * One frame at a time, in arrival order: a frame whose key stalled in a CLI
+ * call (its budget stops it starting more, not the call it is in) cannot
+ * land its tags after a later frame's, which may name another workspace or
+ * have been read back already. A frame that waited out its budget in line
+ * answers at once, each key asked again.
+ */
+export function queueProjectEnvLegacyTag(
+  frame: ProjectEnvLegacyTagFrame,
+  options: ProjectEnvLegacyTagOptions = {},
+): Promise<ProjectEnvLegacyTagAckFrame["results"]> {
+  const startedAt = options.startedAt ?? (options.now ?? Date.now)();
+  const run = queue.then(() => tagProjectEnvLegacyParameters(frame, { ...options, startedAt }));
+  queue = run.catch(() => undefined);
+  return run;
+}