Skip to content

cxRegistry

Auto-generated documentation from JSDoc comments

cxRegistry

Project-scoped persistent key-value store with optional encryption. Data is stored in PostgreSQL and persists across script executions. Sensitive values are encrypted at rest using AES-256-GCM.

Example

import { get, set, keys, list } from 'cxRegistry';

export async function main(data) {
  // Store plaintext values
  await set('config.theme', 'dark');
  await set('settings', { timezone: 'UTC', locale: 'en' });

  // Store sensitive values (encrypted at rest)
  await set('api.key', 'sk-secret-123', { sensitive: true });

  // Retrieve values (auto-decrypts sensitive)
  let theme = await get('config.theme');
  let settings = await get('settings');
  let apiKey = await get('api.key');

  // List all keys
  let allKeys = await keys();

  return { theme, settings, apiKey, allKeys };
}

Proxy secrets (write-only)

A value stored with visibility: 'proxy' can be used but never read by a script. It is always encrypted at rest, and get() throws for it. To use one, write the sentinel __AUTH_<KEY>__ (the key, uppercased) anywhere in an outgoing request header — ScriptForge substitutes the real value at the host boundary, after your code has handed off the request:

import { set } from 'cxRegistry';

// Store once (e.g. from a setup script)
await set('stripe', 'sk_live_xxx', { visibility: 'proxy' });

// Use it anywhere — the value never enters the sandbox
const res = await fetch('https://api.stripe.com/v1/charges', {
  headers: { 'X-Api-Key': '__AUTH_STRIPE__' },
});

// Works embedded in a larger value too
await fetch(url, { headers: { Authorization: 'Basic __AUTH_CREDS__' } });

await get('stripe'); // throws — proxy secrets cannot be read

Use this for third-party API tokens so a script (or one of its dependencies) cannot read the credential or forward it somewhere unintended.

Kind: global class

cxRegistry.get(key) ⇒ Promise.<any>

Get a value by key (auto-decrypts sensitive values)

Kind: static method of cxRegistry
Returns: Promise.<any> - The stored value, or null if not found
Throws:

  • Error If the key holds a proxy secret, which is write-only and can only be used via the __AUTH_<KEY>__ sentinel in a fetch header
Param Type Description
key string The key to retrieve

Example

const value = await get('config.theme');
const settings = await get('settings'); // objects work too

cxRegistry.set(key, value, [options]) ⇒ Promise.<void>

Set a value by key

Kind: static method of cxRegistry

Param Type Default Description
key string The key to store (lowercase alphanumeric, dots, hyphens, underscores)
value any The value to store (null to delete)
[options] object Storage options
[options.sensitive] boolean false Encrypt the value at rest (implied by visibility: 'proxy')
[options.visibility] 'private' | 'public' | 'proxy' 'private' Visibility level. private is readable by scripts in this project; public is also readable by the frontend; proxy is a write-only secret — always encrypted, never readable by a script, and only substituted into outgoing fetch headers via __AUTH_<KEY>__.
[options.ttl] number Time to live in seconds

Example

// Simple set
await set('config.theme', 'dark');

// Store objects
await set('settings', { timezone: 'UTC', locale: 'en' });

// With TTL (expires in 1 hour)
await set('cache.token', 'abc123', { ttl: 3600 });

// Encrypted sensitive value
await set('secrets.api_key', 'sk-xxx', { sensitive: true });

// Public visibility (accessible from frontend)
await set('config.public_setting', 'value', { visibility: 'public' });

// Write-only proxy secret: usable in a fetch header, never readable
await set('stripe', 'sk_live_xxx', { visibility: 'proxy' });
await fetch(url, { headers: { 'X-Api-Key': '__AUTH_STRIPE__' } });

// Delete a key
await set('config.theme', null);

cxRegistry.delete(key) ⇒ Promise.<boolean>

Delete a key from the registry

Kind: static method of cxRegistry
Returns: Promise.<boolean> - True if deleted, false if not found

Param Type Description
key string The key to delete

Example

import { delete as del } from 'cxRegistry';
const deleted = await del('config.theme');

cxRegistry.keys() ⇒ Promise.<Array.<string>>

Get all keys in the registry

Kind: static method of cxRegistry
Returns: Promise.<Array.<string>> - Array of all keys (excludes expired)
Example

const allKeys = await keys();
console.log(`Found ${allKeys.length} keys`);

cxRegistry.list() ⇒ Promise.<Array.<{key: string, value: any, sensitive: boolean, visibility: string, expiresAt: (Date|null)}>>

List all entries in the registry (decrypts sensitive values)

Kind: static method of cxRegistry
Returns: Promise.<Array.<{key: string, value: any, sensitive: boolean, visibility: string, expiresAt: (Date|null)}>> - Proxy secrets are listed with value: null and proxy: true — their values are never returned.
Example

const entries = await list();
for (const entry of entries) {
  console.log(`${entry.key}: ${entry.value} (sensitive: ${entry.sensitive})`);
}

cxRegistry.listPublic() ⇒ Promise.<Array.<{key: string, value: any}>>

List only public visibility entries

Kind: static method of cxRegistry
Example

const publicEntries = await listPublic();