@actuate-media/cms-core 0.11.1 → 0.12.0

package/dist/cron/index.js

@@ -0,0 +1,222 @@
+/**
+ * Cron handlers for scheduled platform jobs.
+ *
+ * The endpoints in `api/handlers.ts` validate `Authorization: Bearer ${CRON_SECRET}`
+ * before invoking these — Vercel Cron sends that header automatically when
+ * `CRON_SECRET` is defined in the project's environment. See:
+ * https://vercel.com/docs/cron-jobs/manage-cron-jobs#securing-cron-jobs
+ *
+ * Each handler is **idempotent** and **bounded** — safe to invoke from any
+ * scheduler (Vercel Cron, GitHub Actions, EventBridge, k8s CronJob, etc.) and
+ * safe to invoke twice in the same window.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { schedulingCronHandler } from '../scheduling/index.js';
+const DAY = 24 * 60 * 60 * 1000;
+const DEFAULT_CLEANUP = {
+    sessionRetentionMs: 7 * DAY,
+    auditLogRetentionMs: 90 * DAY,
+    trashRetentionMs: 30 * DAY,
+    passwordResetRetentionMs: 1 * DAY,
+};
+function modelExists(db, name) {
+    if (db == null || typeof db !== 'object' || !(name in db))
+        return false;
+    const delegate = db[name];
+    // `typeof null === 'object'` in JavaScript, so we have to check `!== null`
+    // explicitly. Without this guard, `{ session: null }` would pass the check
+    // and `db.session.deleteMany(...)` would throw a TypeError that the outer
+    // try/catch only papers over.
+    return delegate !== null && typeof delegate === 'object';
+}
+/**
+ * Delete stale rows from session, audit log, trash, and password-reset tables.
+ *
+ * Each deletion is wrapped in its own try/catch so a missing model (e.g. an
+ * older Prisma schema without `passwordResetToken`) doesn't fail the entire
+ * job — partial cleanup is still useful and the caller logs the count.
+ */
+export async function processCleanup(db, options = {}) {
+    const opts = { ...DEFAULT_CLEANUP, ...options };
+    const now = Date.now();
+    const result = {
+        sessionsDeleted: 0,
+        auditLogsDeleted: 0,
+        documentsDeleted: 0,
+        passwordResetTokensDeleted: 0,
+    };
+    if (modelExists(db, 'session')) {
+        try {
+            const cutoff = new Date(now - opts.sessionRetentionMs);
+            const r = await db.session.deleteMany({
+                where: {
+                    OR: [{ revokedAt: { lt: cutoff } }, { expiresAt: { lt: cutoff } }],
+                },
+            });
+            result.sessionsDeleted = r?.count ?? 0;
+        }
+        catch (err) {
+            console.warn('[actuate][cron] session cleanup failed:', errMsg(err));
+        }
+    }
+    if (modelExists(db, 'auditLog')) {
+        try {
+            const cutoff = new Date(now - opts.auditLogRetentionMs);
+            const r = await db.auditLog.deleteMany({ where: { timestamp: { lt: cutoff } } });
+            result.auditLogsDeleted = r?.count ?? 0;
+        }
+        catch (err) {
+            console.warn('[actuate][cron] audit log cleanup failed:', errMsg(err));
+        }
+    }
+    if (modelExists(db, 'document')) {
+        try {
+            const cutoff = new Date(now - opts.trashRetentionMs);
+            const r = await db.document.deleteMany({ where: { deletedAt: { lt: cutoff } } });
+            result.documentsDeleted = r?.count ?? 0;
+        }
+        catch (err) {
+            console.warn('[actuate][cron] trash cleanup failed:', errMsg(err));
+        }
+    }
+    if (modelExists(db, 'passwordResetToken')) {
+        try {
+            const cutoff = new Date(now - opts.passwordResetRetentionMs);
+            const r = await db.passwordResetToken.deleteMany({
+                where: {
+                    OR: [{ usedAt: { lt: cutoff } }, { expiresAt: { lt: cutoff } }],
+                },
+            });
+            result.passwordResetTokensDeleted = r?.count ?? 0;
+        }
+        catch (err) {
+            console.warn('[actuate][cron] password reset token cleanup failed:', errMsg(err));
+        }
+    }
+    return result;
+}
+/**
+ * Run the same SEO checks as `POST /seo/scan`, but headlessly so a cron
+ * (or a CLI / external scheduler) can invoke it without an admin session.
+ *
+ * Bounded by `maxDocuments` to avoid OOM / timeout on large catalogs —
+ * defaults to 5000, which is well above the typical Vercel function memory
+ * envelope while staying safely under the 60s cron execution limit.
+ */
+export async function processSeoScan(db, options = {}) {
+    const maxDocuments = options.maxDocuments ?? 5000;
+    if (!modelExists(db, 'document')) {
+        return { total: 0, pagesWithIssues: 0, totalProblems: 0, issues: [] };
+    }
+    const documents = await db.document.findMany({
+        where: { status: 'PUBLISHED', deletedAt: null },
+        select: {
+            id: true,
+            title: true,
+            slug: true,
+            collection: true,
+            data: true,
+            plainText: true,
+        },
+        take: maxDocuments,
+    });
+    const issues = [];
+    for (const doc of documents) {
+        const data = (doc.data ?? {});
+        const problems = [];
+        if (!data.metaTitle && !data.seoTitle)
+            problems.push('Missing meta title');
+        if (!data.metaDescription && !data.seoDescription)
+            problems.push('Missing meta description');
+        if (!data.canonical)
+            problems.push('No canonical URL set');
+        if (!data.schemaType)
+            problems.push('No Schema.org type');
+        const plainText = (doc.plainText ?? '');
+        if (plainText.length > 0 && plainText.length < 300) {
+            problems.push('Content is too short (< 300 characters)');
+        }
+        const content = typeof data.body === 'string'
+            ? data.body
+            : typeof data.content === 'string'
+                ? data.content
+                : '';
+        if (content) {
+            const imgMatches = content.match(/<img\b[^>]*>/gi) ?? [];
+            // Case-insensitive: `<IMG ALT="text">` is valid HTML and should not be
+            // flagged as missing. Tests the literal attribute name with `\balt\s*=`
+            // to avoid matching unrelated tokens that happen to contain `alt=`.
+            const missingAlt = imgMatches.filter((img) => !/\balt\s*=/i.test(img)).length;
+            if (missingAlt > 0)
+                problems.push(`${missingAlt} image(s) missing alt text`);
+            // Case-insensitive to match the HTML spec — `<H1>`, `<h1>`, `<h1 class="...">`
+            // and `<h1\n>` all count.
+            if (!/<h1\b/i.test(content)) {
+                problems.push('No H1 heading found in content');
+            }
+        }
+        if (problems.length > 0) {
+            issues.push({
+                documentId: doc.id,
+                title: doc.title ?? 'Untitled',
+                slug: doc.slug ?? '',
+                problems,
+            });
+        }
+    }
+    return {
+        total: documents.length,
+        pagesWithIssues: issues.length,
+        totalProblems: issues.reduce((sum, i) => sum + i.problems.length, 0),
+        issues,
+    };
+}
+/** Re-export for convenience so the route handler can import everything from one module. */
+export { schedulingCronHandler };
+/**
+ * Validate a Vercel-style cron Authorization header against `CRON_SECRET`.
+ *
+ * Returns `false` if the env var is missing — that's deliberately fail-closed
+ * so a misconfigured deploy can't silently expose cron endpoints to the public
+ * internet. Comparison is constant-time to defeat byte-by-byte timing attacks.
+ */
+export function isAuthorizedCronRequest(authHeader) {
+    const secret = process.env.CRON_SECRET;
+    if (!secret || secret.length === 0)
+        return false;
+    if (!authHeader)
+        return false;
+    // Vercel sends `Authorization: Bearer <CRON_SECRET>`. Some self-hosted
+    // schedulers send the bare value; accept both.
+    const trimmed = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : authHeader;
+    return constantTimeEqual(trimmed, secret);
+}
+/**
+ * Per-process random HMAC key. Using a per-process key (not a fixed string)
+ * means an attacker can't precompute HMACs offline to compare against — the
+ * comparison is between two HMACs they cannot directly observe.
+ */
+const HMAC_COMPARE_KEY = randomBytes(32);
+/**
+ * Compare two strings in constant time, including across length differences.
+ *
+ * The naive approach — early-return on length mismatch then per-character
+ * XOR — leaks the secret length: an attacker can probe `Authorization`
+ * header values of varying lengths and time the response to learn how many
+ * bytes `CRON_SECRET` actually has, reducing the brute-force search space.
+ *
+ * Instead, HMAC-SHA256 both inputs (yielding fixed 32-byte digests
+ * regardless of input length) and compare those with `timingSafeEqual`.
+ * `timingSafeEqual` requires equal-length buffers, which the HMAC step
+ * guarantees, and it's the only constant-time comparison primitive in
+ * `node:crypto` that's safe across all V8 optimisations.
+ */
+function constantTimeEqual(a, b) {
+    const hmacA = createHmac('sha256', HMAC_COMPARE_KEY).update(a).digest();
+    const hmacB = createHmac('sha256', HMAC_COMPARE_KEY).update(b).digest();
+    return timingSafeEqual(hmacA, hmacB);
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=index.js.map

package/dist/cron/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cron/index.ts"],"names":[],"mappings":"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"}

package/dist/security/encrypted-fields.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Thrown for invalid `CMS_ENCRYPTION_KEY` shape. We use a named class so the
+ * caller (typically an API handler) can map it to a clear 500 with operator
+ * guidance rather than the opaque `OperationError` that some Web Crypto
+ * implementations throw on malformed keys.
+ */
+export declare class InvalidEncryptionKeyError extends Error {
+    constructor(reason: string);
+}
 /** Encrypt a field value using AES-256-GCM. */
 export declare function encryptField(value: string, keyHex: string): Promise<string>;
 /** Decrypt a field value encrypted with AES-256-GCM. */

package/dist/security/encrypted-fields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encrypted-fields.d.ts","sourceRoot":"","sources":["../../src/security/encrypted-fields.ts"],"names":[],"mappings":"AAIA,+CAA+C;AAC/C,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBjF;AAED,wDAAwD;AACxD,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAarF"}
+{"version":3,"file":"encrypted-fields.d.ts","sourceRoot":"","sources":["../../src/security/encrypted-fields.ts"],"names":[],"mappings":"AAQA;;;;;GAKG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,MAAM,EAAE,MAAM;CAQ3B;AAyBD,+CAA+C;AAC/C,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBjF;AAED,wDAAwD;AACxD,wBAAsB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAcrF"}

package/dist/security/encrypted-fields.js

@@ -1,8 +1,46 @@
 const ALGORITHM = 'AES-GCM';
 const IV_LENGTH = 12;
 const TAG_LENGTH = 128;
+const KEY_BYTES = 32; // AES-256 requires exactly 32 bytes
+const KEY_HEX_LENGTH = KEY_BYTES * 2;
+const HEX_RE = /^[0-9a-fA-F]+$/;
+/**
+ * Thrown for invalid `CMS_ENCRYPTION_KEY` shape. We use a named class so the
+ * caller (typically an API handler) can map it to a clear 500 with operator
+ * guidance rather than the opaque `OperationError` that some Web Crypto
+ * implementations throw on malformed keys.
+ */
+export class InvalidEncryptionKeyError extends Error {
+    constructor(reason) {
+        super(`[Actuate CMS] CMS_ENCRYPTION_KEY is invalid: ${reason}. ` +
+            `Generate a valid key with: ` +
+            `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`);
+        this.name = 'InvalidEncryptionKeyError';
+    }
+}
+/**
+ * Validate that `keyHex` is exactly 64 hex chars (32 bytes for AES-256).
+ *
+ * Without this guard, WebCrypto's `importKey` either throws an opaque
+ * `OperationError` (short keys), or in some non-spec runtimes silently
+ * truncates / pads — both produce ciphertext that the matching `decrypt`
+ * call can't reverse, surfaced to the user as a generic "decryption failed"
+ * weeks after the bad key was first deployed.
+ */
+function validateKey(keyHex) {
+    if (typeof keyHex !== 'string' || keyHex.length === 0) {
+        throw new InvalidEncryptionKeyError('key is empty or not a string');
+    }
+    if (keyHex.length !== KEY_HEX_LENGTH) {
+        throw new InvalidEncryptionKeyError(`key must be ${KEY_HEX_LENGTH} hex characters (${KEY_BYTES} bytes), got ${keyHex.length}`);
+    }
+    if (!HEX_RE.test(keyHex)) {
+        throw new InvalidEncryptionKeyError('key must contain only hex characters [0-9a-fA-F]');
+    }
+}
 /** Encrypt a field value using AES-256-GCM. */
 export async function encryptField(value, keyHex) {
+    validateKey(keyHex);
     const key = await importKey(keyHex);
     const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
     const encoded = new TextEncoder().encode(value);
@@ -14,6 +52,7 @@ export async function encryptField(value, keyHex) {
 }
 /** Decrypt a field value encrypted with AES-256-GCM. */
 export async function decryptField(encrypted, keyHex) {
+    validateKey(keyHex);
     const key = await importKey(keyHex);
     const data = hexToBuffer(encrypted);
     const iv = data.slice(0, IV_LENGTH);
@@ -33,10 +72,22 @@ function bufferToHex(buffer) {
         .map((b) => b.toString(16).padStart(2, '0'))
         .join('');
 }
+/**
+ * Decode a hex string to bytes. Caller is expected to have validated shape
+ * via `validateKey` for keys; this function tolerates already-validated input
+ * and rejects odd-length hex (which previously silently dropped trailing chars).
+ */
 function hexToBuffer(hex) {
+    if (hex.length % 2 !== 0) {
+        throw new Error('hex string must have an even number of characters');
+    }
     const bytes = new Uint8Array(hex.length / 2);
     for (let i = 0; i < hex.length; i += 2) {
-        bytes[i / 2] = parseInt(hex.slice(i, i + 2), 16);
+        const byte = parseInt(hex.slice(i, i + 2), 16);
+        if (Number.isNaN(byte)) {
+            throw new Error(`invalid hex character at offset ${i}`);
+        }
+        bytes[i / 2] = byte;
     }
     return bytes;
 }

package/dist/security/encrypted-fields.js.map

@@ -1 +1 @@
-{"version":3,"file":"encrypted-fields.js","sourceRoot":"","sources":["../../src/security/encrypted-fields.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"encrypted-fields.js","sourceRoot":"","sources":["../../src/security/encrypted-fields.ts"],"names":[],"mappings":"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"}

package/dist/security/ip-canon.d.ts

@@ -0,0 +1,71 @@
+/**
+ * IP canonicalization for SSRF defense.
+ *
+ * The previous regex-based approach in `webhook.ts` only matched the literal
+ * dotted-quad form. It missed every encoding that `getaddrinfo` (and therefore
+ * `fetch`) accepts:
+ *
+ *   - Decimal:        http://2130706433/        → 127.0.0.1
+ *   - Octal:          http://0177.0.0.1/        → 127.0.0.1
+ *   - Hex:            http://0x7f.0.0.1/        → 127.0.0.1
+ *   - Short-form:     http://127.1/             → 127.0.0.1
+ *   - IPv4-mapped v6: http://[::ffff:127.0.0.1] → 127.0.0.1
+ *   - IPv4-compat v6: http://[::127.0.0.1]      → 127.0.0.1
+ *
+ * This module canonicalizes any of those forms to a 4-octet IPv4 string (or
+ * a normalized 16-byte IPv6 address), then range-checks against a complete
+ * private/internal block list including AWS/GCP/Azure metadata endpoints and
+ * the carrier-grade NAT range.
+ */
+/**
+ * Result of {@link canonicalizeHostname}. There are exactly three valid
+ * shapes:
+ *
+ *  - **Valid IPv4 literal** — `isHostname=false`, `isValidIp=true`, `ipv4` set.
+ *  - **Valid IPv6 literal** — `isHostname=false`, `isValidIp=true`, `ipv6` set.
+ *  - **Hostname (DNS name)** — `isHostname=true`, `isValidIp=false`, neither
+ *    `ipv4` nor `ipv6` set.
+ *  - **Malformed IP literal** — `isHostname=false`, `isValidIp=false`, neither
+ *    IP field set. (Inputs that look like IP literals — e.g. contain `:` or
+ *    only digits and dots — but fail to parse cleanly.)
+ *
+ * SSRF gates MUST treat the malformed shape as "reject" rather than as
+ * "validated IP literal". Use `isValidIp` to distinguish the two `false`
+ * `isHostname` cases.
+ */
+export interface CanonicalizedHost {
+    /** Original hostname as it appeared in the URL. */
+    raw: string;
+    /** Canonical IPv4 dotted-quad string when the literal was IPv4 (in any form). */
+    ipv4?: string;
+    /** Canonical IPv6 hextet string when the literal was IPv6. */
+    ipv6?: string;
+    /** True when the input was a DNS name (not an IP literal in any form). */
+    isHostname: boolean;
+    /**
+     * True when the input parsed cleanly into a canonical IP address (`ipv4`
+     * or `ipv6` is set). False for both DNS hostnames and malformed IP-shaped
+     * strings. Callers performing a security check on the parsed IP MUST
+     * verify `isValidIp` before reading `ipv4` / `ipv6`.
+     */
+    isValidIp: boolean;
+}
+/**
+ * Canonicalize a URL hostname into either a normalized IP address or a
+ * passthrough hostname. Handles every IPv4 encoding accepted by `inet_aton`
+ * (decimal, octal, hex, short-form), IPv4-mapped IPv6, and bracketed IPv6.
+ */
+export declare function canonicalizeHostname(rawHostname: string): CanonicalizedHost;
+/**
+ * Returns the matching private/internal range when the canonicalized host is
+ * one, `null` when it's a safe public IP, or a "malformed" reason when the
+ * input claims to be an IP literal but didn't parse cleanly.
+ *
+ * Defense-in-depth: even if a caller forgets to gate on `isValidIp`, this
+ * function still fails closed on the malformed shape (`isHostname=false`
+ * with no `ipv4`/`ipv6`).
+ */
+export declare function isPrivateAddress(host: CanonicalizedHost): {
+    reason: string;
+} | null;
+//# sourceMappingURL=ip-canon.d.ts.map

package/dist/security/ip-canon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-canon.d.ts","sourceRoot":"","sources":["../../src/security/ip-canon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiCH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAA;IACnB;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAA;CACnB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,CAmC3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA4BnF"}