diff --git a/REDESIGN.md b/REDESIGN.md index e960027..54fe749 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -1067,6 +1067,164 @@ This keeps the future NetWare 4.x work aligned with the provider/process split: `nwdirectory`, `nwnds`, and `nwbind` may be separate processes or modules, but they should not be separate sources of truth for identity and directory data. +## Third-party and forked component integration policy + +The long-term redesign should distinguish between three different kinds of +imported code: + +```text +1. fixed third-party building blocks kept under third_party/ +2. optional third-party backends kept behind mars-nwe facades +3. forked mars-nwe components kept at the repository root +``` + +Do not treat all imported code the same way. A small, mostly unmodified library +that is built as part of mars-nwe belongs under `third_party/`. A component that +will be forked, renamed, given CMake support, wired into mars-nwe storage, and +changed as part of the server design should live at the repository root like the +existing project components (`admin`, `dosutils`, `mail`, `smart`). + +The intended layout is: + +```text +third_party/yyjson + existing fixed JSON dependency used by salvage metadata + +third_party/wolfssl + fixed TLS dependency used by mars-nwe TLS code + configured through CMake for the server's supported platforms and features + +third_party/zlog + optional advanced logging backend used only through nwlog + +mars-tinyldap/ + forked/integrated tinyldap-derived component in the repository root + project-facing service name: nwdirectory + converted to the mars-nwe CMake build + later wired to libdirectory/libflaim instead of tinyldap's original flat files +``` + +### TLS dependency rule + +wolfSSL should be the fixed TLS implementation shipped with the tree, similar in +spirit to the bundled yyjson dependency. Do not design the first TLS integration +as an abstract zoo of OpenSSL, LibreSSL, wolfSSL, and other providers. wolfSSL is +portable and can be configured through CMake for the needs of the target server, +so it should be the implementation used for: + +- LDAP/LDAPS/StartTLS at the `nwdirectory` network edge; +- any future TCP-based internal provider IPC, where wolfSSL-backed mTLS is + required; +- future TLS-capable admin or service endpoints, if they are explicitly added. + +However, mars-nwe code should still not include wolfSSL headers everywhere. TLS +call sites should go through a small internal facade: + +```text +include/nwtls.h +src/nwtls.c +src/nwtls_wolfssl.c +``` + +The facade is not meant to promise equal OpenSSL/LibreSSL support. Its purpose +is to keep certificate loading, policy checks, mTLS requirements, error logging, +secure defaults, and wolfSSL-specific setup in one place. If another TLS backend +is ever evaluated much later, it can be hidden behind the same API, but the +planned bundled backend is wolfSSL. + +Protocol handlers and provider code should therefore use `nwtls` concepts, not +raw wolfSSL types. Example ownership: + +```text +nwdirectory LDAP listener -> nwtls -> wolfSSL +provider TCP IPC -> nwtls -> wolfSSL/mTLS +nwlog/security logging -> logs TLS events, never private key material +``` + +TLS configuration belongs in the documented INI, but private key material does +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. + +### zlog dependency rule + +`zlog` should be treated as an optional advanced logging backend under +`third_party/zlog`, not as a direct API used by handlers. The mars-nwe public +logging API remains `include/nwlog.h`. If zlog is enabled, it is reached through +`src/nwlog_zlog.c` only: + +```text +endpoint/provider code -> nwlog -> optional zlog backend +``` + +This keeps secret redaction, structured correlation fields, fallback logging, and +future backend changes centralized. zlog can provide administrator-controlled +category/rule/format routing, but it must never receive raw decoded NCP or +handoff payloads from bypass paths. + +### Forked tinyldap / nwdirectory rule + +`tinyldap` is different from yyjson, wolfSSL, and zlog. It is not merely a small +library dependency. The planned integration requires a fork because the original +code needs mars-nwe-specific work: + +- CMake build support; +- mars-nwe service naming (`nwdirectory`); +- LDAP/LDAPS/StartTLS integration through `nwtls`/wolfSSL; +- replacement or bypass of the original flat-file storage; +- later `libdirectory` and libflaim-backed storage integration; +- directory schema, bootstrap, and setup integration through `nwsetup`. + +Because of that, the fork should live in the repository root as `mars-tinyldap/`, +matching the existing pattern for project components that are not treated as +plain third-party libraries. The code may still document its upstream origin, +license, and local changes, but it is part of the mars-nwe component tree. + +The architectural relationship remains: + +```text +LDAP/LDAPS client + -> nwdirectory service built from mars-tinyldap + -> libdirectory + -> libflaim-backed store +``` + +`nwbind` and future `nwnds` should not speak LDAP internally just because the LDAP +service exists. They should use `libdirectory` directly, while `nwdirectory` +exposes LDAP as an external protocol view of the same directory data. + +### Versioning and local-change documentation + +Each bundled or forked dependency should have a short mars-nwe note describing: + +- upstream project and URL; +- pinned commit/tag or submodule branch policy; +- license; +- whether it is fixed, optional, or forked; +- which mars-nwe facade owns access to it; +- local changes carried by mars-nwe; +- CMake options used by the mars-nwe build. + +Do not silently update third-party submodules together with unrelated functional +changes. Dependency bumps should be separate patches. Forked root components +should keep a `README.mars-nwe.md` or equivalent local-change note so future +updates can be reviewed without guessing which changes are upstream and which are +project integration work. + +Suggested build options: + +```text +WITH_ZLOG=ON/OFF/AUTO optional advanced logging backend +WITH_WOLFSSL=ON/OFF/AUTO bundled TLS backend; required when TLS features are enabled +WITH_NWDIRECTORY=ON/OFF build the mars-tinyldap/nwdirectory component +WITH_NWNDS=ON/OFF future NetWare 4.x/NDS compatibility layer +WITH_LIBFLAIM=ON/OFF/AUTO future directory store backend +WITH_TCP=ON/OFF future client-facing TCP/IP transport +``` + +Conservative builds should still be able to disable incomplete future components, +but once a feature requires TLS, its supported TLS implementation is wolfSSL. + ## Configuration redesign and future typed INI files The current `nw.ini`/`nwserv.conf` format is historically user-editable, but it diff --git a/third_party/README.md b/third_party/README.md index 5a44f48..0d803eb 100644 --- a/third_party/README.md +++ b/third_party/README.md @@ -1,5 +1,10 @@ # Third-party dependencies +This directory is for mostly external building blocks that are built or linked by +mars-nwe but are not project-specific service forks. Code here should normally +be accessed through a mars-nwe facade or subsystem instead of being included +from endpoint/provider code directly. + ## yyjson The salvage metadata backend uses the bundled yyjson submodule for JSON @@ -16,3 +21,47 @@ CMake expects `third_party/yyjson/CMakeLists.txt` to exist. Reader and writer support stay enabled; yyjson tests, fuzzer, misc tools, docs, install targets, JSON5/non-standard support, utilities and incremental reader support are disabled for the mars-nwe build. + +## Planned: wolfSSL + +wolfSSL is the planned fixed TLS implementation for mars-nwe. It should be +added as `third_party/wolfssl` and configured by CMake for the server's supported +platforms and enabled TLS features. + +mars-nwe code should not include wolfSSL headers directly from arbitrary +subsystems. TLS users should go through the future `include/nwtls.h` facade and +its wolfSSL backend, for example: + +```text +include/nwtls.h +src/nwtls.c +src/nwtls_wolfssl.c +``` + +Planned uses include LDAP/LDAPS/StartTLS in `nwdirectory` and any future +TCP-based internal provider IPC that requires mTLS. + +## Planned: zlog + +zlog is the planned optional advanced logging backend. If added, it should live +under `third_party/zlog` and be used only through the mars-nwe `nwlog` facade: + +```text +include/nwlog.h +src/nwlog.c +src/nwlog_zlog.c +``` + +Endpoint and provider code must not call zlog APIs directly. This keeps secret +redaction, request correlation fields, and fallback logging centralized. + +## Forked components are not third_party + +Components that are forked and integrated as mars-nwe services should live at the +repository root, following the existing pattern used by `admin`, `dosutils`, +`mail`, and `smart`. + +The planned tinyldap fork is such a component. It should live as +`mars-tinyldap/` at the repository root, build the project-facing `nwdirectory` +service, gain CMake support, and later use `libdirectory`/libflaim-backed +storage instead of tinyldap's original flat-file storage.