@still-running/health-check 1.0.0

package/dist/core/model.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Platform-neutral workflow model.
+ *
+ * Every adapter (n8n, Make, and whatever comes next) produces this shape and
+ * nothing else. Every check consumes this shape and nothing else. No check may
+ * import an adapter, and no check may branch on `platform` except to word a
+ * message. That rule is the whole architecture constraint: adding platform
+ * three is one new file in adapters/, zero changes in core/checks/.
+ */
+export type Platform = 'n8n' | 'make';
+export type NodeRole = 'trigger' | 'write' | 'read' | 'gate' | 'transform' | 'loop' | 'alert' | 'error-handler' | 'note' | 'other';
+export type WriteKind = 'append' | 'create' | 'update' | 'upsert' | 'delete' | 'send' | 'unknown';
+export type AuthKind = 'oauth2' | 'api-key' | 'basic' | 'service-account' | 'unknown';
+export interface CredentialRef {
+    /** Raw platform identifier, e.g. 'googleSheetsOAuth2Api' or 'account:google'. */
+    rawType: string;
+    /** Provider id resolved against the provider table, e.g. 'google'. null = unknown. */
+    providerId: string | null;
+    authKind: AuthKind;
+    /** The user's own label for the connection, if the export carries one. */
+    label?: string;
+}
+/**
+ * Why a node might hand nothing to the step after it. This is the heart of the
+ * zero-write check: `null` means the node always emits something.
+ */
+export interface ZeroEmit {
+    /** Plain-language cause, shown to the user verbatim. */
+    cause: string;
+    /**
+     * 'structural'  - the shape guarantees it can emit zero (a filter, a search)
+     * 'possible'    - depends on code we cannot read (a Code node, an expression)
+     */
+    certainty: 'structural' | 'possible';
+}
+export interface WorkflowNode {
+    id: string;
+    label: string;
+    /** Raw platform type string, kept for messages and for debugging. */
+    platformType: string;
+    role: NodeRole;
+    writeKind?: WriteKind;
+    /** What the write lands in, when we can name it: 'Google Sheets', 'Airtable'. */
+    writeTarget?: string;
+    zeroEmit: ZeroEmit | null;
+    credentials: CredentialRef[];
+    errorHandling: {
+        /** An error branch or error route leaves this node. */
+        hasErrorBranch: boolean;
+        retries: boolean;
+        continueOnFail: boolean;
+        /** n8n: forces an empty item downstream instead of stopping. */
+        alwaysOutputData: boolean;
+    };
+    disabled: boolean;
+}
+export interface WorkflowEdge {
+    from: string;
+    to: string;
+    /** 'main' | 'error' | a branch label such as 'false' or a Make route filter name. */
+    channel: string;
+    /**
+     * A condition sitting on this edge that can stop everything downstream.
+     * Make puts filters on the link; n8n puts them in nodes. Both normalise here.
+     */
+    gate: {
+        label: string;
+        cause: string;
+    } | null;
+}
+export interface Cadence {
+    kind: 'schedule' | 'event' | 'manual' | 'unknown';
+    /** Human text: 'every 15 minutes', 'on webhook call'. */
+    description: string;
+    /** Seconds between expected runs, when the export states it. */
+    intervalSeconds: number | null;
+    /**
+     * True when the export tells us how often this SHOULD run. If false, nobody
+     * can tell the difference between idle and dead.
+     */
+    expectedIntervalKnown: boolean;
+}
+export interface WorkflowErrorPolicy {
+    /** A workflow-level handler: n8n settings.errorWorkflow, or an Error Trigger. */
+    workflowLevelHandler: boolean;
+    /** Make: metadata.scenario.dlq — are failed runs even stored? null = unknown. */
+    storesFailedRuns: boolean | null;
+    maxErrors: number | null;
+    notes: string[];
+}
+export interface Workflow {
+    platform: Platform;
+    name: string;
+    nodes: WorkflowNode[];
+    edges: WorkflowEdge[];
+    triggerIds: string[];
+    cadence: Cadence;
+    errorPolicy: WorkflowErrorPolicy;
+    /** Adapter-level caveats, e.g. 'this export carries no connection data'. */
+    parseNotes: string[];
+}
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export interface Finding {
+    checkId: 'zero-write' | 'credential-expiry' | 'no-cadence' | 'error-handling';
+    severity: Severity;
+    /** The node this is about. Findings always name a node — no vague advice. */
+    nodeId: string | null;
+    nodeLabel: string | null;
+    title: string;
+    /** What happens if this goes quiet. The spec's requirement, not decoration. */
+    ifItGoesQuiet: string;
+    detail: string;
+    /** Only for things we cannot know from static JSON. Keeps us honest. */
+    howToCheck?: string;
+    sources?: string[];
+}
+export interface Protection {
+    kind: 'guarded-write' | 'error-handler' | 'known-cadence' | 'stores-failed-runs' | 'alert-branch' | 'retries';
+    nodeId: string | null;
+    nodeLabel: string | null;
+    title: string;
+    detail: string;
+}
+export interface AnalysisResult {
+    platform: Platform;
+    workflowName: string;
+    nodeCount: number;
+    findings: Finding[];
+    /** What is holding it together. Shown when little or nothing is wrong. */
+    protections: Protection[];
+    parseNotes: string[];
+    /** Counters only. These three numbers are the Phase E scoreboard. */
+    stats: {
+        writeNodes: number;
+        oauthCredentials: number;
+        triggers: number;
+        /** Credentials that do not expire on a clock. A zero here is information. */
+        staticKeyCredentials: number;
+    };
+}
+export declare const SEVERITY_ORDER: Record<Severity, number>;

