@opengeni/contracts 0.44.1 → 1.0.0

package/src/connection-authority.ts

@@ -0,0 +1,213 @@
+import { z } from "zod";
+import { ConnectionKind, SessionTenancyVisibility } from "./index";
+
+export const ConnectionAuthoritySelectionSource = z.enum(["explicit_workspace", "sender"]);
+export type ConnectionAuthoritySelectionSource = z.infer<typeof ConnectionAuthoritySelectionSource>;
+
+export const ConnectionUseSelectionSource = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z0-9](?:[a-z0-9._:-]*[a-z0-9])?$/u);
+export type ConnectionUseSelectionSource = z.infer<typeof ConnectionUseSelectionSource>;
+
+const AcceptedConnectionWork = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("turn"),
+      turnId: z.string().uuid(),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("scheduled_task"),
+      taskId: z.string().uuid(),
+      taskAuthorityRevision: z.number().int().positive(),
+      runId: z.string().uuid(),
+    })
+    .strict(),
+]);
+
+/**
+ * Internal, credential-free authority frozen when work is accepted. Personal
+ * owner identity is retained only for live authorization and usage/audit
+ * attribution; it is never part of the public delegation envelope.
+ */
+export const ConnectionUseAuthoritySnapshot = z
+  .object({
+    organizationId: z.string().uuid(),
+    originWorkspaceId: z.string().uuid(),
+    targetWorkspaceId: z.string().uuid(),
+    targetSessionId: z.string().uuid(),
+    targetSessionVisibility: SessionTenancyVisibility,
+    targetSessionAuthorityEpoch: z.number().int().positive(),
+    acceptedWork: AcceptedConnectionWork,
+    connectionId: z.string().uuid(),
+    connectionGeneration: z.number().int().positive(),
+    connectionStatus: z.literal("active"),
+    providerDomain: z.string().min(1).max(2048),
+    connectionKind: ConnectionKind,
+    scope: z.enum(["workspace", "user"]),
+    ownerSubjectId: z.string().min(1).max(512).nullable(),
+    ownerOrganizationMembershipId: z.string().uuid().nullable(),
+    ownerMembershipAuthorizationRevision: z.number().int().positive().nullable().default(null),
+    authoritySource: ConnectionAuthoritySelectionSource,
+    selectionSources: z.array(ConnectionUseSelectionSource).min(1).max(128),
+    userDelegation: z.null(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    const ownedBySubject = value.scope !== "workspace";
+    const delegated = value.scope === "user";
+    if (ownedBySubject !== (value.ownerSubjectId !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["ownerSubjectId"],
+        message: "personal connections retain an owner subject",
+      });
+    }
+    if (delegated !== (value.ownerOrganizationMembershipId !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["ownerOrganizationMembershipId"],
+        message: "only user connections retain an owner membership",
+      });
+    }
+    if (delegated !== (value.ownerMembershipAuthorizationRevision !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["ownerMembershipAuthorizationRevision"],
+        message: "only user connections retain an owner membership revision",
+      });
+    }
+    if (delegated && value.authoritySource !== "sender") {
+      context.addIssue({
+        code: "custom",
+        path: ["authoritySource"],
+        message: "user connections require authenticated sender provenance",
+      });
+    }
+    if (!delegated && value.authoritySource === "sender") {
+      context.addIssue({
+        code: "custom",
+        path: ["authoritySource"],
+        message: "workspace connections cannot claim sender provenance",
+      });
+    }
+    if (!delegated && value.originWorkspaceId !== value.targetWorkspaceId) {
+      context.addIssue({
+        code: "custom",
+        path: ["originWorkspaceId"],
+        message: "workspace connections must be owned by the target workspace",
+      });
+    }
+  });
+export type ConnectionUseAuthoritySnapshot = z.infer<typeof ConnectionUseAuthoritySnapshot>;
+
+export const ConnectionUseDenialReason = z.enum([
+  "tenant_mismatch",
+  "workspace_access_inactive",
+  "session_inactive",
+  "session_identity_changed",
+  "session_visibility_changed",
+  "session_authority_epoch_changed",
+  "accepted_attempt_authority_required",
+  "accepted_snapshot_digest_changed",
+  "connection_missing",
+  "connection_identity_changed",
+  "connection_generation_changed",
+  "connection_status_inactive",
+  "connection_owner_changed",
+  "owner_membership_inactive",
+  "authority_missing",
+  "authority_identity_changed",
+  "authority_generation_changed",
+  "authority_status_inactive",
+  "grant_missing",
+  "grant_identity_changed",
+  "grant_generation_changed",
+  "grant_status_inactive",
+  "grant_expired",
+  "grant_already_consumed",
+]);
+export type ConnectionUseDenialReason = z.infer<typeof ConnectionUseDenialReason>;
+
+const ConnectionUseAttributionFields = z
+  .object({
+    organizationId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    connectionId: z.string().uuid(),
+    connectionGeneration: z.number().int().positive(),
+    scope: z.enum(["workspace", "user", "legacy_user"]),
+    ownerSubjectId: z.string().min(1).max(512).nullable(),
+    authorityId: z.string().uuid().nullable(),
+    grantId: z.string().uuid().nullable(),
+  })
+  .strict();
+
+function refineConnectionUseAttribution(
+  value: z.infer<typeof ConnectionUseAttributionFields>,
+  context: z.RefinementCtx,
+): void {
+  const personal = value.scope !== "workspace";
+  for (const field of ["ownerSubjectId"] as const) {
+    if (personal !== (value[field] !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: [field],
+        message: personal
+          ? `personal attribution requires ${field}`
+          : `workspace attribution cannot carry ${field}`,
+      });
+    }
+  }
+  const owned = value.scope === "user";
+  for (const field of ["authorityId"] as const) {
+    if (owned !== (value[field] !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: [field],
+        message: owned
+          ? `personal attribution requires ${field}`
+          : `non-personal attribution cannot carry ${field}`,
+      });
+    }
+  }
+  if (!owned && value.grantId !== null) {
+    context.addIssue({
+      code: "custom",
+      path: ["grantId"],
+      message: "only historical personal attribution can carry a grant",
+    });
+  }
+}
+
+/** Metadata-only attribution emitted after pre-use authorization. */
+export const ConnectionUseAttribution = ConnectionUseAttributionFields.extend({
+  scope: z.enum(["workspace", "user"]),
+  grantId: z.null(),
+}).superRefine(refineConnectionUseAttribution);
+export type ConnectionUseAttribution = z.infer<typeof ConnectionUseAttribution>;
+
+export const ConnectionUseAuditFact = ConnectionUseAttributionFields.extend({
+  outcome: z.enum(["authorized", "denied"]),
+  denialReason: ConnectionUseDenialReason.nullable(),
+  occurredAt: z.string().datetime({ offset: true }),
+}).superRefine((value, context) => {
+  refineConnectionUseAttribution(value, context);
+  if ((value.outcome === "denied") !== (value.denialReason !== null)) {
+    context.addIssue({
+      code: "custom",
+      path: ["denialReason"],
+      message: "only denied connection use carries a denial reason",
+    });
+  }
+});
+export type ConnectionUseAuditFact = z.infer<typeof ConnectionUseAuditFact>;
+
+export const ConnectionUseAuthorizationResult = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("authorized"), attribution: ConnectionUseAttribution }).strict(),
+  z.object({ status: z.literal("denied"), reason: ConnectionUseDenialReason }).strict(),
+]);
+export type ConnectionUseAuthorizationResult = z.infer<typeof ConnectionUseAuthorizationResult>;

