From 502971183bbb619e0dc32b60a6a8ac500119a146 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Yago=20P=C3=A9rez?= <5002453+yagop@users.noreply.github.com>
Date: Sat, 27 Jun 2026 15:24:32 +0200
Subject: [PATCH] feat(session): store session in macOS Keychain by default

Add a sessionStore abstraction so session read/exists/delete go through a
single seam, with two backends: a file (existing behaviour, used off macOS
and when keychain is disabled) and the macOS login Keychain via the
`security` CLI (no cgo, keeps the static binary).

Keychain is the default on macOS; set `keychain: false` to opt out. An
existing file session is migrated into the Keychain on first use and the
file is removed; logout clears both.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md                              |   7 +-
 cmd/tg/accounts.go                     |  10 +--
 cmd/tg/app.go                          |  12 +--
 cmd/tg/config.go                       |   5 ++
 cmd/tg/logout.go                       |  13 +--
 cmd/tg/session_keychain_darwin.go      | 116 +++++++++++++++++++++++++
 cmd/tg/session_keychain_darwin_test.go | 107 +++++++++++++++++++++++
 cmd/tg/session_keychain_other.go       |   9 ++
 cmd/tg/session_store.go                |  80 +++++++++++++++++
 cmd/tg/session_store_test.go           |  78 +++++++++++++++++
 10 files changed, 416 insertions(+), 21 deletions(-)
 create mode 100644 cmd/tg/session_keychain_darwin.go
 create mode 100644 cmd/tg/session_keychain_darwin_test.go
 create mode 100644 cmd/tg/session_keychain_other.go
 create mode 100644 cmd/tg/session_store.go
 create mode 100644 cmd/tg/session_store_test.go

diff --git a/README.md b/README.md
index f534023..d45d008 100644
--- a/README.md
+++ b/README.md
@@ -28,8 +28,11 @@ binaries embed them at build time and present the session as a desktop client, s
 <https://my.telegram.org>: `tg init --app-id APP_ID --app-hash APP_HASH`.
 
 The config is written to the `gotd` subdirectory of your config dir, e.g.
-`~/.config/gotd/gotd.cli.yaml`. The session persists there too, so subsequent
-commands run headless.
+`~/.config/gotd/gotd.cli.yaml`. The session persists too, so subsequent commands
+run headless. On macOS the session is stored in the login Keychain by default; an
+existing file session is migrated into the Keychain automatically on first use.
+Set `keychain: false` in the config to keep it in a file alongside the config
+instead (useful for headless macOS). Other platforms always use a file.
 
 ### Login options
 
diff --git a/cmd/tg/accounts.go b/cmd/tg/accounts.go
index b3d3900..48fd160 100644
--- a/cmd/tg/accounts.go
+++ b/cmd/tg/accounts.go
@@ -4,7 +4,6 @@ import (
 	"fmt"
 	"io"
 	"os"
-	"path/filepath"
 
 	"github.com/go-faster/errors"
 	"github.com/spf13/cobra"
@@ -50,7 +49,6 @@ func (a *app) newAccountsCmd() *cobra.Command {
 		Long:    "List configured accounts (with auth status), or add/remove named accounts.",
 		Args:    cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			dir := filepath.Dir(a.configPath)
 			def := a.cfg.resolvedDefault()
 			var res accountsResult
 			for _, label := range a.cfg.labels() {
@@ -58,13 +56,15 @@ func (a *app) newAccountsCmd() *cobra.Command {
 				if err != nil {
 					return err
 				}
-				sessionPath := acc.sessionPath(dir, label, kindUser)
-				_, statErr := os.Stat(sessionPath)
+				hasSession, err := a.sessionStore(label, acc, kindUser).Exists(cmd.Context())
+				if err != nil {
+					return errors.Wrapf(err, "check session for %s", label)
+				}
 				res.Accounts = append(res.Accounts, accountStatus{
 					Label:      label,
 					AppID:      acc.AppID,
 					HasBot:     acc.BotToken != "",
-					HasSession: statErr == nil,
+					HasSession: hasSession,
 					Default:    label == def,
 				})
 			}
diff --git a/cmd/tg/app.go b/cmd/tg/app.go
index 813e676..9a8529c 100644
--- a/cmd/tg/app.go
+++ b/cmd/tg/app.go
@@ -2,7 +2,6 @@ package main
 
 import (
 	"context"
-	"path/filepath"
 
 	"github.com/go-faster/errors"
 	"github.com/spf13/cobra"
@@ -10,7 +9,6 @@ import (
 
 	"github.com/gotd/contrib/middleware/floodwait"
 	"github.com/gotd/log/logzap"
-	"github.com/gotd/td/session"
 	"github.com/gotd/td/telegram"
 	"github.com/gotd/td/telegram/dcs"
 	"github.com/gotd/td/tg"
@@ -189,12 +187,10 @@ func (a *app) optionsFor(st *accountState, rp runParams, d tg.UpdateDispatcher)
 	}
 
 	opts := telegram.Options{
-		Logger:      logzap.New(a.log.Named("tg")),
-		Device:      deviceConfig(),
-		Middlewares: mw,
-		SessionStorage: &session.FileStorage{
-			Path: st.acc.sessionPath(filepath.Dir(a.configPath), st.label, rp.auth.String()),
-		},
+		Logger:         logzap.New(a.log.Named("tg")),
+		Device:         deviceConfig(),
+		Middlewares:    mw,
+		SessionStorage: a.sessionStore(st.label, st.acc, rp.auth.String()),
 	}
 	if rp.updates {
 		opts.UpdateHandler = d
diff --git a/cmd/tg/config.go b/cmd/tg/config.go
index f422413..1e5f87c 100644
--- a/cmd/tg/config.go
+++ b/cmd/tg/config.go
@@ -42,6 +42,11 @@ type Config struct {
 	// Empty means the top-level "default" account.
 	DefaultAccount string `yaml:"default_account,omitempty"`
 
+	// Keychain stores the session in the macOS Keychain instead of a file.
+	// nil (unset) defaults to on; set `keychain: false` to opt out (e.g. on
+	// headless macOS). Ignored off macOS, where sessions are always files.
+	Keychain *bool `yaml:"keychain,omitempty"`
+
 	// Accounts holds additional named accounts, usable via --account <label>.
 	Accounts map[string]Account `yaml:"accounts,omitempty"`
 }
diff --git a/cmd/tg/logout.go b/cmd/tg/logout.go
index badf8a7..254c446 100644
--- a/cmd/tg/logout.go
+++ b/cmd/tg/logout.go
@@ -35,7 +35,7 @@ files are removed even if it fails (e.g. the session is already invalid).`,
 			}
 			st := a.active
 			dir := filepath.Dir(a.configPath)
-			sessionPath := st.acc.sessionPath(dir, st.label, kind.String())
+			store := a.sessionStore(st.label, st.acc, kind.String())
 			cachePath := st.acc.peerCachePath(dir, st.label, kind.String())
 
 			// Best-effort server-side logout.
@@ -57,11 +57,12 @@ files are removed even if it fails (e.g. the session is already invalid).`,
 				_, _ = fmt.Fprintln(os.Stderr, "Warning: remote logout failed, removing local session anyway:", err)
 			}
 
-			// Remove local files regardless.
-			for _, p := range []string{sessionPath, cachePath} {
-				if rmErr := os.Remove(p); rmErr != nil && !os.IsNotExist(rmErr) {
-					return errors.Wrapf(rmErr, "remove %s", p)
-				}
+			// Remove the local session and peer cache regardless.
+			if rmErr := store.Delete(cmd.Context()); rmErr != nil {
+				return errors.Wrap(rmErr, "remove session")
+			}
+			if rmErr := os.Remove(cachePath); rmErr != nil && !os.IsNotExist(rmErr) {
+				return errors.Wrapf(rmErr, "remove %s", cachePath)
 			}
 			return a.printer.Emit(okResult{OK: true})
 		},
diff --git a/cmd/tg/session_keychain_darwin.go b/cmd/tg/session_keychain_darwin.go
new file mode 100644
index 0000000..57a266f
--- /dev/null
+++ b/cmd/tg/session_keychain_darwin.go
@@ -0,0 +1,116 @@
+//go:build darwin
+
+package main
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"os/exec"
+
+	"github.com/go-faster/errors"
+
+	"github.com/gotd/td/session"
+)
+
+// keychainNotFound is the exit code `security` returns when an item is absent
+// (errSecItemNotFound).
+const keychainNotFound = 44
+
+// keychainSessionStore returns a Keychain-backed store. The bool is always true
+// on darwin; the signature mirrors the non-darwin stub so newSessionStore can
+// fall back to a file when Keychain is unavailable. legacy is the pre-Keychain
+// file session path, migrated into the Keychain (and removed) on first use.
+func keychainSessionStore(service, account, legacy string) (sessionStore, bool) {
+	return &keychainStore{service: service, account: account, legacy: legacy}, true
+}
+
+// keychainStore stores a gotd string session as a generic password in the macOS
+// login Keychain, driven through the `security` CLI (no cgo, keeps the binary
+// static).
+type keychainStore struct {
+	service string
+	account string
+	legacy  string // pre-Keychain file session, migrated then deleted.
+}
+
+func keychainAddArgs(service, account, secret string) []string {
+	// -U updates the item in place when it already exists.
+	return []string{"add-generic-password", "-U", "-s", service, "-a", account, "-w", secret}
+}
+
+func keychainFindArgs(service, account string) []string {
+	// -w prints only the password to stdout.
+	return []string{"find-generic-password", "-s", service, "-a", account, "-w"}
+}
+
+func keychainDeleteArgs(service, account string) []string {
+	return []string{"delete-generic-password", "-s", service, "-a", account}
+}
+
+// isNotFound reports whether err is `security` signalling a missing item.
+func isNotFound(err error) bool {
+	var ee *exec.ExitError
+	return errors.As(err, &ee) && ee.ExitCode() == keychainNotFound
+}
+
+func (s *keychainStore) LoadSession(ctx context.Context) ([]byte, error) {
+	out, err := exec.CommandContext(ctx, "security", keychainFindArgs(s.service, s.account)...).Output()
+	switch {
+	case err == nil:
+		// security appends a trailing newline to the password it prints.
+		return bytes.TrimSuffix(out, []byte("\n")), nil
+	case !isNotFound(err):
+		return nil, errors.Wrap(err, "keychain find")
+	}
+	// Nothing in the Keychain: migrate a pre-Keychain file session if present.
+	data, rerr := os.ReadFile(s.legacy)
+	if errors.Is(rerr, os.ErrNotExist) {
+		return nil, session.ErrNotFound
+	}
+	if rerr != nil {
+		return nil, errors.Wrap(rerr, "read legacy session")
+	}
+	if err := s.StoreSession(ctx, data); err != nil {
+		return nil, err
+	}
+	return data, nil
+}
+
+func (s *keychainStore) StoreSession(ctx context.Context, data []byte) error {
+	if err := exec.CommandContext(ctx, "security", keychainAddArgs(s.service, s.account, string(data))...).Run(); err != nil {
+		return errors.Wrap(err, "keychain add")
+	}
+	// Any write supersedes a pre-Keychain file session; remove it best-effort.
+	if err := os.Remove(s.legacy); err != nil && !os.IsNotExist(err) {
+		return errors.Wrap(err, "remove legacy session")
+	}
+	return nil
+}
+
+func (s *keychainStore) Exists(ctx context.Context) (bool, error) {
+	err := exec.CommandContext(ctx, "security", keychainFindArgs(s.service, s.account)...).Run()
+	if err == nil {
+		return true, nil
+	}
+	if !isNotFound(err) {
+		return false, errors.Wrap(err, "keychain find")
+	}
+	// Not yet migrated: a leftover file session still counts.
+	if _, serr := os.Stat(s.legacy); serr == nil {
+		return true, nil
+	}
+	return false, nil
+}
+
+func (s *keychainStore) Delete(ctx context.Context) error {
+	err := exec.CommandContext(ctx, "security", keychainDeleteArgs(s.service, s.account)...).Run()
+	if err != nil && !isNotFound(err) {
+		return errors.Wrap(err, "keychain delete")
+	}
+	// Also drop any pre-Keychain file session.
+	if rerr := os.Remove(s.legacy); rerr != nil && !os.IsNotExist(rerr) {
+		return errors.Wrap(rerr, "remove legacy session")
+	}
+	return nil
+}
diff --git a/cmd/tg/session_keychain_darwin_test.go b/cmd/tg/session_keychain_darwin_test.go
new file mode 100644
index 0000000..c9176b6
--- /dev/null
+++ b/cmd/tg/session_keychain_darwin_test.go
@@ -0,0 +1,107 @@
+//go:build darwin
+
+package main
+
+import (
+	"context"
+	"errors"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"slices"
+	"testing"
+
+	"github.com/gotd/td/session"
+)
+
+func TestKeychainArgs(t *testing.T) {
+	if got := keychainAddArgs("svc", "acc", "secret"); !slices.Equal(got,
+		[]string{"add-generic-password", "-U", "-s", "svc", "-a", "acc", "-w", "secret"}) {
+		t.Fatalf("add args: %v", got)
+	}
+	if got := keychainFindArgs("svc", "acc"); !slices.Equal(got,
+		[]string{"find-generic-password", "-s", "svc", "-a", "acc", "-w"}) {
+		t.Fatalf("find args: %v", got)
+	}
+	if got := keychainDeleteArgs("svc", "acc"); !slices.Equal(got,
+		[]string{"delete-generic-password", "-s", "svc", "-a", "acc"}) {
+		t.Fatalf("delete args: %v", got)
+	}
+}
+
+// exitErr fabricates an *exec.ExitError with the given code by actually running
+// a process that exits with it (portable, no unsafe).
+func exitErr(t *testing.T, code int) error {
+	t.Helper()
+	err := exec.Command("sh", "-c", "exit "+itoa(code)).Run()
+	var ee *exec.ExitError
+	if !errors.As(err, &ee) || ee.ExitCode() != code {
+		t.Fatalf("could not fabricate exit %d: %v", code, err)
+	}
+	return err
+}
+
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	var b []byte
+	for n > 0 {
+		b = append([]byte{byte('0' + n%10)}, b...)
+		n /= 10
+	}
+	return string(b)
+}
+
+// TestKeychainMigration exercises the real login Keychain (unique service,
+// cleaned up). It is darwin-only and CI runs on Linux, so it never runs there.
+func TestKeychainMigration(t *testing.T) {
+	ctx := context.Background()
+	service := "gotd.session-test-" + t.Name()
+	account := "migrate"
+	legacy := filepath.Join(t.TempDir(), "legacy.json")
+	store, _ := keychainSessionStore(service, account, legacy)
+	t.Cleanup(func() { _ = store.Delete(ctx) })
+
+	// A leftover file session should migrate on first load and be removed.
+	want := []byte(`{"v":1,"data":"abc=="}`)
+	if err := os.WriteFile(legacy, want, 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if ok, err := store.Exists(ctx); err != nil || !ok {
+		t.Fatalf("Exists() with legacy file = %v, %v; want true, nil", ok, err)
+	}
+	got, err := store.LoadSession(ctx)
+	if err != nil || string(got) != string(want) {
+		t.Fatalf("LoadSession() = %q, %v; want %q, nil", got, err, want)
+	}
+	if _, err := os.Stat(legacy); !os.IsNotExist(err) {
+		t.Fatalf("legacy file should be removed after migration, stat err = %v", err)
+	}
+	// Now served from the Keychain, no file.
+	got, err = store.LoadSession(ctx)
+	if err != nil || string(got) != string(want) {
+		t.Fatalf("LoadSession() after migration = %q, %v; want %q, nil", got, err, want)
+	}
+	if err := store.Delete(ctx); err != nil {
+		t.Fatalf("Delete: %v", err)
+	}
+	if _, err := store.LoadSession(ctx); !errors.Is(err, session.ErrNotFound) {
+		t.Fatalf("LoadSession() after delete = %v; want ErrNotFound", err)
+	}
+}
+
+func TestIsNotFound(t *testing.T) {
+	if !isNotFound(exitErr(t, keychainNotFound)) {
+		t.Fatal("exit 44 should be not-found")
+	}
+	if isNotFound(exitErr(t, 1)) {
+		t.Fatal("exit 1 should not be not-found")
+	}
+	if isNotFound(nil) {
+		t.Fatal("nil should not be not-found")
+	}
+	if isNotFound(errors.New("plain")) {
+		t.Fatal("non-exit error should not be not-found")
+	}
+}
diff --git a/cmd/tg/session_keychain_other.go b/cmd/tg/session_keychain_other.go
new file mode 100644
index 0000000..fe5309e
--- /dev/null
+++ b/cmd/tg/session_keychain_other.go
@@ -0,0 +1,9 @@
+//go:build !darwin
+
+package main
+
+// keychainSessionStore reports that no Keychain backend exists off macOS, so
+// newSessionStore falls back to file storage.
+func keychainSessionStore(_, _, _ string) (sessionStore, bool) {
+	return nil, false
+}
diff --git a/cmd/tg/session_store.go b/cmd/tg/session_store.go
new file mode 100644
index 0000000..283a922
--- /dev/null
+++ b/cmd/tg/session_store.go
@@ -0,0 +1,80 @@
+package main
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+
+	"github.com/gotd/td/session"
+)
+
+// sessionService is the Keychain service name under which sessions are stored.
+// It mirrors the on-disk session filename prefix (gotd.session.*).
+const sessionService = "gotd.session"
+
+// sessionStore persists a gotd string session. It is the single seam through
+// which the session is read (by the gotd client), checked for existence (by
+// `accounts`), and removed (by `logout`). Backends: a plain file, or the macOS
+// Keychain (default on darwin).
+type sessionStore interface {
+	session.Storage // LoadSession / StoreSession, consumed by telegram.Options.
+	Exists(ctx context.Context) (bool, error)
+	Delete(ctx context.Context) error
+}
+
+// fileSessionStore is the cross-platform backend: gotd's JSON FileStorage plus
+// existence/deletion over the same path.
+type fileSessionStore struct {
+	*session.FileStorage
+}
+
+func (s *fileSessionStore) Exists(context.Context) (bool, error) {
+	switch _, err := os.Stat(s.Path); {
+	case err == nil:
+		return true, nil
+	case os.IsNotExist(err):
+		return false, nil
+	default:
+		return false, err
+	}
+}
+
+func (s *fileSessionStore) Delete(context.Context) error {
+	if err := os.Remove(s.Path); err != nil && !os.IsNotExist(err) {
+		return err
+	}
+	return nil
+}
+
+// keychainAccount is the Keychain account name (and matches the file seed) for a
+// given account label + auth kind, so user/bot and distinct app credentials
+// never collide.
+func keychainAccount(label string, acc Account, kind string) string {
+	return label + "." + kind + "." + acc.seed(label, kind)
+}
+
+// newSessionStore selects the backend. On macOS with Keychain enabled (the
+// default) it returns the Keychain backend; otherwise it falls back to a file in
+// the config directory.
+func newSessionStore(dir, label string, acc Account, kind string, useKeychain bool) sessionStore {
+	path := acc.sessionPath(dir, label, kind)
+	if useKeychain {
+		// path is handed to the Keychain backend so it can migrate (and clean
+		// up) a pre-Keychain file session on first use.
+		if ks, ok := keychainSessionStore(sessionService, keychainAccount(label, acc, kind), path); ok {
+			return ks
+		}
+	}
+	return &fileSessionStore{FileStorage: &session.FileStorage{Path: path}}
+}
+
+// useKeychain reports whether the Keychain backend is enabled. It defaults to
+// on; set `keychain: false` in the config to opt out (e.g. headless macOS).
+func (a *app) useKeychain() bool {
+	return a.cfg.Keychain == nil || *a.cfg.Keychain
+}
+
+// sessionStore builds the session store for an account label + auth kind.
+func (a *app) sessionStore(label string, acc Account, kind string) sessionStore {
+	return newSessionStore(filepath.Dir(a.configPath), label, acc, kind, a.useKeychain())
+}
diff --git a/cmd/tg/session_store_test.go b/cmd/tg/session_store_test.go
new file mode 100644
index 0000000..bd7e827
--- /dev/null
+++ b/cmd/tg/session_store_test.go
@@ -0,0 +1,78 @@
+package main
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestUseKeychain(t *testing.T) {
+	on, off := true, false
+	cases := []struct {
+		name string
+		val  *bool
+		want bool
+	}{
+		{"unset defaults on", nil, true},
+		{"explicit on", &on, true},
+		{"explicit off", &off, false},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			a := &app{cfg: Config{Keychain: c.val}}
+			if got := a.useKeychain(); got != c.want {
+				t.Fatalf("useKeychain() = %v, want %v", got, c.want)
+			}
+		})
+	}
+}
+
+func TestKeychainAccount(t *testing.T) {
+	acc := Account{AppID: 123}
+	got := keychainAccount("work", acc, kindBot)
+	want := "work." + kindBot + "." + acc.seed("work", kindBot)
+	if got != want {
+		t.Fatalf("keychainAccount() = %q, want %q", got, want)
+	}
+	// user vs bot must not collide.
+	if keychainAccount("work", acc, kindUser) == got {
+		t.Fatal("user and bot accounts collide")
+	}
+}
+
+func TestFileSessionStore(t *testing.T) {
+	ctx := context.Background()
+	dir := t.TempDir()
+	acc := Account{AppID: 42}
+	// keychain off → file backend regardless of platform.
+	store := newSessionStore(dir, defaultAccount, acc, kindUser, false)
+
+	if ok, err := store.Exists(ctx); err != nil || ok {
+		t.Fatalf("Exists() = %v, %v; want false, nil", ok, err)
+	}
+	if err := store.StoreSession(ctx, []byte("blob")); err != nil {
+		t.Fatalf("StoreSession: %v", err)
+	}
+	if ok, err := store.Exists(ctx); err != nil || !ok {
+		t.Fatalf("Exists() after store = %v, %v; want true, nil", ok, err)
+	}
+	got, err := store.LoadSession(ctx)
+	if err != nil || string(got) != "blob" {
+		t.Fatalf("LoadSession() = %q, %v; want \"blob\", nil", got, err)
+	}
+	if err := store.Delete(ctx); err != nil {
+		t.Fatalf("Delete: %v", err)
+	}
+	if ok, _ := store.Exists(ctx); ok {
+		t.Fatal("Exists() after delete = true, want false")
+	}
+	// Delete is idempotent.
+	if err := store.Delete(ctx); err != nil {
+		t.Fatalf("second Delete: %v", err)
+	}
+	// File lands at the expected path.
+	if _, err := os.Stat(filepath.Join(dir, "gotd.session."+defaultAccount+"."+kindUser+"."+acc.seed(defaultAccount, kindUser)+".json")); err == nil {
+		t.Fatal("session file should be gone after delete")
+	}
+}