@openlup/platform 0.0.0 → 0.16.0

package/dist/kernel/platformKernel.js

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import { createPlatformBundleRegistry, platformEnvSchema as corePlatformEnvSchema, createPlatformBundleIdGuard, } from "@openlup/core/platform-runtime";
+/** The bundles a deployment can select with `PLATFORM_BUNDLE`. */
+export const PLATFORM_BUNDLE_IDS = [
+    "vercel-supabase",
+    "node-supabase",
+    "node-postgres",
+];
+/** The bundle selected when `PLATFORM_BUNDLE` is absent or unknown. */
+export const DEFAULT_PLATFORM_BUNDLE = "vercel-supabase";
+export const isPlatformBundleId = createPlatformBundleIdGuard(PLATFORM_BUNDLE_IDS);
+/** The readiness code a bundle reports when a selected capability lacks its configuration. */
+export const ENV_MISSING_CODE = "OPENLUP_E_ENV_MISSING";
+/** The blob capabilities a deployment can select with `PLATFORM_BLOB`. */
+export const BLOB_CAPABILITIES = ["filesystem", "s3", "supabase", "vercel-blob"];
+/**
+ * The blob capability in effect: a valid `PLATFORM_BLOB` selection, else the bundle's own. An
+ * invalid selection keeps the bundle's own here and is refused by readiness.
+ */
+export function resolveBlobCapability(descriptor, env) {
+    const selected = env.PLATFORM_BLOB?.trim();
+    return selected && BLOB_CAPABILITIES.includes(selected) ? selected : descriptor.capabilities.blob;
+}
+/** The settings each blob capability needs; an alternative name may stand in for the first. */
+const BLOB_SETTINGS = {
+    "vercel-blob": [["BLOB_READ_WRITE_TOKEN"]],
+    supabase: [["SUPABASE_URL", "VITE_SUPABASE_URL"], ["SUPABASE_SERVICE_ROLE_KEY"], ["BLOB_SUPABASE_BUCKET"]],
+    filesystem: [["BLOB_FS_ROOT"], ["BLOB_FS_BASE_URL"]],
+    s3: [["BLOB_S3_BUCKET"], ["BLOB_S3_BASE_URL"]],
+};
+function present(env, name) {
+    return typeof env[name] === "string" && env[name].trim() !== "";
+}
+/**
+ * Per-capability readiness, in this order: an unknown PLATFORM_BUNDLE refuses (resolution itself
+ * keeps defaulting); a self-host bundle needs APP_BASE_URL; then every selected capability's
+ * missing settings are reported together under OPENLUP_E_ENV_MISSING: a scheduler needs
+ * CRON_SECRET, Node scheduling needs DATABASE_URL for its cluster lock (never a silent no-op lock),
+ * and the selected blob capability needs its settings. An unknown PLATFORM_BLOB refuses too.
+ */
+function capabilityReadiness(descriptor, selfHost) {
+    return (env) => {
+        const raw = env.PLATFORM_BUNDLE;
+        if (raw !== undefined && raw.trim() !== "" && !isPlatformBundleId(raw)) {
+            return { ok: false, error: `unknown PLATFORM_BUNDLE "${raw}"; expected one of ${PLATFORM_BUNDLE_IDS.join(", ")}` };
+        }
+        const selectedBlob = env.PLATFORM_BLOB;
+        if (selectedBlob !== undefined && selectedBlob.trim() !== "" && !BLOB_CAPABILITIES.includes(selectedBlob.trim())) {
+            return { ok: false, error: `unknown PLATFORM_BLOB "${selectedBlob}"; expected one of ${BLOB_CAPABILITIES.join(", ")}` };
+        }
+        if (selfHost && !present(env, "APP_BASE_URL")) {
+            return { ok: false, error: "APP_BASE_URL is required for self-host bundles" };
+        }
+        const { scheduler } = descriptor.capabilities;
+        const blob = resolveBlobCapability(descriptor, env);
+        const missing = [];
+        if (scheduler === "vercel-cron" || scheduler === "node-cron") {
+            if (!present(env, "CRON_SECRET"))
+                missing.push("CRON_SECRET (scheduler)");
+        }
+        if (scheduler === "node-cron" && !present(env, "DATABASE_URL"))
+            missing.push("DATABASE_URL (scheduler lock)");
+        for (const names of BLOB_SETTINGS[blob] ?? []) {
+            if (!names.some((name) => present(env, name)))
+                missing.push(`${names[0]} (blob: ${blob})`);
+        }
+        return missing.length === 0 ? { ok: true } : { ok: false, error: `${ENV_MISSING_CODE}: ${missing.join(", ")}` };
+    };
+}
+function descriptor(id, capabilities, selfHost) {
+    return { id, capabilities, readReadiness: capabilityReadiness({ capabilities }, selfHost) };
+}
+const DESCRIPTORS = [
+    descriptor("vercel-supabase", {
+        http: "vercel",
+        scheduler: "vercel-cron",
+        blob: "vercel-blob",
+        data: "supabase",
+        migrations: "supabase",
+        analytics: "vercel",
+        transactional: "application",
+    }, false),
+    descriptor("node-supabase", {
+        http: "node",
+        scheduler: "node-cron",
+        blob: "supabase",
+        data: "supabase",
+        migrations: "supabase",
+        analytics: "gtm",
+        transactional: "node",
+    }, true),
+    descriptor("node-postgres", {
+        http: "node",
+        scheduler: "node-cron",
+        blob: "filesystem",
+        data: "postgres",
+        migrations: "postgres",
+        analytics: "noop",
+        transactional: "node",
+    }, true),
+];
+const registry = createPlatformBundleRegistry({
+    descriptors: DESCRIPTORS,
+    defaultBundleId: DEFAULT_PLATFORM_BUNDLE,
+});
+export const PLATFORM_BUNDLE_DESCRIPTORS = registry.descriptors;
+export function getBundleDescriptor(id) {
+    return registry.getBundleDescriptor(id);
+}
+export function resolveBundleId(env) {
+    return registry.resolveBundleId(env);
+}
+export const platformEnvSchema = corePlatformEnvSchema.extend({
+    PLATFORM_BUNDLE: z.enum(PLATFORM_BUNDLE_IDS).optional(),
+});

