Skip to content

Commit 488fe9b

Browse files
Merge commit from fork
Every special-use classifier was built on isInSubnet, which short-circuits to false when the receiver's prefix is shorter than the reference range's. That prefix comes from the CIDR suffix on the parsed input, so a suffix such as /0 suppressed classification entirely: isLoopback, isPrivate, isLinkLocal, isCGNAT, isMulticast, isUnspecified, isBroadcast, isULA, isMapped4, isTeredo, is6to4, isDocumentation and getType all reported internal addresses as unremarkable while correctForm() still returned the real target. Guards built on these checks to block SSRF could be bypassed with '127.0.0.1/0'. The suffix also defeated the IPv4-mapped/NAT64 normalization added in 10.2.1 for GHSA-22jq-vg5j-6vgg, since that path is reached through isInSubnet: '::ffff:127.0.0.1/0' reverted to reading as non-internal. Split the two questions apart. isHostInSubnet compares the address's host bits against the reference range only and backs every classifier; isInSubnet keeps its subnet-containment semantics, including the guard that a wider network is not contained in a narrower one, so '10.0.0.0/8' is still not in '10.0.0.0/16'. Tests assert suffix-independent classification across every prefix length for both families, that public addresses are not newly misclassified, and that containment still rejects wider networks.
1 parent e86ab3e commit 488fe9b

6 files changed

Lines changed: 240 additions & 50 deletions

File tree

‎README.md‎

Lines changed: 32 additions & 30 deletions
Large diffs are not rendered by default.

‎src/common.ts‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,38 @@ export interface ReverseFormOptions {
66
omitSuffix?: boolean;
77
}
88

9+
/**
10+
* Returns whether this address's *network* is contained within `address`,
11+
* i.e. whether every address this one can represent also falls inside
12+
* `address`. A network wider than `address` is not contained in it, so
13+
* `10.0.0.0/8` is not in `10.0.0.0/16`.
14+
*
15+
* To ask whether the address itself falls inside a range, ignoring any CIDR
16+
* suffix it was written with, use {@link isHostInSubnet} instead. That is the
17+
* question the special-use classifiers ask.
18+
*/
919
export function isInSubnet(this: Address4 | Address6, address: Address4 | Address6) {
1020
if (this.subnetMask < address.subnetMask) {
1121
return false;
1222
}
1323

14-
if (this.mask(address.subnetMask) === address.mask()) {
15-
return true;
16-
}
24+
return isHostInSubnet.call(this, address);
25+
}
1726

18-
return false;
27+
/**
28+
* Returns whether this address's host bits fall inside `address`, ignoring
29+
* this address's own subnet mask.
30+
*
31+
* This is the primitive the special-use classifiers (`isLoopback`,
32+
* `isPrivate`, `isLinkLocal`, `getType`, …) are built on: they answer a
33+
* question about the address, so the answer must not change with the CIDR
34+
* suffix the caller happened to write. Use this rather than
35+
* {@link isInSubnet} when classifying a single address — notably when the
36+
* address came from untrusted input and the result backs a trust-boundary
37+
* decision such as an SSRF allow/deny filter.
38+
*/
39+
export function isHostInSubnet(this: Address4 | Address6, address: Address4 | Address6) {
40+
return this.mask(address.subnetMask) === address.mask();
1941
}
2042