package/src/connector-attachments.ts

@@ -0,0 +1,327 @@
+import { z } from "zod";
+
+export const CONNECTOR_ATTACHMENT_TRANSFER_VERSION = 1 as const;
+export const CONNECTOR_ATTACHMENT_RECEIPT_VERSION = 1 as const;
+export const CONNECTOR_ATTACHMENT_TRANSFER_META_KEY =
+  "opengeni/connector-attachment-transfers" as const;
+export const CONNECTOR_ATTACHMENT_RECEIPT_META_KEY =
+  "opengeni/connector-attachment-receipts" as const;
+export const CONNECTOR_ATTACHMENT_MAX_COUNT = 16;
+// Must remain byte-for-byte aligned with Channel A's exact workspace importer.
+export const CONNECTOR_ATTACHMENT_MAX_BYTES = 5_000_000_000;
+export const CONNECTOR_ATTACHMENT_FILENAME_MAX_UTF8_BYTES = 255;
+export const CONNECTOR_ATTACHMENT_MEDIA_TYPE_MAX_UTF8_BYTES = 256;
+export const CONNECTOR_ATTACHMENT_PROVIDER_MAX_UTF8_BYTES = 128;
+export const CONNECTOR_ATTACHMENT_PROVIDER_ID_MAX_UTF8_BYTES = 512;
+export const CONNECTOR_ATTACHMENT_SOURCE_URL_MAX_UTF8_BYTES = 8 * 1024;
+export const CONNECTOR_ATTACHMENT_SANDBOX_PATH_MAX_UTF8_BYTES = 2 * 1024;
+
+const PROVIDER_PATTERN = /^[a-z0-9]+(?:[._-][a-z0-9]+)*$/u;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+const MEDIA_TYPE_PATTERN =
+  /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+(?:\s*;\s*[a-z0-9!#$&^_.+-]+=(?:[a-z0-9!#$&^_.+-]+|"[^"\r\n]*"))*$/iu;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u001f\u007f]/u;
+const HTTP_URL_REFERENCE_PATTERN = /(?:https?:)?\/\/[^\s]/iu;
+const PORTABLE_FILENAME_FORBIDDEN_PATTERN = /[<>:"|?*]/u;
+const PORTABLE_FILENAME_RESERVED_PATTERN = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/iu;
+const textEncoder = new TextEncoder();
+
+function utf8Bytes(value: string): number {
+  return textEncoder.encode(value).byteLength;
+}
+
+function boundedString(maxUtf8Bytes: number) {
+  return z.string().refine((value) => utf8Bytes(value) <= maxUtf8Bytes, {
+    message: `must be at most ${maxUtf8Bytes} UTF-8 bytes`,
+  });
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+function containsHttpUrlReference(value: string): boolean {
+  return HTTP_URL_REFERENCE_PATTERN.test(value);
+}
+
+function isPrivateUrlCredentialQueryName(value: string): boolean {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9]/gu, "");
+  return (
+    normalized === "sig" ||
+    normalized === "auth" ||
+    normalized.endsWith("signature") ||
+    normalized.endsWith("token") ||
+    normalized.endsWith("credential") ||
+    normalized.endsWith("secret") ||
+    normalized.endsWith("password") ||
+    normalized.endsWith("passcode") ||
+    normalized.endsWith("authorization") ||
+    normalized.endsWith("apikey") ||
+    normalized.endsWith("accesskey") ||
+    normalized.endsWith("securitytoken") ||
+    normalized.endsWith("sas") ||
+    normalized === "googleaccessid"
+  );
+}
+
+function privateUrlCredentialValues(value: string): string[] {
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return [];
+  }
+  const credentials = new Set<string>();
+  for (const [name, credential] of parsed.searchParams) {
+    if (credential && isPrivateUrlCredentialQueryName(name)) credentials.add(credential);
+  }
+  for (const pair of parsed.search.slice(1).split("&")) {
+    if (!pair) continue;
+    const separator = pair.indexOf("=");
+    const rawName = separator === -1 ? pair : pair.slice(0, separator);
+    const rawCredential = separator === -1 ? "" : pair.slice(separator + 1);
+    let decodedName: string;
+    try {
+      decodedName = decodeURIComponent(rawName.replace(/\+/gu, " "));
+    } catch {
+      continue;
+    }
+    if (rawCredential && isPrivateUrlCredentialQueryName(decodedName)) {
+      credentials.add(rawCredential);
+    }
+  }
+  return [...credentials];
+}
+
+function publicMetadataContainsCredential(publicValue: string, credential: string): boolean {
+  return publicValue.includes(credential);
+}
+
+export const ConnectorAttachmentProviderIdentity = z
+  .object({
+    provider: boundedString(CONNECTOR_ATTACHMENT_PROVIDER_MAX_UTF8_BYTES).regex(PROVIDER_PATTERN),
+    kind: z.literal("attachment"),
+    value: boundedString(CONNECTOR_ATTACHMENT_PROVIDER_ID_MAX_UTF8_BYTES)
+      .min(1)
+      .refine((value) => !CONTROL_CHARACTER_PATTERN.test(value), {
+        message: "must not contain control characters",
+      })
+      .refine((value) => !isHttpUrl(value) && !containsHttpUrlReference(value), {
+        message: "must be an opaque provider attachment identity, not a URL",
+      }),
+  })
+  .strict();
+export type ConnectorAttachmentProviderIdentity = z.infer<
+  typeof ConnectorAttachmentProviderIdentity
+>;
+
+export const ConnectorAttachmentFileName = boundedString(
+  CONNECTOR_ATTACHMENT_FILENAME_MAX_UTF8_BYTES,
+)
+  .min(1)
+  .refine(
+    (value) =>
+      value !== "." &&
+      value !== ".." &&
+      value === value.trim() &&
+      !value.includes("/") &&
+      !value.includes("\\") &&
+      !CONTROL_CHARACTER_PATTERN.test(value) &&
+      !PORTABLE_FILENAME_FORBIDDEN_PATTERN.test(value) &&
+      !/[ .]$/u.test(value) &&
+      !PORTABLE_FILENAME_RESERVED_PATTERN.test(value),
+    { message: "must be a safe leaf filename" },
+  );
+
+export const ConnectorAttachmentMediaType = boundedString(
+  CONNECTOR_ATTACHMENT_MEDIA_TYPE_MAX_UTF8_BYTES,
+)
+  .regex(MEDIA_TYPE_PATTERN)
+  .refine((value) => !containsHttpUrlReference(value), {
+    message: "must not contain an HTTP URL reference",
+  });
+
+export const ConnectorAttachmentSha256 = z.string().regex(SHA256_PATTERN);
+
+export const ConnectorAttachmentPrivateSource = z
+  .object({
+    url: boundedString(CONNECTOR_ATTACHMENT_SOURCE_URL_MAX_UTF8_BYTES).superRefine(
+      (value, context) => {
+        let parsed: URL;
+        try {
+          parsed = new URL(value);
+        } catch {
+          context.addIssue({
+            code: "custom",
+            message: "must be an absolute URL",
+          });
+          return;
+        }
+        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+          context.addIssue({ code: "custom", message: "must use http or https" });
+        }
+        if (parsed.username || parsed.password) {
+          context.addIssue({
+            code: "custom",
+            message: "must not contain URL userinfo",
+          });
+        }
+        if (parsed.hash) {
+          context.addIssue({
+            code: "custom",
+            message: "must not contain a URL fragment",
+          });
+        }
+      },
+    ),
+    expiresAt: z.iso.datetime({ offset: true }),
+  })
+  .strict();
+export type ConnectorAttachmentPrivateSource = z.infer<typeof ConnectorAttachmentPrivateSource>;
+
+export const ConnectorAttachmentTransfer = z
+  .object({
+    providerAttachmentId: ConnectorAttachmentProviderIdentity,
+    fileName: ConnectorAttachmentFileName,
+    mediaType: ConnectorAttachmentMediaType,
+    byteSize: z.number().int().min(0).max(CONNECTOR_ATTACHMENT_MAX_BYTES),
+    contentSha256: ConnectorAttachmentSha256,
+    source: ConnectorAttachmentPrivateSource,
+  })
+  .strict()
+  .superRefine((attachment, context) => {
+    const publicValues = [
+      attachment.providerAttachmentId.value,
+      attachment.fileName,
+      attachment.mediaType,
+    ];
+    for (const credential of privateUrlCredentialValues(attachment.source.url)) {
+      if (publicValues.some((value) => publicMetadataContainsCredential(value, credential))) {
+        context.addIssue({
+          code: "custom",
+          message: "private source credentials must not appear in public attachment metadata",
+        });
+        return;
+      }
+    }
+  });
+export type ConnectorAttachmentTransfer = z.infer<typeof ConnectorAttachmentTransfer>;
+
+export const ConnectorAttachmentTransferEnvelope = z
+  .object({
+    version: z.literal(CONNECTOR_ATTACHMENT_TRANSFER_VERSION),
+    attachments: z.array(ConnectorAttachmentTransfer).min(1).max(CONNECTOR_ATTACHMENT_MAX_COUNT),
+  })
+  .strict()
+  .superRefine((envelope, context) => {
+    const identities = new Set<string>();
+    for (const [index, attachment] of envelope.attachments.entries()) {
+      const identity = `${attachment.providerAttachmentId.provider}\0${attachment.providerAttachmentId.value}`;
+      if (identities.has(identity)) {
+        context.addIssue({
+          code: "custom",
+          message: "provider attachment identities must be unique",
+          path: ["attachments", index, "providerAttachmentId"],
+        });
+      }
+      identities.add(identity);
+    }
+  });
+export type ConnectorAttachmentTransferEnvelope = z.infer<
+  typeof ConnectorAttachmentTransferEnvelope
+>;
+
+export const ConnectorAttachmentSandboxPath = boundedString(
+  CONNECTOR_ATTACHMENT_SANDBOX_PATH_MAX_UTF8_BYTES,
+)
+  .min(1)
+  .refine(
+    (value) => {
+      if (
+        value !== value.trim() ||
+        value.startsWith("/") ||
+        /^[A-Za-z]:[\\/]/u.test(value) ||
+        value.includes("\\") ||
+        CONTROL_CHARACTER_PATTERN.test(value)
+      ) {
+        return false;
+      }
+      const segments = value.split("/");
+      if (
+        segments.length !== 5 ||
+        segments[0] !== ".opengeni" ||
+        segments[1] !== "connector-attachments" ||
+        !PROVIDER_PATTERN.test(segments[2] ?? "") ||
+        !/^[0-9a-f]{32}$/u.test(segments[3] ?? "") ||
+        !ConnectorAttachmentFileName.safeParse(segments[4]).success
+      ) {
+        return false;
+      }
+      return segments.every(
+        (segment) =>
+          segment.length > 0 &&
+          segment !== "." &&
+          segment !== ".." &&
+          !PORTABLE_FILENAME_FORBIDDEN_PATTERN.test(segment) &&
+          !/[ .]$/u.test(segment) &&
+          !PORTABLE_FILENAME_RESERVED_PATTERN.test(segment),
+      );
+    },
+    { message: "must be a confined connector attachment sandbox path" },
+  );
+
+export const ConnectorAttachmentReceipt = z
+  .object({
+    providerAttachmentId: ConnectorAttachmentProviderIdentity,
+    fileName: ConnectorAttachmentFileName,
+    mediaType: ConnectorAttachmentMediaType,
+    byteSize: z.number().int().min(0).max(CONNECTOR_ATTACHMENT_MAX_BYTES),
+    contentSha256: ConnectorAttachmentSha256,
+    sandboxPath: ConnectorAttachmentSandboxPath,
+  })
+  .strict()
+  .superRefine((receipt, context) => {
+    const segments = receipt.sandboxPath.split("/");
+    if (segments[2] !== receipt.providerAttachmentId.provider) {
+      context.addIssue({
+        code: "custom",
+        message: "sandbox path provider must match the provider attachment identity",
+        path: ["sandboxPath"],
+      });
+    }
+    if (segments[4] !== receipt.fileName) {
+      context.addIssue({
+        code: "custom",
+        message: "sandbox path filename must match the attachment filename",
+        path: ["sandboxPath"],
+      });
+    }
+  });
+export type ConnectorAttachmentReceipt = z.infer<typeof ConnectorAttachmentReceipt>;
+
+export const ConnectorAttachmentReceiptEnvelope = z
+  .object({
+    version: z.literal(CONNECTOR_ATTACHMENT_RECEIPT_VERSION),
+    attachments: z.array(ConnectorAttachmentReceipt).min(1).max(CONNECTOR_ATTACHMENT_MAX_COUNT),
+  })
+  .strict();
+export type ConnectorAttachmentReceiptEnvelope = z.infer<typeof ConnectorAttachmentReceiptEnvelope>;
+
+export function parseConnectorAttachmentTransferEnvelope(
+  value: unknown,
+  options: { nowMs?: number } = {},
+): ConnectorAttachmentTransferEnvelope {
+  const envelope = ConnectorAttachmentTransferEnvelope.parse(value);
+  const nowMs = options.nowMs ?? Date.now();
+  for (const attachment of envelope.attachments) {
+    if (Date.parse(attachment.source.expiresAt) <= nowMs) {
+      throw new Error("connector attachment source is expired");
+    }
+  }
+  return envelope;
+}

