docs: document shared library layering plan

2026-06-03 04:09:35 +00:00
parent 40f95d079a
commit a262caba33
4 changed files with 144 additions and 16 deletions
--- a/AI.md
+++ b/AI.md
@@ -1385,4 +1385,36 @@ Next patch number should be `0253`.
 - Do not mix MatrixSSL import/CMake work with FLAIM CCS/NICI implementation or
  source tree layout changes in the same patch.

-Next patch number should be `0266`.
+## 2026-06-02 - Patch 0266 shared library layering for MatrixSSL, FLAIM, and directory services
+
+- The third-party storage/crypto plan now uses mars-nwe-named shared library
+  layers, not raw upstream target names as public project interfaces.
+- `libnwmatrixssl` is the patched MatrixSSL fork/library.  It exists only to make
+  the GPL-2.0-compatible MatrixSSL source build cleanly under mars-nwe CMake and
+  to avoid collisions with any system MatrixSSL package.  Keep local changes
+  limited to portability, naming, CMake, and build hygiene unless a later
+  security/compatibility patch explicitly says otherwise.
+- `libnwssl` is the mars-nwe SSL/crypto facade.  It owns the MatrixSSL-facing
+  wrappers, future TLS abstraction used by apps/services, and the CCS/NICI
+  compatibility layer that FLAIM needs.  Application code should include/use
+  `libnwssl`, not raw MatrixSSL headers.
+- `libnwflaimtk` and `libnwflaim` are the renamed mars-nwe FLAIM libraries built
+  from the imported FLAIM sources.  The rename is intentional so mars-nwe never
+  accidentally links against, or conflicts with, a system `libflaim`/FTK install.
+- `libnwdirectory` is the directory abstraction library above the FLAIM store. It
+  is the API used by `nwdirectory`, future `nwnds`, setup/import tooling, and
+  later Bindery/NDS integration; those consumers should not call `libnwflaim`
+  directly.
+- Keep the layering explicit:
+
+  ```text
+  apps/services/setup/nwnds -> libnwdirectory -> libnwflaim -> libnwflaimtk
+                            -> libnwssl CCS/NICI -> libnwmatrixssl
+  apps/services TLS         -> libnwssl TLS      -> libnwmatrixssl
+  ```
+
+- FLAIM source import, MatrixSSL fork/CMake work, `libnwssl` facade work,
+  CCS/NICI implementation, and `libnwdirectory` API work should remain separate
+  patches.
+
+Next patch number should be `0267`.
--- a/REDESIGN.md
+++ b/REDESIGN.md
@@ -1649,6 +1649,66 @@ not.  The config may point at certificate/key files, while `nwsetup` should be
 able to generate or validate local defaults.  Private keys and provider mTLS
 credentials must live in protected directories with strict permissions.

+
+### mars-nwe shared library layering
+
+The MatrixSSL/FLAIM/directory plan should produce mars-nwe-named libraries instead
+of exposing raw upstream library identities to the rest of the project.  This keeps
+linking deterministic, avoids collisions with distro packages, and makes it clear
+which layer owns which compatibility boundary.
+
+Planned library names:
+
+```text
+libnwmatrixssl
+  mars-nwe-maintained MatrixSSL fork/import
+  patched only for CMake, portability, symbol/library naming, and build hygiene
+  provides the low-level GPL-2.0-compatible crypto/TLS implementation
+
+libnwssl
+  mars-nwe SSL/crypto facade
+  provides TLS abstraction for apps/services
+  provides the CCS/NICI compatibility API used by FLAIM encryption paths
+  is the only normal project layer that talks directly to libnwmatrixssl
+
+libnwflaimtk
+  renamed FLAIM FTK support library
+  built from the imported FLAIM source but renamed to avoid system-library
+  conflicts
+
+libnwflaim
+  renamed classic FLAIM database library
+  depends on libnwflaimtk and uses libnwssl only through the CCS/NICI interface
+  when encrypted storage support is enabled
+
+libnwdirectory
+  mars-nwe directory abstraction library
+  provides the C API used by nwdirectory, future nwnds, nwsetup/import tools, and
+  any later Bindery/NDS integration
+  owns the mapping from directory objects/schema/security policy to libnwflaim
+```
+
+The intended dependency direction is:
+
+```text
+LDAP/LDAPS nwdirectory service -> libnwdirectory -> libnwflaim -> libnwflaimtk
+future nwnds/NDS provider      -> libnwdirectory -> libnwflaim -> libnwflaimtk
+nwsetup/import tooling         -> libnwdirectory -> libnwflaim -> libnwflaimtk
+
+libnwflaim encrypted storage   -> libnwssl CCS/NICI compat -> libnwmatrixssl
+service/app TLS                -> libnwssl TLS facade      -> libnwmatrixssl
+```
+
+Consumers must not skip layers for convenience.  `nwdirectory`, future `nwnds`,
+`nwsetup`, `nwbind`, and provider code should call `libnwdirectory` for directory
+state and `libnwssl` for TLS/crypto policy.  They should not include FLAIM,
+MatrixSSL, OpenSSL-style, or CCS/NICI implementation headers directly.
+
+This also means the imported FLAIM targets should not be named exactly like a
+system installation.  Use mars-nwe names such as `NWFlaim::ftk` /
+`NWFlaim::flaim` or equivalent targets that produce `libnwflaimtk` and
+`libnwflaim`, while keeping source-origin notes in `third_party/libflaim`.
+
 ### MatrixSSL fork/CMake rule

 `MatrixSSL` should be evaluated as the preferred GPL-2.0-compatible crypto/TLS
