socket-function 1.2.23 → 1.2.24

package/.claude/settings.local.json

@@ -4,7 +4,8 @@
       "Bash(mkdir -p C:/Users/quent/AppData/Local/Temp/claude/D--repos-socket-function/117d10bd-31c6-4c68-938d-1fff47788fa6/scratchpad/tm-recover)",
       "Bash(cp -r 'C:/Users/quent/AppData/Local/BraveSoftware/Brave-Browser/User Data/Default/Local Extension Settings/dhdgffkkebhmkfjojejmpbldmpobfkfo' C:/Users/quent/AppData/Local/Temp/claude/D--repos-socket-function/117d10bd-31c6-4c68-938d-1fff47788fa6/scratchpad/tm-recover/LocalExtSettings)",
       "Bash(yarn test-dns-claude *)",
-      "Bash(yarn type *)"
+      "Bash(yarn type *)",
+      "Bash(yarn test *)"
     ]
   }
 }

package/index.d.ts

@@ -963,6 +963,15 @@ declare module "socket-function/src/formatting/logColors" {
 }
 
 declare module "socket-function/src/forwardPort" {
+    /** Resolves the UPnP Internet Gateway Device we can talk to, along with the local
+     *      addressing needed to build SOAP requests against it. Shared by every operation
+     *      that needs to reach the router's control endpoint. */
+    export declare function resolveGateway(): Promise<{
+        internalIP: string;
+        gatewayIP: string;
+        controlPort: number;
+        controlURLs: string[];
+    }>;
     export interface PortMapping {
         externalPort: number;
         internalPort: number;
@@ -980,14 +989,27 @@ declare module "socket-function/src/forwardPort" {
      *      GetGenericPortMappingEntry from index 0 until the gateway reports the index
      *      is out of range (SOAP error 713 / a non-200 response). */
     export declare function listPortMappings(): Promise<PortMapping[]>;
+    /** Outcome of forwardPort. `owned` is true once we hold the router mapping for the port. When
+     *      false, `reason` says why: "declined" = noPortStealing and another host holds the port (the
+     *      caller should try a different port); "error" = UPnP unreachable / create failed (best-effort,
+     *      nothing forwarded but the caller can carry on). */
+    export type ForwardPortResult = {
+        owned: boolean;
+        reason?: "declined" | "error";
+    };
     export declare function forwardPort(config: {
         externalPort: number;
         internalPort: number;
+        /** Lease length in ms. Defaults to a PERMANENT mapping (never expires), which is what you want:
+         *      finite leases can't be refreshed gap-free (see PERMANENT_LEASE). Pass a finite duration
+         *      only if you specifically want the mapping to expire on its own — in that case we do NOT
+         *      run the supersession monitor, since a finite mapping is expected to disappear. */
         duration?: number;
-        /** Keep the lease alive by re-creating the mapping at 80% of `duration`, forever. On by
-         *      default, which is what you want — an un-maintained forward silently expires. */
-        autoRenew?: boolean;
-    }): Promise<void>;
+        /** If the port is already forwarded to a DIFFERENT internal client, don't steal it: return
+         *      { owned: false, reason: "declined" } instead of taking over. Off by default (default is
+         *      last-writer-wins takeover). An existing mapping that is ours (or none) is still (re)claimed. */
+        noPortStealing?: boolean;
+    }): Promise<ForwardPortResult>;
     /** Our machine's LAN IP, as the router sees it — used to tell whether an existing port
      *      mapping points at us or at a different machine on the network. */
     export declare function getLocalInternalIP(): Promise<string | undefined>;
@@ -996,6 +1018,21 @@ declare module "socket-function/src/forwardPort" {
      *      directly reachable and forwarding is unnecessary. This is the cross-platform gate that
      *      replaced the old "skip forwarding on linux" check, so Linux hosts behind NAT forward. */
     export declare function isBehindNAT(): Promise<boolean>;
+    export declare function createPortMapping(config: {
+        externalPort: number;
+        internalPort: number;
+        gatewayIP: string;
+        controlPort: number;
+        controlPath: string;
+        internalIP: string;
+        duration: number;
+    }): Promise<void>;
+    export declare function deletePortMapping(config: {
+        externalPort: number;
+        gatewayIP: string;
+        controlPort: number;
+        controlPath: string;
+    }): Promise<void>;
 
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "socket-function",
-	"version": "1.2.23",
+	"version": "1.2.24",
 	"main": "index.js",
 	"license": "MIT",
 	"dependencies": {

package/src/forwardPort.d.ts

@@ -1,3 +1,12 @@
+/** Resolves the UPnP Internet Gateway Device we can talk to, along with the local
+ *      addressing needed to build SOAP requests against it. Shared by every operation
+ *      that needs to reach the router's control endpoint. */
+export declare function resolveGateway(): Promise<{
+    internalIP: string;
+    gatewayIP: string;
+    controlPort: number;
+    controlURLs: string[];
+}>;
 export interface PortMapping {
     externalPort: number;
     internalPort: number;
@@ -15,14 +24,27 @@ export interface PortMapping {
  *      GetGenericPortMappingEntry from index 0 until the gateway reports the index
  *      is out of range (SOAP error 713 / a non-200 response). */
 export declare function listPortMappings(): Promise<PortMapping[]>;
+/** Outcome of forwardPort. `owned` is true once we hold the router mapping for the port. When
+ *      false, `reason` says why: "declined" = noPortStealing and another host holds the port (the
+ *      caller should try a different port); "error" = UPnP unreachable / create failed (best-effort,
+ *      nothing forwarded but the caller can carry on). */
+export type ForwardPortResult = {
+    owned: boolean;
+    reason?: "declined" | "error";
+};
 export declare function forwardPort(config: {
     externalPort: number;
     internalPort: number;
+    /** Lease length in ms. Defaults to a PERMANENT mapping (never expires), which is what you want:
+     *      finite leases can't be refreshed gap-free (see PERMANENT_LEASE). Pass a finite duration
+     *      only if you specifically want the mapping to expire on its own — in that case we do NOT
+     *      run the supersession monitor, since a finite mapping is expected to disappear. */
     duration?: number;
-    /** Keep the lease alive by re-creating the mapping at 80% of `duration`, forever. On by
-     *      default, which is what you want — an un-maintained forward silently expires. */
-    autoRenew?: boolean;
-}): Promise<void>;
+    /** If the port is already forwarded to a DIFFERENT internal client, don't steal it: return
+     *      { owned: false, reason: "declined" } instead of taking over. Off by default (default is
+     *      last-writer-wins takeover). An existing mapping that is ours (or none) is still (re)claimed. */
+    noPortStealing?: boolean;
+}): Promise<ForwardPortResult>;
 /** Our machine's LAN IP, as the router sees it — used to tell whether an existing port
  *      mapping points at us or at a different machine on the network. */
 export declare function getLocalInternalIP(): Promise<string | undefined>;
@@ -31,3 +53,18 @@ export declare function getLocalInternalIP(): Promise<string | undefined>;
  *      directly reachable and forwarding is unnecessary. This is the cross-platform gate that
  *      replaced the old "skip forwarding on linux" check, so Linux hosts behind NAT forward. */
 export declare function isBehindNAT(): Promise<boolean>;
+export declare function createPortMapping(config: {
+    externalPort: number;
+    internalPort: number;
+    gatewayIP: string;
+    controlPort: number;
+    controlPath: string;
+    internalIP: string;
+    duration: number;
+}): Promise<void>;
+export declare function deletePortMapping(config: {
+    externalPort: number;
+    gatewayIP: string;
+    controlPort: number;
+    controlPath: string;
+}): Promise<void>;

package/src/forwardPort.ts

@@ -1,7 +1,7 @@
 import debugbreak from "debugbreak";
 import * as dgram from "dgram";
 import os from "os";
-import { timeInHour } from "./misc";
+import { timeInMinute } from "./misc";
 
 const SSDP_DISCOVER_MX = 2;
 const SSDP_DISCOVER_MSG = `M-SEARCH * HTTP/1.1\r\nHOST: 239.255.255.250:1900\r\nMAN: "ssdp:discover"\r\nMX: ${SSDP_DISCOVER_MX}\r\nST: urn:schemas-upnp-org:device:InternetGatewayDevice:1\r\n\r\n`;
@@ -9,7 +9,7 @@ const SSDP_DISCOVER_MSG = `M-SEARCH * HTTP/1.1\r\nHOST: 239.255.255.250:1900\r\n
 /** Resolves the UPnP Internet Gateway Device we can talk to, along with the local
  *      addressing needed to build SOAP requests against it. Shared by every operation
  *      that needs to reach the router's control endpoint. */
-async function resolveGateway(): Promise<{
+export async function resolveGateway(): Promise<{
     internalIP: string;
     gatewayIP: string;
     controlPort: number;
@@ -74,29 +74,82 @@ export async function listPortMappings(): Promise<PortMapping[]> {
     throw new Error(`Failed to list port mappings, could not find a working controlURL. Last error: ${(lastError as Error)?.stack ?? lastError}`);
 }
 
-// A UPnP lease expires on its own, so a forward left un-renewed silently dies partway through.
-//  Renew at 80% of the duration: enough margin to cover a failed attempt (we retry on the next
-//  tick) while the previous lease is still live, so the mapping never actually lapses.
-const LEASE_RENEW_FRACTION = 0.8;
+// We forward with a PERMANENT lease (leaseDuration 0) rather than a finite one that we renew.
+//  A finite lease can't be refreshed gap-free on real routers: an in-place AddPortMapping while
+//  the lease is active is silently ignored (returns 200 but the lease keeps ticking to zero), and
+//  the only way to reset it — delete then re-add — leaves a window where the port isn't forwarded.
+//  A permanent mapping never expires, so there's nothing to renew and no gap. (Verified against a
+//  live IGD; see test.ts.)
+const PERMANENT_LEASE = 0;
+
+// A permanent mapping never expires, so we don't renew. We only watch, on this interval, for
+//  another application having superseded our forward (or a router reboot having wiped it), and log
+//  loudly if so. We do NOT re-take it — last writer wins, so fighting back would just be a war.
+const SUPERSEDE_CHECK_INTERVAL = timeInMinute * 30;
+
+/** Outcome of forwardPort. `owned` is true once we hold the router mapping for the port. When
+ *      false, `reason` says why: "declined" = noPortStealing and another host holds the port (the
+ *      caller should try a different port); "error" = UPnP unreachable / create failed (best-effort,
+ *      nothing forwarded but the caller can carry on). */
+export type ForwardPortResult = {
+    owned: boolean;
+    reason?: "declined" | "error";
+};
 
 export async function forwardPort(config: {
     externalPort: number;
     internalPort: number;
+    /** Lease length in ms. Defaults to a PERMANENT mapping (never expires), which is what you want:
+     *      finite leases can't be refreshed gap-free (see PERMANENT_LEASE). Pass a finite duration
+     *      only if you specifically want the mapping to expire on its own — in that case we do NOT
+     *      run the supersession monitor, since a finite mapping is expected to disappear. */
     duration?: number;
-    /** Keep the lease alive by re-creating the mapping at 80% of `duration`, forever. On by
-     *      default, which is what you want — an un-maintained forward silently expires. */
-    autoRenew?: boolean;
-}) {
-    let duration = config.duration ?? timeInHour;
-    let autoRenew = config.autoRenew ?? true;
-
-    async function createMapping() {
+    /** If the port is already forwarded to a DIFFERENT internal client, don't steal it: return
+     *      { owned: false, reason: "declined" } instead of taking over. Off by default (default is
+     *      last-writer-wins takeover). An existing mapping that is ours (or none) is still (re)claimed. */
+    noPortStealing?: boolean;
+}): Promise<ForwardPortResult> {
+    const { externalPort, internalPort } = config;
+    let duration = config.duration ?? PERMANENT_LEASE;
+    let permanent = duration === PERMANENT_LEASE;
+
+    // Take ownership of the router's mapping for this external port: delete whatever's there (a
+    //  stale mapping of ours, or another host's) so our AddPortMapping isn't rejected as a conflict
+    //  (718), then install our mapping. This makes the last writer win — whichever application
+    //  forwards most recently owns the port. With noPortStealing we first bail out if the existing
+    //  mapping belongs to someone else, leaving it untouched.
+    // Our current mapping for this external port (TCP), from a fresh listing.
+    async function readMapping(): Promise<PortMapping | undefined> {
+        return (await listPortMappings()).find(m => m.externalPort === externalPort && m.protocol.toUpperCase() === "TCP");
+    }
+
+    async function takeOwnership(): Promise<ForwardPortResult> {
         try {
-            const { externalPort, internalPort } = config;
             const { internalIP, gatewayIP, controlPort, controlURLs } = await resolveGateway();
 
+            // One listing up front: tells us who currently owns the port (for noPortStealing) and
+            //  whether a mapping exists at all (so we only delete when there's something to delete).
+            let existing = await readMapping();
+
+            if (existing && existing.internalClient !== internalIP && config.noPortStealing) {
+                console.log(`Port ${externalPort} is already forwarded to ${existing.internalClient} (not us); not stealing it (noPortStealing).`);
+                return { owned: false, reason: "declined" };
+            }
+
+            // Already exactly what we want (ours, permanent, right internal port) — don't churn it.
+            if (existing && existing.internalClient === internalIP && existing.internalPort === internalPort && permanent && existing.leaseDuration === 0) {
+                return { owned: true };
+            }
+
+            // Only delete when a mapping already exists (deleting a missing entry just errors 714,
+            //  and a free port needs no delete). Once one exists we clear it so our AddPortMapping
+            //  isn't rejected as a conflict (718) — this is also what makes the last writer win.
+            let needDelete = !!existing;
             for (let controlURL of controlURLs) {
                 try {
+                    if (needDelete) {
+                        await deletePortMapping({ externalPort, gatewayIP, controlPort, controlPath: controlURL }).catch(() => { });
+                    }
                     await createPortMapping({
                         externalPort, internalPort,
                         gatewayIP,
@@ -105,28 +158,59 @@ export async function forwardPort(config: {
                         internalIP,
                         duration,
                     });
-                    console.log(`Port mapping created on ${gatewayIP}:${externalPort} -> ${internalIP}:${internalPort}`);
-                    return;
+                    // AddPortMapping can return 200 on a control URL that isn't the real WAN
+                    //  connection service without actually taking effect, so confirm the mapping is
+                    //  now ours before trusting it; otherwise move on and try the next control URL.
+                    let after = await readMapping();
+                    if (after && after.internalClient === internalIP) {
+                        console.log(`Port mapping created on ${gatewayIP}:${externalPort} -> ${internalIP}:${internalPort}`);
+                        return { owned: true };
+                    }
+                    console.error(`AddPortMapping on ${controlURL} reported success but ${externalPort} isn't forwarded to us; trying the next control URL`);
                 } catch (e) {
                     console.error(`Failed to create port mapping using controlURL ${controlURL}`, e);
                 }
             }
-            console.error("Failed to create port mapping, could not find controlURL");
+            // Not a port-contention issue — the port itself is fine, we just couldn't program the
+            //  router. Return "error" (not "declined") so the caller keeps this port rather than
+            //  scanning for another one; the console.errors above are the record of what went wrong.
+            console.error(`Failed to create port mapping for ${externalPort} on any control URL (${controlURLs.join(", ")})`);
         } catch (e) {
             console.error("Error in forwardPort", e);
         }
