venafi-connector-machine 1.0.4 → 1.0.5

package/bundle.mjs

@@ -30802,22 +30802,83 @@ Here, the first three types all come from the same data source (keystores), but
 
 **Key: choosing the right categories.** Ask: "How would an admin of this platform describe their certificates?" For FortiGate, it's by service type (VPN, firewall, management). For APIC, it's by infrastructure role (gateway, backend, unassigned, consumer). For F5, it might be by partition or virtual server type. The checkboxes should match the admin's mental model.
 
-**Implementation \u2014 binding metadata:**
+**Implementation \u2014 binding metadata with per-type dropdown fields:**
 
-Use \`BindingType\` (service category) + \`TargetName\` (specific named object) as the binding fields:
-- For singleton/global services (admin HTTPS, SSL VPN): set \`TargetName\` to \`"(global setting)"\` so the UI doesn't show an empty field
-- For named services (IPsec tunnels, VIPs, profiles): set \`TargetName\` to the actual object name
+Instead of a generic \`targetName\` field, use **per-type dropdown fields** that are conditionally shown based on \`bindingType\`. Each field links to the \`getTargetConfiguration\` response via \`x-targetConfigurationRef\`, creating actual dropdowns populated from the target system:
+
+\`\`\`json
+"binding": {
+    "properties": {
+        "bindingType": {
+            "oneOf": [
+                { "const": "management", "x-labelLocalizationKey": "bindingType.management" },
+                { "const": "https-listener", "x-labelLocalizationKey": "bindingType.httpsListener" },
+                { "const": "outbound-tls", "x-labelLocalizationKey": "bindingType.outboundTls" }
+            ]
+        },
+        "vipName": {
+            "type": "string",
+            "default": "",
+            "x-targetConfigurationRef": "/vips",
+            "x-rule": {
+                "effect": "SHOW",
+                "condition": { "scope": "#/properties/bindingType", "schema": { "const": "https-listener" } }
+            }
+        },
+        "tunnelName": {
+            "type": "string",
+            "default": "",
+            "x-targetConfigurationRef": "/ipsecTunnels",
+            "x-rule": {
+                "effect": "SHOW",
+                "condition": { "scope": "#/properties/bindingType", "schema": { "const": "outbound-tls" } }
+            }
+        },
+        "guiPath": {
+            "type": "string",
+            "default": "",
+            "readOnly": true,
+            "x-hidden": true
+        }
+    },
+    "x-primaryKey": ["#/bindingType", "#/vipName", "#/tunnelName", "#/guiPath"]
+}
+\`\`\`
+
+Key features of this pattern:
+- **\`x-targetConfigurationRef\`** links a field to a JSON path in the \`getTargetConfiguration\` response, populating a dropdown
+- **\`x-rule\` with \`"effect": "SHOW"\`** conditionally displays each field only when the relevant \`bindingType\` is selected
+- **\`default: ""\`** on every \`x-primaryKey\` field \u2014 CRITICAL for net new certificate provisioning (see section 30)
+- **\`x-hidden: true\`** hides metadata-only fields (like guiPath) from the provisioning UI while keeping them in the schema
+- Singleton types (management, SSL VPN) don't need a named target \u2014 the dropdown field stays hidden and empty
+- Named-target types (VIP, tunnel, profile) show a dropdown populated from the target system
 
 **Implementation \u2014 buildBindingMap:**
 
-Query each service endpoint selectively based on the user's \`discoveryTypes\` selection. Build a \`map[string][]domain.Binding\` keyed by certificate name. Then when constructing discovery results, look up each cert's bindings and attach them as machine identities. Certs without bindings still get reported (with an empty binding) so they appear in Venafi.
+Query each service endpoint selectively based on the user's \`discoveryTypes\` selection. Build a \`map[string][]domain.Binding\` keyed by certificate name. Then when constructing discovery results, look up each cert's bindings and attach them as machine identities. Certs without bindings still get reported (with a fallback "unbound" binding) so they appear in Venafi.
 
-**Key manifest features:**
-- \`x-rule\` with \`effect: "SHOW"\` on \`targetName\` \u2014 hide it for singleton types where there's no named object to select
-- \`x-primaryKey: ["#/bindingType", "#/targetName"]\` \u2014 uniquely identifies each binding
-- \`discoveryTypes\` uses \`uniqueItems: true\` to prevent duplicate selections
+**Implementation \u2014 provisioning dispatch:**
 
-**Why this matters**: Without discovery type filtering, every discovery run queries all service endpoints, which can be slow and return unwanted results. Without rich binding metadata, users can't tell which service a certificate is associated with or whether an empty "Target Name" field is intentional.
+In \`configureInstallationEndpoint\`, dispatch based on \`bindingType\` and the per-type field values:
+
+\`\`\`go
+switch binding.BindingType {
+case "https-listener":
+    if binding.VipName == "" {
+        return handler.SetSSLVPNServerCert(certName) // global SSL VPN
+    }
+    return handler.SetVIPCertificate(binding.VipName, certName) // specific VIP
+case "outbound-tls":
+    if binding.TunnelName == "" {
+        return fmt.Errorf("tunnelName is required for outbound-tls")
+    }
+    return handler.SetIPsecCertificate(binding.TunnelName, certName)
+}
+\`\`\`
+
+This eliminates guiPath-based dispatch and gives users explicit dropdown selection for each target type.
+
+**Why this matters**: Without per-type dropdowns, users must type exact target names from memory. With \`x-targetConfigurationRef\`, they get a dropdown populated from the actual target system \u2014 reducing errors and improving the provisioning UX significantly.
 
 ### 15. Onboard Discovery vs Network Discovery \u2014 Don't Report What You Can't Observe
 
@@ -31004,30 +31065,35 @@ With catalog-level enrichment, BOTH entries show: Product = "Product Discovery,
 \`\`\`go
 // matchProfileToProduct matches a TLS profile to a specific product
 // by checking if the profile title starts with a product title.
-// Falls back to all catalog products if no match found.
+// Returns empty strings if no match (caller defaults to "N/A").
+// NEVER fall back to catalog-level aggregates \u2014 a catalog with 1786 APIs
+// produces an ~80KB string that gets duplicated into every binding,
+// causing 1MB Kafka message limit failures on satellite\u2192platform transport.
 func matchProfileToProduct(profileTitle string, cp catalogProductInfo) (string, string) {
     if profileTitle != "" {
         for _, pd := range cp.Products {
             if strings.HasPrefix(profileTitle, pd.Title) {
-                return pd.Title, strings.Join(pd.ApiTitles, ", ")
+                apiStr := strings.Join(pd.ApiTitles, ", ")
+                return pd.Title, truncateMetadata(apiStr, len(pd.ApiTitles))
             }
         }
     }
-    return cp.AllProductNames, cp.AllApiNames
+    return "", ""  // caller sets "N/A" defaults
 }
 \`\`\`
 
 **Implementation requirements**:
-1. \`buildCatalogProductMap\` must return per-product detail (title + API list), not just catalog-level aggregates
+1. \`buildCatalogProductMap\` must return per-product detail (title + API list) \u2014 do NOT store catalog-level aggregate strings (\`AllProductNames\`, \`AllApiNames\`)
 2. Products have \`api_urls\` referencing their APIs \u2014 resolve these against the API list to get per-product API titles
 3. The matching uses \`strings.HasPrefix\` on the profile title vs product title \u2014 reliable for standard naming conventions
-4. Fallback to catalog-level aggregates when no product matches (backends, internal profiles)
+4. **NEVER fall back to catalog-level aggregates** \u2014 return empty strings (caller defaults to "N/A"). Catalog-level aggregates were the root cause of 1MB Kafka limit failures in production (a single catalog with 1786 APIs produced 80KB strings duplicated into every binding, creating 2MB+ pages that were silently dropped)
 
 **Result after fix**:
 - \`tls-gw-product-discovery\` \u2192 Product = "Product Discovery", APIs = "Product Catalog API"
 - \`tls-gw-customer-platform\` \u2192 Product = "Customer Platform", APIs = "Customer API, Order API"
+- Unmatched profiles \u2192 Product = "N/A", APIs = "N/A" (safe, small, and honest)
 
-**Why this matters**: When users see duplicate-looking entries in the Venafi UI, they can't determine which platform service each certificate installation belongs to. Discovery should provide the MOST SPECIFIC context available for each binding, not the same generic data for all.
+**Why this matters**: When users see duplicate-looking entries in the Venafi UI, they can't determine which platform service each certificate installation belongs to. Discovery should provide the MOST SPECIFIC context available for each binding. If no specific match exists, "N/A" is better than dumping every product/API in the catalog \u2014 which is both misleading and a response size bomb.
 
 ### 21. CRITICAL: Discovery Field Labels \u2014 title vs x-labelLocalizationKey
 
@@ -31500,6 +31566,317 @@ dc := &DiscoveredCertificate{
 \`\`\`
 
 **Alternative**: Use a pointer with \`omitempty\` if the field is truly optional. But for \`certificateChain\` and \`machineIdentities\`, always send \`[]\` rather than omitting or sending \`null\`.
+
+### 29. CRITICAL: Discovery Response Size \u2014 1MB Kafka Limit and Metadata String Inflation
+
+**The symptom**: Discovery completes page 1 successfully (connector logs show valid response with \`hasMorePages:true\` and correct paginator), but the platform never requests page 2. The discovery job stays in RUNNING state forever. No errors appear in the connector logs \u2014 the response write succeeds from the connector's perspective.
+
+**The root cause**: The vSatellite relays discovery responses to the Venafi platform via **Kafka**, which has a **1MB message size limit**. When the response exceeds this limit, the message is silently dropped. The platform never receives the response (including the pagination token) and never requests the next page. Note: the connector communicates with the satellite over HTTP, and the satellite communicates with the platform over Kafka \u2014 so the connector never sees the Kafka rejection.
+
+**How responses get inflated**: The #1 cause is **metadata string duplication in bindings**. Never enrich bindings with aggregated catalog-level or scope-level data (e.g., all product names or all API titles). In production, a single catalog had 1786 APIs \u2014 joining all titles into one string produced ~80KB that got copied into every binding. With 25 certs per page, that's 2MB+ just from API names, far exceeding the 1MB Kafka limit.
+
+**How we discovered this**: We reproduced the issue by injecting 1786 fake API names into the enrichment path. The response grew to 2.1MB per page of 25 certs, and the Venafi platform silently stopped paginating \u2014 exactly matching the customer's symptom. Without the injection (our 9-API test environment), pages were 54KB and pagination worked perfectly.
+
+**The fix \u2014 only enrich on exact match, never aggregate**:
+
+The root cause was a fallback path in \`matchProfileToProduct\` that dumped ALL product/API names from the entire catalog into every binding that didn't match a specific product. The fix is simple: **if you can't match to a specific item, return empty/default values ("N/A"), never aggregate**.
+
+\`\`\`go
+// CORRECT: Only return metadata on exact match. Default to empty (caller sets "N/A").
+func matchProfileToProduct(profileTitle string, cp catalogProductInfo) (string, string) {
+    if profileTitle != "" {
+        for _, pd := range cp.Products {
+            if strings.HasPrefix(profileTitle, pd.Title) {
+                apiStr := strings.Join(pd.ApiTitles, ", ")
+                return pd.Title, truncateMetadata(apiStr, len(pd.ApiTitles))
+            }
+        }
+    }
+    return "", ""  // caller defaults to "N/A"
+}
+
+// WRONG: Never fall back to catalog-level aggregates
+// return cp.AllProductNames, cp.AllApiNames  // <-- THIS CAUSED 2MB+ PAGES
+\`\`\`
+
+**Defense in depth \u2014 truncateMetadata for exact matches**: Even a single product can have many APIs, so apply \`truncateMetadata()\` to cap any metadata string at 200 chars:
+
+\`\`\`go
+const maxMetadataFieldLen = 200
+
+func truncateMetadata(s string, totalCount int) string {
+    if len(s) <= maxMetadataFieldLen {
+        return s
+    }
+    cut := strings.LastIndex(s[:maxMetadataFieldLen], ",")
+    if cut <= 0 {
+        cut = maxMetadataFieldLen
+    }
+    shown := strings.Count(s[:cut], ",") + 1
+    return fmt.Sprintf("%s (+%d more)", s[:cut], totalCount-shown)
+}
+\`\`\`
+
+**Additional defensive measures**:
+1. **Keep page size small**: Use \`maxPageSize = 10\` to provide headroom against the 1MB Kafka limit
+2. **Do not store catalog-level aggregate strings**: The \`catalogProductInfo\` struct should only hold per-product detail (\`[]productDetail\`), never \`AllProductNames\` or \`AllApiNames\` aggregate fields \u2014 if those fields exist, someone will use them in a fallback
+3. **Single marshal + JSONBlob**: Marshal the response once, use \`c.JSONBlob()\` to send. Avoids double-allocating multi-MB responses
+4. **Profile every page**: Log \`responseSizeBytes\`, \`maxBindingApiNamesLen\`, \`avgMIBytes\`, and \`totalMIJSONBytes\` per batch to detect inflation early
+
+**Key insight**: This failure is invisible to the connector. The HTTP response write succeeds (Echo sends the bytes to the satellite), but Kafka silently drops the oversized message before it reaches the platform. The platform never sees the response and never requests the next page. The only way to detect it is by checking \`responseSizeBytes\` in the connector logs and comparing against the 1MB Kafka limit.
+
+**Rule of thumb**: Keep \`responseSizeBytes\` well under 1MB per page. If it exceeds 500KB, investigate immediately. Never put aggregated/unbounded strings into binding metadata \u2014 if you can't match to a specific item, use "N/A".
+
+### 30. CRITICAL: x-primaryKey Fields MUST Have default Values for Net New Provisioning
+
+**The symptom**: Provisioning an existing (discovered) certificate works fine \u2014 the certificate is pushed to the target and the binding is configured. But provisioning a **net new certificate** (one that was not previously discovered) stalls indefinitely. The Venafi UI shows the provisioning job as RUNNING but it never completes.
+
+**The root cause**: When provisioning a net new certificate, the Venafi platform constructs the binding from the manifest schema. If any \`x-primaryKey\` field lacks a \`"default"\` value, the platform returns error **20106**: *"property X is a primary key but is not specified in request and has no default value"*. This error is NOT visible in the connector logs \u2014 it happens platform-side before the request ever reaches the connector.
+
+**Why discovered certs work**: When re-provisioning a discovered certificate, the binding already has values for all fields (populated during discovery). The \`default\` is only needed when the platform must construct a binding from scratch.
+
+**The fix**: Every field in \`x-primaryKey\` MUST have a \`"default"\` value in the manifest schema:
+
+\`\`\`json
+"binding": {
+    "properties": {
+        "bindingType": { "oneOf": [...] },
+        "vipName": { "type": "string", "default": "" },
+        "tunnelName": { "type": "string", "default": "" },
+        "profileName": { "type": "string", "default": "" },
+        "guiPath": { "type": "string", "default": "", "readOnly": true, "x-hidden": true }
+    },
+    "x-primaryKey": ["#/bindingType", "#/vipName", "#/tunnelName", "#/profileName", "#/guiPath"]
+}
+\`\`\`
+
+**Debugging checklist** when net new provisioning stalls:
+1. Check if provisioning of previously-discovered certs works (if yes, this is likely the issue)
+2. Look for error 20106 in the Venafi platform activity log (\`POST /v1/activitylogsearch\`)
+3. Verify every \`x-primaryKey\` field has a \`"default"\` in the manifest
+4. Deploy a new plugin revision with the defaults added
+
+### 31. CRITICAL: PKCS12 Must Use Legacy Encoding for Network Appliances
+
+**The mistake**: Using modern PKCS12 encoding (AES-256-CBC + SHA-256) when building PKCS12 bundles for certificate import to network appliances.
+
+**The problem**: Many network appliances (FortiGate confirmed, likely F5 and others) cannot parse modern PKCS12 encoding. The import API returns success or a vague error, but the certificate is not usable. FortiGate specifically requires the legacy PKCS12 format (3DES + SHA1).
+
+**The fix**: When building PKCS12 bundles in Go, use the Legacy encoder:
+
+\`\`\`go
+import gopkcs12 "software.sslmate.com/src/go-pkcs12"
+
+// CORRECT: Legacy encoding (3DES/SHA1) \u2014 compatible with network appliances
+p12Data, err := gopkcs12.Legacy.Encode(key, cert, caCerts, password)
+
+// WRONG: Modern encoding (AES-256/SHA-256) \u2014 rejected by FortiGate and similar appliances
+// p12Data, err := gopkcs12.Modern.Encode(key, cert, caCerts, password)
+\`\`\`
+
+**Why this happens**: The \`go-pkcs12\` library defaults to \`Modern\` encoding which uses AES-256-CBC and SHA-256. While more secure, this format is not supported by older TLS stacks. Network appliances typically use OpenSSL 1.x-era PKCS12 parsing that only understands the legacy 3DES/SHA1 format.
+
+**Recommendation**: Always use \`gopkcs12.Legacy.Encode()\` for any connector targeting a network appliance. Only consider \`Modern\` for targets you've explicitly verified support it.
+
+### 32. x-hidden Hides Manifest Fields from Provisioning UI
+
+**The pattern**: When a binding field is needed for schema purposes (\`x-primaryKey\`) but should not be shown to users during provisioning, use \`"x-hidden": true\`:
+
+\`\`\`json
+"guiPath": {
+    "type": "string",
+    "default": "",
+    "readOnly": true,
+    "x-hidden": true,
+    "x-labelLocalizationKey": "guiPath.label",
+    "x-rank": 4
+}
+\`\`\`
+
+This is useful for metadata fields populated by discovery (like a navigation path or internal ID) that provide context in the Venafi UI's installation detail view but shouldn't appear as an input field when a user is provisioning a new certificate.
+
+**Difference from readOnly**: \`readOnly: true\` alone still renders the field in the UI (as a non-editable input). \`x-hidden: true\` prevents it from rendering entirely.
+
+### 33. Image Digest, Not Tag, for vSatellite Deployments
+
+**The problem**: Using \`:latest\` tag in the plugin manifest's \`deployment.image\` field causes intermittent image pull failures on vSatellite, even after pushing a new image.
+
+**The root cause**: The vSatellite's k3s runtime caches images by digest. When the manifest specifies \`:latest\`, the satellite resolves it to a digest at pull time. If the registry mirror (via \`registries.yaml\`) rewrites or caches the digest resolution, subsequent pulls may fail with \`ErrImagePull\` due to digest mismatch.
+
+**The fix**: Always use \`image@sha256:...\` (digest reference) in the plugin manifest, never a tag:
+
+\`\`\`json
+"deployment": {
+    "image": "public.ecr.aws/example/connector@sha256:abc123...",
+    "executionTarget": "vsat"
+}
+\`\`\`
+
+Extract the digest from the build output:
+
+\`\`\`bash
+# After docker buildx push
+DIGEST=$(jq -r '.["containerimage.digest"]' buildx-digest.json)
+\`\`\`
+
+**Additional k3s gotcha**: The vSatellite's \`registries.yaml\` may have a catch-all mirror entry for \`registry.venafi.cloud\` that rewrites image pulls. If your image is in a public registry (e.g., public ECR), ensure that registry's mirror entry appears BEFORE the wildcard catch-all. A misplaced wildcard causes digest mismatch errors on pull.
+
+### 34. Plugin API \u2014 PATCH Not POST, pluginType at Top Level
+
+**When registering a connector on a new tenant**: Use \`POST /v1/plugins\` with \`pluginType\` at the top level alongside \`manifest\`:
+
+\`\`\`bash
+curl -X POST -H "tppl-api-key: $KEY" -H "Content-Type: application/json" \\
+  -d '{"pluginType": "MACHINE", "manifest": {...}}' \\
+  "https://api.venafi.cloud/v1/plugins"
+\`\`\`
+
+**When updating an existing plugin**: Use \`PATCH /v1/plugins/{id}\`. POST returns error **16004** if the plugin already exists.
+
+**Common mistake**: Putting \`pluginType\` inside the \`manifest\` object. The API requires it at the top level of the request body alongside \`manifest\`.
+
+### 35. x-targetConfigurationRef Powers Dropdown Fields from getTargetConfiguration
+
+**The pattern**: When your target system has enumerable resources (scopes, profiles, tunnels, virtual IPs, partitions), return them from the \`getTargetConfiguration\` endpoint and reference them in the manifest to create dropdown fields:
+
+**Step 1 \u2014 Define the targetConfiguration schema in manifest:**
+\`\`\`json
+"targetConfiguration": {
+    "properties": {
+        "vdoms": { "type": "array", "items": { "type": "string" } },
+        "vips": { "type": "array", "items": { "type": "string" } },
+        "tunnels": { "type": "array", "items": { "type": "string" } }
+    },
+    "type": "object"
+}
+\`\`\`
+
+**Step 2 \u2014 Return values from the Go handler:**
+\`\`\`go
+type GetTargetConfigurationResponse struct {
+    VDOMs   []string \`json:"vdoms"\`
+    VIPs    []string \`json:"vips"\`
+    Tunnels []string \`json:"tunnels"\`
+}
+\`\`\`
+
+**Step 3 \u2014 Reference in binding/keystore fields:**
+\`\`\`json
+"vipName": {
+    "type": "string",
+    "default": "",
+    "x-targetConfigurationRef": "/vips",
+    "x-rule": {
+        "effect": "SHOW",
+        "condition": { "scope": "#/properties/bindingType", "schema": { "const": "https-listener" } }
+    }
+}
+\`\`\`
+
+The JSON path in \`x-targetConfigurationRef\` (e.g., \`"/vips"\`) must match the key in your \`getTargetConfiguration\` response. The UI will populate a dropdown with the returned values.
+
+**Combine with x-rule**: Use \`x-rule\` to only show the dropdown when the relevant binding type is selected. This keeps the UI clean \u2014 users only see fields relevant to their selected binding type.
+
+**IMPORTANT limitation**: \`x-targetConfigurationRef\` dropdowns do NOT populate during net new provisioning in the Venafi UI. The platform only calls \`getTargetConfiguration\` for discovery workflows and when editing existing installations. During net new provisioning, these fields render as plain text boxes. Users must type the exact target name. Use \`oneOf\` in the manifest schema for fields that MUST always be dropdowns (like binding type, certificate type).
+
+### 36. CRITICAL: Duplicate Certificate Handling During Provisioning
+
+**The problem**: When provisioning is retried (due to timeouts, partial failures, or the user re-provisioning the same cert to a different binding), the target system may already have the certificate from a previous attempt. Attempting to import a certificate that already exists often returns an error (e.g., HTTP 500 "entry already exists").
+
+**The fix**: Before importing, always check if a certificate with the target name already exists on the system. If it does, skip the import and proceed to the binding step:
+
+\`\`\`go
+existingCerts, err := handler.GetCertificateDetails()
+if err == nil {
+    if certExistsByName(existingCerts, certName) {
+        log.Info("certificate already exists, skipping upload", "name", certName)
+        keystore.CertificateName = certName
+        return keystore, nil
+    }
+}
+\`\`\`
+
+**Name collision with different content**: If a cert with the same name exists but has different content (e.g., renewed cert), generate a unique name. Then check if THAT name also exists before importing \u2014 previous failed attempts may have already uploaded it:
+
+\`\`\`go
+// Name collision \u2014 generate unique name
+uniqueName := generateUniqueName(baseName, cert)
+// Check if the unique name also exists from a previous attempt
+if certExistsByName(existingCerts, uniqueName) {
+    log.Info("unique name also exists, skipping upload", "name", uniqueName)
+    keystore.CertificateName = uniqueName
+    return keystore, nil
+}
+// Safe to import with unique name
+\`\`\`
+
+**Key insight**: The Venafi platform retries provisioning workflows. Your connector MUST be idempotent \u2014 importing the same certificate twice should not fail.
+
+### 37. CRITICAL: Fingerprint Format Varies by Target System
+
+**The problem**: When comparing certificate fingerprints to detect duplicates, the target system may use a different hash algorithm than what you compute. For example, SHA-1 (40 hex chars) vs SHA-256 (64 hex chars), or different formatting (colons vs no colons, uppercase vs lowercase).
+
+**The fix**: Normalize fingerprints before comparing \u2014 strip colons, uppercase, and check that lengths match (same hash algorithm) before comparing values:
+
+\`\`\`go
+func fingerprintsMatch(a, b string) bool {
+    normA := strings.ToUpper(strings.ReplaceAll(a, ":", ""))
+    normB := strings.ToUpper(strings.ReplaceAll(b, ":", ""))
+    if normA == "" || normB == "" {
+        return false
+    }
+    if len(normA) != len(normB) {
+        return false // Different hash algorithms, can't compare
+    }
+    return normA == normB
+}
+\`\`\`
+
+If fingerprints can't be reliably compared (different hash algorithms), fall back to name-based duplicate detection rather than assuming the content is different.
+
+### 38. CRITICAL: Service-Disruptive Binding Changes Need Short Timeouts
+
+**The problem**: Some binding operations cause the target system to restart a service, which drops the HTTP connection used to make the API call. The connector blocks waiting for a response that will never arrive (TCP timeout can be 30-60+ seconds). Meanwhile, the Venafi platform's workflow engine times out waiting for the connector's HTTP response, causing a \`RETRY_STATE_TIMEOUT\` failure.
+
+**Examples**: Changing an admin/management HTTPS certificate, updating an SSL VPN certificate, rotating a load balancer listener cert.
+
+**The fix**: Use a short request timeout (5-10 seconds) for binding operations that are known to cause service restarts. Treat any network error as success, since the change was already applied before the connection dropped:
+
+\`\`\`go
+ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+defer cancel()
+
+resp, err := client.R().
+    SetContext(ctx).
+    SetBody(payload).
+    Put("/api/endpoint/that/restarts/service")
+if err != nil {
+    // Service restarted \u2014 the change was applied before the connection dropped.
+    log.Info("expected connection drop after binding change, treating as success")
+    return nil
+}
+\`\`\`
+
+**Why this matters**: The Venafi platform has its own timeout for workflow activities. If your connector blocks for 60 seconds waiting for a dead TCP connection, the platform will timeout and mark the provisioning as failed \u2014 even though the change succeeded on the target system.
+
+### 39. x-hidden Does NOT Hide Fields from the Provisioning UI
+
+**The problem**: Setting \`"x-hidden": true\` on a manifest field does NOT prevent it from appearing in the net new provisioning form. The field still renders as a text box.
+
+**What x-hidden actually does**: It may only affect discovery result display or other non-provisioning contexts. The Venafi provisioning UI renders ALL fields defined in \`properties\`, regardless of \`x-hidden\`, \`readOnly\`, or other attributes.
+
+**What you CANNOT do**: Remove the field from \`properties\` if it's referenced in \`x-primaryKey\`. Doing so crashes the Venafi UI (blank page, user gets logged out). All \`x-primaryKey\` fields MUST exist in \`properties\`.
+
+**Workaround**: Accept that internal/metadata fields (like GUI navigation paths) will appear as read-only text boxes in the provisioning form. Use \`"readOnly": true\` to prevent user modification, and set \`"default": ""\` so net new provisioning works. This is cosmetic \u2014 it doesn't affect functionality.
+
+### 40. x-primaryKey Field Requirements \u2014 Summary
+
+All fields listed in \`x-primaryKey\` MUST:
+1. Exist in the \`properties\` object (removing them crashes the UI)
+2. Have \`"default": ""\` (or another default) \u2014 without a default, net new provisioning fails with error 20106
+3. Be of type \`"string"\` \u2014 complex types are not supported in primary keys
+
+The \`x-primaryKey\` array defines uniqueness for machine identity bindings during discovery. Every unique combination of primary key values creates a separate binding entry. For provisioning, unused primary key fields default to empty string.
 `;
 var MACHINE_MANIFEST_TEMPLATE = `
 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "venafi-connector-machine",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "MCP server providing machine connector-specific knowledge, templates, and tools for building Venafi TLS Protect Cloud machine connectors",
   "main": "bundle.mjs",
   "type": "module",