Ships `modules/dev-env/scripts/git-hooks/pre-commit` — the same
secret-scanner pattern omnixy uses, lightly adapted (drops the
omnixy-specific test_auth.py skip, generic header comment).
New option `lnbits-sensei.devEnv.gitHooks.enable` (off by default).
When on, modules/dev-env/config.nix installs the hook at
`~/.local/share/lnbits-sensei/git-hooks/pre-commit` and sets the
consumer's git `core.hooksPath` to that directory, so every repo on
the machine picks it up without per-repo wiring.
The hook refuses to commit obvious secrets (PRIVATE KEY blocks,
`password=…`, `secret=…`, `api_key=…`, `admin_key=…`, AWS keys,
non-placeholder POSTGRES_PASSWORD) and unencrypted sops files
(checks for a top-level `sops:` block AND `mac: ENC[…]` — either
signal alone is forgeable). False positives are handled via
`# pragma: allowlist secret` line- or block-level markers (gitleaks
convention).
docs/secrets-management.md gets a new subsection covering what the
hook does, when to enable it, and the false-positive escape hatches.
The Pitfalls section's reference to "the pre-commit hook most
consumers use" is replaced with a concrete pointer to this option.
`nix flake check --no-build` stays green.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New docs/secrets-management.md walks through getting secrets out of
.env and into sops-encrypted YAML, assuming zero familiarity with
sops or age. Companion to the wiring landed in the prior commit.
Sections:
- Why bother — the .env failure modes (history leaks, plaintext on
disk) and what sops/age fixes.
- What's in the box — pointers to the existing scaffold (flake input,
modules/secrets.nix, .sops.yaml, .gitignore guards), why it's inert
until the first encrypted file lands.
- Step-by-step — install tools, generate the age key (with a clear
warning about back-ups + no recovery), paste the public key into
.sops.yaml, create the first encrypted file via `sops`, declare
secrets in NixOS, reference via config.sops.secrets.<name>.path,
activate.
- Common operations — edit / view / rotate / updatekeys.
- Multi-host server deployment — per-host age keys at
/var/lib/sops-nix/key.txt, path_regex-scoped recipients in
.sops.yaml so each host only decrypts its own secrets.
- Pitfalls — don't commit unencrypted YAML, don't lose the key,
updatekeys ≠ rotation, sops -d outputs are sensitive, the
pathExists gate fails-silently-on-delete trap.
Linked from README "Further reading" with a one-liner noting the
sops-nix wiring already ships with the scaffold.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two new docs to round out the lnbits-specific reference set:
docs/lnbits-frontend-gotchas.md — the Vue/Quasar UMD traps that don't
manifest under the build-step model most tutorials assume. Sections:
- No self-closing tags. UMD-loaded templates are parsed by the
browser's HTML parser, which doesn't honor self-close on non-void
elements; nesting silently breaks. Fine in .vue SFCs because the
build step rewrites them — but lnbits templates aren't SFCs.
- CSS specificity vs Quasar utilities. LNbits applies !important
overrides on .text-caption / .text-grey-*; class-based rules in
extension pages lose. Reach for inline :style bindings or static
style="" attrs instead.
- Cache busting via ?v={server_startup_time}. Bumping JS requires a
server restart; templates re-render every request.
- Dark-mode color discipline. bg-{color}-1 utilities don't get a
default text-inversion in dark theme; pair every pale background
with an explicit text class.
docs/lnbits-extension-dev.md — auth + testing + migration pattern.
Sections:
- Auth decorators table: require_invoice_key, require_admin_key,
check_admin, check_super_user. The require_admin_key vs
check_admin distinction is the most common misuse — one is
wallet-level write access (any user), the other is instance admin.
- Testing: FakeWallet for CRUD/API/UI, regtest only for real
Lightning behavior. Why the dev CLI defaults to --fakewallet.
- The migrations_fork.py pattern: keep migrations.py byte-identical
to upstream, put fork-only schema deltas in a sibling file loaded
under <ext>_fork in dbversions. Covers: architecture facts
(dbversions in core DB, no cross-DB atomicity → idempotent
migrations mandatory), squash recipe for adoption, one-time
dbversions surgery for installs that previously ran old fork
migrations, the upstream-overlap rebase scenario.
Both linked from README "Further reading". No personal identity in
either file.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
LNbits has two sources of truth for settings depending on lifecycle.
The trap: on first boot, .env seeds the DB; on every subsequent boot,
the DB row overwrites the in-memory Settings. Editing .env after the
first boot is a no-op for editable fields — they can only change via
the Admin UI or by clearing rows in system_settings.
Documented:
- the boot-time read-DB → seed-from-env → overwrite-cached-Settings
sequence with file:line references for verification
- exceptions where env still wins (super_user, lnbits_admin_ui=False,
the full ReadOnlySettings field list)
- LNBITS_FIRST_INSTALL_TOKEN rotation does NOT reset settings to env
(it's an admin-recovery escape hatch, not a config-refresh)
- the deploy-side implication: declarative env vars are a *seed*
for EditableSettings, authoritative for ReadOnlySettings — plan
your deploy story accordingly
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
New docs/lnbits-workspace-notes.md collects the day-to-day gotchas
that have repeatedly surprised people doing lnbits dev work — content
that lives in personal CLAUDE.md / memory notes elsewhere but is
genuinely useful as a public reference once stripped of identity.
Sections:
- pick a non-default port (5000 collides with macOS AirPlay etc.)
- LNBITS_SRC + docker-compose build context (commits don't reach
the dev image if the build context points at a stale worktree;
`docker compose config | grep -A2 lnbits` to verify)
- extension folder mounted as install target: clicking "Upgrade"
in the LNbits UI extracts the catalog tarball over the mounted
fork checkout, wiping .git
- Nostr key handling: upstream stores user nsecs plaintext in
accounts.prvkey; signer-abstraction shape (LocalSigner with
envelope-encrypted blob / RemoteBunkerSigner via NIP-46 /
ClientSideOnlySigner) with the "prefer don't-store-the-key"
principle
- CLINK protocol scope: Shocknet's 21001-21003 event kinds are
Lightning.Pub-specific; LNbits has zero CLINK knowledge; how
to think about cross-system designs without conflating them
- fork versioning: v<upstream>-<tag>.<N> + the PEP 440
`+<tag>.<N>` package-version form for pyproject.toml
- codebase reading tips (key paths, --first-parent log reading)
Linked from README "Further reading". No personal identity in the
new doc — scrubbed of aiolabs/atitlan/bohm/etc references.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two new docs under docs/:
- upstream-prs.md — how to send a PR upstream using the
~/dev/upstream-prs/ worktree flow. Opens with a "Primer" section
for anyone new to forks / pull requests (the three remote roles —
upstream / github-fork / origin — explained as a table), then the
per-project prerequisites, the prb/prc helper-driven workflow, and
a "Common pitfalls" section.
- lnbits-upstream-flow.md — reference for how lnbits/lnbits actually
moves: the dev/main branch split, the squash-merge PR convention,
the non-FF release merge from dev into main, and how to read the
history with --first-parent. Adapted from internal aiolabs notes
with the fork-versioning specifics stripped; closing section is
generic guidance for anyone maintaining their own long-lived fork.
README links both from a new "Further reading" section. The prior
"Contributing" section is retitled "Contributing to this scaffold"
to avoid colliding with the new upstream-PR doc on the term.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
modules/git/remotes.nix declares upstream/fork/extras schema. extras is
a typed submodule list so order is preserved and future fields
(pushUrl, mirror) can extend without breaking callers. docs/remotes.md
walks the three canonical topologies (upstream-only / github-fork /
multi-remote with private host).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
