securl 1.4.1

package/RELEASING.md

@@ -0,0 +1,37 @@
+# Releasing `securl`
+
+## Pre-release checklist
+
+Only release `securl` when the package itself changes. Backend-only API resources, hosted app deploy scripts, Railway settings, Hostinger static deploys, and app-only UI changes do not warrant a core package bump unless they also change files that are published from `packages/core`.
+
+Version bump guidance:
+
+- **Patch**: bug fixes, scoring calibration fixes, false-positive/false-negative corrections, dependency/runtime fixes, or docs/signalling updates intentionally worth republishing.
+- **Minor**: new exported helpers, new analysis signals, new CLI options, new report formats, new typed result fields, or additive public API changes.
+- **Major**: breaking changes to exported functions, CLI commands/options, package exports, result types, scoring semantics that consumers must handle differently, or supported Node/runtime expectations.
+
+Before deciding to bump, check what changed since the latest core tag:
+
+```sh
+git diff --name-status securl-v$(node -p "require('./packages/core/package.json').version")..HEAD -- packages/core package.json package-lock.json
+```
+
+1. Update `packages/core/package.json` version.
+2. Update `packages/core/CHANGELOG.md`.
+3. Run:
+   - `npm run release:core:check`
+4. Review the dry-run tarball contents.
+5. Confirm `NPM_TOKEN` is present in GitHub repository secrets.
+
+## Release steps
+
+1. Commit the version/changelog update.
+2. Tag the release using `securl-v<version>`, for example `securl-v1.4.1`.
+3. Push the tag.
+4. Let `.github/workflows/publish-core-package.yml` publish the package.
+
+## Post-release
+
+1. Confirm the package is available on npm.
+2. Verify import/install instructions from the published artifact.
+3. Move changelog notes from `Unreleased` to the released version section.

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security Policy for `securl`
+
+This package is published from the public source repository:
+
+- `https://github.com/this-is-securl/securl`
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities privately via:
+
+- GitHub security advisory / private vulnerability report on the repository, or
+- email `keithbatterham@pm.me`
+
+Please avoid filing public issues for security-sensitive reports.
+
+## Package trust signals
+
+- public source repository
+- reproducible package contents via `npm pack --dry-run`
+- GitHub Actions release workflow
+- npm provenance enabled at publish time
+- no install scripts
+- one runtime dependency (`node-html-parser`)
+
+## Scope note
+
+This package performs network-facing posture analysis by design. That can look high-risk to automated package reputation systems, but the intended use is defensive scanning against targets you own or are authorized to assess.

package/dist/certificate.d.ts

@@ -0,0 +1,5 @@
+import type { CertificateResult } from "./types.js";
+export declare const OBSERVATIONAL_TLS_OPTIONS: {
+    rejectUnauthorized: boolean;
+};
+export declare const scanTls: (targetUrl: URL) => Promise<CertificateResult>;

package/dist/certificate.js

@@ -0,0 +1,92 @@
+import tls from "node:tls";
+import { TLS_HANDSHAKE_TIMEOUT_MS } from "./scannerConfig.js";
+const firstStringValue = (value) => {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        const first = value.find((item) => typeof item === "string");
+        return typeof first === "string" ? first : null;
+    }
+    return null;
+};
+const allowInsecureTls = process.env.EXTERNAL_POSTURE_ALLOW_INSECURE_TLS === "1";
+export const OBSERVATIONAL_TLS_OPTIONS = {
+    // Keep certificate verification on by default.
+    // Set EXTERNAL_POSTURE_ALLOW_INSECURE_TLS=1 only for controlled observational runs.
+    rejectUnauthorized: !allowInsecureTls,
+};
+export const scanTls = (targetUrl) => {
+    if (targetUrl.protocol !== "https:") {
+        return Promise.resolve({
+            available: false,
+            valid: false,
+            authorized: false,
+            issuer: null,
+            subject: null,
+            validFrom: null,
+            validTo: null,
+            daysRemaining: null,
+            protocol: null,
+            cipher: null,
+            fingerprint: null,
+            subjectAltName: [],
+            issues: ["TLS certificate data is only available for HTTPS targets."],
+        });
+    }
+    return new Promise((resolve, reject) => {
+        const socket = tls.connect({
+            host: targetUrl.hostname,
+            port: Number(targetUrl.port || 443),
+            servername: targetUrl.hostname,
+            ...OBSERVATIONAL_TLS_OPTIONS,
+            timeout: TLS_HANDSHAKE_TIMEOUT_MS,
+        });
+        socket.once("secureConnect", () => {
+            const certificate = socket.getPeerCertificate(true);
+            const protocol = socket.getProtocol?.() || null;
+            const cipherInfo = socket.getCipher?.();
+            const validTo = certificate?.valid_to || null;
+            const validFrom = certificate?.valid_from || null;
+            const daysRemaining = validTo
+                ? Math.ceil((new Date(validTo).getTime() - Date.now()) / (1000 * 60 * 60 * 24))
+                : null;
+            const subjectAltName = typeof certificate?.subjectaltname === "string"
+                ? certificate.subjectaltname.split(",").map((entry) => entry.trim().replace(/^DNS:/, ""))
+                : [];
+            const issues = [];
+            if (!socket.authorized) {
+                issues.push(typeof socket.authorizationError === "string"
+                    ? socket.authorizationError
+                    : "Certificate is not trusted.");
+            }
+            if (allowInsecureTls) {
+                issues.push("Insecure TLS observation mode is enabled via EXTERNAL_POSTURE_ALLOW_INSECURE_TLS.");
+            }
+            if (daysRemaining !== null && daysRemaining <= 14)
+                issues.push("Certificate expires very soon.");
+            if (protocol && /tlsv1(\.0|\.1)?$/i.test(protocol))
+                issues.push("TLS protocol is outdated.");
+            resolve({
+                available: true,
+                valid: Boolean(socket.authorized),
+                authorized: Boolean(socket.authorized),
+                issuer: firstStringValue(certificate?.issuer?.O) ?? firstStringValue(certificate?.issuer?.CN),
+                subject: firstStringValue(certificate?.subject?.CN),
+                validFrom,
+                validTo,
+                daysRemaining,
+                protocol,
+                cipher: cipherInfo?.name || null,
+                fingerprint: certificate?.fingerprint256 || null,
+                subjectAltName,
+                issues,
+            });
+            socket.end();
+        });
+        socket.once("timeout", () => {
+            socket.destroy(new Error("TLS handshake timed out."));
+        });
+        socket.once("error", reject);
+    });
+};

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};