Skip to content

Docs: setup guide and manual Telegram test #16

Closed

Description

@groupsky

Why

A person must be able to set it up without reading the code.

What

  • README quick start.
  • docs/setup.md: broker with systemd encrypted credentials, the strict known_hosts, a client, a Telegram bot, and account safety (never log in to the approving Telegram account on an agent machine).
  • docs/manual-telegram-test.md: the steps for a real-bot test.

Done when

  • The setup guide was followed once on a test machine.

  • The manual test steps exist.

  • The example systemd unit sets LogRateLimitIntervalSec=0. Over its rate limit, journald drops lines without notice, and the audit anchors would be lost. (From the Audit log: hash chain, verify, torn-line recovery #5 review.)

  • bws and the standalone bw come from the official releases, owned by root, in directories only root can write to; with an npm bw, the node found through the fixed PATH is owned by root. No bw-data directory next to bw or node. (From the Secret stores: bws and bw #8 review.)

  • Login and server setup for a store run with exactly the broker's environment (sudo -u nodkey env -i HOME=<stores>/NAME PATH=<fixed PATH> <program> …); afterwards bw status shows the separate account. No bw lock or bw unlock by hand in a store home. The bw KDF settings let an unlock finish within 30 s. The secret is the password of a login item.

  • The example unit sets StateDirectory= (stores directory 0700), UMask=0077, LimitCORE=1, network access to Bitwarden, and no MemoryDenyWriteExecute= when bw (Node.js) is used.

  • The broker host keeps a pipe (|) or file core_pattern (the systemd default), because the core limit of 1 does not stop the newer socket (@) form from passing a crash dump with secrets to systemd-coredump. (From the Secret stores: bws and bw #8 review.)

Activity

  1. added this to the v1 milestone on Oct 12, 2026
  2. groupsky commented on Oct 15, 2026

    @groupsky
    ContributorAuthor

    Status 2026-10-15: the setup guide (docs/setup.md), the quick start in README.md and the manual test steps (docs/manual-telegram-test.md) are merged in #71. The example unit has every setting this issue lists (checked; it was already in #60).

    First "Done when" item, partly done. The guide was followed once in a throwaway Debian 12 container with the real bws 2.1.0 and bw 2026.9.1: sections 2 to 8 and the testable parts of 9 to 14. Not yet followed:

    • a real systemd start with LoadCredentialEncrypted= and the unit's sandbox with bw on Node.js;
    • the TPM2 path;
    • the real Telegram and the real Bitwarden.

    This item stays open until the guide is followed on a real test host. The real-bot part comes with #17.

  3. groupsky commented on Oct 20, 2026

    @groupsky
    ContributorAuthor

    The setup guide was followed once on 2026-10-20, on a new VPS with Debian 13 and no TPM2 (--with-key=host). It used nodkey 0.2.0 from install.sh on both the broker and the client, with one bws store, one client and one test secret (ask = "always").

    • The broker started with every log line of section 10.
    • The client got the test secret after an "Approve once" on the phone, twice.
    • nodkey audit verify with the journal's anchors passed: 4 entries, 0 torn lines, all anchors match.

    bw was not part of this run. Closing, as every box is ticked.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Projects

    No projects

      Milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions