@friggframework/core 2.0.0--canary.686.87e9875.0 → 2.0.0--canary.686.00d79d8.0

package/CLAUDE.md

@@ -775,6 +775,9 @@ Use test doubles from `@friggframework/test` package for consistent mocking.
 - `SECRET_ARN` - AWS Secrets Manager ARN for auto-injection
 - `FRIGG_LOG_LEVEL` - Minimum log level (`TRACE` … `FATAL`, default `INFO`; `DEBUG` on local runs)
 - `FRIGG_QUEUE_MAX_RECEIVE_COUNT` - Set by devtools on integration queue workers whose queue the stack owns; feeds `delivery.maxReceiveCount`
+- `FRIGG_QUEUE_SIGNING_SECRET` - Required for HTTP-delivered queues (Netlify Background Functions). `NetlifyBackgroundProvider` signs each message (HMAC-SHA256 over `timestamp.rawBody`, `x-frigg-queue-signature` / `x-frigg-queue-timestamp`) and `verifyEvent()` refuses anything unsigned, tampered, signed with another secret or older than 5 minutes. Unset → `send()` throws and every event is refused (`queues/queue-message-auth.js`)
+- `FRIGG_QUEUE_ALLOW_UNSIGNED` - `true` accepts unsigned queue messages when no secret is set, outside production only (`STAGE` dev/test/local, `NODE_ENV` development/test, or `NETLIFY_DEV`); ignored in production
+- `QSTASH_CURRENT_SIGNING_KEY` / `QSTASH_NEXT_SIGNING_KEY` - Required with the QStash queue: `QStashQueueProvider.verifyEvent()` checks the `Upstash-Signature` JWT with them
 
 ## Version Information
 

package/application/commands/scheduler-commands.js

@@ -121,17 +121,19 @@ function createSchedulerCommands({ integrationName, schedulerService }) {
                     throw error;
                 }
 
