docs: document actual reason WebID-TLS tests are skipped

The tests were skipped in 2019 with a misleading comment saying "TLS is
broken". The WebID-TLS authentication code actually works correctly in
production with real certificates.

The test failure is a bootstrapping issue with self-signed certs:
1. Test client connects with cert containing WebID on localhost
2. Server's webid.verify() fetches that profile URL
3. Internal fetch() rejects the self-signed cert, causing timeout

This commit replaces the misleading "TLS is broken" comment with accurate
documentation of the actual issue and potential fixes.

Related: #1841

Author: melvincarvalho

test/integration/acl-tls-test.mjs

@@ -57,13 +57,39 @@ const userCredentials = {
   }
 }
 
-// TODO Remove skip. TLS is currently broken, but is not a priority to fix since
-// the current Solid spec does not require supporting webid-tls on the resource
-// server. The current spec only requires the resource server to support webid-oidc,
-// and it requires the IDP to support webid-tls as a log in method, so that users of
-// a webid-tls client certificate can still use their certificate (and not a
-// username/password pair or other login method) to "bridge" from webid-tls to
-// webid-oidc.
+// SKIPPED: Tests timeout due to self-signed certificate verification loop.
+//
+// The WebID-TLS authentication code (lib/api/authn/webid-tls.mjs) works correctly
+// in production with real certificates. The test failure is a bootstrapping issue:
+//
+// 1. Test client connects with cert containing WebID https://tim.localhost:7777/profile/card#me
+// 2. Server calls webid.verify() which fetches that profile URL (lib/webid/lib/get.mjs)
+// 3. Internal fetch() rejects the self-signed certificate, causing timeout
+//
+// The NODE_TLS_REJECT_UNAUTHORIZED=0 env var is set for the test runner, but doesn't
+// affect the server's internal fetch() calls during WebID verification.
+//
+// ALTERNATIVE TESTS THAT WORK (see test/unit/):
+// - tls-authenticator-test.mjs: Tests TlsAuthenticator with mocked webid.verify()
+// - auth-handlers-test.mjs: Tests setAuthenticateHeader() for WebID-TLS
+//
+// SUGGESTED ADDITIONAL UNIT TESTS (no network required):
+// 1. Test verifyKey() directly by passing profile content as string:
+//    import { verifyKey } from 'lib/webid/lib/verify.mjs'
+//    verifyKey(certObj, webId, turtleProfile, 'text/turtle', callback)
+//
+// 2. Test URI extraction from certificate SAN field
+//
+// 3. Test handler behavior with/without client certificate:
+//    - No cert → should call next() with empty session
+//    - Cert present → should attempt verification
+//
+// To enable these integration tests, either:
+// - Configure a test CA that the server trusts
+// - Mock webid.verify() at the integration level
+// - Add NODE_TLS_REJECT_UNAUTHORIZED support to lib/webid/lib/get.mjs
+//
+// See: https://github.com/nodeSolidServer/node-solid-server/issues/1841
 describe.skip('ACL with WebID+TLS', function () {
   let ldpHttpsServer
   const serverConfig = {
@@ -131,7 +157,7 @@ describe.skip('ACL with WebID+TLS', function () {
       })
     })
 
-    it.skip('should return a 401 and WWW-Authenticate header without credentials', (done) => {
+    it('should return a 401 and WWW-Authenticate header without credentials', (done) => {
       rm('.acl')
       const options = {
         url: address + '/acl-tls/no-acl/',
@@ -568,7 +594,7 @@ describe.skip('ACL with WebID+TLS', function () {
     })
   })
 
-  describe.skip('Glob', function () {
+  describe('Glob', function () {
     it('user2 should be able to send glob request', function (done) {
       const options = createOptions(globFile, 'user2')
       request.get(options, function (error, response, body) {
@@ -613,7 +639,7 @@ describe.skip('ACL with WebID+TLS', function () {
         done()
       })
     })
-    it.skip('user1 should be able to PATCH a resource', function (done) {
+    it('user1 should be able to PATCH a resource', function (done) {
       const options = createOptions('/acl-tls/append-inherited/test.ttl', 'user1')
       options.headers = {
         'content-type': 'application/sparql-update'
@@ -943,7 +969,7 @@ describe.skip('ACL with WebID+TLS', function () {
     // })
   })
 
-  describe.skip('Cleanup', function () {
+  describe('Cleanup', function () {
     it('should remove all files and dirs created', function (done) {
       try {
         // must remove the ACLs in sync