From 4bbd70432130ee90acb592932f2818d8720def23 Mon Sep 17 00:00:00 2001
From: Mario Fetka <mario.fetka@gmail.com>
Date: Tue, 2 Jun 2026 07:40:03 +0000
Subject: [PATCH] docs: document secure provider IPC policy

---
 REDESIGN.md | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 94 insertions(+), 1 deletion(-)

diff --git a/REDESIGN.md b/REDESIGN.md
index b3893d0..f0b6350 100644
--- a/REDESIGN.md
+++ b/REDESIGN.md
@@ -530,6 +530,97 @@ The safe order is:
 The rule is: do not create a new provider process until the caller can receive a
 formal reply from it and can handle provider failure centrally.
 
+
+## Secure internal provider IPC and client transport compatibility
+
+Provider handoff security and client transport compatibility are separate
+concerns.  Future TCP/IP support for client-facing NCP/NDS traffic must not
+imply that every historic NetWare 4.x-compatible client is required to speak
+TLS.  Classic compatibility should remain protocol-accurate first; TLS for
+client-facing protocols should only be enabled where the real protocol/frontend
+supports it, such as LDAP/LDAPS/StartTLS on `nwdirectory` or a later explicitly
+secure client protocol.
+
+Internal provider IPC is different.  Once a request has been decoded or partially
+decoded by `nwconn`, the internal handoff payload can contain sensitive material:
+password data, login/authentication material, Bindery object properties, Queue
+state, future NDS credentials, or directory attributes.  A plaintext TCP-based
+provider handoff would expose more than the original network packet boundary did.
+
+The design rule should be:
+
+```text
+local provider IPC:
+  Unix-domain sockets or pipes are acceptable when filesystem permissions,
+  process ownership, and socket directories are strict.
+
+TCP-based provider IPC:
+  never plaintext; wolfSSL-backed TLS with mutual authentication is required.
+```
+
+So the local default may remain simple and compatible:
+
+```text
+nwconn -> nwbind      local pipe/Unix-domain IPC, strict permissions
+nwconn -> nwqueue     local pipe/Unix-domain IPC, strict permissions
+nwconn -> nwnds       local pipe/Unix-domain IPC, strict permissions
+```
+
+But any future provider split over TCP, even if it is only `localhost` TCP or a
+container boundary, must be treated as a secure channel:
+
+```text
+nwconn -> provider over TCP:
+  wolfSSL required
+  mutual authentication required
+  no anonymous TLS
+  no opportunistic downgrade to plaintext
+  clear failure if certificates/keys are missing or invalid
+```
+
+This is intentionally stricter than client-facing compatibility.  Historical
+NetWare 4.x/NDS clients should not be forced to use TLS just because internal
+provider IPC can use TLS.  The two policy surfaces are independent:
+
+```text
+Client NCP/NDS transport:
+  compatibility first; no blanket TLS requirement for classic clients.
+
+LDAP/LDAPS/StartTLS:
+  handled by nwdirectory; wolfSSL is appropriate at that network edge.
+
+Internal provider IPC over TCP:
+  always wolfSSL/mTLS because decoded server-internal data may cross it.
+```
+
+Local IPC still needs security rules even without TLS:
+
+- IPC sockets/directories should not be world-readable or world-writable;
+- provider processes should run as the expected user/group;
+- raw handoff payloads must not be logged by default;
+- debug dumps should redact or omit authentication payloads;
+- sensitive request/reply buffers should be wiped when practical after use;
+- core dumps for processes handling credentials should be considered unsafe by
+  default;
+- formal handoff logging should record selector paths, provider names, reply
+  kinds, and completion codes, not raw secret bytes.
+
+This also means there are two different wolfSSL uses in the long-term design:
+
+```text
+1. LDAP TLS:
+   external LDAP/LDAPS/StartTLS clients -> nwdirectory
+
+2. Provider IPC TLS:
+   mars-nwe process -> mars-nwe provider process, only when the provider IPC
+   transport is TCP-based
+```
+
+The two uses should have separate configuration and credentials.  Reusing an
+external LDAP certificate as an internal provider trust root should not be the
+default assumption.  A later setup tool can create or install a local mars-nwe
+provider-IPC CA/key set if TCP-based provider IPC ever becomes supported.
+
 ## Provider boundaries
 
 A clean design would treat the existing modules as providers instead of hidden
@@ -905,7 +996,9 @@ The migration path should be conservative:
 
 1. add the design boundary and naming notes first;
 2. import or integrate tinyldap under the project-facing `nwdirectory` name;
-3. keep wolfSSL confined to the LDAP/LDAPS/StartTLS network edge;
+3. keep client-facing wolfSSL usage confined to the LDAP/LDAPS/StartTLS
+   network edge initially; internal TCP-based provider IPC may also use wolfSSL
+   later, but only as a separate mTLS configuration;
 4. introduce `libdirectory` before making Bindery depend on it;
 5. add `nwsetup` as the direct bootstrap/provisioning tool for the initial
    libflaim-backed directory store;