omnata-plugin-devkit 0.13.2a182__tar.gz → 0.13.2a183__tar.gz

{omnata_plugin_devkit-0.13.2a182 → omnata_plugin_devkit-0.13.2a183}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: omnata-plugin-devkit
-Version: 0.13.2a182
+Version: 0.13.2a183
 Summary: 
 License-File: LICENSE
 Author: James Weakley

{omnata_plugin_devkit-0.13.2a182 → omnata_plugin_devkit-0.13.2a183}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "omnata-plugin-devkit"
-version = "0.13.2a182"
+version = "0.13.2a183"
 description = ""
 authors = ["James Weakley <james.weakley@omnata.com>"]
 readme = "README.md"

omnata_plugin_devkit-0.13.2a183/src/omnata_plugin_devkit/jinja_templates/SET_CONNECTION_OBJECTS.sql.jinja

@@ -0,0 +1,367 @@
+create or replace procedure PLUGIN.SET_CONNECTION_OBJECTS(PARAMETERS OBJECT)
+returns object
+language python
+RUNTIME_VERSION = '3.10'
+PACKAGES = ({{packages}})
+IMPORTS = ('/app.zip')
+HANDLER = 'run'
+COMMENT = $$
+Creates or replaces every Snowflake object required to provision a connection: network
+rules, OAuth security integration, OAuth secret, secret authorization configuration,
+other_secrets generic secret, External Access Integration, EAI application specification,
+and Security Integration application specification. OAuth-related objects are only created
+when oauth_security_integration_name is provided.
+
+Expected keys on PARAMETERS:
+  external_access_integration_name             (required; account-level, no schema)
+  network_rule_name                            (required; unqualified — DATA schema is prepended)
+  network_addresses                            (required, array of strings)
+  network_rule_name_privatelink                (optional; unqualified — DATA schema is prepended)
+  network_rule_addresses_privatelink           (required if privatelink rule set)
+  oauth_security_integration_name              (optional; account-level, no schema — enables the oauth branch)
+  oauth_parameters                             (required if oauth SI set; object with
+                                                oauth_grant, oauth_token_endpoint,
+                                                oauth_authorization_endpoint,
+                                                oauth_allowed_scopes, oauth_client_id,
+                                                oauth_client_secret)
+  oauth_secret_name                            (optional; unqualified — DATA schema is prepended; requires oauth SI)
+  oauth_secret_configuration_name              (optional; application-scope, no schema; requires oauth_secret_name)
+  other_secrets_name                           (required; unqualified — DATA schema is prepended)
+  connection_secrets                           (optional object; merged into the generic secret
+                                                contents, overwriting any matching keys from
+                                                merge_with_secret_name)
+  merge_with_secret_name                       (optional; unqualified name of an existing generic
+                                                secret in DATA whose contents are read via
+                                                RETRIEVE_SECRETS_UDF and used as the baseline for
+                                                the new other_secrets generic secret.)
+  external_access_integration_spec_name        (required; application-scope, no schema)
+  security_integration_spec_name               (optional; application-scope, no schema; requires oauth SI)
+  connection_slug                              (required; human-readable connection identifier
+                                                included in spec labels/descriptions so the
+                                                consumer knows which connection they are
+                                                approving)
+$$
+execute as owner
+as
+$$
+import json
+from logging import getLogger
+from typing import Any, Dict, List, Literal, Optional
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+from omnata_plugin_runtime.logging import log_exception
+logger = getLogger(__name__)
+
+_IDENT_PATTERN = r'^[A-Za-z_][A-Za-z0-9_$.]*$'
+_BARE_IDENT_PATTERN = r'^[A-Za-z_][A-Za-z0-9_$]*$'
+_BARE_IDENT_HINT = "must be an unqualified identifier (no schema prefix; DATA. is prepended automatically)"
+
+
+class OAuthParameters(BaseModel):
+   model_config = ConfigDict(extra='allow')
+   oauth_grant: Literal['authorization_code', 'client_credentials'] = 'authorization_code'
+   oauth_token_endpoint: Optional[str] = None
+   oauth_authorization_endpoint: Optional[str] = None
+   oauth_allowed_scopes: Optional[List[str]] = None
+   oauth_client_id: Optional[str] = None
+   oauth_client_secret: Optional[str] = None
+
+
+class SetConnectionParameters(BaseModel):
+   model_config = ConfigDict(extra='ignore')
+
+   external_access_integration_name: str = Field(pattern=_IDENT_PATTERN, max_length=255)
+   network_rule_name: str = Field(pattern=_BARE_IDENT_PATTERN, max_length=255, description=_BARE_IDENT_HINT)
+   network_addresses: List[str]
+   network_rule_name_privatelink: Optional[str] = Field(default=None, pattern=_BARE_IDENT_PATTERN, max_length=255, description=_BARE_IDENT_HINT)
+   network_rule_addresses_privatelink: Optional[List[str]] = None
+   oauth_security_integration_name: Optional[str] = Field(default=None, pattern=_IDENT_PATTERN, max_length=255)
+   oauth_parameters: Optional[OAuthParameters] = None
+   oauth_secret_name: Optional[str] = Field(default=None, pattern=_BARE_IDENT_PATTERN, max_length=255, description=_BARE_IDENT_HINT)
+   oauth_secret_configuration_name: Optional[str] = Field(default=None, pattern=_IDENT_PATTERN, max_length=255)
+   other_secrets_name: str = Field(pattern=_BARE_IDENT_PATTERN, max_length=255, description=_BARE_IDENT_HINT)
+   connection_secrets: Optional[Dict[str, Any]] = None
+   merge_with_secret_name: Optional[str] = Field(default=None, pattern=_BARE_IDENT_PATTERN, max_length=255, description=_BARE_IDENT_HINT)
+   external_access_integration_spec_name: str = Field(pattern=_IDENT_PATTERN, max_length=255)
+   security_integration_spec_name: Optional[str] = Field(default=None, pattern=_IDENT_PATTERN, max_length=255)
+   connection_slug: str = Field(min_length=1, max_length=255)
+
+   @model_validator(mode='after')
+   def _check_combinations(self):
+      if self.network_rule_name_privatelink and self.network_rule_addresses_privatelink is None:
+         raise ValueError("network_rule_addresses_privatelink is required when network_rule_name_privatelink is provided")
+      if self.oauth_security_integration_name and self.oauth_parameters is None:
+         raise ValueError("oauth_parameters (object) is required when oauth_security_integration_name is provided")
+      if self.oauth_secret_name and not self.oauth_security_integration_name:
+         raise ValueError("oauth_security_integration_name is required when oauth_secret_name is provided")
+      if self.oauth_secret_configuration_name and not self.oauth_secret_name:
+         raise ValueError("oauth_secret_name is required when oauth_secret_configuration_name is provided")
+      if self.security_integration_spec_name and not self.oauth_security_integration_name:
+         raise ValueError("oauth_security_integration_name is required when security_integration_spec_name is provided")
+      return self
+
+
+def _esc_sql(s):
+   return str(s).replace("'", "''")
+
+
+def _call_proc(session, sql, params):
+   """Run `CALL PLUGIN.X(...)` and unwrap the {success, data|error} envelope.
+   Raises RuntimeError when success is false; returns `data` on success."""
+   rows = session.sql(sql, params=params).collect()
+   if not rows:
+      raise RuntimeError(f"delegate proc returned no rows: {sql}")
+   val = rows[0][0]
+   if isinstance(val, str):
+      try:
+         val = json.loads(val)
+      except json.JSONDecodeError:
+         pass
+   if isinstance(val, dict) and val.get('success') is False:
+      raise RuntimeError(val.get('error') or f"delegate proc failed: {sql}")
+   return val.get('data') if isinstance(val, dict) else val
+
+
+def run(session, parameters):
+   try:
+      params = SetConnectionParameters.model_validate(parameters or {})
+
+      eai_name                  = params.external_access_integration_name
+      network_rule_name         = params.network_rule_name
+      network_rule_fqn          = f"DATA.{network_rule_name}"
+      network_addresses         = params.network_addresses
+      eai_spec_name             = params.external_access_integration_spec_name
+      connection_slug           = params.connection_slug
+
+      privatelink_rule_name     = params.network_rule_name_privatelink
+      privatelink_rule_fqn      = f"DATA.{privatelink_rule_name}" if privatelink_rule_name else None
+      privatelink_addresses     = params.network_rule_addresses_privatelink
+
+      oauth_si_name             = params.oauth_security_integration_name
+      oauth_parameters          = params.oauth_parameters
+      oauth_secret_name         = params.oauth_secret_name
+      oauth_secret_fqn          = f"DATA.{oauth_secret_name}" if oauth_secret_name else None
+      oauth_secret_config_name  = params.oauth_secret_configuration_name
+      si_spec_name              = params.security_integration_spec_name
+
+      other_secrets_name        = params.other_secrets_name
+      other_secrets_fqn         = f"DATA.{other_secrets_name}"
+      merge_with_secret_name    = params.merge_with_secret_name
+      connection_secrets        = params.connection_secrets
+
+      logger.info(f"SET_CONNECTION_OBJECTS: provisioning connection '{connection_slug}' (EAI {eai_name})")
+
+      # (1) Direct network rule — delegate to CREATE_NETWORK_RULE_OBJECT.
+      _call_proc(
+         session,
+         "call PLUGIN.CREATE_NETWORK_RULE_OBJECT(?, PARSE_JSON(?), ?)",
+         [network_rule_fqn, json.dumps(network_addresses), 'HOST_PORT'],
+      )
+
+      # (2) Privatelink network rule — optional.
+      if privatelink_rule_fqn:
+         _call_proc(
+            session,
+            "call PLUGIN.CREATE_NETWORK_RULE_OBJECT(?, PARSE_JSON(?), ?)",
+            [privatelink_rule_fqn, json.dumps(privatelink_addresses), 'PRIVATE_HOST_PORT'],
+         )
+
+      # (3) OAuth security integration — inline DDL (no existing proc).
+      if oauth_si_name:
+         op = oauth_parameters
+         oauth_grant = op.oauth_grant
+         oauth_token_ep = op.oauth_token_endpoint or ''
+         oauth_auth_ep = op.oauth_authorization_endpoint or ''
+         oauth_scopes = op.oauth_allowed_scopes or []
+         oauth_client_id = op.oauth_client_id
+         oauth_client_secret = op.oauth_client_secret
+
+         clauses = [
+            "TYPE = API_AUTHENTICATION",
+            "AUTH_TYPE = OAUTH2",
+            "OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST",
+            f"OAUTH_GRANT = {oauth_grant.upper()}",
+         ]
+         if oauth_grant == 'authorization_code' and oauth_auth_ep:
+            clauses.append(f"OAUTH_AUTHORIZATION_ENDPOINT = '{_esc_sql(oauth_auth_ep)}'")
+         if oauth_token_ep:
+            clauses.append(f"OAUTH_TOKEN_ENDPOINT = '{_esc_sql(oauth_token_ep)}'")
+         if oauth_scopes:
+            scope_parts = [f"'{_esc_sql(s)}'" for s in oauth_scopes]
+            clauses.append(f"OAUTH_ALLOWED_SCOPES = ({', '.join(scope_parts)})")
+         if oauth_client_id is not None:
+            clauses.append(f"OAUTH_CLIENT_ID = '{_esc_sql(oauth_client_id)}'")
+         if oauth_client_secret is not None:
+            clauses.append(f"OAUTH_CLIENT_SECRET = '{_esc_sql(oauth_client_secret)}'")
+         clauses.append("ENABLED = TRUE")
+
+         si_sql = "CREATE OR REPLACE SECURITY INTEGRATION IDENTIFIER(?)\n  " + "\n  ".join(clauses)
+         logger.info(f"Executing SQL: {si_sql}")
+         session.sql(si_sql, params=[oauth_si_name]).collect()
+         # USAGE on the security integration is required for any APPLICATION_ROLES listed in an
+         # ALTER APPLICATION SET CONFIGURATION DEFINITION SECRET_AUTHORIZATION (the referenced
+         # OAuth secret's API_AUTHENTICATION points to this integration).
+         session.sql(
+            "grant usage on integration IDENTIFIER(?) to application role OMNATA_MANAGEMENT",
+            params=[oauth_si_name],
+         ).collect()
+
+      # (4) OAuth secret — delegate to CREATE_OAUTH_SECRET_OBJECT.
+      if oauth_secret_fqn:
+         _call_proc(
+            session,
+            "call PLUGIN.CREATE_OAUTH_SECRET_OBJECT(?, ?)",
+            [oauth_secret_fqn, oauth_si_name],
+         )
+         # CREATE_OAUTH_SECRET_OBJECT grants USAGE only. MODIFY is required on the secret for
+         # any APPLICATION_ROLES listed in an ALTER APPLICATION SET CONFIGURATION DEFINITION
+         # SECRET_AUTHORIZATION, otherwise the configuration fails with
+         # "role ... is missing 'MODIFY' privilege on Secret".
+         session.sql(
+            "grant modify, usage on secret IDENTIFIER(?) to application role OMNATA_MANAGEMENT",
+            params=[oauth_secret_fqn],
+         ).collect()
+
+      # (5) Secret authorization configuration.
+      # https://docs.snowflake.com/en/developer-guide/native-apps/app-configuration-secret-authorization#step-5-create-the-secret-authorization-configuration
+      if oauth_secret_config_name:
+         # The secret name alternates its trailing __A / __B suffix on each edit; include that
+         # letter in the label so the edit-flow configuration is distinct from the prior one
+         # (configuration definition labels must be unique).
+         secret_alt = oauth_secret_name[-1]
+         cfg_label = f"Authorize OAuth connection: {connection_slug} ({secret_alt})"
+         cfg_description = (
+            f"Complete the OAuth flow so this application can access the external service "
+            f"for connection '{connection_slug}'"
+         )
+         cfg_sql = (
+            f"ALTER APPLICATION SET CONFIGURATION DEFINITION {oauth_secret_config_name}\n"
+            f"  TYPE = SECRET_AUTHORIZATION\n"
+            f"  SECRET = {oauth_secret_fqn}\n"
+            f"  LABEL = '{_esc_sql(cfg_label)}'\n"
+            f"  DESCRIPTION = '{_esc_sql(cfg_description)}'\n"
+            f"  APPLICATION_ROLES = (OMNATA_MANAGEMENT)"
+         )
+         logger.info(f"Executing SQL: {cfg_sql}")
+         session.sql(cfg_sql).collect()
+
+      # (6) Other secrets — seeded from an existing secret and/or caller-supplied values.
+      seed_secrets = {}
+      if merge_with_secret_name:
+         # RETRIEVE_SECRETS_UDF reads the secret contents via _snowflake.get_generic_secret_string,
+         # which takes the binding alias (the unqualified name) — not the FQN. The source secret
+         # must already be bound to RETRIEVE_SECRETS_UDF via a prior CONFIGURE_APIS run.
+         # Passing NULL for the OAuth secret name keeps the access_token key out of the returned object.
+         seed_rows = session.sql(
+            "select PLUGIN.RETRIEVE_SECRETS_UDF(NULL, ?)",
+            params=[merge_with_secret_name],
+         ).collect()
+         seed_value = seed_rows[0][0] if seed_rows else None
+         if isinstance(seed_value, str):
+            try:
+               seed_value = json.loads(seed_value)
+            except json.JSONDecodeError:
+               seed_value = None
+         if isinstance(seed_value, dict):
+            seed_secrets = dict(seed_value)
+      if connection_secrets:
+         for k, v in connection_secrets.items():
+            seed_secrets[k] = v
+      # json.dumps emits strict JSON: every U+0000–U+001F byte is escaped, so PEM line breaks
+      # in caller-supplied values land in SECRET_STRING as `\n` (two bytes) rather than as a
+      # raw LF that would later trip strict json.loads on the read paths.
+      _call_proc(
+         session,
+         "call PLUGIN.CREATE_GENERIC_SECRET_OBJECT(?, ?)",
+         [other_secrets_fqn, json.dumps(seed_secrets)],
+      )
+
+      # (7) External Access Integration.
+      eai_rules = [network_rule_fqn]
+      if privatelink_rule_fqn:
+         eai_rules.append(privatelink_rule_fqn)
+      eai_secrets = [other_secrets_fqn]
+      if oauth_secret_fqn:
+         eai_secrets.append(oauth_secret_fqn)
+
+      eai_rules_sql = ', '.join(eai_rules)
+      eai_secrets_clause = ''
+      if eai_secrets:
+         eai_secrets_clause = f"\n  ALLOWED_AUTHENTICATION_SECRETS = ({', '.join(eai_secrets)})"
+      eai_sql = (
+         f"CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION IDENTIFIER(?)\n"
+         f"  ALLOWED_NETWORK_RULES = ({eai_rules_sql})"
+         f"{eai_secrets_clause}\n"
+         f"  ENABLED = FALSE"
+      )
+      logger.info(f"Executing SQL: {eai_sql}")
+      session.sql(eai_sql, params=[eai_name]).collect()
+      # Grant USAGE so the sync engine (via OMNATA_MANAGEMENT) can see/use the EAI.
+      session.sql(
+         "grant usage on integration IDENTIFIER(?) to application role OMNATA_MANAGEMENT",
+         params=[eai_name],
+      ).collect()
+
+      # (8) EAI application specification — delegate to SET_EAI_SPECIFICATION.
+      # Unlike for security integrations/configurations, this specification does not need to alternate when editing as it's not bound to any objects
+      eai_spec_props = {
+         "LABEL": f"External access for connection: {connection_slug}",
+         "DESCRIPTION": f"Allows this app to communicate with external services for connection '{connection_slug}'",
+         "HOST_PORTS": network_addresses,
+      }
+      if privatelink_addresses:
+         eai_spec_props["PRIVATE_HOST_PORTS"] = privatelink_addresses
+      _call_proc(
+         session,
+         "call PLUGIN.SET_EAI_SPECIFICATION(?, PARSE_JSON(?))",
+         [eai_spec_name, json.dumps(eai_spec_props)],
+      )
+
+      # (9) SI application specification — delegate to SET_SI_SPECIFICATION (OAuth only).
+      if si_spec_name:
+         op2 = oauth_parameters
+         grant_uc = op2.oauth_grant.upper()
+         # Include the alternating suffix letter so the edit-flow spec gets a distinct label.
+         si_spec_alt = si_spec_name[-1]
+         si_spec_props = {
+            "LABEL": f"OAuth integration for connection: {connection_slug} ({si_spec_alt})",
+            "DESCRIPTION": f"Allows this app to use an OAuth security integration for connection '{connection_slug}'",
+            "OAUTH_TYPE": grant_uc,
+         }
+         if op2.oauth_token_endpoint:
+            si_spec_props["OAUTH_TOKEN_ENDPOINT"] = op2.oauth_token_endpoint
+         if grant_uc == 'AUTHORIZATION_CODE' and op2.oauth_authorization_endpoint:
+            si_spec_props["OAUTH_AUTHORIZATION_ENDPOINT"] = op2.oauth_authorization_endpoint
+         if op2.oauth_allowed_scopes:
+            si_spec_props["OAUTH_ALLOWED_SCOPES"] = op2.oauth_allowed_scopes
+         _call_proc(
+            session,
+            "call PLUGIN.SET_SI_SPECIFICATION(?, PARSE_JSON(?))",
+            [si_spec_name, json.dumps(si_spec_props)],
+         )
+
+      return {
+         "success": True,
+         "data": {
+            "connection_slug": connection_slug,
+            "external_access_integration_name": eai_name,
+            "network_rule_name": network_rule_fqn,
+            "network_rule_name_privatelink": privatelink_rule_fqn,
+            "oauth_security_integration_name": oauth_si_name,
+            "oauth_secret_name": oauth_secret_fqn,
+            "oauth_secret_configuration_name": oauth_secret_config_name,
+            "other_secrets_name": other_secrets_fqn,
+            "external_access_integration_spec_name": eai_spec_name,
+            "security_integration_spec_name": si_spec_name,
+         },
+      }
+   except Exception as exception:
+      log_exception(exception, logger)
+      return {
+         "success": False,
+         "error": f"SET_CONNECTION_OBJECTS: {str(exception)}",
+      }
+$$
+;
+
+grant usage on procedure PLUGIN.SET_CONNECTION_OBJECTS(OBJECT)
+to application role OMNATA_MANAGEMENT;

