@moondeck/station 0.0.1 → 1.0.0

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/preview-ports.ts

@@ -0,0 +1,85 @@
+import { z } from "zod";
+
+export const PREVIEW_PORT_NAME_RE = /^[a-z0-9][a-z0-9_-]{0,62}$/;
+
+export const PreviewPortDeclarationSchema = z.object({
+  name: z
+    .string()
+    .trim()
+    .min(1)
+    .max(63)
+    .regex(
+      PREVIEW_PORT_NAME_RE,
+      "name must be lowercase letters, digits, _ or -, starting with a letter or digit",
+    ),
+  containerPort: z.coerce.number().int().min(1).max(65535),
+});
+
+export const PreviewPortRuntimeSchema = z.object({
+  name: z.string().trim().min(1).max(63).regex(PREVIEW_PORT_NAME_RE),
+  hostPort: z.coerce.number().int().min(1).max(65535),
+});
+
+export const PreviewPortDeclarationsSchema = z
+  .array(PreviewPortDeclarationSchema)
+  .max(20)
+  .superRefine((ports, ctx) => {
+    const seen = new Set<string>();
+    for (const [index, port] of ports.entries()) {
+      if (seen.has(port.name)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [index, "name"],
+          message: `duplicate preview port name: ${port.name}`,
+        });
+      }
+      seen.add(port.name);
+    }
+  });
+
+export const PreviewPortRuntimesSchema = z
+  .array(PreviewPortRuntimeSchema)
+  .max(20)
+  .superRefine((ports, ctx) => {
+    const seen = new Set<string>();
+    for (const [index, port] of ports.entries()) {
+      if (seen.has(port.name)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          path: [index, "name"],
+          message: `duplicate preview port name: ${port.name}`,
+        });
+      }
+      seen.add(port.name);
+    }
+  });
+
+export type PreviewPortDeclaration = z.infer<
+  typeof PreviewPortDeclarationSchema
+>;
+export type PreviewPortRuntime = z.infer<typeof PreviewPortRuntimeSchema>;
+
+export function parsePreviewPortDeclarations(
+  raw: string | null | undefined,
+): PreviewPortDeclaration[] {
+  return parseJsonList(raw, PreviewPortDeclarationsSchema);
+}
+
+export function parsePreviewPortRuntimes(
+  raw: string | null | undefined,
+): PreviewPortRuntime[] {
+  return parseJsonList(raw, PreviewPortRuntimesSchema);
+}
+
+function parseJsonList<T extends z.ZodTypeAny>(
+  raw: string | null | undefined,
+  schema: T,
+): z.infer<T> {
+  if (!raw) return [];
+  try {
+    const parsed = schema.safeParse(JSON.parse(raw));
+    return parsed.success ? parsed.data : [];
+  } catch {
+    return [];
+  }
+}