package/src/connector-tool-permissions.ts

@@ -0,0 +1,60 @@
+import { z } from "zod";
+import { MCP_MAX_CATALOG_TOOL_ENTRIES } from "./mcp-catalog-limits";
+
+export const ConnectorToolPermission = z.enum(["allow", "ask", "block"]);
+export type ConnectorToolPermission = z.infer<typeof ConnectorToolPermission>;
+
+export const ConnectorToolPermissionEntry = z.object({
+  name: z.string().min(1).max(512),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  group: z.enum(["read", "write", "other"]),
+  permission: ConnectorToolPermission,
+  inherited: z.boolean(),
+  approvalRequired: z.boolean(),
+});
+export type ConnectorToolPermissionEntry = z.infer<typeof ConnectorToolPermissionEntry>;
+
+export const ConnectorToolPermissionsResponse = z.object({
+  connectionId: z.string(),
+  serverId: z.string(),
+  defaultPermission: ConnectorToolPermission.nullable(),
+  tools: z.array(ConnectorToolPermissionEntry),
+  discoveryError: z.string().nullable(),
+  canManage: z.boolean(),
+});
+export type ConnectorToolPermissionsResponse = z.infer<typeof ConnectorToolPermissionsResponse>;
+
+// Group changes name the currently displayed tools explicitly. MCP annotations
+// organize the UI only; they never grant future tools permission automatically.
+export const UpdateConnectorToolPermissionsRequest = z.discriminatedUnion("target", [
+  z
+    .object({
+      connectionId: z.string().min(1).max(512),
+      target: z.literal("default"),
+      permission: ConnectorToolPermission,
+    })
+    .strict(),
+  z
+    .object({
+      connectionId: z.string().min(1).max(512),
+      target: z.literal("tools"),
+      toolNames: z
+        .array(
+          z
+            .string()
+            .min(1)
+            .max(512)
+            .refine((name) => name !== "*" && name === name.trim(), {
+              message: "Tool names must be exact and cannot use the connector-default wildcard.",
+            }),
+        )
+        .min(1)
+        .max(MCP_MAX_CATALOG_TOOL_ENTRIES),
+      permission: ConnectorToolPermission,
+    })
+    .strict(),
+]);
+export type UpdateConnectorToolPermissionsRequest = z.infer<
+  typeof UpdateConnectorToolPermissionsRequest
+>;