package/dist/migrations/index.d.ts

@@ -0,0 +1 @@
+export { createPostgresMigrationRunner, resolvePostgresMigrationRunnerEnv, type PlatformMigrationFile, type PlatformMigrationManifest, type PlatformMigrationManifestEntry, type PlatformMigrationSource, type PostgresMigrationRunnerEnv, type PostgresMigrationRunnerOptions, } from "./postgresRunner.js";

package/dist/migrations/index.js

@@ -0,0 +1 @@
+export { createPostgresMigrationRunner, resolvePostgresMigrationRunnerEnv, } from "./postgresRunner.js";

package/dist/migrations/postgresRunner.d.ts

@@ -0,0 +1,50 @@
+import type { Pool, PoolClient } from "pg";
+import type { MigrationRunnerPort } from "@openlup/core/platform-runtime";
+export interface PostgresMigrationRunnerEnv {
+    connectionString: string;
+}
+/** One migration file of the deployment's platform catalogue. */
+export type PlatformMigrationFile = {
+    file: string;
+    content: string;
+};
+export type PlatformMigrationManifestEntry = {
+    file: string;
+    sha256: string;
+};
+/** The validated manifest: a baseline, its ordered forwards and the expected object inventory. */
+export type PlatformMigrationManifest = {
+    schemaVersion: 1;
+    baseline: PlatformMigrationManifestEntry;
+    forward: PlatformMigrationManifestEntry[];
+    objectInventorySha256: string;
+};
+/**
+ * The deployment's migration catalogue and its validator. `evaluate` returns every refusal for a
+ * manifest against the catalogue files and, when given, the live object-inventory payload.
+ */
+export interface PlatformMigrationSource {
+    readMigrations(root: string): {
+        migrations: PlatformMigrationFile[];
+        errors: string[];
+    };
+    readManifest(root: string): unknown | null;
+    evaluate(input: {
+        manifest: unknown;
+        migrations: readonly PlatformMigrationFile[];
+        objectInventoryPayload?: string;
+    }): string[];
+}
+export interface PostgresMigrationRunnerOptions {
+    /** Name of the PostgreSQL advisory lock that serializes migration sessions. */
+    lockName: string;
+    /** The deployment's migration catalogue. */
+    source: PlatformMigrationSource;
+    /** Serializes the live object inventory that the manifest's `objectInventorySha256` pins. */
+    catalogProjectionPayload: (client: PoolClient) => Promise<string>;
+    /** Catalogue root; defaults to process.cwd(). */
+    root?: string;
+    poolFactory?: (env: PostgresMigrationRunnerEnv) => Pool | Promise<Pool>;
+}
+export declare function createPostgresMigrationRunner(env: PostgresMigrationRunnerEnv, options: PostgresMigrationRunnerOptions): MigrationRunnerPort;
+export declare function resolvePostgresMigrationRunnerEnv(env: Record<string, string | undefined>): PostgresMigrationRunnerEnv;

