mirror of https://github.com/allaunthefox/Research-Stack.git synced 2026-07-31 03:05:21 +00:00

Brandon Schneider 546783faaf docs: add external research import maps

2026-05-20 18:41:21 -05:00

19 KiB

Raw Blame History

AngrySphinx Donated-Cycle Gate Specification

Version History

Version	Date	Author	Changes
0.1	2026-05-20	Codex	Initial design spec for Anubis-style web proxy integration

1. Purpose

AngrySphinx Donated-Cycle Gate is a web-facing proof-of-defense layer where suspicious or adversarial clients must spend local compute before receiving protected content. Unlike generic proof-of-work, the client work is shaped so accepted proofs contribute to the defender's own gate calibration, route hardening, challenge corpus, or bounded useful-compute queue.

The security doctrine is:

The attacker either leaves, or donates cycles that improve the gate defending the system.

The system is intentionally compatible with an Anubis-style anti-bot proxy: browser-side or client-side challenge work is expensive for the requester, while server-side verification remains cheap and bounded.

Baseline critique: a plain Anubis-style proof-of-work gate is needlessly wasteful when the solved work is only discarded. It can still be operationally useful as bot friction, but the compute is burned rather than converted into route memory, defensive calibration, or challenge hardening. AngrySphinx keeps the cheap-verification proxy shape while requiring accepted work to leave a defensive receipt.

2. Design Goals

2.1 Primary Goals

Convert abusive traffic into measurable defensive work.
Avoid burn-only proof-of-work where accepted client cycles produce no defensive state.
Preserve cheap server verification for every challenge response.
Increase challenge difficulty based on observed attack pressure.
Attach every accepted proof to an auditable proof-of-defense receipt.
Keep protected origin services insulated from untrusted clients.
Make useful work optional and bounded; the default challenge remains hashcash-compatible.

2.2 Non-Goals

Do not execute arbitrary attacker-supplied code.
Do not rely on server-expensive verification.
Do not claim that web proof-of-work stops all bot traffic.
Do not require useful scientific computation in the first prototype.
Do not weaken accessibility or legitimate low-power client access without fallback paths.

3. System Model

3.1 Components

Component	Responsibility
Edge Proxy	Intercepts requests before origin access, issues challenges, verifies proofs
Challenge Engine	Builds challenge payloads from policy, telemetry, and difficulty state
Work Client	Browser or command-line solver performing bounded local compute
Proof Verifier	Checks proof cheaply and deterministically
PoD Ledger	Records accepted work, shell depth, attestation, and route metadata
Defense Calibrator	Converts proof telemetry into difficulty and route-hardening updates
Policy Layer	Refuses forbidden operations and selects fallback behavior

3.2 Existing Formal Anchors

Semantics.AngrySphinx.AttackPressure: represents attack pressure as energy quanta.
Semantics.AngrySphinx.ShellDepth: tracks S3 shell depth.
Semantics.AngrySphinx.gearProduct: computes the shell multiplier, defaulting to 2^depth.
Semantics.AngrySphinx.solveEnergy: models required solve energy from pressure and shell depth.
Semantics.AngrySphinx.PodAccumulator: records accepted work and the last attestation.
Semantics.AngrySphinx.verifyPod: checks accumulated work against shell depth.
Semantics.AngrySphinxPolicy: enforces refusal and review gates.

4. Core Mechanic

4.1 Request Flow

Client requests a protected URL.
Edge Proxy evaluates request risk using IP, path, rate, user-agent, cookies, prior receipts, and route class.
If risk is low, request passes normally.
If risk is medium or high, Challenge Engine emits an AngrySphinx challenge.
Work Client solves the challenge locally.
Client submits proof, nonce, challenge ID, and optional timing telemetry.
Proof Verifier checks the proof cheaply.
If valid, Edge Proxy issues a short-lived access token and forwards the request.
PoD Ledger records donated work and updates defensive state.
Defense Calibrator adjusts future challenge difficulty or route policy.

4.2 Challenge Shape

Every challenge must contain:

{
  "challenge_id": "opaque id",
  "route_id": "normalized protected route class",
  "issued_at": "unix timestamp",
  "expires_at": "unix timestamp",
  "difficulty": 24,
  "shell_depth": 8,
  "gear_ratio": 2,
  "mode": "hashcash",
  "seed": "server signed random seed",
  "policy_root": "angrysphinx:web_gate:v0.1",
  "receipt_required": true
}

