@friggframework/core 2.0.0--canary.623.b39b42d.0 → 2.0.0--canary.625.950ba82.0

package/core/CLAUDE.md

@@ -131,6 +131,7 @@ class MyIntegration extends Delegate {
    ```javascript
    initDebugLog(eventName, event);           // Debug logging setup
    await secretsToEnv();                     // Secrets Manager injection
+   await parametersToEnv();                  // SSM Parameter Store fetch (only when SSM_PARAMETER_PREFIX + FRIGG_SSM_OFFLOADED_KEYS are set)
    context.callbackWaitsForEmptyEventLoop = false; // Connection pooling
    ```
 
@@ -165,6 +166,15 @@ class MyIntegration extends Delegate {
 - **Security**: No secrets logging or exposure in error messages
 - **Caching**: Secrets cached for Lambda container lifetime
 
+### SSM Parameter Store Loader (`parameters-to-env.js`)
+Offloads env vars that would otherwise exceed Lambda's 4KB env limit. Runs right after `secretsToEnv()` and is a no-op unless both `SSM_PARAMETER_PREFIX` and `FRIGG_SSM_OFFLOADED_KEYS` (comma-separated env var names) are set.
+
+- **Precedence**: real `process.env` > Secrets Manager > SSM. A key already present in `process.env` at load time is never fetched or overwritten (a documented local-debugging escape hatch); only keys the loader itself set are refreshed.
+- **Fetch**: `GetParametersCommand` with `WithDecryption: true`, batched in groups of 10 (the GetParameters max). Parameter name for key `K` is `${SSM_PARAMETER_PREFIX}/${K}`.
+- **TTL cache**: successful loads cache for `FRIGG_SSM_CACHE_TTL` seconds (default 300; `0` = forever). Concurrent callers share one in-flight promise. A failed initial load is never cached, so the next invocation retries; a failed TTL *refresh* keeps serving the stale values (warn + 30s backoff) instead of erroring a warm container. `ThrottlingException` is retried with short exponential backoff.
+- **Fail-fast**: throws listing every missing parameter name (and the prefix) if a required key is absent from SSM. Keys already satisfied by real `process.env` never trigger a failure.
+- **Security**: logs parameter names and versions only, never values.
+
 ## Database Connection Patterns
 
 ### Connection Pooling Strategy

package/core/create-handler.js

@@ -4,6 +4,7 @@
 
 const { initDebugLog, flushDebugLog } = require('../logs');
 const { secretsToEnv } = require('./secrets-to-env');
+const { parametersToEnv } = require('./parameters-to-env');
 
 // Best-effort extraction of correlation identifiers from a Lambda event.
 // For SQS: pulls messageIds + parsed event/processId/integrationId from each
@@ -80,6 +81,9 @@ const createHandler = (optionByName = {}) => {
             // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
             await secretsToEnv();
 
+            // If enabled (i.e. if SSM_PARAMETER_PREFIX and FRIGG_SSM_OFFLOADED_KEYS are set) fetch offloaded params from SSM Parameter Store into process.env.
+            await parametersToEnv();
+
             // Lazy-required so DB-free handlers never load the Prisma client.
             if (shouldUseDatabase) {
                 const { connectPrisma } = require('../database/prisma');

package/core/parameters-to-env.js

@@ -0,0 +1,170 @@
+// Runtime loader that hydrates process.env from SSM Parameter Store. Used to
+// offload env vars that would otherwise blow past Lambda's 4KB env limit.
+// Real process.env always wins over SSM (a documented local-debugging escape
+// hatch); only keys this loader sets are ever refreshed.
+
+const DEFAULT_CACHE_TTL_SECONDS = 300;
+const BATCH_SIZE = 10;
+const THROTTLE_BACKOFF_MS = [100, 200, 400];
+const REFRESH_RETRY_MS = 30_000;
+
+let client = null;
+let cacheExpiresAt = null;
+let inflight = null;
+const ownedKeys = new Set();
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const chunk = (items, size) => {
+    const batches = [];
+    for (let i = 0; i < items.length; i += size) {
+        batches.push(items.slice(i, i + size));
+    }
+    return batches;
+};
+
+const getCacheTtlSeconds = () => {
+    const raw = process.env.FRIGG_SSM_CACHE_TTL;
+    if (raw === undefined || raw === '') {
+        return DEFAULT_CACHE_TTL_SECONDS;
+    }
+    const parsed = Number(raw);
+    return Number.isNaN(parsed) ? DEFAULT_CACHE_TTL_SECONDS : parsed;
+};
+
+const parseKeys = (raw) =>
+    raw
+        .split(',')
+        .map((key) => key.trim())
+        .filter(Boolean);
+
+const sendWithRetry = async (command) => {
+    let attempt = 0;
+    for (;;) {
+        try {
+            return await client.send(command);
+        } catch (err) {
+            if (
+                err.name === 'ThrottlingException' &&
+                attempt < THROTTLE_BACKOFF_MS.length
+            ) {
+                await sleep(THROTTLE_BACKOFF_MS[attempt]);
+                attempt += 1;
+                continue;
+            }
+            throw err;
+        }
+    }
+};
+
+const loadParameters = async (prefix, keys) => {
+    const { SSMClient, GetParametersCommand } = require('@aws-sdk/client-ssm');
+    if (!client) {
+        client = new SSMClient({ region: process.env.AWS_REGION });
+    }
+
+    // A key already living in process.env wins over SSM, except keys we set
+    // ourselves — those we refresh so later invocations pick up rotations.
+    const keysToFetch = keys.filter(
+        (key) => ownedKeys.has(key) || process.env[key] === undefined
+    );
+    const nameFor = (key) => `${prefix}/${key}`;
+
+    // A refresh means every key already has a served value; a warm container
+    // must keep serving stale values through an SSM blip instead of erroring.
+    const isRefresh =
+        keysToFetch.length > 0 &&
+        keysToFetch.every((key) => ownedKeys.has(key));
+
+    const found = new Map();
+    try {
+        for (const batch of chunk(keysToFetch, BATCH_SIZE)) {
+            const { Parameters = [] } = await sendWithRetry(
+                new GetParametersCommand({
+                    Names: batch.map(nameFor),
+                    WithDecryption: true,
+                })
+            );
+            for (const param of Parameters) {
+                found.set(param.Name, param);
+            }
+        }
+
+        const missing = keysToFetch
+            .map(nameFor)
+            .filter((name) => !found.has(name));
+        if (missing.length > 0) {
+            throw new Error(
+                `parametersToEnv: missing SSM parameters under ${prefix}: ${missing.join(
+                    ', '
+                )}`
+            );
+        }
+    } catch (err) {
+        if (!isRefresh) {
+            throw err;
+        }
+        console.warn(
+            `parametersToEnv: refresh failed, keeping cached values: ${err.message}`
+        );
+        cacheExpiresAt = Date.now() + REFRESH_RETRY_MS;
+        return;
+    }
+
+    const loaded = keysToFetch.map((key) => {
+        const param = found.get(nameFor(key));
+        process.env[key] = param.Value;
+        ownedKeys.add(key);
+        return `${param.Name} (v${param.Version})`;
+    });
+
+    const ttlSeconds = getCacheTtlSeconds();
+    cacheExpiresAt =
+        ttlSeconds === 0 ? Infinity : Date.now() + ttlSeconds * 1000;
+
+    if (loaded.length > 0) {
+        console.log('parametersToEnv: loaded', loaded);
+    }
+};
+
+/**
+ * Hydrate process.env from SSM Parameter Store.
+ *
+ * No-op unless both SSM_PARAMETER_PREFIX and FRIGG_SSM_OFFLOADED_KEYS are set.
+ * Results are cached for FRIGG_SSM_CACHE_TTL seconds (default 300; 0 = forever).
+ * A failed fetch is never cached, so the next invocation retries.
+ */
+const parametersToEnv = async () => {
+    const prefix = process.env.SSM_PARAMETER_PREFIX;
+    const rawKeys = process.env.FRIGG_SSM_OFFLOADED_KEYS;
+    if (!prefix || !rawKeys) {
+        return;
+    }
+    const keys = parseKeys(rawKeys);
+    if (keys.length === 0) {
+        return;
+    }
+
+    if (cacheExpiresAt !== null && Date.now() < cacheExpiresAt) {
+        return;
+    }
+
+    if (!inflight) {
+        inflight = loadParameters(prefix, keys).finally(() => {
+            inflight = null;
+        });
+    }
+    return inflight;
+};
+
+const _resetCache = () => {
+    client = null;
+    cacheExpiresAt = null;
+    inflight = null;
+    ownedKeys.clear();
+};
+
+module.exports = {
+    parametersToEnv,
+    _resetCache,
+};

package/integrations/EXTENSIONS.md

@@ -1,6 +1,6 @@
 # Integration Extensions Quick Start
 
-Tier 3 **Integration Extensions** let an API module ship reusable handler bundles — receiver routes, event handlers, queues, workers — that an integration consumes declaratively via `Definition.extensions`. See [ADR-EXTENSIONS](../../../docs/architecture/ADR-EXTENSIONS.md) for the full taxonomy.
+Tier 3 **Integration Extensions** let an API module ship reusable handler bundles — receiver routes, event handlers, queues, workers — that an integration consumes declaratively via `Definition.extensions`. See [ADR-015: Extensions Taxonomy](../../../docs/architecture-decisions/015-extensions-taxonomy.md) for the full taxonomy.
 
 ## When to use this vs `Definition.webhooks: true`
 
@@ -235,6 +235,6 @@ This keeps core platform-neutral and reusable while keeping the api-module code
 
 ## See also
 
-- [ADR-EXTENSIONS](../../../docs/architecture/ADR-EXTENSIONS.md) — the three-tier taxonomy (Core Plugins / Application Extensions / Integration Extensions)
+- [ADR-015: Extensions Taxonomy](../../../docs/architecture-decisions/015-extensions-taxonomy.md) — the three-tier taxonomy (Core Plugins / Application Extensions / Integration Extensions)
 - [WEBHOOK-QUICKSTART](./WEBHOOK-QUICKSTART.md) — per-account `Definition.webhooks: true` pattern
 - `extension.js` — the validation + flattening helpers (`validateExtensionBinding`, `getExtensionRoutes`, `getExtensionWorkers`)

package/package.json

@@ -1,12 +1,13 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.623.b39b42d.0",
+    "version": "2.0.0--canary.625.950ba82.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
         "@aws-sdk/client-lambda": "^3.714.0",
         "@aws-sdk/client-sqs": "^3.588.0",
+        "@aws-sdk/client-ssm": "^3.588.0",
         "@hapi/boom": "^10.0.1",
         "bcryptjs": "^2.4.3",
         "body-parser": "^1.20.5",
@@ -38,9 +39,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.623.b39b42d.0",
-        "@friggframework/prettier-config": "2.0.0--canary.623.b39b42d.0",
-        "@friggframework/test": "2.0.0--canary.623.b39b42d.0",
+        "@friggframework/eslint-config": "2.0.0--canary.625.950ba82.0",
+        "@friggframework/prettier-config": "2.0.0--canary.625.950ba82.0",
+        "@friggframework/test": "2.0.0--canary.625.950ba82.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -80,5 +81,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "b39b42dc96ec3dfe4963a63b27468cd1b9c107c6"
+    "gitHead": "950ba828b2885a01768dbfbee5a1fd531efb89ab"
 }