venafi-connector-machine 2.1.0 → 2.3.0

package/bundle.mjs

@@ -29951,11 +29951,11 @@ var StdioServerTransport = class {
 var MACHINE_BLUEPRINT = `
 # Venafi Machine Connector Blueprint
 
-This document captures the machine connector-specific architecture, patterns, and structure for building a Venafi TLS Protect Cloud machine connector. It is distilled from building multiple connectors: Splunk Enterprise (SSH), FortiGate (REST API), IBM API Connect (REST API), DataPower (REST API), and the Venafi Machine Connector Framework documentation.
+This document captures the machine connector-specific architecture, patterns, and structure for building a Venafi TLS Protect Cloud machine connector. It is distilled from building multiple connectors across SSH-based targets, REST API appliances, and API management platforms, as well as the Venafi Machine Connector Framework documentation.
 
 ## What Is a Machine Connector?
 
-A machine connector is a containerized Go REST service that runs on a Venafi vSatellite. It acts as middleware between Venafi TLS Protect Cloud and a target system (e.g., Splunk, Apache, Nginx, HAProxy, F5). The connector discovers certificates on the target, reports them to Venafi, and provisions/renews certificates when instructed.
+A machine connector is a containerized Go REST service that runs on a Venafi vSatellite. It acts as middleware between Venafi TLS Protect Cloud and a target system (e.g., web servers, app servers, load balancers, network appliances). The connector discovers certificates on the target, reports them to Venafi, and provisions/renews certificates when instructed.
 
 - **pluginType**: "MACHINE"
 - **workTypes**: ["PROVISIONING", "DISCOVERY"]
@@ -30213,7 +30213,7 @@ Keystore and binding fields can be turned into dropdowns populated from the targ
 2. Implementing \`getTargetConfiguration\` to return actual values (not a stub)
 3. Adding \`x-targetConfigurationRef\` to the field in keystore/binding
 
-**Example**: FortiGate VDOMs as a dropdown:
+**Example**: Virtual domains (partitions) as a dropdown:
 
 \`\`\`json
 "targetConfiguration": {
@@ -30236,7 +30236,7 @@ Keystore and binding fields can be turned into dropdowns populated from the targ
 }
 \`\`\`
 
-The F5 BIG-IP connector uses this same pattern for partition dropdowns.
+Other reference connectors use this same pattern for partition dropdowns.
 
 ## Project Structure (Proven Pattern)
 
@@ -30266,7 +30266,7 @@ The F5 BIG-IP connector uses this same pattern for partition dropdowns.
     \u2502   \u251C\u2500\u2500 discovery/                # Certificate discovery logic
     \u2502   \u2502   \u251C\u2500\u2500 discovery.go          # Main discovery orchestration
     \u2502   \u2502   \u2514\u2500\u2500 types.go              # Request/response types
-    \u2502   \u2514\u2500\u2500 <target>/                 # Target-specific logic (e.g., splunk/, apache/, nginx/)
+    \u2502   \u2514\u2500\u2500 <target>/                 # Target-specific logic (e.g., webserver/, appliance/)
     \u2502       \u251C\u2500\u2500 client.go             # Connection client abstraction (SSH, API, etc.)
     \u2502       \u251C\u2500\u2500 detect.go             # Target software detection
     \u2502       \u251C\u2500\u2500 install.go            # Certificate file writing
@@ -30356,7 +30356,7 @@ func New() *fx.App {
 var LESSONS_LEARNED = `
 # Lessons Learned: Machine Connector Projects
 
-This document captures everything that worked well, everything that was challenging, and every mistake or pitfall encountered while building machine connectors (Splunk SSH, FortiGate REST, IBM API Connect REST). Use this to avoid repeating mistakes and to replicate what worked.
+This document captures everything that worked well, everything that was challenging, and every mistake or pitfall encountered while building machine connectors across SSH-based targets and REST API appliances. Use this to avoid repeating mistakes and to replicate what worked.
 
 ---
 
@@ -30461,7 +30461,7 @@ This is critical for any values that come from user input (file paths, passwords
 
 **The reality**:
 - Venafi sends certificates in the \`CertificateBundle\` as **DER-encoded binary** (\`[]byte\`)
-- Most target systems (Splunk, Apache, Nginx) expect **PEM format** (text with BEGIN/END headers)
+- Most target systems (web servers, app servers) expect **PEM format** (text with BEGIN/END headers)
 - Discovery must return certificates in **PEM format** (text strings)
 
 **The fix**: Always use \`pem.EncodeToMemory()\` when converting from Venafi's DER format to files:
@@ -30581,7 +30581,7 @@ return c.String(http.StatusBadRequest, fmt.Sprintf("SSH connection failed: %s",
 
 ### 8. Config Parsing is Inherently Fragile
 
-**The issue**: Splunk's config files use an INI-like format, and our parser is basic:
+**The issue**: The target's config files use an INI-like format, and our parser is basic:
 
 \`\`\`go
 func parseINI(content string) map[string]map[string]string {
@@ -30590,34 +30590,34 @@ func parseINI(content string) map[string]map[string]string {
 \`\`\`
 
 **What it doesn't handle**:
-- Multi-line values (rare in Splunk but possible)
+- Multi-line values (rare but possible)
 - Escaped characters
 - Include directives
 - App-level configs (only reads system/local and system/default)
 
-**Why it worked anyway**: Splunk's SSL config is always simple key=value pairs. The basic parser handles 95%+ of real-world configs.
+**Why it worked anyway**: The target's SSL config is always simple key=value pairs. The basic parser handles 95%+ of real-world configs.
 
 **Recommendation for the next connector**: Match the parser complexity to the target's config format. If the target uses JSON/YAML, use Go's standard \`encoding/json\` or a YAML library. Don't build custom parsers for well-known formats.
 
 ### 9. Container Detection Based on Image Name
 
-**The issue**: Container Splunk detection uses \`grep -i splunk\` on the image name:
+**The issue**: Container detection uses \`grep -i <product>\` on the image name:
 
 \`\`\`go
-cs.RunCommand(client, fmt.Sprintf("%s ps --format '{{.Names}} {{.Image}}' | grep -i splunk", runtime))
+cs.RunCommand(client, fmt.Sprintf("%s ps --format '{{.Names}} {{.Image}}' | grep -i <product>", runtime))
 \`\`\`
 
-**The problem**: This misses containers with custom image names that don't include "splunk" and may false-positive on unrelated containers that happen to have "splunk" in the name.
+**The problem**: This misses containers with custom image names that don't include the product name and may false-positive on unrelated containers that happen to match.
 
 **Recommendation for next connector**: Be specific about what you're detecting. If the target software has a known process name, binary path, or config file, check for those inside the container rather than relying on image name.
 
 ### 10. GetTargetConfiguration Can Power Dynamic Dropdowns
 
-**The original issue**: The Splunk connector returned an empty response from \`getTargetConfiguration\`.
+**The original issue**: The SSH-based connector returned an empty response from \`getTargetConfiguration\`.
 
-**Updated learning from FortiGate**: \`getTargetConfiguration\` is NOT just a stub. It can return dynamic values that populate dropdown fields in the Venafi UI. This is done via \`x-targetConfigurationRef\` in the manifest.
+**Updated learning from a REST API appliance connector**: \`getTargetConfiguration\` is NOT just a stub. It can return dynamic values that populate dropdown fields in the Venafi UI. This is done via \`x-targetConfigurationRef\` in the manifest.
 
-**Pattern**: When the target has scopes/partitions/VDOMs, return them from \`getTargetConfiguration\`:
+**Pattern**: When the target has scopes/partitions/virtual domains, return them from \`getTargetConfiguration\`:
 
 \`\`\`go
 type GetTargetConfigurationResponse struct {
@@ -30646,7 +30646,7 @@ Then in the manifest, add a \`targetConfiguration\` domainSchema and reference t
 }
 \`\`\`
 
-This creates a dropdown in the keystore form populated with actual values from the target system. The F5 BIG-IP connector uses this same pattern for partition dropdowns.
+This creates a dropdown in the keystore form populated with actual values from the target system. Other reference connectors use this same pattern for partition dropdowns.
 
 **Recommendation**: Use \`getTargetConfiguration\` whenever the target has enumerable scopes, profiles, or resource lists that users need to select from. Keep it as a stub only if there's nothing dynamic to populate.
 
@@ -30663,7 +30663,7 @@ This creates a dropdown in the keystore form populated with actual values from t
 
 **The problem**: The Venafi platform silently rejects this format. Discovery appears to succeed but returns: "The webhook invocation for discovering certificates failed because the discovery result is empty."
 
-**The correct format** (confirmed by PAN Panorama, Citrix ADC, and FortiGate connectors):
+**The correct format** (confirmed by multiple reference connectors):
 
 \`\`\`json
 {
@@ -30688,9 +30688,9 @@ Key differences:
 
 **Why this is so dangerous**: The error message gives no clue about the wrong format. You'll spend hours debugging connectivity when the real issue is JSON structure. Always verify your response matches the types in the \`discovery-types.go\` template.
 
-### 12. Multi-Scope Discovery Pattern (VDOMs, Partitions, Tenants)
+### 12. Multi-Scope Discovery Pattern (Virtual Domains, Partitions, Tenants)
 
-**The pattern**: Many network appliances have scoping concepts (FortiGate VDOMs, F5 partitions, AVI tenants). Discovery should support both "discover all" and "discover specific scope."
+**The pattern**: Many network appliances have scoping concepts (virtual domains, partitions, tenants). Discovery should support both "discover all" and "discover specific scope."
 
 **Implementation**:
 1. The discovery request includes a scope field (e.g., \`vdom\`)
@@ -30737,7 +30737,7 @@ With localization: \`"vdomLabel": "VDOM (leave blank to discover all)"\`
 **What actually happens on network appliances**: Certificate data is split across APIs:
 - **Operational/Monitor APIs** return rich metadata (subject, issuer, serial number, fingerprint, validity dates) but NOT the PEM certificate content
 - **Configuration/CMDB APIs** return the actual PEM content, but only when fetching individual certificates \u2014 **batch/list endpoints strip heavy blob fields** to keep responses small
-- This split is common across FortiGate (CMDB vs Monitor), F5 BIG-IP (mgmt vs stats), and similar REST API appliances
+- This split is common across REST API appliances (e.g., CMDB vs Monitor endpoints, mgmt vs stats endpoints)
 
 **The symptom in Venafi**: Discovery succeeds with no errors from the connector, but the Venafi Cloud activity log shows: **"Discovered certificate cannot be read"** for every certificate. This means the \`certificate\` field in the discovery response is empty or not valid PEM. The platform accepted the \`messages\` format but couldn't parse the cert data inside.
 
@@ -30773,7 +30773,7 @@ for _, cert := range certDetails {
 
 **Two approaches based on target type:**
 
-**Approach A \u2014 Service-type filtering (FortiGate pattern):** For network appliances where certificates are assigned to different service types (admin HTTPS, SSL VPN, IPsec VPN, VIPs, SSL inspection), the \`discoveryTypes\` match the appliance's service categories:
+**Approach A \u2014 Service-type filtering (network appliance pattern):** For network appliances where certificates are assigned to different service types (admin HTTPS, SSL VPN, IPsec VPN, VIPs, SSL inspection), the \`discoveryTypes\` match the appliance's service categories:
 
 \`\`\`json
 "oneOf": [
@@ -30787,7 +30787,7 @@ for _, cert := range certDetails {
 
 These map 1:1 to the binding types. The connector queries only the selected service endpoints.
 
-**Approach B \u2014 Usage-based filtering (APIC pattern):** For API management platforms where certificates serve different infrastructure roles, the \`discoveryTypes\` match certificate usage categories that the admin would recognize from their platform:
+**Approach B \u2014 Usage-based filtering (API management platform pattern):** For API management platforms where certificates serve different infrastructure roles, the \`discoveryTypes\` match certificate usage categories that the admin would recognize from their platform:
 
 \`\`\`json
 "oneOf": [
@@ -30800,7 +30800,7 @@ These map 1:1 to the binding types. The connector queries only the selected serv
 
 Here, the first three types all come from the same data source (keystores), but are classified after enumeration based on how they're used. The fourth comes from a separate data source (consumer apps). This approach replaces a less intuitive "profileBoundOnly" toggle \u2014 unchecking "Unassigned Keystores" achieves the same filtering in platform-native terms.
 
-**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.
+**Key: choosing the right categories.** Ask: "How would an admin of this platform describe their certificates?" For a network appliance, it's by service type (VPN, firewall, management). For an API management platform, it's by infrastructure role (gateway, backend, unassigned, consumer). For a load balancer, it might be by partition or virtual server type. The checkboxes should match the admin's mental model.
 
 **Implementation \u2014 binding metadata with per-type dropdown fields:**
 
@@ -30902,9 +30902,9 @@ Reporting configuration-level TLS settings (what the platform *says* it supports
 - Regular fields (no readOnly) \u2014 same result: stored but invisible in the UI
 - Fields added to \`x-primaryKey\` \u2014 **visible** in the UI immediately
 
-**The rule**: The Venafi UI installation detail view renders ONLY the fields listed in the manifest's \`x-primaryKey\` arrays for both keystore and binding sections. No exceptions. No production connector (FortiGate, F5, Citrix ADC, A10) uses \`readOnly: true\` \u2014 all visible metadata goes through \`x-primaryKey\`.
+**The rule**: The Venafi UI installation detail view renders ONLY the fields listed in the manifest's \`x-primaryKey\` arrays for both keystore and binding sections. No exceptions. No production connector uses \`readOnly: true\` \u2014 all visible metadata goes through \`x-primaryKey\`.
 
-**Verification**: FortiGate shows \`certificateName\`, \`vdom\`, \`bindingType\`, and \`targetName\` in the UI \u2014 every one of them is in \`x-primaryKey\`. Fields not in \`x-primaryKey\` are never shown regardless of any other manifest attributes.
+**Verification**: Reference connectors show \`certificateName\`, \`vdom\`, \`bindingType\`, and \`targetName\` in the UI \u2014 every one of them is in \`x-primaryKey\`. Fields not in \`x-primaryKey\` are never shown regardless of any other manifest attributes.
 
 **What administrators actually want**: When a platform admin looks at Venafi, they want to see the same context they see in their platform admin UI:
 - **Certificate usage**: "api-gateway" vs "outbound-mtls" vs "keystore-only"
@@ -30941,7 +30941,7 @@ Reporting configuration-level TLS settings (what the platform *says* it supports
 **What actually happens with readOnly fields**:
 - The Venafi platform **stores** the data correctly (confirmed via REST API queries)
 - The Venafi UI **does NOT display** readOnly fields in the installation detail view
-- No production machine connector (FortiGate, F5, Citrix ADC, A10, PAN Panorama) uses \`readOnly: true\`
+- No production machine connector uses \`readOnly: true\`
 - The UI only renders fields listed in \`x-primaryKey\` (see section 16)
 
 **When readOnly might be useful**: Only for fields that are genuinely for internal use \u2014 like a platform UUID (\`keystoreId\`) used by the connector code during provisioning to target the correct resource, but not needed by human users in the UI. Even then, consider whether the field is worth including at all if users can't see it.
@@ -31042,7 +31042,7 @@ if binding.ApiNames == "" {
 4. Cross-reference with connector's discovery response \u2014 find MIs where a primaryKey field is empty
 5. Add a default value for the empty field, rebuild, and re-deploy
 
-**Proven defaults from APIC connector**:
+**Proven defaults from an API management platform connector**:
 - \`catalogName\`: "org-level" for keystores/profiles not deployed to any catalog
 - \`productName\`: "N/A" for catalogs without published products
 - \`apiNames\`: "N/A" for catalogs without published APIs
@@ -31060,7 +31060,7 @@ if binding.ApiNames == "" {
 
 With catalog-level enrichment, BOTH entries show: Product = "Product Discovery, Customer Platform", APIs = "Product Catalog API, Customer API, Order API". This is misleading and unhelpful.
 
-**The fix \u2014 Profile-level enrichment via title matching**: When the target platform doesn't provide a direct API-to-profile mapping (e.g., APIC's \`tls_client_profile_urls\` is empty on published APIs), use the TLS profile title as a heuristic to match against product names. Platform administrators typically follow naming conventions where profile titles encode the product/service context:
+**The fix \u2014 Profile-level enrichment via title matching**: When the target platform doesn't provide a direct API-to-profile mapping (e.g., the platform's \`tls_client_profile_urls\` is empty on published APIs), use the TLS profile title as a heuristic to match against product names. Platform administrators typically follow naming conventions where profile titles encode the product/service context:
 
 \`\`\`go
 // matchProfileToProduct matches a TLS profile to a specific product
@@ -31102,7 +31102,7 @@ func matchProfileToProduct(profileTitle string, cp catalogProductInfo) (string,
 - **\`discoveryTypes\` (array field with oneOf checkboxes)**: \`x-labelLocalizationKey\` is NOT resolved \u2014 the raw key text appears as the label in the UI (e.g., "discovery.typesLabel" shows literally). You MUST use the \`"title"\` property instead.
 - **Boolean discovery fields** (e.g., \`excludeExpiredCertificates\`): \`x-labelLocalizationKey\` DOES work, but ONLY with the nested \`"discovery.xxx"\` pattern.
 
-**The correct pattern (confirmed by FortiGate, verified on APIC):**
+**The correct pattern (confirmed across multiple connectors):**
 
 \`\`\`json
 "discovery": {
@@ -31207,11 +31207,11 @@ for _, chainDER := range bundle.CertificateChain {
 2. Is the root CA ever included, or only intermediates?
 3. Should connectors assume the order and pass through, or re-sort based on issuer/subject matching?
 
-This matters for targets like F5, Citrix ADC, and Java keystores where incorrect chain order causes TLS handshake failures. Until documented, connectors should pass through in the order received and note this assumption in their documentation.
+This matters for targets like load balancers, ADCs, and Java keystores where incorrect chain order causes TLS handshake failures. Until documented, connectors should pass through in the order received and note this assumption in their documentation.
 
 ### 25. DER-to-PEM Conversion for REST API Discovery
 
-**The pattern**: When a REST API target returns certificates as base64-encoded DER (common for appliances like DataPower, FortiGate), the discovery response must convert to PEM. This conversion is easy to miss because the API response looks like a base64 string that could be passed through directly.
+**The pattern**: When a REST API target returns certificates as base64-encoded DER (common for REST API appliances), the discovery response must convert to PEM. This conversion is easy to miss because the API response looks like a base64 string that could be passed through directly.
 
 \`\`\`go
 // REST API returns base64 DER \u2014 MUST convert to PEM for discovery response
@@ -31309,7 +31309,7 @@ Getting these wrong can cause the target service to refuse to start.
 
 ### 1. Unit Tests
 
-The Splunk connector has zero unit tests. This was acceptable for an MVP but should be addressed from the start:
+The SSH-based connector has zero unit tests. This was acceptable for an MVP but should be addressed from the start:
 
 - Mock \`ClientServices\` to test handlers without SSH
 - Test certificate parsing with known PEM files
@@ -31357,13 +31357,13 @@ Or return \`result: false\` with a helpful message if the target software isn't
 
 ---
 
-## REST API Appliance Patterns (FortiGate, APIC, DataPower)
+## REST API Appliance Patterns
 
 These patterns apply to machine connectors that communicate via REST API rather than SSH.
 
 ### 20. PKCS12 Is the Dominant Provisioning Format for REST API Targets
 
-**The pattern**: Most REST API appliances (FortiGate, IBM APIC, F5, Citrix ADC, PAN Panorama) accept certificate bundles as **PKCS12** files, not raw PEM files. The connector must build a PKCS12 bundle from Venafi's DER-encoded certificate bundle.
+**The pattern**: Most REST API appliances accept certificate bundles as **PKCS12** files, not raw PEM files. The connector must build a PKCS12 bundle from Venafi's DER-encoded certificate bundle.
 
 **Implementation** (using \`go-pkcs12\`):
 
@@ -31410,7 +31410,7 @@ func parsePrivateKey(keyDER []byte) (crypto.PrivateKey, error) {
 }
 \`\`\`
 
-This sequence is proven across FortiGate, APIC, and DataPower connectors. Never assume RSA.
+This sequence is proven across multiple REST API appliance connectors. Never assume RSA.
 
 ### 22. CRITICAL: Binding Must Never Be Nil in Discovery Results
 
@@ -31446,7 +31446,7 @@ if hasBindings {
 2. **If yes**: Upload a new cert with a unique name (e.g., \`certName_YYMMDD_serial\`), update the binding to point to the new cert, then optionally delete the old cert
 3. **If no**: Simply upload the cert and create the binding reference
 
-This is the proven pattern for FortiGate and PAN Panorama where certificates are immutable once created. APIC handles this differently \u2014 its PATCH API preserves UUIDs when updating keystore content in-place.
+This is the proven pattern for appliances where certificates are immutable once created. Some API management platforms handle this differently \u2014 their PATCH API preserves UUIDs when updating keystore content in-place.
 
 **Key**: The \`installCertificateBundle\` handler returns the updated keystore (with the new cert name), which is passed to \`configureInstallationEndpoint\`. Use the keystore fields to carry the cert name between activities.
 
@@ -31490,9 +31490,9 @@ if pageEnd < len(allCerts) {
 // page = nil means "done"
 \`\`\`
 
-### 25. OAuth2 Token Exchange (APIC Pattern)
+### 25. OAuth2 Token Exchange (API Management Platform Pattern)
 
-**The pattern**: Some REST API targets (IBM APIC) use OAuth2 token exchange instead of static API keys. The connector exchanges credentials for a bearer token at the start of each endpoint call.
+**The pattern**: Some REST API targets (API management platforms) use OAuth2 token exchange instead of static API keys. The connector exchanges credentials for a bearer token at the start of each endpoint call.
 
 \`\`\`go
 func (h *Handler) authenticate() error {
@@ -31516,34 +31516,34 @@ func (h *Handler) authenticate() error {
 \`\`\`
 
 **IMPORTANT \u2014 Token endpoint body format varies by target**:
-- **IBM APIC**: Requires \`application/json\` body (NOT form-urlencoded). Sending form-urlencoded silently fails.
+- **Some API platforms**: Require \`application/json\` body (NOT form-urlencoded). Sending form-urlencoded silently fails.
 - **Standard OAuth2**: Uses \`application/x-www-form-urlencoded\` per RFC 6749 (use \`SetFormData()\`).
 - Always check the target API documentation for the expected content type.
 
-**Key**: Token has a TTL (8 hours for APIC). For connectors where each endpoint call is stateless, exchange the token at the start of each call \u2014 don't cache across calls.
+**Key**: Token has a TTL (e.g., 8 hours). For connectors where each endpoint call is stateless, exchange the token at the start of each call \u2014 don't cache across calls.
 
 ### 26. REST API Targets May Use PATCH Instead of PUT
 
-**The learning**: IBM APIC hosted environments return 405 (Method Not Allowed) for PUT on keystore updates. APIC requires PATCH. FortiGate requires PUT for most updates. DataPower uses PUT for config objects.
+**The learning**: Some API management platforms return 405 (Method Not Allowed) for PUT on keystore updates and require PATCH instead. Other REST API appliances require PUT for most updates.
 
 **The fix**: Don't assume PUT or PATCH \u2014 check the target API documentation and test both during development. Make the HTTP method part of your helper function:
 
 \`\`\`go
 func (h *Handler) UpdateResource(path string, body interface{}) (*resty.Response, error) {
-    // APIC: PATCH; FortiGate: PUT; DataPower: PUT
+    // some targets require PATCH; others use PUT
     return h.client.R().SetBody(body).Patch(h.baseURL + path) // or .Put()
 }
 \`\`\`
 
 ### 27. Protocols Field Must Never Be Empty Array for Machine Identities
 
-**The learning from APIC**: Venafi platform silently drops machine identities with \`protocols: []\` (empty array) in the discovery response. Omitting \`protocols\` entirely (with \`omitempty\`) causes hard discovery failure.
+**The learning**: Venafi platform silently drops machine identities with \`protocols: []\` (empty array) in the discovery response. Omitting \`protocols\` entirely (with \`omitempty\`) causes hard discovery failure.
 
 **The fix**: For onboard discovery, do NOT set protocols at all. Leave the field out of the response struct entirely (don't even define it). Protocols are for network discovery connectors that observe live TLS connections, not for onboard discovery that reads platform inventory.
 
 ### 28. Null-Safe JSON Arrays in Discovery Responses
 
-**The learning from APIC**: Go's \`encoding/json\` marshals a nil slice as \`null\`, but the Venafi platform expects empty arrays to be \`[]\` (not \`null\`). A \`null\` value for \`certificateChain\` or \`machineIdentities\` can cause discovery failures or silent data loss.
+**The learning**: Go's \`encoding/json\` marshals a nil slice as \`null\`, but the Venafi platform expects empty arrays to be \`[]\` (not \`null\`). A \`null\` value for \`certificateChain\` or \`machineIdentities\` can cause discovery failures or silent data loss.
 
 **The symptom**: Discovery responses with \`"certificateChain": null\` or \`"machineIdentities": null\` are silently rejected or produce incomplete results.
 
@@ -31660,7 +31660,7 @@ func truncateMetadata(s string, totalCount int) string {
 
 **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 problem**: Many network appliances cannot parse modern PKCS12 encoding. The import API returns success or a vague error, but the certificate is not usable. These appliances specifically require the legacy PKCS12 format (3DES + SHA1).
 
 **The fix**: When building PKCS12 bundles in Go, use the Legacy encoder:
 
@@ -31670,7 +31670,7 @@ 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
+// WRONG: Modern encoding (AES-256/SHA-256) \u2014 rejected by many network appliances
 // p12Data, err := gopkcs12.Modern.Encode(key, cert, caCerts, password)
 \`\`\`
 
@@ -31911,7 +31911,7 @@ if _, err := x509.ParsePKCS8PrivateKey(keyDER); err == nil {
 
 **When to use which approach**:
 - **Target accepts PEM** (GCP, AWS, cloud APIs): Use the no-re-marshal approach above. Just detect the type for the PEM header and wrap the original DER bytes.
-- **Target requires PKCS12** (FortiGate, network appliances): You MUST parse into Go types to pass to \`pkcs12.Encode()\`. Re-marshaling is unavoidable and acceptable here because the PKCS12 encoder produces its own encoding.
+- **Target requires PKCS12** (network appliances): You MUST parse into Go types to pass to \`pkcs12.Encode()\`. Re-marshaling is unavoidable and acceptable here because the PKCS12 encoder produces its own encoding.
 
 ### 42. CRITICAL: Handle Both DER and PEM Input in Certificate Bundle
 
@@ -32671,8 +32671,8 @@ var TEMPLATES = {
       "// File: internal/app/domain/binding.go",
       "// CUSTOMIZE: Replace fields with your target-specific service data.",
       "// Choose the pattern that fits your target:",
-      "//   SSH-based targets: ServiceType + ServicePort (e.g., Splunk, Apache, Nginx)",
-      "//   REST API appliances: BindingType + TargetName (e.g., FortiGate, F5, Citrix ADC)",
+      "//   SSH-based targets: ServiceType + ServicePort (e.g., web server, app server)",
+      "//   REST API appliances: BindingType + TargetName (e.g., load balancer, firewall, ADC)",
       "// ============================================================",
       "",
       "package domain",
@@ -32685,7 +32685,7 @@ var TEMPLATES = {
       '// 	ServicePort int    `json:"servicePort"` // port the service listens on',
       "// }",
       "",
-      "// --- Option B: REST API appliance binding (FortiGate pattern) ---",
+      "// --- Option B: REST API appliance binding (network appliance pattern) ---",
       "",
       "// Binding represents how a certificate is used by a target service.",
       '// BindingType identifies the service category (e.g., "admin-https", "ssl-vpn",',
@@ -32702,17 +32702,49 @@ var TEMPLATES = {
       "// ============================================================",
       "// File: internal/app/domain/certificate_bundle.go",
       "// DO NOT MODIFY: This is standard across all connectors.",
+      "//",
+      '// IMPORTANT: The manifest schema uses "contentEncoding": "base64" and',
+      '// "x-encrypted-base64": true on the privateKey field.',
+      "// Venafi Cloud sends certificateBundle fields as base64-encoded DER.",
+      "//",
+      "// Choose ONE option below:",
+      "//",
+      "// Option A (RECOMMENDED for REST API connectors):",
+      "//   Use string fields and explicitly base64.StdEncoding.DecodeString() each field.",
+      "//   This is the most explicit pattern and proven across multiple connector builds.",
+      "//   After decoding, you have DER bytes \u2014 convert to PEM with pem.EncodeToMemory().",
+      "//",
+      "// Option B (works for SSH connectors):",
+      "//   Use []byte fields \u2014 Go's JSON unmarshaler auto-decodes base64 into []byte.",
+      "//   After unmarshaling, fields already contain DER bytes.",
+      "//",
+      "// Both options produce the same result: DER-encoded binary data.",
       "// ============================================================",
       "",
       "package domain",
       "",
       "// CertificateBundle represents the certificate data sent by Venafi for provisioning.",
+      "//",
+      "// Option A: string fields (RECOMMENDED \u2014 explicit base64 decode)",
+      "//   certDER, _ := base64.StdEncoding.DecodeString(bundle.Certificate)",
+      "//   keyDER, _ := base64.StdEncoding.DecodeString(bundle.PrivateKey)",
+      "//   for _, chainEntry := range bundle.CertificateChain {",
+      "//       chainDER, _ := base64.StdEncoding.DecodeString(chainEntry)",
+      '//       chainPEM = append(chainPEM, pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: chainDER})...)',
+      "//   }",
       "type CertificateBundle struct {",
-      '	Certificate      []byte   `json:"certificate"`',
-      '	PrivateKey       []byte   `json:"privateKey"`',
-      '	CertificateChain [][]byte `json:"certificateChain"`',
+      '	Certificate      string   `json:"certificate"`',
+      '	PrivateKey       string   `json:"privateKey"`',
+      '	CertificateChain []string `json:"certificateChain"`',
       "}",
       "",
+      "// Option B: []byte fields (Go auto-decodes base64 \u2014 fields contain DER bytes directly)",
+      "// type CertificateBundle struct {",
+      '// 	Certificate      []byte   `json:"certificate"`',
+      '// 	PrivateKey       []byte   `json:"privateKey"`',
+      '// 	CertificateChain [][]byte `json:"certificateChain"`',
+      "// }",
+      "",
       "// ============================================================",
       "// File: internal/app/domain/client.go",
       "// This is the same across all SSH-based connectors.",
@@ -32845,6 +32877,20 @@ var TEMPLATES = {
     content: [
       "// TEMPLATE: Discovery request/response types. Standard across all connectors.",
       "// File: internal/app/discovery/types.go",
+      "//",
+      "// CRITICAL RULES:",
+      '//   1. The response top-level key MUST be "messages" \u2014 the platform silently rejects other names.',
+      "//   2. Use VALUE types (not pointers) for Keystore, Binding, and slice elements.",
+      "//      Pointers serialize to null when nil, which the platform may reject.",
+      "//   3. Initialize all slices with make() to ensure JSON [] not null.",
+      "//   4. The certificate field must contain a PEM string (not DER, not base64).",
+      "//      Always normalize through pem.EncodeToMemory() before returning \u2014 even if",
+      "//      the source is already PEM \u2014 to guarantee trailing newline and line wrapping.",
+      '//   5. discoveryPage: null in the response signals "done" to the platform.',
+      '//   6. Each DiscoveredCertificate MUST include an "installations" array with at least',
+      "//      one entry containing hostname, ipAddress, and port. Without this field, the",
+      "//      platform silently discards discovered certificates \u2014 no error, discovery shows",
+      '//      as "complete" but no certificates appear in the UI.',
       "",
       "package discovery",
       "",
@@ -32860,11 +32906,10 @@ var TEMPLATES = {
       "type DiscoverCertificatesConfiguration struct {",
       "	// DiscoveryTypes lets users toggle which service types to discover.",
       "	// For REST API appliances, this filters which binding endpoints are queried.",
-      '	// Example values: "admin-https", "ssl-vpn", "ipsec-vpn", "vip", "ssl-inspection"',
       '	// An empty slice means "discover all types".',
       '	DiscoveryTypes             []string `json:"discoveryTypes"`',
       '	ExcludeExpiredCertificates bool     `json:"excludeExpiredCertificates"`',
-      "	// Scope field for multi-tenant targets (e.g., VDOM, partition, tenant).",
+      "	// Scope field for multi-tenant targets (e.g., partition, tenant, virtual domain).",
       "	// Leave blank to auto-discover all scopes.",
       '	Scope string `json:"scope"`',
       "}",
@@ -32878,29 +32923,82 @@ var TEMPLATES = {
       "}",
       "",
       "// DiscoveryPage represents the current pagination state.",
+      '// Return nil to signal "discovery complete" to the platform.',
+      "// Return a non-nil DiscoveryPage to request another page.",
       "type DiscoveryPage struct {",
-      '	DiscoveryType *string `json:"discoveryType,omitempty"`',
-      '	Paginator     string  `json:"paginator"`',
+      '	DiscoveryType string `json:"discoveryType"`',
+      '	Paginator     string `json:"paginator"`',
       "}",
       "",
       "// DiscoverCertificatesResponse represents the response to a discovery request.",
+      '// CRITICAL: The top-level JSON key MUST be "messages" \u2014 the platform ignores other keys.',
       "type DiscoverCertificatesResponse struct {",
+      '	Messages []DiscoveredCertificate `json:"messages"`',
       '	Page     *DiscoveryPage          `json:"discoveryPage"`',
-      '	Messages []*DiscoveredCertificate `json:"messages"`',
       "}",
       "",
       "// DiscoveredCertificate represents a single certificate found during discovery.",
+      "// CRITICAL: Use VALUE types (not pointers) \u2014 pointers serialize to null which the platform rejects.",
+      "// CRITICAL: The Installations field is REQUIRED \u2014 without it, the platform silently discards",
+      '// the certificate. Discovery will show as "complete" but no certs appear in the UI.',
       "type DiscoveredCertificate struct {",
-      '	Certificate       string             `json:"certificate"`',
-      '	CertificateChain  []string           `json:"certificateChain"`',
-      '	MachineIdentities []*MachineIdentity `json:"machineIdentities"`',
+      '	Certificate       string            `json:"certificate"`       // PEM string (use pem.EncodeToMemory)',
+      '	CertificateChain  []string          `json:"certificateChain"`  // PEM strings, initialize with make()',
+      '	MachineIdentities []MachineIdentity `json:"machineIdentities"` // VALUE type slice, initialize with make()',
+      '	Installations     []Installation    `json:"installations"`     // REQUIRED \u2014 at least one entry',
+      "}",
+      "",
+      "// Installation identifies where the certificate was found (host + port).",
+      "// CRITICAL: At least one Installation is required per DiscoveredCertificate.",
+      "// Without this field, the platform silently drops the certificate from results.",
+      "type Installation struct {",
+      '	Hostname  string `json:"hostname"`',
+      '	IPAddress string `json:"ipAddress"`',
+      '	Port      int    `json:"port"`',
       "}",
       "",
       "// MachineIdentity represents a certificate usage found during discovery.",
+      "// CRITICAL: Use VALUE types for Keystore and Binding \u2014 never pointers.",
+      '// Binding must NEVER be empty \u2014 use a default like "unbound" for certs with no bindings.',
+      "// All x-primaryKey fields must have non-empty values or the identity is silently dropped.",
       "type MachineIdentity struct {",
-      '	Keystore *domain.Keystore `json:"keystore"`',
-      '	Binding  *domain.Binding  `json:"binding"`',
-      "}"
+      '	Keystore domain.Keystore `json:"keystore"`',
+      '	Binding  domain.Binding  `json:"binding"`',
+      "}",
+      "",
+      "// ============================================================",
+      "// Example: Building a discovery response",
+      "// ============================================================",
+      "//",
+      "// messages := make([]DiscoveredCertificate, 0)  // MUST use make() \u2014 nil serializes as null",
+      "// chainPEMs := make([]string, 0)                // same for chains",
+      "//",
+      "// // Always normalize PEM through pem.EncodeToMemory, even if source is already PEM:",
+      "// block, _ := pem.Decode([]byte(rawPEM))",
+      "// normalizedPEM := string(pem.EncodeToMemory(block))",
+      "//",
+      "// // For REST API targets returning base64 DER:",
+      "// derBytes, _ := base64.StdEncoding.DecodeString(apiResponse.Base64)",
+      '// certPEM := string(pem.EncodeToMemory(&pem.Block{Type: "CERTIFICATE", Bytes: derBytes}))',
+      "//",
+      "// messages = append(messages, DiscoveredCertificate{",
+      "//     Certificate:       normalizedPEM,",
+      "//     CertificateChain:  chainPEMs,",
+      "//     MachineIdentities: []MachineIdentity{{",
+      '//         Keystore: domain.Keystore{CertificateName: "my-cert"},',
+      '//         Binding:  domain.Binding{BindingType: "unbound"},  // never empty',
+      "//     }},",
+      "//     Installations: []Installation{{",
+      "//         Hostname:  connection.HostnameOrAddress,",
+      "//         IPAddress: connection.HostnameOrAddress,",
+      "//         Port:      connection.Port,",
+      "//     }},  // REQUIRED \u2014 without this, certs are silently dropped",
+      "// })",
+      "//",
+      "// return c.JSON(http.StatusOK, DiscoverCertificatesResponse{",
+      "//     Messages: messages,",
+      "//     Page:     nil,  // nil = done; non-nil = call again",
+      "// })"
     ].join("\n"),
     customizable: true
   },
@@ -32910,12 +33008,14 @@ var TEMPLATES = {
     targetPath: "internal/app/<target>/install_helpers.go",
     content: [
       "// TEMPLATE: Helper functions for certificate installation.",
-      "// These are proven patterns from the Splunk connector that work correctly.",
+      "// These are proven patterns from multiple connector builds.",
       "// Include these in your install.go or a helpers.go file.",
       "",
       "package <target>",
       "",
       "import (",
+      '	"crypto/ecdsa"',
+      '	"crypto/rsa"',
       '	"crypto/x509"',
       '	"encoding/pem"',
       '	"fmt"',
@@ -32925,27 +33025,52 @@ var TEMPLATES = {
       '	"go.uber.org/zap"',
       ")",
       "",
-      "// privateKeyPEMType detects the private key type and returns the correct PEM header.",
-      '// IMPORTANT: Do NOT hardcode "RSA PRIVATE KEY" - Venafi may issue EC keys.',
-      "func privateKeyPEMType(keyBytes []byte) string {",
-      "	// Try PKCS#1 RSA",
-      "	if _, err := x509.ParsePKCS1PrivateKey(keyBytes); err == nil {",
-      '		return "RSA PRIVATE KEY"',
+      "// encodeKeyToPEM detects the key type and encodes to PEM with the correct header.",
+      "//",
+      "// CRITICAL: When PKCS8 wraps a key, re-marshal to the native format.",
+      "// Some targets validate that the DER encoding matches the PEM header.",
+      '// PKCS8 DER with "RSA PRIVATE KEY" header = INVALID (DER is PKCS8, header says PKCS1).',
+      '// PKCS1 DER with "RSA PRIVATE KEY" header = VALID (both agree on format).',
+      "//",
+      '// Do NOT hardcode "RSA PRIVATE KEY" \u2014 Venafi may issue EC or other key types.',
+      "func encodeKeyToPEM(keyDER []byte) []byte {",
+      "	// Try PKCS8 first (most common from Venafi)",
+      "	key, err := x509.ParsePKCS8PrivateKey(keyDER)",
+      "	if err == nil {",
+      "		switch k := key.(type) {",
+      "		case *rsa.PrivateKey:",
+      '			// Re-marshal to PKCS1 so DER matches "RSA PRIVATE KEY" header',
+      "			pkcs1DER := x509.MarshalPKCS1PrivateKey(k)",
+      '			return pem.EncodeToMemory(&pem.Block{Type: "RSA PRIVATE KEY", Bytes: pkcs1DER})',
+      "		case *ecdsa.PrivateKey:",
+      "			ecDER, ecErr := x509.MarshalECPrivateKey(k)",
+      "			if ecErr == nil {",
+      '				return pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: ecDER})',
+      "			}",
+      '			return pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: keyDER})',
+      "		default:",
+      '			return pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: keyDER})',
+      "		}",
       "	}",
-      "	// Try EC",
-      "	if _, err := x509.ParseECPrivateKey(keyBytes); err == nil {",
-      '		return "EC PRIVATE KEY"',
+      "",
+      "	// Try RSA PKCS1",
+      "	if _, err := x509.ParsePKCS1PrivateKey(keyDER); err == nil {",
+      '		return pem.EncodeToMemory(&pem.Block{Type: "RSA PRIVATE KEY", Bytes: keyDER})',
       "	}",
-      "	// Try PKCS#8 (wraps either RSA or EC)",
-      "	if _, err := x509.ParsePKCS8PrivateKey(keyBytes); err == nil {",
-      '		return "PRIVATE KEY"',
+      "",
+      "	// Try EC",
+      "	if _, err := x509.ParseECPrivateKey(keyDER); err == nil {",
+      '		return pem.EncodeToMemory(&pem.Block{Type: "EC PRIVATE KEY", Bytes: keyDER})',
       "	}",
-      "	// Default to PKCS#8 header (most compatible)",
-      '	return "PRIVATE KEY"',
+      "",
+      "	// Fallback \u2014 generic PRIVATE KEY header",
+      '	return pem.EncodeToMemory(&pem.Block{Type: "PRIVATE KEY", Bytes: keyDER})',
       "}",
       "",
       "// buildCombinedPEM creates a combined PEM file with cert + chain + key.",
       "// Used when the target expects all components in a single file.",
+      "// NOTE: This assumes CertificateBundle uses []byte fields (Option B).",
+      "// If using string fields (Option A), decode from base64 first.",
       "func buildCombinedPEM(bundle *domain.CertificateBundle) ([]byte, error) {",
       "	var pemContent strings.Builder",
       "",
@@ -32963,12 +33088,8 @@ var TEMPLATES = {
       "		})))",
       "	}",
       "",
-      "	// Private key (with correct type detection)",
-      "	keyType := privateKeyPEMType(bundle.PrivateKey)",
-      "	pemContent.WriteString(string(pem.EncodeToMemory(&pem.Block{",
-      "		Type:  keyType,",
-      "		Bytes: bundle.PrivateKey,",
-      "	})))",
+      "	// Private key (with PKCS8 re-marshaling)",
+      "	pemContent.WriteString(string(encodeKeyToPEM(bundle.PrivateKey)))",
       "",
       "	return []byte(pemContent.String()), nil",
       "}",
@@ -32996,12 +33117,9 @@ var TEMPLATES = {
       "}",
       "",
       "// buildKeyPEM creates a PEM file with just the private key.",
+      "// Re-marshals PKCS8 keys to native format for PEM header correctness.",
       "func buildKeyPEM(bundle *domain.CertificateBundle) []byte {",
-      "	keyType := privateKeyPEMType(bundle.PrivateKey)",
-      "	return pem.EncodeToMemory(&pem.Block{",
-      "		Type:  keyType,",
-      "		Bytes: bundle.PrivateKey,",
-      "	})",
+      "	return encodeKeyToPEM(bundle.PrivateKey)",
       "}",
       "",
       "// backupFile creates a backup of an existing file before overwriting.",
@@ -33247,7 +33365,7 @@ func configureLogger() (*zap.Logger, error) {
   },
   "rest-client.go": {
     name: "rest-client.go",
-    description: "REST API client (handler) pattern for network appliance connectors (FortiGate, F5, Citrix ADC). Uses go-resty with multi-auth support (API token, session, PKI).",
+    description: "REST API client (handler) pattern for network appliance connectors (firewalls, load balancers, ADCs). Uses go-resty with multi-auth support (API token, session, PKI).",
     targetPath: "internal/app/<target>/handler.go",
     content: [
       "package <target>",
@@ -33384,7 +33502,7 @@ func configureLogger() (*zap.Logger, error) {
   },
   "rest-api-service-pattern.go": {
     name: "rest-api-service-pattern.go",
-    description: "3-service decomposition pattern for REST API connectors (PAN Panorama architecture). Connection, Provisioning, and Discovery as separate services.",
+    description: "3-service decomposition pattern for REST API connectors. Connection, Provisioning, and Discovery as separate services.",
     targetPath: "internal/app/<target>/<target>.go",
     content: [
       "package <target>",
@@ -33557,14 +33675,17 @@ ${content}`;
 function getMachineEndpoints(args) {
   const webTemplate = TEMPLATES["machine-web.go"];
   const testConnTemplate = TEMPLATES["test-connection.go"];
+  const discoveryTypesTemplate = TEMPLATES["discovery-types.go"];
   let webContent = webTemplate.content;
   let testConnContent = testConnTemplate.content;
+  let discoveryTypesContent = discoveryTypesTemplate.content;
   if (args?.connectorName || args?.modulePath || args?.targetPackage) {
     const cn = args?.connectorName || "<CONNECTOR_NAME>";
     const mp = args?.modulePath || "<CONNECTOR_MODULE>";
     const tp = args?.targetPackage || "<target>";
     webContent = substituteTemplate(webContent, cn, mp, tp);
     testConnContent = substituteTemplate(testConnContent, cn, mp, tp);
+    discoveryTypesContent = substituteTemplate(discoveryTypesContent, cn, mp, tp);
   }
   return `# Machine Connector Endpoint Templates
 
@@ -33576,9 +33697,9 @@ A machine connector implements 5 endpoints (plus /healthz). All are POST endpoin
 |---|---|---|
 | POST /v1/testconnection | HandleTestConnection | Validate connectivity, detect target software |
 | POST /v1/discovercertificates | HandleDiscoverCertificates | Find certificates, return with keystore/binding metadata |
-| POST /v1/installcertificatebundle | HandleInstallCertificateBundle | Write cert+chain+key files to target |
-| POST /v1/configureinstallationendpoint | HandleConfigureInstallationEndpoint | Restart/reload target service |
-| POST /v1/gettargetconfiguration | HandleGetTargetConfiguration | Return target info (stub is OK) |
+| POST /v1/installcertificatebundle | HandleInstallCertificateBundle | Install cert+chain+key on target |
+| POST /v1/configureinstallationendpoint | HandleConfigureInstallationEndpoint | Configure service binding for the installed cert |
+| POST /v1/gettargetconfiguration | HandleGetTargetConfiguration | Return target info for UI dropdowns (stub is OK) |
 | GET /healthz | (inline) | Kubernetes liveness probe |
 
 ## WebhookService Interface (web.go)
@@ -33597,17 +33718,172 @@ This is a complete test connection handler with SSH validation. Customize step 4
 ${testConnContent}
 \`\`\`
 
+## Discovery Response Types (discovery/types.go)
+
+These types define the discovery request/response structures. The response format is critical \u2014 incorrect types cause silent failures.
+
+\`\`\`go
+${discoveryTypesContent}
+\`\`\`
+
+## Install Certificate Bundle Handler
+
+CRITICAL: The response MUST wrap the updated keystore in \`{"keystore": {...}}\`.
+Returning the keystore directly (without the wrapper) causes: \`"missing json schema in plugin manifest for entity keystoreId"\`.
+
+\`\`\`go
+// File: internal/app/<target>/install_certificate_bundle.go
+
+// InstallCertificateBundleRequest contains the request for installing a certificate.
+type InstallCertificateBundleRequest struct {
+	Connection        *domain.Connection        \`json:"connection"\`
+	Keystore          *domain.Keystore           \`json:"keystore"\`
+	CertificateBundle *domain.CertificateBundle  \`json:"certificateBundle"\`
+}
+
+// InstallCertificateBundleResponse wraps the updated keystore.
+// CRITICAL: Response MUST be {"keystore": {...}} \u2014 platform validates against manifest schema.
+type InstallCertificateBundleResponse struct {
+	Keystore domain.Keystore \`json:"keystore"\`
+}
+
+func (svc *WebhookServiceImpl) HandleInstallCertificateBundle(c echo.Context) error {
+	zap.L().Info("installCertificateBundle workflow activity started")
+
+	// Step 1: Parse request
+	req := InstallCertificateBundleRequest{}
+	if err := c.Bind(&req); err != nil {
+		zap.L().Error("install step 1 failed: invalid request", zap.Error(err))
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	// Step 2: Connect to target
+	client := svc.ClientServices.NewClient(req.Connection)
+	if err := svc.ClientServices.Connect(client); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+	defer svc.ClientServices.Close(client)
+
+	// Step 3: Install the certificate
+	// CUSTOMIZE: Implement your target-specific installation logic here.
+	// For SSH targets: write PEM files to disk, set permissions.
+	// For REST API targets: upload via API (PKCS12, PEM, or target-specific format).
+	//
+	// Certificate bundle fields are base64-encoded DER (if using string fields):
+	//   certDER, _ := base64.StdEncoding.DecodeString(req.CertificateBundle.Certificate)
+	//   keyDER, _ := base64.StdEncoding.DecodeString(req.CertificateBundle.PrivateKey)
+	//   for _, entry := range req.CertificateBundle.CertificateChain {
+	//       chainDER, _ := base64.StdEncoding.DecodeString(entry)
+	//   }
+	//
+	// If using []byte fields, Go auto-decodes \u2014 fields already contain DER bytes.
+
+	updatedKeystore := *req.Keystore // Copy and update as needed
+
+	zap.L().Info("installCertificateBundle completed",
+		zap.Any("keystore", updatedKeystore),
+	)
+
+	// CRITICAL: Wrap in {"keystore": {...}} \u2014 do NOT return the keystore directly
+	return c.JSON(http.StatusOK, InstallCertificateBundleResponse{Keystore: updatedKeystore})
+}
+\`\`\`
+
+## Configure Installation Endpoint Handler
+
+CRITICAL: The response MUST wrap the binding in \`{"binding": {...}}\`.
+
+\`\`\`go
+// File: internal/app/<target>/configure_installation_endpoint.go
+
+// ConfigureInstallationEndpointRequest contains the request for configuring the binding.
+type ConfigureInstallationEndpointRequest struct {
+	Connection *domain.Connection \`json:"connection"\`
+	Keystore   *domain.Keystore   \`json:"keystore"\`
+	Binding    *domain.Binding    \`json:"binding"\`
+}
+
+// ConfigureInstallationEndpointResponse wraps the binding.
+// CRITICAL: Response MUST be {"binding": {...}} \u2014 platform validates against manifest schema.
+type ConfigureInstallationEndpointResponse struct {
+	Binding domain.Binding \`json:"binding"\`
+}
+
+func (svc *WebhookServiceImpl) HandleConfigureInstallationEndpoint(c echo.Context) error {
+	zap.L().Info("configureInstallationEndpoint workflow activity started")
+
+	// Step 1: Parse request
+	req := ConfigureInstallationEndpointRequest{}
+	if err := c.Bind(&req); err != nil {
+		zap.L().Error("configure step 1 failed: invalid request", zap.Error(err))
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	// Step 2: Connect to target
+	client := svc.ClientServices.NewClient(req.Connection)
+	if err := svc.ClientServices.Connect(client); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+	defer svc.ClientServices.Close(client)
+
+	// Step 3: Configure the binding
+	// CUSTOMIZE: Implement your target-specific binding logic here.
+	// For SSH targets: restart/reload the service (systemctl restart, service reload, etc.).
+	// For REST API targets: update the binding via API (assign cert to VIP, profile, etc.).
+
+	zap.L().Info("configureInstallationEndpoint completed",
+		zap.Any("binding", req.Binding),
+	)
+
+	// CRITICAL: Wrap in {"binding": {...}} \u2014 do NOT return the binding directly
+	return c.JSON(http.StatusOK, ConfigureInstallationEndpointResponse{Binding: *req.Binding})
+}
+\`\`\`
+
+## Get Target Configuration Handler
+
+Returns target metadata for UI dropdowns. Can be a stub initially.
+
+\`\`\`go
+// File: internal/app/<target>/get_target_configuration.go
+
+type GetTargetConfigurationRequest struct {
+	Connection *domain.Connection \`json:"connection"\`
+}
+
+func (svc *WebhookServiceImpl) HandleGetTargetConfiguration(c echo.Context) error {
+	zap.L().Info("getTargetConfiguration workflow activity started")
+
+	req := GetTargetConfigurationRequest{}
+	if err := c.Bind(&req); err != nil {
+		return c.JSON(http.StatusBadRequest, map[string]string{"error": err.Error()})
+	}
+
+	// CUSTOMIZE: Return target configuration for UI dropdowns.
+	// Fields returned here populate x-targetConfigurationRef dropdowns in the manifest.
+	// Return an empty object if no dynamic configuration is needed.
+	return c.JSON(http.StatusOK, map[string]interface{}{})
+}
+\`\`\`
+
 ## Handler Pattern (Use for ALL Endpoints)
 
 Every handler follows these steps:
 1. Parse and validate the request
 2. Establish connection (with defer Close)
 3. Do the actual work
-4. Return response
+4. Return response as JSON
+
+### Critical Response Rules
+- **testConnection**: Return \`c.JSON(http.StatusOK, TestConnectionResponse{Result: true})\`
+- **installCertificateBundle**: Return \`c.JSON(http.StatusOK, InstallCertificateBundleResponse{Keystore: ...})\` \u2014 MUST wrap in \`{"keystore": ...}\`
+- **configureInstallationEndpoint**: Return \`c.JSON(http.StatusOK, ConfigureInstallationEndpointResponse{Binding: ...})\` \u2014 MUST wrap in \`{"binding": ...}\`
+- **discoverCertificates**: Return \`c.JSON(http.StatusOK, DiscoverCertificatesResponse{Messages: ...})\` \u2014 MUST use \`"messages"\` key
+- **ALL responses must be JSON** \u2014 the vSatellite unmarshals every webhook response as JSON. Returning plain text (\`c.String(200, "OK")\`) causes: \`"invalid character 'O' looking for beginning of value"\`
+- Return HTTP 400 for ALL errors (not 500)
 
-Key rules:
+### Other Rules
 - Always defer Close() immediately after Connect()
-- Return HTTP 400 for ALL errors (not 500)
 - Log every step with structured fields
 - Each endpoint is stateless \u2014 connect, do work, disconnect
 `;
@@ -33615,7 +33891,7 @@ Key rules:
 function getMachineBestPractices() {
   return `# Machine Connector Best Practices
 
-These best practices are distilled from building multiple machine connectors: Splunk Enterprise (SSH), FortiGate (REST API), IBM APIC (REST API), and DataPower (REST API). They cover what worked, what failed, and what to avoid.
+These best practices are distilled from building multiple machine connectors across SSH-based and REST API-based targets. They cover what worked, what failed, and what to avoid.
 
 ${LESSONS_LEARNED}
 
@@ -33641,12 +33917,18 @@ ${LESSONS_LEARNED}
 18. **Retired certificates in Venafi silently block discovery** \u2014 query certificateStatus for RETIRED records when MI count is low
 19. **Null-safe JSON arrays** \u2014 initialize slices to \`[]string{}\` not nil, as \`null\` in JSON causes silent discovery failures
 20. **discoveryTypes label MUST use "title"** \u2014 \`x-labelLocalizationKey\` does NOT work for array discovery fields (shows raw key text). Use \`"title": "Certificate Types"\` on the property and \`"title"\` on each oneOf item. Boolean discovery fields CAN use \`x-labelLocalizationKey\` with the \`"discovery.xxx"\` pattern
-21. **Discovery type checkboxes should match the target platform's certificate categories** \u2014 ask "how would an admin describe their certificates?" (FortiGate: by service type; APIC: by usage role). Don't use generic/internal labels
+21. **Discovery type checkboxes should match the target platform's certificate categories** \u2014 ask "how would an admin describe their certificates?" (network appliance: by service type; API platform: by usage role). Don't use generic/internal labels
 22. **x-labelLocalizationKey must be two-level dot paths** \u2014 \`"fieldName.label"\` works, but \`"section.fieldName.label"\` (three levels) does NOT resolve and shows raw key text in the UI. Use flat prefixes like \`"dpDomain.label"\` instead of \`"keystore.domain.label"\`
 23. **certificateBundle.certificateChain is an ARRAY** \u2014 Venafi Cloud sends it as \`["base64cert1", "base64cert2"]\`, not a single string. Manifest must declare \`{ "type": "array", "items": { "contentEncoding": "base64", "type": "string" } }\`. Go struct uses \`[][]byte\` (auto base64 decode) or \`[]string\` (manual decode)
 24. **Certificate chain ordering is undocumented** \u2014 Venafi Cloud sends the chain array but the ordering guarantee is not documented. Pass through in received order and note this assumption. Targets with strict ordering requirements may need issuer/subject-based re-sorting
 25. **REST API discovery: convert base64 DER to PEM** \u2014 when a target API returns certs as base64-encoded DER, you MUST convert to PEM for the discovery response (\`base64.Decode \u2192 pem.EncodeToMemory\`). Validate with \`strings.HasPrefix(cert, "-----BEGIN CERTIFICATE-----")\`
 26. **Default binding must be assigned BEFORE discovery type filtering** \u2014 if "unbound" (or any fallback binding) is assigned after the filter runs, unbound certs are silently dropped. Always: find bindings \u2192 assign default if empty \u2192 then filter
+27. **Discovery messages MUST include an \`installations\` array** \u2014 each DiscoveredCertificate must have at least one entry with hostname, ipAddress, and port. Without this field, the platform silently discards the certificate \u2014 discovery shows "complete" but no certs appear in the UI. This is the most common cause of "discovery works but nothing shows up"
+28. **Connection reset after cert import = SUCCESS** \u2014 some targets restart their web gateway or management interface after a certificate is installed, causing connection resets, timeouts, or HTTP errors. These MUST be caught and treated as success, not failure. Add a short retry/delay if you need to verify the install afterward
+29. **Idempotent install detection** \u2014 HTTP 409 or response body containing "already exists" / "identical" during cert import should be treated as success, not error. The certificate was already installed (e.g., from a previous attempt that reported a connection error)
+30. **Error messages must attribute the component** \u2014 prefix all errors so users can identify which system caused the failure: \`"Target API error: ..."\` (target returned an error), \`"Target connection error: ..."\` (cannot reach target), \`"Connector error: ..."\` (invalid request or internal processing error). This saves significant support/debugging time
+31. **Binding is optional in the manifest** \u2014 if your target has no binding concept (single-cert targets), you can omit binding from the domainSchema. However, if binding was ever defined and machines exist with binding data, you MUST keep at least \`{"properties": {}, "type": "object"}\` or the Venafi UI will crash when editing those machines. \`x-primaryKey\` is optional on binding when it has no properties, but always required on keystore
+32. **Dropdowns use \`oneOf\` with \`const\`, not \`enum\`** \u2014 the correct manifest pattern for dropdown fields is \`"oneOf": [{"const": "value", "x-labelLocalizationKey": "field.value"}]\`. Using \`enum\` alone does not render labels in the UI
 `;
 }
 function getRESTClientPattern(args) {
@@ -33666,7 +33948,7 @@ function getRESTClientPattern(args) {
   }
   return `# REST API Client Pattern for Machine Connectors
 
-The REST API client pattern is for network appliance connectors (FortiGate, F5, Citrix ADC, PAN Panorama) that communicate via HTTPS REST API instead of SSH.
+The REST API client pattern is for network appliance connectors (firewalls, load balancers, ADCs, management platforms) that communicate via HTTPS REST API instead of SSH.
 
 ## When to Use This Pattern
 - Target is a network appliance (firewall, load balancer, ADC)
@@ -33681,7 +33963,7 @@ The REST API client pattern is for network appliance connectors (FortiGate, F5,
 - No sudo, no file system ops \u2014 everything is API calls
 - Each request creates a fresh handler (stateless per endpoint call)
 
-## Architecture: 3-Service Decomposition (PAN Panorama Pattern)
+## Architecture: 3-Service Decomposition
 
 Instead of a single \`ClientServices\` interface, REST API connectors use three services:
 - **ConnectionService** \u2014 handles \`testConnection\`
@@ -33711,7 +33993,7 @@ ${appContent}
 ## Network Appliance Patterns
 
 ### Certificate Cannot Be Updated In-Place
-Many appliances (FortiGate, PAN) cannot update a certificate's content in-place. The replacement pattern is:
+Many appliances cannot update a certificate's content in-place. The replacement pattern is:
 1. Upload new cert with a **different name** (e.g., \`name_YYMonDD_serial\`)
 2. Update all bindings to reference the new name
 3. Delete the old certificate (only if no bindings remain)
@@ -33741,10 +34023,8 @@ Changing the management interface certificate drops the active HTTPS session.
 Catch the connection error and treat it as success.
 
 ## Reference Connectors
-- **PAN Panorama** \u2014 cleanest architecture, 3-service decomposition, config locking
-- **Citrix ADC** \u2014 NITRO REST API, partition switching, SNI handling, comprehensive tests
-- **F5** \u2014 simpler flat structure, go-bigip SDK, file upload pattern
 - **VMware AVI** (github.com/Venafi/vmware-avi-connector) \u2014 public REST API reference
+- Reference connectors using 3-service decomposition, partition switching, and SNI handling are available internally
 `;
 }
 function getSSHClientPattern(args) {
@@ -33857,7 +34137,7 @@ This means: no shared state between calls. Each call connects, does work, discon
 - \`get_machine_manifest\` \u2014 Get the machine connector manifest.json template with all sections explained
 - \`get_machine_domain_types\` \u2014 Get Go domain type templates (Connection, Keystore, Binding, CertificateBundle, Client)
 - \`get_machine_endpoints\` \u2014 Get handler/service interface templates for all 5 machine endpoints
-- \`get_machine_best_practices\` \u2014 Get lessons learned and best practices from building the Splunk connector
+- \`get_machine_best_practices\` \u2014 Get lessons learned and best practices from building reference connectors
 - \`get_ssh_client_pattern\` \u2014 Get the SSH client abstraction code with sudo, file I/O, and command execution
 
 ## What I Need From You
@@ -33889,7 +34169,7 @@ server.resource("machine-blueprint", "venafi://connector-machine/blueprint", {
   ]
 }));
 server.resource("lessons-learned", "venafi://connector-machine/lessons-learned", {
-  description: "What worked, what failed, and mistakes to avoid \u2014 from building the Splunk SSH connector. Covers SSH patterns, discovery challenges, certificate format issues, and more.",
+  description: "What worked, what failed, and mistakes to avoid \u2014 from building multiple machine connectors. Covers SSH and REST API patterns, discovery challenges, certificate format issues, and more.",
   mimeType: "text/markdown"
 }, async () => ({
   contents: [
@@ -33944,7 +34224,7 @@ server.tool("get_machine_endpoints", "Return handler and service interface templ
     }
   ]
 }));
-server.tool("get_machine_best_practices", "Return lessons learned and best practices from building the Splunk SSH connector. Covers: what worked (Avi reference, logging, interfaces, DI), mistakes (DER vs PEM, key types, pagination, error handling), and things that need improvement (unit tests, integration tests, error context, timeouts).", {}, async () => ({
+server.tool("get_machine_best_practices", "Return lessons learned and best practices from building multiple machine connectors (SSH and REST API). Covers: what worked (Avi reference, logging, interfaces, DI), mistakes (DER vs PEM, key types, pagination, error handling, response format), and things that need improvement (unit tests, integration tests, error context, timeouts).", {}, async () => ({
   content: [
     {
       type: "text",
@@ -33964,7 +34244,7 @@ server.tool("get_ssh_client_pattern", "Return the SSH client abstraction code fo
     }
   ]
 }));
-server.tool("get_rest_client_pattern", "Return the REST API client abstraction code for network appliance machine connectors (FortiGate, F5, Citrix ADC, PAN Panorama). Includes the Handler interface with multi-auth support (API token, username/password, PKI client cert), 3-service decomposition (ConnectionService, ProvisioningService, DiscoveryService), and uber/fx DI wiring. Use this instead of get_ssh_client_pattern when the target is a network appliance with a REST API.", {
+server.tool("get_rest_client_pattern", "Return the REST API client abstraction code for network appliance machine connectors (firewalls, load balancers, ADCs, management platforms). Includes the Handler interface with multi-auth support (API token, username/password, PKI client cert), 3-service decomposition (ConnectionService, ProvisioningService, DiscoveryService), and uber/fx DI wiring. Use this instead of get_ssh_client_pattern when the target is a network appliance with a REST API.", {
   connectorName: external_exports3.string().optional().describe("Connector name (e.g., 'fortigate-connector'). Replaces <CONNECTOR_NAME>."),
   modulePath: external_exports3.string().optional().describe("Go module path (e.g., 'github.com/venafi/fortigate-connector'). Replaces <CONNECTOR_MODULE>."),
   targetPackage: external_exports3.string().optional().describe("Target Go package name (e.g., 'fortigate'). Replaces <target>.")
@@ -33977,7 +34257,7 @@ server.tool("get_rest_client_pattern", "Return the REST API client abstraction c
   ]
 }));
 server.prompt("new_machine_connector", "Start building a new Venafi machine connector. Provides all context, tools, and instructions needed to begin building a machine connector for a specific target software.", {
-  targetSoftware: external_exports3.string().describe("The target software (e.g., 'Apache HTTP Server', 'Nginx', 'HAProxy', 'Splunk')"),
+  targetSoftware: external_exports3.string().describe("The target software (e.g., 'Apache HTTP Server', 'Nginx', 'HAProxy', 'network appliance')"),
   connectionMethod: external_exports3.string().optional().default("ssh").describe("Connection method: 'ssh' or 'api'")
 }, async (args) => ({
   messages: [

package/package.json

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