icub3d/decentcom

Fork

You've already forked decentcom

Code Issues 21 Pull requests Projects Releases Packages 1 Wiki Activity Actions

Feature: Bot Account Type #53

New issue

Closed

opened 2026-04-26 16:46:10 +00:00 by icub3d · 0 comments

icub3d commented

2026-04-26 16:46:10 +00:00

Owner

Copy link

Migrated from GitHub issue icub3d/decentcom#75
Original Author: @icub3d
Original Date: 2026-04-17T21:41:45Z

Feature: Bot Account Type

Overview

Introduce a first-class bot account type so servers can distinguish automated participants from humans, apply scoped permissions, and let first-party and third-party bots integrate cleanly using the same identity model as humans.

Background

Per #68, bots are the right tool for moderation, onboarding, and utility tasks that don't belong on the auth/permissions critical path. Rather than introduce a parallel auth system (long-lived tokens), bots use the same Ed25519 challenge-response flow as humans — the only differences are an is_bot flag bound to the signed challenge payload and a manual admin approval gate before the bot can act on the server.

Requirements

Bots use the same Ed25519 keypair + challenge-response auth flow as human users.
The signed challenge payload includes an is_bot: true claim so the server can distinguish bot authentications from human ones.
Bot accounts require explicit admin approval before they can join or send messages. Unapproved bot pubkeys that authenticate land in a pending queue.
Bots appear in member lists and message author displays with a distinct "Bot" badge.
Bots are subject to all existing permission checks — no bypasses.
Admins can approve, revoke, or re-approve bots from the admin UI.
Bot accounts can be exempted from PoW / velocity gating at admin discretion (coordination with #68).

Design

Auth Flow

Bot generates an Ed25519 keypair (same as humans).
Bot initiates auth: POST /api/v1/auth/challenge with { pubkey, is_bot: true }.
Server returns a nonce. The nonce commits to the is_bot claim (e.g. signs over nonce || is_bot) so the claim cannot be stripped or swapped.
Bot signs and submits.
If the pubkey is not yet in bot_approvals, the server records it as pending and either rejects the session or issues a read-only session (TBD in design). Admin sees the pending bot in the admin UI.
Admin approves the bot. On the next auth round, the bot gets a normal session with whatever roles the admin assigned.

Data Model Changes

users table: add is_bot INTEGER NOT NULL DEFAULT 0 (set the first time a pubkey authenticates with the is_bot claim).
New bot_approvals table: (pubkey TEXT PRIMARY KEY, approved_by TEXT REFERENCES users(id), approved_at TEXT, revoked_at TEXT, note TEXT).

API / Interface Changes

POST /api/v1/auth/challenge accepts an optional is_bot flag in the request body; the flag is bound into the signed payload.
GET /api/v1/admin/bots/pending — list bots awaiting approval.
POST /api/v1/admin/bots/{pubkey}/approve — approve a bot.
POST /api/v1/admin/bots/{pubkey}/revoke — revoke a previously approved bot.
GET /api/v1/members response includes is_bot and approval state.

Component Changes

client/src/components/members/MemberList.tsx — render bot badge (with optional "pending" state for unapproved bots if they're visible).
Admin panel — bot approval UI (pending list + approve/revoke actions).

Task List

Phase 1: Server

Migration adding is_bot column and bot_approvals table.
Challenge endpoint accepts and binds the is_bot claim.
Auth path: reject or restrict sessions for unapproved bots; queue them for approval.
Admin endpoints: list pending, approve, revoke.
Extend members API with is_bot and approval state.

Phase 2: Client UI

Bot badge in member list and message author display.
Admin panel: pending bots list, approve/revoke actions.

Test List

Unit test: the is_bot claim is bound to the signed payload and auth fails if it is tampered with.
Integration: unapproved bot authenticates, admin sees it in the pending queue, bot cannot send messages.
Integration: admin approves, bot can now send messages with assigned roles.
Integration: admin revokes, bot's next auth goes back to pending / restricted.
Integration: approved bot is still subject to normal permission checks.

Open Questions

Should unapproved bots get a read-only session, or be fully rejected until approved? (Recommendation: read-only so admins can see what the bot was going to do — leaning on server logs rather than messages — before approving.)
Should approval be per-server or per-instance? (Recommendation: per-server, aligned with decentcom's one-instance-one-server model.)
Should the is_bot claim be self-asserted (current design) or issued by someone? (Recommendation: self-asserted. The approval gate, not the claim, is what grants trust.)

Dependencies

Related: #68 (verification / velocity gating — bots should be exemptable at admin discretion).
Blocks: #76 (Bot SDK), #77 (Reference Bots).

**Migrated from GitHub issue icub3d/decentcom#75** **Original Author:** @icub3d **Original Date:** 2026-04-17T21:41:45Z --- # Feature: Bot Account Type ## Overview Introduce a first-class bot account type so servers can distinguish automated participants from humans, apply scoped permissions, and let first-party and third-party bots integrate cleanly using the same identity model as humans. ## Background Per #68, bots are the right tool for moderation, onboarding, and utility tasks that don't belong on the auth/permissions critical path. Rather than introduce a parallel auth system (long-lived tokens), bots use the same Ed25519 challenge-response flow as humans — the only differences are an `is_bot` flag bound to the signed challenge payload and a manual admin approval gate before the bot can act on the server. ## Requirements - [ ] Bots use the same Ed25519 keypair + challenge-response auth flow as human users. - [ ] The signed challenge payload includes an `is_bot: true` claim so the server can distinguish bot authentications from human ones. - [ ] Bot accounts require explicit admin approval before they can join or send messages. Unapproved bot pubkeys that authenticate land in a pending queue. - [ ] Bots appear in member lists and message author displays with a distinct "Bot" badge. - [ ] Bots are subject to all existing permission checks — no bypasses. - [ ] Admins can approve, revoke, or re-approve bots from the admin UI. - [ ] Bot accounts can be exempted from PoW / velocity gating at admin discretion (coordination with #68). ## Design ### Auth Flow 1. Bot generates an Ed25519 keypair (same as humans). 2. Bot initiates auth: `POST /api/v1/auth/challenge` with `{ pubkey, is_bot: true }`. 3. Server returns a nonce. The nonce commits to the `is_bot` claim (e.g. signs over `nonce || is_bot`) so the claim cannot be stripped or swapped. 4. Bot signs and submits. 5. If the pubkey is not yet in `bot_approvals`, the server records it as pending and either rejects the session or issues a read-only session (TBD in design). Admin sees the pending bot in the admin UI. 6. Admin approves the bot. On the next auth round, the bot gets a normal session with whatever roles the admin assigned. ### Data Model Changes - `users` table: add `is_bot INTEGER NOT NULL DEFAULT 0` (set the first time a pubkey authenticates with the `is_bot` claim). - New `bot_approvals` table: `(pubkey TEXT PRIMARY KEY, approved_by TEXT REFERENCES users(id), approved_at TEXT, revoked_at TEXT, note TEXT)`. ### API / Interface Changes - `POST /api/v1/auth/challenge` accepts an optional `is_bot` flag in the request body; the flag is bound into the signed payload. - `GET /api/v1/admin/bots/pending` — list bots awaiting approval. - `POST /api/v1/admin/bots/{pubkey}/approve` — approve a bot. - `POST /api/v1/admin/bots/{pubkey}/revoke` — revoke a previously approved bot. - `GET /api/v1/members` response includes `is_bot` and approval state. ### Component Changes - `client/src/components/members/MemberList.tsx` — render bot badge (with optional "pending" state for unapproved bots if they're visible). - Admin panel — bot approval UI (pending list + approve/revoke actions). ## Task List ### Phase 1: Server - [x] Migration adding `is_bot` column and `bot_approvals` table. - [x] Challenge endpoint accepts and binds the `is_bot` claim. - [x] Auth path: reject or restrict sessions for unapproved bots; queue them for approval. - [x] Admin endpoints: list pending, approve, revoke. - [x] Extend members API with `is_bot` and approval state. ### Phase 2: Client UI - [x] Bot badge in member list and message author display. - [x] Admin panel: pending bots list, approve/revoke actions. ## Test List - [x] Unit test: the `is_bot` claim is bound to the signed payload and auth fails if it is tampered with. - [x] Integration: unapproved bot authenticates, admin sees it in the pending queue, bot cannot send messages. - [x] Integration: admin approves, bot can now send messages with assigned roles. - [x] Integration: admin revokes, bot's next auth goes back to pending / restricted. - [x] Integration: approved bot is still subject to normal permission checks. ## Open Questions - Should unapproved bots get a read-only session, or be fully rejected until approved? (Recommendation: read-only so admins can see what the bot was going to do — leaning on server logs rather than messages — before approving.) - Should approval be per-server or per-instance? (Recommendation: per-server, aligned with decentcom's one-instance-one-server model.) - Should the `is_bot` claim be self-asserted (current design) or issued by someone? (Recommendation: self-asserted. The approval gate, not the claim, is what grants trust.) ## Dependencies - Related: #68 (verification / velocity gating — bots should be exemptable at admin discretion). - Blocks: #76 (Bot SDK), #77 (Reference Bots).

icub3d

2026-04-26 16:46:10 +00:00

closed this issue
added the
area:ux

area:api

type:feature

area:core

status:complete
labels

No Branch/Tag specified

main

feature/115-chatbot-2

feature/16-dms

gh-pages

No results found.

Labels

Clear labels

area:api

Backend endpoints, REST, DB, Gateway

area:core

Shared Rust logic, crypto, Tauri shell

area:docs

Documentation, OpenAPI specs, architecture

area:infra

Deployment, Docker, build tools

area:ux

Frontend UI, React components, Tailwind

dependencies

Pull requests that update a dependency file

documentation

Improvements or additions to documentation

duplicate

This issue or pull request already exists

good first issue

Good for newcomers

help wanted

Extra attention is needed

invalid

This doesn't seem right

question

Further information is requested

rust

Pull requests that update rust code

status:complete

Feature fully implemented

status:partial

Partially implemented (server done, client pending)

Architectural changes, major design decisions

type:feature

New features

type:infra

Infrastructure and CI/CD changes

type:refactor

Code improvements without behavioral changes

type:research

Spikes, investigating new tech

type:ux

User experience improvements

wontfix

This will not be worked on

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

icub3d/decentcom#53

Reference in a new issue

Repository

icub3d/decentcom

Title

Body

No description provided.

Delete branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?

Rows
Columns