package/src/direct-model-provider.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+
+export const DirectModelProvider = z.enum(["openai", "azure_openai"]);
+export type DirectModelProvider = z.infer<typeof DirectModelProvider>;
+
+/** Pin customer credentials to official provider origins, never arbitrary URLs. */
+export const AzureOpenAIEndpoint = z
+  .string()
+  .trim()
+  .url()
+  .superRefine((value, ctx) => {
+    let url: URL;
+    try {
+      url = new URL(value);
+    } catch {
+      // The preceding URL validator supplies the normal validation issue.
+      return;
+    }
+    if (
+      url.protocol !== "https:" ||
+      url.username ||
+      url.password ||
+      url.port ||
+      !/^[a-z0-9-]+\.openai\.azure\.com$/i.test(url.hostname) ||
+      !["", "/", "/openai/v1", "/openai/v1/"].includes(url.pathname) ||
+      url.search ||
+      url.hash
+    ) {
+      ctx.addIssue({ code: "custom", message: "Enter your Azure OpenAI HTTPS resource endpoint" });
+    }
+  })
+  .transform((value) => new URL(value).origin + "/openai/v1");
+
+export const DirectModelProviderMetadata = z
+  .object({
+    provider: DirectModelProvider,
+    model: z
+      .string()
+      .trim()
+      .min(1)
+      .max(128)
+      .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
+    endpoint: AzureOpenAIEndpoint.optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.provider === "azure_openai" && !value.endpoint) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["endpoint"],
+        message: "Azure OpenAI needs an endpoint",
+      });
+    }
+    if (value.provider === "openai" && value.endpoint) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["endpoint"],
+        message: "OpenAI uses its official API endpoint",
+      });
+    }
+  });
+export type DirectModelProviderMetadata = z.infer<typeof DirectModelProviderMetadata>;
+
+export function directModelConnectionSpec(connection: {
+  id: string;
+  version: number;
+  subjectId: string | null;
+  kind: string;
+  status: string;
+  providerDomain: string;
+  metadata: Record<string, unknown>;
+}) {
+  if (
+    connection.subjectId !== null ||
+    connection.kind !== "api_key" ||
+    connection.status !== "active"
+  )
+    return null;
+  const parsed = DirectModelProviderMetadata.safeParse(connection.metadata.directModelProvider);
+  if (!parsed.success || connection.metadata.credentialRole !== `direct_${parsed.data.provider}`)
+    return null;
+  const config = parsed.data;
+  const baseUrl = config.provider === "openai" ? "https://api.openai.com/v1" : config.endpoint!;
+  if (connection.providerDomain.toLowerCase() !== new URL(baseUrl).hostname) return null;
+  const providerId = `workspace-${config.provider === "openai" ? "openai" : "azure-openai"}-${connection.id}`;
+  return {
+    ...config,
+    baseUrl,
+    providerId,
+    modelId: `${providerId}/${connection.version}/${config.model}`,
+    connectionId: connection.id,
+    version: connection.version,
+  };
+}
+
+export function isDirectModelId(modelId: string): boolean {
+  return /^workspace-(?:openai|azure-openai)-[0-9a-f-]{36}\//.test(modelId);
+}