@runuai/host 0.9.170 → 0.9.172

package/src/cloud-credentials.ts

@@ -1,3 +1,10 @@
+import { LEASE_PARAMETER_ROOT, BROKER_PARAMETER_ROOT, MAX_CREDENTIAL_ID_CHARS, MAX_PARAMETER_NAME_CHARS, leaseParameterName, brokerParameterName, idPathSegment, parseIdPathSegment, isEngineKind, parseLeaseParameterName, parseBrokerParameterName, sameLocation, isIdValue, isTagValue, type CredentialClass, type CredentialScope, type CredentialLocation } from "./credential-location";
+export * from "./credential-location";
+import { parseCaptureFlowWire, parseCaptureResultWire, type CaptureFlowWire, type CaptureResultWire } from "./capture-wire";
+export * from "./capture-wire";
+import { exactObject, isPositiveInteger, isEpochMs } from "./credential-wire-validation";
+import { parseCustomConnectionMaterial, parseCustomConnectionLease, parseCustomConnectionEnabled, type CustomConnectionMaterial, type CustomConnectionLease, type CustomConnectionCombination } from "./custom-connections";
+export * from "./custom-connections";
 import { MAX_TASK_SECRETS, TASK_SECRET_NAME, TASK_SECRET_STAGING_ID, type TaskSecretManifestEntry } from "./task-secrets";
 
 /**
@@ -55,233 +62,6 @@ export const TASK_MACHINE_CREDENTIALS_V1_ENV = "UAI_TASK_MACHINE_CREDENTIALS_V1"
 // Parameter layout
 // ---------------------------------------------------------------------------
 
-/** What a task may receive: a static key, or an OAuth login's brokered copy. */
-export const LEASE_PARAMETER_ROOT = "/uai/lease";
-/**
- * The full OAuth material only the broker reads. Outside `/uai` altogether:
- * `GetParametersByPath` returns every descendant of a path its caller may
- * read, even one a Deny names, so containment comes from the root alone.
- */
-export const BROKER_PARAMETER_ROOT = "/uai-broker";
-
-export type CredentialClass = "engine" | "mcp" | "github" | "ssh";
-export type CredentialScope = "org" | "user";
-
-/** Where one revision of one credential lives. */
-export interface CredentialLocation {
-  class: CredentialClass;
-  /** `github` and `ssh` are always `user`: one per person. */
-  scope: CredentialScope;
-  /** The org id for `org` scope, the user id for `user` scope. */
-  ownerId: string;
-  /** `engine` only: the engine kind (`codex`, `claude`, …). */
-  engineKind?: string;
-  /** `engine` and `mcp` only: the credential's stable id. */
-  credentialId?: string;
-  /** One immutable revision of the material. */
-  revision: string;
-}
-
-/** SSM allows `[A-Za-z0-9_.-]` in a path segment. An id that already fits,
- *  starts with a letter or digit and has no dot is used as it is; any other
- *  id is `-` followed by the hex of its UTF-8 bytes. No plain id starts with
- *  `-`, so the mapping is injective. Legacy workspace ids
- *  (`personal:<user>`) take the second form. */
-const PLAIN_ID_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
-const ENCODED_ID_SEGMENT = /^-(?:[0-9a-f]{2})+$/;
-const ENGINE_KIND = /^[a-z][a-z0-9-]{0,31}$/;
-export const MAX_CREDENTIAL_ID_CHARS = 128;
-/** SSM's limit for a parameter name, its ARN included. */
-export const MAX_PARAMETER_NAME_CHARS = 1011;
-
-function isIdValue(value: unknown): value is string {
-  return (
-    typeof value === "string" &&
-    value.length > 0 &&
-    value.length <= MAX_CREDENTIAL_ID_CHARS &&
-    !/[\u0000-\u001f\u007f]/.test(value)
-  );
-}
-
-function utf8Hex(value: string): string {
-  let out = "";
-  for (const byte of new TextEncoder().encode(value)) {
-    out += byte.toString(16).padStart(2, "0");
-  }
-  return out;
-}
-
-function fromUtf8Hex(hex: string): string | null {
-  const bytes = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < bytes.length; i++) {
-    bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16);
-  }
-  try {
-    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-  } catch {
-    return null;
-  }
-}
-
-/** The path segment for an id (see `PLAIN_ID_SEGMENT`). Throws on an id no
- *  segment may carry: empty, too long, or containing control characters. */
-export function idPathSegment(id: string): string {
-  if (!isIdValue(id)) throw new Error("invalid credential path id");
-  return PLAIN_ID_SEGMENT.test(id) ? id : `-${utf8Hex(id)}`;
-}
-
-/** Inverse of `idPathSegment`; null for a segment it never produces. */
-export function parseIdPathSegment(segment: string): string | null {
-  if (PLAIN_ID_SEGMENT.test(segment)) {
-    return segment.length <= MAX_CREDENTIAL_ID_CHARS ? segment : null;
-  }
-  if (!ENCODED_ID_SEGMENT.test(segment)) return null;
-  const id = fromUtf8Hex(segment.slice(1));
-  if (id === null || !isIdValue(id) || PLAIN_ID_SEGMENT.test(id)) return null;
-  return id;
-}
-
-export function isEngineKind(value: unknown): value is string {
-  return typeof value === "string" && ENGINE_KIND.test(value);
-}
-
-function locationSegments(location: CredentialLocation): string[] {
-  const owner = location.scope === "org" ? "orgs" : "users";
-  const segments = [owner, idPathSegment(location.ownerId)];
-  switch (location.class) {
-    case "engine": {
-      if (!isEngineKind(location.engineKind)) {
-        throw new Error("invalid engine kind");
-      }
-      if (location.credentialId === undefined) {
-        throw new Error("an engine credential needs its id");
-      }
-      segments.push(
-        "engines",
-        location.engineKind,
-        idPathSegment(location.credentialId),
-      );
-      break;
-    }
-    case "mcp": {
-      if (location.engineKind !== undefined) {
-        throw new Error("an MCP credential has no engine kind");
-      }
-      if (location.credentialId === undefined) {
-        throw new Error("an MCP credential needs its id");
-      }
-      segments.push("mcp", idPathSegment(location.credentialId));
-      break;
-    }
-    case "github":
-    case "ssh": {
-      if (location.scope !== "user") {
-        throw new Error(`${location.class} credentials belong to a user`);
-      }
-      if (
-        location.engineKind !== undefined ||
-        location.credentialId !== undefined
-      ) {
-        throw new Error(`${location.class} has one credential per person`);
-      }
-      segments.push(location.class);
-      break;
-    }
-    default:
-      throw new Error("invalid credential class");
-  }
-  segments.push(idPathSegment(location.revision));
-  return segments;
-}
-
-function nameUnder(root: string, location: CredentialLocation): string {
-  const name = `${root}/${locationSegments(location).join("/")}`;
-  if (name.length > MAX_PARAMETER_NAME_CHARS) {
-    throw new Error("credential parameter name too long");
-  }
-  return name;
-}
-
-/** The lease-readable parameter of one revision. */
-export function leaseParameterName(location: CredentialLocation): string {
-  return nameUnder(LEASE_PARAMETER_ROOT, location);
-}
-
-/** The broker-only parameter of one revision of an OAuth credential. GitHub
- *  tokens and SSH keys are static and have none. */
-export function brokerParameterName(location: CredentialLocation): string {
-  if (location.class === "github" || location.class === "ssh") {
-    throw new Error(`${location.class} credentials have no broker part`);
-  }
-  return nameUnder(BROKER_PARAMETER_ROOT, location);
-}
-
-function parseUnder(root: string, name: string): CredentialLocation | null {
-  if (
-    typeof name !== "string" ||
-    name.length > MAX_PARAMETER_NAME_CHARS ||
-    !name.startsWith(`${root}/`)
-  ) {
-    return null;
-  }
-  const parts = name.slice(root.length + 1).split("/");
-  const [ownerKind, ownerSegment] = parts;
-  const scope: CredentialScope | null =
-    ownerKind === "orgs" ? "org" : ownerKind === "users" ? "user" : null;
-  if (scope === null || ownerSegment === undefined) return null;
-  const ownerId = parseIdPathSegment(ownerSegment);
-  if (ownerId === null) return null;
-  const revisionOf = (segment: string | undefined): string | null =>
-    segment === undefined ? null : parseIdPathSegment(segment);
-
-  if (parts[2] === "engines" && parts.length === 6) {
-    const credentialId = parseIdPathSegment(parts[4]!);
-    const revision = revisionOf(parts[5]);
-    if (!isEngineKind(parts[3]) || credentialId === null || revision === null) {
-      return null;
-    }
-    return {
-      class: "engine",
-      scope,
-      ownerId,
-      engineKind: parts[3],
-      credentialId,
-      revision,
-    };
-  }
-  if (parts[2] === "mcp" && parts.length === 5) {
-    const credentialId = parseIdPathSegment(parts[3]!);
-    const revision = revisionOf(parts[4]);
-    if (credentialId === null || revision === null) return null;
-    return { class: "mcp", scope, ownerId, credentialId, revision };
-  }
-  if (
-    (parts[2] === "github" || parts[2] === "ssh") &&
-    parts.length === 4 &&
-    scope === "user"
-  ) {
-    const revision = revisionOf(parts[3]);
-    if (revision === null) return null;
-    return { class: parts[2], scope, ownerId, revision };
-  }
-  return null;
-}
-
-export function parseLeaseParameterName(
-  name: string,
-): CredentialLocation | null {
-  return parseUnder(LEASE_PARAMETER_ROOT, name);
-}
-
-export function parseBrokerParameterName(
-  name: string,
-): CredentialLocation | null {
-  const location = parseUnder(BROKER_PARAMETER_ROOT, name);
-  return location && (location.class === "engine" || location.class === "mcp")
-    ? location
-    : null;
-}
-
 // ---------------------------------------------------------------------------
 // Lease-readable values
 // ---------------------------------------------------------------------------