The initial prototype should use mode = "hashcash" because it is simple, auditable, and cheap to verify. Later modes can embed bounded useful-compute tasks, but only when verification remains cheap.

4.3 Proof Shape

Every proof must contain:

{
  "challenge_id": "opaque id",
  "nonce": "client nonce",
  "digest": "hash(seed || nonce || route_id)",
  "client_elapsed_ms": 1830,
  "work_claim": 16777216,
  "client_class_hint": "browser"
}

The verifier must be able to recompute the digest and compare it to the target threshold without replaying the full search.

5. Donated-Cycle Accounting

5.1 Work Units

The proxy records accepted challenge work as work_units, not trusted joules. For hashcash challenges:

work_units = 2^difficulty

For sampled verification modes:

work_units = verified_steps * confidence_factor

The client may report elapsed time, but elapsed time is telemetry only. It must not be trusted for accounting.

5.2 PoD Ledger Entry

Each accepted proof appends a record:

{
  "receipt_id": "pod receipt id",
  "challenge_id": "challenge id",
  "route_id": "normalized route",
  "client_fingerprint": "privacy-preserving bucket",
  "risk_class": "medium|high|hostile",
  "difficulty": 24,
  "shell_depth_before": 8,
  "shell_depth_after": 9,
  "work_units": 16777216,
  "accepted_at": "unix timestamp",
  "attestation": "work=...,depth=...",
  "policy_root": "angrysphinx:web_gate:v0.1"
}

This corresponds to PodAccumulator.accumulateWork: accepted work increases totalWork, and sustained hostile pressure can deepen the shell.

5.3 Work Sinks

Accepted work can support four defensive sinks:

Sink	Description	Prototype Priority
Difficulty Calibration	Tune future difficulty by observed solve rates and route pressure	High
Route Hardening	Raise challenge depth for routes receiving hostile pressure	High
Challenge Corpus Expansion	Generate new signed seeds and route-specific challenge variants	Medium
Science Donation Plugin Queue	Assign bounded, verifiable tasks that contribute to research or defense models	Later

The first implementation should only support calibration and route hardening. Science donation plugins should be added only after threat modeling and verification design are complete.

6. Difficulty and Shell Policy

6.1 Attack Pressure

Attack pressure is computed per route bucket:

pressure = f(request_rate, failed_proofs, replay_attempts, origin_errors, suspicious_paths)

The pressure maps to AttackPressure.joules in the formal model. This is a normalized integer, not physical energy.

6.2 Shell Depth

Shell depth increases when hostile traffic keeps paying challenges or failing proofs:

new_depth = min(max_depth, base_depth + pressure_band + route_sensitivity)

With default gear ratio 2, solve cost scales as:

required_work >= 2^shell_depth

6.3 Difficulty Bounds

The proxy must enforce bounds:

Bound	Purpose
`min_difficulty`	Prevent zero-cost bypass
`max_difficulty`	Avoid denial of service against legitimate clients
`max_solve_ms_target`	Accessibility and device-safety budget
`token_ttl`	Limit replay value
`challenge_ttl`	Limit stale challenge reuse

Suggested initial defaults:

min_difficulty = 18
max_difficulty = 28
base_shell_depth = 8
max_shell_depth = 32
challenge_ttl = 120 seconds
access_token_ttl = 900 seconds

7. Verification Requirements

7.1 Server Verification

Verification must be:

Deterministic.
Stateless or bounded-state.
O(1) or O(log n) relative to client work.
Replay resistant.
Bound to route, timestamp, and policy root.
Signed or MACed so clients cannot forge easier challenges.

7.2 Replay Protection

The server must reject:

Expired challenge IDs.
Reused challenge IDs.
Proofs bound to different routes.
Proofs with invalid policy roots.
Proofs below the target threshold.
Proofs for revoked challenge versions.

7.3 Origin Isolation

The origin service should only receive requests with a valid access token or trusted bypass identity. It should not implement challenge verification itself.

8. Science Donation Plugin Extension

The science donation concept is a plugin track layered beside the live security gate. The gate still decides access using cheap proof verification. The plugin consumes eligible donated-cycle opportunities and assigns bounded work packets that can support science or defense research.

The plugin must not make origin access depend on expensive server-side recomputation. Its job is to turn otherwise wasted proof-of-work into auditable science work when safe, not to put arbitrary scientific workloads in the critical request path.

