feat(hubspot): add api_key_name support for Vault secret lookup by name (supabase#545)

* feat(hubspot): add api_key_name support for Vault secret lookup by name

## Summary
Add `api_key_name` support to HubSpot FDW, enabling Vault secret lookup by name for environment-agnostic configuration.

### Infrastructure Changes (enables feature for all WASM FDWs)
- Add `get-vault-secret-by-name` function to WIT interface (v1 and v2)
- Implement host-side binding to call native `get_vault_secret_by_name`

### HubSpot FDW Changes
- Add `api_key_name` option to HubSpot FDW authentication
- Follow Stripe FDW implementation pattern
- Update documentation with examples

Fixes supabase#437

* docs(hubspot): clarify that api_key accepts Private App Access Token

Add note explaining that HubSpot deprecated their legacy API Keys in
November 2022 and that the api_key option accepts Private App Access
Tokens, which is HubSpot's recommended authentication method.

This helps address confusion reported in supabase#461.

* fix: correct Rust type errors in api_key retrieval

- Remove `.cloned()` call on Option<String> (already owned)
- Pass &key_id and &key_name to get_vault_secret functions (expects &str)

Author: JohnCari

docs/catalog/hubspot.md

@@ -42,6 +42,9 @@ create foreign data wrapper wasm_wrapper
   validator wasm_fdw_validator;
 ```
 
+!!! note "About Authentication"
+    HubSpot deprecated their legacy API Keys in November 2022. The `api_key` option in this wrapper accepts a **Private App Access Token**, which is HubSpot's recommended authentication method. See [HubSpot Private Apps](https://developers.hubspot.com/docs/guides/apps/private-apps/overview) for setup instructions.
+
 ### Store your credentials (optional)
 
 By default, Postgres stores FDW credentials inside `pg_catalog.pg_foreign_server` in plain text. Anyone with access to this table will be able to view these credentials. Wrappers is designed to work with [Vault](https://supabase.com/docs/guides/database/vault), which provides an additional level of security for storing credentials. We recommend using Vault to store your credentials.
@@ -50,16 +53,18 @@ By default, Postgres stores FDW credentials inside `pg_catalog.pg_foreign_server
 -- Save your HubSpot private apps access token in Vault and retrieve the created `key_id`
 select vault.create_secret(
   '<HubSpot access token>', -- HubSpot private apps access token
-  'hubspot',
+  'hubspot',  -- secret name for api_key_name lookup
   'HubSpot private apps access token for Wrappers'
 );
 ```
 
+The secret name (e.g., `'hubspot'`) can be used with `api_key_name` for environment-agnostic configuration.
+
 ### Connecting to HubSpot
 
 We need to provide Postgres with the credentials to access HubSpot and any additional options. We can do this using the `create server` command:
 
-=== "With Vault"
+=== "With Vault (by ID)"
 
     ```sql
     create server hubspot_server
@@ -74,6 +79,23 @@ We need to provide Postgres with the credentials to access HubSpot and any addit
       );
     ```
 
+=== "With Vault (by Name)"
+
+    ```sql
+    create server hubspot_server
+      foreign data wrapper wasm_wrapper
+      options (
+        fdw_package_url 'https://github.com/supabase/wrappers/releases/download/wasm_hubspot_fdw_v0.1.0/hubspot_fdw.wasm',
+        fdw_package_name 'supabase:hubspot-fdw',
+        fdw_package_version '0.1.0',
+        fdw_package_checksum '2cbf39e9e28aa732a225db09b2186a2342c44697d4fa047652d358e292ba5521',
+        api_url 'https://api.hubapi.com/crm/v3',  -- optional
+        api_key_name 'hubspot' -- The secret name from above.
+      );
+    ```
+
+    Using `api_key_name` enables environment-agnostic configuration - the same SQL works across dev, staging, and production as long as each environment has a Vault secret with the same name.
+
 === "Without Vault"
 
     ```sql

wasm-wrappers/fdw/hubspot_fdw/src/lib.rs

@@ -221,13 +221,17 @@ impl Guest for HubspotFdw {
         // get foreign server options
         let opts = ctx.get_options(&OptionsType::Server);
         this.base_url = opts.require_or("api_url", "https://api.hubapi.com/crm/v3");
-        let api_key = match opts.get("api_key") {
-            Some(key) => key,
-            None => {
-                let key_id = opts.require("api_key_id")?;
-                utils::get_vault_secret(&key_id).unwrap_or_default()
-            }
-        };
+        let api_key = opts
+            .get("api_key")
+            .or_else(|| {
+                opts.get("api_key_id")
+                    .and_then(|key_id| utils::get_vault_secret(&key_id))
+            })
+            .or_else(|| {
+                opts.get("api_key_name")
+                    .and_then(|key_name| utils::get_vault_secret_by_name(&key_name))
+            })
+            .ok_or("missing required option: 'api_key', 'api_key_id', or 'api_key_name'")?;
 
         // HubSpot API authentication
         // ref: https://developers.hubspot.com/docs/guides/apps/authentication/intro-to-auth

wasm-wrappers/wit/v1/utils.wit

@@ -8,4 +8,5 @@ interface utils {
 
     cell-to-string: func(cell: option<cell>) -> string;
     get-vault-secret: func(secret-id: string) -> option<string>;
+    get-vault-secret-by-name: func(secret-name: string) -> option<string>;
 }

wasm-wrappers/wit/v2/utils.wit

@@ -8,4 +8,5 @@ interface utils {
 
     cell-to-string: func(cell: option<cell>) -> string;
     get-vault-secret: func(secret-id: string) -> option<string>;
+    get-vault-secret-by-name: func(secret-name: string) -> option<string>;
 }

wrappers/src/fdw/wasm_fdw/host/utils.rs

@@ -36,6 +36,10 @@ const _: () = {
         fn get_vault_secret(&mut self, secret_id: String) -> Option<String> {
             get_vault_secret(&secret_id)
         }
+
+        fn get_vault_secret_by_name(&mut self, secret_name: String) -> Option<String> {
+            get_vault_secret_by_name(&secret_name)
+        }
     }
 };
 
@@ -71,5 +75,9 @@ const _: () = {
         fn get_vault_secret(&mut self, secret_id: String) -> Option<String> {
             get_vault_secret(&secret_id)
         }
+
+        fn get_vault_secret_by_name(&mut self, secret_name: String) -> Option<String> {
+            get_vault_secret_by_name(&secret_name)
+        }
     }
 };