@builder.io/ai-utils 0.89.0 → 0.90.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.89.0",
+  "version": "0.90.0",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/editor-ai.d.ts

@@ -1,6 +1,10 @@
 import { z } from "zod";
 export declare const EDITOR_AI_READ_DEFAULT_LIMIT = 250;
 export declare const EDITOR_AI_READ_MAX_LIMIT = 1500;
+export declare const EditorAiComponentSchema: z.ZodObject<{
+    name: z.ZodString;
+}, z.core.$loose>;
+export type EditorAiComponent = z.infer<typeof EditorAiComponentSchema>;
 export declare const EditorAiReadRequestSchema: z.ZodObject<{
     contentId: z.ZodString;
     offset: z.ZodOptional<z.ZodNumber>;
@@ -22,6 +26,9 @@ export declare const EditorAiEditRequestSchema: z.ZodObject<{
     old_str: z.ZodString;
     new_str: z.ZodString;
     activeLocale: z.ZodOptional<z.ZodString>;
+    components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$loose>>>;
 }, z.core.$strip>;
 export type EditorAiEditRequest = z.infer<typeof EditorAiEditRequestSchema>;
 export declare const EditorAiEditResponseSchema: z.ZodObject<{
@@ -34,6 +41,9 @@ export declare const EditorAiWriteRequestSchema: z.ZodObject<{
     contentId: z.ZodString;
     content: z.ZodString;
     activeLocale: z.ZodOptional<z.ZodString>;
+    components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+    }, z.core.$loose>>>;
 }, z.core.$strip>;
 export type EditorAiWriteRequest = z.infer<typeof EditorAiWriteRequestSchema>;
 export declare const EditorAiWriteResponseSchema: z.ZodObject<{

package/src/editor-ai.js

@@ -3,6 +3,16 @@ import { z } from "zod";
 // endpoints. Shared so the Builder CMS MCP server reuses the same shapes.
 export const EDITOR_AI_READ_DEFAULT_LIMIT = 250;
 export const EDITOR_AI_READ_MAX_LIMIT = 1500;
+// Registered component names are sanitized into valid JSX identifiers when
+// content is serialized ("Hero Banner" -> "Hero_Banner"). Blocks already in the
+// content restore from their own stored name, but a block the model introduces
+// for the first time can only be mapped back via this catalog.
+export const EditorAiComponentSchema = z
+    .looseObject({
+    name: z.string().min(1),
+})
+    .meta({ title: "EditorAiComponent" });
+const componentsField = z.array(EditorAiComponentSchema).optional();
 export const EditorAiReadRequestSchema = z
     .object({
     contentId: z.string().min(1),
@@ -34,6 +44,7 @@ export const EditorAiEditRequestSchema = z
     new_str: z.string(),
     // Locale to operate on; defaults to "Default" when omitted.
     activeLocale: z.string().min(1).optional(),
+    components: componentsField,
 })
     .meta({ title: "EditorAiEditRequest" });
 export const EditorAiEditResponseSchema = z
@@ -49,6 +60,7 @@ export const EditorAiWriteRequestSchema = z
     content: z.string().min(1),
     // Locale to operate on; defaults to "Default" when omitted.
     activeLocale: z.string().min(1).optional(),
+    components: componentsField,
 })
     .meta({ title: "EditorAiWriteRequest" });
 export const EditorAiWriteResponseSchema = z

package/src/organization.d.ts

@@ -243,6 +243,38 @@ export interface Coupon extends SubscriptionInfo {
     id: string;
     plan: keyof SubscriptionInfoMap;
 }
+export type BuilderAuthRule = {
+    type: "builderAuth";
+    id: string;
+} & ({
+    scope: "orgMember";
+} | {
+    scope: "namedUsers";
+    userIds: string[];
+});
+export type SiteAccessRule = {
+    type: "password";
+    id: string;
+    passwordHash: string;
+} | BuilderAuthRule | {
+    type: "ip";
+    id: string;
+    cidrs: string[];
+};
+export interface SiteAccessControl {
+    enabled: boolean;
+    combinator: "any" | "all";
+    rules: SiteAccessRule[];
+    tokenVersion?: number;
+}
+export interface SiteSessionClaims {
+    userId: string;
+    slug: string;
+    /** Project-level policy version at mint time. */
+    tokenVersion: number;
+    /** Org-level policy version at mint time; an org rotation invalidates the session too. */
+    orgTokenVersion: number;
+}
 export interface FeatureMap {
     abTesting?: boolean;
     metrics?: boolean;
@@ -321,6 +353,7 @@ export interface FeatureMap {
     customDockerImages?: boolean;
     performanceInfrastructure?: boolean;
     previewPasswordProtection?: boolean;
+    siteAccessControl?: boolean;
     publicPreviews?: boolean;
     privacyMode?: boolean;
     usageInsights?: boolean;

package/src/projects.d.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import type { BuilderConfigHosting } from "./builder-config.js";
 import type { ConnectivityErrorCode, CheckType, LikelyCause } from "./connectivity/types.js";
 import type { LaunchServerState, LaunchServerStatus, BranchBackup, CommitMode, GitSnapshot, GenerateUserMessage, CodeGenToolMap, GenerateCompletionStep, ExitState } from "./codegen";
-import type { FallbackTokensPrivate } from "./organization";
+import type { FallbackTokensPrivate, SiteAccessControl } from "./organization";
 /**
  * Temporary type for date fields during migration.
  * Handles both old (string) and new (number) formats.
@@ -1720,6 +1720,24 @@ export interface OrganizationPrivate {
     updatedAt: number;
     fallbackTokens?: FallbackTokensPrivate;
     fusionWebhookSecrets?: Record<string, string>;
+    /**
+     * Full org-default hosted-site access policy (rules + scrypt password hashes).
+     * Server-only: never exposed to clients. UI reads via
+     * GET /projects/hosting/site-access.
+     */
+    siteAccessControl?: SiteAccessControl;
+}
+/**
+ * Server-only per-project document (`projects_private/{projectId}`), mirroring
+ * `organizations_private`. Holds secrets that must never reach clients.
+ */
+export interface ProjectPrivate {
+    projectId: string;
+    /**
+     * Full project-level hosted-site access policy (rules + scrypt password
+     * hashes). Server-only; UI reads via GET /projects/hosting/site-access.
+     */
+    siteAccessControl?: SiteAccessControl;
 }
 export interface CreateProjectOptions {
     name?: string;
@@ -3037,6 +3055,134 @@ export declare const CloneProjectOptionsSchema: z.ZodObject<{
     useKube: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 export type CloneProjectOptions = z.infer<typeof CloneProjectOptionsSchema>;
+/**
+ * Write-time contract for a single hosted-site access rule. Mirrors the stored
+ * {@link SiteAccessRule} in `organization.ts`, except a password rule carries a
+ * **plaintext** `password` (write-only — scrypt hashing happens server-side)
+ * instead of `passwordHash`, and `id` is optional (the server assigns stable
+ * ids to new rules). Omitting `password` on an existing rule (matched by `id`)
+ * preserves the stored hash. `organization.ts` remains the source of truth for
+ * the persisted shape.
+ */
+export declare const SiteAccessRuleInputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"password">;
+    id: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"builderAuth">;
+    id: z.ZodOptional<z.ZodString>;
+    scope: z.ZodEnum<{
+        namedUsers: "namedUsers";
+        orgMember: "orgMember";
+    }>;
+    userIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ip">;
+    id: z.ZodOptional<z.ZodString>;
+    cidrs: z.ZodArray<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type SiteAccessRuleInput = z.infer<typeof SiteAccessRuleInputSchema>;
+/** Write-time contract for one level of a site's access boundary. */
+export declare const SiteAccessControlInputSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    combinator: z.ZodDefault<z.ZodEnum<{
+        all: "all";
+        any: "any";
+    }>>;
+    rules: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        type: z.ZodLiteral<"password">;
+        id: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"builderAuth">;
+        id: z.ZodOptional<z.ZodString>;
+        scope: z.ZodEnum<{
+            namedUsers: "namedUsers";
+            orgMember: "orgMember";
+        }>;
+        userIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"ip">;
+        id: z.ZodOptional<z.ZodString>;
+        cidrs: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>], "type">>;
+}, z.core.$strip>;
+export type SiteAccessControlInput = z.infer<typeof SiteAccessControlInputSchema>;
+/**
+ * Request to save a site's access boundary at the project or org-default level.
+ * Handled by `POST /projects/hosting/site-access` — a dedicated write path
+ * because passwords must be hashed server-side, the paid `siteAccessControl`
+ * feature (and enterprise, for `ip` rules) is enforced at save time,
+ * `tokenVersion` is bumped on change, and the Envoy `SecurityPolicy` is
+ * reconciled. The generic project settings update does none of this.
+ */
+export declare const SaveSiteAccessControlRequestSchema: z.ZodObject<{
+    level: z.ZodEnum<{
+        org: "org";
+        project: "project";
+    }>;
+    projectId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+    access: z.ZodObject<{
+        enabled: z.ZodBoolean;
+        combinator: z.ZodDefault<z.ZodEnum<{
+            all: "all";
+            any: "any";
+        }>>;
+        rules: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"password">;
+            id: z.ZodOptional<z.ZodString>;
+            password: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"builderAuth">;
+            id: z.ZodOptional<z.ZodString>;
+            scope: z.ZodEnum<{
+                namedUsers: "namedUsers";
+                orgMember: "orgMember";
+            }>;
+            userIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"ip">;
+            id: z.ZodOptional<z.ZodString>;
+            cidrs: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>], "type">>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SaveSiteAccessControlRequest = z.infer<typeof SaveSiteAccessControlRequestSchema>;
+/**
+ * Request to read a site's (sanitized) access boundary for one level. Handled
+ * by `GET /projects/hosting/site-access` so the settings editor can prefill the
+ * configured rules. Full policy lives in server-only storage
+ * (`organizations_private` / `projects_private`).
+ */
+export declare const GetSiteAccessControlRequestSchema: z.ZodObject<{
+    level: z.ZodEnum<{
+        org: "org";
+        project: "project";
+    }>;
+    projectId: z.ZodOptional<z.ZodString>;
+    organizationId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GetSiteAccessControlRequest = z.infer<typeof GetSiteAccessControlRequestSchema>;
+/**
+ * Body for `POST /projects/hosting/site-access/exchange`. Trades a Firebase ID
+ * token for a short-lived, site-scoped exchange code (so the ID token never
+ * reaches the site host). Sent as `application/x-www-form-urlencoded`.
+ */
+export declare const SiteAccessExchangeRequestSchema: z.ZodObject<{
+    idToken: z.ZodString;
+    host: z.ZodString;
+}, z.core.$strip>;
+export type SiteAccessExchangeRequest = z.infer<typeof SiteAccessExchangeRequestSchema>;
+/**
+ * Body/query for `POST /__builder-site-access/callback`. The exchange `code` is
+ * preferred from the body; query is accepted for defensive compatibility.
+ */
+export declare const SiteAccessLoginReturnParamsSchema: z.ZodObject<{
+    code: z.ZodOptional<z.ZodString>;
+    returnTo: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type SiteAccessLoginReturnParams = z.infer<typeof SiteAccessLoginReturnParamsSchema>;
 export declare const DuplicateBranchOptionsSchema: z.ZodObject<{
     projectId: z.ZodString;
     sourceBranchName: z.ZodString;

package/src/projects.js

@@ -1609,6 +1609,81 @@ export const CloneProjectOptionsSchema = z.object({
         description: "Whether to provision on cloud-v2 (Kubernetes). Defaults to false.",
     }),
 });
+/**
+ * Write-time contract for a single hosted-site access rule. Mirrors the stored
+ * {@link SiteAccessRule} in `organization.ts`, except a password rule carries a
+ * **plaintext** `password` (write-only — scrypt hashing happens server-side)
+ * instead of `passwordHash`, and `id` is optional (the server assigns stable
+ * ids to new rules). Omitting `password` on an existing rule (matched by `id`)
+ * preserves the stored hash. `organization.ts` remains the source of truth for
+ * the persisted shape.
+ */
+export const SiteAccessRuleInputSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("password"),
+        id: z.string().optional(),
+        password: z.string().min(1).optional(),
+    }),
+    z.object({
+        type: z.literal("builderAuth"),
+        id: z.string().optional(),
+        scope: z.enum(["orgMember", "namedUsers"]),
+        userIds: z.array(z.string()).optional(),
+    }),
+    z.object({
+        type: z.literal("ip"),
+        id: z.string().optional(),
+        cidrs: z.array(z.string().min(1)),
+    }),
+]);
+/** Write-time contract for one level of a site's access boundary. */
+export const SiteAccessControlInputSchema = z.object({
+    enabled: z.boolean(),
+    combinator: z.enum(["any", "all"]).default("all"),
+    rules: z.array(SiteAccessRuleInputSchema),
+});
+/**
+ * Request to save a site's access boundary at the project or org-default level.
+ * Handled by `POST /projects/hosting/site-access` — a dedicated write path
+ * because passwords must be hashed server-side, the paid `siteAccessControl`
+ * feature (and enterprise, for `ip` rules) is enforced at save time,
+ * `tokenVersion` is bumped on change, and the Envoy `SecurityPolicy` is
+ * reconciled. The generic project settings update does none of this.
+ */
+export const SaveSiteAccessControlRequestSchema = z.object({
+    level: z.enum(["project", "org"]),
+    projectId: z.string().optional(),
+    organizationId: z.string().optional(),
+    access: SiteAccessControlInputSchema,
+});
+/**
+ * Request to read a site's (sanitized) access boundary for one level. Handled
+ * by `GET /projects/hosting/site-access` so the settings editor can prefill the
+ * configured rules. Full policy lives in server-only storage
+ * (`organizations_private` / `projects_private`).
+ */
+export const GetSiteAccessControlRequestSchema = z.object({
+    level: z.enum(["project", "org"]),
+    projectId: z.string().optional(),
+    organizationId: z.string().optional(),
+});
+/**
+ * Body for `POST /projects/hosting/site-access/exchange`. Trades a Firebase ID
+ * token for a short-lived, site-scoped exchange code (so the ID token never
+ * reaches the site host). Sent as `application/x-www-form-urlencoded`.
+ */
+export const SiteAccessExchangeRequestSchema = z.object({
+    idToken: z.string().min(1),
+    host: z.string().min(1),
+});
+/**
+ * Body/query for `POST /__builder-site-access/callback`. The exchange `code` is
+ * preferred from the body; query is accepted for defensive compatibility.
+ */
+export const SiteAccessLoginReturnParamsSchema = z.object({
+    code: z.string().min(1).optional(),
+    returnTo: z.string().optional(),
+});
 export const DuplicateBranchOptionsSchema = z.object({
     projectId: z.string().min(1).meta({
         description: "Project that owns the branch being duplicated.",

package/src/single-tenancy.d.ts

@@ -22,8 +22,53 @@ export interface VpcGcpNetworkAttachment extends VpcConnectionBase {
     gcpProjectId: string;
     networkAttachmentName: string;
 }
+/**
+ * One customer-owned VPC Endpoint Service that we create a matching interface
+ * VPC Endpoint for, in the shared Builder AWS VPC.
+ */
+export interface PrivateLinkEndpoint {
+    /** `com.amazonaws.vpce.<region>.vpce-svc-xxx` — the customer's Endpoint Service. */
+    serviceName: string;
+    /**
+     * Customer-private hostnames that resolve to this endpoint, rendered as dnsmasq
+     * `address=/<hostname>/<ip>` overrides on the customer's proxy VM. Needed
+     * because a customer Endpoint Service cannot enable private DNS without domain
+     * verification.
+     */
+    hostnames: string[];
+    /** Ports the customer exposes. Scopes the endpoint's AWS security group. */
+    ports: number[];
+    /**
+     * Server-allocated host number for this endpoint's pinned ENI IPs, unique
+     * across the shared Builder VPC and never renumbered: reusing an index gives a
+     * new endpoint an old one's IP, so a pod holding a stale DNS answer reaches the
+     * wrong service. Guarded by the `ip_index` preconditions in
+     * packages/terraform/aws-vpc-module/privatelink.tf.
+     */
+    ipIndex: number;
+}
+/**
+ * AWS PrivateLink — the customer provisions an NLB plus a VPC Endpoint Service
+ * allowlisting Builder's AWS account; we create the matching interface endpoint
+ * in a shared Builder VPC, reached from the customer's GCP proxy VM over the
+ * shared GCP↔AWS bridge. Per-service rather than per-VPC, so a config holds N
+ * endpoints.
+ */
+export interface VpcAwsPrivateLink extends VpcConnectionBase {
+    type: "aws-privatelink";
+    /** Must match the region aws-vpc-module runs in ({@link BUILDER_AWS_REGION}). */
+    awsRegion: string;
+    endpoints: PrivateLinkEndpoint[];
+    /**
+     * Highest `ipIndex` this config has ever been allocated, retained after the
+     * endpoint holding it is removed. Without it, deleting the highest endpoint
+     * would lower the next allocation and hand a new endpoint the removed one's
+     * pinned IPs. Optional for configs written before it existed.
+     */
+    ipIndexWatermark?: number;
+}
 /** Discriminated union of all VPC connectivity types. */
-export type VpcConnection = VpcGcpPeering | VpcGcpNetworkAttachment;
+export type VpcConnection = VpcGcpPeering | VpcGcpNetworkAttachment | VpcAwsPrivateLink;
 /**
  * Dedicated node pool preferences for a single tenancy customer.
  * Independent of VPC connectivity.
@@ -67,7 +112,23 @@ export interface CreateVpcGcpNetworkAttachmentParams {
     networkAttachmentName: string;
     customerDnsServers: string[];
 }
-export type CreateSingleTenancyVpcParams = CreateVpcGcpPeeringParams | CreateVpcGcpNetworkAttachmentParams;
+/**
+ * Endpoint fields a caller supplies. Omits the server-allocated `ipIndex`, which
+ * makes the never-renumber invariant structural rather than a validation rule.
+ */
+export type CreatePrivateLinkEndpointParams = Omit<PrivateLinkEndpoint, "ipIndex">;
+export interface CreateVpcAwsPrivateLinkParams {
+    type: "aws-privatelink";
+    awsRegion: string;
+    endpoints: CreatePrivateLinkEndpointParams[];
+    /**
+     * Unused for PrivateLink, which resolves via static dnsmasq overrides derived
+     * from `endpoints[].hostnames` rather than forwarding to customer resolvers.
+     * Accepted for parity with the other modes; defaults to `[]`.
+     */
+    customerDnsServers?: string[];
+}
+export type CreateSingleTenancyVpcParams = CreateVpcGcpPeeringParams | CreateVpcGcpNetworkAttachmentParams | CreateVpcAwsPrivateLinkParams;
 /**
  * Full create payload — VPC connectivity plus optional dedicated node pool.
  * The {@link CreateSingleTenancyVpcParams} discriminated union still drives
@@ -79,15 +140,26 @@ export type CreateSingleTenancyConfigOpts = CreateSingleTenancyVpcParams & {
 /**
  * Patch payload for an existing single tenancy config.
  * Only the safe-to-edit fields are exposed; `vpc.type`, `vpc.proxyIp`,
- * `vpc.gcpProjectId`, `vpc.gcpNetworkName`, `vpc.networkAttachmentName`, and
- * `vpc.bridgeCidr` are immutable because changing them would diverge from
- * already-provisioned infrastructure.
+ * `vpc.gcpProjectId`, `vpc.gcpNetworkName`, `vpc.networkAttachmentName`,
+ * `vpc.bridgeCidr`, and `vpc.awsRegion` are immutable because changing them
+ * would diverge from already-provisioned infrastructure.
  */
 export interface UpdateSingleTenancyConfigOpts {
     enabled?: boolean;
     customerDnsServers?: string[];
     importCustomRoutes?: boolean;
     dedicatedNodePool?: DedicatedNodePoolConfig | null;
+    /**
+     * `aws-privatelink` only. Full declarative replacement of the endpoint list,
+     * reconciled server-side by `serviceName`: an existing name keeps its allocated
+     * `ipIndex` with hostnames and ports updated in place, a new name gets a fresh
+     * index, and an omitted name is removed. An empty array is valid and means the
+     * customer removed their last service.
+     *
+     * Declarative rather than add/remove verbs so it mirrors the diff-driven,
+     * `serviceName`-keyed terraform model and stays idempotent under retry.
+     */
+    endpoints?: CreatePrivateLinkEndpointParams[];
 }
 /** Status of a single provisioned VPC resource (bridge VPC, proxy VM, etc.). */
 export interface SingleTenancyLiveCheck {
@@ -97,23 +169,102 @@ export interface SingleTenancyLiveCheck {
     resourceName?: string;
     resourceType?: string;
 }
-/**
- * Aggregated live status of the resources backing a VPC connection. Which
- * checks are present depends on the connection type: peering configs report
- * `bridgeVpc`/`proxyVm`/`peering`, network-attachment configs report
- * `proxyVm`/`networkAttachment`.
- */
-export interface SingleTenancyLiveStatus {
-    bridgeVpc?: SingleTenancyLiveCheck;
+/** The one check every connection type reports: each gets a proxy VM. */
+interface LiveStatusBase {
+    type: string;
     proxyVm?: SingleTenancyLiveCheck;
+}
+/** Bridge VPC on our side, plus the peering between it and the customer's. */
+export interface LiveStatusGcpPeering extends LiveStatusBase {
+    type: "gcp-peering";
+    bridgeVpc?: SingleTenancyLiveCheck;
     peering?: SingleTenancyLiveCheck;
+}
+/** The customer-owned network attachment our proxy VM's nic1 connects to. */
+export interface LiveStatusGcpNetworkAttachment extends LiveStatusBase {
+    type: "gcp-network-attachment";
     networkAttachment?: SingleTenancyLiveCheck;
 }
+export interface LiveStatusAwsPrivateLink extends LiveStatusBase {
+    type: "aws-privatelink";
+    /**
+     * One entry per configured endpoint, because PrivateLink is per-service: each
+     * endpoint is its own interface VPC Endpoint with its own ENIs, security group
+     * and AWS state. `resourceName` carries the endpoint's `serviceName`, except on
+     * the single aggregate row {@link buildErrorLiveStatus} emits when the live
+     * lookup itself failed.
+     */
+    endpoints?: SingleTenancyLiveCheck[];
+}
+/**
+ * Aggregated live status of the resources backing a VPC connection, discriminated
+ * on the same `type` as {@link VpcConnection} so which checks exist is known at
+ * compile time rather than by convention. A flat superset would let a consumer
+ * read `bridgeVpc` off an AWS status, or let a producer emit endpoint rows for a
+ * peering config.
+ *
+ * A new connection mode adds a variant. Plurality is a property of the resource,
+ * not of AWS: an HA VPN mode would report an array of tunnels and BGP peers.
+ */
+export type SingleTenancyLiveStatus = LiveStatusGcpPeering | LiveStatusGcpNetworkAttachment | LiveStatusAwsPrivateLink;
 /** Computed infrastructure resource names derived from a config id/type. */
 export interface SingleTenancyDerivedNames {
     bridgeVpcName?: string;
     proxyVmName?: string;
     bridgePeeringName?: string;
     networkAttachmentName?: string;
+    /** `aws-privatelink`: serviceName → the endpoint's terraform `Name` tag. */
+    privateLinkEndpointNames?: Record<string, string>;
+    /** `aws-privatelink`: serviceName → the endpoint's pinned ENI IPs, one per AZ. */
+    privateLinkEndpointIps?: Record<string, string[]>;
 }
+/**
+ * The single AWS region Builder's PrivateLink infrastructure runs in. Keep in
+ * sync with the `aws` provider region in packages/terraform/main.tf — an Endpoint
+ * Service in another region is unreachable by our interface endpoints.
+ */
+export declare const BUILDER_AWS_REGION = "us-east-1";
+/**
+ * AWS-generated VPC Endpoint Service name: `com.amazonaws.vpce.<region>.vpce-svc-<id>`.
+ * The id is 8 or 17 hex chars — AWS resource ids are never a length in between.
+ */
+export declare const PRIVATELINK_SERVICE_NAME_RE: RegExp;
+/**
+ * Bounds for a `PrivateLinkEndpoint.ipIndex`. AWS reserves the first four and the
+ * last address of every subnet, so an out-of-range index passes terraform's
+ * `cidrhost()` but fails at apply.
+ */
+export declare const PRIVATELINK_MIN_IP_INDEX = 4;
+export declare const PRIVATELINK_MAX_IP_INDEX = 4094;
+/**
+ * Parses a pasted VPC Endpoint Service name, deriving the region embedded in it.
+ * Returns `null` for a malformed name. Callers reject a region that isn't
+ * {@link BUILDER_AWS_REGION} themselves, so the two failures get distinct messages.
+ */
+export declare function parsePrivateLinkServiceName(raw: string): {
+    serviceName: string;
+    awsRegion: string;
+} | null;
+/**
+ * Whether a VPC connection can carry pod traffic anywhere at all — the bar for
+ * pointing an organization's workloads at it.
+ *
+ * A running proxy VM is not that bar for `aws-privatelink`. Its egress policy
+ * table is built entirely from the configured endpoints, with `blackhole default`
+ * underneath, so a connection with an empty `endpoints` array yields a VM that
+ * drops *every* packet a pod sends — not just traffic to whichever service was
+ * removed. The two GCP flavors have no such state: egress leaves through nic1 into
+ * the customer's network, which exists as soon as the connection does.
+ *
+ * An empty endpoint list is a legitimate thing to store (a customer removing their
+ * last service), so this gates routing rather than rejecting the write.
+ *
+ * Takes the two fields it reads rather than a {@link VpcConnection}, so the staff
+ * app can pass its flattened list item — where `type` and `endpoints` are hoisted
+ * to the top level — without a cast.
+ */
+export declare function canCarryPodTraffic(vpc: {
+    type?: VpcConnection["type"];
+    endpoints?: readonly unknown[];
+} | undefined): boolean;
 export {};

package/src/single-tenancy.js

@@ -1 +1,59 @@
-export {};
+/**
+ * The single AWS region Builder's PrivateLink infrastructure runs in. Keep in
+ * sync with the `aws` provider region in packages/terraform/main.tf — an Endpoint
+ * Service in another region is unreachable by our interface endpoints.
+ */
+export const BUILDER_AWS_REGION = "us-east-1";
+/**
+ * AWS-generated VPC Endpoint Service name: `com.amazonaws.vpce.<region>.vpce-svc-<id>`.
+ * The id is 8 or 17 hex chars — AWS resource ids are never a length in between.
+ */
+export const PRIVATELINK_SERVICE_NAME_RE = /^com\.amazonaws\.vpce\.([a-z0-9-]+)\.vpce-svc-(?:[0-9a-f]{8}|[0-9a-f]{17})$/;
+/**
+ * Bounds for a `PrivateLinkEndpoint.ipIndex`. AWS reserves the first four and the
+ * last address of every subnet, so an out-of-range index passes terraform's
+ * `cidrhost()` but fails at apply.
+ */
+export const PRIVATELINK_MIN_IP_INDEX = 4;
+export const PRIVATELINK_MAX_IP_INDEX = 4094;
+/**
+ * Parses a pasted VPC Endpoint Service name, deriving the region embedded in it.
+ * Returns `null` for a malformed name. Callers reject a region that isn't
+ * {@link BUILDER_AWS_REGION} themselves, so the two failures get distinct messages.
+ */
+export function parsePrivateLinkServiceName(raw) {
+    const serviceName = raw.trim();
+    const match = serviceName.match(PRIVATELINK_SERVICE_NAME_RE);
+    if (!(match === null || match === void 0 ? void 0 : match[1])) {
+        return null;
+    }
+    return { serviceName, awsRegion: match[1] };
+}
+/**
+ * Whether a VPC connection can carry pod traffic anywhere at all — the bar for
+ * pointing an organization's workloads at it.
+ *
+ * A running proxy VM is not that bar for `aws-privatelink`. Its egress policy
+ * table is built entirely from the configured endpoints, with `blackhole default`
+ * underneath, so a connection with an empty `endpoints` array yields a VM that
+ * drops *every* packet a pod sends — not just traffic to whichever service was
+ * removed. The two GCP flavors have no such state: egress leaves through nic1 into
+ * the customer's network, which exists as soon as the connection does.
+ *
+ * An empty endpoint list is a legitimate thing to store (a customer removing their
+ * last service), so this gates routing rather than rejecting the write.
+ *
+ * Takes the two fields it reads rather than a {@link VpcConnection}, so the staff
+ * app can pass its flattened list item — where `type` and `endpoints` are hoisted
+ * to the top level — without a cast.
+ */
+export function canCarryPodTraffic(vpc) {
+    var _a;
+    if (!(vpc === null || vpc === void 0 ? void 0 : vpc.type)) {
+        return false;
+    }
+    if (vpc.type === "aws-privatelink") {
+        return ((_a = vpc.endpoints) !== null && _a !== void 0 ? _a : []).length > 0;
+    }
+    return true;
+}

package/src/single-tenancy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/src/single-tenancy.test.js

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { BUILDER_AWS_REGION, canCarryPodTraffic, parsePrivateLinkServiceName, } from "./single-tenancy";
+describe("parsePrivateLinkServiceName", () => {
+    it("parses a current-format (17 hex char) service name", () => {
+        expect(parsePrivateLinkServiceName("com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0")).toEqual({
+            serviceName: "com.amazonaws.vpce.us-east-1.vpce-svc-0123456789abcdef0",
+            awsRegion: "us-east-1",
+        });
+    });
+    it("parses a legacy-format (8 hex char) service name", () => {
+        var _a;
+        expect((_a = parsePrivateLinkServiceName("com.amazonaws.vpce.us-east-1.vpce-svc-0123abcd")) === null || _a === void 0 ? void 0 : _a.awsRegion).toBe("us-east-1");
+    });
+    it("trims surrounding whitespace from a pasted value", () => {
+        expect(parsePrivateLinkServiceName("  com.amazonaws.vpce.us-east-1.vpce-svc-0123abcd\n")).toEqual({
+            serviceName: "com.amazonaws.vpce.us-east-1.vpce-svc-0123abcd",
+            awsRegion: "us-east-1",
+        });
+    });
+    it("derives a region other than ours rather than rejecting it, so callers can report the two failures differently", () => {
+        const parsed = parsePrivateLinkServiceName("com.amazonaws.vpce.us-west-2.vpce-svc-0123456789abcdef0");
+        expect(parsed === null || parsed === void 0 ? void 0 : parsed.awsRegion).toBe("us-west-2");
+        expect(parsed === null || parsed === void 0 ? void 0 : parsed.awsRegion).not.toBe(BUILDER_AWS_REGION);
+    });
+    it("rejects an id length between the two valid formats", () => {
+        expect(parsePrivateLinkServiceName("com.amazonaws.vpce.us-east-1.vpce-svc-0123456789")).toBeNull();
+    });
+    it("rejects a missing vpce-svc- prefix", () => {
+        expect(parsePrivateLinkServiceName("com.amazonaws.vpce.us-east-1.0123abcd")).toBeNull();
+    });
+    it("rejects an interface endpoint id in place of a service id", () => {
+        expect(parsePrivateLinkServiceName("com.amazonaws.vpce.us-east-1.vpce-0123456789abcdef0")).toBeNull();
+    });
+    it("rejects uppercase, since AWS service names are always lowercase", () => {
+        expect(parsePrivateLinkServiceName("com.amazonaws.vpce.us-east-1.vpce-svc-0123ABCD")).toBeNull();
+    });
+    it("rejects a GCP network attachment URI", () => {
+        expect(parsePrivateLinkServiceName("projects/acme/regions/us-central1/networkAttachments/builder-connection")).toBeNull();
+    });
+    it("rejects an empty string", () => {
+        expect(parsePrivateLinkServiceName("")).toBeNull();
+        expect(parsePrivateLinkServiceName("   ")).toBeNull();
+    });
+});
+describe("canCarryPodTraffic", () => {
+    const awsVpc = (endpoints) => ({
+        type: "aws-privatelink",
+        awsRegion: "us-east-1",
+        proxyIp: "10.64.0.10",
+        customerDnsServers: [],
+        endpoints,
+    });
+    it("rejects an aws-privatelink connection with no endpoints", () => {
+        // Its proxy VM runs, but the policy table is `blackhole default` and nothing
+        // else, so pointing an org at it drops every packet its pods send.
+        expect(canCarryPodTraffic(awsVpc([]))).toBe(false);
+    });
+    it("accepts an aws-privatelink connection with an endpoint", () => {
+        expect(canCarryPodTraffic(awsVpc([
+            {
+                serviceName: "com.amazonaws.vpce.us-east-1.vpce-svc-000000000000000a0",
+                hostnames: ["db.internal"],
+                ports: [5432],
+                ipIndex: 7,
+            },
+        ]))).toBe(true);
+    });
+    it("treats a document with no endpoints key like an empty list", () => {
+        const { endpoints: _omitted, ...withoutEndpoints } = awsVpc([]);
+        expect(canCarryPodTraffic(withoutEndpoints)).toBe(false);
+    });
+    it("accepts both GCP flavors, whose egress exists as soon as the config does", () => {
+        // Typed as VpcConnection rather than passed inline, so this also pins that a
+        // full connection object satisfies the narrowed parameter.
+        const peering = {
+            type: "gcp-peering",
+            gcpProjectId: "p",
+            gcpNetworkName: "n",
+            bridgeCidr: "10.12.0.0/29",
+            importCustomRoutes: false,
+            proxyIp: "10.64.0.11",
+            customerDnsServers: [],
+        };
+        const attachment = {
+            type: "gcp-network-attachment",
+            gcpProjectId: "p",
+            networkAttachmentName: "builder-connection",
+            proxyIp: "10.64.0.12",
+            customerDnsServers: [],
+        };
+        expect(canCarryPodTraffic(peering)).toBe(true);
+        expect(canCarryPodTraffic(attachment)).toBe(true);
+    });
+    it("rejects a config with no VPC connectivity at all", () => {
+        expect(canCarryPodTraffic(undefined)).toBe(false);
+    });
+});