Summary

Adds preliminary implementation of W3C Linked Web Storage (LWS) protocol mode as an optional configuration flag.

Status: 🚧 DRAFT - This PR captures the initial infrastructure for LWS support. Not intended for immediate merge - waiting for ecosystem signals (see #87).

Changes

Config Infrastructure

• ✅ Added --lws-mode CLI flag
• ✅ Added JSS_LWS_MODE environment variable support
• ✅ Added lwsMode config file option
• ✅ Server displays "LWS Mode: enabled (DRAFT)" in config output

Core Implementation

• ✅ PUT restriction: In LWS mode, PUT returns 404 for non-existent resources with helpful error message suggesting POST
• ✅ Preserves LDP mode: Default behavior unchanged (PUT creates or updates)
• ✅ Request decoration: request.lwsMode available to all handlers

Testing

• ✅ Basic LWS test suite (test/lws.test.js)
  • Tests PUT rejection for non-existent resources
  • Tests PUT success for updates
  • Tests POST for creation (already works)
  • Documents key LWS differences

Documentation

• ✅ README section explaining LWS mode with examples
• ✅ Comparison table (Solid/LDP vs LWS)
• ✅ Warning about draft status
• ✅ Links to issue LWS Protocol Mode Support (Draft/Future) #87 for full context

Key Difference

Solid/LDP Mode (default):

PUT /alice/new.json → 201 Created (creates resource)

LWS Mode:

PUT /alice/new.json → 404 Not Found (suggests POST instead)
POST /alice/ + Slug → 201 Created (required for creation)
PUT /alice/existing.json → 204 No Content (updates work)

What's NOT Implemented Yet

From the full plan in #87, this PR only implements the foundation:

• ❌ Link header-based container detection (still uses trailing slash)
• ❌ Linkset metadata endpoints (/resource;linkset)
• ❌ JSON Merge Patch for metadata
• ❌ Full test matrix (only basic tests included)

These are intentionally deferred until we see ecosystem adoption.

Why This PR Exists

This PR:

1. Captures the analysis from evaluating LWS PR Login with did:nostr #37
2. Proves feasibility - demonstrates LWS mode can coexist with LDP
3. Enables experimentation - developers can test LWS semantics
4. Preserves work - when/if LWS gains traction, we have a foundation

Decision Criteria for Merge

Recommend merging when:

• ✅ At least 3 other servers implement LWS protocol
• ✅ At least 5 client apps use LWS endpoints
• ✅ W3C Solid CG shows interest in LWS alignment
• ✅ LWS spec reaches Candidate Recommendation

Current status (Jan 2026):

• Servers: Unknown
• Clients: Likely zero
• Spec: Early draft (PR Login with did:nostr #37 just merged)

Testing

# Run LWS-specific tests
npm test -- test/lws.test.js

# Run full suite (LWS tests are isolated)
npm test

Related

• Issue: LWS Protocol Mode Support (Draft/Future) #87
• LWS Spec PR: Initial CRUD with proposed metadata handling w3c/lws-protocol#37
• LWS Repo: https://github.com/w3c/lws-protocol

Checklist

• Config flag infrastructure
• Basic PUT restriction logic
• Tests demonstrating behavior
• README documentation
• Full container detection (deferred)
• Linkset endpoints (deferred)
• Complete test matrix (deferred)

Note: Keeping as draft until ecosystem signals warrant merge. Can be rebased/updated as LWS spec evolves.