Epic: Core Data Flow — Hash Cracking Pipeline, Result Tracking & Agent Integration

[unclesp1d3r]

Overview

This epic tracks the foundational end-to-end data flow of the HashHive platform: the path by which agents acquire work, execute attacks, submit crack results, and propagate those results back through the system. Without this pipeline, the platform cannot track progress, distribute results, or provide any meaningful operational feedback.

This is a CipherSwarm parity epic derived from gap analysis. All P0 issues here are blockers for core platform functionality.

---

Scope

This epic covers:

1. Agent Prerequisites — Benchmarking and cracker binary management that gate agents from being fully operational
2. Attack Prerequisites — Reusable attack templates required before campaigns can be configured efficiently
3. Hash Result Pipeline — The core crack submission, status reporting, and zap (deduplication) system
4. Hash Data Operations — Extensions of the result pipeline: ETA calculation, attack complexity, SuperHashlists, export/import

---

Child Issues

P0 — Core Parity Blockers

Issue	Title	Labels	Story Points
#93	[P0] Agent Benchmarking & Performance Profiling System	backend, agent-management	SP:8
#94	[P0] Cracker Binary Management & Agent Auto-Update	backend, agent-management	SP:5
#95	[P0] Attack Templates — Reusable Attack Definitions	campaign-management	SP:5
#98	[P0] Hash Item Storage, Crack Result Tracking & Zap System	backend, hash-management	SP:13

P1 — Important CipherSwarm Features

Issue	Title	Labels	Story Points
#99	[P1] Attack Complexity Calculation & State Machine	backend, campaign-management	SP:5
#100	[P1] Campaign ETA Calculator Service	backend, campaign-management	SP:3
#101	[P1] SuperHashlists — Cross-Hashlist Deduplication	hash-management	SP:8
#102	[P1] Hash List Export, Pre-Cracked Import & Global Search	hash-management	SP:5

---

Dependency Graph

#93 Agent Benchmarking
  └──▶ #96 Keyspace Distribution (→ Epic #118 Intelligent Scheduling)
         └──▶ #97 Task Preemption (→ Epic #118)

#94 Cracker Binary Management
  └── (standalone)

#95 Attack Templates
  ├──▶ #112 Crackable Uploads (→ Epic #120)
  └──▶ #115 Attack Playbooks (→ Epic #120)

#98 Hash Item Storage / Crack Tracking / Zap System
  ├──▶ #101 SuperHashlists
  └──▶ #102 Hash Export / Pre-Cracked Import / Global Search

---

Key Technical Context

#93 — Agent Benchmarking

Agents must benchmark before accepting tasks. The benchmark data (per-agent, per-hash-type throughput) feeds directly into the keyspace distribution scheduler in Epic #118. Without benchmark data, proportional chunk sizing is impossible.

• CipherSwarm ref: HashcatBenchmark model (6.4 KB), POST /api/v1/client/agents/{id}/submit_benchmark
• Blocks: [P0] Keyspace-Based Task Distribution with Dynamic Chunking #96 (Keyspace Distribution)

#94 — Cracker Binary Management

The server tracks hashcat binary versions and serves presigned download URLs to agents. Ensures all agents run compatible cracker versions without manual per-rig maintenance.

• CipherSwarm ref: CrackerBinary model, CrackersController (91 lines), MinIO binary storage

#95 — Attack Templates

