n8nac 2.4.0 → 2.5.0

package/dist/core/services/tls-certificates.js

@@ -0,0 +1,329 @@
+import * as fs from 'fs';
+import { createRequire } from 'module';
+import * as path from 'path';
+import * as tls from 'tls';
+/**
+ * Additional trust anchors for outbound HTTPS.
+ *
+ * Node honours `NODE_EXTRA_CA_CERTS` and `--use-system-ca` when it builds the default
+ * TLS trust store, but only when the process is a stock Node build that is started with
+ * those settings. The VS Code extension host is neither: it is an Electron process
+ * (BoringSSL, no `NODE_EXTRA_CA_CERTS` support) that users cannot pass Node flags to.
+ * The same gap exists for anything reaching n8n through the global `fetch`
+ * (`@n8n-as-code/n8n-manager-core` health probes, project listing, credential REST calls),
+ * because `fetch` ignores `https.Agent` options entirely.
+ *
+ * So we read the certificates ourselves and append them to every secure context the
+ * process creates, which covers axios, `fetch`, `ws` and `http-proxy` in one place.
+ */
+const PEM_CERTIFICATE_PATTERN = /-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g;
+/** Read in addition to Node's own `NODE_EXTRA_CA_CERTS`; accepts several paths. */
+export const N8NAC_EXTRA_CA_CERTS_ENV = 'N8NAC_EXTRA_CA_CERTS';
+const patchedHosts = new WeakMap();
+let defaultSecureContextHost;
+/**
+ * The mutable `tls` module object.
+ *
+ * `import * as tls` yields a frozen module namespace, so the patch has to go through the
+ * CommonJS export object that `https`, `ws` and undici's `fetch` all read from.
+ */
+function getDefaultSecureContextHost() {
+    defaultSecureContextHost ??= createRequire(import.meta.url)('tls');
+    return defaultSecureContextHost;
+}
+/**
+ * Split a path list. Accepts the platform delimiter, commas and newlines so a single
+ * setting works whether it was copied from a shell variable or typed by hand.
+ */
+export function splitCertificatePathList(value) {
+    return value
+        .split(new RegExp(`[${escapeForCharacterClass(path.delimiter)},\\r\\n]`))
+        .map((entry) => entry.trim().replace(/^["']|["']$/g, ''))
+        .filter((entry) => entry.length > 0);
+}
+function escapeForCharacterClass(value) {
+    return value.replace(/[\\\]^-]/g, '\\$&');
+}
+/** Extract every PEM certificate block from a bundle, ignoring keys and comments. */
+export function extractPemCertificates(contents) {
+    return contents.match(PEM_CERTIFICATE_PATTERN) ?? [];
+}
+function readCertificateFile(filePath, resolution, label) {
+    let contents;
+    try {
+        contents = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (error) {
+        resolution.errors.push(`${label}: cannot read "${filePath}" (${error?.code || error?.message || error})`);
+        return;
+    }
+    const certificates = extractPemCertificates(contents);
+    if (!certificates.length) {
+        resolution.errors.push(`${label}: "${filePath}" does not contain any PEM certificate`);
+        return;
+    }
+    resolution.hasConfiguredAnchors = true;
+    addCertificates(resolution, certificates, `${label}: ${filePath}`);
+}
+function addCertificates(resolution, certificates, source) {
+    let added = 0;
+    for (const certificate of certificates) {
+        const normalized = certificate.trim();
+        if (!normalized || resolution.certificates.includes(normalized))
+            continue;
+        resolution.certificates.push(normalized);
+        added++;
+    }
+    if (added > 0) {
+        resolution.sources.push(`${source} (${added})`);
+    }
+}
+function readSystemCertificates(resolution) {
+    // Node 22.15+/24 only. Older hosts (and Electron) simply do not expose it, which is the
+    // expected state rather than a misconfiguration, so it is not reported as an error.
+    const getCACertificates = tls.getCACertificates;
+    if (typeof getCACertificates !== 'function') {
+        return;
+    }
+    try {
+        addCertificates(resolution, getCACertificates('system'), 'system trust store');
+    }
+    catch (error) {
+        resolution.errors.push(`system trust store: ${error?.message || error}`);
+    }
+}
+/**
+ * Collect the extra trust anchors from settings, `N8NAC_EXTRA_CA_CERTS`,
+ * `NODE_EXTRA_CA_CERTS` and — on request — the OS trust store.
+ */
+export function resolveExtraCaCertificates(options = {}) {
+    const env = options.env ?? process.env;
+    const baseDir = options.baseDir ?? process.cwd();
+    const resolution = {
+        certificates: [],
+        sources: [],
+        errors: [],
+        hasConfiguredAnchors: false,
+    };
+    const resolvePath = (candidate) => (path.isAbsolute(candidate) ? candidate : path.resolve(baseDir, candidate));
+    for (const candidate of options.caFiles ?? []) {
+        for (const filePath of splitCertificatePathList(candidate)) {
+            readCertificateFile(resolvePath(filePath), resolution, 'setting');
+        }
+    }
+    for (const filePath of splitCertificatePathList(env[N8NAC_EXTRA_CA_CERTS_ENV] ?? '')) {
+        readCertificateFile(resolvePath(filePath), resolution, N8NAC_EXTRA_CA_CERTS_ENV);
+    }
+    for (const filePath of splitCertificatePathList(env.NODE_EXTRA_CA_CERTS ?? '')) {
+        readCertificateFile(resolvePath(filePath), resolution, 'NODE_EXTRA_CA_CERTS');
+    }
+    if (options.useSystemCertificateAuthorities) {
+        readSystemCertificates(resolution);
+    }
+    return resolution;
+}
+/**
+ * Append the resolved certificates to every secure context created from now on.
+ *
+ * Idempotent: calling it again replaces the certificate set instead of stacking another
+ * wrapper, so it is safe to re-run whenever the configuration changes.
+ */
+export function installExtraCaCertificates(options = {}, host = getDefaultSecureContextHost()) {
+    const resolution = resolveExtraCaCertificates(options);
+    const existing = patchedHosts.get(host);
+    if (existing) {
+        existing.certificates = resolution.certificates;
+        return { ...resolution, installed: resolution.certificates.length > 0 };
+    }
+    if (!resolution.certificates.length) {
+        // Nothing to trust yet — leave the runtime untouched rather than wrapping it for nothing.
+        return { ...resolution, installed: false };
+    }
+    const state = {
+        original: host.createSecureContext,
+        certificates: resolution.certificates,
+    };
+    patchedHosts.set(host, state);
+    host.createSecureContext = (contextOptions) => {
+        const context = state.original.call(host, contextOptions);
+        const nativeContext = context.context;
+        if (typeof nativeContext?.addCACert !== 'function') {
+            return context;
+        }
+        for (const certificate of state.certificates) {
+            try {
+                nativeContext.addCACert(certificate);
+            }
+            catch {
+                // A malformed or duplicate anchor must not break the whole handshake.
+            }
+        }
+        return context;
+    };
+    return { ...resolution, installed: true };
+}
+/** Certificates currently appended by the installer, for diagnostics and tests. */
+export function getInstalledExtraCaCertificates(host = getDefaultSecureContextHost()) {
+    return [...(patchedHosts.get(host)?.certificates ?? [])];
+}
+/** Restore the untouched `createSecureContext`. Intended for tests. */
+export function uninstallExtraCaCertificates(host = getDefaultSecureContextHost()) {
+    const state = patchedHosts.get(host);
+    if (!state)
+        return;
+    host.createSecureContext = state.original;
+    patchedHosts.delete(host);
+}
+/** Set to 1/true/yes to skip certificate verification outright. Last resort, see below. */
+export const N8NAC_INSECURE_TLS_ENV = 'N8NAC_INSECURE_TLS';
+const PRIVATE_HOSTNAME_SUFFIXES = ['.localhost', '.local', '.internal', '.home.arpa'];
+/** Pull the host out of a URL by hand, for the inputs `URL` refuses (an IPv6 zone id). */
+function stripUrlDecorations(value) {
+    const bare = value
+        .replace(/^[a-z][a-z0-9+.-]*:\/\//i, '')
+        .replace(/^[^@/]*@/, '')
+        .replace(/[/?#].*$/, '');
+    const bracketed = /^\[([^\]]*)\]/.exec(bare);
+    if (bracketed)
+        return bracketed[1];
+    // A bare IPv6 literal holds several colons; a `host:port` pair holds exactly one.
+    return bare.split(':').length === 2 ? bare.replace(/:\d*$/, '') : bare;
+}
+/** Strip the scheme, port, brackets, IPv6 zone id and trailing dot from a configured host. */
+function normalizeHostname(hostOrUrl) {
+    const value = hostOrUrl.trim();
+    if (!value)
+        return '';
+    let hostname;
+    try {
+        hostname = new URL(value.includes('://') ? value : `https://${value}`).hostname;
+    }
+    catch {
+        hostname = stripUrlDecorations(value);
+    }
+    return hostname
+        .toLowerCase()
+        .replace(/^\[|\]$/g, '')
+        .replace(/%.*$/, '')
+        .replace(/\.$/, '');
+}
+function isPrivateIpv4(hostname) {
+    const octets = hostname.split('.').map(Number);
+    if (octets.length !== 4 || octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)) {
+        return false;
+    }
+    const [first, second] = octets;
+    if (first === 0)
+        return true; // "this host on this network"
+    if (first === 10)
+        return true; // RFC 1918
+    if (first === 127)
+        return true; // loopback
+    if (first === 169 && second === 254)
+        return true; // link-local
+    if (first === 172 && second >= 16 && second <= 31)
+        return true; // RFC 1918
+    if (first === 192 && second === 168)
+        return true; // RFC 1918
+    if (first === 100 && second >= 64 && second <= 127)
+        return true; // CGNAT, incl. Tailscale
+    return false;
+}
+function isPrivateIpv6(hostname) {
+    if (hostname === '::1' || hostname === '::')
+        return true;
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/.exec(hostname);
+    if (mapped)
+        return isPrivateIpv4(mapped[1]);
+    // `URL` rewrites an IPv4-mapped address to its hex form (`::ffff:c0a8:10a`), so the
+    // embedded IPv4 address has to be read back out of the last two groups.
+    const mappedHex = /^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(hostname);
+    if (mappedHex) {
+        const high = parseInt(mappedHex[1], 16);
+        const low = parseInt(mappedHex[2], 16);
+        return isPrivateIpv4([high >> 8, high & 0xff, low >> 8, low & 0xff].join('.'));
+    }
+    if (/^f[cd][0-9a-f]{2}:/.test(hostname))
+        return true; // fc00::/7 unique local
+    if (/^fe[89ab][0-9a-f]:/.test(hostname))
+        return true; // fe80::/10 link-local
+    return false;
+}
+/**
+ * `true` when the host can only be reached from this machine or a private network.
+ *
+ * These are precisely the destinations a public CA will not issue a certificate for, so they
+ * are the ones where a self-signed certificate is the normal setup rather than an attack.
+ * Anything else — a real domain name — is treated as public, which is the safe default: an
+ * unrecognised host fails closed into verification.
+ */
+export function isPrivateNetworkHost(hostOrUrl) {
+    const hostname = normalizeHostname(hostOrUrl);
+    if (!hostname)
+        return false;
+    if (hostname === 'localhost')
+        return true;
+    if (PRIVATE_HOSTNAME_SUFFIXES.some((suffix) => hostname.endsWith(suffix)))
+        return true;
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(hostname))
+        return isPrivateIpv4(hostname);
+    if (hostname.includes(':'))
+        return isPrivateIpv6(hostname);
+    // A single-label name ("n8n-box") is an intranet name: it has no public DNS entry and no
+    // public CA will certify it.
+    return !hostname.includes('.');
+}
+/**
+ * Whether the server certificate has to verify for this destination.
+ *
+ * Verification is the default. It is relaxed only where the historical zero-configuration
+ * behaviour is actually needed — a private or loopback address, which cannot hold a publicly
+ * trusted certificate — and only while the user has not configured any anchor of their own.
+ * Configuring an anchor still means "verify everywhere", so a private host does not become a
+ * hole for someone who did set the certificates up.
+ *
+ * The remaining case, a self-signed certificate on a public host name, has to opt out through
+ * {@link N8NAC_INSECURE_TLS_ENV}, because it is indistinguishable from an interception.
+ */
+export function shouldVerifyServerCertificate(policy) {
+    const env = policy.env ?? process.env;
+    if (/^(1|true|yes)$/i.test((env[N8NAC_INSECURE_TLS_ENV] ?? '').trim()))
+        return false;
+    if (policy.hasConfiguredAnchors)
+        return true;
+    return !isPrivateNetworkHost(policy.host);
+}
+/** `true` when the error is a TLS trust failure rather than a transport or HTTP error. */
+export function isCertificateTrustError(error) {
+    const code = typeof error?.code === 'string' ? error.code : '';
+    if (code.startsWith('UNABLE_TO_') || code.startsWith('SELF_SIGNED') || code.startsWith('DEPTH_ZERO_')) {
+        return true;
+    }
+    if (code === 'CERT_HAS_EXPIRED' || code === 'ERR_TLS_CERT_ALTNAME_INVALID' || code === 'CERT_SIGNATURE_FAILURE') {
+        return true;
+    }
+    if (error?.cause && error.cause !== error && isCertificateTrustError(error.cause)) {
+        return true;
+    }
+    const message = String(error?.message ?? error ?? '');
+    return /unable to (get|verify)|self[- ]signed certificate|certificate has expired|CERT_/i.test(message);
+}
+/** Guidance appended to connection errors caused by an untrusted certificate. */
+export const CERTIFICATE_TRUST_HINT = 'The certificate is not trusted by this process. Point "n8n.tls.certificateAuthorities" '
+    + '(or the NODE_EXTRA_CA_CERTS environment variable) at the PEM bundle holding your root CA, then retry. '
+    + 'The VS Code extension host cannot read Node\'s --use-system-ca flag, so the setting is the reliable path there.';
+/**
+ * The same guidance for someone running `n8nac` in a terminal.
+ *
+ * Deliberately not {@link CERTIFICATE_TRUST_HINT}: that one points at the
+ * `n8n.tls.certificateAuthorities` VS Code setting and explains extension-host behaviour, and
+ * neither exists on the command line — following it would send a CLI user to a setting they
+ * have no way to set. The environment variables are the CLI's actual levers, and
+ * `N8NAC_EXTRA_CA_CERTS` is named first because it accepts several paths while Node's own
+ * variable takes exactly one.
+ */
+export const CERTIFICATE_TRUST_HINT_CLI = 'The certificate presented by the n8n instance is not trusted by this process. Point '
+    + `${N8NAC_EXTRA_CA_CERTS_ENV} (accepts several paths) or NODE_EXTRA_CA_CERTS at the PEM bundle `
+    + 'holding your root CA, then retry. If the instance is genuinely only reachable over a '
+    + `self-signed certificate and you accept the risk, set ${N8NAC_INSECURE_TLS_ENV}=1 to skip verification.`;
+//# sourceMappingURL=tls-certificates.js.map

package/dist/core/services/tls-certificates.js.map

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

package/dist/core/services/workflow-path-utils.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Rewrites a path to POSIX separators.
+ *
+ * Workflow paths are stored POSIX-style in `.n8n-state.json` so a repository
+ * checked out on Windows and on Linux produces the same state file.
+ */
+export declare function toPosixRelativePath(value: string): string;
+/**
+ * Normalises a workflow path relative to the workflows directory and rejects
+ * anything that could escape it.
+ *
+ * @param value Path as written by a user, a state file, or the CLI.
+ * @returns The normalised POSIX-relative path.
+ * @throws If the path is empty, absolute, climbs above the root, or contains a
+ * control character — all of which would let a crafted state file or filename
+ * write outside the sync scope.
+ */
+export declare function normalizeWorkflowRelativePath(value: string): string;
+/**
+ * Resolves a workflow-relative path against the workflows directory.
+ *
+ * Validates before joining, so this is the only sanctioned way to turn a stored
+ * filename into an absolute path.
+ *
+ * @param root Absolute path of the workflows directory.
+ * @param relativePath Workflow-relative path (nested paths allowed).
+ */
+export declare function workflowRelativePathToAbsolute(root: string, relativePath: string): string;
+/**
+ * Inverse of {@link workflowRelativePathToAbsolute}: expresses an absolute path
+ * as a validated workflow-relative one.
+ *
+ * @throws If the file lies outside `root`.
+ */
+export declare function relativePathFromAbsolute(root: string, absolutePath: string): string;
+/**
+ * Creates the parent directory of `filePath` if it is missing.
+ *
+ * Needed since workflows can live in nested folders: the first pull or push of
+ * `Reports/Weekly/summary.workflow.ts` has to create `Reports/Weekly` first.
+ */
+export declare function ensureParentDirectory(filePath: string): void;
+/**
+ * Lists every `*.workflow.ts` file under `root`, recursively.
+ *
+ * Dot-prefixed entries are skipped, so `.n8n-state.json` and `.git` never show
+ * up. Results are workflow-relative, normalised, and sorted for deterministic
+ * ordering across platforms.
+ *
+ * Synchronous by design — it runs inside the tracker's synchronous scan path.
+ * Fine for the hundreds of workflows a project realistically holds.
+ *
+ * @returns Sorted workflow-relative paths; empty when `root` does not exist.
+ */
+export declare function listWorkflowFilesRecursive(root: string): string[];
+//# sourceMappingURL=workflow-path-utils.d.ts.map

package/dist/core/services/workflow-path-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-path-utils.d.ts","sourceRoot":"","sources":["../../../src/core/services/workflow-path-utils.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;;;GASG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAanE;AAED;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAGnF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAmBjE"}

package/dist/core/services/workflow-path-utils.js

@@ -0,0 +1,102 @@
+import fs from 'fs';
+import path from 'path';
+/**
+ * Rewrites a path to POSIX separators.
+ *
+ * Workflow paths are stored POSIX-style in `.n8n-state.json` so a repository
+ * checked out on Windows and on Linux produces the same state file.
+ */
+export function toPosixRelativePath(value) {
+    return value.split(path.sep).join('/').replace(/\\/g, '/');
+}
+/**
+ * Normalises a workflow path relative to the workflows directory and rejects
+ * anything that could escape it.
+ *
+ * @param value Path as written by a user, a state file, or the CLI.
+ * @returns The normalised POSIX-relative path.
+ * @throws If the path is empty, absolute, climbs above the root, or contains a
+ * control character — all of which would let a crafted state file or filename
+ * write outside the sync scope.
+ */
+export function normalizeWorkflowRelativePath(value) {
+    const normalized = path.posix.normalize(toPosixRelativePath(value).trim());
+    if (!normalized || normalized === '.') {
+        throw new Error('Workflow path must not be empty');
+    }
+    if (normalized.startsWith('../') || normalized === '..' || path.posix.isAbsolute(normalized)) {
+        throw new Error(`Workflow path escapes the sync scope: ${value}`);
+    }
+    const parts = normalized.split('/');
+    if (parts.some((part) => !part || part === '.' || part === '..' || /[\u0000-\u001f\u007f]/.test(part))) {
+        throw new Error(`Workflow path contains an unsafe segment: ${value}`);
+    }
+    return normalized;
+}
+/**
+ * Resolves a workflow-relative path against the workflows directory.
+ *
+ * Validates before joining, so this is the only sanctioned way to turn a stored
+ * filename into an absolute path.
+ *
+ * @param root Absolute path of the workflows directory.
+ * @param relativePath Workflow-relative path (nested paths allowed).
+ */
+export function workflowRelativePathToAbsolute(root, relativePath) {
+    const safeRelativePath = normalizeWorkflowRelativePath(relativePath);
+    return path.join(root, ...safeRelativePath.split('/'));
+}
+/**
+ * Inverse of {@link workflowRelativePathToAbsolute}: expresses an absolute path
+ * as a validated workflow-relative one.
+ *
+ * @throws If the file lies outside `root`.
+ */
+export function relativePathFromAbsolute(root, absolutePath) {
+    const relative = path.relative(root, absolutePath);
+    return normalizeWorkflowRelativePath(toPosixRelativePath(relative));
+}
+/**
+ * Creates the parent directory of `filePath` if it is missing.
+ *
+ * Needed since workflows can live in nested folders: the first pull or push of
+ * `Reports/Weekly/summary.workflow.ts` has to create `Reports/Weekly` first.
+ */
+export function ensureParentDirectory(filePath) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+/**
+ * Lists every `*.workflow.ts` file under `root`, recursively.
+ *
+ * Dot-prefixed entries are skipped, so `.n8n-state.json` and `.git` never show
+ * up. Results are workflow-relative, normalised, and sorted for deterministic
+ * ordering across platforms.
+ *
+ * Synchronous by design — it runs inside the tracker's synchronous scan path.
+ * Fine for the hundreds of workflows a project realistically holds.
+ *
+ * @returns Sorted workflow-relative paths; empty when `root` does not exist.
+ */
+export function listWorkflowFilesRecursive(root) {
+    const results = [];
+    const visit = (dir, relativeDir = '') => {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const childRelative = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+            const childAbsolute = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                visit(childAbsolute, childRelative);
+                continue;
+            }
+            if (entry.isFile() && entry.name.endsWith('.workflow.ts')) {
+                results.push(normalizeWorkflowRelativePath(childRelative));
+            }
+        }
+    };
+    if (fs.existsSync(root))
+        visit(root);
+    return results.sort();
+}
+//# sourceMappingURL=workflow-path-utils.js.map

package/dist/core/services/workflow-path-utils.js.map

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

package/dist/core/services/workflow-state-tracker.d.ts

@@ -20,6 +20,8 @@ export declare class WorkflowStateTracker extends EventEmitter {
     private ignoredTags;
     private projectId;
     private stateFilePath;
+    private folderSync;
+    private warnedFolderMetadataUnavailable;
     private isConnected;
     /** True during the first refreshRemoteState() call — suppresses status broadcasts */
     private isInitialRemoteLoad;
@@ -36,11 +38,14 @@ export declare class WorkflowStateTracker extends EventEmitter {
     private remoteActive;
     /** Remote archived flag per workflow (populated by refreshRemoteState / updateSingleRemoteState). */
     private remoteArchived;
+    private remoteParentFolderIds;
+    private remoteFolderPaths;
     constructor(client: N8nApiClient, options: {
         directory: string;
         syncInactive: boolean;
         ignoredTags: string[];
         projectId: string;
+        folderSync?: boolean;
     });
     getDirectory(): string;
     getFilenameForId(id: string): string | undefined;
@@ -89,6 +94,22 @@ export declare class WorkflowStateTracker extends EventEmitter {
     calculateStatus(filename: string, workflowId?: string): WorkflowSyncStatus;
     private shouldIgnore;
     private safeName;
+    /**
+     * Builds the resolver that turns a remote workflow's folder into local path
+     * segments — when n8n tells us what that folder is.
+     *
+     * As of n8n 2.32 it does not: `parentFolderId` is declared `writeOnly` in the
+     * public API spec, the read handlers never load the `parentFolder` relation,
+     * and no endpoint maps workflows to folders. This holds on every edition,
+     * Enterprise included, so pull lays workflows out flat and this returns null.
+     *
+     * The detection is deliberately based on the payload rather than a version
+     * check: the day a workflow read carries folder fields, nested pulls start
+     * working with no change here.
+     */
+    private createFolderResolver;
+    private warnFolderMetadataUnavailable;
+    private buildRelativeFilename;
     /**
      * Find local file that contains a specific workflow ID
      * Used when we have an ID but no filename mapping yet (e.g., after file rename)
@@ -115,6 +136,41 @@ export declare class WorkflowStateTracker extends EventEmitter {
         includeArchived?: boolean;
         onlyArchived?: boolean;
     }): Promise<IWorkflowStatus[]>;
+    /**
+     * Cheap drift computation for the lightweight `list` path.
+     *
+     * Single source of truth (SSOT) for the "did either side change since last sync?"
+     * question when a remote hash is not yet cached (i.e. before `n8nac fetch <id>`
+     * runs the expensive per-workflow hash roundtrip).
+     *
+     * Returns `undefined` when there is no reference state for the workflow
+     * (never pulled / first sync), so consumers can distinguish "no drift known"
+     * from "drift checked and nothing changed". Within the returned object each
+     * axis is likewise `undefined` when its input is missing, so an absent axis
+     * reads as "unknown" and never as "unchanged".
+     *
+     * Cost: O(1) Map lookups, one string compare and one timestamp parse. No AST,
+     * no I/O, no extra API calls.
+     * The data sources are already populated by the existing lightweight refresh:
+     *   - `localHashes[filename]`  - populated by `refreshLocalState`
+     *   - `state.workflows[id]`    - read from `.n8n-state.json`
+     *   - `remoteTimestamp`        - returned by `/api/v1/workflows` (now cached by
+     *                                `refreshRemoteState` into `remoteTimestamps`)
+     */
+    private computeDrift;
+    /**
+     * True when the remote `updatedAt` is strictly newer than the recorded `lastSyncedAt`.
+     *
+     * `lastSyncedAt` is normally a verbatim copy of the remote `updatedAt` (see
+     * `updateWorkflowState`), so both sides usually share the same representation and
+     * equality means "in sync". They can still diverge in format — the fallback in
+     * `updateWorkflowState` writes a client-side `new Date().toISOString()` when the API
+     * response carried no `updatedAt`, and n8n instances differ in how they serialise
+     * timestamps. A lexical compare across two formats misreports silently (`' '` < `'T'`
+     * makes a space-separated timestamp always look older), so compare parsed instants,
+     * consistent with the existing remote-change guard in `sync-engine.ts`.
+     */
+    private isNewerThan;
     /**
      * Get list of local workflow filenames (just checks file system, no parsing)
      */

package/dist/core/services/workflow-state-tracker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-state-tracker.d.ts","sourceRoot":"","sources":["../../../src/core/services/workflow-state-tracker.ts"],"names":[],"mappings":"AAEA,OAAO,YAAY,MAAM,QAAQ,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAGnD,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AA8B7E;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;IAClD,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAU;IAC9B,OAAO,CAAC,WAAW,CAAW;IAC9B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,WAAW,CAAiB;IACpC,qFAAqF;IACrF,OAAO,CAAC,mBAAmB,CAAkB;IAG7C,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,YAAY,CAAkC;IACtD,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,WAAW,CAAkC;IACrD,OAAO,CAAC,iBAAiB,CAA8C;IACvE,OAAO,CAAC,SAAS,CAA0B;IAG3C,OAAO,CAAC,gBAAgB,CAAkC;IAC1D,4FAA4F;IAC5F,OAAO,CAAC,WAAW,CAAkC;IACrD,mGAAmG;IACnG,OAAO,CAAC,YAAY,CAAmC;IACvD,qGAAqG;IACrG,OAAO,CAAC,cAAc,CAAmC;gBAGrD,MAAM,EAAE,YAAY,EACpB,OAAO,EAAE;QACL,SAAS,EAAE,MAAM,CAAC;QAClB,YAAY,EAAE,OAAO,CAAC;QACtB,WAAW,EAAE,MAAM,EAAE,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC;KACrB;IAcE,YAAY,IAAI,MAAM;IAItB,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIhD,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAIxD,iBAAiB;IAmJ9B;;;;;;;;OAQG;IACU,kBAAkB;IA4H/B;;;OAGG;IACU,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmDtF;;;OAGG;YACW,mBAAmB;IAUjC;;;OAGG;IACU,mBAAmB,CAAC,EAAE,EAAE,MAAM;IAmB3C;;;OAGG;IACH,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,wBAAwB;IAoBhC;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,eAAe;IAyBhB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,kBAAkB;IAgDjF,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,QAAQ;IA6DhB;;;OAGG;IACH,OAAO,CAAC,wBAAwB;IAiBhC,OAAO,CAAC,YAAY;YAyDN,gBAAgB;IAcvB,cAAc;IAIrB;;;OAGG;IACI,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;IAIjD;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAS1B;;;OAGG;IACU,kBAAkB,CAAC,OAAO,CAAC,EAAE;QACtC,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,YAAY,CAAC,EAAE,OAAO,CAAC;KAC1B,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;IAsF9B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IAepB,eAAe,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;IA0G1D;;OAEG;IACI,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAK9D;;OAEG;IACI,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAKhE;;;OAGG;IACI,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5D;;OAEG;IACI,qBAAqB,IAAI,MAAM,EAAE;IAKxC;;;;OAIG;IACU,eAAe,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAkCpD;;OAEG;IACU,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA6C1E;;;OAGG;IACU,uBAAuB,CAAC,QAAQ,EAAE,SAAS;CAqD3D"}
+{"version":3,"file":"workflow-state-tracker.d.ts","sourceRoot":"","sources":["../../../src/core/services/workflow-state-tracker.ts"],"names":[],"mappings":"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"}