@@ -340,6 +120,7 @@ interface LeasedValueBase {
 }
 
 export type LeasedValue =
+  | (LeasedValueBase & { class: "engine"; authKind: "custom-connection"; connection: CustomConnectionMaterial })
   | (LeasedValueBase & { class: "engine"; authKind: "env"; env: Record<string, string> })
   | (LeasedValueBase & {
       class: "engine";
@@ -374,16 +155,6 @@ const FORBIDDEN_HEADER_NAMES = new Set([
   "upgrade",
 ]);
 
-function sameLocation(a: CredentialLocation, b: CredentialLocation): boolean {
-  return (
-    a.class === b.class &&
-    a.scope === b.scope &&
-    a.ownerId === b.ownerId &&
-    a.engineKind === b.engineKind &&
-    a.credentialId === b.credentialId &&
-    a.revision === b.revision
-  );
-}
 
 function parseLocationField(value: unknown): CredentialLocation | null {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
@@ -475,6 +246,10 @@ export function parseLeasedValue(
   switch (location.class) {
     case "engine": {
       const kind = location.engineKind!;
+      if (o.authKind === "custom-connection") {
+        const connection = exactObject(o, ["v", "part", "location", "class", "authKind", "connection"]) ? parseCustomConnectionMaterial(o.connection) : null;
+        return connection && connection.engine === kind ? { ...base, class: "engine", authKind: "custom-connection", connection } : null;
+      }
       if (o.authKind === "env") {
         const env = exactObject(o, ["v", "part", "location", "class", "authKind", "env"])
           ? parseStringMap(o.env, ENGINE_ENV_CREDENTIAL_KEYS[kind] ?? [], 4096)
@@ -559,104 +334,6 @@ export function parseLeasedValue(
 /** Advertised by a sign-in box that writes captures as ADR-154 revisions. */
 export const SIGNIN_BOX_CAPTURE_FLOWS_FEATURE = "signin-box-capture-flows-v1";
 
-/**
- * What the cloud tells the sign-in box to write for one capture: the
- * revision's parameters (the box never chooses a name) and the ids it tags
- * them with. The box checks every field against the others before it writes.
- */
-export interface CaptureFlowWire {
-  credentialId: string;
-  revision: string;
-  leaseParameter: string;
-  /** Null for a static credential. */
-  brokerParameter: string | null;
-  /** The workspace tag: required except for GitHub and SSH. */
-  orgId: string | null;
-  /** The person, for a personal credential. */
-  userId: string | null;
-}
-
-/** What the box answers once both parts are written: never material. */
-export interface CaptureResultWire {
-  credentialId: string;
-  revision: string;
-  /** The lease-readable parameter's Parameter Store version. */
-  leaseVersion: number;
-  /** The access token's expiry when the box could read it. */
-  expiresAt: number | null;
-}
-
-/**
- * A capture flow, rebuilt and checked, with the location its parameters name,
- * or null. The two parameters must name the same credential and revision under
- * their own roots, and the tags must be the parameter's owner: a workspace
- * credential's `orgId` is its owner and it has no `userId`; a personal AI
- * account or MCP connection names both its person and its workspace; GitHub
- * and SSH name their person alone.
- */
-export function parseCaptureFlowWire(
-  value: unknown,
-): (CaptureFlowWire & { location: CredentialLocation }) | null {
-  const o = exactObject(value, [
-    "credentialId",
-    "revision",
-    "leaseParameter",
-    "brokerParameter",
-    "orgId",
-    "userId",
-  ]);
-  if (
-    !o ||
-    !isIdValue(o.credentialId) ||
-    !isIdValue(o.revision) ||
-    typeof o.leaseParameter !== "string" ||
-    !(o.brokerParameter === null || typeof o.brokerParameter === "string") ||
-    !(o.orgId === null || (isIdValue(o.orgId) && isTagValue(o.orgId))) ||
-    !(o.userId === null || (isIdValue(o.userId) && isTagValue(o.userId)))
-  ) {
-    return null;
-  }
-  const location = parseLeaseParameterName(o.leaseParameter);
-  if (!location || location.revision !== o.revision) return null;
-  const isPerson = location.class === "github" || location.class === "ssh";
-  if (!isPerson && location.credentialId !== o.credentialId) return null;
-  if (o.brokerParameter !== null) {
-    const broker = parseBrokerParameterName(o.brokerParameter);
-    if (!broker || !sameLocation(broker, location)) return null;
-  }
-  if (isPerson && o.brokerParameter !== null) return null;
-  const ownerOk =
-    location.scope === "org"
-      ? o.orgId === location.ownerId && o.userId === null
-      : o.userId === location.ownerId && (isPerson ? o.orgId === null : o.orgId !== null);
-  if (!ownerOk) return null;
-  return {
-    credentialId: o.credentialId,
-    revision: o.revision,
-    leaseParameter: o.leaseParameter,
-    brokerParameter: o.brokerParameter,
-    orgId: o.orgId,
-    userId: o.userId,
-    location,
-  };
-}
-
-export function parseCaptureResultWire(value: unknown): CaptureResultWire | null {
-  const o = exactObject(value, ["credentialId", "revision", "leaseVersion", "expiresAt"]);
-  return o &&
-    isIdValue(o.credentialId) &&
-    isIdValue(o.revision) &&
-    isPositiveInteger(o.leaseVersion) &&
-    (o.expiresAt === null || isEpochMs(o.expiresAt))
-    ? {
-        credentialId: o.credentialId,
-        revision: o.revision,
-        leaseVersion: o.leaseVersion,
-        expiresAt: o.expiresAt,
-      }
-    : null;
-}
-
 // ---------------------------------------------------------------------------
 // Session tags
 // ---------------------------------------------------------------------------
@@ -672,15 +349,6 @@ export const LEASE_V1_SESSION_TAG = { key: "lease", value: "v1" } as const;
  *  which resource-tag conditions compare. */
 export const ORG_PATH_SESSION_TAG_KEY = "orgseg";
 
-const TAG_VALUE = /^[\p{L}\p{Z}\p{N}_.:/=+\-@]{1,256}$/u;
-
-/** STS session tag and SSM resource tag values: the same grammar, refused
- *  rather than rewritten, so a principal tag and a resource tag written for
- *  one id always compare equal. */
-export function isTagValue(value: unknown): value is string {
-  return typeof value === "string" && TAG_VALUE.test(value);
-}
-
 // ---------------------------------------------------------------------------
 // The v1 grant and its manifest
 // ---------------------------------------------------------------------------
@@ -734,7 +402,8 @@ export interface LeaseManifestEngine {
   engineKind: string;
   scope: CredentialScope;
   label: string;
-  authKind: "env" | "config-dir";
+  authKind: "env" | "config-dir" | "custom-connection";
+  connection?: CustomConnectionLease;
   /** Position within its scope; the list itself is already in try order. */
   position: number;
 }
@@ -763,6 +432,10 @@ export interface LeaseManifestStatic {
 
 /** What a task may read, by name and version — never a value. */
 export interface CredentialManifest {
+  /** Platform connections.enabled, included in the digest; absent fails closed. */
+  connectionsEnabled?: CustomConnectionCombination[];
+  /** Pins refused by connection policy, never secret material. Omitted if empty. */
+  connectionsUnsupported?: string[];
   /** Omitted on older peers and when empty, preserving old digests. */
   taskSecrets?: TaskSecretManifestEntry[];
   /** The task's projects, lead first. */
@@ -956,22 +629,6 @@ export interface CredentialsActivatedFrame {
 
 type WireObject = Record<string, unknown>;
 
-function exactObject(
-  value: unknown,
-  required: readonly string[],
-  optional: readonly string[] = [],
-): WireObject | null {
-  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
-  const object = value as WireObject;
-  const keys = Object.keys(object);
-  if (
-    keys.some(key => !required.includes(key) && !optional.includes(key)) ||
-    required.some((key) => !Object.hasOwn(object, key))
-  ) {
-    return null;
-  }
-  return object;
-}
 
 function isBoundedString(value: unknown, max: number): value is string {
   return typeof value === "string" && value.length > 0 && value.length <= max;
@@ -981,17 +638,13 @@ function isOpId(value: unknown): value is string {
   return isBoundedString(value, MAX_LEASE_OP_ID_CHARS) && OP_ID.test(value);
 }
 
-function isPositiveInteger(value: unknown): value is number {
-  return Number.isSafeInteger(value) && (value as number) > 0;
-}
+
 
 function isNonNegativeInteger(value: unknown): value is number {
   return Number.isSafeInteger(value) && (value as number) >= 0;
 }
 
-function isEpochMs(value: unknown): value is number {
-  return isPositiveInteger(value);
-}
+
 
 function isScope(value: unknown): value is CredentialScope {
   return value === "org" || value === "user";
@@ -1058,7 +711,7 @@ function parseEngine(
     "label",
     "authKind",
     "position",
-  ]);
+  ], ["connection"]);
   if (
     !o ||
     !isIdValue(o.credentialId) ||
@@ -1071,11 +724,13 @@ function parseEngine(
     !isEngineKind(o.engineKind) ||
     !isScope(o.scope) ||
     !isBoundedString(o.label, MAX_MANIFEST_LABEL_CHARS) ||
-    (o.authKind !== "env" && o.authKind !== "config-dir") ||
+    (o.authKind !== "env" && o.authKind !== "config-dir" && o.authKind !== "custom-connection") ||
     !isNonNegativeInteger(o.position)
   ) {
     return null;
   }
+  const connection = o.connection === undefined ? undefined : parseCustomConnectionLease(o.connection, o.engineKind);
+  if (connection === null || ((o.authKind === "custom-connection") !== (connection !== undefined)) || (connection && (connection.expiresAt ?? null) !== o.expiresAt)) return null;
   const location = parseLeaseParameterName(o.parameter);
   if (
     !location ||
@@ -1100,6 +755,7 @@ function parseEngine(
     label: o.label,
     authKind: o.authKind,
     position: o.position,
+    ...(connection ? { connection } : {}),
   };
 }
 
@@ -1243,7 +899,7 @@ function parseManifest(
   grant: { orgId: string; userId: string; taskId: string },
   credentialSessions: ReadonlySet<string>,
 ): CredentialManifest | null {
-  const o = exactObject(value, ["projects", "engines", "mcp", "github", "ssh"], ["taskSecrets"]);
+  const o = exactObject(value, ["projects", "engines", "mcp", "github", "ssh"], ["taskSecrets", "connectionsEnabled", "connectionsUnsupported"]);
   if (
     !o ||
     !Array.isArray(o.projects) ||
@@ -1255,6 +911,14 @@ function parseManifest(
   ) {
     return null;
   }
+  const connectionsEnabled = o.connectionsEnabled === undefined ? undefined : parseCustomConnectionEnabled(o.connectionsEnabled);
+  if (connectionsEnabled === null) return null;
+  const connectionsUnsupported = o.connectionsUnsupported;
+  if (connectionsUnsupported !== undefined && (!Array.isArray(connectionsUnsupported) ||
+    connectionsUnsupported.length === 0 || connectionsUnsupported.length > MAX_MANIFEST_ENGINES ||
+    !connectionsUnsupported.every(isIdValue) || new Set(connectionsUnsupported).size !== connectionsUnsupported.length)) return null;
+  const customManifest = { ...(connectionsEnabled ? { connectionsEnabled } : {}),
+    ...(connectionsUnsupported ? { connectionsUnsupported: [...connectionsUnsupported] as string[] } : {}) };
   const projects: LeaseManifestProject[] = [];
   for (const item of o.projects) {
     const p = exactObject(item, ["projectId", "sessionId"]);
@@ -1316,9 +980,9 @@ function parseManifest(
       entries.push(e as unknown as TaskSecretManifestEntry);
     }
     if (!uniqueBy(entries, e => e.name)) return null;
-    return { projects, engines, mcp, github, ssh, taskSecrets: entries };
+    return { projects, engines, mcp, github, ssh, taskSecrets: entries, ...customManifest };
   }
-  return { projects, engines, mcp, github, ssh };
+  return { projects, engines, mcp, github, ssh, ...customManifest };
 }
 
 function parseFiles(value: unknown): LeaseFiles | null {