Channel Policy System¶

freeq channels can have access policies that control who can join and what roles they receive. Policies are credential-based: users prove something about their identity (e.g., GitHub membership, Bluesky follows) to gain access.

Quick Start¶

1. Set Channel Rules¶

As a channel operator (+o), set the rules users must accept:

/msg ChanServ POLICY #mychannel SET Be respectful. Follow our Code of Conduct.

Or use the Channel Settings panel in the web UI (click the gear icon).

This creates a basic "accept rules" policy. Users see the rules and must accept to join.

2. Add Credential Verifiers (Optional)¶

Require users to prove something beyond accepting rules:

# Require GitHub repo access
/msg ChanServ POLICY #mychannel REQUIRE github_repo issuer=did:web:irc.freeq.at:verify url=/verify/github/start?repo=owner/repo label=GitHub_Repo

# Require GitHub org membership
/msg ChanServ POLICY #mychannel REQUIRE github_membership issuer=did:web:irc.freeq.at:verify url=/verify/github/start?org=myorg label=GitHub_Org

# Require Bluesky follow
/msg ChanServ POLICY #mychannel REQUIRE bluesky_follower issuer=did:web:irc.freeq.at:verify url=/verify/bluesky/start?target=handle.bsky.social label=Bluesky_Follow

3. Configure Role Escalation (Optional)¶

Auto-grant channel modes based on credentials:

# GitHub repo contributors get op (+o)
/msg ChanServ POLICY #mychannel SET-ROLE op {"type":"PRESENT","credential_type":"github_repo","issuer":"did:web:irc.freeq.at:verify"}

# Moderators get halfop (+h)
/msg ChanServ POLICY #mychannel SET-ROLE moderator {"type":"PRESENT","credential_type":"channel_moderator","issuer":"did:web:irc.freeq.at:verify"}

4. Remove Policy¶

/msg ChanServ POLICY #mychannel CLEAR

How It Works¶

1. User tries to join a channel with a policy
2. Server checks if the user has valid credentials
3. If not, the web/iOS client shows a gate modal with:
4. The channel rules
5. Links to verify credentials (GitHub OAuth, etc.)
6. User completes verification → receives a signed credential
7. User can now join the channel
8. If role rules are configured, the user is auto-granted modes (op/voice/etc.)

Credential Types¶

Web UI¶

The easiest way to manage policies is through the Channel Settings panel:

1. Click the ⚙️ gear icon in the channel header
2. Go to the Rules tab to set/update channel rules
3. Go to the Verifiers tab to add credential requirements
4. Go to the Roles tab to configure auto-granted modes

The UI provides templates for common setups and shows the current policy in human-readable form.

Architecture¶

• Policies are stored in a separate SQLite database (irc-policy.db)
• Credentials are signed by the server's verifier DID (did:web:irc.freeq.at:verify)
• Credentials are reusable within their TTL (default 5 minutes)
• DID operators and channel founders always bypass policy checks
• Policies are versioned — updating rules increments the version

API¶

GET  /api/v1/policy/{channel}    — Fetch current policy
POST /api/v1/policy/{channel}/accept — Accept channel rules (returns credential)

Notes¶

• Only channel operators (+o) can set/modify policies
• DID-authenticated users (did:plc:...) who are channel founders or DID-ops bypass all policy checks
• Guest users can satisfy ACCEPT requirements but not credential-based ones (they need a DID)
• Policies compose: REQUIRE adds to existing requirements with AND logic