Widgets/Transformer

Secret Widget

Secret Widget

A "Transformer" type widget. Secret Widget securely retrieves decrypted secret values from the Hub and transmits them when triggered. It's designed to handle sensitive data like API keys, passwords, database credentials, or any configuration values that have been mapped to the recipe.

The widget ensures secure access to secrets by only retrieving values that have been explicitly mapped to the current recipe.

 

Inputs

  • read (DataType: Anything) The main input port that triggers secret retrieval. Any event received here will fetch the secret value specified in the Name setting and emit it through the value output port.

Outputs

  • value (DataType: String) Outputs the decrypted secret value if it's properly mapped to the recipe. If the secret name specified in Name is not mapped to the current recipe, the widget will throw an error instead of outputting a value.

Custom Settings

  • Name Setting — Specifies the secret key to read from the Hub. You must ensure the recipe has a proper mapping for this secret name before the widget can successfully retrieve its value.

Custom settings

 

Adding a New Secret in the Kemu Hub

API keys, passwords, and other sensitive configuration values can be securely stored in the Kemu Hub as secrets. These secrets are later retrieved by the Secret Widget within recipes.

  1. Open Account Settings
    Click your profile icon and select Manage Account.

  2. Access Hub Secrets
    In the account window, open Hub Secrets.

  3. Click Add Secret, then enter:

    • Name: e.g., CUSTOM_SECRET
    • Context: select or type a context (e.g., my_context)
    • Value: the secret’s value or API key

  4. Click Save to securely store the secret in the Hub.

The new secret will appear in the list and can be mapped to recipes through the Secret Mapping panel.


Adding new secret



Mapping a Secret to a Recipe

When a Secret Widget is added to a recipe and a secret name is entered (e.g., CUSTOM_SECRET), a red Recipe Secrets icon appears in the sidebar indicating that the secret must be mapped.

  1. Open Recipe Secrets
    Click the red Recipe Secrets icon to open the Secret Mapping window.

  2. Select Context and Variable

    • Context (A): Contexts allow you to group secrets by a common category. E.g. "Client A", or "Development".
    • Environment Variable (B): Select the matching variable (e.g., CUSTOM_SECRET).

  3. Save and Close
    Click Save, then Close to confirm the mapping.

Once mapped, the Secret Widget can securely retrieve its value from the Hub when triggered in the recipe.


Mapping secret

 

Examples

Basic Secret Retrieval

This example illustrates the core behavior of the Secret Widget: retrieving a secret value and displaying it in a Text widget.


Drag the example onto the workspace to explore and experiment!



In this example

  1. The Button widget triggers the Secret widget to retrieve the mapped secret value
  2. The Secret widget securely fetches the secret from the Hub and outputs its value to the Text widget
  3. The Text widget displays the retrieved secret value

 

Example 2: Secret Access in Exported Recipes

This example demonstrates the Secret Widget's core functionality in a complete exportable workflow, showcasing how secrets remain accessible and secure even after exporting recipes to standalone applications. This example proves that exported recipes maintain full access to mapped secrets, making them perfect for production deployments.


Drag the example onto the workspace to explore and experiment!


In this example:

  1. Input Widget (task) receives string data from external code via sendToInputWidgetAndWaitForOutput()
  2. Secret Widget Retrieves the API_KEY secret value from the Hub and passes it to the next widget
  3. Template String Widget Combines the input task string with the secret API key using Mustache syntax to generate: "Starting task with API Key: {API_KEY}..."
  4. Output Widget transmits the final processed result directly back to external code via sendToInputWidgetAndWaitForOutput()

How to Run This Example

  1. Export the recipe as "Javascript Library Mode" from Kemu Edge
  2. Modify the main.js file with the following code:

import kemuEdge, { DataType } from '@kemu-io/edge-runtime';

console.log('Starting recipe...');
const recipe = await kemuEdge.start();
console.log('Recipe running...');

// Send data and wait for output directly
const result = await recipe.sendToInputWidgetAndWaitForOutput('task', {
  type: DataType.String,
  value: 'My Task'
});

console.log('Result:', result);

  1. Open the exported folder in terminal and run:

    npm install
node main.js

    Note: If you enabled "Install dependencies" during export, npm install was already executed automatically.

  2. Expected Output: The terminal will display:

    Starting recipe...
Recipe running...
Result: Starting task with API Key: your-actual-api-key...

  • The recipe processes the input string "My Task" and combines it with the secret API_KEY retrieved from the Hub, then returns the formatted message through the Output Widget.

  • Secrets remain fully accessible in exported recipes. The Secret Widget retrieves the API_KEY from the Hub, and all configured secrets are stored in the .env file within the exported folder.

 

Security Features

  • Recipe-specific mapping: Secrets can only be accessed if they're explicitly mapped to the current recipe
  • Encrypted storage: All secrets are encrypted in the Hub and only decrypted when needed
  • Runtime validation: The widget validates secret mappings every time a secret is accessed
  • Error handling: Throws descriptive errors when secrets are not found or not properly mapped

 

Glossary

  • Hub

    The Kemu Hub App is a desktop application that serves as a centralized service management system, allowing you to install and manage Hub Services (like ChatGPT, image processing tools, etc.). The Hub Secrets are managed through the Kemu web application, where you can securely store API keys, passwords, and other sensitive configuration values, organize them by contexts, and map them to specific recipes.

  • Recipe Mapping

    The process of associating specific secrets with individual recipes, ensuring that each recipe can only access secrets it has been explicitly granted permission to use.

  • Dynamic Secrets

    A feature that allows secrets to be specified at runtime rather than being predefined in widget manifests, providing flexibility for different deployment environments.