teleportxr 1.0.89 → 1.0.90

package/client/avatar_service.js

@@ -1,26 +1,34 @@
 'use strict';
-// Per-client server-side state for avatar negotiation. Phase 2 of the
-// implementation in plans/avatars_implementation.md: round-trip a policy,
-// receive an offer, always reply with using_default. No validation, no
-// download, no import. Behaviour is the same regardless of whether the
-// client offered an avatar or not.
+// Per-client server-side state for avatar negotiation. Phase 3 of the
+// implementation in plans/avatars_implementation.md: hand an offered
+// URL to an IAvatarValidator and surface its verdict. With no
+// validator wired the service falls back to the Phase-2 behaviour
+// (always reply using_default), so existing deployments keep working.
 //
 // One AvatarService is owned by each Client; messages are dispatched in
 // from the signaling layer.
 
 const avatars = require('../protocol/avatars.js');
 
+// Threshold above which a 'pending' frame is sent so the client can
+// show progress (plan §4.1 / §9). Picked to be just under one second
+// so the UX never feels stuck.
+const PENDING_DELAY_MS = 750;
+
 function envelope(type, content) {
 	return JSON.stringify({ 'teleport-signal-type': type, content });
 }
 
 class AvatarService {
-	constructor(clientID, sigSend) {
+	constructor(clientID, sigSend, opts) {
 		this.clientID		= clientID;
 		this.sigSend		= sigSend;
 		this.currentPolicy	= null;
 		this.lastOffer		= null;
 		this.lastResult		= null;
+		// Optional IAvatarValidator. When null the service keeps its
+		// Phase-2 behaviour: any offer is answered with using_default.
+		this.validator		= (opts && opts.validator) || null;
 	}
 
 	// Send (or re-send) the policy to the owning client. The client is
@@ -36,17 +44,17 @@ class AvatarService {
 		this.sigSend(envelope(avatars.TELEPORT_SIGNAL_TYPE_AVATAR_POLICY, content));
 	}
 
-	// Handle an incoming avatar-offer. Phase 2 always replies using_default.
-	handleOffer(offerJson) {
+	// Handle an incoming avatar-offer. With no validator wired the
+	// service replies using_default exactly as Phase 2 did; with a
+	// validator the offered URL is fetched, hashed and measured, and
+	// the verdict is reported back.
+	async handleOffer(offerJson) {
 		const offer = avatars.parseAvatarOffer(offerJson);
 		this.lastOffer = offer;
 		console.log('avatar-offer  ← client ' + this.clientID +
 			' policy_id=' + offer.policy_id +
 			' have_avatar=' + offer.have_avatar);
 
-		// If we have not sent a policy, or the offer references a different
-		// policy_id, reject so the client knows it is talking about something
-		// the server does not currently care about.
 		if (!this.currentPolicy ||
 			BigInt(offer.policy_id || 0n) !== BigInt(this.currentPolicy.policy_id))
 		{
@@ -61,16 +69,72 @@ class AvatarService {
 			return;
 		}
 
-		// Phase 2: regardless of what the client offered, the server uses its
-		// default avatar. node_uid is 0 because no real node has been imported.
-		this._reply({
-			policy_id:		offer.policy_id,
-			status:			'using_default',
-			node_uid:		0n,
-			using_default:	true,
-			delivery:		'import',
-			reasons:		[],
-		});
+		// Without a validator, or without an offered URL, fall straight
+		// back to the default avatar (this is also the Phase-2 path).
+		if (!this.validator || !offer.have_avatar || !offer.url) {
+			this._reply({
+				policy_id:		offer.policy_id,
+				status:			'using_default',
+				node_uid:		0n,
+				using_default:	true,
+				delivery:		'import',
+				reasons:		[],
+			});
+			return;
+		}
+
+		// Long-running validation gets a 'pending' status so the client
+		// can show progress instead of appearing to hang (plan §4.1).
+		let pendingSent = false;
+		const pendingTimer = setTimeout(() => {
+			pendingSent = true;
+			this._reply({
+				policy_id:		offer.policy_id,
+				status:			'pending',
+				node_uid:		0n,
+				using_default:	false,
+				delivery:		'import',
+				reasons:		[],
+			}, /*record*/ false);
+		}, PENDING_DELAY_MS);
+
+		let result;
+		try {
+			result = await this.validator.validate(offer, this.currentPolicy.requirements || {});
+		} catch (err) {
+			result = { ok: false, reasons: ['validator_error'], bytes: 0, contentHash: '', format: '' };
+		}
+		clearTimeout(pendingTimer);
+
+		if (result.ok) {
+			this._reply({
+				policy_id:		offer.policy_id,
+				status:			'accepted',
+				node_uid:		0n,
+				using_default:	false,
+				delivery:		'import',
+				reasons:		[],
+			});
+		} else if (this.currentPolicy.default_available) {
+			this._reply({
+				policy_id:		offer.policy_id,
+				status:			'using_default',
+				node_uid:		0n,
+				using_default:	true,
+				delivery:		'import',
+				reasons:		result.reasons || [],
+			});
+		} else {
+			this._reply({
+				policy_id:		offer.policy_id,
+				status:			'rejected',
+				node_uid:		0n,
+				using_default:	false,
+				delivery:		'import',
+				reasons:		result.reasons || ['validation_failed'],
+			});
+		}
+		void pendingSent;
 	}
 
 	// Handle a client-initiated revoke (rare in Phase 2; provided for
@@ -86,9 +150,9 @@ class AvatarService {
 		this.lastResult = null;
 	}
 
-	_reply(result) {
+	_reply(result, record = true) {
 		const content = avatars.encodeAvatarResult(result);
-		this.lastResult = content;
+		if (record) this.lastResult = content;
 		console.log('avatar-result → client ' + this.clientID +
 			' status=' + content.status +
 			' delivery=' + content.delivery +

package/client/avatar_validator.js

@@ -0,0 +1,332 @@
+'use strict';
+// Phase 3 of the avatar implementation plan: server-side validation of
+// avatar URLs supplied in avatar-offer. Goal is real download, real
+// measurement, real rejection reasons. Bytes never leave this process
+// — Phase 3 still has no peer visibility.
+//
+// IAvatarValidator is the pluggable interface; DefaultAvatarValidator is
+// a node-only implementation that uses node:https for full control over
+// the transport (so SSRF and byte/time limits can be enforced before any
+// peer protocol code sees the bytes). Tests substitute a fake fetcher
+// via the constructor so they don't have to hit the network.
+
+const crypto	= require('node:crypto');
+const dns		= require('node:dns');
+const https		= require('node:https');
+const http		= require('node:http');
+const net		= require('node:net');
+const { URL }	= require('node:url');
+
+// SSRF blocklist ------------------------------------------------------
+// Mirrors plans/avatars_plan.md §7 (SSRF row) and §5 V3. Refuses
+// loopback, link-local, private, broadcast, metadata-service and the
+// "this network" range. IPv6: refuses loopback, link-local, ULA, and
+// IPv4-mapped addresses (which would re-enter the v4 blocklist).
+function isBlockedIp(ip)
+{
+	if (typeof ip !== 'string' || !ip.length)
+		return true;
+	const family = net.isIP(ip);
+	if (family === 4)
+	{
+		const o = ip.split('.').map(Number);
+		if (o.length !== 4 || o.some(b => !Number.isFinite(b) || b < 0 || b > 255))
+			return true;
+		if (o[0] === 0)									return true; // "this" net
+		if (o[0] === 10)								return true; // RFC1918
+		if (o[0] === 127)								return true; // loopback
+		if (o[0] === 169 && o[1] === 254)				return true; // link-local + AWS metadata
+		if (o[0] === 172 && o[1] >= 16 && o[1] <= 31)	return true; // RFC1918
+		if (o[0] === 192 && o[1] === 168)				return true; // RFC1918
+		if (o[0] === 192 && o[1] === 0   && o[2] === 0)	return true; // IETF protocol
+		if (o[0] === 198 && (o[1] === 18 || o[1] === 19)) return true; // benchmarking
+		if (o[0] >= 224)								return true; // multicast + reserved
+		return false;
+	}
+	if (family === 6)
+	{
+		const lo = ip.toLowerCase();
+		if (lo === '::1' || lo === '::')				return true;
+		if (lo.startsWith('fe80:') || lo.startsWith('fe80::')) return true; // link-local
+		if (lo.startsWith('fc') || lo.startsWith('fd'))	return true; // ULA fc00::/7
+		if (lo.startsWith('ff'))						return true; // multicast
+		if (lo.startsWith('::ffff:'))					return true; // v4-mapped
+		return false;
+	}
+	return true;
+}
+
+// Resolve a hostname to a single IP and check it against the blocklist.
+// Returns the resolved address on success; throws with a code that maps
+// to one of the avatar-result reason codes on failure.
+function resolveAndCheck(hostname)
+{
+	return new Promise((resolve, reject) =>
+	{
+		// If the hostname is already a literal IP, validate directly.
+		if (net.isIP(hostname))
+		{
+			if (isBlockedIp(hostname))
+				return reject(Object.assign(new Error('ssrf_blocked'), { code: 'ssrf_blocked' }));
+			return resolve(hostname);
+		}
+		dns.lookup(hostname, { verbatim: true }, (err, address) =>
+		{
+			if (err)
+				return reject(Object.assign(new Error('dns_failed'), { code: 'download_failed' }));
+			if (isBlockedIp(address))
+				return reject(Object.assign(new Error('ssrf_blocked'), { code: 'ssrf_blocked' }));
+			resolve(address);
+		});
+	});
+}
+
+// Default fetcher --------------------------------------------------
+// Streams the response body, hashing as it goes and aborting the
+// connection as soon as `maxBytes` would be exceeded so that a hostile
+// origin cannot trickle gigabytes. Honours `maxRedirects` and re-runs
+// the SSRF check at every hop. Returns { ok, status, body, sha256,
+// finalUrl, reason } where `body` is a Buffer trimmed to maxBytes.
+function defaultFetcher(opts)
+{
+	const { url, maxBytes, timeoutMs, maxRedirects, allowedSchemes } = opts;
+	// Tests can inject a permissive resolver so the loopback-bound
+	// scratch server they spin up isn't rejected by the SSRF guard.
+	const resolver = opts.resolver || resolveAndCheck;
+	return new Promise((resolve) =>
+	{
+		const visited = new Set();
+		const start = Date.now();
+
+		const attempt = (currentUrl, hopsLeft) =>
+		{
+			let u;
+			try { u = new URL(currentUrl); }
+			catch (e) { return resolve({ ok: false, reason: 'invalid_url' }); }
+
+			if (!allowedSchemes.includes(u.protocol))
+				return resolve({ ok: false, reason: 'scheme_not_allowed' });
+			if (visited.has(u.href))
+				return resolve({ ok: false, reason: 'redirect_loop' });
+			visited.add(u.href);
+
+			resolver(u.hostname).then((ip) =>
+			{
+				const lib = u.protocol === 'http:' ? http : https;
+				const port = u.port ? Number(u.port) : (u.protocol === 'http:' ? 80 : 443);
+				const remaining = Math.max(1, timeoutMs - (Date.now() - start));
+				const req = lib.request({
+					host:		ip,
+					port:		port,
+					path:		u.pathname + u.search,
+					method:		'GET',
+					servername:	u.hostname,	// SNI/SAN check still uses real host
+					headers:	{ host: u.hostname, 'user-agent': 'teleportxr-avatar-validator/1' },
+					timeout:	remaining,
+				}, (res) =>
+				{
+					// Follow redirects with the same SSRF check at every hop.
+					if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location)
+					{
+						res.resume();
+						if (hopsLeft <= 0)
+							return resolve({ ok: false, reason: 'too_many_redirects' });
+						const next = new URL(res.headers.location, u).href;
+						return attempt(next, hopsLeft - 1);
+					}
+					if (res.statusCode !== 200)
+					{
+						res.resume();
+						return resolve({ ok: false, reason: 'http_' + res.statusCode });
+					}
+					const hash = crypto.createHash('sha256');
+					const chunks = [];
+					let total = 0;
+					let aborted = false;
+					res.on('data', (chunk) =>
+					{
+						if (aborted) return;
+						total += chunk.length;
+						if (total > maxBytes)
+						{
+							aborted = true;
+							req.destroy();
+							return resolve({ ok: false, reason: 'file_too_large' });
+						}
+						hash.update(chunk);
+						chunks.push(chunk);
+					});
+					res.on('end', () =>
+					{
+						if (aborted) return;
+						resolve({
+							ok:			true,
+							status:		200,
+							body:		Buffer.concat(chunks, total),
+							sha256:		hash.digest('hex'),
+							finalUrl:	u.href,
+						});
+					});
+					res.on('error', () =>
+					{
+						if (!aborted) resolve({ ok: false, reason: 'download_failed' });
+					});
+				});
+				req.on('timeout', () => { req.destroy(); resolve({ ok: false, reason: 'fetch_timeout' }); });
+				req.on('error', () => resolve({ ok: false, reason: 'download_failed' }));
+				req.end();
+			}).catch((err) =>
+			{
+				resolve({ ok: false, reason: err.code || 'download_failed' });
+			});
+		};
+
+		attempt(url, maxRedirects);
+	});
+}
+
+// LRU cache --------------------------------------------------------
+// Bounded by both entry count and total bytes. Maps content_hash → a
+// frozen validation result so two clients submitting the same URL do
+// not cause two fetches (plan §5 V5, §9). Map preserves insertion order
+// so we can evict the oldest by simply re-inserting on access.
+class LruCache
+{
+	constructor(maxEntries, maxBytes)
+	{
+		this.maxEntries	= Math.max(1, maxEntries | 0);
+		this.maxBytes	= Math.max(0, maxBytes | 0);
+		this.map		= new Map();
+		this.bytes		= 0;
+	}
+	get(key)
+	{
+		if (!this.map.has(key)) return undefined;
+		const v = this.map.get(key);
+		this.map.delete(key); this.map.set(key, v);
+		return v;
+	}
+	set(key, value, bytes)
+	{
+		if (this.map.has(key))
+		{
+			this.bytes -= this.map.get(key)._bytes || 0;
+			this.map.delete(key);
+		}
+		const stored = Object.assign({}, value, { _bytes: bytes });
+		this.map.set(key, stored);
+		this.bytes += bytes;
+		while (this.map.size > this.maxEntries || this.bytes > this.maxBytes)
+		{
+			const first = this.map.keys().next().value;
+			if (first === undefined) break;
+			this.bytes -= this.map.get(first)._bytes || 0;
+			this.map.delete(first);
+		}
+	}
+	get size() { return this.map.size; }
+}
+
+// Sniff the leading bytes to confirm the declared format. Phase 3
+// supports GLB (binary glTF) by magic + glTF (JSON) by leading brace.
+// Anything else is passed through as ok=true; the host-supplied
+// validator can do stricter checking. Returns the canonical short name.
+function sniffFormat(buf)
+{
+	if (!buf || buf.length < 4) return '';
+	if (buf[0] === 0x67 && buf[1] === 0x6C && buf[2] === 0x54 && buf[3] === 0x46)
+		return 'glb';
+	// Skip BOM, whitespace.
+	let i = 0;
+	if (buf.length >= 3 && buf[0] === 0xEF && buf[1] === 0xBB && buf[2] === 0xBF) i = 3;
+	while (i < buf.length && (buf[i] === 0x20 || buf[i] === 0x09 || buf[i] === 0x0A || buf[i] === 0x0D)) i++;
+	if (i < buf.length && buf[i] === 0x7B) return 'gltf';
+	return '';
+}
+
+// IAvatarValidator -------------------------------------------------
+// Reference interface; subclass and override `validate`. The default
+// implementation below is sufficient for the Phase 3 exit criteria;
+// host applications that want a stricter pipeline (e.g. real glTF
+// parse, triangle count, proof check) supply their own.
+class IAvatarValidator
+{
+	async validate(/* offer, requirements */)
+	{
+		throw new Error('IAvatarValidator.validate is abstract');
+	}
+}
+
+class DefaultAvatarValidator extends IAvatarValidator
+{
+	constructor(opts = {})
+	{
+		super();
+		this.allowedSchemes		= opts.allowedSchemes		|| ['https:'];
+		this.maxRedirects		= opts.maxRedirects ?? 3;
+		this.defaultMaxBytes	= opts.defaultMaxBytes		|| 10 * 1024 * 1024;
+		this.defaultTimeoutMs	= opts.defaultTimeoutMs		|| 15000;
+		this.fetcher			= opts.fetcher				|| defaultFetcher;
+		this.cache				= opts.cache				|| new LruCache(opts.cacheEntries || 256, opts.cacheBytes || 256 * 1024 * 1024);
+	}
+
+	async validate(offer, requirements)
+	{
+		const reasons	= [];
+		const req		= requirements || {};
+		const formats	= Array.isArray(req.formats) ? req.formats.map(s => String(s).toLowerCase()) : [];
+		const maxBytes	= Number.isFinite(req.max_file_bytes) ? Math.min(req.max_file_bytes, this.defaultMaxBytes) : this.defaultMaxBytes;
+		const timeoutMs	= Number.isFinite(req.fetch_timeout_ms) ? req.fetch_timeout_ms : this.defaultTimeoutMs;
+
+		// Cheap pre-flight checks before spending a TCP connection.
+		if (!offer || !offer.url || typeof offer.url !== 'string')
+			return { ok: false, reasons: ['no_url'], bytes: 0, contentHash: '', format: '' };
+		const declared = offer.declared || {};
+		if (formats.length && declared.format && !formats.includes(String(declared.format).toLowerCase()))
+			return { ok: false, reasons: ['format_not_allowed'], bytes: 0, contentHash: '', format: declared.format };
+		if (declared.file_bytes && declared.file_bytes > maxBytes)
+			return { ok: false, reasons: ['file_too_large'], bytes: declared.file_bytes, contentHash: '', format: declared.format || '' };
+
+		// Cache hit on declared content_hash short-circuits the fetch.
+		if (offer.content_hash && this.cache.get(offer.content_hash))
+		{
+			const cached = this.cache.get(offer.content_hash);
+			return { ok: cached.ok, reasons: cached.reasons.slice(), bytes: cached.bytes, contentHash: offer.content_hash, format: cached.format, fromCache: true };
+		}
+
+		const fetched = await this.fetcher({
+			url:				offer.url,
+			maxBytes:			maxBytes,
+			timeoutMs:			timeoutMs,
+			maxRedirects:		this.maxRedirects,
+			allowedSchemes:		this.allowedSchemes,
+		});
+		if (!fetched.ok)
+			return { ok: false, reasons: [fetched.reason || 'download_failed'], bytes: 0, contentHash: '', format: '' };
+
+		const bytes			= fetched.body.length;
+		const contentHash	= 'sha256:' + fetched.sha256;
+		const sniffed		= sniffFormat(fetched.body);
+		const format		= sniffed || (declared.format || '').toLowerCase();
+
+		if (offer.content_hash && offer.content_hash !== contentHash)
+			reasons.push('hash_mismatch');
+		if (formats.length && format && !formats.includes(format))
+			reasons.push('format_not_allowed');
+		if (bytes > maxBytes)
+			reasons.push('file_too_large');
+
+		const ok = reasons.length === 0;
+		const result = { ok, reasons: reasons.slice(), bytes, contentHash, format };
+		this.cache.set(contentHash, result, bytes);
+		return result;
+	}
+}
+
+module.exports.isBlockedIp				= isBlockedIp;
+module.exports.resolveAndCheck			= resolveAndCheck;
+module.exports.defaultFetcher			= defaultFetcher;
+module.exports.LruCache					= LruCache;
+module.exports.sniffFormat				= sniffFormat;
+module.exports.IAvatarValidator			= IAvatarValidator;
+module.exports.DefaultAvatarValidator	= DefaultAvatarValidator;

package/package.json

@@ -16,7 +16,7 @@
   },
   "name": "teleportxr",
   "description": "Teleport Spatial Server on node.js",
-  "version": "1.0.89",
+  "version": "1.0.90",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/simul/teleport-nodejs.git"
@@ -33,6 +33,7 @@
     "./client/client": "./client/client.js",
     "./client/client_manager": "./client/client_manager.js",
     "./client/avatar_service": "./client/avatar_service.js",
+    "./client/avatar_validator": "./client/avatar_validator.js",
     "./connections/webrtcconnectionmanager": "./connections/webrtcconnectionmanager.js",
     "./protocol/avatars": "./protocol/avatars.js",
     "./scene/scene": "./scene/scene.js",

package/test/test_avatar_service.js

@@ -103,6 +103,81 @@ test('handleRevoke clears cached offer state without emitting anything', () => {
 	assert.strictEqual(svc.lastResult, null);
 });
 
+// Phase-3 integration: when a validator is wired in, the service runs
+// the offered URL through it and reports the verdict instead of always
+// falling back to using_default.
+
+function makeValidator(verdict) {
+	return { validate: async () => verdict };
+}
+
+test('handleOffer with validator: accepted result emits status=accepted', async () => {
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send, {
+		validator: makeValidator({ ok: true, reasons: [], bytes: 100, contentHash: 'sha256:aa', format: 'glb' }),
+	});
+	svc.sendPolicy(new avatars.AvatarPolicy({ policy_id: 11n, default_available: true }));
+	sink.sent.length = 0;
+	await svc.handleOffer({ policy_id: 11, have_avatar: true, url: 'https://x/a.glb', declared: { format: 'glb' } });
+	const msg = sink.sent[sink.sent.length - 1];
+	assert.strictEqual(msg.content.status, 'accepted');
+	assert.strictEqual(msg.content.using_default, false);
+	assert.deepStrictEqual(msg.content.reasons, []);
+});
+
+test('handleOffer with validator: failure falls back to using_default when default_available', async () => {
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send, {
+		validator: makeValidator({ ok: false, reasons: ['file_too_large'], bytes: 0, contentHash: '', format: '' }),
+	});
+	svc.sendPolicy(new avatars.AvatarPolicy({ policy_id: 12n, default_available: true }));
+	sink.sent.length = 0;
+	await svc.handleOffer({ policy_id: 12, have_avatar: true, url: 'https://x/big.glb', declared: { format: 'glb' } });
+	const msg = sink.sent[sink.sent.length - 1];
+	assert.strictEqual(msg.content.status, 'using_default');
+	assert.strictEqual(msg.content.using_default, true);
+	assert.deepStrictEqual(msg.content.reasons, ['file_too_large']);
+});
+
+test('handleOffer with validator: failure becomes rejected when default_available=false', async () => {
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send, {
+		validator: makeValidator({ ok: false, reasons: ['ssrf_blocked'], bytes: 0, contentHash: '', format: '' }),
+	});
+	svc.sendPolicy(new avatars.AvatarPolicy({ policy_id: 13n, default_available: false }));
+	sink.sent.length = 0;
+	await svc.handleOffer({ policy_id: 13, have_avatar: true, url: 'https://x/local', declared: { format: 'glb' } });
+	const msg = sink.sent[sink.sent.length - 1];
+	assert.strictEqual(msg.content.status, 'rejected');
+	assert.deepStrictEqual(msg.content.reasons, ['ssrf_blocked']);
+});
+
+test('handleOffer with validator: have_avatar=false still replies using_default without calling validator', async () => {
+	const sink = makeSink();
+	let called = false;
+	const svc  = new avatar_service.AvatarService(42n, sink.send, {
+		validator: { validate: async () => { called = true; return { ok: true }; } },
+	});
+	svc.sendPolicy(new avatars.AvatarPolicy({ policy_id: 14n, default_available: true }));
+	sink.sent.length = 0;
+	await svc.handleOffer({ policy_id: 14, have_avatar: false });
+	assert.strictEqual(called, false);
+	assert.strictEqual(sink.sent[0].content.status, 'using_default');
+});
+
+test('handleOffer with validator: thrown validator error reports validator_error', async () => {
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send, {
+		validator: { validate: async () => { throw new Error('boom'); } },
+	});
+	svc.sendPolicy(new avatars.AvatarPolicy({ policy_id: 15n, default_available: false }));
+	sink.sent.length = 0;
+	await svc.handleOffer({ policy_id: 15, have_avatar: true, url: 'https://x/a.glb', declared: { format: 'glb' } });
+	const msg = sink.sent[sink.sent.length - 1];
+	assert.strictEqual(msg.content.status, 'rejected');
+	assert.deepStrictEqual(msg.content.reasons, ['validator_error']);
+});
+
 test('signaling dispatch: avatar-offer routed to handleAvatarOffer', () => {
 	// Round-trip the dispatch path: build a SignalingClient stub, attach a
 	// handler, and feed it a JSON frame. Reaching into the module the same

package/test/test_avatar_validator.js

@@ -0,0 +1,330 @@
+'use strict';
+// Tests for the Phase-3 avatar validator. The SSRF blocklist and LRU
+// cache are exercised directly; the DefaultAvatarValidator is driven
+// with an injected fake fetcher so the network is never touched. This
+// matches the rest of teleport-nodejs/test/, which uses node:test
+// rather than Jest.
+
+const test		= require('node:test');
+const assert	= require('node:assert');
+
+const validator = require('../client/avatar_validator.js');
+
+// SSRF blocklist ---------------------------------------------------
+
+test('isBlockedIp: refuses loopback and private v4 ranges', () => {
+	assert.strictEqual(validator.isBlockedIp('127.0.0.1'), true);
+	assert.strictEqual(validator.isBlockedIp('10.1.2.3'), true);
+	assert.strictEqual(validator.isBlockedIp('172.16.0.1'), true);
+	assert.strictEqual(validator.isBlockedIp('172.31.255.255'), true);
+	assert.strictEqual(validator.isBlockedIp('192.168.0.1'), true);
+	assert.strictEqual(validator.isBlockedIp('169.254.169.254'), true);
+	assert.strictEqual(validator.isBlockedIp('0.0.0.0'), true);
+	assert.strictEqual(validator.isBlockedIp('224.0.0.1'), true);
+});
+
+test('isBlockedIp: allows public v4 addresses', () => {
+	assert.strictEqual(validator.isBlockedIp('8.8.8.8'), false);
+	assert.strictEqual(validator.isBlockedIp('1.1.1.1'), false);
+	assert.strictEqual(validator.isBlockedIp('172.15.0.1'), false);
+	assert.strictEqual(validator.isBlockedIp('172.32.0.1'), false);
+});
+
+test('isBlockedIp: refuses loopback, link-local and ULA v6', () => {
+	assert.strictEqual(validator.isBlockedIp('::1'), true);
+	assert.strictEqual(validator.isBlockedIp('fe80::1'), true);
+	assert.strictEqual(validator.isBlockedIp('fd00::1'), true);
+	assert.strictEqual(validator.isBlockedIp('ff02::1'), true);
+	assert.strictEqual(validator.isBlockedIp('::ffff:127.0.0.1'), true);
+});
+
+test('isBlockedIp: rejects garbage', () => {
+	assert.strictEqual(validator.isBlockedIp(''), true);
+	assert.strictEqual(validator.isBlockedIp('not-an-ip'), true);
+	assert.strictEqual(validator.isBlockedIp(null), true);
+});
+
+// LRU cache --------------------------------------------------------
+
+test('LruCache evicts the oldest entry beyond maxEntries', () => {
+	const c = new validator.LruCache(2, 1 << 20);
+	c.set('a', { ok: true }, 1);
+	c.set('b', { ok: true }, 1);
+	c.set('c', { ok: true }, 1);
+	assert.strictEqual(c.size, 2);
+	assert.strictEqual(c.get('a'), undefined);
+	assert.ok(c.get('b'));
+	assert.ok(c.get('c'));
+});
+
+test('LruCache evicts to honour maxBytes', () => {
+	const c = new validator.LruCache(100, 10);
+	c.set('a', { ok: true }, 8);
+	c.set('b', { ok: true }, 5);
+	assert.strictEqual(c.get('a'), undefined);
+	assert.ok(c.get('b'));
+});
+
+test('LruCache get() refreshes recency', () => {
+	const c = new validator.LruCache(2, 1 << 20);
+	c.set('a', { ok: true }, 1);
+	c.set('b', { ok: true }, 1);
+	c.get('a');								// promote 'a'
+	c.set('c', { ok: true }, 1);			// evicts 'b', not 'a'
+	assert.ok(c.get('a'));
+	assert.strictEqual(c.get('b'), undefined);
+});
+
+// sniffFormat ------------------------------------------------------
+
+test('sniffFormat recognises GLB magic', () => {
+	const glb = Buffer.from([0x67, 0x6C, 0x54, 0x46, 0x02, 0, 0, 0]);
+	assert.strictEqual(validator.sniffFormat(glb), 'glb');
+});
+
+test('sniffFormat recognises JSON glTF', () => {
+	assert.strictEqual(validator.sniffFormat(Buffer.from('  {\n"asset":{}}')), 'gltf');
+	assert.strictEqual(validator.sniffFormat(Buffer.from('\uFEFF{"a":1}')), 'gltf');
+});
+
+test('sniffFormat returns empty for unknown payloads', () => {
+	assert.strictEqual(validator.sniffFormat(Buffer.from('NOPE')), '');
+	assert.strictEqual(validator.sniffFormat(Buffer.alloc(0)), '');
+});
+
+// DefaultAvatarValidator with an injected fetcher ----------------
+// The fetcher contract is just `({ url, maxBytes, ... }) → { ok, body,
+// sha256, ... }`. By injecting one we keep the tests offline and
+// deterministic.
+function makeBody(text) {
+	const crypto = require('node:crypto');
+	const body = Buffer.from(text);
+	const sha256 = crypto.createHash('sha256').update(body).digest('hex');
+	return { body, sha256 };
+}
+function fakeFetcher(map) {
+	return async (opts) => {
+		const next = map[opts.url];
+		if (typeof next === 'function') return next(opts);
+		if (!next) return { ok: false, reason: 'download_failed' };
+		return next;
+	};
+}
+
+test('DefaultAvatarValidator: happy path returns ok with the computed hash', async () => {
+	const { body, sha256 } = makeBody(
+		String.fromCharCode(0x67, 0x6C, 0x54, 0x46) + 'binary-glb-body');
+	const v = new validator.DefaultAvatarValidator({
+		fetcher: fakeFetcher({
+			'https://x/avatar.glb': { ok: true, body, sha256, finalUrl: 'https://x/avatar.glb' },
+		}),
+	});
+	const r = await v.validate(
+		{ url: 'https://x/avatar.glb', declared: { format: 'glb' } },
+		{ formats: ['glb'], max_file_bytes: 1 << 20 });
+	assert.strictEqual(r.ok, true);
+	assert.strictEqual(r.format, 'glb');
+	assert.strictEqual(r.contentHash, 'sha256:' + sha256);
+	assert.deepStrictEqual(r.reasons, []);
+});
+
+test('DefaultAvatarValidator: rejects declared format outside allow-list before fetching', async () => {
+	let fetched = false;
+	const v = new validator.DefaultAvatarValidator({
+		fetcher: async () => { fetched = true; return { ok: true, body: Buffer.alloc(0), sha256: '' }; },
+	});
+	const r = await v.validate(
+		{ url: 'https://x/a.fbx', declared: { format: 'fbx' } },
+		{ formats: ['glb', 'vrm'] });
+	assert.strictEqual(r.ok, false);
+	assert.deepStrictEqual(r.reasons, ['format_not_allowed']);
+	assert.strictEqual(fetched, false);
+});
+
+test('DefaultAvatarValidator: rejects oversized declared file before fetching', async () => {
+	let fetched = false;
+	const v = new validator.DefaultAvatarValidator({
+		fetcher: async () => { fetched = true; return { ok: true, body: Buffer.alloc(0), sha256: '' }; },
+	});
+	const r = await v.validate(
+		{ url: 'https://x/a.glb', declared: { format: 'glb', file_bytes: 1_000_000 } },
+		{ formats: ['glb'], max_file_bytes: 100 });
+	assert.strictEqual(r.ok, false);
+	assert.deepStrictEqual(r.reasons, ['file_too_large']);
+	assert.strictEqual(fetched, false);
+});
+
+test('DefaultAvatarValidator: surfaces a content_hash mismatch', async () => {
+	const { body, sha256 } = makeBody(
+		String.fromCharCode(0x67, 0x6C, 0x54, 0x46) + 'real-bytes');
+	const v = new validator.DefaultAvatarValidator({
+		fetcher: fakeFetcher({ 'https://x/a.glb': { ok: true, body, sha256 } }),
+	});
+	const r = await v.validate(
+		{ url: 'https://x/a.glb', declared: { format: 'glb' }, content_hash: 'sha256:deadbeef' },
+		{ formats: ['glb'] });
+	assert.strictEqual(r.ok, false);
+	assert.ok(r.reasons.includes('hash_mismatch'));
+	// Hash on the result is the actual computed hash, not the claimed one.
+	assert.strictEqual(r.contentHash, 'sha256:' + sha256);
+});
+
+test('DefaultAvatarValidator: maps fetcher failure reasons through', async () => {
+	const v = new validator.DefaultAvatarValidator({
+		fetcher: fakeFetcher({ 'https://x/a.glb': { ok: false, reason: 'ssrf_blocked' } }),
+	});
+	const r = await v.validate({ url: 'https://x/a.glb', declared: { format: 'glb' } }, { formats: ['glb'] });
+	assert.strictEqual(r.ok, false);
+	assert.deepStrictEqual(r.reasons, ['ssrf_blocked']);
+});
+
+test('DefaultAvatarValidator: cache hit on content_hash skips the fetcher', async () => {
+	const { body, sha256 } = makeBody(
+		String.fromCharCode(0x67, 0x6C, 0x54, 0x46) + 'cached');
+	let fetches = 0;
+	const v = new validator.DefaultAvatarValidator({
+		fetcher: async () => { fetches++; return { ok: true, body, sha256 }; },
+	});
+	const offer = { url: 'https://x/c.glb', declared: { format: 'glb' } };
+	const first = await v.validate(offer, { formats: ['glb'] });
+	assert.strictEqual(first.ok, true);
+	assert.strictEqual(fetches, 1);
+	const second = await v.validate(
+		{ url: 'https://x/c.glb', declared: { format: 'glb' }, content_hash: first.contentHash },
+		{ formats: ['glb'] });
+	assert.strictEqual(second.ok, true);
+	assert.strictEqual(second.fromCache, true);
+	assert.strictEqual(fetches, 1);
+});
+
+
+// defaultFetcher against a local http server -----------------------
+// Exercises the real transport path (node:http with the byte cap,
+// timeout and redirect follower) by binding a server to 127.0.0.1.
+// The defaultFetcher's SSRF guard is bypassed for these tests via the
+// `resolver` injection point — see the dedicated SSRF guard test below
+// for the real-blocklist path.
+
+const http = require('node:http');
+
+function withServer(handler, fn) {
+	return new Promise((resolve, reject) => {
+		const srv = http.createServer(handler);
+		srv.listen(0, '127.0.0.1', async () => {
+			const port = srv.address().port;
+			try {
+				const out = await fn(port);
+				srv.close(() => resolve(out));
+			} catch (err) {
+				srv.close(() => reject(err));
+			}
+		});
+	});
+}
+
+// Permissive resolver used for the loopback tests: returns whatever it
+// was asked for without consulting DNS or the blocklist.
+const permissiveResolver = (host) => Promise.resolve(host);
+
+test('fetcher: happy-path GET returns body + sha256', async () => {
+	const body = Buffer.from([0x67, 0x6C, 0x54, 0x46, 1, 2, 3, 4, 5, 6, 7, 8]);
+	await withServer((req, res) => { res.writeHead(200, { 'content-type': 'model/gltf-binary' }); res.end(body); }, async (port) => {
+		const r = await validator.defaultFetcher({
+			url: 'http://127.0.0.1:' + port + '/a.glb', maxBytes: 1 << 16,
+			timeoutMs: 5000, maxRedirects: 0, allowedSchemes: ['http:'],
+			resolver: permissiveResolver,
+		});
+		assert.strictEqual(r.ok, true);
+		assert.strictEqual(r.body.length, body.length);
+		assert.strictEqual(r.sha256, require('node:crypto').createHash('sha256').update(body).digest('hex'));
+	});
+});
+
+test('fetcher: aborts mid-stream when body exceeds maxBytes', async () => {
+	await withServer((req, res) => {
+		res.writeHead(200, { 'content-type': 'application/octet-stream' });
+		let n = 0;
+		const iv = setInterval(() => {
+			n++;
+			res.write(Buffer.alloc(1024, 0xAB));
+			if (n > 200) { clearInterval(iv); res.end(); }
+		}, 1);
+	}, async (port) => {
+		const r = await validator.defaultFetcher({
+			url: 'http://127.0.0.1:' + port + '/big', maxBytes: 4096,
+			timeoutMs: 5000, maxRedirects: 0, allowedSchemes: ['http:'],
+			resolver: permissiveResolver,
+		});
+		assert.strictEqual(r.ok, false);
+		assert.strictEqual(r.reason, 'file_too_large');
+	});
+});
+
+test('fetcher: surfaces an HTTP timeout', async () => {
+	await withServer((req, res) => { /* never respond */ }, async (port) => {
+		const r = await validator.defaultFetcher({
+			url: 'http://127.0.0.1:' + port + '/hang', maxBytes: 1 << 16,
+			timeoutMs: 100, maxRedirects: 0, allowedSchemes: ['http:'],
+			resolver: permissiveResolver,
+		});
+		assert.strictEqual(r.ok, false);
+		assert.strictEqual(r.reason, 'fetch_timeout');
+	});
+});
+
+test('fetcher: follows a redirect up to maxRedirects', async () => {
+	const body = Buffer.from([0x67, 0x6C, 0x54, 0x46, 0, 0, 0, 0]);
+	await withServer((req, res) => {
+		if (req.url === '/start') { res.writeHead(302, { location: '/final' }); res.end(); return; }
+		if (req.url === '/final') { res.writeHead(200); res.end(body); return; }
+		res.writeHead(404); res.end();
+	}, async (port) => {
+		const r = await validator.defaultFetcher({
+			url: 'http://127.0.0.1:' + port + '/start', maxBytes: 1 << 16,
+			timeoutMs: 5000, maxRedirects: 2, allowedSchemes: ['http:'],
+			resolver: permissiveResolver,
+		});
+		assert.strictEqual(r.ok, true);
+		assert.strictEqual(r.body.length, body.length);
+	});
+});
+
+test('fetcher: refuses a redirect to loopback (SSRF guard runs per hop)', async () => {
+	// The first hop is on a stubbed public host (192.0.2.1, TEST-NET-1)
+	// served by our loopback http server; it 302s to 127.0.0.1, which
+	// the real resolveAndCheck guard must refuse.
+	await withServer((req, res) => {
+		res.writeHead(302, { location: 'http://127.0.0.1:1/never' }); res.end();
+	}, async (port) => {
+		const stubbedResolver = (host) => host === '127.0.0.1'
+			? validator.resolveAndCheck(host)	// real check, will reject
+			: Promise.resolve('127.0.0.1');	// pretend the first hop resolves to loopback
+		const r = await validator.defaultFetcher({
+			url: 'http://example.invalid:' + port + '/start', maxBytes: 1 << 16,
+			timeoutMs: 5000, maxRedirects: 3, allowedSchemes: ['http:'],
+			resolver: stubbedResolver,
+		});
+		assert.strictEqual(r.ok, false);
+		assert.strictEqual(r.reason, 'ssrf_blocked');
+	});
+});
+
+test('fetcher: defaultFetcher refuses an http://127.0.0.1 URL (SSRF guard)', async () => {
+	// Production resolveAndCheck runs; isBlockedIp must reject loopback.
+	const r = await validator.defaultFetcher({
+		url: 'http://127.0.0.1:1/anything', maxBytes: 1024,
+		timeoutMs: 1000, maxRedirects: 0, allowedSchemes: ['http:'],
+	});
+	assert.strictEqual(r.ok, false);
+	assert.strictEqual(r.reason, 'ssrf_blocked');
+});
+
+test('fetcher: refuses a non-allow-listed scheme', async () => {
+	const r = await validator.defaultFetcher({
+		url: 'file:///etc/passwd', maxBytes: 1024,
+		timeoutMs: 1000, maxRedirects: 0, allowedSchemes: ['https:'],
+	});
+	assert.strictEqual(r.ok, false);
+	assert.strictEqual(r.reason, 'scheme_not_allowed');
+});
+