@@ -1680,8 +1740,8 @@ Expose normal targets.  The exact names may be adjusted during import, but the
 intended split is:

 ```text
-MATRIXSSL::crypto   # crypto primitives used by CCS/NICI compat
-MATRIXSSL::tls      # TLS layer, only if/when mars-nwe needs it
+NWMatrixSSL::crypto   # produces/represents libnwmatrixssl crypto primitives
+NWMatrixSSL::tls      # optional TLS surface from the MatrixSSL fork, if built
 ```

 FLAIM should still not include MatrixSSL headers directly.  The intended layering
@@ -1741,7 +1801,7 @@ inside mars-nwe:
 ```

 The CMake conversion should separate the library from optional tools/tests,
-expose a normal target such as `FLAIM::flaim`, and support static/shared choices
+expose a normal target such as `NWFlaim::flaim`, and support static/shared choices
 where useful.  The original Makefiles may remain as reference material during the
 import, but they should not be the long-term build path.

@@ -1757,8 +1817,8 @@ The first CMake import should be intentionally small and storage-focused:

 ```text
 required first targets:
-  FLAIM::ftk      # cross-platform toolkit used by libflaim
-  FLAIM::flaim    # classic FLAIM database library used by libdirectory
+  NWFlaim::ftk    # produces libnwflaimtk, the renamed FTK support library
+  NWFlaim::flaim  # produces libnwflaim, the renamed classic FLAIM DB library

 optional later targets:
  FLAIM::sql      # SQL FLAIM, not needed for initial directory store
