teleportxr 1.0.87 → 1.0.89

package/client/avatar_service.js

@@ -0,0 +1,100 @@
+'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.
+//
+// One AvatarService is owned by each Client; messages are dispatched in
+// from the signaling layer.
+
+const avatars = require('../protocol/avatars.js');
+
+function envelope(type, content) {
+	return JSON.stringify({ 'teleport-signal-type': type, content });
+}
+
+class AvatarService {
+	constructor(clientID, sigSend) {
+		this.clientID		= clientID;
+		this.sigSend		= sigSend;
+		this.currentPolicy	= null;
+		this.lastOffer		= null;
+		this.lastResult		= null;
+	}
+
+	// Send (or re-send) the policy to the owning client. The client is
+	// expected to reply with an avatar-offer.
+	sendPolicy(policy) {
+		if (!policy)
+			return;
+		this.currentPolicy = policy;
+		const content = policy && typeof policy.toJSON === 'function'
+			? policy.toJSON()
+			: avatars.parseAvatarPolicy(policy).toJSON();
+		console.log('avatar-policy → client ' + this.clientID + ' policy_id=' + content.policy_id);
+		this.sigSend(envelope(avatars.TELEPORT_SIGNAL_TYPE_AVATAR_POLICY, content));
+	}
+
+	// Handle an incoming avatar-offer. Phase 2 always replies using_default.
+	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))
+		{
+			this._reply({
+				policy_id:		offer.policy_id || 0n,
+				status:			'rejected',
+				node_uid:		0n,
+				using_default:	false,
+				delivery:		'import',
+				reasons:		['policy_unknown'],
+			});
+			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:		[],
+		});
+	}
+
+	// Handle a client-initiated revoke (rare in Phase 2; provided for
+	// symmetry with later phases).
+	handleRevoke(revokeJson) {
+		const policy_id = revokeJson && revokeJson.policy_id != null
+			? BigInt(revokeJson.policy_id) : 0n;
+		console.log('avatar-revoke ← client ' + this.clientID + ' policy_id=' + policy_id);
+		// In Phase 2 a revoke from the client just drops cached state; the
+		// server keeps the same policy in force and a new offer is expected
+		// next.
+		this.lastOffer = null;
+		this.lastResult = null;
+	}
+
+	_reply(result) {
+		const content = avatars.encodeAvatarResult(result);
+		this.lastResult = content;
+		console.log('avatar-result → client ' + this.clientID +
+			' status=' + content.status +
+			' delivery=' + content.delivery +
+			(content.reasons.length ? ' reasons=' + JSON.stringify(content.reasons) : ''));
+		this.sigSend(envelope(avatars.TELEPORT_SIGNAL_TYPE_AVATAR_RESULT, content));
+	}
+}
+
+module.exports = { AvatarService };

package/client/client.js

@@ -4,6 +4,7 @@ const core= require("../core/core.js");
 const command= require("../protocol/command.js");
 const message= require("../protocol/message.js");
 const gs= require("./geometry_service.js");
+const avatar_service= require("./avatar_service.js");
 const node_encoder= require("../protocol/encoders/node_encoder.js");
 const resource_encoder= require("../protocol/encoders/resource_encoder.js");
 const WebRtcConnectionManager = require('../connections/webrtcconnectionmanager');
