How to Manage User Roles in FckSignups: Architecture, Limitations, and Implementation Guide

FckSignups does not implement user role management; all privileged operations are gated by a single GitHub personal access token stored in the Cloudflare Worker environment.

FckSignups is a static, client-side web application that catalogs open-source tools. According to the BraveOPotato/FckSignups source code, the project intentionally avoids persistent user authentication and database infrastructure. This architectural choice simplifies deployment but means role-based access control must be added manually if your deployment requires differentiated permissions.

Why FckSignups Has No Built-In Role Management

The application stores all data in a single JSON file (tools.json) fetched by the frontend at runtime. Write operations—adding tools, reporting broken entries, or submitting suggestions—flow through a Cloudflare Worker that interacts with the GitHub API to modify the repository directly.

Because there is no user database, no session layer, and no authentication system, the codebase cannot distinguish between visitors, contributors, or administrators through identity-based checks.

The Current Privilege Model

The only access control mechanism in place relies on a secret token comparison. In cloudflare-worker/urlHandlers/handleSubmitTool.ts, the worker validates requests like this:

// cloudflare-worker/urlHandlers/handleSubmitTool.ts
export async function handleSubmitTool(request: Request) {
  const auth = request.headers.get('Authorization');
  if (auth !== `Bearer ${ADMIN_TOKEN}`) {
    return new Response('Unauthorized', { status: 401 });
  }
  // …validate payload, update tools.json via GitHub API…
}

Anyone possessing the ADMIN_TOKEN environment variable can perform administrative actions. The public UI offers no login flow or role indicator—every visitor has identical frontend capabilities.

Endpoints and Their Protection Levels

Endpoint	Handler File	Access Control
Submit new tool	cloudflare-worker/urlHandlers/handleSubmitTool.ts	Bearer token required
Report broken tool	cloudflare-worker/urlHandlers/handleReportTool.ts	Bearer token required
Suggest tool	cloudflare-worker/urlHandlers/handleSuggestTool.ts	No authentication

The handleSuggestTool.ts endpoint accepts unauthenticated requests, allowing any visitor to propose additions. Token-gated endpoints in handleSubmitTool.ts and handleReportTool.ts restrict execution to the secret holder.

Implementing User Role Management in FckSignups

To add proper role management to FckSignups, you must introduce three components not present in the current codebase.

1. Authentication Layer

Before roles can exist, you must identify users. Integrate GitHub OAuth or another identity provider to obtain verified user identities:

// Example: Cloudflare Worker OAuth verification helper
async function verifyGitHubOAuth(request: Request): Promise<GithubUser> {
  const code = new URL(request.url).searchParams.get('code');
  const tokenResp = await fetch('https://github.com/login/oauth/access_token', {
    method: 'POST',
    headers: { Accept: 'application/json' },
    body: new URLSearchParams({ client_id, client_secret, code }),
  });
  const { access_token } = await tokenResp.json();
  
  const userResp = await fetch('https://api.github.com/user', {
    headers: { Authorization: `Bearer ${access_token}` },
  });
  return userResp.json();
}

Store the resulting user session in Cloudflare KV or encrypted cookies.

2. Role Storage System

Create a mapping between user identities and permission levels. Cloudflare KV provides a suitable key-value store:

// cloudflare-worker/middleware/requireRole.ts
export async function requireRole(request: Request, role: string) {
  const user = await verifyGitHubOAuth(request);
  const userRoles = await KV.get(`roles:${user.id}`);
  if (!userRoles?.includes(role)) {
    return new Response('Forbidden', { status: 403 });
  }
  return null; // continue processing
}

Populate KV entries manually or through an admin interface:

# Example: Grant admin role to GitHub user 12345

wrangler kv:key put "roles:12345" '["admin","moderator"]' --namespace-id=xxxx

3. Middleware Integration

Apply role checks to existing handlers. Modify handleSubmitTool.ts to require specific roles:

// cloudflare-worker/urlHandlers/handleSubmitTool.ts
import { requireRole } from '../middleware/requireRole';

export async function handleSubmitTool(request: Request) {
  const forbidden = await requireRole(request, 'admin');
  if (forbidden) return forbidden;
  
  // Proceed with tool submission…
}

Frontend Considerations for Role Management

The current frontend in src/hooks/useTools.ts sends requests without authentication context:

// src/hooks/useTools.ts – client-side helper
export async function submitTool(tool: NewTool) {
  const resp = await fetch(
    'https://<worker-subdomain>.workers.dev/api/submit-tool',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(tool),
    },
  );
  if (!resp.ok) throw new Error('Failed to submit tool');
  return resp.json();
}

With role management enabled, extend this helper to include session credentials:

export async function submitTool(tool: NewTool, sessionToken: string) {
  const resp = await fetch('/api/submit-tool', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${sessionToken}`,
    },
    body: JSON.stringify(tool),
  });
  if (resp.status === 401) throw new Error('Please log in');
  if (resp.status === 403) throw new Error('Admin access required');
  if (!resp.ok) throw new Error('Submission failed');
  return resp.json();
}

Key Files for Role Management Modifications

File Path	Purpose in Role Implementation
tools.json	Data store; no changes needed for roles
src/hooks/useTools.ts	Add authentication headers to API calls
cloudflare-worker/worker.ts	Route authentication-related endpoints
cloudflare-worker/urlHandlers/handleSubmitTool.ts	Add role-gated access control
cloudflare-worker/urlHandlers/handleReportTool.ts	Add role-gated access control
cloudflare-worker/urlHandlers/handleSuggestTool.ts	Optional: convert to role-based permissions

Summary

• FckSignups currently manages no user roles; privileged operations require a single shared secret token
• The Cloudflare Worker in handleSubmitTool.ts and handleReportTool.ts gates writes through Bearer token comparison, not identity verification
• Adding role management requires implementing authentication, a role store in KV, and middleware checks
• The frontend helper useTools.ts must be extended to propagate session credentials
• Unauthenticated endpoints like handleSuggestTool.ts can optionally be brought under role control

Frequently Asked Questions

Does FckSignups support multiple admin accounts?

No. The codebase recognizes only one credential: the ADMIN_TOKEN environment variable. Anyone with this value can perform administrative actions. To support multiple accounts with differentiated permissions, you must build the three-layer system described above.

Can I restrict who can submit tool suggestions?

Currently, handleSuggestTool.ts accepts all requests without authentication. To restrict submissions, add the same role-check middleware used for handleSubmitTool.ts, requiring at minimum a contributor role before processing suggestions.

What storage should I use for role assignments?

Cloudflare KV is the natural choice since FckSignups already deploys to the Cloudflare ecosystem. For more complex requirements—hierarchical roles, audit logging, or group memberships—consider D1 (Cloudflare's SQL database) or an external service like Auth0 with role claims.

Is OAuth required, or can I use API keys?

API keys work for programmatic access but do not identify individual users. If you need per-user accountability and granular permissions, GitHub OAuth (or similar) is necessary. For simple service-to-service authentication, expanding the existing secret-token pattern with multiple named tokens may suffice.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}