+        return { owned: false, reason: "error" };
     }
 
-    await createMapping();
+    // Re-read the mapping and warn if we no longer own it. Compares against our CURRENT LAN IP, so
+    //  this also catches the case where our own IP changed out from under the old mapping.
+    async function warnIfSuperseded() {
+        try {
+            let currentIP = await getLocalInternalIP();
+            let ours = (await listPortMappings()).find(m => m.externalPort === externalPort && m.protocol.toUpperCase() === "TCP");
+            if (!ours) {
+                console.error(`Port forward ${externalPort} is gone — the mapping was removed (router reboot, or another host deleted it).`);
+            } else if (currentIP && ours.internalClient !== currentIP) {
+                console.error(`Port forward ${externalPort} was superseded — it now forwards to ${ours.internalClient} instead of us (${currentIP}). Another application has taken the port.`);
+            }
+        } catch (e) {
+            console.error(`Failed to check port forward ${externalPort} for supersession`, (e as Error).stack ?? e);
+        }
+    }
 
-    if (autoRenew) {
+    let result = await takeOwnership();
+
+    // Only monitor permanent mappings we actually own. A finite lease is expected to expire, so its
+    //  disappearance isn't a supersession worth warning about; a declined/failed claim owns nothing.
+    if (result.owned && permanent) {
         // unref so a script that only wants a one-off forward (and then exits) isn't held open by
-        //  the renewal timer; a running server stays alive on its own and the renewals keep firing.
+        //  the monitor timer; a running server stays alive on its own and the checks keep firing.
         let timer = setInterval(() => {
-            void createMapping();
-        }, Math.max(1, Math.floor(duration * LEASE_RENEW_FRACTION)));
+            void warnIfSuperseded();
+        }, SUPERSEDE_CHECK_INTERVAL);
         timer.unref?.();
     }