omnata_plugin_devkit-0.13.2a182/src/omnata_plugin_devkit/jinja_templates/SET_CONNECTION_OBJECTS.sql.jinja

@@ -1,375 +0,0 @@
-create or replace procedure PLUGIN.SET_CONNECTION_OBJECTS(PARAMETERS OBJECT)
-   returns object
-   language javascript
-   COMMENT = $$
-   Creates or replaces every Snowflake object required to provision a connection: network
-   rules, OAuth security integration, OAuth secret, secret authorization configuration,
-   other_secrets generic secret, External Access Integration, EAI application specification,
-   and Security Integration application specification. OAuth-related objects are only created
-   when oauth_security_integration_name is provided.
-
-   Expected keys on PARAMETERS:
-     external_access_integration_name             (required; account-level, no schema)
-     network_rule_name                            (required; unqualified — DATA schema is prepended)
-     network_addresses                            (required, array of strings)
-     network_rule_name_privatelink                (optional; unqualified — DATA schema is prepended)
-     network_rule_addresses_privatelink           (required if privatelink rule set)
-     oauth_security_integration_name              (optional; account-level, no schema — enables the oauth branch)
-     oauth_parameters                             (required if oauth SI set; object with
-                                                   oauth_grant, oauth_token_endpoint,
-                                                   oauth_authorization_endpoint,
-                                                   oauth_allowed_scopes, oauth_client_id,
-                                                   oauth_client_secret)
-     oauth_secret_name                            (optional; unqualified — DATA schema is prepended; requires oauth SI)
-     oauth_secret_configuration_name              (optional; application-scope, no schema; requires oauth_secret_name)
-     other_secrets_name                           (required; unqualified — DATA schema is prepended)
-     connection_secrets                           (optional object; merged into the generic secret
-                                                   contents, overwriting any matching keys from
-                                                   merge_with_secret_name)
-     merge_with_secret_name                       (optional; unqualified name of an existing generic
-                                                   secret in DATA whose contents are read via
-                                                   RETRIEVE_SECRETS_UDF and used as the baseline for
-                                                   the new other_secrets generic secret.)
-     external_access_integration_spec_name        (required; application-scope, no schema)
-     security_integration_spec_name               (optional; application-scope, no schema; requires oauth SI)
-     connection_slug                              (required; human-readable connection identifier
-                                                   included in spec labels/descriptions so the
-                                                   consumer knows which connection they are
-                                                   approving)
-   $$
-   execute as owner
-as
-$$
-try{
-    var p = PARAMETERS || {};
-
-    function isIdent(n){
-        return typeof n === 'string' && /^[A-Za-z_][A-Za-z0-9_$.]*$/.test(n) && n.length <= 255;
-    }
-    function isBareIdent(n){
-        return typeof n === 'string' && /^[A-Za-z_][A-Za-z0-9_$]*$/.test(n) && n.length <= 255;
-    }
-    function requireIdent(key){
-        if (!isIdent(p[key])){ throw `parameter '${key}' is required and must be a valid identifier`; }
-        return p[key];
-    }
-    function optIdent(key){
-        if (p[key] == null) return null;
-        if (!isIdent(p[key])){ throw `parameter '${key}' must be a valid identifier`; }
-        return p[key];
-    }
-    function requireBareIdent(key){
-        if (!isBareIdent(p[key])){ throw `parameter '${key}' is required and must be an unqualified identifier (no schema prefix; DATA. is prepended automatically)`; }
-        return p[key];
-    }
-    function optBareIdent(key){
-        if (p[key] == null) return null;
-        if (!isBareIdent(p[key])){ throw `parameter '${key}' must be an unqualified identifier (no schema prefix; DATA. is prepended automatically)`; }
-        return p[key];
-    }
-    function requireArrayOfStrings(key){
-        if (!Array.isArray(p[key])){ throw `parameter '${key}' must be an array of strings`; }
-        p[key].forEach(function(s){ if (typeof s !== 'string'){ throw `parameter '${key}' entries must be strings`; } });
-        return p[key];
-    }
-    function optArrayOfStrings(key){
-        if (p[key] == null) return null;
-        return requireArrayOfStrings(key);
-    }
-    function esc(s){ return String(s).replace(/'/g, "''"); }
-    // JSON.stringify per spec must escape control characters in strings, but
-    // PEM-bearing values (RSA private keys with literal LF/CR line breaks) have
-    // produced stored secrets that strict json.loads rejects with
-    // "Invalid control character at...". Re-escape any control character that
-    // survives serialization so the stored secret is always strict-JSON-parseable.
-    function strictJsonStringify(v){
-        return JSON.stringify(v).replace(/[\x00-\x1f]/g, function(c){
-            switch(c){
-                case '\b': return '\\b';
-                case '\f': return '\\f';
-                case '\n': return '\\n';
-                case '\r': return '\\r';
-                case '\t': return '\\t';
-                default:
-                    return '\\u' + ('0000' + c.charCodeAt(0).toString(16)).slice(-4);
-            }
-        });
-    }
-    function callProc(sql, binds){
-        var rs = snowflake.createStatement({sqlText: sql, binds: binds}).execute();
-        rs.next();
-        var r = rs.getColumnValue(1);
-        if (r && r.success === false){ throw r.error || `delegate proc failed: ${sql}`; }
-        return r;
-    }
-
-    // Required parameters.
-    var eaiName            = requireIdent('external_access_integration_name');
-    var networkRuleName    = requireBareIdent('network_rule_name');
-    var networkRuleFqn     = `DATA.${networkRuleName}`;
-    var networkAddresses   = requireArrayOfStrings('network_addresses');
-    var eaiSpecName        = requireIdent('external_access_integration_spec_name');
-    var connectionSlug     = p.connection_slug;
-    if (typeof connectionSlug !== 'string' || connectionSlug.length === 0 || connectionSlug.length > 255){
-        throw `parameter 'connection_slug' is required and must be a non-empty string`;
-    }
-
-    // Optional privatelink network rule.
-    var privatelinkRuleName   = optBareIdent('network_rule_name_privatelink');
-    var privatelinkRuleFqn    = privatelinkRuleName ? `DATA.${privatelinkRuleName}` : null;
-    var privatelinkAddresses  = optArrayOfStrings('network_rule_addresses_privatelink');
-    if (privatelinkRuleName && privatelinkAddresses === null){
-        throw `network_rule_addresses_privatelink is required when network_rule_name_privatelink is provided`;
-    }
-
-    // Optional OAuth bundle.
-    var oauthSiName            = optIdent('oauth_security_integration_name');
-    var oauthSecretName        = optBareIdent('oauth_secret_name');
-    var oauthSecretFqn         = oauthSecretName ? `DATA.${oauthSecretName}` : null;
-    var oauthSecretConfigName  = optIdent('oauth_secret_configuration_name');
-    var siSpecName             = optIdent('security_integration_spec_name');
-    var oauthParameters        = (typeof p.oauth_parameters === 'object' && p.oauth_parameters !== null) ? p.oauth_parameters : null;
-    if (oauthSiName && !oauthParameters){
-        throw `oauth_parameters (object) is required when oauth_security_integration_name is provided`;
-    }
-    if (oauthSecretName && !oauthSiName){
-        throw `oauth_security_integration_name is required when oauth_secret_name is provided`;
-    }
-    if (oauthSecretConfigName && !oauthSecretName){
-        throw `oauth_secret_name is required when oauth_secret_configuration_name is provided`;
-    }
-    if (siSpecName && !oauthSiName){
-        throw `oauth_security_integration_name is required when security_integration_spec_name is provided`;
-    }
-
-    // Other-secrets (mandatory) plus optional seed/merge inputs.
-    var otherSecretsName     = requireBareIdent('other_secrets_name');
-    var otherSecretsFqn      = `DATA.${otherSecretsName}`;
-    var mergeWithSecretName  = optBareIdent('merge_with_secret_name');
-    var connectionSecrets    = (typeof p.connection_secrets === 'object' && p.connection_secrets !== null && !Array.isArray(p.connection_secrets))
-                               ? p.connection_secrets
-                               : null;
-    if (p.connection_secrets != null && connectionSecrets === null){
-        throw `connection_secrets must be an object`;
-    }
-
-    snowflake.log("info", `SET_CONNECTION_OBJECTS: provisioning connection '${connectionSlug}' (EAI ${eaiName})`);
-
-    // (1) Direct network rule — delegate to CREATE_NETWORK_RULE_OBJECT.
-    callProc(
-        `call PLUGIN.CREATE_NETWORK_RULE_OBJECT(?, PARSE_JSON(?), ?)`,
-        [networkRuleFqn, JSON.stringify(networkAddresses), 'HOST_PORT']
-    );
-
-    // (2) Privatelink network rule — optional.
-    if (privatelinkRuleFqn){
-        callProc(
-            `call PLUGIN.CREATE_NETWORK_RULE_OBJECT(?, PARSE_JSON(?), ?)`,
-            [privatelinkRuleFqn, JSON.stringify(privatelinkAddresses), 'PRIVATE_HOST_PORT']
-        );
-    }
-
-    // (3) OAuth security integration — inline DDL (no existing proc).
-    if (oauthSiName){
-        var op = oauthParameters;
-        var oauthGrant        = String(op.oauth_grant || 'authorization_code').toLowerCase();
-        var oauthTokenEp      = op.oauth_token_endpoint || '';
-        var oauthAuthEp       = op.oauth_authorization_endpoint || '';
-        var oauthScopes       = Array.isArray(op.oauth_allowed_scopes) ? op.oauth_allowed_scopes : [];
-        var oauthClientId     = op.oauth_client_id;
-        var oauthClientSecret = op.oauth_client_secret;
-
-        if (oauthGrant !== 'authorization_code' && oauthGrant !== 'client_credentials'){
-            throw `oauth_parameters.oauth_grant must be 'authorization_code' or 'client_credentials'`;
-        }
-
-        var clauses = [
-            "TYPE = API_AUTHENTICATION",
-            "AUTH_TYPE = OAUTH2",
-            "OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST",
-            `OAUTH_GRANT = ${oauthGrant.toUpperCase()}`
-        ];
-        if (oauthGrant === 'authorization_code' && oauthAuthEp){
-            clauses.push(`OAUTH_AUTHORIZATION_ENDPOINT = '${esc(oauthAuthEp)}'`);
-        }
-        if (oauthTokenEp){
-            clauses.push(`OAUTH_TOKEN_ENDPOINT = '${esc(oauthTokenEp)}'`);
-        }
-        if (oauthScopes.length > 0){
-            var scopesList = oauthScopes.map(function(s){
-                if (typeof s !== 'string'){ throw `oauth_parameters.oauth_allowed_scopes entries must be strings`; }
-                return `'${esc(s)}'`;
-            }).join(', ');
-            clauses.push(`OAUTH_ALLOWED_SCOPES = (${scopesList})`);
-        }
-        if (oauthClientId != null){
-            if (typeof oauthClientId !== 'string'){ throw `oauth_parameters.oauth_client_id must be a string`; }
-            clauses.push(`OAUTH_CLIENT_ID = '${esc(oauthClientId)}'`);
-        }
-        if (oauthClientSecret != null){
-            if (typeof oauthClientSecret !== 'string'){ throw `oauth_parameters.oauth_client_secret must be a string`; }
-            clauses.push(`OAUTH_CLIENT_SECRET = '${esc(oauthClientSecret)}'`);
-        }
-        clauses.push("ENABLED = TRUE");
-
-        var siSql = `CREATE OR REPLACE SECURITY INTEGRATION IDENTIFIER(?)\n  ` + clauses.join('\n  ');
-        snowflake.log("info", `Executing SQL: ${siSql}`);
-        snowflake.createStatement({sqlText: siSql, binds: [oauthSiName]}).execute();
-        // USAGE on the security integration is required for any APPLICATION_ROLES listed in an
-        // ALTER APPLICATION SET CONFIGURATION DEFINITION SECRET_AUTHORIZATION (the referenced
-        // OAuth secret's API_AUTHENTICATION points to this integration).
-        snowflake.createStatement({
-            sqlText: `grant usage on integration IDENTIFIER(?) to application role OMNATA_MANAGEMENT`,
-            binds: [oauthSiName]
-        }).execute();
-    }
-
-    // (4) OAuth secret — delegate to CREATE_OAUTH_SECRET_OBJECT.
-    if (oauthSecretFqn){
-        callProc(`call PLUGIN.CREATE_OAUTH_SECRET_OBJECT(?, ?)`, [oauthSecretFqn, oauthSiName]);
-        // CREATE_OAUTH_SECRET_OBJECT grants USAGE only. MODIFY is required on the secret for
-        // any APPLICATION_ROLES listed in an ALTER APPLICATION SET CONFIGURATION DEFINITION
-        // SECRET_AUTHORIZATION, otherwise the configuration fails with
-        // "role ... is missing 'MODIFY' privilege on Secret".
-        snowflake.createStatement({
-            sqlText: `grant modify, usage on secret IDENTIFIER(?) to application role OMNATA_MANAGEMENT`,
-            binds: [oauthSecretFqn]
-        }).execute();
-    }
-
-    // (5) Secret authorization configuration.
-    // TODO: verify exact DDL and keywords against Snowflake docs; WebFetch was unavailable during authoring.
-    // https://docs.snowflake.com/en/developer-guide/native-apps/app-configuration-secret-authorization#step-5-create-the-secret-authorization-configuration
-    if (oauthSecretConfigName){
-        // The secret name alternates its trailing __A / __B suffix on each edit; include that
-        // letter in the label so the edit-flow configuration is distinct from the prior one
-        // (configuration definition labels must be unique).
-        var secretAlt      = oauthSecretName.slice(-1);
-        var cfgLabel       = `Authorize OAuth connection: ${connectionSlug} (${secretAlt})`;
-        var cfgDescription = `Complete the OAuth flow so this application can access the external service for connection '${connectionSlug}'`;
-        var cfgSql = `ALTER APPLICATION SET CONFIGURATION DEFINITION ${oauthSecretConfigName}\n` +
-                     `  TYPE = SECRET_AUTHORIZATION\n` +
-                     `  SECRET = ${oauthSecretFqn}\n` +
-                     `  LABEL = '${esc(cfgLabel)}'\n` +
-                     `  DESCRIPTION = '${esc(cfgDescription)}'\n` +
-                     `  APPLICATION_ROLES = (OMNATA_MANAGEMENT)`;
-        snowflake.log("info", `Executing SQL: ${cfgSql}`);
-        snowflake.createStatement({sqlText: cfgSql, binds: []}).execute();
-    }
-
-    // (6) Other secrets — seeded from an existing secret and/or caller-supplied values.
-    var seedSecrets = {};
-    if (mergeWithSecretName){
-        // RETRIEVE_SECRETS_UDF reads the secret contents via _snowflake.get_generic_secret_string,
-        // which takes the binding alias (the unqualified name) — not the FQN. The source secret
-        // must already be bound to RETRIEVE_SECRETS_UDF via a prior CONFIGURE_APIS run.
-        // Passing NULL for the OAuth secret name keeps the access_token key out of the returned object.
-        var seedRs = snowflake.createStatement({
-            sqlText: `select PLUGIN.RETRIEVE_SECRETS_UDF(NULL, ?)`,
-            binds: [mergeWithSecretName]
-        }).execute();
-        seedRs.next();
-        var seedValue = seedRs.getColumnValue(1);
-        if (seedValue && typeof seedValue === 'object'){
-            seedSecrets = seedValue;
-        }
-    }
-    if (connectionSecrets){
-        Object.keys(connectionSecrets).forEach(function(k){
-            seedSecrets[k] = connectionSecrets[k];
-        });
-    }
-    callProc(`call PLUGIN.CREATE_GENERIC_SECRET_OBJECT(?, ?)`, [otherSecretsFqn, strictJsonStringify(seedSecrets)]);
-
-    // (7) External Access Integration.
-    var eaiRules = [networkRuleFqn];
-    if (privatelinkRuleFqn){ eaiRules.push(privatelinkRuleFqn); }
-    var eaiSecrets = [otherSecretsFqn];
-    if (oauthSecretFqn){ eaiSecrets.push(oauthSecretFqn); }
-
-    var eaiRulesSql = eaiRules.join(', ');
-    var eaiSecretsClause = '';
-    if (eaiSecrets.length > 0){
-        eaiSecretsClause = `\n  ALLOWED_AUTHENTICATION_SECRETS = (${eaiSecrets.join(', ')})`;
-    }
-    var eaiSql = `CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION IDENTIFIER(?)\n` +
-                 `  ALLOWED_NETWORK_RULES = (${eaiRulesSql})` +
-                 eaiSecretsClause + `\n` +
-                 `  ENABLED = FALSE`;
-    snowflake.log("info", `Executing SQL: ${eaiSql}`);
-    snowflake.createStatement({sqlText: eaiSql, binds: [eaiName]}).execute();
-    // Grant USAGE so the sync engine (via OMNATA_MANAGEMENT) can see/use the EAI.
-    snowflake.createStatement({
-        sqlText: `grant usage on integration IDENTIFIER(?) to application role OMNATA_MANAGEMENT`,
-        binds: [eaiName]
-    }).execute();
-
-    // (8) EAI application specification — delegate to SET_EAI_SPECIFICATION.
-    // Unlike for security integrations/configurations, this specification does not need to alternate when editing as it's not bound to any objects
-    var eaiSpecProps = {
-        LABEL: `External access for connection: ${connectionSlug}`,
-        DESCRIPTION: `Allows this app to communicate with external services for connection '${connectionSlug}'`,
-        HOST_PORTS: networkAddresses
-    };
-    if (privatelinkAddresses){
-        eaiSpecProps.PRIVATE_HOST_PORTS = privatelinkAddresses;
-    }
-    callProc(
-        `call PLUGIN.SET_EAI_SPECIFICATION(?, PARSE_JSON(?))`,
-        [eaiSpecName, JSON.stringify(eaiSpecProps)]
-    );
-
-    // (9) SI application specification — delegate to SET_SI_SPECIFICATION (OAuth only).
-    if (siSpecName){
-        var op2 = oauthParameters;
-        var grantUc = String(op2.oauth_grant || 'authorization_code').toUpperCase();
-        // Include the alternating suffix letter so the edit-flow spec gets a distinct label.
-        var siSpecAlt = siSpecName.slice(-1);
-        var siSpecProps = {
-            LABEL: `OAuth integration for connection: ${connectionSlug} (${siSpecAlt})`,
-            DESCRIPTION: `Allows this app to use an OAuth security integration for connection '${connectionSlug}'`,
-            OAUTH_TYPE: grantUc
-        };
-        if (op2.oauth_token_endpoint){
-            siSpecProps.OAUTH_TOKEN_ENDPOINT = op2.oauth_token_endpoint;
-        }
-        if (grantUc === 'AUTHORIZATION_CODE' && op2.oauth_authorization_endpoint){
-            siSpecProps.OAUTH_AUTHORIZATION_ENDPOINT = op2.oauth_authorization_endpoint;
-        }
-        if (Array.isArray(op2.oauth_allowed_scopes) && op2.oauth_allowed_scopes.length > 0){
-            siSpecProps.OAUTH_ALLOWED_SCOPES = op2.oauth_allowed_scopes;
-        }
-        callProc(
-            `call PLUGIN.SET_SI_SPECIFICATION(?, PARSE_JSON(?))`,
-            [siSpecName, JSON.stringify(siSpecProps)]
-        );
-    }
-
-    return {
-        "success": true,
-        "data": {
-            "connection_slug": connectionSlug,
-            "external_access_integration_name": eaiName,
-            "network_rule_name": networkRuleFqn,
-            "network_rule_name_privatelink": privatelinkRuleFqn,
-            "oauth_security_integration_name": oauthSiName,
-            "oauth_secret_name": oauthSecretFqn,
-            "oauth_secret_configuration_name": oauthSecretConfigName,
-            "other_secrets_name": otherSecretsFqn,
-            "external_access_integration_spec_name": eaiSpecName,
-            "security_integration_spec_name": siSpecName
-        }
-    };
-}
-catch(e){
-    snowflake.log("error", e);
-    return {
-        "success": false,
-        "error": `SET_CONNECTION_OBJECTS: ${String(e)}`
-    };
-}
-$$
-;
-
-grant usage on procedure PLUGIN.SET_CONNECTION_OBJECTS(OBJECT)
-to application role OMNATA_MANAGEMENT;