@@ -54,6 +55,9 @@ class Client {
         this.origin_uid=0;
         this.handshakeMessage=new message.HandshakeMessage();
 		this.geometryService=new gs.GeometryService(cid);
+		// Per-client avatar negotiation state. The host application drives
+		// when (and whether) policy is sent via this service.
+		this.avatarService=new avatar_service.AvatarService(cid, sigSend);
 		this.webRtcConnected=false;
 		this.webRtcConnection=null;
 		this.currentOriginState=new OriginState();

package/client/client_manager.js

@@ -111,6 +111,10 @@ class ClientManager
 		// then we tell the client manager to start this client.
 		var c=this.GetOrCreateClient(clientID);
 		signalingClient.receiveReliableBinaryMessage=c.receiveReliableBinaryMessage.bind(c);
+		// Route avatar-offer / avatar-revoke text frames to the per-client
+		// AvatarService. The signaling layer dispatches by message type.
+		signalingClient.handleAvatarOffer=c.avatarService.handleOffer.bind(c.avatarService);
+		signalingClient.handleAvatarRevoke=c.avatarService.handleRevoke.bind(c.avatarService);
 		//c.SetScene(this.scene);
 		c.Start();
 		return c;

package/client/geometry_service.js

@@ -126,7 +126,7 @@ class GeometryService {
 		// MAY not be in this set:
 		this.streamedNodes.delete(uid);
 		// TODO: now reduce the counts for all the dependent resources.
-		console.log("Unstreaming node ", node_uid," for client ", this.clientID);
+		console.log("Unstreaming node ", uid," for client ", this.clientID);
 	}
 	StreamOrUnstream(resourceMap, uid, diff) {
 		// exclude "undefined"

package/connections/webrtcconnection.js

@@ -431,7 +431,6 @@ class WebRtcConnection extends EventEmitter
 
         this.videoDataChannel = this.createDataChannel("video",20);
         this.tagDataChannel = this.createDataChannel("video_tags",40);
-        this.audioToClientDataChannel = this.createDataChannel("audio_server_to_client",60);
         this.geometryDataChannel = this.createDataChannel("geometry_unframed",80);
         this.reliableDataChannel = this.createDataChannel("reliable",100);
         this.unreliableDataChannel = this.createDataChannel("unreliable",120,false);
@@ -585,7 +584,6 @@ class WebRtcConnection extends EventEmitter
 	{
         //.videoDataChannel = .("video",20);
         //.tagDataChannel = .("video_tags",40);
-        //.audioToClientDataChannel = .("audio_server_to_client",60);
         //.geometryDataChannel =l("geometry_unframed",80);
         //.reliableDataChannel =l("reliable",100);
         //.unreliableDataChannelnel("unreliable",120,false);

package/package.json

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

package/protocol/avatars.js

@@ -0,0 +1,162 @@
+'use strict';
+// JSON codecs for the avatar-negotiation signaling messages.
+// Wire format mirrors Teleport/TeleportCore/Avatars.h and is documented
+// in Teleport/docs/protocol/signaling.rst.
+//
+// Each codec is a tiny pair of plain JS helpers so callers can build the
+// JSON object directly, or round-trip an incoming JSON value into a
+// well-typed object. Unknown keys on incoming objects are preserved so
+// future protocol fields survive a parse+emit cycle.
+
+const TELEPORT_SIGNAL_TYPE_AVATAR_POLICY        = 'avatar-policy';
+const TELEPORT_SIGNAL_TYPE_AVATAR_OFFER         = 'avatar-offer';
+const TELEPORT_SIGNAL_TYPE_AVATAR_RESULT        = 'avatar-result';
+const TELEPORT_SIGNAL_TYPE_AVATAR_REVOKE        = 'avatar-revoke';
+const TELEPORT_SIGNAL_TYPE_PEER_AVATAR          = 'peer-avatar';
+const TELEPORT_SIGNAL_TYPE_PEER_AVATAR_FAILED   = 'peer-avatar-failed';
+
+// SignalingCapabilities ------------------------------------------------
+// Free-form capability bag advertised on the `connect` envelope. Unknown
+// keys are ignored on read and dropped on write — first-class flags only.
+
+function decodeCapabilities(raw) {
+	const out = { avatar_relay: false };
+	if (raw && typeof raw === 'object' && typeof raw.avatar_relay === 'boolean') {
+		out.avatar_relay = raw.avatar_relay;
+	}
+	return out;
+}
+
+function encodeCapabilities(caps) {
+	return { avatar_relay: !!(caps && caps.avatar_relay) };
+}
+
+// AvatarPolicy ---------------------------------------------------------
+
+class AvatarPolicy {
+	constructor(opts = {}) {
+		this.policy_id          = BigInt(opts.policy_id || 0n);
+		this.requirement        = opts.requirement || 'optional';   // required | optional | forbidden
+		this.default_available  = !!opts.default_available;
+		this.requirements       = opts.requirements || {};
+		this.proof              = Object.assign({ required: false, accepted_schemes: [] }, opts.proof || {});
+		if (opts.fetch_timeout_ms != null) this.fetch_timeout_ms = opts.fetch_timeout_ms;
+	}
+	toJSON() {
+		const j = {
+			policy_id:         Number(this.policy_id),
+			requirement:       this.requirement,
+			default_available: this.default_available,
+			requirements:      this.requirements,
+			proof: {
+				required:         !!this.proof.required,
+				accepted_schemes: Array.isArray(this.proof.accepted_schemes) ? this.proof.accepted_schemes : []
+			}
+		};
+		if (this.fetch_timeout_ms != null) j.fetch_timeout_ms = this.fetch_timeout_ms;
+		return j;
+	}
+}
+
+function parseAvatarPolicy(j) {
+	const p = new AvatarPolicy();
+	if (!j || typeof j !== 'object') return p;
+	if (j.policy_id         != null) p.policy_id         = BigInt(j.policy_id);
+	if (j.requirement       != null) p.requirement       = String(j.requirement);
+	if (j.default_available != null) p.default_available = !!j.default_available;
+	if (j.requirements      != null) p.requirements      = j.requirements;
+	if (j.proof             != null) p.proof = {
+		required:         !!j.proof.required,
+		accepted_schemes: Array.isArray(j.proof.accepted_schemes) ? j.proof.accepted_schemes.slice() : []
+	};
+	if (j.fetch_timeout_ms  != null) p.fetch_timeout_ms  = j.fetch_timeout_ms;
+	return p;
+}
+
+// AvatarOffer ----------------------------------------------------------
+
+function parseAvatarOffer(j) {
+	const o = { policy_id: 0n, have_avatar: false };
+	if (!j || typeof j !== 'object') return o;
+	if (j.policy_id   != null) o.policy_id   = BigInt(j.policy_id);
+	if (j.have_avatar != null) o.have_avatar = !!j.have_avatar;
+	if (j.url          != null) o.url          = String(j.url);
+	if (j.content_hash != null) o.content_hash = String(j.content_hash);
+	if (j.declared && typeof j.declared === 'object') {
+		o.declared = {
+			format: j.declared.format ? String(j.declared.format) : '',
+		};
+		if (j.declared.file_bytes != null) o.declared.file_bytes = Number(j.declared.file_bytes);
+		if (j.declared.triangles  != null) o.declared.triangles  = Number(j.declared.triangles);
+	}
+	if (j.proof && typeof j.proof === 'object') {
+		o.proof = {
+			scheme: j.proof.scheme ? String(j.proof.scheme) : '',
+			value:  j.proof.value  ? String(j.proof.value)  : ''
+		};
+	}
+	if (j.allow_relay != null) o.allow_relay = !!j.allow_relay;
+	return o;
+}
+
+function encodeAvatarOffer(o) {
+	const j = { policy_id: Number(o.policy_id || 0n), have_avatar: !!o.have_avatar };
+	if (o.url          != null) j.url          = String(o.url);
+	if (o.content_hash != null) j.content_hash = String(o.content_hash);
+	if (o.declared) j.declared = Object.assign({}, o.declared);
+	if (o.proof)    j.proof    = Object.assign({}, o.proof);
+	if (o.allow_relay != null) j.allow_relay = !!o.allow_relay;
+	return j;
+}
+
+// AvatarResult / Revoke / Peer messages --------------------------------
+
+function encodeAvatarResult(r) {
+	return {
+		policy_id:     Number(r.policy_id || 0n),
+		status:        r.status || 'rejected',           // accepted | rejected | pending
+		node_uid:      Number(r.node_uid || 0n),
+		using_default: !!r.using_default,
+		delivery:      r.delivery || 'import',           // import | relay
+		reasons:       Array.isArray(r.reasons) ? r.reasons.slice() : []
+	};
+}
+
+function encodeAvatarRevoke(r) {
+	return { policy_id: Number(r.policy_id || 0n), reason: r.reason || '' };
+}
+
+function encodePeerAvatar(p) {
+	const j = {
+		peer_client_id: Number(p.peer_client_id || 0n),
+		peer_node_uid:  Number(p.peer_node_uid  || 0n),
+		revoked:        !!p.revoked
+	};
+	if (p.url          != null) j.url          = String(p.url);
+	if (p.content_hash != null) j.content_hash = String(p.content_hash);
+	if (p.format       != null) j.format       = String(p.format);
+	if (p.proof)               j.proof        = Object.assign({}, p.proof);
+	return j;
+}
+
+function parsePeerAvatarFailed(j) {
+	const f = { peer_node_uid: 0n, reason: '' };
+	if (!j || typeof j !== 'object') return f;
+	if (j.peer_node_uid != null) f.peer_node_uid = BigInt(j.peer_node_uid);
+	if (j.reason        != null) f.reason        = String(j.reason);
+	return f;
+}
+
+module.exports = {
+	TELEPORT_SIGNAL_TYPE_AVATAR_POLICY,
+	TELEPORT_SIGNAL_TYPE_AVATAR_OFFER,
+	TELEPORT_SIGNAL_TYPE_AVATAR_RESULT,
+	TELEPORT_SIGNAL_TYPE_AVATAR_REVOKE,
+	TELEPORT_SIGNAL_TYPE_PEER_AVATAR,
+	TELEPORT_SIGNAL_TYPE_PEER_AVATAR_FAILED,
+	decodeCapabilities, encodeCapabilities,
+	AvatarPolicy, parseAvatarPolicy,
+	parseAvatarOffer, encodeAvatarOffer,
+	encodeAvatarResult, encodeAvatarRevoke,
+	encodePeerAvatar, parsePeerAvatarFailed,
+};

package/signaling.js

@@ -4,6 +4,7 @@ const getcurrentline = require("get-current-line").default;
 // Importing the required modules
 const WebSocketServer = require("ws");
 const core = require("./core/core.js");
+const avatars = require("./protocol/avatars.js");
 
 class SignalingState {
 	static START = new SignalingState("Start");
@@ -22,7 +23,7 @@ class SignalingState {
 }
 var serverID=BigInt(0n);
 
-class SignalingClient { 
+class SignalingClient {
 	constructor(ip, ws, id) {
 		this.ip = ip;
 		this.ws = ws;
@@ -31,6 +32,15 @@ class SignalingClient {
 		this.signalingState = SignalingState.START;
 		this.clientID = id;
 		this.receiveReliableBinaryMessage=null;
+		// Handlers wired by the per-client Client when it is created
+		// (see ClientManager.newClient). Avatar negotiation messages are
+		// JSON text frames so they cannot share the WebRTC binary path.
+		this.handleAvatarOffer=null;
+		this.handleAvatarRevoke=null;
+		// Session-level capabilities advertised by the client in its
+		// `connect` message. Defaults to all-false so that an older
+		// client which omits the field is treated conservatively.
+		this.capabilities = { avatar_relay: false };
 	}
 	ChangeSignalingState(newState) {
 		console.log(
@@ -80,6 +90,11 @@ function processDisconnection(clientID,signalingClient){
 	signalingClients.delete(clientID);
 }
 function processInitialRequest(clientID, signalingClient, content) {
+	// Free-form capability bag: a missing / malformed object leaves
+	// capabilities at their default (all-false) state.
+	if (content && typeof content === 'object' && content.capabilities) {
+		signalingClient.capabilities = avatars.decodeCapabilities(content.capabilities);
+	}
 	var j_clientID = 0;
 	if (content.hasOwnProperty("clientID")) {
 		var j_clientID = content["clientID"];
@@ -162,6 +177,18 @@ function receiveWebSocketsMessage(clientID, signalingClient, txt) {
     {
         processDisconnection(clientID, signalingClient);
     }
+	else if (teleport_signal_type == avatars.TELEPORT_SIGNAL_TYPE_AVATAR_OFFER)
+	{
+		if (signalingClient.handleAvatarOffer)
+			signalingClient.handleAvatarOffer(message["content"]);
+		else
+			console.log("avatar-offer received for client " + clientID + " but no handler is wired.");
+	}
+	else if (teleport_signal_type == avatars.TELEPORT_SIGNAL_TYPE_AVATAR_REVOKE)
+	{
+		if (signalingClient.handleAvatarRevoke)
+			signalingClient.handleAvatarRevoke(message["content"]);
+	}
     else
     {
         var webRtcConnection = webRtcConnectionManager.getConnection(clientID);

package/test/test_avatar_service.js

@@ -0,0 +1,139 @@
+'use strict';
+// Tests for the per-client AvatarService introduced in Phase 2 of the
+// avatars implementation plan. The service:
+//   * serialises a policy and emits it as an avatar-policy text frame;
+//   * receives an avatar-offer and replies with avatar-result.
+// Phase 2 always replies status=using_default for a matching policy and
+// status=rejected,reasons=[policy_unknown] for anything else.
+
+const test		= require('node:test');
+const assert	= require('node:assert');
+
+const avatars			= require('../protocol/avatars.js');
+const avatar_service	= require('../client/avatar_service.js');
+
+// Tiny helper that captures every signaling string the service emits.
+function makeSink() {
+	const sent = [];
+	return { send: (s) => sent.push(JSON.parse(s)), sent };
+}
+
+test('sendPolicy emits an avatar-policy envelope with the policy content', () => {
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send);
+	const policy = new avatars.AvatarPolicy({
+		policy_id: 12345n,
+		requirement: 'optional',
+		default_available: true,
+		requirements: { formats: ['glb'], max_file_bytes: 8388608 },
+	});
+	svc.sendPolicy(policy);
+	assert.strictEqual(sink.sent.length, 1);
+	const msg = sink.sent[0];
+	assert.strictEqual(msg['teleport-signal-type'], 'avatar-policy');
+	assert.strictEqual(msg.content.policy_id, 12345);
+	assert.strictEqual(msg.content.requirement, 'optional');
+	assert.strictEqual(msg.content.default_available, true);
+	assert.deepStrictEqual(msg.content.requirements.formats, ['glb']);
+});
+
+test('handleOffer replies with using_default when policy_id matches', () => {
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send);
+	svc.sendPolicy(new avatars.AvatarPolicy({ policy_id: 7n, default_available: true }));
+	sink.sent.length = 0;
+	svc.handleOffer({ policy_id: 7, have_avatar: false });
+	assert.strictEqual(sink.sent.length, 1);
+	const msg = sink.sent[0];
+	assert.strictEqual(msg['teleport-signal-type'], 'avatar-result');
+	assert.strictEqual(msg.content.policy_id, 7);
+	assert.strictEqual(msg.content.status, 'using_default');
+	assert.strictEqual(msg.content.using_default, true);
+	assert.strictEqual(msg.content.delivery, 'import');
+	assert.strictEqual(msg.content.node_uid, 0);
+	assert.deepStrictEqual(msg.content.reasons, []);
+});
+
+test('handleOffer still replies using_default when client supplies an avatar', () => {
+	// Phase 2 ignores the offer contents entirely; this asserts that we
+	// don't accidentally accept a URL.
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send);
+	svc.sendPolicy(new avatars.AvatarPolicy({ policy_id: 9n, default_available: true }));
+	sink.sent.length = 0;
+	svc.handleOffer({
+		policy_id: 9,
+		have_avatar: true,
+		url: 'https://example.com/avatar.glb',
+		content_hash: 'sha256:abcd',
+		declared: { format: 'glb', file_bytes: 4096 },
+	});
+	assert.strictEqual(sink.sent[0].content.status, 'using_default');
+	assert.strictEqual(sink.sent[0].content.using_default, true);
+});
+
+test('handleOffer rejects with policy_unknown when policy_id does not match', () => {
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send);
+	svc.sendPolicy(new avatars.AvatarPolicy({ policy_id: 100n, default_available: true }));
+	sink.sent.length = 0;
+	svc.handleOffer({ policy_id: 999, have_avatar: false });
+	const msg = sink.sent[0];
+	assert.strictEqual(msg.content.status, 'rejected');
+	assert.deepStrictEqual(msg.content.reasons, ['policy_unknown']);
+});
+
+test('handleOffer rejects when no policy has been sent yet', () => {
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send);
+	svc.handleOffer({ policy_id: 1, have_avatar: false });
+	assert.strictEqual(sink.sent[0].content.status, 'rejected');
+	assert.deepStrictEqual(sink.sent[0].content.reasons, ['policy_unknown']);
+});
+
+test('handleRevoke clears cached offer state without emitting anything', () => {
+	const sink = makeSink();
+	const svc  = new avatar_service.AvatarService(42n, sink.send);
+	svc.sendPolicy(new avatars.AvatarPolicy({ policy_id: 5n }));
+	svc.handleOffer({ policy_id: 5, have_avatar: false });
+	sink.sent.length = 0;
+	svc.handleRevoke({ policy_id: 5 });
+	assert.strictEqual(sink.sent.length, 0);
+	assert.strictEqual(svc.lastOffer, null);
+	assert.strictEqual(svc.lastResult, null);
+});
+
+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
+	// way test_avatars.js does because SignalingClient is not exported.
+	const fs		= require('node:fs');
+	const path		= require('node:path');
+	const Module	= require('node:module');
+	const src		= fs.readFileSync(path.join(__dirname, '..', 'signaling.js'), 'utf8');
+	const m			= new Module(require.resolve('../signaling.js'));
+	m.filename = require.resolve('../signaling.js');
+	m.paths = Module._nodeModulePaths(m.filename);
+	m._compile(src + '\nmodule.exports._SignalingClient = SignalingClient;'
+		+ '\nmodule.exports._receiveWebSocketsMessage = receiveWebSocketsMessage;\n', m.filename);
+	const SignalingClient = m.exports._SignalingClient;
+	const receive		  = m.exports._receiveWebSocketsMessage;
+
+	const sc = new SignalingClient('1.2.3.4', { send: () => {} }, 1n);
+	let receivedOffer = null;
+	sc.handleAvatarOffer = (o) => { receivedOffer = o; };
+	let receivedRevoke = null;
+	sc.handleAvatarRevoke = (r) => { receivedRevoke = r; };
+
+	receive(1n, sc, JSON.stringify({
+		'teleport-signal-type': 'avatar-offer',
+		content: { policy_id: 1, have_avatar: false },
+	}));
+	assert.deepStrictEqual(receivedOffer, { policy_id: 1, have_avatar: false });
+
+	receive(1n, sc, JSON.stringify({
+		'teleport-signal-type': 'avatar-revoke',
+		content: { policy_id: 1, reason: 'replaced' },
+	}));
+	assert.deepStrictEqual(receivedRevoke, { policy_id: 1, reason: 'replaced' });
+});

package/test/test_avatars.js

@@ -0,0 +1,140 @@
+'use strict';
+// Unit tests for the avatar-negotiation JSON codecs in protocol/avatars.js
+// and the connect-time `capabilities` parsing in signaling.js.
+// Mirrors the C++ test suite in Teleport/test/test_avatars.cpp so a
+// regression on either side surfaces in matching test cases.
+
+const test = require('node:test');
+const assert = require('node:assert');
+
+const avatars = require('../protocol/avatars.js');
+
+test('decodeCapabilities returns all-false for missing / empty / non-object input', () => {
+	assert.deepStrictEqual(avatars.decodeCapabilities(undefined), { avatar_relay: false });
+	assert.deepStrictEqual(avatars.decodeCapabilities(null),      { avatar_relay: false });
+	assert.deepStrictEqual(avatars.decodeCapabilities({}),        { avatar_relay: false });
+	assert.deepStrictEqual(avatars.decodeCapabilities('nope'),    { avatar_relay: false });
+});
+
+test('decodeCapabilities reads avatar_relay and ignores unknown future keys', () => {
+	const caps = avatars.decodeCapabilities({ avatar_relay: true, future_flag: 'whatever' });
+	assert.strictEqual(caps.avatar_relay, true);
+	assert.strictEqual('future_flag' in caps, false);
+});
+
+test('decodeCapabilities ignores non-boolean avatar_relay', () => {
+	const caps = avatars.decodeCapabilities({ avatar_relay: 'yes' });
+	assert.strictEqual(caps.avatar_relay, false);
+});
+
+test('encodeCapabilities drops unknown keys and coerces to boolean', () => {
+	assert.deepStrictEqual(avatars.encodeCapabilities({ avatar_relay: 1, junk: 'x' }), { avatar_relay: true });
+	assert.deepStrictEqual(avatars.encodeCapabilities({}),                              { avatar_relay: false });
+});
+
+test('AvatarPolicy: toJSON / parseAvatarPolicy round-trip', () => {
+	const policy = new avatars.AvatarPolicy({
+		policy_id: 12345n,
+		requirement: 'required',
+		default_available: true,
+		requirements: { formats: ['glb', 'vrm'], max_file_bytes: 8388608, max_triangles: 60000, skeleton: 'humanoid' },
+		proof: { required: true, accepted_schemes: ['jws-detached', 'well-known-url'] },
+		fetch_timeout_ms: 7500,
+	});
+	const wire = JSON.parse(JSON.stringify(policy));
+	const parsed = avatars.parseAvatarPolicy(wire);
+	assert.strictEqual(parsed.policy_id,         12345n);
+	assert.strictEqual(parsed.requirement,       'required');
+	assert.strictEqual(parsed.default_available, true);
+	assert.deepStrictEqual(parsed.requirements.formats, ['glb', 'vrm']);
+	assert.strictEqual(parsed.proof.required, true);
+	assert.deepStrictEqual(parsed.proof.accepted_schemes, ['jws-detached', 'well-known-url']);
+	assert.strictEqual(parsed.fetch_timeout_ms, 7500);
+});
+
+test('parseAvatarOffer handles the have_avatar=false short-form', () => {
+	const o = avatars.parseAvatarOffer({ policy_id: 7, have_avatar: false });
+	assert.strictEqual(o.policy_id, 7n);
+	assert.strictEqual(o.have_avatar, false);
+	assert.strictEqual(o.url, undefined);
+	assert.strictEqual(o.declared, undefined);
+});
+
+test('parseAvatarOffer + encodeAvatarOffer round-trip a full offer', () => {
+	const offer = {
+		policy_id: 42n,
+		have_avatar: true,
+		url: 'https://avatars.example.com/u/42.glb',
+		content_hash: 'sha256:abcd',
+		declared: { format: 'glb', file_bytes: 4096, triangles: 1200 },
+		proof: { scheme: 'jws-detached', value: 'eyJ...' },
+		allow_relay: false,
+	};
+	const wire = avatars.encodeAvatarOffer(offer);
+	const back = avatars.parseAvatarOffer(wire);
+	assert.strictEqual(back.policy_id, 42n);
+	assert.strictEqual(back.have_avatar, true);
+	assert.strictEqual(back.url, offer.url);
+	assert.strictEqual(back.content_hash, offer.content_hash);
+	assert.deepStrictEqual(back.declared, offer.declared);
+	assert.deepStrictEqual(back.proof, offer.proof);
+	assert.strictEqual(back.allow_relay, false);
+});
+
+test('encodeAvatarResult fills sensible defaults for missing fields', () => {
+	const r = avatars.encodeAvatarResult({ policy_id: 3n, status: 'accepted', node_uid: 999n, delivery: 'relay' });
+	assert.strictEqual(r.policy_id, 3);
+	assert.strictEqual(r.status, 'accepted');
+	assert.strictEqual(r.node_uid, 999);
+	assert.strictEqual(r.using_default, false);
+	assert.strictEqual(r.delivery, 'relay');
+	assert.deepStrictEqual(r.reasons, []);
+});
+
+test('encodeAvatarRevoke produces the expected envelope', () => {
+	assert.deepStrictEqual(
+		avatars.encodeAvatarRevoke({ policy_id: 17n, reason: 'licence_expired' }),
+		{ policy_id: 17, reason: 'licence_expired' }
+	);
+});
+
+test('encodePeerAvatar carries url / hash / format / proof', () => {
+	const wire = avatars.encodePeerAvatar({
+		peer_client_id: 100n,
+		peer_node_uid: 200n,
+		url: 'https://example.com/a.glb',
+		content_hash: 'sha256:ff',
+		format: 'glb',
+		proof: { scheme: 'well-known-url', value: 'https://example.com/.well-known/avatar-binding' },
+	});
+	assert.strictEqual(wire.peer_client_id, 100);
+	assert.strictEqual(wire.peer_node_uid, 200);
+	assert.strictEqual(wire.url, 'https://example.com/a.glb');
+	assert.strictEqual(wire.content_hash, 'sha256:ff');
+	assert.strictEqual(wire.format, 'glb');
+	assert.strictEqual(wire.proof.scheme, 'well-known-url');
+	assert.strictEqual(wire.revoked, false);
+});
+
+test('parsePeerAvatarFailed round-trips peer_node_uid and reason', () => {
+	const f = avatars.parsePeerAvatarFailed({ peer_node_uid: '200', reason: '404' });
+	assert.strictEqual(f.peer_node_uid, 200n);
+	assert.strictEqual(f.reason, '404');
+});
+
+test('signaling.SignalingClient defaults capabilities to all-false', () => {
+	// Constructed without a websocket — fine for testing the field shape only.
+	const signaling = require('../signaling.js');
+	// SignalingClient isn't exported; reach into the module like other tests do.
+	const fs = require('node:fs');
+	const path = require('node:path');
+	const Module = require('node:module');
+	const src = fs.readFileSync(path.join(__dirname, '..', 'signaling.js'), 'utf8');
+	const m = new Module(require.resolve('../signaling.js'));
+	m.filename = require.resolve('../signaling.js');
+	m.paths = Module._nodeModulePaths(m.filename);
+	m._compile(src + '\nmodule.exports._SignalingClient = SignalingClient;\n', m.filename);
+	const SignalingClient = m.exports._SignalingClient;
+	const c = new SignalingClient('1.2.3.4', /* ws */ null, 1n);
+	assert.deepStrictEqual(c.capabilities, { avatar_relay: false });
+});