@thierrynakoa/fire-flow 12.2.2 → 13.0.1

package/skills-library/plugin-development/plugin-doc-auto-generation.md

@@ -0,0 +1,172 @@
+---
+name: plugin-doc-auto-generation
+category: plugin-development
+version: 1.0.0
+contributed: 2026-03-06
+contributor: dominion-flow
+last_updated: 2026-03-06
+contributors:
+  - dominion-flow
+tags: [bash, plugin, documentation, automation, cli, devops]
+difficulty: easy
+usage_count: 0
+success_rate: 100
+---
+
+# Plugin Documentation Auto-Generation
+
+## Problem
+
+Claude Code plugin documentation drifts from reality over time. When you add new commands, agents, or skills, the index files and README stats become stale. Manual counting is error-prone and tedious.
+
+Common symptoms:
+- README says "39 commands" but there are actually 42 on disk
+- SKILLS-INDEX.md lists 237 skills but 470+ exist in the filesystem
+- Agent reference table shows 5 agents but 13 `.md` files exist in `agents/`
+- Version numbers are inconsistent across plugin.json, README, and COMMAND-REFERENCE
+
+## Solution Pattern
+
+Create shell scripts that scan the filesystem (the source of truth) and either generate index files or audit documentation for drift. Use `plugin.json` as the single source of truth for the version number, and propagate it to all other files.
+
+Three scripts handle the complete lifecycle:
+
+1. **`generate-skills-index.sh`** — Walks the skills directory tree, counts `.md` files per category, and generates a complete `SKILLS-INDEX.md` with category headers and skill listings.
+
+2. **`generate-command-reference.sh`** — Counts commands, agents, and skills on disk. Outputs an agent reference table. Runs a sync check against `plugin.json` and `README.md` to flag drift.
+
+3. **`sync-version.sh`** — Reads the version from `plugin.json` (or accepts a new version as argument), then `sed`-replaces all version references across documentation files.
+
+## Code Example
+
+```bash
+# Before (manual, error-prone)
+# Developer manually edits SKILLS-INDEX.md
+# Developer manually counts: "ls commands/ | wc -l"
+# Developer manually updates README: "Includes 39 slash commands..."
+# Result: Numbers drift within days
+
+# After (automated, always accurate)
+# Generate skills index from filesystem
+bash scripts/generate-skills-index.sh
+# Output: SKILLS-INDEX.md regenerated with accurate count
+
+# Audit command/agent counts and check for drift
+bash scripts/generate-command-reference.sh
+# Output: Stats + sync check showing OK or DRIFT
+
+# Bump version across all files
+bash scripts/sync-version.sh 10.1.0
+# Output: plugin.json + all docs updated to v10.1.0
+```
+
+### generate-skills-index.sh (core pattern)
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+SKILLS_DIR="$PLUGIN_ROOT/skills-library"
+OUTPUT="$SKILLS_DIR/SKILLS-INDEX.md"
+
+# Count total skills (excluding index/meta files)
+TOTAL=$(find "$SKILLS_DIR" -name "*.md" \
+    -not -name "SKILLS-INDEX.md" \
+    -not -name "README.md" \
+    | wc -l | tr -d ' ')
+
+# Get version from plugin.json (source of truth)
+VERSION=$(grep '"version"' "$PLUGIN_ROOT/plugin.json" \
+    | head -1 \
+    | sed 's/.*"version"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/')
+
+# Generate header
+cat > "$OUTPUT" << HEADER
+# Skills Library Index
+> Auto-generated — $(date +%Y-%m-%d) — v${VERSION}
+> **Total skills: ${TOTAL}**
+---
+HEADER
+
+# Walk each category directory
+find "$SKILLS_DIR" -mindepth 1 -maxdepth 1 -type d | sort | while read -r dir; do
+    DIRNAME=$(basename "$dir")
+    [[ "$DIRNAME" == .* ]] && continue
+    COUNT=$(find "$dir" -name "*.md" -not -name "README.md" | wc -l | tr -d ' ')
+    [ "$COUNT" -eq 0 ] && continue
+
+    TITLE=$(echo "$DIRNAME" | sed 's/-/ /g' | sed 's/\b\(.\)/\u\1/g')
+    echo "### $TITLE ($COUNT skills)" >> "$OUTPUT"
+    echo "" >> "$OUTPUT"
+
+    find "$dir" -name "*.md" -not -name "README.md" | sort | while read -r file; do
+        NAME=$(basename "$file" .md)
+        DESC=$(grep -m 1 "^# " "$file" 2>/dev/null | sed 's/^# //' || echo "$NAME")
+        echo "- \`$NAME\` — $DESC" >> "$OUTPUT"
+    done
+    echo "" >> "$OUTPUT"
+done
+
+echo "Generated: $TOTAL skills indexed"
+```
+
+### sync-version.sh (core pattern)
+
+```bash
+#!/bin/bash
+set -euo pipefail
+
+PLUGIN_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+NEW_VERSION="${1:-$(grep '"version"' "$PLUGIN_ROOT/plugin.json" \
+    | head -1 | sed 's/.*"\([^"]*\)".*/\1/')}"
+
+# Update plugin.json if version was passed as argument
+[ $# -ge 1 ] && sed -i "s/\"version\": \"[^\"]*\"/\"version\": \"$NEW_VERSION\"/" \
+    "$PLUGIN_ROOT/plugin.json"
+
+# Propagate to all documentation files
+for file in README.md COMMAND-REFERENCE.md DOMINION-FLOW-OVERVIEW.md; do
+    [ -f "$PLUGIN_ROOT/$file" ] || continue
+    sed -i "s/v[0-9]\+\.[0-9]\+\(\.[0-9]\+\)\?/v$NEW_VERSION/g" "$PLUGIN_ROOT/$file"
+done
+```
+
+## Implementation Steps
+
+1. Create a `scripts/` directory in your plugin root
+2. Add `generate-skills-index.sh` — scans skills and generates index
+3. Add `generate-command-reference.sh` — audits counts and flags drift
+4. Add `sync-version.sh` — propagates version from plugin.json
+5. Run after any structural change (new commands, agents, or skills)
+6. Optionally add to a pre-commit hook or CI pipeline
+
+## When to Use
+
+- After adding new commands, agents, or skills to a plugin
+- Before tagging a release (ensures docs match reality)
+- When preparing a README for public visibility (accuracy matters)
+- As part of a CI pipeline to catch documentation drift
+
+## When NOT to Use
+
+- For plugins with fewer than 10 files (manual is fine)
+- When documentation intentionally differs from disk (e.g., hiding internal/experimental commands)
+- In non-plugin projects where docs aren't filesystem-derived
+
+## Common Mistakes
+
+- Forgetting to exclude meta files (SKILLS-INDEX.md, README.md) from the count
+- Using `wc -l` without `tr -d ' '` — macOS `wc` adds leading spaces
+- Not using `set -euo pipefail` — silent failures cause stale output
+- Hardcoding version numbers instead of reading from plugin.json
+
+## Related Skills
+
+- [claude-md-archival](../_general/methodology/claude-md-archival.md) — CLAUDE.md management patterns
+- [git-worktrees-parallel](../_general/methodology/git-worktrees-parallel.md) — Parallel development workflows
+
+## References
+
+- Contributed from: dominion-flow competitive analysis session (2026-03-06)
+- Pattern discovered when audit revealed 39-vs-42 command count drift

package/skills-library/security/GITHUB_REPO_SECURITY_AUDIT.md

@@ -0,0 +1,115 @@
+---
+name: github-repo-security-audit
+category: security
+version: 1.0.0
+contributed: 2026-02-24
+contributor: dominion-flow
+last_updated: 2026-02-24
+tags: [security, github, audit, skills, plugins, supply-chain]
+difficulty: medium
+---
+
+# GitHub Repo Security Audit
+
+## Problem
+
+Installing skills, plugins, or tools from GitHub repos introduces supply chain risk. Repos may contain prompt injection, credential harvesting, exfiltration URLs, tool poisoning, or hidden malicious content. Without systematic auditing, compromised skills enter the agent's trusted execution environment.
+
+## Solution Pattern
+
+6-layer security audit performed BEFORE installation. The audit runs in an isolated temp directory, never in the target skill path. Only after passing all layers does the repo get copied to the install location.
+
+## Pre-Download Checklist
+
+Before even cloning, evaluate:
+
+| Check | How | Red Flag |
+|-------|-----|----------|
+| Repo age | `gh repo view --json createdAt` | Created < 7 days ago |
+| Stars/forks | `gh repo view --json stargazersCount,forkCount` | Stars < 10, looks artificial |
+| Recent commits | `gh api repos/{owner}/{repo}/commits?per_page=5` | All commits in last 24h (rush job) |
+| Open issues | `gh repo view --json issues` | Many unresolved security issues |
+| License | `gh repo view --json licenseInfo` | No license or unusual license |
+| Owner reputation | `gh api users/{owner}` | New account, no other repos |
+
+## 6-Layer Post-Clone Audit
+
+### Layer 1: Credential Scan
+```bash
+bash ~/.claude/hooks/credential-filter.sh --dir /tmp/{repo}-review/
+```
+Catches real API keys, passwords, connection strings in the repo.
+
+### Layer 2: Prompt Injection Scan
+Search all `.md`, `.txt`, `.json`, `.yaml` files for:
+- `ignore previous instructions`
+- `you are now` / `act as` (role manipulation)
+- `system prompt` extraction attempts
+- `<|im_start|>` or other special tokens
+- Hidden Unicode characters (zero-width spaces, directional overrides)
+
+```bash
+grep -rnE 'ignore.*(previous|above|prior).*(instruction|prompt|rule)' /tmp/{repo}-review/
+grep -rnE '(you are now|act as|new role|forget|override|bypass)' /tmp/{repo}-review/
+```
+
+### Layer 3: Exfiltration Detection
+Search for outbound data transmission:
+- `fetch(` / `XMLHttpRequest` / `WebSocket` / `navigator.sendBeacon`
+- `curl` / `wget` with external URLs
+- `document.cookie` / `localStorage` / `sessionStorage` reads
+- Image/script `src` pointing to non-CDN domains
+- Any URL that isn't a well-known CDN (jsdelivr, cdnjs, unpkg, googleapis)
+
+### Layer 4: Tool Poisoning
+Search for destructive or privileged operations:
+- `rm -rf` / `sudo` / `chmod 777` / `eval` / `exec`
+- File writes to `~/.claude/`, `~/.ssh/`, `~/.env`, `~/.aws/`
+- Attempts to read credential files
+- `child_process` / `os.system` / `subprocess` calls
+
+### Layer 5: Hidden Content
+- Run NFKC normalization on all text files
+- Search for zero-width Unicode characters (`\u200B`, `\u200C`, `\u200D`, `\uFEFF`)
+- Check for base64 payloads longer than 100 chars (exclude images)
+- Look for `atob`, `btoa`, `String.fromCharCode`, `unescape`
+
+### Layer 6: CDN Dependency Pinning
+For all external script/CSS references in HTML files:
+- Check if version is pinned to exact version (e.g., `@3.2.2`) — GOOD
+- Major-only pinning (e.g., `@11`) — ADVISORY
+- No version at all — WARNING
+- Non-standard CDN domain — RED FLAG
+
+## Verdict Matrix
+
+| Result | Action |
+|--------|--------|
+| All 6 layers CLEAN | Install to `~/.claude/skills/{name}/` |
+| 1-2 ADVISORY items | Install with warnings documented |
+| Any SUSPICIOUS finding | Show to user, require explicit approval |
+| Any BLOCKED finding | Do NOT install. Show findings. |
+
+## Post-Install Verification
+
+After installing a clean repo:
+1. Remove `.git/` directory (no need for git history in skills)
+2. Run credential filter one more time on installed location
+3. Log the audit result: `~/.claude/audit-log/{repo}-{date}.md`
+
+## When to Use
+
+- ALWAYS when installing skills/plugins from GitHub
+- When adding any external repo to the agent's trusted environment
+- When updating an existing skill from a remote source
+- When someone shares a "cool Claude Code skill" link
+
+## When NOT to Use
+
+- For repos you're building yourself (use credential filter + pre-commit hooks instead)
+- For official Anthropic repos (still advisable but lower risk)
+
+## Related Skills
+
+- [CREDENTIAL-SECURITY-WORKFLOW.md](../awesome-workflows/CREDENTIAL-SECURITY-WORKFLOW.md) — Credential leak prevention
+- [deployment-security/](../deployment-security/) — Production security patterns

package/skills-library/security/admin-deletion-safety.md

@@ -0,0 +1,396 @@
+---
+name: admin-deletion-safety
+category: security
+version: 1.0.0
+contributed: 2026-01-24
+contributor: my-other-project
+last_updated: 2026-01-24
+tags: [admin, user-management, audit-logging, soft-delete, security-alerts, rbac]
+difficulty: medium
+usage_count: 0
+success_rate: 100
+---
+
+# Admin Deletion Safety - Industry Standard Implementation
+
+## Problem
+
+Deleting admin users without proper safeguards can lead to:
+- **System lockout**: Last admin deleted → no one can manage the system
+- **Security blind spots**: No audit trail of who deleted whom and why
+- **Lack of accountability**: No notification to other admins about deletions
+- **Accidental self-sabotage**: Admin deletes their own account
+- **Data loss**: Hard delete makes recovery impossible
+
+Common symptoms:
+- 403 errors when trying to delete admin users (blanket block)
+- No audit log of admin actions
+- Permanent data loss on deletion
+- Security incidents go unnoticed
+
+## Solution Pattern
+
+Implement a **multi-layered safety system** for admin user deletion:
+
+1. **Self-Deletion Protection** - Prevent admins from deleting their own account
+2. **Minimum Admin Requirement** - Require at least N admins (typically 2)
+3. **Audit Logging** - Complete trail of all deletion attempts (success/blocked/failed)
+4. **Email Notifications** - Security alerts to remaining admins
+5. **Soft Delete** - Mark as deleted instead of hard delete (allows recovery)
+
+This creates defense-in-depth: if one check is bypassed, others catch it.
+
+## Code Example
+
+### Before (Problematic)
+
+```javascript
+// Simple hard delete with basic admin check
+export const deleteUser = async (req, res) => {
+  const user = await getUserById(req.params.id);
+  if (user.role === 'admin') {
+    return res.status(403).json({ error: 'Cannot delete admin users' });
+  }
+
+  // Hard delete - no recovery
+  await sql`DELETE FROM profiles WHERE id = ${req.params.id}`;
+  res.status(200).json({ message: 'User deleted' });
+};
+```
+
+**Issues:**
+- Blanket admin deletion block (even with 10 admins)
+- No self-deletion check (can delete own account)
+- No audit trail
+- No notifications
+- Permanent data loss
+- No IP/timestamp tracking
+
+### After (Solution)
+
+```javascript
+import { logAdminAction, getIpAddress, getUserAgent } from '../utils/auditLogger.js';
+import { sendEmail } from '../config/email.js';
+
+export const deleteUser = async (req, res, next) => {
+  const user = await getUserById(req.params.id);
+  if (!user) return next(new ApiError('User not found', 404));
+
+  const ipAddress = getIpAddress(req);
+  const userAgent = getUserAgent(req);
+
+  // SAFETY CHECK 1: Prevent self-deletion
+  if (req.user.id === req.params.id) {
+    await logAdminAction({
+      adminId: req.user.id,
+      adminEmail: req.user.email,
+      action: 'user_delete_attempt',
+      targetUserId: user.id,
+      targetUserEmail: user.email,
+      targetUserRole: user.role,
+      status: 'blocked',
+      reason: 'Self-deletion not allowed',
+      ipAddress,
+      userAgent
+    });
+
+    return next(new ApiError('Cannot delete your own account. Ask another admin.', 403));
+  }
+
+  // SAFETY CHECK 2: Minimum admin requirement
+  if (user.role === 'admin') {
+    const adminCount = await sql`SELECT COUNT(*) as count FROM profiles WHERE role = 'admin'`;
+    const totalAdmins = parseInt(adminCount[0].count);
+
+    if (totalAdmins <= 2) {
+      await logAdminAction({
+        adminId: req.user.id,
+        adminEmail: req.user.email,
+        action: 'user_delete_attempt',
+        targetUserId: user.id,
+        targetUserEmail: user.email,
+        targetUserRole: user.role,
+        status: 'blocked',
+        reason: `Minimum admin requirement not met (${totalAdmins} admins, minimum 2 required)`,
+        metadata: { admin_count: totalAdmins, minimum_required: 2 },
+        ipAddress,
+        userAgent
+      });
+
+      return next(new ApiError(`Cannot delete admin. System requires at least 2 admins. Currently ${totalAdmins} exist.`, 403));
+    }
+  }
+
+  try {
+    // SOFT DELETE: Mark as deleted instead of removing
+    await sql.begin(async sql => {
+      await sql`
+        UPDATE profiles
+        SET deleted_at = NOW(),
+            deleted_by = ${req.user.id}
+        WHERE id = ${req.params.id}
+      `;
+    });
+
+    // AUDIT LOG: Successful deletion
+    await logAdminAction({
+      adminId: req.user.id,
+      adminEmail: req.user.email,
+      action: 'user_deleted',
+      targetUserId: user.id,
+      targetUserEmail: user.email,
+      targetUserRole: user.role,
+      status: 'success',
+      ipAddress,
+      userAgent
+    });
+
+    // EMAIL NOTIFICATION: Alert remaining admins
+    if (user.role === 'admin') {
+      const remainingAdmins = await sql`SELECT email, first_name FROM profiles WHERE role = 'admin' AND id != ${req.params.id}`;
+
+      for (const admin of remainingAdmins) {
+        await sendEmail({
+          to: admin.email,
+          subject: '🔒 Security Alert: Admin Account Deleted',
+          html: `
+            <h2>Security Notification</h2>
+            <p>An administrator account has been deleted.</p>
+            <p><strong>Deleted:</strong> ${user.email}</p>
+            <p><strong>By:</strong> ${req.user.email}</p>
+            <p><strong>Time:</strong> ${new Date().toISOString()}</p>
+            <p><strong>IP:</strong> ${ipAddress}</p>
+          `
+        });
+      }
+    }
+
+    res.status(200).json({ status: 'success', message: 'User deleted successfully' });
+  } catch (error) {
+    // AUDIT LOG: Failed deletion
+    await logAdminAction({
+      adminId: req.user.id,
+      adminEmail: req.user.email,
+      action: 'user_delete_attempt',
+      targetUserId: user.id,
+      targetUserEmail: user.email,
+      targetUserRole: user.role,
+      status: 'failed',
+      reason: error.message,
+      metadata: { error_code: error.code },
+      ipAddress,
+      userAgent
+    });
+
+    return next(new ApiError(error.message, 400));
+  }
+};
+
+// RESTORATION: Allow undeleting users
+export const restoreUser = async (req, res, next) => {
+  const user = await sql`SELECT id, email, deleted_at FROM profiles WHERE id = ${req.params.id}`;
+
+  if (!user[0] || !user[0].deleted_at) {
+    return next(new ApiError('User not found or not deleted', 404));
+  }
+
+  await sql`UPDATE profiles SET deleted_at = NULL, deleted_by = NULL WHERE id = ${req.params.id}`;
+
+  await logAdminAction({
+    adminId: req.user.id,
+    adminEmail: req.user.email,
+    action: 'user_restored',
+    targetUserId: user[0].id,
+    targetUserEmail: user[0].email,
+    status: 'success',
+    ipAddress: getIpAddress(req),
+    userAgent: getUserAgent(req)
+  });
+
+  res.status(200).json({ status: 'success', message: 'User restored successfully' });
+};
+```
+
+## Implementation Steps
+
+### 1. Create Audit Log Table
+
+```sql
+-- Migration: admin_audit_log.sql
+CREATE TABLE IF NOT EXISTS admin_audit_log (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  admin_id UUID REFERENCES profiles(id) ON DELETE SET NULL,
+  admin_email VARCHAR(255) NOT NULL,
+  action VARCHAR(100) NOT NULL,
+  target_user_id UUID,
+  target_user_email VARCHAR(255),
+  target_user_role VARCHAR(50),
+  status VARCHAR(50) NOT NULL, -- 'success', 'blocked', 'failed'
+  reason TEXT,
+  metadata JSONB,
+  ip_address VARCHAR(45),
+  user_agent TEXT,
+  created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+
+  INDEX idx_admin_audit_admin_id (admin_id),
+  INDEX idx_admin_audit_action (action),
+  INDEX idx_admin_audit_created_at (created_at DESC)
+);
+```
+
+### 2. Add Soft Delete Columns
+
+```sql
+-- Migration: add_soft_delete.sql
+ALTER TABLE profiles
+ADD COLUMN IF NOT EXISTS deleted_at TIMESTAMPTZ DEFAULT NULL,
+ADD COLUMN IF NOT EXISTS deleted_by UUID REFERENCES profiles(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_profiles_deleted_at ON profiles(deleted_at);
+```
+
+### 3. Create Audit Logger Utility
+
+```javascript
+// server/utils/auditLogger.js
+import sql from '../config/db.js';
+
+export const logAdminAction = async ({
+  adminId, adminEmail, action, targetUserId,
+  targetUserEmail, targetUserRole, status, reason,
+  metadata, ipAddress, userAgent
+}) => {
+  try {
+    await sql`
+      INSERT INTO admin_audit_log (
+        admin_id, admin_email, action, target_user_id,
+        target_user_email, target_user_role, status, reason,
+        metadata, ip_address, user_agent
+      ) VALUES (
+        ${adminId}, ${adminEmail}, ${action}, ${targetUserId},
+        ${targetUserEmail}, ${targetUserRole}, ${status}, ${reason},
+        ${metadata ? JSON.stringify(metadata) : null}, ${ipAddress}, ${userAgent}
+      )
+    `;
+  } catch (error) {
+    console.error('[AUDIT LOG ERROR]', error);
+  }
+};
+
+export const getIpAddress = (req) => {
+  return req.ip || req.headers['x-forwarded-for'] || req.connection.remoteAddress || null;
+};
+
+export const getUserAgent = (req) => {
+  return req.headers['user-agent'] || null;
+};
+```
+
+### 4. Update User Model for Soft Delete Filtering
+
+```javascript
+// server/models/User.js
+export const getUsers = async (filters = {}, options = {}) => {
+  let hasWhere = false;
+  const parts = ['SELECT * FROM profiles'];
+  const values = [];
+  let idx = 1;
+
+  // Soft delete filtering (default: exclude deleted)
+  if (filters.excludeDeleted) {
+    parts.push('WHERE deleted_at IS NULL');
+    hasWhere = true;
+  } else if (filters.deletedOnly) {
+    parts.push('WHERE deleted_at IS NOT NULL');
+    hasWhere = true;
+  }
+
+  // ... rest of filters
+};
+```
+
+### 5. Add Restore Route
+
+```javascript
+// server/routes/adminRoutes.js
+router.post('/users/:id/restore', protect, authorize('admin'), adminController.restoreUser);
+```
+
+## When to Use
+
+- **Any system with admin users** - Critical infrastructure requiring admin access
+- **Multi-tenant SaaS platforms** - Multiple admins managing the system
+- **Compliance requirements** - HIPAA, SOC2, ISO27001 requiring audit trails
+- **Financial/payment systems** - High-stakes environments needing accountability
+- **Enterprise applications** - Professional software with security standards
+- **When users complain** - "I can't delete this admin" → proper implementation needed
+
+## When NOT to Use
+
+- **Single-user systems** - No multi-admin requirement (but audit logging still valuable)
+- **Prototype/demo apps** - Overkill for non-production learning projects
+- **Public-facing user accounts** - Different deletion rules apply (GDPR right to deletion)
+- **When immediate hard delete required** - Rare cases needing instant permanent removal
+- **Simple CRUD apps** - Basic user management without admin hierarchyuse soft delete sparingly
+
+## Configuration Options
+
+```javascript
+// config/security.js
+export const ADMIN_DELETION_CONFIG = {
+  minimumAdmins: 2,              // Minimum admins required
+  softDeleteEnabled: true,        // Use soft delete (vs hard delete)
+  emailNotifications: true,       // Send email alerts
+  auditLogging: true,            // Log all actions
+  allowSelfDeletion: false,      // Prevent self-deletion
+  recoveryGracePeriod: 30,       // Days before permanent deletion
+  notifyAllAdmins: true,         // Alert all admins (vs just superadmins)
+};
+```
+
+## Common Mistakes
+
+1. **Hardcoded minimum admin count** - Should be configurable
+2. **Forgetting IP/user agent logging** - Critical for security forensics
+3. **No email notification** - Admins unaware of security events
+4. **Hard delete on first call** - No recovery option
+5. **Audit log in same transaction** - If transaction rolls back, no audit entry
+6. **Not excluding soft-deleted users in queries** - Appear in user lists
+7. **Missing restoration endpoint** - Soft delete useless without restore
+8. **Blanket admin block** - "Cannot delete admins" even with 10 admins
+
+## Testing Checklist
+
+- [ ] Try deleting your own admin account → Should block with clear message
+- [ ] With 2 admins, try deleting one → Should block
+- [ ] With 3+ admins, delete one → Should succeed
+- [ ] Check admin_audit_log table → Entry created
+- [ ] Check email inbox → Security alert received
+- [ ] Verify user marked as deleted (deleted_at set)
+- [ ] Call restore endpoint → User restored
+- [ ] Query users list → Deleted user excluded by default
+- [ ] Try deleting already-deleted user → Appropriate error
+- [ ] Attempt deletion of non-existent user → 404 error
+
+## Related Skills
+
+- [rbac-permission-system](../security/rbac-permission-system.md) - Role-based access control
+- [audit-logging-patterns](../security/audit-logging-patterns.md) - Comprehensive audit trails
+- [soft-delete-implementation](../database-solutions/soft-delete-implementation.md) - Soft delete strategies
+- [email-notification-system](../integrations/email-notification-system.md) - Email alert patterns
+- [admin-impersonation](../security/admin-impersonation.md) - Admin user impersonation
+
+## References
+
+- OWASP: [Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html)
+- NIST: [Digital Identity Guidelines](https://pages.nist.gov/800-63-3/)
+- SOC 2: Access Control Requirements
+- Contributed from: MERN Community LMS (2026-01-24)
+
+## Success Metrics
+
+- **Zero lockouts** - No incidents of system becoming inaccessible
+- **100% audit coverage** - All admin actions logged
+- **Recovery success rate** - Percentage of soft-deleted users successfully restored
+- **Mean time to recovery** - How fast deleted users can be restored
+- **Security alert response time** - How quickly admins respond to deletion alerts