2143
export function isCorrect(defaultBits: number) {

‎src/ipv4.ts‎

Lines changed: 15 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -449,60 +449,68 @@ export class Address4 {
449449
*/
450450
isInSubnet = common.isInSubnet;
451451

452+
/**
453+
* Returns true if this address's host bits fall inside the given subnet,
454+
* ignoring this address's own subnet mask. See
455+
* {@link common.isHostInSubnet}.
456+
* @returns {boolean}
457+
*/
458+
isHostInSubnet = common.isHostInSubnet;
459+
452460
/**
453461
* Returns true if the given address is a multicast address
454462
* @returns {boolean}
455463
*/
456464
isMulticast(): boolean {
457-
return this.isInSubnet(MULTICAST_V4);
465+
return this.isHostInSubnet(MULTICAST_V4);
458466
}
459467

460468
/**
461469
* Returns true if the address is in one of the [RFC 1918](https://datatracker.ietf.org/doc/html/rfc1918) private address ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`).
462470
* @returns {boolean}
463471
*/
464472
isPrivate(): boolean {
465-
return PRIVATE_V4.some((subnet) => this.isInSubnet(subnet));
473+
return PRIVATE_V4.some((subnet) => this.isHostInSubnet(subnet));
466474
}
467475

468476
/**
469477
* Returns true if the address is in the loopback range `127.0.0.0/8` ([RFC 1122](https://datatracker.ietf.org/doc/html/rfc1122)).
470478
* @returns {boolean}
471479
*/
472480
isLoopback(): boolean {
473-
return this.isInSubnet(LOOPBACK_V4);
481+
return this.isHostInSubnet(LOOPBACK_V4);
474482
}
475483

476484
/**
477485
* Returns true if the address is in the link-local range `169.254.0.0/16` ([RFC 3927](https://datatracker.ietf.org/doc/html/rfc3927)).
478486
* @returns {boolean}
479487
*/
480488
isLinkLocal(): boolean {
481-
return this.isInSubnet(LINK_LOCAL_V4);
489+
return this.isHostInSubnet(LINK_LOCAL_V4);
482490
}
483491

484492
/**
485493
* Returns true if the address is the unspecified address `0.0.0.0`.
486494
* @returns {boolean}
487495
*/
488496
isUnspecified(): boolean {
489-
return this.isInSubnet(UNSPECIFIED_V4);
497+
return this.isHostInSubnet(UNSPECIFIED_V4);
490498
}
491499

492500
/**
493501
* Returns true if the address is the limited broadcast address `255.255.255.255` ([RFC 919](https://datatracker.ietf.org/doc/html/rfc919)).
494502
* @returns {boolean}
495503
*/
496504
isBroadcast(): boolean {
497-
return this.isInSubnet(BROADCAST_V4);
505+
return this.isHostInSubnet(BROADCAST_V4);
498506
}
499507

500508
/**
501509
* Returns true if the address is in the carrier-grade NAT range `100.64.0.0/10` ([RFC 6598](https://datatracker.ietf.org/doc/html/rfc6598)).
502510
* @returns {boolean}
503511
*/
504512
isCGNAT(): boolean {
505-
return this.isInSubnet(CGNAT_V4);
513+
return this.isHostInSubnet(CGNAT_V4);
506514
}
507515

508516
/**

‎src/ipv6.ts‎

Lines changed: 17 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -567,7 +567,7 @@ export class Address6 {
567567
getType(): string {
568568
for (let i = 0; i < TYPE_SUBNETS.length; i++) {
569569
const entry = TYPE_SUBNETS[i];
570-
if (this.isInSubnet(entry[0])) {
570+
if (this.isHostInSubnet(entry[0])) {
571571
return entry[1];
572572
}
573573
}
@@ -1094,7 +1094,7 @@ export class Address6 {
10941094
throw new AddressError('NAT64 prefix length must be 32, 40, 48, 56, 64, or 96');
10951095
}
10961096

1097-
if (!this.isInSubnet(prefix6)) {
1097+
if (!this.isHostInSubnet(prefix6)) {
10981098
return null;
10991099
}
11001100

@@ -1182,6 +1182,14 @@ export class Address6 {
11821182
*/
11831183
isInSubnet = common.isInSubnet;
11841184

1185+
/**
1186+
* Returns true if this address's host bits fall inside the given subnet,
1187+
* ignoring this address's own subnet mask. See
1188+
* {@link common.isHostInSubnet}.
1189+
* @returns {boolean}
1190+
*/
1191+
isHostInSubnet = common.isHostInSubnet;
1192+
11851193
/**
11861194
* Returns true if the address is correct, false otherwise
11871195
* @returns {boolean}
@@ -1206,7 +1214,7 @@ export class Address6 {
12061214
return embedded.isLinkLocal();
12071215
}
12081216

1209-
// Zeroes are required, i.e. we can't check isInSubnet with 'fe80::/10'
1217+
// Zeroes are required, i.e. we can't check isHostInSubnet with 'fe80::/10'
12101218
if (
12111219
this.getBitsBase2(0, 64) ===
12121220
'1111111010000000000000000000000000000000000000000000000000000000'
@@ -1251,7 +1259,7 @@ export class Address6 {
12511259
* @returns {boolean}
12521260
*/
12531261
isMapped4(): boolean {
1254-
return this.isInSubnet(IPV4_MAPPED_SUBNET);
1262+
return this.isHostInSubnet(IPV4_MAPPED_SUBNET);
12551263
}
12561264

12571265
/**
@@ -1272,7 +1280,7 @@ export class Address6 {
12721280
* @returns {Address4 | null}
12731281
*/
12741282
embeddedIPv4(): Address4 | null {
1275-
if (this.isMapped4() || this.isInSubnet(NAT64_WELL_KNOWN_SUBNET)) {
1283+
if (this.isMapped4() || this.isHostInSubnet(NAT64_WELL_KNOWN_SUBNET)) {
12761284
return this.to4();
12771285
}
12781286

@@ -1284,15 +1292,15 @@ export class Address6 {
12841292
* @returns {boolean}
12851293
*/
12861294
isTeredo(): boolean {
1287-
return this.isInSubnet(TEREDO_SUBNET);
1295+
return this.isHostInSubnet(TEREDO_SUBNET);
12881296
}
12891297

12901298
/**
12911299
* Returns true if the address is a 6to4 address, false otherwise
12921300
* @returns {boolean}
12931301
*/
12941302
is6to4(): boolean {
1295-
return this.isInSubnet(SIX_TO_FOUR_SUBNET);
1303+
return this.isHostInSubnet(SIX_TO_FOUR_SUBNET);
12961304
}
12971305

12981306
/**
@@ -1313,7 +1321,7 @@ export class Address6 {
13131321
* @returns {boolean}
13141322
*/
13151323
isULA(): boolean {
1316-
return this.isInSubnet(ULA_SUBNET);
1324+
return this.isHostInSubnet(ULA_SUBNET);
13171325
}
13181326

13191327
/**
@@ -1387,7 +1395,7 @@ export class Address6 {
13871395
* @returns {boolean}
13881396
*/
13891397
isDocumentation(): boolean {
1390-
return this.isInSubnet(DOCUMENTATION_SUBNET);
1398+
return this.isHostInSubnet(DOCUMENTATION_SUBNET);
13911399
}
13921400
// #endregion
13931401

‎test/functionality-v4-test.ts‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -674,4 +674,65 @@ describe('v4', () => {
674674
});
675675
});
676676
});
677+
678+
describe('classification ignores the address own subnet mask', () => {
679+
// A classifier answers a question about the address, so a CIDR suffix on
680+
// the input must not change the answer. Suffixes shorter than the
681+
// reference range's prefix are the interesting case.
682+
const cases: [string, 'isLoopback' | 'isPrivate' | 'isLinkLocal' | 'isCGNAT' | 'isUnspecified' | 'isBroadcast' | 'isMulticast'][] =
683+
[
684+
['127.0.0.1', 'isLoopback'],
685+
['10.0.0.1', 'isPrivate'],
686+
['172.16.5.5', 'isPrivate'],
687+
['192.168.1.1', 'isPrivate'],
688+
['169.254.169.254', 'isLinkLocal'],
689+
['100.64.0.1', 'isCGNAT'],
690+
['0.0.0.0', 'isUnspecified'],
691+
['255.255.255.255', 'isBroadcast'],
692+
['224.0.0.1', 'isMulticast'],
693+
];
694+
695+
it('classifies the host identically with and without a /0 suffix', () => {
696+
cases.forEach(([notation, method]) => {
697+
should.equal(new Address4(notation)[method](), true, `${notation} ${method}`);
698+
should.equal(new Address4(`${notation}/0`)[method](), true, `${notation}/0 ${method}`);
699+
});
700+
});
701+
702+
it('classifies the host identically for every prefix length', () => {
703+
for (let prefix = 0; prefix <= 32; prefix++) {
704+
should.equal(new Address4(`127.0.0.1/${prefix}`).isLoopback(), true, `/${prefix}`);
705+
should.equal(new Address4(`10.0.0.5/${prefix}`).isPrivate(), true, `/${prefix}`);
706+
should.equal(
707+
new Address4(`169.254.169.254/${prefix}`).isLinkLocal(),
708+
true,
709+
`/${prefix}`,
710+
);
711+
}
712+
});
713+
714+
it('does not start misclassifying public addresses', () => {
715+
for (let prefix = 0; prefix <= 32; prefix++) {
716+
should.equal(new Address4(`8.8.8.8/${prefix}`).isLoopback(), false, `/${prefix}`);
717+
should.equal(new Address4(`8.8.8.8/${prefix}`).isPrivate(), false, `/${prefix}`);
718+
should.equal(new Address4(`8.8.8.8/${prefix}`).isLinkLocal(), false, `/${prefix}`);
719+
should.equal(new Address4(`8.8.8.8/${prefix}`).isCGNAT(), false, `/${prefix}`);
720+
}
721+
});
722+
});
723+
724+
describe('isInSubnet retains subnet-containment semantics', () => {
725+
// isInSubnet answers "is my network inside yours", which is a different
726+
// question from classification and must keep rejecting wider networks.
727+
it('reports a wider network as not contained in a narrower one', () => {
728+
should.equal(new Address4('127.0.0.1/0').isInSubnet(new Address4('127.0.0.0/8')), false);
729+
should.equal(new Address4('10.0.0.0/8').isInSubnet(new Address4('10.0.0.0/16')), false);
730+
});
731+
732+
it('still reports genuine containment', () => {
733+
should.equal(new Address4('10.1.0.0/16').isInSubnet(new Address4('10.0.0.0/8')), true);
734+
should.equal(new Address4('127.0.0.1/32').isInSubnet(new Address4('127.0.0.0/8')), true);
735+
should.equal(new Address4('11.0.0.0/16').isInSubnet(new Address4('10.0.0.0/8')), false);
736+
});
737+
});
677738
});

