Runtime API

The Frostbite Runtime API provides specialized functionality for using encrypted files in live project environments. It allows you to decrypt files in memory without writing sensitive data to disk, watch files for changes, and more.

createRuntime()

Creates a new FrostbiteRuntime instance for live project environments.

Syntax

const frostbite = require('frostbite');

const runtime = frostbite.createRuntime(options);

Parameters

Parameter Type Description
options object Runtime options
options.key string Encryption/decryption key
options.license string (Optional) License key for additional protection

Return Value

Returns a FrostbiteRuntime instance with the methods described in this documentation.

Example

const frostbite = require('frostbite');

// Create a runtime instance
const runtime = frostbite.createRuntime({
  key: process.env.FROSTBITE_KEY,
  license: process.env.FROSTBITE_LICENSE
});

initialize()

Initializes the runtime by deriving the encryption key.

Syntax

await runtime.initialize();

Return Value

Returns a Promise that resolves to the runtime instance for chaining.

Example

const runtime = frostbite.createRuntime({
  key: process.env.FROSTBITE_KEY
});

// Initialize the runtime
await runtime.initialize();

decryptFile()

Decrypts a file and returns its contents without writing to disk.

Syntax

const content = await runtime.decryptFile(filePath, options);

Parameters

Parameter Type Description
filePath string Path to the encrypted file
options object (Optional) Decryption options
options.cache boolean (Optional) Whether to cache the decrypted content (default: true)
options.encoding string (Optional) Encoding to use for the decrypted content (e.g., 'utf8')

Return Value

Returns a Promise that resolves to a Buffer containing the decrypted content, or a string if an encoding is specified.

Example

// Initialize the runtime
await runtime.initialize();

// Decrypt a file as a buffer
const binaryContent = await runtime.decryptFile('./config/binary-data.bin.fbz');

// Decrypt a file as text
const textContent = await runtime.decryptFile('./config/text-file.txt.fbz', {
  encoding: 'utf8'
});

requireJSON()

Decrypts a JSON file and parses its contents.

Syntax

const jsonData = await runtime.requireJSON(filePath, options);

Parameters

Parameter Type Description
filePath string Path to the JSON file (with or without .fbz extension)
options object (Optional) Decryption options
options.cache boolean (Optional) Whether to cache the decrypted content (default: true)

Return Value

Returns a Promise that resolves to the parsed JSON object.

Example

// Initialize the runtime
await runtime.initialize();

// Load and parse a JSON configuration file
const config = await runtime.requireJSON('./config/production.json.fbz');

console.log(`Database URL: ${config.database.url}`);
console.log(`API Key: ${config.apiKey}`);

watch()

Watches a file or directory for changes and automatically encrypts/decrypts files.

Syntax

const watcher = await runtime.watch(targetPath, options);

Parameters

Parameter Type Description
targetPath string Path to the file or directory to watch
options object (Optional) Watch options
options.autoDecrypt boolean (Optional) Automatically decrypt files when they change (default: true)
options.autoEncrypt boolean (Optional) Automatically encrypt files when they change (default: false)
options.onChange function (Optional) Callback function when a file changes

Return Value

Returns a Promise that resolves to a watcher object.

Example

// Initialize the runtime
await runtime.initialize();

// Watch a directory for changes
await runtime.watch('./config', {
  autoDecrypt: true,  // Decrypt files when they change
  autoEncrypt: true,  // Encrypt files when they change
  onChange: (action, filePath, content) => {
    console.log(`File ${filePath} was ${action}ed`);

    // Reload configuration if needed
    if (filePath.includes('config.json')) {
      // Handle configuration change
    }
  }
});

unwatch()

Stops watching a file or directory.

Syntax

await runtime.unwatch(targetPath);

Parameters

Parameter Type Description
targetPath string Path to stop watching

Return Value

Returns a Promise that resolves when the watcher is closed.

Example

// Start watching
await runtime.watch('./config');

// Later, stop watching
await runtime.unwatch('./config');

clearCache()

Clears the decrypted content cache.

Syntax

runtime.clearCache();

Example

// Clear the cache to force re-decryption on next access
runtime.clearCache();

close()

Closes the runtime and cleans up resources.

Syntax

await runtime.close();

Return Value

Returns a Promise that resolves when all resources are cleaned up.

Example

// When shutting down the application
process.on('SIGTERM', async () => {
  console.log('Shutting down...');

  // Close the runtime to clean up resources
  await runtime.close();

  process.exit(0);
});

Live Project Example

Here's a complete example of using the Runtime API in a live project:

const express = require('express');
const frostbite = require('frostbite');

// Create Express app
const app = express();
const PORT = process.env.PORT || 3000;

// Create a runtime instance
const runtime = frostbite.createRuntime({
  key: process.env.FROSTBITE_KEY
});

async function startServer() {
  // Initialize the runtime
  await runtime.initialize();

  try {
    // Load configuration
    const config = await runtime.requireJSON('./config/production.json');

    // Set up middleware
    app.use(express.json());

    // Set up routes
    app.get('/api/status', (req, res) => {
      res.json({ status: 'ok' });
    });

    // Start watching for configuration changes
    await runtime.watch('./config', {
      autoDecrypt: true,
      onChange: async (action, filePath) => {
        if (filePath.includes('production.json')) {
          console.log('Configuration changed, reloading...');

          // Reload configuration
          const newConfig = await runtime.requireJSON('./config/production.json', {
            cache: false  // Force re-reading the file
          });

          // Update application with new configuration
          // ...
        }
      }
    });

    // Start the server
    app.listen(PORT, () => {
      console.log(`Server running on port ${PORT}`);
    });

    // Handle graceful shutdown
    process.on('SIGTERM', async () => {
      console.log('Shutting down...');
      await runtime.close();
      process.exit(0);
    });
  } catch (error) {
    console.error('Failed to start server:', error);
    process.exit(1);
  }
}

startServer();