Reusable attack configurations (mode + parameters + resource references) that pre-fill campaign attacks. Required before crackable uploads (#112) and attack playbooks (#115) can be built.

• CipherSwarm ref: Template model, template → attack instantiation

#98 — Hash Item Storage, Crack Result Tracking & Zap System ⭐ Core

This is the single most critical issue in this epic. Agents submit cracks (submit_crack), report status (submit_status), and fetch already-cracked hashes to skip (get_zaps). Without this, the platform cannot record any results.

• CipherSwarm ref: HashItem model, HashcatGuess model, CrackSubmissionService (6.2 KB), StatusSubmissionService (6.2 KB), HashcatStatus model (12.4 KB)
• Blocks: [P1] SuperHashlists — Cross-Hashlist Deduplication #101, [P1] Hash List Export, Pre-Cracked Import & Global Search #102

#99 — Attack Complexity & State Machine

Each attack tracks its own state machine (pending → running → completed/exhausted/failed/paused) and has its total keyspace/duration estimated. Complexity feeds progress bars and ETA display.

• CipherSwarm ref: Attack model (15.3 KB), CalculateMaskComplexityJob

#100 — Campaign ETA Calculator

Calculates estimated campaign completion from current throughput, remaining keyspace, and fleet size. Recalculates in real-time as WebSocket status updates arrive.

• CipherSwarm ref: CampaignETACalculator (5.9 KB)
• Related: [P0] Agent Benchmarking & Performance Profiling System #93 (benchmark data), [P1] Attack Complexity Calculation & State Machine #99 (attack complexity)

#101 — SuperHashlists

When multiple hash lists share the same hash type, SuperHashlists merge them for deduplication — crack once, propagate to all source lists.

• CipherSwarm ref: CipherSwarm issue #634 (priority:high)
• Blocked by: [P0] Hash Item Storage, Crack Result Tracking & Zap System #98

#102 — Hash List Export, Pre-Cracked Import & Global Search

Export cracked pairs in CSV/potfile format, import pre-cracked hashes from external tools, and search for a specific hash across all lists in a project.

• CipherSwarm ref: Issues #625, #635, #624
• Blocked by: [P0] Hash Item Storage, Crack Result Tracking & Zap System #98

---

Acceptance Criteria

• Agents can submit benchmark results and the data is persisted per hash type ([P0] Agent Benchmarking & Performance Profiling System #93)
• Server tracks hashcat binary versions; agents can check for and download updates ([P0] Cracker Binary Management & Agent Auto-Update #94)
• Attack templates can be created, listed, and applied when building campaigns ([P0] Attack Templates — Reusable Attack Definitions #95)
• Individual hash items are stored and tracked within hash lists ([P0] Hash Item Storage, Crack Result Tracking & Zap System #98)
• Agents submit crack results and status updates via the agent API ([P0] Hash Item Storage, Crack Result Tracking & Zap System #98)
• Agents fetch zaps (hashes cracked by others) and skip solved hashes ([P0] Hash Item Storage, Crack Result Tracking & Zap System #98)
• Dashboard shows crack results, progress, and campaign completion ([P0] Hash Item Storage, Crack Result Tracking & Zap System #98, [P1] Campaign ETA Calculator Service #100)
• Attack-level state machine tracks lifecycle independently from campaign state ([P1] Attack Complexity Calculation & State Machine #99)
• Complexity calculation provides keyspace/duration estimates for each attack ([P1] Attack Complexity Calculation & State Machine #99)
• Campaign ETA is calculated and updated in real-time ([P1] Campaign ETA Calculator Service #100)
• SuperHashlists deduplicate hashes across multiple lists and propagate cracks ([P1] SuperHashlists — Cross-Hashlist Deduplication #101)
• Hash lists can be exported and pre-cracked hashes imported ([P1] Hash List Export, Pre-Cracked Import & Global Search #102)
• Global hash search works across all lists in a project ([P1] Hash List Export, Pre-Cracked Import & Global Search #102)

---

Related Epics

• Epic: Intelligent Scheduling — Keyspace Distribution, Task Preemption & Attack Complexity #118 — Intelligent Scheduling: Keyspace-based task distribution and preemption (depends on [P0] Agent Benchmarking & Performance Profiling System #93 benchmark data)
• Epic: Operational Polish — Audit Logging, Agent Config, Data Integrity & Hash Management #119 — Operational Polish: Audit logging, soft deletes, webhooks, health monitoring, file integrity
• Epic: Advanced Features — Control API, SuperHashlists, Extended Attacks & Webhooks #120 — Advanced Features: Advanced attack types, agent advanced config, historical analytics
• Visualization & Stretch #121 — Visualization & Stretch: P2 stretch goals — crackable uploads, inline editing, playbooks, TUI, Agent API v2

---

Source

All issues in this epic were identified via CipherSwarm/Ouroboros gap analysis and tagged with the gap-analysis label.

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

The codebase is a Bun + Hono + Drizzle ORM monorepo. The schema already has hashItems, agents, attacks, campaigns, and tasks tables. The core crack submission pipeline (updateTaskProgress in tasks.ts) already writes to hashItems with onConflictDoUpdate. The agent API has heartbeat, task assignment, and task reporting endpoints. Missing are: agent benchmarking, cracker binary management, attack templates, attack-level state machine, ETA calculation, SuperHashlists, pre-cracked import, and the zap endpoint.

Approach

Implement the eight child issues in dependency order: P0 blockers first (benchmarking, cracker binaries, attack templates, zap endpoint), then P1 features (attack state machine, ETA service, SuperHashlists, import/global search). Each change follows the established pattern: schema additions in shared/src/db/schema.ts → Drizzle migration → service logic → Hono route → OpenAPI spec update → frontend hook/page.

---

Implementation Plan

Phase 1 — Schema Extensions (packages/shared/src/db/schema.ts)

Add all new tables in one migration pass to avoid multiple migration files:

1.1 — agent_benchmarks table (for #93)

• Columns: id, agentId (FK → agents), hashTypeId (FK → hash_types), hashcatMode (integer), speed (bigint, hashes/sec), deviceInfo (jsonb), createdAt
• Unique index on (agentId, hashcatMode) — one benchmark row per agent per mode, use onConflictDoUpdate on upsert

1.2 — cracker_binaries table (for #94)

• Columns: id, version (varchar), platform (varchar — e.g. linux-amd64), fileRef (jsonb — MinIO key + bucket), isActive (boolean default true), createdAt, updatedAt
• Unique index on (version, platform)

1.3 — attack_templates table (for #95)

• Columns: id, projectId (FK → projects), name, description, mode (integer), hashTypeId (nullable FK), wordlistId (nullable FK), rulelistId (nullable FK), masklistId (nullable FK), advancedConfiguration (jsonb), createdBy (FK → users), createdAt, updatedAt

1.4 — super_hash_lists and super_hash_list_members tables (for #101)

• super_hash_lists: id, projectId, name, hashTypeId, createdAt, updatedAt
• super_hash_list_members: id, superHashListId (FK), hashListId (FK), unique on (superHashListId, hashListId)

1.5 — Schema changes to existing tables

• agents: add crackerVersion (varchar, nullable), benchmarkStatus (varchar default 'pending' — values: pending | running | completed)
• attacks: add complexity (jsonb, nullable — stores { keyspace, estimatedDuration, calculatedAt }), eta (timestamp, nullable)

After all table additions, run bun --filter @hashhive/backend db:generate and db:migrate.

---

Phase 2 — #93: Agent Benchmarking

2.1 — Agent API endpoint in packages/backend/src/routes/agent/index.ts

Add POST /benchmarks route (protected by requireAgentToken):

• Zod schema: { results: Array<{ hashcatMode: number; speed: number; deviceInfo?: object }> }
• Upsert each result into agent_benchmarks using onConflictDoUpdate on (agentId, hashcatMode)
• After upsert, update agents.benchmarkStatus = 'completed' and agents.updatedAt
• Return { acknowledged: true, count: number }

2.2 — Dashboard API endpoint in packages/backend/src/routes/dashboard/agents.ts

Add GET /agents/:id/benchmarks route:

• Query agent_benchmarks joined with hash_types for the given agentId
• Return array of { hashcatMode, hashTypeName, speed, deviceInfo, createdAt }

2.3 — OpenAPI spec (packages/openapi/agent-api.yaml)

• Add POST /benchmarks path with BenchmarkSubmission schema (array of mode + speed pairs)

2.4 — Frontend (packages/frontend/src/)

• Add useAgentBenchmarks(agentId) hook in hooks/ using TanStack Query
• Add a benchmarks table section to the agent detail page (pages/agent-detail.tsx)

---

Phase 3 — #94: Cracker Binary Management

3.1 — Dashboard API in a new file packages/backend/src/routes/dashboard/crackers.ts

• GET /crackers — list all cracker binaries (admin only)
• POST /crackers — upload metadata + generate MinIO presigned PUT URL for binary upload (admin only); use existing @aws-sdk/client-s3 + @aws-sdk/s3-request-presigner pattern from packages/backend/src/config/storage.ts
• DELETE /crackers/:id — soft-delete (set isActive = false)

3.2 — Agent API endpoint in packages/backend/src/routes/agent/index.ts

Add GET /crackers/latest route:

• Accept platform query param (e.g. linux-amd64)
• Query cracker_binaries for the latest active binary matching the platform
• Generate a presigned GET URL for the binary using the existing MinIO client
• Return { version, downloadUrl, expiresAt }
• After agent downloads, it should report its version via heartbeat (capabilities.crackerVersion)

3.3 — Mount route in packages/backend/src/index.ts

• app.route('/api/v1/dashboard/crackers', crackerRoutes)

3.4 — OpenAPI spec — add GET /crackers/latest path

---

Phase 4 — #95: Attack Templates

4.1 — Dashboard API in a new file packages/backend/src/routes/dashboard/templates.ts

• GET /templates — list project-scoped templates (filter by projectId from JWT)
• POST /templates — create template (admin/operator); Zod schema mirrors createAttackSchema in campaigns.ts plus name and description
• GET /templates/:id — get single template
• PATCH /templates/:id — update template
• DELETE /templates/:id — delete template

4.2 — Template instantiation in packages/backend/src/services/campaigns.ts

Add createAttackFromTemplate(campaignId, templateId):

• Fetch template, verify project scope
• Call existing createAttack() with template fields pre-filled

4.3 — Campaign attack creation endpoint in packages/backend/src/routes/dashboard/campaigns.ts

• Extend POST /:id/attacks to accept optional templateId; when present, delegate to createAttackFromTemplate

4.4 — Mount route in packages/backend/src/index.ts

• app.route('/api/v1/dashboard/templates', templateRoutes)

4.5 — Frontend

• Add useTemplates() and useCreateTemplate() hooks
• Add template selector component in the campaign attack creation form (components/features/)

---

Phase 5 — #98: Zap Endpoint (the missing piece of the crack pipeline)

The crack submission itself already works via POST /tasks/:id/report. The missing piece is the zap endpoint — agents fetching already-cracked hashes to skip.

5.1 — Agent API endpoint in packages/backend/src/routes/agent/index.ts

Add GET /tasks/:id/zaps route:

• Accept optional since query param (ISO timestamp)
• Join hashItems → campaigns → hashLists to find hashes cracked for the same hash list as the task's campaign, since the given timestamp
• Return { hashes: string[], count: number } — just the hash values (agents skip these)
• Default since to task's assignedAt if not provided

5.2 — OpenAPI spec — add GET /tasks/{taskId}/zaps path with since query param

---

Phase 6 — #99: Attack State Machine & Complexity

6.1 — Attack state transitions in packages/backend/src/services/campaigns.ts

Add transitionAttack(attackId, targetStatus):

• Valid transitions: pending → running → completed | exhausted | failed | paused, paused → running
• Update attacks.status and attacks.updatedAt
• Emit a WebSocket event via emitAttackStatus (add to services/events.ts)

6.2 — Complexity calculation in a new packages/backend/src/services/complexity.ts

Add calculateAttackComplexity(attackId):

• For dictionary attacks (mode 0): complexity = wordlist lineCount × (rulelist lineCount or 1)
• For mask attacks (mode 3): parse mask from advancedConfiguration.mask, compute keyspace using standard charset sizes (lower=26, upper=26, digits=10, special=33)
• For combinator attacks (mode 1): wordlist1 lineCount × wordlist2 lineCount
• Store result in attacks.complexity jsonb: { keyspace, estimatedDurationSeconds, calculatedAt }
• Return the complexity object

6.3 — BullMQ job in a new packages/backend/src/queue/workers/complexity-calculator.ts

• Worker processes complexity-calculation queue jobs
• Each job payload: { attackId }
• Calls calculateAttackComplexity(attackId)

6.4 — Trigger complexity calculation in packages/backend/src/services/campaigns.ts

• After createAttack(), enqueue a complexity-calculation job if queue is available; otherwise calculate inline

6.5 — Dashboard API in packages/backend/src/routes/dashboard/campaigns.ts

• GET /:id/attacks/:attackId/complexity — return attacks.complexity for the given attack

---

Phase 7 — #100: Campaign ETA Calculator

7.1 — ETA service in a new packages/backend/src/services/eta.ts

Add calculateCampaignETA(campaignId):

• Fetch all running tasks for the campaign with their progress.speed values
• Sum total throughput (hashes/sec) across all agents
• Fetch total hashItems count and cracked count for the campaign's hash list
• Fetch remaining keyspace from attacks.complexity for pending/running attacks
• ETA formula: remainingKeyspace / totalThroughput → seconds from now
• Store result in campaigns.progress.eta (ISO string) and campaigns.progress.throughput

7.2 — Trigger ETA recalculation in packages/backend/src/services/tasks.ts

• In updateTaskProgress(), after calling updateCampaignProgress(), also call calculateCampaignETA(campaignId) when data.progress?.speed is present

7.3 — Frontend

• Display campaign.progress.eta on the campaign list and detail pages
• The existing WebSocket campaign-status events already push progress updates — no new WS events needed

---

Phase 8 — #101: SuperHashlists

8.1 — Dashboard API in a new packages/backend/src/routes/dashboard/super-hash-lists.ts

• POST /super-hash-lists — create a SuperHashlist, validate all member hash lists share the same hashTypeId
• GET /super-hash-lists — list project-scoped SuperHashlists
• POST /super-hash-lists/:id/members — add a hash list to a SuperHashlist
• DELETE /super-hash-lists/:id/members/:hashListId — remove a member

8.2 — Deduplication service in a new packages/backend/src/services/super-hash-lists.ts

Add deduplicateSuperHashList(superHashListId):

• Query all hashItems across all member hash lists
• Find hashes that appear in multiple lists (group by hashValue)
• Return deduplication stats: { totalHashes, uniqueHashes, duplicates }

Add propagateCrackResult(hashValue, plaintext, sourceHashListId):

• Find all super_hash_list_members where hashListId = sourceHashListId
• For each sibling hash list in those SuperHashlists, upsert the crack result into hashItems using onConflictDoUpdate
• Emit emitCrackResult for each affected project

8.3 — Hook into crack submission in packages/backend/src/services/tasks.ts

• After the existing hashItems upsert in updateTaskProgress(), call propagateCrackResult for each cracked hash

8.4 — Mount route in packages/backend/src/index.ts

---

Phase 9 — #102: Pre-Cracked Import & Global Hash Search

9.1 — Pre-cracked import in packages/backend/src/routes/dashboard/results.ts

Add POST /results/import:

• Accept JSON body: { hashListId: number; pairs: Array<{ hashValue: string; plaintext: string }> }
• Validate hashListId belongs to the user's project
• Bulk upsert into hashItems using onConflictDoUpdate (same pattern as updateTaskProgress)
• Set crackedAt = now(), agentId = null, campaignId = null (external source)
• Return { imported: number, skipped: number }

9.2 — Global hash search in packages/backend/src/routes/dashboard/results.ts

Add GET /results/search:

• Accept q query param (exact hash value or partial)
• Query hashItems joined with hashLists filtered by hashLists.projectId = projectId
• Return matches with { hashValue, plaintext, crackedAt, hashListId, hashListName }

The existing GET /results already supports q for ILIKE search — the new endpoint focuses on cross-list search without requiring a campaignId filter.

---

Phase 10 — Frontend Wiring

For each new backend feature, add the corresponding TanStack Query hooks in packages/frontend/src/hooks/ and surface them in the relevant pages:

Feature	Hook file	Page
Benchmarks	use-agent-benchmarks.ts	agent-detail.tsx
Cracker binaries	use-crackers.ts	New crackers.tsx admin page
Templates	use-templates.ts	campaign-create.tsx attack form
Attack complexity	use-attack-complexity.ts	campaign-detail.tsx attack list
Campaign ETA	Already in campaign.progress	campaigns.tsx list + campaign-detail.tsx
SuperHashlists	use-super-hash-lists.ts	New super-hash-lists.tsx page
Import	use-import-results.ts	results.tsx
Global search	use-hash-search.ts	results.tsx search bar

All hooks follow the existing pattern: useQuery for reads, useMutation with onSuccess cache invalidation for writes (see use-campaigns.ts for reference).

---

Dependency & Execution Order

graph TD
    A[Phase 1: Schema Extensions] --> B[Phase 2: Benchmarking #93]
    A --> C[Phase 3: Cracker Binaries #94]
    A --> D[Phase 4: Attack Templates #95]
    A --> E[Phase 5: Zap Endpoint #98]
    E --> F[Phase 6: Attack State Machine #99]
    F --> G[Phase 7: ETA Calculator #100]
    E --> H[Phase 8: SuperHashlists #101]
    E --> I[Phase 9: Import & Search #102]
    B --> G
    F --> G

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase is a Bun + Hono + Drizzle ORM monorepo. The schema already has `hashItems`, `agents`, `attacks`, `campaigns`, and `tasks` tables. The core crack submission pipeline (`updateTaskProgress` in `tasks.ts`) already writes to `hashItems` with `onConflictDoUpdate`. The agent API has heartbeat, task assignment, and task reporting endpoints. Missing are: agent benchmarking, cracker binary management, attack templates, attack-level state machine, ETA calculation, SuperHashlists, pre-cracked import, and the zap endpoint.

## Approach

Implement the eight child issues in dependency order: P0 blockers first (benchmarking, cracker binaries, attack templates, zap endpoint), then P1 features (attack state machine, ETA service, SuperHashlists, import/global search). Each change follows the established pattern: schema additions in `shared/src/db/schema.ts` → Drizzle migration → service logic → Hono route → OpenAPI spec update → frontend hook/page.

---

## Implementation Plan

### Phase 1 — Schema Extensions (`packages/shared/src/db/schema.ts`)

Add all new tables in one migration pass to avoid multiple migration files:

**1.1 — `agent_benchmarks` table** (for #93)
- Columns: `id`, `agentId` (FK → `agents`), `hashTypeId` (FK → `hash_types`), `hashcatMode` (integer), `speed` (bigint, hashes/sec), `deviceInfo` (jsonb), `createdAt`
- Unique index on `(agentId, hashcatMode)` — one benchmark row per agent per mode, use `onConflictDoUpdate` on upsert

**1.2 — `cracker_binaries` table** (for #94)
- Columns: `id`, `version` (varchar), `platform` (varchar — e.g. `linux-amd64`), `fileRef` (jsonb — MinIO key + bucket), `isActive` (boolean default true), `createdAt`, `updatedAt`
- Unique index on `(version, platform)`

**1.3 — `attack_templates` table** (for #95)
- Columns: `id`, `projectId` (FK → `projects`), `name`, `description`, `mode` (integer), `hashTypeId` (nullable FK), `wordlistId` (nullable FK), `rulelistId` (nullable FK), `masklistId` (nullable FK), `advancedConfiguration` (jsonb), `createdBy` (FK → `users`), `createdAt`, `updatedAt`

**1.4 — `super_hash_lists` and `super_hash_list_members` tables** (for #101)
- `super_hash_lists`: `id`, `projectId`, `name`, `hashTypeId`, `createdAt`, `updatedAt`
- `super_hash_list_members`: `id`, `superHashListId` (FK), `hashListId` (FK), unique on `(superHashListId, hashListId)`

**1.5 — Schema changes to existing tables**
- `agents`: add `crackerVersion` (varchar, nullable), `benchmarkStatus` (varchar default `'pending'` — values: `pending | running | completed`)
- `attacks`: add `complexity` (jsonb, nullable — stores `{ keyspace, estimatedDuration, calculatedAt }`), `eta` (timestamp, nullable)

After all table additions, run `bun --filter @hashhive/backend db:generate` and `db:migrate`.

---

### Phase 2 — #93: Agent Benchmarking

**2.1 — Agent API endpoint** in `packages/backend/src/routes/agent/index.ts`

Add `POST /benchmarks` route (protected by `requireAgentToken`):
- Zod schema: `{ results: Array<{ hashcatMode: number; speed: number; deviceInfo?: object }> }`
- Upsert each result into `agent_benchmarks` using `onConflictDoUpdate` on `(agentId, hashcatMode)`
- After upsert, update `agents.benchmarkStatus = 'completed'` and `agents.updatedAt`
- Return `{ acknowledged: true, count: number }`

**2.2 — Dashboard API endpoint** in `packages/backend/src/routes/dashboard/agents.ts`

Add `GET /agents/:id/benchmarks` route:
- Query `agent_benchmarks` joined with `hash_types` for the given `agentId`
- Return array of `{ hashcatMode, hashTypeName, speed, deviceInfo, createdAt }`

**2.3 — OpenAPI spec** (`packages/openapi/agent-api.yaml`)
- Add `POST /benchmarks` path with `BenchmarkSubmission` schema (array of mode + speed pairs)

**2.4 — Frontend** (`packages/frontend/src/`)
- Add `useAgentBenchmarks(agentId)` hook in `hooks/` using TanStack Query
- Add a benchmarks table section to the agent detail page (`pages/agent-detail.tsx`)

---

### Phase 3 — #94: Cracker Binary Management

**3.1 — Dashboard API** in a new file `packages/backend/src/routes/dashboard/crackers.ts`
- `GET /crackers` — list all cracker binaries (admin only)
- `POST /crackers` — upload metadata + generate MinIO presigned PUT URL for binary upload (admin only); use existing `@aws-sdk/client-s3` + `@aws-sdk/s3-request-presigner` pattern from `packages/backend/src/config/storage.ts`
- `DELETE /crackers/:id` — soft-delete (set `isActive = false`)

**3.2 — Agent API endpoint** in `packages/backend/src/routes/agent/index.ts`

Add `GET /crackers/latest` route:
- Accept `platform` query param (e.g. `linux-amd64`)
- Query `cracker_binaries` for the latest active binary matching the platform
- Generate a presigned GET URL for the binary using the existing MinIO client
- Return `{ version, downloadUrl, expiresAt }`
- After agent downloads, it should report its version via heartbeat (`capabilities.crackerVersion`)

**3.3 — Mount route** in `packages/backend/src/index.ts`
- `app.route('/api/v1/dashboard/crackers', crackerRoutes)`

**3.4 — OpenAPI spec** — add `GET /crackers/latest` path

---

### Phase 4 — #95: Attack Templates

**4.1 — Dashboard API** in a new file `packages/backend/src/routes/dashboard/templates.ts`
- `GET /templates` — list project-scoped templates (filter by `projectId` from JWT)
- `POST /templates` — create template (admin/operator); Zod schema mirrors `createAttackSchema` in `campaigns.ts` plus `name` and `description`
- `GET /templates/:id` — get single template
- `PATCH /templates/:id` — update template
- `DELETE /templates/:id` — delete template

**4.2 — Template instantiation** in `packages/backend/src/services/campaigns.ts`

Add `createAttackFromTemplate(campaignId, templateId)`:
- Fetch template, verify project scope
- Call existing `createAttack()` with template fields pre-filled

**4.3 — Campaign attack creation endpoint** in `packages/backend/src/routes/dashboard/campaigns.ts`
- Extend `POST /:id/attacks` to accept optional `templateId`; when present, delegate to `createAttackFromTemplate`

**4.4 — Mount route** in `packages/backend/src/index.ts`
- `app.route('/api/v1/dashboard/templates', templateRoutes)`

**4.5 — Frontend**
- Add `useTemplates()` and `useCreateTemplate()` hooks
- Add template selector component in the campaign attack creation form (`components/features/`)

---

### Phase 5 — #98: Zap Endpoint (the missing piece of the crack pipeline)

The crack submission itself already works via `POST /tasks/:id/report`. The missing piece is the **zap endpoint** — agents fetching already-cracked hashes to skip.

**5.1 — Agent API endpoint** in `packages/backend/src/routes/agent/index.ts`

Add `GET /tasks/:id/zaps` route:
- Accept optional `since` query param (ISO timestamp)
- Join `hashItems` → `campaigns` → `hashLists` to find hashes cracked for the same hash list as the task's campaign, since the given timestamp
- Return `{ hashes: string[], count: number }` — just the hash values (agents skip these)
- Default `since` to task's `assignedAt` if not provided

**5.2 — OpenAPI spec** — add `GET /tasks/{taskId}/zaps` path with `since` query param

---

### Phase 6 — #99: Attack State Machine & Complexity

**6.1 — Attack state transitions** in `packages/backend/src/services/campaigns.ts`

Add `transitionAttack(attackId, targetStatus)`:
- Valid transitions: `pending → running → completed | exhausted | failed | paused`, `paused → running`
- Update `attacks.status` and `attacks.updatedAt`
- Emit a WebSocket event via `emitAttackStatus` (add to `services/events.ts`)

**6.2 — Complexity calculation** in a new `packages/backend/src/services/complexity.ts`

Add `calculateAttackComplexity(attackId)`:
- For **dictionary** attacks (mode 0): complexity = wordlist `lineCount` × (rulelist `lineCount` or 1)
- For **mask** attacks (mode 3): parse mask from `advancedConfiguration.mask`, compute keyspace using standard charset sizes (lower=26, upper=26, digits=10, special=33)
- For **combinator** attacks (mode 1): wordlist1 `lineCount` × wordlist2 `lineCount`
- Store result in `attacks.complexity` jsonb: `{ keyspace, estimatedDurationSeconds, calculatedAt }`
- Return the complexity object

**6.3 — BullMQ job** in a new `packages/backend/src/queue/workers/complexity-calculator.ts`
- Worker processes `complexity-calculation` queue jobs
- Each job payload: `{ attackId }`
- Calls `calculateAttackComplexity(attackId)`

**6.4 — Trigger complexity calculation** in `packages/backend/src/services/campaigns.ts`
- After `createAttack()`, enqueue a `complexity-calculation` job if queue is available; otherwise calculate inline

**6.5 — Dashboard API** in `packages/backend/src/routes/dashboard/campaigns.ts`
- `GET /:id/attacks/:attackId/complexity` — return `attacks.complexity` for the given attack

---

### Phase 7 — #100: Campaign ETA Calculator

**7.1 — ETA service** in a new `packages/backend/src/services/eta.ts`

Add `calculateCampaignETA(campaignId)`:
- Fetch all running tasks for the campaign with their `progress.speed` values
- Sum total throughput (hashes/sec) across all agents
- Fetch total `hashItems` count and cracked count for the campaign's hash list
- Fetch remaining keyspace from `attacks.complexity` for pending/running attacks
- ETA formula: `remainingKeyspace / totalThroughput` → seconds from now
- Store result in `campaigns.progress.eta` (ISO string) and `campaigns.progress.throughput`

**7.2 — Trigger ETA recalculation** in `packages/backend/src/services/tasks.ts`
- In `updateTaskProgress()`, after calling `updateCampaignProgress()`, also call `calculateCampaignETA(campaignId)` when `data.progress?.speed` is present

**7.3 — Frontend**
- Display `campaign.progress.eta` on the campaign list and detail pages
- The existing WebSocket `campaign-status` events already push `progress` updates — no new WS events needed

---

### Phase 8 — #101: SuperHashlists

**8.1 — Dashboard API** in a new `packages/backend/src/routes/dashboard/super-hash-lists.ts`
- `POST /super-hash-lists` — create a SuperHashlist, validate all member hash lists share the same `hashTypeId`
- `GET /super-hash-lists` — list project-scoped SuperHashlists
- `POST /super-hash-lists/:id/members` — add a hash list to a SuperHashlist
- `DELETE /super-hash-lists/:id/members/:hashListId` — remove a member

**8.2 — Deduplication service** in a new `packages/backend/src/services/super-hash-lists.ts`

Add `deduplicateSuperHashList(superHashListId)`:
- Query all `hashItems` across all member hash lists
- Find hashes that appear in multiple lists (group by `hashValue`)
- Return deduplication stats: `{ totalHashes, uniqueHashes, duplicates }`

Add `propagateCrackResult(hashValue, plaintext, sourceHashListId)`:
- Find all `super_hash_list_members` where `hashListId = sourceHashListId`
- For each sibling hash list in those SuperHashlists, upsert the crack result into `hashItems` using `onConflictDoUpdate`
- Emit `emitCrackResult` for each affected project

**8.3 — Hook into crack submission** in `packages/backend/src/services/tasks.ts`
- After the existing `hashItems` upsert in `updateTaskProgress()`, call `propagateCrackResult` for each cracked hash

**8.4 — Mount route** in `packages/backend/src/index.ts`

---

### Phase 9 — #102: Pre-Cracked Import & Global Hash Search

**9.1 — Pre-cracked import** in `packages/backend/src/routes/dashboard/results.ts`

Add `POST /results/import`:
- Accept JSON body: `{ hashListId: number; pairs: Array<{ hashValue: string; plaintext: string }> }`
- Validate `hashListId` belongs to the user's project
- Bulk upsert into `hashItems` using `onConflictDoUpdate` (same pattern as `updateTaskProgress`)
- Set `crackedAt = now()`, `agentId = null`, `campaignId = null` (external source)
- Return `{ imported: number, skipped: number }`

**9.2 — Global hash search** in `packages/backend/src/routes/dashboard/results.ts`

Add `GET /results/search`:
- Accept `q` query param (exact hash value or partial)
- Query `hashItems` joined with `hashLists` filtered by `hashLists.projectId = projectId`
- Return matches with `{ hashValue, plaintext, crackedAt, hashListId, hashListName }`

> The existing `GET /results` already supports `q` for ILIKE search — the new endpoint focuses on cross-list search without requiring a `campaignId` filter.

---

### Phase 10 — Frontend Wiring

For each new backend feature, add the corresponding TanStack Query hooks in `packages/frontend/src/hooks/` and surface them in the relevant pages:

| Feature | Hook file | Page |
|---|---|---|
| Benchmarks | `use-agent-benchmarks.ts` | `agent-detail.tsx` |
| Cracker binaries | `use-crackers.ts` | New `crackers.tsx` admin page |
| Templates | `use-templates.ts` | `campaign-create.tsx` attack form |
| Attack complexity | `use-attack-complexity.ts` | `campaign-detail.tsx` attack list |
| Campaign ETA | Already in `campaign.progress` | `campaigns.tsx` list + `campaign-detail.tsx` |
| SuperHashlists | `use-super-hash-lists.ts` | New `super-hash-lists.tsx` page |
| Import | `use-import-results.ts` | `results.tsx` |
| Global search | `use-hash-search.ts` | `results.tsx` search bar |

All hooks follow the existing pattern: `useQuery` for reads, `useMutation` with `onSuccess` cache invalidation for writes (see `use-campaigns.ts` for reference).

---

### Dependency & Execution Order

```mermaid
graph TD
    A[Phase 1: Schema Extensions] --> B[Phase 2: Benchmarking #93]
    A --> C[Phase 3: Cracker Binaries #94]
    A --> D[Phase 4: Attack Templates #95]
    A --> E[Phase 5: Zap Endpoint #98]
    E --> F[Phase 6: Attack State Machine #99]
    F --> G[Phase 7: ETA Calculator #100]
    E --> H[Phase 8: SuperHashlists #101]
    E --> I[Phase 9: Import & Search #102]
    B --> G
    F --> G
```

---

Execution Information

Branch: main
Commit: 16f43e5

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[unclesp1d3r]

@coderabbitai Enhance this issue body with additional context. This is an Epic for tracking work on the subissues, and the context should be derived from the associated subissues. Improve the issue title and assign the proper labels and other metadata.