‎test/functionality-v6-test.ts‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1419,4 +1419,93 @@ describe('v6', () => {
14191419
});
14201420
});
14211421
});
1422+
1423+
describe('classification ignores the address own subnet mask', () => {
1424+
// A classifier answers a question about the address, so a CIDR suffix on
1425+
// the input must not change the answer. Suffixes shorter than the
1426+
// reference range's prefix are the interesting case.
1427+
type Predicate =
1428+
| 'isLoopback'
1429+
| 'isLinkLocal'
1430+
| 'isULA'
1431+
| 'isPrivate'
1432+
| 'isUnspecified'
1433+
| 'isMulticast'
1434+
| 'isMapped4'
1435+
| 'isTeredo'
1436+
| 'is6to4'
1437+
| 'isDocumentation';
1438+
1439+
const cases: [string, Predicate][] = [
1440+
['::1', 'isLoopback'],
1441+
['fe80::1', 'isLinkLocal'],
1442+
['fc00::1', 'isULA'],
1443+
['fc00::1', 'isPrivate'],
1444+
['::', 'isUnspecified'],
1445+
['ff02::1', 'isMulticast'],
1446+
['::ffff:1.2.3.4', 'isMapped4'],
1447+
['2001::1', 'isTeredo'],
1448+
['2002::1', 'is6to4'],
1449+
['2001:db8::1', 'isDocumentation'],
1450+
// IPv4-mapped and NAT64 normalization (GHSA-22jq-vg5j-6vgg) must also
1451+
// survive a suffix, otherwise that fix is trivially undone.
1452+
['::ffff:127.0.0.1', 'isLoopback'],
1453+
['::ffff:10.0.0.1', 'isPrivate'],
1454+
['::ffff:169.254.169.254', 'isLinkLocal'],
1455+
['64:ff9b::7f00:1', 'isLoopback'],
1456+
['64:ff9b::a9fe:a9fe', 'isLinkLocal'],
1457+
];
1458+
1459+
it('classifies the host identically with and without a /0 suffix', () => {
1460+
cases.forEach(([notation, method]) => {
1461+
should.equal(new Address6(notation)[method](), true, `${notation} ${method}`);
1462+
should.equal(new Address6(`${notation}/0`)[method](), true, `${notation}/0 ${method}`);
1463+
});
1464+
});
1465+
1466+
it('classifies the host identically for every prefix length', () => {
1467+
for (let prefix = 0; prefix <= 128; prefix++) {
1468+
should.equal(new Address6(`::1/${prefix}`).isLoopback(), true, `::1/${prefix}`);
1469+
should.equal(new Address6(`fc00::1/${prefix}`).isPrivate(), true, `fc00::1/${prefix}`);
1470+
should.equal(
1471+
new Address6(`::ffff:127.0.0.1/${prefix}`).isLoopback(),
1472+
true,
1473+
`::ffff:127.0.0.1/${prefix}`,
1474+
);
1475+
}
1476+
});
1477+
1478+
it('reports getType by the host bits regardless of suffix', () => {
1479+
should.equal(new Address6('::1/0').getType(), 'Loopback');
1480+
should.equal(new Address6('fe80::1/0').getType(), 'Link-local unicast');
1481+
should.equal(new Address6('fc00::1/0').getType(), 'Unique local');
1482+
should.equal(new Address6('::ffff:127.0.0.1/0').getType(), 'IPv4-mapped');
1483+
});
1484+
1485+
it('does not start misclassifying public addresses', () => {
1486+
for (let prefix = 0; prefix <= 128; prefix++) {
1487+
const address = new Address6(`2001:4860:4860::8888/${prefix}`);
1488+
should.equal(address.isLoopback(), false, `/${prefix}`);
1489+
should.equal(address.isPrivate(), false, `/${prefix}`);
1490+
should.equal(address.isULA(), false, `/${prefix}`);
1491+
should.equal(address.isMulticast(), false, `/${prefix}`);
1492+
should.equal(address.isMapped4(), false, `/${prefix}`);
1493+
}
1494+
});
1495+
});
1496+
1497+
describe('isInSubnet retains subnet-containment semantics', () => {
1498+
// isInSubnet answers "is my network inside yours", which is a different
1499+
// question from classification and must keep rejecting wider networks.
1500+
it('reports a wider network as not contained in a narrower one', () => {
1501+
should.equal(new Address6('::1/0').isInSubnet(new Address6('::1/128')), false);
1502+
should.equal(new Address6('fc00::/7').isInSubnet(new Address6('fc00::/16')), false);
1503+
});
1504+
1505+
it('still reports genuine containment', () => {
1506+
should.equal(new Address6('fc00::/16').isInSubnet(new Address6('fc00::/7')), true);
1507+
should.equal(new Address6('::1/128').isInSubnet(new Address6('::/0')), true);
1508+
should.equal(new Address6('2001::/16').isInSubnet(new Address6('fc00::/7')), false);
1509+
});
1510+
});
14221511
});

0 commit comments

Comments
 (0)