Critical rule: science donation is funded only by surplus attacker cost. The gate must first satisfy its defensive work requirement. Only the excess work budget above the active defense floor may be redirected to science tasks.

required_defense_work = defense_floor(route, shell_depth, pressure, policy)
paid_work            = accepted client work
surplus_work         = max(0, paid_work - required_defense_work)

science_work_allowed iff surplus_work > 0 and defense_level_after >= defense_level_before

If a science plugin would reduce route hardening, lower shell depth, consume verifier budget, delay refusal, weaken replay protection, or otherwise reduce the active defense level, the plugin is not admissible for that request.

8.1 Required Properties

Science donation plugins are admissible only if they satisfy:

Cheap verification.
No private data exposure.
No attacker-controlled program execution.
No result dependence on unverifiable floating-point behavior.
Bounded memory and CPU footprint.
Deterministic challenge generation.
Clear failure mode that falls back to hashcash.
Explicit plugin manifest describing task class, verification method, resource budget, and data provenance.

8.2 Plugin Boundary

Each plugin exposes:

{
  "plugin_id": "science.protein_microtask.v0",
  "task_class": "bounded_search",
  "verification": "known_witness_or_spot_check",
  "max_client_ms": 2000,
  "max_memory_mb": 64,
  "data_policy": "public_or_synthetic_only",
  "fallback_mode": "hashcash",
  "receipt_schema": "science_donation_receipt.v0"
}

The Challenge Engine may select a plugin task only when:

required defensive work has already been met
projected defense level will not decrease
surplus work remains after gate accounting
route policy permits plugin work
client class can safely run it
task verification remains bounded
task data is public or synthetic
fallback hashcash challenge is available

8.3 Candidate Task Classes

Task Class	Verification Strategy	Risk
Hashcash with route-derived seeds	Recompute digest	Low
Verifiable random function preimage search	Recompute proof	Low
Merkleized micro-benchmark witness	Spot-check trace commitments	Medium
SAT/CNF micro-instance with known witness	Verify assignment	Medium
Protein/graph heuristic search	Hard to verify cheaply	High

Scientific or research-side tasks should start as offline sinks fed by proof telemetry, not as direct web challenges.

8.4 Plugin Receipt

Science donation work emits a separate receipt linked to the PoD receipt:

{
  "science_receipt_id": "science receipt id",
  "pod_receipt_id": "linked proof-of-defense receipt id",
  "plugin_id": "science.protein_microtask.v0",
  "task_id": "bounded task id",
  "verification_result": "accepted|rejected|sampled",
  "work_units": 16777216,
  "output_commitment": "hash of submitted result",
  "data_policy": "public_or_synthetic_only"
}

This lets the security ledger remain simple while science donation work gets its own provenance chain.

8.5 Defense-Preserving Redirect

The redirect rule is:

defense first, science second

The Challenge Engine computes a route-specific defense floor before issuing any science task. A client may be asked to solve a combined challenge, but the proof must be decomposable into:

the defensive portion required for access control
the surplus portion eligible for science donation

The PoD Ledger records the defensive portion first. The Science Donation Plugin records only surplus work. If the client abandons the science portion, the gate may still accept the defensive proof if the required defense floor was met.

This prevents the plugin system from becoming an accidental bypass where science work replaces route hardening.

8.6 Practical Rule

For web deployment:

If verification is not cheap, it is not an AngrySphinx web gate task.

For plugin deployment:

If science work cannot be verified cheaply online, route it to an offline donation queue instead of the access gate.
If science work competes with the defense floor, reject the science plugin and keep the defense work.

9. Privacy and Safety

9.1 Client Fingerprints

The ledger should store coarse buckets, not raw fingerprints:

route bucket
risk class
approximate client class
proof timing quantile
coarse network bucket if needed

Avoid storing raw IPs unless operationally required. If raw IPs are stored, define retention and deletion policy.

9.2 Legitimate Client Fallback

The system must support:

authenticated bypass
low-power mode
accessibility bypass
allowlisted crawlers where appropriate
manual review or contact path

9.3 Abuse Constraints

The system must not become a client-side cryptominer or hidden compute extractor. Challenges are only issued for access control and defense. The page must clearly indicate that a security check is running.

10. Anubis Integration Plan

10.1 Minimal Fork Strategy

Use Anubis as the edge proxy and challenge transport, but treat its default burn-only proof-of-work model as the baseline to improve. Add AngrySphinx as a policy/accounting layer:

Anubis request classifier
  -> AngrySphinx difficulty policy
  -> Anubis-style hash challenge
  -> AngrySphinx proof ledger
  -> access token
  -> origin

This avoids rewriting proxy mechanics before the donated-cycle model is validated.

10.2 Required Integration Points

Integration Point	Required Change
Challenge generation	Include `route_id`, `shell_depth`, `policy_root`, signed seed
Challenge page	Brand/copy as AngrySphinx, expose clear security-check semantics
Proof verification	Emit ledger event after accepted proof
Difficulty policy	Compute challenge difficulty from route pressure and shell depth
Metrics	Track solves, failures, replay attempts, elapsed time, and origin pass-through
Admin config	Add route-specific min/max difficulty and bypass rules

10.3 First Prototype Scope

The first prototype should implement:

Hashcash-only challenge mode.
Route-bound challenge IDs.
Signed challenge payloads.
In-memory or SQLite PoD ledger.
Per-route difficulty adjustment.
Basic admin metrics.
No useful-compute tasks yet.
No science donation plugins in the request-critical path yet.

11. Formal Mapping

11.1 Lean Correspondence

Web Spec Concept	Lean Concept
risk pressure	`AttackPressure`
route shell depth	`ShellDepth`
difficulty multiplier	`GearRatio` / `gearProduct`
donated proof work	`PodAccumulator.totalWork`
accepted proof receipt	`PodAccumulator.lastAttestation`
work admission check	`verifyPod`
refusal policy	`AngrySphinxPolicy` / `AngrySphinxGate`

11.2 Intended Theorem Direction

Future formal work should prove:

accepted_web_proof implies ledger_work_increases
ledger_work_increases implies nondecreasing_defense_budget
shell_depth_increases implies required_work_non_decreasing
invalid_or_expired_proof implies no_origin_access

The existing solveEnergyExponential theorem is the core target: route pressure should imply exponentially increasing solve obligation under bounded depth.

12. Operational Metrics

Track:

challenge issue count
proof success count
proof failure count
replay rejection count
average solve time by difficulty
p95 solve time by client class
route pressure score
current route shell depth
donated work units per route
origin requests spared
bypass uses

The key dashboard metric:

defense_work_ratio = accepted_donated_work_units / origin_requests_served

13. Open Questions

Which Anubis version and extension points should be used for the prototype?
Should the first ledger be SQLite, JSONL, or Prometheus-only?
How should authenticated users bypass or receive lower difficulty?
What is the maximum acceptable challenge time for low-power devices?
Which route classes deserve independent shell depth?
Should useful-compute be implemented at all in the web path, or only as an offline research sink?
How should FAMM route scars and PIST shell coordinates be bound into the live challenge policy?
What plugin manifest and receipt schema should science donation tasks use?

14. Implementation Milestones

Milestone 1: Baseline Gate

Run Anubis-style hashcash challenge on protected route.
Bind challenge to route, timestamp, and policy root.
Verify proof and issue short-lived access token.

Milestone 2: PoD Ledger

Persist accepted proof records.
Track donated work units.
Emit work=...,depth=... attestations compatible with PodAccumulator.

Milestone 3: Adaptive Shell Policy

Compute per-route pressure.
Adjust shell depth and difficulty within bounds.
Add replay and failure-rate hardening.
Wire FAMM scar memory into route hardening using FAMMScarMemory.lean, FAMM.lean, and RouteCost.lean.
Map route and challenge IDs into PIST/ShellModel coordinates using PIST.lean, ShellModel.lean, and PistBridge.lean.

Milestone 4: Admin and Observability

Add metrics endpoint or dashboard.
Show route pressure, donated work, failure rate, and current difficulty.
Add operational bypass and allowlist controls.

Milestone 5: Useful-Compute Research Track

Evaluate verifiable task classes offline.
Add only if verification remains cheap and policy-compliant.
Define the science donation plugin manifest.
Define the linked science donation receipt schema.
Keep plugin tasks outside the request-critical path until bounded verification is proven.

15. Summary

AngrySphinx Donated-Cycle Gate turns anti-bot friction into a defensive asset. The attacker does not merely burn cycles; accepted work is receipted, counted, and used to harden the same gate that blocked them. An Anubis-style proxy provides the correct implementation shape because it already separates expensive client solving from cheap server verification.

19 KiB Raw Blame History