package/dist/migrations/postgresRunner.js

@@ -0,0 +1,176 @@
+// Public-platform MigrationRunnerPort for the experimental node-postgres bundle.
+// The manifest and its exact SQL bytes are validated before a pool is created.
+// Applied rows are an exact prefix of that catalog; path, digest or position
+// drift is fatal. Only the caller's catalogue is applied; no other migration
+// history is selected or reachable through a default.
+const LEDGER = "public.platform_schema_migrations";
+const ACQUIRE_MIGRATION_LOCK = "SELECT pg_advisory_lock(hashtextextended($1, 0))";
+const RELEASE_MIGRATION_LOCK = "SELECT pg_advisory_unlock(hashtextextended($1, 0)) AS unlocked";
+export function createPostgresMigrationRunner(env, options) {
+    const root = options.root ?? process.cwd();
+    let pool = null;
+    async function getPool() {
+        if (pool)
+            return pool;
+        const factory = options.poolFactory ?? defaultPoolFactory;
+        pool = await factory(env);
+        return pool;
+    }
+    return {
+        async status() {
+            assertConnectionString(env);
+            const plan = loadPlan(root, options.source);
+            return withMigrationSession(await getPool(), options.lockName, async (client) => {
+                const applied = await readAppliedPrefix(client, plan.units);
+                if (applied.length === plan.units.length)
+                    await assertObjectInventory(client, plan, options);
+                return {
+                    pending: plan.units.slice(applied.length).map((unit) => unit.catalogPath),
+                    applied: applied.map((unit) => unit.catalogPath),
+                };
+            });
+        },
+        async apply(opts) {
+            assertConnectionString(env);
+            const plan = loadPlan(root, options.source);
+            return withMigrationSession(await getPool(), options.lockName, async (client) => {
+                const already = await readAppliedPrefix(client, plan.units);
+                const pending = plan.units.slice(already.length);
+                if (opts?.dryRun) {
+                    if (pending.length === 0)
+                        await assertObjectInventory(client, plan, options);
+                    return { applied: pending.map((unit) => unit.catalogPath) };
+                }
+                const appliedNow = [];
+                for (const unit of pending) {
+                    await client.query("BEGIN");
+                    try {
+                        await client.query(unit.sql);
+                        await client.query(`INSERT INTO ${LEDGER} (catalog_path, sha256, position) VALUES ($1, $2, $3)`, [unit.catalogPath, unit.sha256, unit.position]);
+                        await client.query("COMMIT");
+                        appliedNow.push(unit.catalogPath);
+                    }
+                    catch (error) {
+                        await client.query("ROLLBACK").catch(() => { });
+                        throw new Error(`platform migration ${unit.catalogPath} failed: ${errorMessage(error)}`);
+                    }
+                }
+                const complete = await readAppliedPrefix(client, plan.units);
+                if (complete.length !== plan.units.length)
+                    throw new Error("platform migration ledger is incomplete after apply");
+                await assertObjectInventory(client, plan, options);
+                return { applied: appliedNow };
+            });
+        },
+    };
+}
+async function withMigrationSession(pool, lockName, operation) {
+    const client = await pool.connect();
+    let locked = false;
+    let failed = false;
+    let operationFailure;
+    let result;
+    try {
+        await client.query(ACQUIRE_MIGRATION_LOCK, [lockName]);
+        locked = true;
+        result = await operation(client);
+    }
+    catch (error) {
+        failed = true;
+        operationFailure = error;
+    }
+    let unlockFailure;
+    if (locked) {
+        try {
+            const unlocked = await client.query(RELEASE_MIGRATION_LOCK, [lockName]);
+            if (unlocked.rows[0]?.unlocked !== true)
+                throw new Error("PostgreSQL did not release the advisory lock");
+        }
+        catch (error) {
+            unlockFailure = error;
+        }
+    }
+    client.release(unlockFailure !== undefined || (failed && !locked));
+    if (failed) {
+        if (unlockFailure !== undefined) {
+            throw new Error(`platform migration operation failed: ${errorMessage(operationFailure)}; advisory lock release failed: ${errorMessage(unlockFailure)}`);
+        }
+        throw operationFailure;
+    }
+    if (unlockFailure !== undefined) {
+        throw new Error(`platform migration advisory lock release failed: ${errorMessage(unlockFailure)}`);
+    }
+    return result;
+}
+function assertConnectionString(env) {
+    if (env.connectionString.trim() === "") {
+        throw new Error("DATABASE_URL is required for node-postgres migrations");
+    }
+}
+function loadPlan(root, source) {
+    const catalog = source.readMigrations(root);
+    const rawManifest = source.readManifest(root);
+    const errors = [...catalog.errors];
+    if (rawManifest === null)
+        errors.push("platform migration manifest is missing");
+    else
+        errors.push(...source.evaluate({ manifest: rawManifest, migrations: catalog.migrations }));
+    if (errors.length > 0)
+        throw new Error(`platform migration catalog rejected: ${errors.join("; ")}`);
+    const manifest = rawManifest;
+    const byPath = new Map(catalog.migrations.map((migration) => [migration.file, migration.content]));
+    const entries = [manifest.baseline, ...manifest.forward];
+    const units = entries.map((entry, position) => Object.freeze({
+        catalogPath: entry.file,
+        sha256: entry.sha256,
+        position,
+        sql: byPath.get(entry.file),
+    }));
+    return Object.freeze({ manifest, migrations: catalog.migrations, units: Object.freeze(units) });
+}
+async function readAppliedPrefix(client, units) {
+    const exists = await client.query("SELECT to_regclass($1) IS NOT NULL AS ledger_exists", [LEDGER]);
+    if (exists.rows[0]?.ledger_exists !== true)
+        return [];
+    const result = await client.query(`SELECT catalog_path, sha256, position FROM ${LEDGER} ORDER BY position`);
+    if (result.rows.length > units.length)
+        throw new Error("platform migration ledger contains an extra row");
+    for (let index = 0; index < result.rows.length; index += 1) {
+        const row = result.rows[index];
+        const unit = units[index];
+        if (row.catalog_path !== unit.catalogPath || row.sha256 !== unit.sha256 || row.position !== unit.position) {
+            throw new Error(`platform migration ledger is not the exact manifest prefix at position ${index}`);
+        }
+    }
+    return units.slice(0, result.rows.length);
+}
+async function assertObjectInventory(client, plan, options) {
+    const payload = await options.catalogProjectionPayload(client);
+    const errors = options.source.evaluate({
+        manifest: plan.manifest,
+        migrations: plan.migrations,
+        objectInventoryPayload: payload,
+    });
+    if (errors.length > 0)
+        throw new Error(`platform migration inventory rejected: ${errors.join("; ")}`);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+async function defaultPoolFactory(env) {
+    const pg = await import("pg").catch(peerMissing);
+    const PoolCtor = (pg.default?.Pool ?? pg.Pool);
+    return new PoolCtor({ connectionString: env.connectionString });
+}
+export function resolvePostgresMigrationRunnerEnv(env) {
+    return { connectionString: env.DATABASE_URL ?? "" };
+}
+/** Translate only absence of this optional peer; preserve broken SDKs and other failures. */
+function peerMissing(cause) {
+    if (cause instanceof Error && "code" in cause
+        && (cause.code === "ERR_MODULE_NOT_FOUND" || cause.code === "MODULE_NOT_FOUND")
+        && /^Cannot find (?:package|module) ['"]pg['"]/.test(cause.message)) {
+        throw new Error("OPENLUP_E_PEER_MISSING: pg is required by the Postgres migration runner; install it alongside @openlup/platform", { cause });
+    }
+    throw cause;
+}

package/dist/scheduler/advisoryLock.d.ts

@@ -0,0 +1,44 @@
+/** A cluster-wide, per-job mutex. Returns true iff THIS caller acquired the lock. */
+export interface AdvisoryLock {
+    /** Explicit capability marker; a host that must not run a job twice requires a cluster lock. */
+    readonly durability?: "cluster" | "process";
+    /** Try to acquire the lock for `jobId` without blocking. */
+    tryAcquire(jobId: string): Promise<boolean>;
+    /** Release a previously-acquired lock for `jobId`. */
+    release(jobId: string): Promise<void>;
+    /** Release the dedicated session when the host stops; safe to call repeatedly. */
+    close(): Promise<void>;
+}
+/** Minimal pg-query surface (a `pg` Pool/Client satisfies this) — keeps `pg` out of the import graph. */
+export interface AdvisoryLockQuerier {
+    query<T = unknown>(text: string, values?: unknown[]): Promise<{
+        rows: T[];
+    }>;
+    end?(): Promise<void>;
+}
+/**
+ * Deterministic 64-bit-ish key from a jobId for pg_try_advisory_lock(bigint).
+ * Postgres advisory locks key on bigint; we hash the job name to a stable signed-32-bit int
+ * (the single-arg `pg_try_advisory_lock(key bigint)` accepts it). Stable across processes.
+ */
+export declare function advisoryLockKey(jobId: string): number;
+/**
+ * pg-backed advisory lock. Uses `pg_try_advisory_lock` (session-scoped, non-blocking) on acquire
+ * and `pg_advisory_unlock` on release. NOTE: session-scoped locks require the same connection for
+ * acquire+release, so the supplied querier should be a single dedicated client/connection, not a
+ * pool that hands out a different connection per query.
+ */
+export declare function createPgAdvisoryLock(client: AdvisoryLockQuerier, closeClient?: () => Promise<void>): AdvisoryLock;
+/**
+ * Build the lock a long-running host should actually use, from the connection string the
+ * environment declares. Returns null when no connection string is configured, which leaves the
+ * scheduler on its always-granting default — the exact behaviour of a host with a single instance.
+ *
+ * The connection is opened LAZILY, on the first acquire, and then reused: a session-scoped
+ * try-lock must acquire and release on the SAME connection, and a host that never fires a timer
+ * must never open one. `pg` stays out of the static import graph (dynamic import), so the default
+ * hosted path and typecheck are untouched.
+ */
+export declare function createEnvAdvisoryLock(env: Record<string, string | undefined>, connect?: (connectionString: string) => Promise<AdvisoryLockQuerier>): AdvisoryLock | null;
+/** Lock that always grants (single-instance / tests). Never use in multi-instance Node deploys. */
+export declare function createNoopAdvisoryLock(): AdvisoryLock;

package/dist/scheduler/advisoryLock.js

@@ -0,0 +1,114 @@
+// Per-job advisory lock for the Node scheduler.
+//
+// On Vercel exactly one cron timer fires per schedule. On a self-hosted Node bundle the SAME
+// process image can run on MULTIPLE instances (horizontal scale, blue/green overlap, a stray
+// second pod) — each with its own node-cron timer. Without coordination, every instance would
+// fire the same job at the same minute => double-run (double emails, double polls, double
+// dispatch). `pg_try_advisory_lock` gives us a cluster-wide, connection-scoped mutex keyed per job:
+// only the instance that ACQUIRES the lock runs the job body; the rest skip and release nothing
+// (try-lock returns false without blocking). The lock is released after the job body finishes.
+//
+// Injectable: the adapter depends on the AdvisoryLock interface, not on `pg` directly, so tests
+// run without a database and a non-Supabase bundle can supply its own pg-backed implementation.
+/**
+ * Deterministic 64-bit-ish key from a jobId for pg_try_advisory_lock(bigint).
+ * Postgres advisory locks key on bigint; we hash the job name to a stable signed-32-bit int
+ * (the single-arg `pg_try_advisory_lock(key bigint)` accepts it). Stable across processes.
+ */
+export function advisoryLockKey(jobId) {
+    // FNV-1a 32-bit, then coerce to signed 32-bit so it fits a Postgres int safely.
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < jobId.length; i += 1) {
+        hash ^= jobId.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash | 0;
+}
+/**
+ * pg-backed advisory lock. Uses `pg_try_advisory_lock` (session-scoped, non-blocking) on acquire
+ * and `pg_advisory_unlock` on release. NOTE: session-scoped locks require the same connection for
+ * acquire+release, so the supplied querier should be a single dedicated client/connection, not a
+ * pool that hands out a different connection per query.
+ */
+export function createPgAdvisoryLock(client, closeClient = () => client.end?.() ?? Promise.resolve()) {
+    let closePromise = null;
+    return {
+        durability: "cluster",
+        async tryAcquire(jobId) {
+            const key = advisoryLockKey(jobId);
+            const { rows } = await client.query("SELECT pg_try_advisory_lock($1) AS locked", [key]);
+            return rows[0]?.locked === true;
+        },
+        async release(jobId) {
+            const key = advisoryLockKey(jobId);
+            await client.query("SELECT pg_advisory_unlock($1)", [key]);
+        },
+        close() {
+            closePromise ??= closeClient();
+            return closePromise;
+        },
+    };
+}
+/**
+ * Build the lock a long-running host should actually use, from the connection string the
+ * environment declares. Returns null when no connection string is configured, which leaves the
+ * scheduler on its always-granting default — the exact behaviour of a host with a single instance.
+ *
+ * The connection is opened LAZILY, on the first acquire, and then reused: a session-scoped
+ * try-lock must acquire and release on the SAME connection, and a host that never fires a timer
+ * must never open one. `pg` stays out of the static import graph (dynamic import), so the default
+ * hosted path and typecheck are untouched.
+ */
+export function createEnvAdvisoryLock(env, connect = connectDedicatedClient) {
+    const connectionString = env.DATABASE_URL?.trim() ?? "";
+    if (connectionString === "")
+        return null;
+    let pending = null;
+    let closed = false;
+    let closePromise = null;
+    const querier = {
+        async query(text, values) {
+            if (closed)
+                throw new Error("advisory_lock_closed");
+            pending ??= connect(connectionString);
+            const client = await pending;
+            return client.query(text, values);
+        },
+    };
+    return createPgAdvisoryLock(querier, () => {
+        closed = true;
+        closePromise ??= pending?.then((client) => client.end?.() ?? undefined) ?? Promise.resolve();
+        return closePromise;
+    });
+}
+async function connectDedicatedClient(connectionString) {
+    const pg = await import("pg").catch(peerMissing);
+    const ClientCtor = (pg.default?.Client ?? pg.Client);
+    const client = new ClientCtor({ connectionString });
+    await client.connect();
+    return client;
+}
+/** Lock that always grants (single-instance / tests). Never use in multi-instance Node deploys. */
+export function createNoopAdvisoryLock() {
+    return {
+        durability: "process",
+        async tryAcquire() {
+            return true;
+        },
+        async release() {
+            /* no-op */
+        },
+        async close() {
+            /* no-op */
+        },
+    };
+}
+/** Translate only absence of this optional peer; preserve broken SDKs and other failures. */
+function peerMissing(cause) {
+    if (cause instanceof Error && "code" in cause
+        && (cause.code === "ERR_MODULE_NOT_FOUND" || cause.code === "MODULE_NOT_FOUND")
+        && /^Cannot find (?:package|module) ['"]pg['"]/.test(cause.message)) {
+        throw new Error("OPENLUP_E_PEER_MISSING: pg is required by the Postgres scheduler advisory lock; install it alongside @openlup/platform", { cause });
+    }
+    throw cause;
+}

package/dist/scheduler/cronGuard.d.ts

@@ -0,0 +1,10 @@
+import type { HttpRequest } from "../http/index.js";
+import { bearerToken } from "./cronSecret.js";
+export { bearerToken };
+export interface CronAuthDenied {
+    status: number;
+    body: Record<string, unknown>;
+}
+export declare function authorizeCron(req: HttpRequest, env: {
+    CRON_SECRET?: string;
+}): CronAuthDenied | null;

package/dist/scheduler/cronGuard.js

@@ -0,0 +1,19 @@
+import { bearerToken, cronSecretMatches } from "./cronSecret.js";
+export { bearerToken };
+// Shared cron entrypoint guard: method allowlist + CRON_SECRET presence + constant-time bearer
+// match (see ./cronSecret.ts). Returns a response to return verbatim when denied, or null when the
+// request is authorized. Per-job flag kill-switches and provider/env readiness
+// checks intentionally stay in each job — they differ per job and must run after
+// this guard but before any ledger write.
+export function authorizeCron(req, env) {
+    if (req.method !== "GET" && req.method !== "POST") {
+        return { status: 405, body: { ok: false, error: "method_not_allowed" } };
+    }
+    if (!env.CRON_SECRET) {
+        return { status: 503, body: { ok: false, error: "cron_secret_required" } };
+    }
+    if (!cronSecretMatches(bearerToken(req), env.CRON_SECRET)) {
+        return { status: 401, body: { ok: false, error: "unauthorized" } };
+    }
+    return null;
+}

package/dist/scheduler/cronSecret.d.ts

@@ -0,0 +1,5 @@
+import type { PlatformHttpRequest } from "@openlup/core/platform-runtime";
+/** Extract the Bearer token from a request Authorization header (case-insensitive). */
+export declare function bearerToken(req: PlatformHttpRequest): string | null;
+/** True when the presented token equals the configured secret, compared in constant time. */
+export declare function cronSecretMatches(presented: string | null, expected: string): boolean;

package/dist/scheduler/cronSecret.js

@@ -0,0 +1,23 @@
+// The one cron bearer check shared by the cron entrypoint guard and the scheduler verifier.
+//
+// Grammar: `Authorization: Bearer <token>`, scheme case-insensitive, the first value of a repeated
+// header, the presented token trimmed and the configured secret compared as-is. The comparison takes
+// the same time for every presented token of the secret's byte length, so a mismatch reveals no
+// matching prefix; a token of another byte length (including any non-ASCII one) is refused first.
+import { timingSafeEqual } from "node:crypto";
+/** Extract the Bearer token from a request Authorization header (case-insensitive). */
+export function bearerToken(req) {
+    const auth = req.headers.authorization;
+    const header = Array.isArray(auth) ? auth[0] : auth;
+    return header?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim() ?? null;
+}
+/** True when the presented token equals the configured secret, compared in constant time. */
+export function cronSecretMatches(presented, expected) {
+    if (presented === null)
+        return false;
+    const presentedBytes = Buffer.from(presented, "utf8");
+    const expectedBytes = Buffer.from(expected, "utf8");
+    if (presentedBytes.length !== expectedBytes.length)
+        return false;
+    return timingSafeEqual(presentedBytes, expectedBytes);
+}

package/dist/scheduler/handlers.d.ts

@@ -0,0 +1,9 @@
+export type ScheduledInvocationSource = "node_cron" | "scheduler";
+export interface ScheduledJobInvocation {
+    jobId: string;
+    invocationSource: ScheduledInvocationSource;
+}
+export type ScheduledJobHandler = (invocation: ScheduledJobInvocation) => Promise<void> | void;
+export type ScheduledJobHandlerRegistry = Readonly<Partial<Record<string, ScheduledJobHandler>>>;
+/** Merge contributed bindings in order; a later contribution replaces an earlier one for the same job. */
+export declare function mergeScheduledJobHandlers(...registries: ReadonlyArray<ScheduledJobHandlerRegistry | undefined>): ScheduledJobHandlerRegistry;

package/dist/scheduler/handlers.js

@@ -0,0 +1,10 @@
+// Direct scheduled-job bindings for self-hosted runtimes.
+//
+// The Node host mounts every declared `/api/cron/<jobId>` route, so any job can be reached
+// through the HTTP compatibility bridge. A direct binding skips that hop: it calls the
+// application runtime in-process and records an honest invocation source instead of a
+// hosted-cron one. Deployments and domains contribute bindings; this module only merges them.
+/** Merge contributed bindings in order; a later contribution replaces an earlier one for the same job. */
+export function mergeScheduledJobHandlers(...registries) {
+    return Object.assign({}, ...registries.filter((registry) => registry !== undefined));
+}

package/dist/scheduler/httpEntry.d.ts

@@ -0,0 +1,16 @@
+import type { JobLeasePort } from "@openlup/core/platform-runtime";
+import type { HttpRequest, HttpResponse } from "../http/index.js";
+import { type ScheduledJob } from "./jobs.js";
+export interface ScheduledJobHttpEntryOptions {
+    /** Environment whose CRON_SECRET authenticates the caller, read on each request. */
+    env: () => {
+        CRON_SECRET?: string;
+    };
+    /** Evidence recorded for HTTP invocations, for example the hosting platform's cron. */
+    invocationSource: string;
+    /** The job-lease port, required when the job declares a lease. */
+    lease?: JobLeasePort;
+    /** Error sink for a failed run (defaults to console.error). */
+    onError?: (jobId: string, error: unknown) => void;
+}
+export declare function createScheduledJobHttpEntry(job: ScheduledJob, options: ScheduledJobHttpEntryOptions): (req: HttpRequest, res: HttpResponse) => Promise<void>;

package/dist/scheduler/httpEntry.js

@@ -0,0 +1,31 @@
+// Authenticated HTTP cron entry for a transport-neutral scheduled job.
+//
+// The entry is an adapter: it applies the cron guard (method, configured secret, bearer token) and
+// only then runs the job with an HTTP invocation. A refusal answers the guard's own status and
+// body. A run answers 200 with its result, a lease held elsewhere answers 200 as skipped, and a
+// failed run answers 500 without error detail; the error goes to the host's error sink.
+import { authorizeCron } from "./cronGuard.js";
+import { runScheduledJob } from "./jobs.js";
+export function createScheduledJobHttpEntry(job, options) {
+    const onError = options.onError ?? ((jobId, error) => console.error(`[scheduled-job] "${jobId}" failed`, error));
+    return async function scheduledJobEntry(req, res) {
+        const denied = authorizeCron(req, options.env());
+        if (denied) {
+            res.status(denied.status).json(denied.body);
+            return;
+        }
+        try {
+            const result = await runScheduledJob(job, {
+                invocation: { triggerKind: "scheduler", invocationSource: options.invocationSource },
+                lease: options.lease,
+            });
+            res.status(200).json(result.status === "skipped"
+                ? { ok: true, skipped: true, reason: result.reason }
+                : { ok: true, result: result.summary });
+        }
+        catch (error) {
+            onError(job.id, error);
+            res.status(500).json({ ok: false, error: "scheduled_job_failed" });
+        }
+    };
+}

package/dist/scheduler/index.d.ts

@@ -0,0 +1,9 @@
+export { jobIdFromPath, jobRegistryFromConfig, loadJobRegistry, type PlatformRuntimeConfig, type ScheduledJobDeclaration, } from "./jobRegistry.js";
+export { advisoryLockKey, createEnvAdvisoryLock, createNoopAdvisoryLock, createPgAdvisoryLock, type AdvisoryLock, type AdvisoryLockQuerier, } from "./advisoryLock.js";
+export { createNodeScheduler, withAdvisoryLock, type CreateNodeSchedulerOptions, type CronScheduler, type NodeSchedulerAdapter, } from "./nodeScheduler.js";
+export { bearerToken, createVercelScheduler, verifyCronAuth, type VercelSchedulerAdapter, } from "./vercelScheduler.js";
+export { authorizeCron, type CronAuthDenied } from "./cronGuard.js";
+export { cronSecretMatches } from "./cronSecret.js";
+export { mergeScheduledJobHandlers, type ScheduledInvocationSource, type ScheduledJobHandler, type ScheduledJobHandlerRegistry, type ScheduledJobInvocation, } from "./handlers.js";
+export { createScheduledJobRegistry, cronFromCadenceSeconds, runScheduledJob, scheduledJobsFromContribution, type ScheduledJob, type ScheduledJobContext, type ScheduledJobRunResult, } from "./jobs.js";
+export { createScheduledJobHttpEntry, type ScheduledJobHttpEntryOptions } from "./httpEntry.js";