+
+    return result;
 }
 
 /** Our machine's LAN IP, as the router sees it — used to tell whether an existing port
@@ -256,7 +340,7 @@ async function getControlPaths(gateway: string) {
     return matches;
 }
 
-async function createPortMapping(config: {
+export async function createPortMapping(config: {
     externalPort: number;
     internalPort: number;
     gatewayIP: string;
@@ -302,6 +386,44 @@ async function createPortMapping(config: {
     }
 }
 
+export async function deletePortMapping(config: {
+    externalPort: number;
+    gatewayIP: string;
+    controlPort: number;
+    controlPath: string;
+}): Promise<void> {
+    const { externalPort, controlPath, controlPort, gatewayIP } = config;
+    const action = "\"urn:schemas-upnp-org:service:WANIPConnection:1#DeletePortMapping\"";
+
+    const soapBody = `
+        <?xml version="1.0"?>
+        <s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
+            <s:Body>
+                <u:DeletePortMapping xmlns:u="urn:schemas-upnp-org:service:WANIPConnection:1">
+                    <NewRemoteHost></NewRemoteHost>
+                    <NewExternalPort>${externalPort}</NewExternalPort>
+                    <NewProtocol>TCP</NewProtocol>
+                </u:DeletePortMapping>
+            </s:Body>
+        </s:Envelope>
+    `;
+
+    const res = await fetch(`http://${gatewayIP}:${controlPort}${controlPath}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "text/xml; charset=\"utf-8\"",
+            "SOAPAction": action,
+            "Content-Length": Buffer.byteLength(soapBody) + "",
+        },
+        body: soapBody
+    });
+
+    if (res.status !== 200) {
+        const data = await res.text();
+        throw new Error(`Failed to delete port mapping: ${data}`);
+    }
+}
+
 // UPnP returns this error code when we walk past the last mapping index, which is how
 //  we detect the end of the list rather than a real failure.
 const UPNP_ARRAY_INDEX_INVALID = 713;

package/src/webSocketServer.ts

@@ -13,12 +13,11 @@ import { getNodeId } from "./nodeCache";
 import crypto from "crypto";
 import { Watchable, getRootDomain } from "./misc";
 import { delay } from "./batching";
-import { magenta, red } from "./formatting/logColors";
 import { yellow } from "./formatting/logColors";
 import { green } from "./formatting/logColors";
 import { formatTime } from "./formatting/format";
 import { getExternalIP, testTCPIsListening } from "./networking";
-import { forwardPort, listPortMappings, getLocalInternalIP, isBehindNAT, PortMapping } from "./forwardPort";
+import { forwardPort, isBehindNAT } from "./forwardPort";
 
 // When a requested port is taken and useAvailablePortIfPortInUse is set, we scan
 //  upwards from this base instead of binding a random OS-assigned port, so restarts
@@ -349,7 +348,7 @@ export async function startSocketServer(
     }
 
     // Frees the currently-bound listening socket so we can rebind on a different port
-    //  (used when a locally-free port turns out to be unusable for forwarding).
+    //  (used when a locally-bound port turns out to be forwarded to another host).
     async function releasePort(): Promise<void> {
         await new Promise<void>((resolve, reject) => {
             if (!realServer.listening) {
@@ -360,39 +359,10 @@ export async function startSocketServer(
         });
     }
 
-    // Forwarding maps the external port to an equal internal port, so a candidate is only
-    //  usable if we can also own its external mapping on the router. Only worthwhile when a
-    //  NAT sits between us and the internet; a directly-reachable public host needs no forward.
+    // Only worthwhile when a NAT sits between us and the internet; a directly-reachable public host
+    //  needs no forward.
     const doForward = !!(config.autoForwardPort && config.public) && await isBehindNAT();
 
-    // Ensures the router's external mapping for `externalPort` belongs to us. Returns true
-    //  if it's ours to keep (existing-and-ours → refresh the lease; free → create and
-    //  confirm we won it), false if another machine owns it and we should try a new port.
-    async function claimPortForward(externalPort: number): Promise<boolean> {
-        const ourIP = await getLocalInternalIP();
-        const matches = (m: PortMapping) => m.externalPort === externalPort && m.protocol.toUpperCase() === "TCP";
-
-        const existing = (await listPortMappings()).find(matches);
-        if (existing) {
-            if (ourIP && existing.internalClient === ourIP) {
-                await forwardPort({ externalPort, internalPort: externalPort });
-                return true;
-            }
-            console.log(magenta(`External port ${externalPort} is already forwarded to ${existing.internalClient}, trying another port`));
-            return false;
-        }
-
-        // Free right now — create the mapping, then re-read it to make sure another host
-        //  didn't grab the same external port in the race between our list and our create.
-        await forwardPort({ externalPort, internalPort: externalPort });
-        const ours = (await listPortMappings()).find(matches);
-        if (!ours || (ourIP && ours.internalClient !== ourIP)) {
-            console.log(magenta(`Failed to claim external port ${externalPort} (now ${ours ? `forwarded to ${ours.internalClient}` : "still unmapped"}), trying another port`));
-            return false;
-        }
-        return true;
-    }
-
     // Candidate ports: an explicitly requested port first (a falsy port, the default 0,
     //  means "no preference"), then a consistent upward scan so restarts are predictable.
     function* candidatePorts(): Generator<number> {
@@ -411,19 +381,14 @@ export async function startSocketServer(
             }
             continue;
         }
-        // Locally bound. If we also forward, the external mapping must be ours too, or we
-        //  release this port and keep scanning.
+        // Locally bound. If we also forward, we need to own the router mapping for this port too.
         if (doForward) {
-            let claimed: boolean;
-            try {
-                claimed = await claimPortForward(candidate);
-            } catch (e) {
-                // UPnP unavailable (no gateway / discovery failed): fall back to best-effort
-                //  forwarding rather than refusing to start.
-                console.error(red(`Could not verify forwarding for port ${candidate}, continuing best-effort: ${(e as Error).stack}`));
-                claimed = true;
-            }
-            if (!claimed) {
+            // Take over the explicitly-requested port (the user asked for it), but during the
+            //  fallback scan don't steal a port another host is already forwarding — skip it and
+            //  keep scanning. forwardPort is best-effort: on a UPnP error it returns owned:false
+            //  reason:"error", and we keep the port anyway rather than refusing to start.
+            let result = await forwardPort({ externalPort: candidate, internalPort: candidate, noPortStealing: candidate !== config.port });
+            if (!result.owned && result.reason === "declined") {
                 await releasePort();
                 continue;
             }
@@ -438,12 +403,6 @@ export async function startSocketServer(
 
     port = (realServer.address() as net.AddressInfo).port;
 
-    if (doForward) {
-        // The mapping is claimed above; this establishes the maintained forward, which
-        //  auto-renews its own lease (at 80% of the duration) so it doesn't expire.
-        await forwardPort({ externalPort: port, internalPort: port });
-    }
-
     let nodeId = getNodeId(getCommonName(config.cert), port);
     console.log(green(`Started Listening on ${nodeId} (${host}) after ${formatTime(process.uptime() * 1000)}`), {
         domains: Object.keys(config.SNICerts || {}),

package/test.ts

@@ -1,21 +1,73 @@
-import { listPortMappings, getLocalInternalIP, isBehindNAT } from "./src/forwardPort";
+import { forwardPort, listPortMappings, resolveGateway, createPortMapping, deletePortMapping, PortMapping } from "./src/forwardPort";
 
+// Verifies noPortStealing:
+//   1. Against a real foreign mapping (owned by another device, if the router has one): forwardPort
+//      must return { owned:false, reason:"declined" } and leave that mapping UNTOUCHED.
+//   2. On a free port: noPortStealing still claims it (owned:true).
+//   3. When the existing mapping is OURS: noPortStealing still (re)claims it (owned:true).
+//   4. Default (stealing) still takes over an existing finite mapping and makes it permanent.
+
+const TEST_EXTERNAL_PORT = 54000;
+const TEST_INTERNAL_PORT = 54000;
 
 async function main() {
-    let ourIP = await getLocalInternalIP();
-    let behindNAT = await isBehindNAT();
-    console.log(`Outbound / local IP: ${ourIP ?? "(could not determine)"}`);
-    console.log(`Behind NAT (forwarding ${behindNAT ? "WILL" : "will NOT"} be attempted): ${behindNAT}`);
-
-    let mappings = await listPortMappings();
-    console.log(`Found ${mappings.length} port mapping(s):`);
-    for (let mapping of mappings) {
-        let host = mapping.remoteHost || "*";
-        let lease = mapping.leaseDuration === 0 ? "permanent" : `${mapping.leaseDuration}s left`;
-        let ours = ourIP && mapping.internalClient === ourIP ? " <-- OURS" : "";
-        console.log(`  ${mapping.protocol} ${host}:${mapping.externalPort} -> ${mapping.internalClient}:${mapping.internalPort} (${mapping.enabled ? "enabled" : "disabled"}, ${lease})${mapping.description ? ` "${mapping.description}"` : ""}${ours}`);
+    let { internalIP, gatewayIP, controlPort, controlURLs } = await resolveGateway();
+    console.log(`Our IP: ${internalIP}`);
+
+    async function mappingFor(externalPort: number): Promise<PortMapping | undefined> {
+        return (await listPortMappings()).find(m => m.externalPort === externalPort && m.protocol.toUpperCase() === "TCP");
+    }
+    async function cleanup() {
+        for (let controlPath of controlURLs) {
+            await deletePortMapping({ externalPort: TEST_EXTERNAL_PORT, gatewayIP, controlPort, controlPath }).catch(() => { });
+        }
+    }
+    let pass = true;
+    let check = (ok: boolean, msg: string) => { if (!ok) pass = false; console.log(`  ${ok ? "PASS" : "FAIL"}: ${msg}`); };
+
+    // 1. Real foreign mapping, if the router has one.
+    console.log(`\n=== 1) decline a real foreign mapping (noPortStealing) ===`);
+    let foreign = (await listPortMappings()).find(m => m.protocol.toUpperCase() === "TCP" && m.internalClient && m.internalClient !== internalIP);
+    if (!foreign) {
+        console.log(`  (skipped: router has no mapping owned by another device to test against)`);
+    } else {
+        console.log(`  found foreign mapping: port ${foreign.externalPort} -> ${foreign.internalClient} (lease ${foreign.leaseDuration}s)`);
+        let result = await forwardPort({ externalPort: foreign.externalPort, internalPort: foreign.internalPort, noPortStealing: true });
+        let after = await mappingFor(foreign.externalPort);
+        check(!result.owned && result.reason === "declined", `forwardPort returned declined (got owned=${result.owned}, reason=${result.reason})`);
+        check(after?.internalClient === foreign.internalClient && after?.leaseDuration === foreign.leaseDuration, `foreign mapping left untouched (still -> ${after?.internalClient}, lease ${after?.leaseDuration}s)`);
     }
-    console.table(mappings);
+
+    // 2. Free port: noPortStealing still claims.
+    console.log(`\n=== 2) claim a free port (noPortStealing) ===`);
+    await cleanup();
+    let r2 = await forwardPort({ externalPort: TEST_EXTERNAL_PORT, internalPort: TEST_INTERNAL_PORT, noPortStealing: true });
+    let m2 = await mappingFor(TEST_EXTERNAL_PORT);
+    check(r2.owned === true, `returned owned=true (got ${r2.owned}, reason=${r2.reason})`);
+    check(m2?.internalClient === internalIP && m2?.leaseDuration === 0, `mapping is ours & permanent (-> ${m2?.internalClient}, lease ${m2?.leaseDuration}s)`);
+
+    // 3. Existing mapping is OURS: noPortStealing still reclaims.
+    console.log(`\n=== 3) reclaim our own mapping (noPortStealing) ===`);
+    let r3 = await forwardPort({ externalPort: TEST_EXTERNAL_PORT, internalPort: TEST_INTERNAL_PORT, noPortStealing: true });
+    check(r3.owned === true, `returned owned=true (got ${r3.owned}, reason=${r3.reason})`);
+
+    // 4. Default (stealing) takes over a finite mapping -> permanent.
+    console.log(`\n=== 4) default takeover of a finite mapping ===`);
+    await cleanup();
+    for (let controlPath of controlURLs) {
+        try {
+            await createPortMapping({ externalPort: TEST_EXTERNAL_PORT, internalPort: TEST_INTERNAL_PORT, gatewayIP, controlPort, controlPath, internalIP, duration: 120 * 1000 });
+            break;
+        } catch { }
+    }
+    let seeded = await mappingFor(TEST_EXTERNAL_PORT);
+    let r4 = await forwardPort({ externalPort: TEST_EXTERNAL_PORT, internalPort: TEST_INTERNAL_PORT });
+    let m4 = await mappingFor(TEST_EXTERNAL_PORT);
+    check(seeded?.leaseDuration === 120, `seeded a finite (120s) mapping first (got ${seeded?.leaseDuration}s)`);
+    check(r4.owned === true && m4?.leaseDuration === 0, `took over -> permanent (owned=${r4.owned}, lease ${m4?.leaseDuration}s)`);
+
+    await cleanup();
+    console.log(`\n${pass ? "ALL PASS" : "SOME FAILED"}. Cleaned up test mapping on port ${TEST_EXTERNAL_PORT}.`);
 }
 
 main().catch(e => console.error(e.stack ?? e)).finally(() => process.exit(0));