package/dist/core/model.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Platform-neutral workflow model.
+ *
+ * Every adapter (n8n, Make, and whatever comes next) produces this shape and
+ * nothing else. Every check consumes this shape and nothing else. No check may
+ * import an adapter, and no check may branch on `platform` except to word a
+ * message. That rule is the whole architecture constraint: adding platform
+ * three is one new file in adapters/, zero changes in core/checks/.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEVERITY_ORDER = void 0;
+exports.SEVERITY_ORDER = {
+    critical: 0,
+    high: 1,
+    medium: 2,
+    low: 3,
+    info: 4,
+};

package/dist/core/providers.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Provider expiry table.
+ *
+ * This is a DATA ASSET, not a switch statement. It is the seed of the paid
+ * product: the free tool reads it to say "this could expire", the paid product
+ * reads the same table plus a live connection to say "this expires Tuesday".
+ *
+ * Rules for editing this file:
+ *  1. Every `window` and every `condition` needs a `sources` URL. No folklore.
+ *  2. If we cannot know the condition from a pasted JSON, say so in `certainty:
+ *     'conditional'` and give `howToCheck`. Never predict what we cannot see.
+ *  3. Adding a provider must never require touching a check.
+ */
+import type { AuthKind } from './model.js';
+export interface ExpiryRule {
+    /** The situation in which this window applies, in plain words. */
+    condition: string;
+    /** 'certain'     - true for every connection of this type.
+     *  'conditional' - depends on something not visible in the export. */
+    certainty: 'certain' | 'conditional';
+    /** e.g. '7 days', '60 days', 'never'. */
+    window: string;
+    detail: string;
+    /** How the reader confirms it themselves, in under a minute. */
+    howToCheck?: string;
+}
+export interface Provider {
+    id: string;
+    displayName: string;
+    /** Substring matchers against the raw credential type, lower-cased. */
+    match: {
+        n8n: string[];
+        make: string[];
+    };
+    defaultAuthKind: AuthKind;
+    /** Can the platform silently refresh this without a human? */
+    autoRefreshable: boolean;
+    rules: ExpiryRule[];
+    sources: string[];
+    /** Complaint Mine Log row numbers backing this entry. Evidence, not vibes. */
+    complaintLogRows?: number[];
+}
+export declare const PROVIDERS: Provider[];
+/** Credential types that never expire on a clock — they get revoked instead. */
+export declare const STATIC_KEY_HINTS: string[];
+export declare function resolveProvider(rawType: string, platform: 'n8n' | 'make'): Provider | null;
+/** Best-effort auth kind when no provider matches. */
+export declare function guessAuthKind(rawType: string): AuthKind;

