File size: 8,956 Bytes
311fa35 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 | import { createHmac, randomUUID } from "node:crypto";
import { lookup } from "node:dns/promises";
import { isIP } from "node:net";
import { VERSION } from "./version.js";
export type CallbackEvent = "job.completed" | "job.failed" | "job.cancelled";
export const CALLBACK_EVENTS: readonly CallbackEvent[] = [
"job.completed",
"job.failed",
"job.cancelled",
];
export interface CallbackConfig {
url: string;
/** HMAC-SHA256 signing secret. Never persisted to meta.json. */
secret?: string;
/** Restrict which events are delivered. Defaults to all events. */
events?: CallbackEvent[];
}
export interface CallbackPayload {
event: CallbackEvent;
jobId: string;
status: string;
topic?: string;
createdAt?: string;
completedAt?: string;
videoPath?: string;
runDir?: string;
error?: string;
timestamp: string;
[key: string]: unknown;
}
export interface CallbackDeliveryResult {
delivered: boolean;
attempts: number;
statusCode?: number;
error?: string;
}
export class UnsafeCallbackUrlError extends Error {
constructor(message: string) {
super(message);
this.name = "UnsafeCallbackUrlError";
}
}
export type CallbackAddressResolver = (hostname: string) => Promise<string[]>;
const MAX_CALLBACK_URL_LENGTH = 2048;
/** True for loopback, private, link-local, CGNAT, multicast, and non-routable addresses. */
export function isPrivateAddress(address: string): boolean {
const host = address.toLowerCase().replace(/^\[|\]$/g, "");
if (!host) return true;
if (host.startsWith("::ffff:")) {
return isPrivateIpv4(host.slice("::ffff:".length));
}
if (host.includes(":")) {
if (host === "::" || host === "::1") return true;
const first = Number.parseInt(host.split(":")[0] || "0", 16);
if (!Number.isFinite(first)) return true;
// fc00::/7 unique-local, fe80::/10 link-local, ff00::/8 multicast.
if ((first & 0xfe00) === 0xfc00) return true;
if ((first & 0xffc0) === 0xfe80) return true;
if ((first & 0xff00) === 0xff00) return true;
if (first === 0) return true;
return false;
}
return isPrivateIpv4(host);
}
function isPrivateIpv4(address: string): boolean {
const parts = address.split(".").map((part) => Number(part));
if (
parts.length !== 4 ||
parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255)
) {
// Fail closed for malformed addresses.
return true;
}
const [a, b] = parts as [number, number, number, number];
if (a === 0 || a === 10 || a === 127) return true; // this-network, private, loopback
if (a === 100 && b >= 64 && b <= 127) return true; // CGNAT 100.64/10
if (a === 169 && b === 254) return true; // link-local
if (a === 172 && b >= 16 && b <= 31) return true; // private 172.16/12
if (a === 192 && b === 168) return true; // private 192.168/16
if (a === 192 && b === 0) return true; // 192.0.0/24 + 192.0.2/24
if (a === 198 && (b === 18 || b === 19)) return true; // benchmarking
if (a === 198 && b === 51) return true; // documentation
if (a === 203 && b === 0) return true; // documentation
if (a >= 224) return true; // multicast + reserved
return false;
}
/**
* Validate a callback URL without doing DNS work. Used when a job is created
* so bad URLs fail fast; SSRF resolution happens again at delivery time.
*/
export function validateCallbackUrlSyntax(raw: string): URL {
if (typeof raw !== "string" || raw.trim().length === 0) {
throw new UnsafeCallbackUrlError("callbackUrl is required when callbacks are enabled");
}
if (raw.length > MAX_CALLBACK_URL_LENGTH) {
throw new UnsafeCallbackUrlError(
`callbackUrl must be ${MAX_CALLBACK_URL_LENGTH} characters or fewer`,
);
}
let url: URL;
try {
url = new URL(raw);
} catch {
throw new UnsafeCallbackUrlError("callbackUrl must be a valid absolute URL");
}
if (url.protocol !== "http:" && url.protocol !== "https:") {
throw new UnsafeCallbackUrlError("callbackUrl must use http or https");
}
if (url.username || url.password) {
throw new UnsafeCallbackUrlError("callbackUrl must not contain credentials");
}
return url;
}
/**
* Resolve a callback URL and reject it when it points at a private network.
* DNS rebinding is still theoretically possible between this check and the
* request; pair webhooks with a trusted receiver and do not expose the API
* publicly without authentication.
*/
export async function assertSafeCallbackUrl(
raw: string,
options: {
allowPrivate?: boolean;
resolve?: CallbackAddressResolver;
} = {},
): Promise<URL> {
const url = validateCallbackUrlSyntax(raw);
if (options.allowPrivate) return url;
const host = url.hostname.toLowerCase();
if (host === "localhost" || host.endsWith(".localhost")) {
throw new UnsafeCallbackUrlError("callbackUrl must not target localhost");
}
if (isIP(host)) {
if (isPrivateAddress(host)) {
throw new UnsafeCallbackUrlError("callbackUrl must not target a private address");
}
return url;
}
let addresses: string[];
try {
addresses = options.resolve
? await options.resolve(host)
: (await lookup(host, { all: true, verbatim: true })).map((entry) => entry.address);
} catch {
throw new UnsafeCallbackUrlError(`Could not resolve callback host: ${host}`);
}
if (addresses.length === 0) {
throw new UnsafeCallbackUrlError(`Could not resolve callback host: ${host}`);
}
if (addresses.some((address) => isPrivateAddress(address))) {
throw new UnsafeCallbackUrlError("callbackUrl must not target a private address");
}
return url;
}
/** HMAC-SHA256 over `${timestamp}.${rawBody}`. */
export function signCallbackPayload(secret: string, timestamp: string, rawBody: string): string {
return createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
}
export function callbackAllowsEvent(config: CallbackConfig, event: CallbackEvent): boolean {
if (!config.events || config.events.length === 0) return true;
return config.events.includes(event);
}
/**
* Deliver a signed webhook with bounded retries. Never throws: callback
* failures are reported to the caller and must not fail the render job.
*/
export async function deliverCallback(
config: CallbackConfig,
payload: CallbackPayload,
options: {
allowPrivate?: boolean;
fetchImpl?: typeof fetch;
resolve?: CallbackAddressResolver;
maxAttempts?: number;
timeoutMs?: number;
retryDelayMs?: number;
} = {},
): Promise<CallbackDeliveryResult> {
if (!callbackAllowsEvent(config, payload.event)) {
return { delivered: false, attempts: 0, error: "event not subscribed" };
}
const fetchImpl = options.fetchImpl ?? fetch;
const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
const timeoutMs = options.timeoutMs ?? 10_000;
const retryDelayMs = options.retryDelayMs ?? 1_000;
const rawBody = JSON.stringify(payload);
let lastStatus: number | undefined;
let lastError = "";
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
try {
const url = await assertSafeCallbackUrl(config.url, {
allowPrivate: options.allowPrivate,
resolve: options.resolve,
});
const timestamp = String(Math.floor(Date.now() / 1000));
const headers: Record<string, string> = {
"Content-Type": "application/json",
"User-Agent": `OpenReels/${VERSION}`,
"X-OpenReels-Event": payload.event,
"X-OpenReels-Job-Id": payload.jobId,
"X-OpenReels-Delivery": randomUUID(),
"X-OpenReels-Timestamp": timestamp,
};
if (config.secret) {
headers["X-OpenReels-Signature"] = `sha256=${signCallbackPayload(
config.secret,
timestamp,
rawBody,
)}`;
}
const response = await fetchImpl(url, {
method: "POST",
headers,
body: rawBody,
redirect: "manual",
signal: AbortSignal.timeout(timeoutMs),
});
lastStatus = response.status;
// Drain the body so sockets are released.
await response.text().catch(() => "");
if (response.status >= 200 && response.status < 300) {
return { delivered: true, attempts: attempt, statusCode: response.status };
}
lastError = `callback returned HTTP ${response.status}`;
} catch (err) {
lastError = err instanceof Error ? err.message : String(err);
if (err instanceof UnsafeCallbackUrlError) {
// Permanent configuration/security failure — do not retry.
return { delivered: false, attempts: attempt, error: lastError };
}
}
if (attempt < maxAttempts && retryDelayMs > 0) {
await new Promise((resolve) => setTimeout(resolve, retryDelayMs * attempt));
}
}
return {
delivered: false,
attempts: maxAttempts,
...(lastStatus !== undefined ? { statusCode: lastStatus } : {}),
error: lastError || "callback delivery failed",
};
}
|