​

Advanced

In short. This page holds what you need only now and then: how the deploy is protected, what is where on the server, a private repository, updates to the server scripts, rare restores, login limits, and the security checklist. Do the security checklist before you go live.

​

How the deploy is protected

• Signed tags only. Each task deploy... command checks a release tag’s signature against SESAME_ALLOWED_SIGNERS. task deploy -- <tag> checks the tag it installs. The other commands check the newest release-* tag on your computer. The command then runs deploy/deploy.sh from that tag, not the copy in your working tree.
• The server checks again. The server checks the signature against /etc/sesame/allowed_signers. It also checks that the signed tag has the name you asked for.
• One command for each touch. deploy.sh makes one SSH connection for each command. It uses no SSH agent and no forwarding, and the server’s host key must match the one you recorded.
• No shell for the deploy key. The server sends every deploy connection to sesame-deploy-shell. It accepts only deploy <tag>, rollback [tag], restore <name.db>, restore-stdin <name.db>, logs sesame|caddy, backup-now, list-backups, start and status. It records each request in the journal with the tag sesame-deploy-shell. Then it runs sudo sesamectl <command> [argument].
• The deploy account is not root. Its one sudoers rule allows sesamectl and nothing else. It is not in the docker group, because access to Docker is root access. Do not list docker compose commands in sudoers in place of sesamectl: -f, run --entrypoint and exec run any command as root.
• The server builds. sesamectl builds both images from git archive of the tag, so nothing from your computer gets to the server. It refuses to run while anyone other than root can write to /etc/sesame, a file in it, or /opt/sesame. A person who can write deploy.conf or allowed_signers chooses the code or the signer.
• Secrets stay on the server. sesame.env is root:root 0600. The deploy account cannot read it, and no command prints it.
• Backups leave encrypted. The server encrypts each backup to your age public key. The backup account can read only the encrypted copies. Neither machine has the key that decrypts them.
• Computers with agents. Sign release tags only on a computer without agents. The person who has the signing key decides what the server runs as root. If you must deploy from a computer where agents run, use a security key with a PIN (verify-required). A key file with a passphrase is not enough there. A process with your rights can read the file. It can also read the passphrase as you type it. On such a computer, the local tag check stops only an edited checkout. The protection comes from the server’s forced command and its own signature check.
• What agents may do. Agents may change Dockerfile, deploy/ and Taskfile.yml through a reviewed pull request. They never run deploys or open SSH to the server. They never use or read a key or sesame.env, and never sign or push release tags. They never edit /etc/sesame/*, SESAME_ALLOWED_SIGNERS, deploy/.deploy.env, git’s signing settings, sudoers, sshd or the firewall, and never add a proxy.
• Lost deploy key. In the provider’s web console, delete /etc/ssh/authorized_keys/deploy. If someone possibly used the key on the server, follow Session Key revocation and the incident runbook.

​

Files on the server

browser --HTTPS--> caddy :80 :443 --> sesame :8080 --> Polymarket, Telegram
your computer --SSH, one command--> deploy --> sesame-deploy-shell --> sudo sesamectl
backup machine --rsync, read only--> sesame-backup --> encrypted outbox

​

Private repository

1. In GitHub, open the repository settings, then Deploy keys. Add a key without write access.
2. On the server, put the private key in /root/.ssh.
3. Add github.com to /root/.ssh/known_hosts. Use the fingerprints that GitHub publishes.
4. In /etc/sesame/deploy.conf, write REPO_URL in the form git@github.com:<owner>/<repo>.git.

​

Updating the server scripts

sesamectl: deploy/sesamectl in <tag> differs from /usr/local/sbin/sesamectl; review it and reinstall as root ...

1. Copy the script out of the tag:
   sudo sh -c 'git -C /opt/sesame/repo.git show refs/tags/<tag>:deploy/sesamectl > /tmp/sesamectl'
   
2. Read the script:
   less /tmp/sesamectl
   
3. Install it and remove the copy:
   sudo install -o root -g root -m 0755 /tmp/sesamectl /usr/local/sbin/sesamectl && sudo rm /tmp/sesamectl
   

​

Backup details

• Every BACKUP_INTERVAL (default 6 h), the app writes sesame-<UTC time>.db to /data/backups. It keeps the newest BACKUP_KEEP backups (default 28).
• Beside each backup, the app writes <name>.mac. This is a checksum keyed from SESSION_SECRET. It proves that this app wrote the backup.
• A backup holds all the app’s data: the order audit trail, settings, alerts and login sessions.
• Every hour, sesamectl seal-backups encrypts each new backup and its .mac into /var/lib/sesame-backup/outbox/<name>.age. When the app deletes a backup, the encrypted copy goes too.
• The encryption reads only regular files, as the app’s user. It skips files over 512 MiB.
• The outbox holds at most 128 files. When it is full, the encryption stops with an error (troubleshooting).
• A restore checks the MAC, the database’s integrity and its schema. It also checks that the backup’s audit trail is the start of the current audit trail.
• A restore deletes all login sessions and logs out every remembered browser.

​

Restore an off-site copy

1. In the folder with the encrypted copies, check them against SHA256SUMS:
   sha256sum -c --ignore-missing SHA256SUMS
   
   Each file shows OK. Do not use a file that shows FAILED.
2. Decrypt the backup:
   age -d -i sesame-backup.agekey -o sesame-20261001T040000Z.db sesame-20261001T040000Z.db.age
   
3. Decrypt its .mac file:
   age -d -i sesame-backup.agekey -o sesame-20261001T040000Z.db.mac sesame-20261001T040000Z.db.mac.age
   
4. From the repository folder, upload and restore it. The ./ tells the command to upload the file:
   task deploy:restore -- ./sesame-20261001T040000Z.db
   
5. Delete the decrypted copies.

​

Restore onto a new server

1. Set up the new server with pages 1 and 2. Put the old SESSION_SECRET in sesame.env.
2. Upload the decrypted backup and its .mac as in Restore an off-site copy. The server keeps the file but refuses the restore, because there is no history to compare. The app stays stopped.
3. On the server, restore the file:
   sudo sesamectl restore-fresh <file name>
   
   It prints MAC verified; no current history to continue (...). It also prints the number of rows and the head of the order audit trail. Compare them with the last values the old server reported. The Telegram message Server started shows the head.
4. Log in and check the data.

​

Backups that fail the MAC check

1. Check the encrypted copy against SHA256SUMS before you decrypt it, as in Restore an off-site copy. Use the backup only if the check shows OK.
2. Upload it with task deploy:restore. The server keeps the file and refuses the restore.
3. On the server, go to the app’s folder:
   cd /opt/sesame
   
4. Stop the app:
   sudo docker compose stop sesame
   
5. Install the backup without the checks:
   sudo docker compose run --rm --no-deps -T sesame restore --from <file name> --accept-unverified-backup
   
6. Start the app:
   sudo sesamectl start
   

​

Login limits

• Each IP address gets 5 wrong passwords. An IPv6 address counts as its /64 network.
• After that, each wrong password locks that address out. The lockout starts at 1 minute and doubles each time, up to 15 minutes. After 1 hour with no attempt, the count starts again.
• A second limit covers all browsers that did not log in before, together: 20 login attempts a minute. A person with four or more new IPv6 networks a minute can keep new browsers out while this lasts.
• A browser that logged in before is remembered for 180 days. These limits do not stop it.
• Each time the second limit stops a browser, you get the notification Logins refused for new devices. You get at most one each minute.
• Log out everywhere and each restore make all browsers new again.

​

Security checklist

curl -6 -s -o /dev/null -w '%{http_code}\n' -H 'Origin: https://<your-domain>' \
  -H 'Content-Type: application/json' --data '{"password":"wrong"}' https://<your-domain>/api/auth/login
task deploy:logs -- caddy
task deploy:logs -- sesame

cd /opt/sesame && sudo docker compose exec -T sesame /sesame audit-verify /data

sudo stat -c '%U:%G %a' /opt/sesame/sesame.env                     # root:root 600
sudo stat -c '%U:%G %a %n' /etc/sesame /etc/sesame/* /opt/sesame    # root:root, no group or other write
ls -l /etc/ssh/authorized_keys                                      # root:root 0644 files
id deploy                                                           # no docker group
getent passwd deploy sesame-backup                                  # /bin/sh for both
sudo -l -U deploy                                                   # only /usr/local/sbin/sesamectl
sudo sshd -T -C user=deploy,host=x,addr=<your-ip> | grep forcecommand   # /usr/local/sbin/sesame-deploy-shell
sudo docker inspect sesame-sesame-1 --format '{{.Config.User}} {{.HostConfig.ReadonlyRootfs}} {{.HostConfig.CapDrop}} {{.HostConfig.SecurityOpt}}'
sudo docker inspect sesame-caddy-1 --format '{{.Config.User}} {{.HostConfig.ReadonlyRootfs}} {{.HostConfig.CapDrop}} {{.HostConfig.Memory}} {{.HostConfig.PidsLimit}}'
timedatectl | grep synchronized                                     # yes

ssh -i ~/.ssh/sesame_deploy -o IdentityAgent=none deploy@<your-domain> id
ssh -i ~/.ssh/sesame_deploy -o IdentityAgent=none deploy@<your-domain>
ssh -i ~/.ssh/sesame_deploy -o IdentityAgent=none deploy@<your-domain> restore-fresh x.db

​

Further reading

• configuration.md: every setting.
• Session Key setup, Telegram, live verification and incidents.
• The security reviews behind this setup: threat model, phase 6 findings and phase 6 recheck.