package/dist/core/providers.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Provider expiry table.
+ *
+ * This is a DATA ASSET, not a switch statement. It is the seed of the paid
+ * product: the free tool reads it to say "this could expire", the paid product
+ * reads the same table plus a live connection to say "this expires Tuesday".
+ *
+ * Rules for editing this file:
+ *  1. Every `window` and every `condition` needs a `sources` URL. No folklore.
+ *  2. If we cannot know the condition from a pasted JSON, say so in `certainty:
+ *     'conditional'` and give `howToCheck`. Never predict what we cannot see.
+ *  3. Adding a provider must never require touching a check.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STATIC_KEY_HINTS = exports.PROVIDERS = void 0;
+exports.resolveProvider = resolveProvider;
+exports.guessAuthKind = guessAuthKind;
+exports.PROVIDERS = [
+    {
+        id: 'google',
+        displayName: 'Google',
+        match: {
+            n8n: [
+                'googlesheetsoauth2',
+                'googledriveoauth2',
+                'gmailoauth2',
+                'googlecalendaroauth2',
+                'googledocsoauth2',
+                'googleoauth2',
+                'gsuiteadminoauth2',
+                'googlebigqueryoauth2',
+                'googleanalyticsoauth2',
+            ],
+            make: ['account:google', 'google'],
+        },
+        defaultAuthKind: 'oauth2',
+        autoRefreshable: true,
+        rules: [
+            {
+                condition: 'The Google Cloud project behind this connection has its OAuth consent screen set to "Testing" with an External user type',
+                certainty: 'conditional',
+                window: '7 days',
+                detail: 'Google issues a refresh token that expires 7 days after consent. When it dies the platform gets invalid_grant, the trigger stops firing, and nothing throws a run-level error because there is no run.',
+                howToCheck: 'Google Cloud Console -> APIs & Services -> OAuth consent screen. If Publishing status says "Testing", this connection dies every 7 days. If it says "In production", it does not.',
+            },
+            {
+                condition: 'The consent screen is published to production and verified',
+                certainty: 'conditional',
+                window: 'indefinite, with five exceptions',
+                detail: 'Effectively permanent unless: the token goes unused for six months, the user revokes access, the user changes their password while Gmail scopes are granted, the per-user token cap is exceeded, or the app loses verification for sensitive scopes.',
+                howToCheck: 'The six-month rule matters here: a workflow that stops running also stops refreshing, so a quiet workflow eventually becomes a dead credential.',
+            },
+        ],
+        sources: [
+            'https://developers.google.com/identity/protocols/oauth2',
+            'https://support.google.com/cloud/answer/15549945',
+        ],
+        complaintLogRows: [9, 11, 12, 40, 41],
+    },
+    {
+        id: 'microsoft',
+        displayName: 'Microsoft',
+        match: {
+            n8n: [
+                'microsoftoauth2',
+                'microsoftoutlookoauth2',
+                'microsoftexceloauth2',
+                'microsoftonedriveoauth2',
+                'microsoftsharepointoauth2',
+                'microsoftteamsoauth2',
+                'microsoftgraphsecurityoauth2',
+                'azure',
+            ],
+            make: ['account:microsoft', 'microsoft', 'office365'],
+        },
+        defaultAuthKind: 'oauth2',
+        autoRefreshable: true,
+        rules: [
+            {
+                condition: 'Normal case — the workflow runs at least every 90 days',
+                certainty: 'certain',
+                window: 'effectively indefinite',
+                detail: 'Microsoft refresh tokens default to a 90-day inactivity limit and replace themselves every time they are used. A workflow that runs daily keeps resetting the clock, so this is lower risk than Google.',
+            },
+            {
+                condition: 'The workflow stops running for 90 days',
+                certainty: 'certain',
+                window: '90 days of inactivity',
+                detail: 'The refresh token expires from disuse. Note the trap: a workflow that already went quiet for another reason quietly becomes unrecoverable too, so a short outage turns into a manual re-auth.',
+            },
+            {
+                condition: 'The tenant applies a Conditional Access sign-in frequency policy',
+                certainty: 'conditional',
+                window: 'whatever the policy says',
+                detail: 'Since January 2021 refresh lifetimes are no longer configurable through token lifetime policies, but Conditional Access sign-in frequency still forces re-authentication on a schedule the client cannot see.',
+                howToCheck: 'Ask the tenant admin whether a sign-in frequency policy applies to this app. It is not visible from the automation side.',
+            },
+        ],
+        sources: [
+            'https://learn.microsoft.com/en-us/entra/identity-platform/refresh-tokens',
+            'https://learn.microsoft.com/en-us/entra/identity-platform/configurable-token-lifetimes',
+        ],
+        complaintLogRows: [14],
+    },
+    {
+        id: 'meta-whatsapp',
+        displayName: 'WhatsApp / Meta',
+        match: {
+            n8n: ['whatsapp', 'facebookgraph', 'facebookapp'],
+            make: ['account:whatsapp', 'account:facebook', 'whatsapp', 'facebook'],
+        },
+        defaultAuthKind: 'api-key',
+        // The decisive fact: this is a bearer token pasted by hand. Nothing refreshes it.
+        autoRefreshable: false,
+        rules: [
+            {
+                condition: 'The token was copied from the Meta app dashboard for testing',
+                certainty: 'conditional',
+                window: 'under 24 hours',
+                detail: 'Temporary access tokens expire in less than a day. Anyone who set this up while testing and never went back has a workflow that died the next morning.',
+                howToCheck: 'If the token came from the "Temporary access token" box on the app dashboard, it is already gone. Only a System User token survives.',
+            },
+            {
+                condition: 'A System User token was generated with a 60-day expiry',
+                certainty: 'conditional',
+                window: '60 days',
+                detail: 'Meta lets you pick the expiry when generating a System User token. 60 days is the common choice and there is no warning before it lapses.',
+                howToCheck: 'Meta Business Settings -> Users -> System Users -> your user -> the token list shows the expiry you chose.',
+            },
+            {
+                condition: 'A System User token was generated with no expiry',
+                certainty: 'conditional',
+                window: 'never',
+                detail: 'Permanent until someone revokes it manually.',
+            },
+        ],
+        sources: [
+            'https://developers.facebook.com/blog/post/2022/12/05/auth-tokens/',
+            'https://community.n8n.io/t/whatsapp-token-expires/182022',
+        ],
+        complaintLogRows: [13],
+    },
+];
+/** Credential types that never expire on a clock — they get revoked instead. */
+exports.STATIC_KEY_HINTS = [
+    'apikey',
+    'api',
+    'token',
+    'httpheaderauth',
+    'httpbasicauth',
+    'httpqueryauth',
+    'smtp',
+    'postgres',
+    'mysql',
+    'redis',
+    'mongodb',
+];
+function resolveProvider(rawType, platform) {
+    const needle = rawType.toLowerCase();
+    for (const p of exports.PROVIDERS) {
+        for (const m of p.match[platform]) {
+            if (needle.includes(m))
+                return p;
+        }
+    }
+    return null;
+}
+/** Best-effort auth kind when no provider matches. */
+function guessAuthKind(rawType) {
+    const t = rawType.toLowerCase();
+    if (t.includes('oauth2') || t.includes('oauth'))
+        return 'oauth2';
+    if (t.includes('basicauth'))
+        return 'basic';
+    if (t.includes('serviceaccount') || t === 'googleapi')
+        return 'service-account';
+    if (exports.STATIC_KEY_HINTS.some((h) => t.includes(h)))
+        return 'api-key';
+    return 'unknown';
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * stillrunning.dev — Workflow Health Check
+ *
+ * Public entry point. Everything here runs in the browser: no network calls, no
+ * storage, nothing leaves the page. The only thing the server ever learns is
+ * three counters (pastes, results shown, emails), sent separately.
+ *
+ * Check order is deliberately inverted from the original spec. Zero-write and
+ * credential expiry lead because they are the two nobody else does; error
+ * handling is last because six free tools already ship it.
+ */
+import type { AnalysisResult, Workflow } from './core/model.js';
+export declare class UnknownFormatError extends Error {
+    constructor();
+}
+export declare function parseWorkflow(input: string | object): Workflow;
+export declare function analyze(input: string | object): AnalysisResult;
+export type { AnalysisResult, Finding, Protection, Severity, Workflow, WorkflowNode, CredentialRef, } from './core/model.js';
+export { PROVIDERS } from './core/providers.js';

package/dist/index.js

@@ -0,0 +1,68 @@
+"use strict";
+/**
+ * stillrunning.dev — Workflow Health Check
+ *
+ * Public entry point. Everything here runs in the browser: no network calls, no
+ * storage, nothing leaves the page. The only thing the server ever learns is
+ * three counters (pastes, results shown, emails), sent separately.
+ *
+ * Check order is deliberately inverted from the original spec. Zero-write and
+ * credential expiry lead because they are the two nobody else does; error
+ * handling is last because six free tools already ship it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROVIDERS = exports.UnknownFormatError = void 0;
+exports.parseWorkflow = parseWorkflow;
+exports.analyze = analyze;
+const model_js_1 = require("./core/model.js");
+const zero_write_js_1 = require("./core/checks/zero-write.js");
+const others_js_1 = require("./core/checks/others.js");
+const protections_js_1 = require("./core/checks/protections.js");
+const n8n_js_1 = require("./adapters/n8n.js");
+const make_js_1 = require("./adapters/make.js");
+class UnknownFormatError extends Error {
+    constructor() {
+        super('That does not look like an n8n workflow or a Make blueprint. Export from n8n with "Download" or from Make with "Export Blueprint", then paste the whole file.');
+        this.name = 'UnknownFormatError';
+    }
+}
+exports.UnknownFormatError = UnknownFormatError;
+function parseWorkflow(input) {
+    const raw = typeof input === 'string' ? JSON.parse(input) : input;
+    if ((0, n8n_js_1.isN8nWorkflow)(raw))
+        return (0, n8n_js_1.parseN8n)(raw);
+    if ((0, make_js_1.isMakeBlueprint)(raw))
+        return (0, make_js_1.parseMake)(raw);
+    throw new UnknownFormatError();
+}
+/** Order matters: this is what the user reads top to bottom. */
+const CHECKS = [
+    zero_write_js_1.checkZeroWrite,
+    others_js_1.checkCredentialExpiry,
+    others_js_1.checkCadence,
+    others_js_1.checkErrorHandling,
+];
+function analyze(input) {
+    const wf = parseWorkflow(input);
+    const findings = CHECKS.flatMap((c) => c(wf)).sort((a, b) => model_js_1.SEVERITY_ORDER[a.severity] - model_js_1.SEVERITY_ORDER[b.severity]);
+    return {
+        platform: wf.platform,
+        workflowName: wf.name,
+        nodeCount: wf.nodes.filter((n) => n.role !== 'note' && !n.disabled).length,
+        findings,
+        protections: (0, protections_js_1.checkProtections)(wf),
+        parseNotes: wf.parseNotes,
+        stats: {
+            writeNodes: wf.nodes.filter((n) => n.role === 'write' && !n.disabled).length,
+            oauthCredentials: wf.nodes
+                .flatMap((n) => n.credentials)
+                .filter((c) => c.authKind === 'oauth2').length,
+            triggers: wf.triggerIds.length,
+            staticKeyCredentials: wf.nodes
+                .flatMap((n) => n.credentials)
+                .filter((c) => c.authKind === 'api-key' || c.authKind === 'basic').length,
+        },
+    };
+}
+var providers_js_1 = require("./core/providers.js");
+Object.defineProperty(exports, "PROVIDERS", { enumerable: true, get: function () { return providers_js_1.PROVIDERS; } });

package/dist/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@still-running/health-check",
+  "version": "1.0.0",
+  "description": "Static analysis of n8n workflow JSON and Make blueprint JSON — no execution, no network, no storage.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AliAlsamraay/stillrunning.git",
+    "directory": "packages/health-check"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc -b",
+    "build": "tsc -p tsconfig.build.json && node -e \"require('fs').writeFileSync('dist/package.json', JSON.stringify({type:'commonjs'}))\"",
+    "prepublishOnly": "npm run build"
+  }
+}