Let existing accounts move followers to bots

[dahlia]

Publish aliases as the actor's alsoKnownAs so Mastodon can verify the target before moving followers to a bot. Standalone, static, and dynamic bots publish aliases this way and keep their existing follow policy.

Accept actor URIs to avoid network lookups during dispatch, and copy the array so Fedify's lazy alias resolution cannot modify the configuration. docs/concepts/bot.md explains how to find the old actor URI and deploy the bot before starting the move.

Fixes #48.

Summary by CodeRabbit

• New Features
  • Bots can now advertise alternate account identities through aliases, accessible from bot and session profiles.
  • Account aliases support moving followers from an existing account to a bot. The bot must list the old account’s actor URI; only followers transfer.
• Documentation
  • Added guidance for configuring aliases, migrating followers, and handling aliases on existing and multi-bot instances.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

🧰 Additional context used

📚 Code guidelines (1)

AGENTS.md — auto-discovered

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: b5b070e6-172d-4794-9a59-9412d8d146be

📥 Commits

Reviewing files that changed from the base of the PR and between 8efc656 and bcc0031.

📒 Files selected for processing (11)

• CHANGES.md
• changes.d/botkit/account-aliases.md
• docs/concepts/bot.md
• docs/concepts/instance.md
• docs/concepts/session.md
• packages/botkit/src/account-aliases.test.ts
• packages/botkit/src/bot-impl.ts
• packages/botkit/src/bot.ts
• packages/botkit/src/instance-impl.ts
• packages/botkit/src/instance.ts
• packages/botkit/src/text.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 1 remain after this review.

---

📝 Walkthrough

Walkthrough

BotKit adds actor URI aliases to bot configuration and public bot state. It publishes configured aliases as alsoKnownAs and adds documentation for moving followers from an existing account to a BotKit bot.

Changes

Account aliases

Layer / File(s)	Summary
Alias configuration and public API packages/botkit/src/bot.ts, packages/botkit/src/instance.ts, docs/concepts/bot.md, docs/concepts/instance.md	CreateBotOptions and BotProfile accept alias URL lists. Bot interfaces expose aliases, and the API documentation describes the option.
Alias propagation and actor output packages/botkit/src/bot-impl.ts, packages/botkit/src/instance-impl.ts, packages/botkit/src/account-aliases.test.ts, packages/botkit/src/text.test.ts	Bot implementations default aliases to an empty list, expose them through bot state, and pass them into actor data. Tests cover configured, omitted, empty, and updated aliases.
Migration guidance and release notes docs/concepts/bot.md, docs/concepts/session.md, CHANGES.md, changes.d/botkit/account-aliases.md	Documentation describes configuring and verifying an alias before migrating followers. It also covers follower-policy handling and alias updates for static and dynamic bots. Changelog entries describe the alias option.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Merge Risk: ⚪ Minimal · up to bcc00

The alias and follower-migration changes appear ready to merge after normal checks.

Security Architecture Review

Security architecture risk: 🔵 Low · up to bcc00

The new identity assertions come from application-controlled configuration, and incoming follow requests retain their existing acceptance controls. No new security bypass was established. Migration still depends on external servers, correct alias configuration, and deployment readiness.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The direct exposure is each configured bot's public identity assertion and downstream migration decisions. Reusing mutable alias configuration across dynamic profiles can propagate configuration changes across those profiles; actual dispatcher ownership and backing data were not inspected.

Security Findings and Attack Paths

• inferred — No new alias-to-follow-acceptance bypass was established in the inspected path. Alias publication does not alter the Follow handler's target checks, callback state handling, or followerPolicy enforcement.

Trust Boundaries and Controls

• observed — BotKit publishes application-supplied alias claims rather than independently proving historical account ownership. The documented migration requires verification at the old server and initiation while signed in to the old account; those external controls were not inspected.

Resilience and Maintainability Implications

• observed — The wrapper exposes the implementation's alias array directly. TypeScript readonly restricts typed callers but does not prevent runtime mutation. This preserves configuration-owner authority rather than establishing a remote attack path.

Hardening Proposals

• proposed — If immutable identity-configuration snapshots are desired, copy both input arrays and URL values or provide a controlled update API. This would protect against trusted-caller configuration drift beyond the existing serialization-level copy.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: enabling existing accounts to move followers to bots through configured aliases.
Linked Issues check	✅ Passed	Issue #48 requirements are implemented. CreateBotOptions, BotProfile, Bot, and ReadonlyBot expose aliases with URL actor-URI types and empty defaults. BotImpl stores the option, static a…
Out of Scope Changes check	✅ Passed	The changed source, tests, documentation, fixture update, and changelog entries all support Issue #48. The tests verify the new alias behavior. The documentation explains configuration and migration u…
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 6 files. (5 skipped: 5 …

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

Files with missing lines	Coverage Δ
packages/botkit/src/bot-impl.ts	89.70% <100.00%> (+0.03%)	⬆️
packages/botkit/src/bot.ts	100.00% <ø> (ø)
packages/botkit/src/instance-impl.ts	78.78% <100.00%> (+0.02%)	⬆️
packages/botkit/src/instance.ts	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.