-                if (!queueUrl) {
+                // An adapter with its own notion of a queue target (Netlify:
+                // the worker function) resolves it; otherwise the target is
+                // an SQS queue and its URL is required.
+                const service = getSchedulerService();
+                const resolvesOwnTarget =
+                    typeof service?.toQueueResourceId === 'function';
+
+                if (!queueUrl && !resolvesOwnTarget) {
                     const error = new Error('queueUrl is required');
                     error.code = 'INVALID_JOB_DATA';
                     throw error;
                 }
 
-                // Derive ARN from URL (business logic - transformation)
-                const queueArn = deriveArnFromQueueUrl(queueUrl);
-
-                // Get scheduler service (via DI or factory)
-                const service = getSchedulerService();
                 if (!service) {
                     console.warn(
                         `[${integrationName}] Scheduler not configured, skipping job schedule`
@@ -157,7 +159,9 @@ function createSchedulerCommands({ integrationName, schedulerService }) {
                 const result = await service.scheduleOneTime({
                     scheduleName: jobId,
                     scheduleAt: scheduledAt,
-                    queueResourceId: queueArn,
+                    queueResourceId: resolvesOwnTarget
+                        ? service.toQueueResourceId(queueUrl)
+                        : deriveArnFromQueueUrl(queueUrl),
                     payload: sqsPayload,
                 });
 

package/core/create-handler.js

@@ -81,6 +81,15 @@ const createHandler = (optionByName = {}) => {
                     if (shouldUseDatabase) {
                         const { connectPrisma } = require('../database/prisma');
                         await connectPrisma();
+
+                        // Extension bootstraps (e.g. db-credentials swapping a
+                        // module's env for its DB loader) run once per
+                        // process, after the connect and before any request
+                        // builds a module. AWS and Netlify both reach here.
+                        const {
+                            initializeApp,
+                        } = require('../extensions/initialize-app');
+                        await initializeApp();
                     }
 
                     // Helps reuse the database connection.  Lowers response times.

package/infrastructure/scheduler/netlify-scheduler-adapter.js

@@ -24,6 +24,11 @@
 
 const { SchedulerServiceInterface } = require('./scheduler-service-interface');
 
+// The one queue worker every Netlify deployment has (provider-netlify's
+// worker-background function); it dispatches by integrationName.
+const DEFAULT_WORKER_PATH = '/.netlify/functions/worker-background';
+const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+
 class NetlifySchedulerAdapter extends SchedulerServiceInterface {
     /**
      * @param {Object} options
@@ -31,11 +36,15 @@ class NetlifySchedulerAdapter extends SchedulerServiceInterface {
      *   Must implement: save(schedule), delete(scheduleName),
      *   findByName(scheduleName), findDue(now)
      * @param {Object} [options.queueProvider] - Queue provider for dispatching due jobs
+     * @param {number} [options.leaseMs] - how long a claimed (PROCESSING) job
+     *   is held before another tick may take it again (default 5 minutes,
+     *   well past a Netlify scheduled function's 60-second limit)
      */
     constructor(options = {}) {
         super();
         this.repository = options.repository;
         this.queueProvider = options.queueProvider;
+        this.leaseMs = options.leaseMs ?? DEFAULT_LEASE_MS;
 
         if (!this.repository) {
             console.warn(
@@ -47,6 +56,20 @@ class NetlifySchedulerAdapter extends SchedulerServiceInterface {
         }
     }
 
+    /**
+     * Where a due job is sent. Netlify has no per-integration queues, so an
+     * SQS-style queue URL (often unset here) maps to the worker function;
+     * a function path is kept as given.
+     *
+     * @param {string} [queueUrl]
+     * @returns {string} a path NetlifyBackgroundProvider.send() accepts
+     */
+    toQueueResourceId(queueUrl) {
+        return typeof queueUrl === 'string' && queueUrl.startsWith('/')
+            ? queueUrl
+            : DEFAULT_WORKER_PATH;
+    }
+
     async scheduleOneTime({
         scheduleName,
         scheduleAt,
@@ -129,23 +152,31 @@ class NetlifySchedulerAdapter extends SchedulerServiceInterface {
             console.warn(
                 '[NetlifyScheduler] Cannot process due schedules without a repository'
             );
-            return { processed: 0, errors: 0 };
+            return { processed: 0, errors: 0, skipped: 0 };
         }
 
         const now = new Date();
-        const dueSchedules = await this.repository.findDue(now);
+        const lease = { leaseMs: this.leaseMs };
+        const dueSchedules = await this.repository.findDue(now, lease);
 
         let processed = 0;
         let errors = 0;
+        let skipped = 0;
 
         for (const schedule of dueSchedules) {
             try {
-                // Mark as PROCESSING before dispatch so the next cron tick
-                // won't re-pick this schedule (findDue only returns PENDING).
-                await this.repository.save({
-                    ...schedule,
-                    state: 'PROCESSING',
-                });
+                // Claim before dispatch. Two overlapping ticks can both see
+                // the row in findDue; only the one whose conditional update
+                // wins sends it. A repository without claim() (a custom one)
+                // keeps the old unconditional PROCESSING write.
+                const claimed =
+                    typeof this.repository.claim === 'function'
+                        ? await this.repository.claim(schedule.scheduleName, now, lease)
+                        : (await this.repository.save({ ...schedule, state: 'PROCESSING' }), true);
+                if (!claimed) {
+                    skipped++;
+                    continue;
+                }
 
                 if (this.queueProvider) {
                     await this.queueProvider.send(
@@ -176,10 +207,10 @@ class NetlifySchedulerAdapter extends SchedulerServiceInterface {
         }
 
         console.log(
-            `[NetlifyScheduler] Processed ${processed} due schedules, ${errors} errors`
+            `[NetlifyScheduler] Processed ${processed} due schedules, ${errors} errors, ${skipped} claimed elsewhere`
         );
-        return { processed, errors };
+        return { processed, errors, skipped };
     }
 }
 
-module.exports = { NetlifySchedulerAdapter };
+module.exports = { NetlifySchedulerAdapter, DEFAULT_WORKER_PATH, DEFAULT_LEASE_MS };

package/infrastructure/scheduler/scheduled-job-repository.js

@@ -0,0 +1,118 @@
+/**
+ * Scheduled Job Repository
+ *
+ * Prisma-based implementation of the repository interface required by
+ * NetlifySchedulerAdapter. Persists one-time scheduled jobs to the
+ * ScheduledJob model so they survive function restarts.
+ *
+ * Repository interface:
+ *   save(scheduleData)        — Upsert a scheduled job
+ *   delete(scheduleName)      — Remove a scheduled job
+ *   findByName(scheduleName)  — Find a single scheduled job
+ *   findDue(now, { leaseMs }) — Find due jobs: PENDING, or PROCESSING with an
+ *                               expired lease (a dispatcher that died after
+ *                               claiming), where scheduledAt <= now
+ *   claim(scheduleName, now, { leaseMs })
+ *                             — Atomically move one due job to PROCESSING;
+ *                               true only for the one caller that won it
+ *
+ * The lease clock is the row's updatedAt: a claim writes it, so a PROCESSING
+ * row whose updatedAt is older than now - leaseMs is claimable again.
+ */
+
+const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+
+// Rows a dispatcher may take: never claimed, or claimed by one that has not
+// finished within the lease.
+function claimableWhere(now, leaseMs = DEFAULT_LEASE_MS) {
+    return {
+        OR: [
+            { state: 'PENDING' },
+            {
+                state: 'PROCESSING',
+                updatedAt: { lt: new Date(now.getTime() - leaseMs) },
+            },
+        ],
+    };
+}
+
+class ScheduledJobRepository {
+    /**
+     * @param {Object} options
+     * @param {import('@prisma/client').PrismaClient} options.prismaClient
+     */
+    constructor({ prismaClient }) {
+        if (!prismaClient) {
+            throw new Error(
+                'ScheduledJobRepository requires a prismaClient instance'
+            );
+        }
+        this.prisma = prismaClient;
+    }
+
+    async save(scheduleData) {
+        return this.prisma.scheduledJob.upsert({
+            where: { scheduleName: scheduleData.scheduleName },
+            update: {
+                scheduledAt: new Date(scheduleData.scheduledAt),
+                queueResourceId: scheduleData.queueResourceId,
+                payload: scheduleData.payload ?? undefined,
+                state: scheduleData.state || 'PENDING',
+            },
+            create: {
+                scheduleName: scheduleData.scheduleName,
+                scheduledAt: new Date(scheduleData.scheduledAt),
+                queueResourceId: scheduleData.queueResourceId,
+                payload: scheduleData.payload ?? undefined,
+                state: scheduleData.state || 'PENDING',
+            },
+        });
+    }
+
+    async delete(scheduleName) {
+        try {
+            await this.prisma.scheduledJob.delete({
+                where: { scheduleName },
+            });
+        } catch (error) {
+            // P2025 = record not found — safe to ignore on delete
+            if (error.code !== 'P2025') {
+                throw error;
+            }
+        }
+    }
+
+    async findByName(scheduleName) {
+        return this.prisma.scheduledJob.findUnique({
+            where: { scheduleName },
+        });
+    }
+
+    async findDue(now, { leaseMs = DEFAULT_LEASE_MS } = {}) {
+        return this.prisma.scheduledJob.findMany({
+            where: {
+                scheduledAt: { lte: now },
+                ...claimableWhere(now, leaseMs),
+            },
+            orderBy: { scheduledAt: 'asc' },
+        });
+    }
+
+    /**
+     * Conditional update: only a row that is still claimable moves to
+     * PROCESSING, so of two overlapping ticks exactly one gets count === 1.
+     * (PostgreSQL re-checks the WHERE on the row it locked; MongoDB updates
+     * each document atomically.)
+     *
+     * @returns {Promise<boolean>} true when this caller claimed the job
+     */
+    async claim(scheduleName, now, { leaseMs = DEFAULT_LEASE_MS } = {}) {
+        const { count } = await this.prisma.scheduledJob.updateMany({
+            where: { scheduleName, ...claimableWhere(now, leaseMs) },
+            data: { state: 'PROCESSING', updatedAt: now },
+        });
+        return count === 1;
+    }
+}
+
+module.exports = { ScheduledJobRepository, DEFAULT_LEASE_MS };

package/infrastructure/scheduler/scheduler-service-factory.js

@@ -9,6 +9,8 @@
  * - SCHEDULER_PROVIDER=mock -> Use in-memory mock scheduler
  * - SCHEDULER_PROVIDER=netlify -> Netlify poll-and-dispatch scheduler
  *   (friggframework/frigg#545; needs `repository`, usually `queueProvider`)
+ * - Default on Netlify (NETLIFY=true, set by the Netlify runtime and build;
+ *   provider-netlify's generated functions also set SCHEDULER_PROVIDER) -> Netlify
  * - Default in dev/test/local stages -> Mock scheduler
  * - Default in other stages -> EventBridge scheduler
  * - Any other name -> require('@friggframework/provider-<name>').SchedulerAdapter
@@ -36,6 +38,12 @@ function determineProvider() {
         return explicitProvider;
     }
 
+    // Checked before the stage: a Netlify site with no STAGE (or STAGE=dev)
+    // must still persist schedules where scheduled-sync reads them.
+    if (process.env.NETLIFY === 'true') {
+        return SCHEDULER_PROVIDERS.NETLIFY;
+    }
+
     const stage = process.env.STAGE || 'dev';
     if (LOCAL_STAGES.includes(stage)) {
         return SCHEDULER_PROVIDERS.MOCK;
@@ -44,6 +52,13 @@ function determineProvider() {
     return SCHEDULER_PROVIDERS.EVENTBRIDGE;
 }
 
+function createDefaultScheduledJobRepository() {
+    const { ScheduledJobRepository } = require('./scheduled-job-repository');
+    // The prisma export is a lazy proxy: nothing connects until a query runs.
+    const { prisma } = require('../../database/prisma');
+    return new ScheduledJobRepository({ prismaClient: prisma });
+}
+
 /**
  * Create a scheduler service instance
  *
@@ -74,7 +89,11 @@ function createSchedulerService(options = {}) {
         case SCHEDULER_PROVIDERS.NETLIFY: {
             const { NetlifySchedulerAdapter } = require('./netlify-scheduler-adapter');
             return new NetlifySchedulerAdapter({
-                repository: options.repository,
+                // Default: the Prisma ScheduledJob rows that the Netlify
+                // scheduled-sync function polls. Without it the adapter
+                // falls back to memory, and a schedule made in one function
+                // is never seen by the cron.
+                repository: options.repository || createDefaultScheduledJobRepository(),
                 queueProvider: options.queueProvider,
             });
         }

package/modules/module.js

@@ -21,9 +21,17 @@ class Module extends Delegate {
      * @param {string} params.userId The user id
      * @param {Object} params.entity The entity record from the database
      * @param {string} [params.state] Optional OAuth state value forwarded to the API client (round-trips through the OAuth provider).
-     * @param {Object} [params.resolvedEnv] definition.env already resolved by Module.create(); defaults to the static definition.env.
+     * @param {Object} [params.resolvedEnv] definition.env as Module.create() resolved it (may be undefined).
+     * @param {boolean} [params.envResolved=false] true when resolvedEnv carries the resolved env, even an undefined one; otherwise the static definition.env is used.
      */
-    constructor({ definition, userId = null, entity: entityObj = null, state = null, resolvedEnv = null }) {
+    constructor({
+        definition,
+        userId = null,
+        entity: entityObj = null,
+        state = null,
+        resolvedEnv,
+        envResolved = false,
+    }) {
         super({ definition, userId, entity: entityObj });
 
         this.validateDefinition(definition);
@@ -58,7 +66,17 @@ class Module extends Delegate {
         // A pre-resolved env (Module.create()) supports definition.env as an
         // async function, e.g. OAuth app credentials loaded from the database
         // by the db-credentials extension; otherwise the static object.
-        const envValues = resolvedEnv !== null ? resolvedEnv : this.definition.env;
+        // "Resolved" is an explicit flag, not a non-null value: a function env
+        // may legitimately resolve to undefined (no static env, no DB row),
+        // and falling back to definition.env would then read the function.
+        const envValues = envResolved ? resolvedEnv : this.definition.env;
+        if (typeof envValues === 'function') {
+            // Spreading a function yields no keys, so the API client would
+            // silently get no client_id / client_secret.
+            throw new TypeError(
+                `Module ${this.name}: definition.env is a function; build the module with await Module.create(...)`
+            );
+        }
 
         const apiParams = {
             ...envValues,
@@ -97,7 +115,7 @@ class Module extends Delegate {
      */
     static async create({ definition, userId = null, entity = null, state = null }) {
         const resolvedEnv = await Module.resolveEnv(definition);
-        return new Module({ definition, userId, entity, state, resolvedEnv });
+        return new Module({ definition, userId, entity, state, resolvedEnv, envResolved: true });
     }
 
     getName() {

package/modules/use-cases/create-entity-from-credential.js

@@ -36,7 +36,7 @@ class CreateEntityFromCredential {
         this.processAuthorizationCallback = processAuthorizationCallback;
         this.credentialRepository = credentialRepository;
         this.moduleDefinitions = moduleDefinitions || [];
-        this.createModule = createModule || ((params) => new Module(params));
+        this.createModule = createModule || ((params) => Module.create(params));
     }
 
     /**
@@ -78,7 +78,7 @@ class CreateEntityFromCredential {
         // API can call the provider and a token refresh during
         // getEntityDetails updates the owner's credential.
         const { id, userId, externalId, authIsValid, ...data } = credential;
-        const module = this.createModule({
+        const module = await this.createModule({
             userId: ownership.ownerId,
             definition,
             entity: {

package/modules/use-cases/get-authorization-requirements.js

@@ -3,7 +3,7 @@ const { findDefinition, getAuthStepCount } = require('./entity-types');
 
 const defaultCreateModule = (params) => {
     const { Module } = require('../module');
-    return new Module(params);
+    return Module.create(params);
 };
 
 /**
@@ -80,7 +80,7 @@ class GetAuthorizationRequirements {
         if (typeof definition.getAuthRequirementsForStep === 'function') {
             raw = await definition.getAuthRequirementsForStep(step);
         } else {
-            const module = this.createModule({
+            const module = await this.createModule({
                 userId,
                 definition,
                 ...(state ? { state } : {}),

package/modules/use-cases/get-entities-for-user.js

@@ -27,16 +27,18 @@ class GetEntitiesForUser {
             describeRecord(entity, ctx, 'entity')
         );
 
-        return entities.map((entity) => {
-            const definition = this.definitionMap.get(entity.moduleName);
+        return Promise.all(
+            entities.map(async (entity) => {
+                const definition = this.definitionMap.get(entity.moduleName);
 
-            const moduleInstance = new Module({
-                userId: entity.userId,
-                definition: definition,
-                entity: entity,
-            });
-            return mapModuleClassToModuleDTO(moduleInstance);
-        });
+                const moduleInstance = await Module.create({
+                    userId: entity.userId,
+                    definition: definition,
+                    entity: entity,
+                });
+                return mapModuleClassToModuleDTO(moduleInstance);
+            })
+        );
     }
 }
 

package/modules/use-cases/get-entity-module-for-user.js

@@ -20,7 +20,7 @@ function userOwns(user, ownerId) {
 
 const defaultCreateModule = (params) => {
     const { Module } = require('../module');
-    return new Module(params);
+    return Module.create(params);
 };
 
 /**
@@ -62,7 +62,7 @@ class GetEntityModuleForUser {
                 { code: 'ENTITY_TYPE_NOT_FOUND' }
             );
         }
-        const module = this.createModule({
+        const module = await this.createModule({
             userId: entity.userId,
             entity,
             definition,

package/modules/use-cases/get-entity-options-by-id.js

@@ -63,7 +63,7 @@ class GetEntityOptionsById {
         // Built for the entity's OWNER, not the caller: a caller may use an
         // organization's entity, and a token refresh during this call must
         // update the owner's credential, not create one under the caller.
-        const module = new Module({
+        const module = await Module.create({
             userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,

package/modules/use-cases/get-entity-options-by-type.js

@@ -21,7 +21,7 @@ class GetEntityOptionsByType {
         if (!moduleDefinition) {
             throw new Error(`Module definition not found for type: ${type}`);
         }
-        const moduleInstance = new Module({
+        const moduleInstance = await Module.create({
             userId,
             definition: moduleDefinition,
         });

package/modules/use-cases/get-module-instance-from-type.js

@@ -23,7 +23,7 @@ class GetModuleInstanceFromType {
         if (!moduleDefinition) {
             throw new Error(`Module definition not found for type: ${type}`);
         }
-        return new Module({
+        return Module.create({
             userId,
             definition: moduleDefinition,
             state: options.state,

package/modules/use-cases/get-module.js

@@ -59,7 +59,7 @@ class GetModule {
         // Built for the entity's OWNER, not the caller: a caller may use an
         // organization's entity, and a token refresh during this call must
         // update the owner's credential, not create one under the caller.
-        const module = new Module({
+        const module = await Module.create({
             userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,

package/modules/use-cases/multi-step-authorization.js

@@ -10,7 +10,7 @@ const log = getLogger('frigg.api.authorize');
 
 const defaultCreateModule = (params) => {
     const { Module } = require('../module');
-    return new Module(params);
+    return Module.create(params);
 };
 
 const isMultiStep = (definition) =>
@@ -225,7 +225,7 @@ class SubmitAuthorizationStep {
             );
         }
 
-        const module = this.createModule({ userId: ownership.ownerId, definition });
+        const module = await this.createModule({ userId: ownership.ownerId, definition });
         let result;
         try {
             result = await definition.processAuthorizationStep(

package/modules/use-cases/process-authorization-callback.js

@@ -88,7 +88,7 @@ class ProcessAuthorizationCallback {
             });
         }
 
-        const module = new Module({
+        const module = await Module.create({
             userId,
             entity: existingEntity,
             definition: moduleDefinition,

package/modules/use-cases/refresh-entity-options.js

@@ -64,7 +64,7 @@ class RefreshEntityOptions {
         // Built for the entity's OWNER, not the caller: a caller may use an
         // organization's entity, and a token refresh during this call must
         // update the owner's credential, not create one under the caller.
-        const module = new Module({
+        const module = await Module.create({
             userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,

package/modules/use-cases/test-module-auth.js

@@ -63,7 +63,7 @@ class TestModuleAuth {
         // Built for the entity's OWNER, not the caller: a caller may use an
         // organization's entity, and a token refresh during this call must
         // update the owner's credential, not create one under the caller.
-        const module = new Module({
+        const module = await Module.create({
             userId: entity.userId ?? userId,
             entity,
             definition: moduleDefinition,

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.686.87e9875.0",
+    "version": "2.0.0--canary.686.00d79d8.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -48,9 +48,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.686.87e9875.0",
-        "@friggframework/prettier-config": "2.0.0--canary.686.87e9875.0",
-        "@friggframework/test": "2.0.0--canary.686.87e9875.0",
+        "@friggframework/eslint-config": "2.0.0--canary.686.00d79d8.0",
+        "@friggframework/prettier-config": "2.0.0--canary.686.00d79d8.0",
+        "@friggframework/test": "2.0.0--canary.686.00d79d8.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -90,5 +90,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "87e9875d4dba36bf3bb90400e862d5fb9db17ae1"
+    "gitHead": "00d79d89a9657b62bf89544cbfdf3338e84aea0c"
 }

package/queues/providers/netlify-background-provider.js

@@ -8,6 +8,14 @@
  * Queue ID format: The function name or URL path for the background function.
  * Convention: function files named with '-background' suffix (e.g., 'worker-background.js')
  *
+ * Authentication: a background function is a public URL and Netlify does
+ * not authenticate its caller, so every message is signed with
+ * FRIGG_QUEUE_SIGNING_SECRET (HMAC-SHA256 over timestamp + raw body, see
+ * ../queue-message-auth.js) and verifyEvent() checks that signature before
+ * the worker parses or dispatches anything. Without the secret, send() and
+ * verifyEvent() refuse, except outside production with
+ * FRIGG_QUEUE_ALLOW_UNSIGNED=true.
+ *
  * Limitations:
  * - No built-in retry (must implement manually)
  * - No dead-letter queue
@@ -15,12 +23,42 @@
  * - 15-minute max execution time
  */
 const { QueueProvider } = require('../queue-provider');
+const {
+    SIGNING_SECRET_ENV,
+    ALLOW_UNSIGNED_ENV,
+    SIGNATURE_HEADER,
+    TIMESTAMP_HEADER,
+    allowsUnsignedMessages,
+    readSigningSecret,
+    signQueueMessage,
+    verifyQueueMessage,
+    readHeader,
+    readRawBody,
+} = require('../queue-message-auth');
 
 class NetlifyBackgroundProvider extends QueueProvider {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.baseUrl] - site URL (default process.env.URL)
+     * @param {string} [options.signingSecret] - default FRIGG_QUEUE_SIGNING_SECRET, read per call
+     * @param {Object} [options.env] - environment to read (default process.env)
+     * @param {() => number} [options.now] - clock in milliseconds (tests)
+     */
     constructor(options = {}) {
         super();
         // Base URL for triggering background functions (e.g., https://mysite.netlify.app)
         this.baseUrl = options.baseUrl || process.env.URL || '';
+        this.signingSecret = options.signingSecret;
+        this.env = options.env || process.env;
+        this.now = options.now || Date.now;
+        // verifyEvent() proves an HTTP delivery came from Frigg.
+        this.verifiesHttpDelivery = true;
+    }
+
+    // Read on every call, not in the constructor: secrets may be loaded into
+    // the environment after the provider is built (loadSecrets).
+    _secret() {
+        return this.signingSecret || readSigningSecret(this.env);
     }
 
     /**
@@ -31,10 +69,25 @@ class NetlifyBackgroundProvider extends QueueProvider {
      */
     async send(message, queueId) {
         const url = `${this.baseUrl}${queueId}`;
+        const body = JSON.stringify(message);
+        const headers = { 'Content-Type': 'application/json' };
+
+        const secret = this._secret();
+        if (secret) {
+            Object.assign(headers, signQueueMessage({ body, secret, now: this.now() }));
+        } else if (!allowsUnsignedMessages(this.env)) {
+            // The worker would refuse the message, and a background function
+            // answers 202 either way, so the loss would be silent. Fail here.
+            throw new Error(
+                `${SIGNING_SECRET_ENV} is required to send to a Netlify background function ` +
+                    `(${ALLOW_UNSIGNED_ENV}=true allows unsigned messages outside production only)`
+            );
+        }
+
         const response = await fetch(url, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(message),
+            headers,
+            body,
         });
 
         if (!response.ok && response.status !== 202) {
@@ -49,7 +102,8 @@ class NetlifyBackgroundProvider extends QueueProvider {
     /**
      * Send batch of messages sequentially (background functions are HTTP-triggered).
      */
-    async batchSend(entries = [], queueId) {
+    async batchSend(batch, queueId) {
+        const entries = batch ?? [];
         const results = [];
         for (const entry of entries) {
             const result = await this.send(entry, queueId);
@@ -58,15 +112,35 @@ class NetlifyBackgroundProvider extends QueueProvider {
         return { results };
     }
 
+    /**
+     * Check the Frigg signature on an incoming background-function event.
+     *
+     * @param {Object} event - Netlify v1 (Lambda-shaped) event
+     * @returns {Promise<{ ok: boolean, reason?: string, unsigned?: boolean }>}
+     */
+    async verifyEvent(event) {
+        const secret = this._secret();
+        if (!secret) {
+            return allowsUnsignedMessages(this.env)
+                ? { ok: true, unsigned: true }
+                : { ok: false, reason: 'signing_secret_not_configured' };
+        }
+        return verifyQueueMessage({
+            body: readRawBody(event),
+            timestamp: readHeader(event, TIMESTAMP_HEADER),
+            signature: readHeader(event, SIGNATURE_HEADER),
+            secret,
+            now: this.now(),
+        });
+    }
+
     /**
      * Parse Netlify Background Function event.
      * Background functions receive the raw HTTP event body as the event.
      */
     parseEvent(event) {
-        const body =
-            typeof event.body === 'string'
-                ? JSON.parse(event.body)
-                : event.body;
+        const raw = readRawBody(event);
+        const body = raw !== null ? JSON.parse(raw) : event.body;
 
         // Background functions receive a single message per invocation
         return [body];

package/queues/providers/qstash-queue-provider.js

@@ -16,8 +16,24 @@
  * - QSTASH_CURRENT_SIGNING_KEY and QSTASH_NEXT_SIGNING_KEY for verification
  *
  * Queue ID format: The destination URL that QStash will POST to when delivering the message.
+ *
+ * Verification (verifyEvent), per Upstash's documented scheme and its
+ * @upstash/qstash Receiver: every delivery carries an `Upstash-Signature`
+ * header, a JWT signed HS256 with the current signing key (the next key
+ * during rotation). Its claims are iss "Upstash", sub the destination URL,
+ * exp / nbf / iat, and body = base64url(SHA-256(raw body)). A delivery is
+ * accepted when the JWT verifies with either key, has not expired, and its
+ * body claim matches the body received (trailing '=' padding ignored, as the
+ * Receiver does). With neither key configured it is refused, except outside
+ * production with FRIGG_QUEUE_ALLOW_UNSIGNED=true.
  */
+const crypto = require('crypto');
 const { QueueProvider } = require('../queue-provider');
+const {
+    allowsUnsignedMessages,
+    readHeader,
+    readRawBody,
+} = require('../queue-message-auth');
 
 const QSTASH_API_BASE = 'https://qstash.upstash.io/v2';
 
@@ -28,6 +44,68 @@ class QStashQueueProvider extends QueueProvider {
             options.token || process.env.QSTASH_TOKEN;
         this.retries =
             options.retries !== undefined ? options.retries : 3;
+        this.currentSigningKey = options.currentSigningKey;
+        this.nextSigningKey = options.nextSigningKey;
+        // Optional: when set, the JWT's sub must equal this destination URL.
+        this.destinationUrl = options.destinationUrl;
+        this.env = options.env || process.env;
+        this.clockToleranceSeconds = options.clockToleranceSeconds || 0;
+        // verifyEvent() proves an HTTP delivery came from QStash.
+        this.verifiesHttpDelivery = true;
+    }
+
+    // Read per call: secrets may reach the environment after construction.
+    _signingKeys() {
+        return [
+            this.currentSigningKey || this.env.QSTASH_CURRENT_SIGNING_KEY,
+            this.nextSigningKey || this.env.QSTASH_NEXT_SIGNING_KEY,
+        ].filter((key) => typeof key === 'string' && key.length > 0);
+    }
+
+    /**
+     * Verify the Upstash-Signature JWT of a QStash delivery.
+     *
+     * @param {Object} event - Lambda-shaped HTTP event
+     * @returns {Promise<{ ok: boolean, reason?: string, unsigned?: boolean }>}
+     */
+    async verifyEvent(event) {
+        const keys = this._signingKeys();
+        if (keys.length === 0) {
+            return allowsUnsignedMessages(this.env)
+                ? { ok: true, unsigned: true }
+                : { ok: false, reason: 'signing_keys_not_configured' };
+        }
+        const token = readHeader(event, 'upstash-signature');
+        if (!token) return { ok: false, reason: 'missing_signature' };
+        const body = readRawBody(event);
+        if (body === null) return { ok: false, reason: 'missing_body' };
+
+        const jose = require('jose');
+        let payload;
+        for (const key of keys) {
+            try {
+                ({ payload } = await jose.jwtVerify(token, new TextEncoder().encode(key), {
+                    issuer: 'Upstash',
+                    algorithms: ['HS256'],
+                    requiredClaims: ['exp', 'body'],
+                    clockTolerance: this.clockToleranceSeconds,
+                }));
+                break;
+            } catch (_) {
+                // try the next key
+            }
+        }
+        if (!payload) return { ok: false, reason: 'invalid_signature' };
+
+        if (this.destinationUrl !== undefined && payload.sub !== this.destinationUrl) {
+            return { ok: false, reason: 'invalid_subject' };
+        }
+        const bodyHash = crypto.createHash('sha256').update(body, 'utf8').digest('base64url');
+        const claimed = typeof payload.body === 'string' ? payload.body.replace(/=+$/, '') : '';
+        if (claimed !== bodyHash.replace(/=+$/, '')) {
+            return { ok: false, reason: 'body_mismatch' };
+        }
+        return { ok: true };
     }
 
     /**
@@ -71,7 +149,8 @@ class QStashQueueProvider extends QueueProvider {
     /**
      * Send batch of messages via QStash batch API.
      */
-    async batchSend(entries = [], queueId) {
+    async batchSend(batch, queueId) {
+        const entries = batch ?? [];
         if (!this.token) {
             throw new Error(
                 'QSTASH_TOKEN is required. Get one at https://console.upstash.com'
@@ -109,10 +188,8 @@ class QStashQueueProvider extends QueueProvider {
      * QStash POSTs the message body directly to the destination URL.
      */
     parseEvent(event) {
-        const body =
-            typeof event.body === 'string'
-                ? JSON.parse(event.body)
-                : event.body;
+        const raw = readRawBody(event);
+        const body = raw !== null ? JSON.parse(raw) : event.body;
 
         // QStash delivers a single message per invocation
         return [body];

package/queues/providers/sqs-queue-provider.js

@@ -34,7 +34,8 @@ class SqsQueueProvider extends QueueProvider {
         });
     }
 
-    async batchSend(entries = [], queueUrl) {
+    async batchSend(batch, queueUrl) {
+        const entries = batch ?? [];
         let last = {};
         for (let i = 0; i < entries.length; i += SQS_BATCH_SIZE) {
             const Entries = entries.slice(i, i + SQS_BATCH_SIZE).map((entry) => ({
@@ -56,6 +57,14 @@ class SqsQueueProvider extends QueueProvider {
         const records = event?.Records || [];
         return records.map((record) => JSON.parse(record.body));
     }
+
+    /**
+     * SQS events reach a Lambda only through its event source mapping, which
+     * AWS authenticates; there is no public URL to post to.
+     */
+    async verifyEvent() {
+        return { ok: true };
+    }
 }
 
 module.exports = { SqsQueueProvider };

package/queues/queue-message-auth.js

@@ -0,0 +1,187 @@
+/**
+ * Queue message authentication for HTTP-delivered queues.
+ *
+ * An SQS-triggered Lambda is invoked by AWS itself, so its events are trusted
+ * by the transport. An HTTP-delivered queue (a Netlify Background Function,
+ * a QStash destination) is a public URL: anyone who can reach it can post a
+ * message. These helpers let the sending adapter prove a message came from
+ * Frigg and let the receiving adapter check that proof before anything runs.
+ *
+ * Scheme (Frigg-signed messages):
+ *   timestamp = whole seconds since the epoch, as a decimal string
+ *   signature = 'v1=' + hex(HMAC-SHA256(secret, `${timestamp}.${rawBody}`))
+ * sent as the `x-frigg-queue-timestamp` and `x-frigg-queue-signature`
+ * headers. The receiver recomputes the HMAC over the raw body it was given,
+ * compares in constant time, and refuses a timestamp more than
+ * MAX_MESSAGE_AGE_SECONDS away from its own clock (replay window).
+ *
+ * Fail closed: with no secret configured, a message is accepted unsigned only
+ * when FRIGG_QUEUE_ALLOW_UNSIGNED=true AND the environment is not production
+ * (isProductionEnvironment). Anything else is refused.
+ */
+const crypto = require('crypto');
+
+const SIGNING_SECRET_ENV = 'FRIGG_QUEUE_SIGNING_SECRET';
+const ALLOW_UNSIGNED_ENV = 'FRIGG_QUEUE_ALLOW_UNSIGNED';
+const SIGNATURE_HEADER = 'x-frigg-queue-signature';
+const TIMESTAMP_HEADER = 'x-frigg-queue-timestamp';
+const SIGNATURE_VERSION = 'v1';
+const MAX_MESSAGE_AGE_SECONDS = 5 * 60;
+
+// Stages core already treats as non-production (database/prisma.js bypasses
+// encryption for the same list).
+const NON_PRODUCTION_STAGES = ['dev', 'test', 'local'];
+const NON_PRODUCTION_NODE_ENVS = ['development', 'test'];
+
+/**
+ * Production unless the environment says otherwise: an unset STAGE and
+ * NODE_ENV count as production, so a missing setting never opens the door.
+ *
+ * @param {Object} [env=process.env]
+ * @returns {boolean}
+ */
+function isProductionEnvironment(env = process.env) {
+    if (NON_PRODUCTION_STAGES.includes(env.STAGE)) return false;
+    if (NON_PRODUCTION_NODE_ENVS.includes(env.NODE_ENV)) return false;
+    if (env.NETLIFY_DEV === 'true') return false;
+    return true;
+}
+
+/**
+ * Unsigned messages are allowed only by an explicit opt-in outside production.
+ *
+ * @param {Object} [env=process.env]
+ * @returns {boolean}
+ */
+function allowsUnsignedMessages(env = process.env) {
+    return env[ALLOW_UNSIGNED_ENV] === 'true' && !isProductionEnvironment(env);
+}
+
+/**
+ * @param {Object} [env=process.env]
+ * @returns {string|undefined} the configured signing secret, if non-empty
+ */
+function readSigningSecret(env = process.env) {
+    const secret = env[SIGNING_SECRET_ENV];
+    return typeof secret === 'string' && secret.length > 0 ? secret : undefined;
+}
+
+function computeSignature(secret, timestamp, rawBody) {
+    const mac = crypto
+        .createHmac('sha256', secret)
+        .update(`${timestamp}.${rawBody}`)
+        .digest('hex');
+    return `${SIGNATURE_VERSION}=${mac}`;
+}
+
+/**
+ * Sign a raw message body.
+ *
+ * @param {Object} params
+ * @param {string} params.body - the exact string that will be sent
+ * @param {string} params.secret
+ * @param {number} [params.now] - milliseconds since the epoch (default Date.now())
+ * @returns {{ [header: string]: string }} headers to add to the request
+ */
+function signQueueMessage({ body, secret, now = Date.now() }) {
+    if (!secret) {
+        throw new Error('A signing secret is required to sign a queue message');
+    }
+    const timestamp = String(Math.floor(now / 1000));
+    return {
+        [TIMESTAMP_HEADER]: timestamp,
+        [SIGNATURE_HEADER]: computeSignature(secret, timestamp, body),
+    };
+}
+
+function constantTimeEqual(a, b) {
+    const left = Buffer.from(a, 'utf8');
+    const right = Buffer.from(b, 'utf8');
+    // timingSafeEqual throws on unequal lengths; the length of a v1 signature
+    // is fixed, so comparing lengths first leaks nothing secret.
+    if (left.length !== right.length) return false;
+    return crypto.timingSafeEqual(left, right);
+}
+
+/**
+ * Verify a Frigg-signed message.
+ *
+ * @param {Object} params
+ * @param {string|null|undefined} params.body - raw body as received
+ * @param {string|undefined} params.timestamp - x-frigg-queue-timestamp
+ * @param {string|undefined} params.signature - x-frigg-queue-signature
+ * @param {string} params.secret
+ * @param {number} [params.now] - milliseconds since the epoch
+ * @param {number} [params.maxAgeSeconds]
+ * @returns {{ ok: true } | { ok: false, reason: string }}
+ */
+function verifyQueueMessage({
+    body,
+    timestamp,
+    signature,
+    secret,
+    now = Date.now(),
+    maxAgeSeconds = MAX_MESSAGE_AGE_SECONDS,
+}) {
+    if (!secret) return { ok: false, reason: 'signing_secret_not_configured' };
+    if (!signature || !timestamp) return { ok: false, reason: 'missing_signature' };
+    if (typeof body !== 'string') return { ok: false, reason: 'missing_body' };
+    if (!/^\d{1,15}$/.test(timestamp)) return { ok: false, reason: 'invalid_timestamp' };
+
+    const ageSeconds = Math.abs(Math.floor(now / 1000) - Number(timestamp));
+    if (ageSeconds > maxAgeSeconds) return { ok: false, reason: 'stale_timestamp' };
+
+    const expected = computeSignature(secret, timestamp, body);
+    if (!constantTimeEqual(expected, signature)) {
+        return { ok: false, reason: 'invalid_signature' };
+    }
+    return { ok: true };
+}
+
+/**
+ * Case-insensitive header lookup over a Lambda/Netlify v1 event's headers.
+ *
+ * @param {Object} event
+ * @param {string} name - lower-case header name
+ * @returns {string|undefined}
+ */
+function readHeader(event, name) {
+    const headers = event?.headers || {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === name) {
+            return Array.isArray(value) ? value[0] : value;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * The raw request body exactly as signed: a string body as is, a base64
+ * body decoded to its UTF-8 text. An already-parsed object body cannot be
+ * verified (its bytes are gone), so it reads as absent.
+ *
+ * @param {Object} event
+ * @returns {string|null}
+ */
+function readRawBody(event) {
+    if (typeof event?.body !== 'string') return null;
+    if (event.isBase64Encoded) {
+        return Buffer.from(event.body, 'base64').toString('utf8');
+    }
+    return event.body;
+}
+
+module.exports = {
+    SIGNING_SECRET_ENV,
+    ALLOW_UNSIGNED_ENV,
+    SIGNATURE_HEADER,
+    TIMESTAMP_HEADER,
+    MAX_MESSAGE_AGE_SECONDS,
+    isProductionEnvironment,
+    allowsUnsignedMessages,
+    readSigningSecret,
+    signQueueMessage,
+    verifyQueueMessage,
+    readHeader,
+    readRawBody,
+};

package/queues/queue-provider.js

@@ -41,6 +41,25 @@ class QueueProvider {
     parseEvent(event) {
         throw new Error('Method parseEvent must be implemented by subclass');
     }
+
+    /**
+     * Prove an incoming event was sent by Frigg before anything is parsed or
+     * dispatched. HTTP-delivered queues (Netlify Background Functions,
+     * QStash) are public URLs, so their adapters check a signature here.
+     *
+     * The default refuses: an adapter that does not know how to verify its
+     * events must not have them run. An adapter whose transport already
+     * authenticates the caller (SQS triggering a Lambda) overrides this, and
+     * must not set `verifiesHttpDelivery`: an HTTP entry point (Netlify's
+     * worker-background) consults only adapters that set it to true, since
+     * a transport-trust answer says nothing about an HTTP caller.
+     *
+     * @param {Object} event - Raw event from the runtime
+     * @returns {Promise<{ ok: boolean, reason?: string, unsigned?: boolean }>}
+     */
+    async verifyEvent(event) {
+        return { ok: false, reason: 'verification_not_implemented' };
+    }
 }
 
 module.exports = { QueueProvider };