@@ -1768,7 +1828,8 @@ optional later targets:
  flaim docs      # off by default
 ```

-`FLAIM::flaim` depends on the FTK toolkit, so the CMake conversion should model
+`NWFlaim::flaim` depends on the renamed FTK toolkit target, so the CMake
+conversion should model
 that dependency explicitly instead of relying on Autotools' installed-library
 search.  The initial mars-nwe directory-store work only needs the classic FLAIM
 library path; SQL FLAIM, XFLAIM, Java/C# bindings, Doxygen, OBS/debian package
@@ -1788,7 +1849,7 @@ policy.
 If the FLAIM source cannot be built cleanly without old OpenSSL-facing code, the
 preferred fallback is still not to introduce a general OpenSSL/LibreSSL backend
 matrix.  First disable the old FTK TLS-facing code for the required
-`FLAIM::ftk`/`FLAIM::flaim` targets.  If a legacy path is unavoidable, keep the
+`NWFlaim::ftk`/`NWFlaim::flaim` targets.  If a legacy path is unavoidable, keep the
 patch inside `third_party/libflaim` and use a narrow shim or source adjustment;
 do not expose OpenSSL-compatible types outside the FLAIM/FTK build and do not
 make LDAP/provider IPC use OpenSSL APIs.
--- a/TODO.md
+++ b/TODO.md
@@ -2013,3 +2013,30 @@ Follow-up:
 - When importing third-party code, keep its original license in the
  corresponding `third_party/` subtree and document it separately rather than
  mixing it into mars-nwe-owned source headers.
+
+### Shared library layering for MatrixSSL, FLAIM, and directory services
+
+Current status:
+
+- Patch `0266` documents the planned mars-nwe shared-library layering for the
+  MatrixSSL, FLAIM, SSL/crypto, and directory work.
+- The intended library names are:
+  - `libnwmatrixssl` for the patched MatrixSSL fork with native CMake support;
+  - `libnwssl` for the mars-nwe TLS facade and CCS/NICI compatibility layer;
+  - `libnwflaimtk` for the renamed FLAIM FTK support library;
+  - `libnwflaim` for the renamed classic FLAIM database library;
+  - `libnwdirectory` for the directory abstraction API consumed by `nwdirectory`,
+    future `nwnds`, setup/import tooling, and later provider integration.
+- The intended dependency direction is `libnwdirectory -> libnwflaim ->
+  libnwflaimtk`, with encrypted-storage crypto flowing through `libnwssl ->
+  libnwmatrixssl`.
+
+Follow-up:
+
+- Add build-system support for these shared libraries in small mechanical
+  patches.
+- Import/fork MatrixSSL first as `libnwmatrixssl` with native CMake.
+- Add `libnwssl` as a thin facade before wiring FLAIM encryption paths.
+- Import/Fork FLAIM as renamed `libnwflaimtk`/`libnwflaim` targets.
+- Add `libnwdirectory` only after the storage and crypto library boundaries are
+  clear.
--- a/third_party/README.md
+++ b/third_party/README.md
@@ -75,13 +75,15 @@ mars-nwe build path.  Add a native CMake build that works both standalone and as
 a mars-nwe subdirectory.  Expected targets are along these lines:

 ```text
-MATRIXSSL::crypto
-MATRIXSSL::tls
+NWMatrixSSL::crypto
+NWMatrixSSL::tls
 ```

-`MATRIXSSL::crypto` is the important first target for a Flaim CCS/NICI compat
-backend.  `MATRIXSSL::tls` may remain disabled until a real mars-nwe TLS consumer
-needs it.
+`NWMatrixSSL::crypto` is the important first target for `libnwssl` and the
+Flaim CCS/NICI compat backend.  `NWMatrixSSL::tls` may remain disabled until a
+real mars-nwe TLS consumer needs it.  The built library should use a mars-nwe
+name such as `libnwmatrixssl` to avoid collisions with system MatrixSSL
+packages.

 FLAIM should not call MatrixSSL APIs directly.  Keep the layering as:

@@ -93,6 +95,10 @@ OpenSSL remains out of the default dependency policy.  Any old FLAIM/FTK
 OpenSSL-facing network code should be disabled or isolated inside the FLAIM
 import, not exposed to mars-nwe modules.

+The normal mars-nwe consumer target should be `libnwssl`, not MatrixSSL directly.
+`libnwssl` owns TLS facade APIs and the CCS/NICI compatibility API used by FLAIM;
+it links to `libnwmatrixssl` underneath.
+
 ## Planned: libflaim

 libflaim is the planned bundled persistent storage engine for the future
@@ -120,8 +126,8 @@ OpenSSL/LibreSSL TLS backend for mars-nwe.
 The first required targets are expected to be:

 ```text
-FLAIM::ftk
-FLAIM::flaim
+NWFlaim::ftk    # libnwflaimtk
+NWFlaim::flaim  # libnwflaim
 ```

 SQL FLAIM, XFLAIM, tools, tests, generated documentation, package metadata,
@@ -130,7 +136,9 @@ outputs should remain optional/off by default until mars-nwe actually needs
 them.

 FLAIM is C++ code.  mars-nwe C components should not include FLAIM C++ headers
-directly.  Access should go through the future `libdirectory` C API.
+directly.  Access should go through the future `libnwdirectory` C API.  The
+imported FLAIM libraries should be renamed to `libnwflaimtk` and `libnwflaim`
+to avoid collisions with a system FLAIM installation.

 ## Planned: zlog