View source on GitHub →

ICN Invite System - Complete Implementation ✅

Date: December 12, 2025
Status: READY FOR TESTING

The cooperative invite system has been fully implemented across backend (Gateway API) and frontend (Pilot UI).

🎯 Overview

New users can now join cooperatives via invite codes without needing command-line access. Admins can create time-limited, single-use invite codes that grant specific roles.

✅ Backend Implementation (Gateway API)

InviteManager (icn/crates/icn-gateway/src/invite.rs)

  • Storage: In-memory HashMap (ready for persistent storage upgrade)
  • Code Generation: 12-character alphanumeric codes (excluding confusing chars)
  • Operations:
    • create_invite() - Generate new invite with role + expiration
    • get_invite() - Retrieve by code
    • list_invites() - List all for a cooperative
    • mark_used() - Redeem and mark as used
    • validate_invite() - Check validity (not used, not expired)
  • Tests: 4/4 passing ✅

API Endpoints (icn/crates/icn-gateway/src/api/invites.rs)

Endpoint Method Auth Description
/v1/invites POST coop:admin Create new invite
/v1/invites GET coop:read List invites (admin only)
/v1/invites/join POST None Join via invite code

Models (icn/crates/icn-gateway/src/models.rs)

  • CreateInviteRequest - coop_id, role, optional expiration
  • InviteResponse - code, coop info, invite URL
  • InviteListResponse / InviteInfo - List view
  • JoinRequest - invite_code + client DID
  • JoinResponse - DID, token, coop_id, role

Validation (icn/crates/icn-gateway/src/validation.rs)

  • validate_role() - Ensures valid role (member/admin/participant/facilitator)
  • Max 30 days expiration
  • Max 32 character role names

Metrics (icn/crates/icn-obs/src/metrics.rs)

  • invites_created(coop_id) - Counter per coop
  • invites_used(coop_id) - Counter per coop

Integration

  • Registered in server.rs with auth + rate limiting
  • AuthManager updated with public issue_token() method
  • All build tests passing ✅

✅ Frontend Implementation (Pilot UI)

Join Screen (web/pilot-ui/index.html)

  • New Join Screen with:
    • Gateway URL input
    • Invite code input (12-char, auto-uppercase)
    • Error/success messaging
    • "Join with Invite Code" button on login
    • "Back to Sign In" link

Invite Management UI (Members Tab)

  • Invites Card (admin-only):
    • Create Invite button
    • List of invites with status badges
    • Color-coded: Active (green), Expired (orange), Used (gray)
    • Shows code, role, creator, expiration

Create Invite Modal

  • Role selection dropdown
  • Expiration presets (1-30 days)
  • Generated code display with copy button
  • Shareable URL with copy button
  • Success confirmation

JavaScript (web/pilot-ui/app.js)

  • Join Flow (+150 lines):
    • Client-side keypair generation
    • POST to /v1/invites/join
    • Credential storage + display
    • Auto-login after success
  • Invite Management (+125 lines):
    • loadInvites() - Fetch and render
    • createInvite() - Modal + API call
    • Copy to clipboard helpers
    • Status badge rendering

Styling (web/pilot-ui/style.css)

  • Invite list cards (+80 lines)
  • Status badges with colors (+20 lines)
  • Join screen styling (+30 lines)
  • Modal enhancements (+39 lines)

🔐 Security Features

  1. Client-side key generation - Private keys never leave user's device
  2. Single-use codes - Automatically invalidated after redemption
  3. Time-limited - Configurable expiration (1-30 days)
  4. Role-based creation - Only admins can create invites
  5. High entropy codes - 12 alphanumeric characters
  6. Rate limiting - Applied to all invite endpoints
  7. Audit trail - Tracks creator, creation time, redemption

📊 User Flows

🆕 New Member Joining

1. Receive invite code from admin
2. Visit Pilot UI → "Join with Invite Code"
3. Enter gateway URL + invite code
4. System generates keypair (Ed25519)
5. Displays success + credentials to backup
6. Auto-login with new identity
7. Welcome to the cooperative!

👤 Admin Creating Invite

1. Login as admin
2. Navigate to Members tab
3. Click "Create Invite"
4. Select role + expiration
5. Click "Create Invite"
6. Copy code or share link
7. Send to prospective member

📁 Files Modified

Backend (Gateway)

  • icn/crates/icn-gateway/src/invite.rs (NEW) - 267 lines
  • icn/crates/icn-gateway/src/api/invites.rs (NEW) - 172 lines
  • icn/crates/icn-gateway/src/lib.rs - Added module
  • icn/crates/icn-gateway/src/api/mod.rs - Added module
  • icn/crates/icn-gateway/src/models.rs - Added invite models
  • icn/crates/icn-gateway/src/server.rs - Registered routes
  • icn/crates/icn-gateway/src/validation.rs - Added role validation
  • icn/crates/icn-gateway/src/auth.rs - Made issue_token public
  • icn/crates/icn-obs/src/metrics.rs - Added invite metrics

Frontend (Pilot UI)

  • web/pilot-ui/index.html - +79 lines (join screen + invite UI)
  • web/pilot-ui/app.js - +275 lines (join + invite logic)
  • web/pilot-ui/style.css - +169 lines (invite styling)

Total: 9 backend files, 3 frontend files

🧪 Testing Status

Backend Tests

  • ✅ test_create_and_get_invite - Passing
  • ✅ test_mark_used - Passing
  • ✅ test_validate_invite - Passing
  • ✅ test_list_invites - Passing

Integration Tests

  • ⏳ Manual end-to-end test pending
  • ⏳ Mobile responsiveness test pending
  • ⏳ Metrics verification pending

🚀 Deployment Steps

  1. Build Gateway:

    cd icn/
cargo build --release -p icn-gateway

  2. Start Gateway:

    ./target/release/icnd

  3. Deploy Pilot UI:

    cd web/pilot-ui
# Serve via nginx/caddy or:
python3 -m http.server 3000

  4. Create Test Invite:

    # Login as admin via CLI
icnctl auth login --gateway http://localhost:8080 --coop test-coop

# Or create via UI (Members tab → Create Invite)

  5. Test Join Flow:

    • Open browser to http://localhost:3000
    • Click "Join with Invite Code"
    • Enter test invite code
    • Verify credentials generated
    • Verify auto-login works

📈 Monitoring

Prometheus metrics exposed at /metrics:

  • icn_gateway_invites_created_total{coop_id="..."}
  • icn_gateway_invites_used_total{coop_id="..."}

Track invite creation and redemption rates per cooperative.

🎯 Success Criteria

  • Backend API endpoints functional
  • Frontend UI components complete
  • Client-side key generation works
  • Invite codes validate correctly
  • Single-use enforcement
  • Expiration enforcement
  • Admin-only creation
  • Metrics collection
  • End-to-end test passing
  • Mobile responsive verified
  • Production deployment

🔜 Future Enhancements

  1. QR Code Generation - Display QR code for mobile invite sharing
  2. Email Integration - Send invite via email
  3. Batch Invites - Create multiple invites at once
  4. Custom Roles - Define custom roles beyond presets
  5. Persistent Storage - Move from in-memory to database
  6. Usage Analytics - Track invite conversion rates
  7. Revocation - Admin can revoke unused invites

📝 Documentation

See also:

  • docs/GATEWAY_API.md - API endpoint documentation
  • web/pilot-ui/README.md - Pilot UI setup guide
  • CLAUDE.md - Development guidelines

Status: ✅ COMPLETE - Ready for testing and deployment

Next Action: Deploy to test environment and run end-to-end validation

← Back to Docs