env vars
the file options there are relevant for secrets, to prevent them from leaking into the (public) nix store directory. to this end, make sure to pass file path as strings, not as actual path types.
naming
there are some common fields that maybe have nix conventions, tho where we don’t need to wrap options we do try and (as per RFC42) transparently expose upstream ones
secrets
externalPath sounds advisable yeah, tho in some toy settings people may still be passing in-store credentials as it’s easy.
for LoadCredential there should be some examples in nixpkgs - e.g. homebox’s, which does in fact look similar to your example there, if a bit further generalized (to account for multiple distinct secrets like that).
How much should a service module provide?
i think so far in practice this has ended up a function of how much effort people have wanted to put into a module / how much they wanted out of it. i agree the RFC would make things easier (and in fact, i think its initial PR could use some reviews).
linting / best practices
for linting, i think there have been several different efforts at least:
statixlintsnildiagnosticsnixddiagnosticsnixpkgs-hammeringoverlays (explanations)- @tfc’s book ‘Nix Antipatterns’
there would probably be room to consolidate some more of that.