diff --git a/AGENTS.md b/AGENTS.md index 88c9c17..db9352b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -47,6 +47,8 @@ source/ C++ application source timeutil.cpp/h Server clock parsing (RFC 3339 and RFC 7231) fsutil.cpp/h mkdirs, temp-file + atomic-replace helpers hash.cpp/h MD5 and the Dropbox content hash + certtrust.cpp/h PinnedKey= / CACert= parsing (TlsTrust), IP names in a + certificate; Curl does the checking tlsclose.cpp close_notify for libcurl's TLS connections (link-time wrap) sockopt.cpp SO_ERROR in newlib's numbering, for libsmb2 (link-time wrap) cancel.cpp/h START as a running transfer sees it (transferCancelled()) @@ -107,12 +109,12 @@ The Makefile auto-discovers all `.cpp` files under `source/`. Adding a new `.cpp ```bash arm-none-eabi-g++ -fsyntax-only -std=gnu++11 -Wall \ -march=armv6k -mtune=mpcore -mfloat-abi=hard -mtp=soft -D__3DS__ -DARM11 \ - -DINI_MAX_LINE=2048 \ + -DINI_MAX_LINE=16384 -DINI_USE_STACK=0 -DINI_INITIAL_ALLOC=16384 \ -I$DEVKITPRO/libctru/include -I$DEVKITPRO/portlibs/3ds/include \ -I$DEVKITPRO/portlibs/armv6k/include source/main.cpp ``` -`source/libs/inih/ini.c` and `ini.h` are byte-identical to [benhoyt/inih](https://github.com/benhoyt/inih) `577ae2d` (2026-01-30) and must stay that way, so the next resync is a two-file copy with no patch to re-apply. Compile-time configuration of them therefore belongs in `BUILD_FLAGS` in the Makefile: `INI_MAX_LINE=2048` is set there because upstream's 200 truncates a pasted `Token=`, which is an OAuth access token and can exceed a kilobyte. When bumping, re-check that `ini_parse()` and `ini_parse_string()` keep their signatures and that `INI_HANDLER_LINENO` still defaults to 0 — `INIReader::ValueHandler` is a 4-argument handler. +`source/libs/inih/ini.c` and `ini.h` are byte-identical to [benhoyt/inih](https://github.com/benhoyt/inih) `577ae2d` (2026-01-30) and must stay that way, so the next resync is a two-file copy with no patch to re-apply. Compile-time configuration of them therefore belongs in `BUILD_FLAGS` in the Makefile: `INI_MAX_LINE=16384` is set there because upstream's 200 truncates a pasted `Token=`, which is an OAuth access token and can exceed a kilobyte, and a `CACert=` line is a whole CA certificate in base64. The buffer is on the heap (`INI_USE_STACK=0`, allocated at full size by `INI_INITIAL_ALLOC`) rather than 16 KB of the main thread's stack; `INI_ALLOW_REALLOC` is avoided because its code does not compile as C++, which the host tests build `ini.c` as. `tests/Makefile` repeats the flags. When bumping, re-check that `ini_parse()` and `ini_parse_string()` keep their signatures and that `INI_HANDLER_LINENO` still defaults to 0 — `INIReader::ValueHandler` is a 4-argument handler. `source/libs/inih/INIReader/` is *not* upstream and cannot be resynced blindly: `GetValues()` is a local addition that `getConfiguredSyncPaths()` depends on, and upstream's `INIReader` exposes no equivalent; `Set()` (sealed credentials) and `GetSpelling()` (a key's name as the file wrote it, see "Path names keep their spelling") are local too. @@ -133,9 +135,10 @@ Keep the format `major.minor.micro`: the Makefile splits it on the dots and `mak - **C++11**, no exceptions, no RTTI. - Logic worth testing goes in a unit that does not include `<3ds.h>`, libcurl or libsmb2, and gets a test. The providers should stay thin: talk to the network, hand the response to a parser. - All HTTP goes through the `Curl` wrapper (`source/utils/curl.h`). Never call libcurl directly. -- **Certificates are checked on every TLS connection.** `Curl::_applyDefaults()` sets `VERIFYPEER`/`VERIFYHOST` and hands mbedTLS the roots from `romfs/cacert.pem` through `CURLOPT_SSL_CTX_FUNCTION` (`_sslContext()`), parsed once per run (`caChain()`): libcurl would otherwise reparse the file per connection, and FTPS opens one per transfer. It also clears `CAINFO`/`CAPATH`, because devkitPro's libcurl defaults to `sdmc:/config/ssl/cacert.pem`, which most cards lack. The callback runs after libcurl's own `mbedtls_ssl_conf_ca_chain()` (checked with `objdump` on libcurl 8.4: the indirect call follows it in `mbed_connect_common`), so its chain wins; recheck after a libcurl bump. Only WebDAV and FTP may turn checking off (`VerifyTLS=false` → `Curl::setVerifyTls(false)`, parsed in `remoteconfig.cpp`). A certificate failure (curl 60, or 77 for a missing bundle) is fatal for that remote, never retried, and explained by `Curl::printCertificateHelp()` — including the 3DS date, since an unset clock is the likeliest cause. Update the bundle with curl's published file and checksum (`https://curl.se/ca/cacert.pem` and `.sha256`). +- **Certificates are checked on every TLS connection.** `Curl::_applyDefaults()` sets `VERIFYPEER`/`VERIFYHOST` and hands mbedTLS the roots from `romfs/cacert.pem` through `CURLOPT_SSL_CTX_FUNCTION` (`_sslContext()`), parsed once per run (`caChain()`): libcurl would otherwise reparse the file per connection, and FTPS opens one per transfer. It also clears `CAINFO`/`CAPATH`, because devkitPro's libcurl defaults to `sdmc:/config/ssl/cacert.pem`, which most cards lack. The callback runs after libcurl's own `mbedtls_ssl_conf_ca_chain()` (checked with `objdump` on libcurl 8.4: the indirect call follows it in `mbed_connect_common`), so its chain wins; recheck after a libcurl bump. Only WebDAV and FTP may change what is trusted, through a `TlsTrust` (`utils/certtrust.h`, parsed in `remoteconfig.cpp`, handed to `Curl::setTrust()`) — see the next point. A certificate failure (curl 60, or 77 for a missing bundle or an unreadable `CACert=`) is fatal for that remote, never retried, and explained by `Curl::printCertificateHelp()` — including the 3DS date, since an unset clock is the likeliest cause, and for WebDAV/FTP the `PinnedKey=` line for the key the server presented. Update the bundle with curl's published file and checksum (`https://curl.se/ca/cacert.pem` and `.sha256`). - **Remote names never leave the sync folder.** `syncEntry()` drops every listed relPath that `isSafeRelativePath()` (`utils/pathutil`) refuses — a `..`, `.` or empty segment, a backslash, a control character — before anything is decided, says so once per remote and entry, and adds a `problems` entry. Providers need not check this themselves, but must not "fix" such a name into something that passes. - **A transfer that stops receiving gives up after 60 s** (`CURLOPT_LOW_SPEED_LIMIT`/`_TIME` in `Curl::_applyDefaults()`, `STALL_SECONDS`). Wi-Fi dropping mid-file sends no error — the connection just goes quiet — and libcurl's only other limit is the 50 s connect timeout, so a ROM download once waited until START. The timeout is `CURLE_OPERATION_TIMEDOUT`, which every provider retries; a retry must discard what a stalled download already wrote (`rewindDownloadFile()` — FTP did not, and appended to the half file) and FTP opens a fresh connection for it. +- **A WebDAV or FTP remote can trust its own server** (#72). `PinnedKey=` is the SHA-256 of the server's public key (SubjectPublicKeyInfo) or of its certificate, comma-separated for several; `CACert=` is base64 DER on one line (the configurator converts the `.pem`). `parsePinnedKeys()`/`parseCaCerts()` in `utils/certtrust.cpp` are host-tested and mirrored by `pinnedKeyProblem()`/`caCertProblem()` in `inifile.js` — change both together. One that does not parse leaves the remote out (a startup issue), never falls back to not checking; either overrides `VerifyTLS=false`; with both, the pin decides and `CACert=` is dropped with an issue. Dropbox, Drive and SMB ignore both with an issue. On the 3DS `_sslContext()` gives mbedTLS `CACert=`'s chain *instead of* the bundle (parsed once per handle, `ownCaChain()`) and always installs `_verifyCertificate()` with `mbedtls_ssl_conf_verify()`: it records the server's key hash (for the help text) and, with a pin, holds back the chain's flags until depth 0 (always called last) and clears all of them on a match — self-signed, unknown issuer, wrong name, expiry — or adds `MBEDTLS_X509_BADCERT_OTHER` on a mismatch. That relies on libcurl 8.4 setting `MBEDTLS_SSL_VERIFY_OPTIONAL`, reading `mbedtls_ssl_get_verify_result()` afterwards, and setting no verify callback of its own (checked with `objdump`/`nm`); recheck after a libcurl bump. `CURLOPT_PINNEDPUBLICKEY` was not used because it cannot accept a certificate hash nor say which key it saw. The long `CACert=` line is why `INI_MAX_LINE` is 16384, on the heap (`INI_USE_STACK=0`); see "Build". - `Curl::perform()` returns 0 on network success. **HTTP status is not checked by `perform()`** — callers must call `getStatusCode()`. `CURLOPT_FAILONERROR` is intentionally disabled so error response bodies are captured. - Every provider owns a `_performWithRetry()` that maps transport errors to *transient* (retry with back-off), *fatal* (`_fatalError`, stop the run) or *per-file* (log and skip). Never call `_curl.perform()` directly from a provider method — the retry helper is also where the server `Date` header is captured. - libcurl options are sticky on a handle. Providers that issue more than one shape of request call `Curl::reset()` first (via their own `_prepare()`); otherwise `NOBODY`, `UPLOAD`, `WILDCARDMATCH` or a custom method leaks into the next call. @@ -330,6 +333,9 @@ Mode=passive ; passive | active Url=https://host/remote.php/dav/files/user/ User=... Password=... +PinnedKey=... ; WebDAV and FTP: SHA-256 of the server's key (hex or sha256//base64) +CACert=... ; WebDAV and FTP: own CA certificate(s), base64 DER on one line +VerifyTLS=false ; WebDAV and FTP: don't check the certificate at all [SMB:Backup] ; a second remote of a type: [: