request-minimizer

Safely find the smallest cookie subset that still makes an authenticated browser request work.

request-minimizer imports a browser-copied cURL request containing many cookies, replays it only to the imported endpoint, and uses provider-specific validation while reducing the cookie set. Its complete local workflow is:

import → verify → minimize → fetch

Version 0.1 minimizes cookies only. It is not browser automation, a login tool, a credential scraper, a proxy, a server, or a general-purpose HTTP framework.

Why it exists

Browser requests often carry dozens of cookies even when an endpoint needs only one or two. Replaying all of them creates unnecessary credential exposure and makes integrations harder to understand. This tool answers a narrower question: which cookie names remain necessary for a specific request to satisfy a meaningful response contract?

HTTP 200 is not enough. Every request is judged by a validator that understands the provider response and exposes only explicitly approved summary fields.

Real-world result

The first end-to-end test used an authenticated Alibaba Model Studio Token Plan usage request:

45 cookies → 1 cookie
18 requests
~1m 23s
zero-cookie request failed validation
fresh final verification passed
safe minimized-request fetch passed

The retained cookie was named login_aliyunid_ticket. Its value was never displayed.

That result applied only to that endpoint, region, account session, and moment in time. Providers can change authentication requirements, and cookie names can vary. A surviving cookie value is still a credential and must be treated like a password.

How minimization works

1. A fresh request with the complete imported cookie set establishes a working baseline. The baseline is intentionally tested once, even when candidate confirmations exceed one, to limit traffic.
2. A deterministic delta-debugging-style search tries removing cookie groups, reducing the group size when larger removals fail.
3. Successful candidates require two fresh confirmations by default. A bounded retry may be used for a retryable malformed response.
4. Authentication failure from a reduced candidate normally means a required cookie was removed. The candidate is recorded as failed, then the current known-good set is tested with a fresh control request. The run stops for session expiration only if that control also fails authentication.
5. Unless disabled, a final one-cookie-at-a-time cleanup checks whether any retained cookie can still be removed. This includes testing an empty cookie set when applicable.
6. The retained set receives a fresh, uncached final verification before result files are written.
7. fetch checks the minimized result's provenance and sends one fresh request using only the retained cookie set. It never falls back to the original set.

Every baseline, candidate confirmation, bounded retry, known-good control, resumed baseline, and final request counts toward the request budget and observes the configured inter-request delay. Candidate subsets are cached by cookie-name set, and checkpoints contain no cookie values.

The result is minimal relative to observed validator behavior and mutable server state. With final cleanup it is intended to be 1-minimal: no single retained cookie can be removed without failure. It is not a mathematical guarantee of the globally smallest set under every possible combination or future provider behavior.

Safety model

The tool helps prevent:

• unnecessary replay of unrelated cookies;
• accidental printing of cookie and sensitive-header values;
• credential replay to a different scheme, host, or effective port;
• automatic redirect following and cross-host redirect leakage;
• raw-response dumping;
• stale minimized-result reuse;
• treating HTTP 200 alone as success.

It does not protect against:

• a compromised machine or malicious local user;
• a coding agent explicitly authorized to read secret-bearing files;
• provider-side behavior changes or session expiration;
• credential theft outside this process;
• abuse of the one surviving credential;
• secrets copied into issue reports, commits, or unrelated tooling.

.env uses restrictive POSIX permissions and base64-encoded values to reduce accidental leakage. Base64 is not encryption, file permissions are not a sandbox, and neither is a hard security boundary. Log out or revoke the session after experimentation when appropriate.

Installation

Python 3.12 or newer is required.

Shell-neutral setup:

python -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/request-minimizer --help

For local development in Fish:

python -m venv .venv
source .venv/bin/activate.fish
python -m pip install -e '.[dev]'

The installed command is request-minimizer; python -m request_minimizer is equivalent.

Quick start

Export a request with Chrome or another browser's “Copy as cURL” command and save it locally. Do not paste real requests or cookies into chat, issues, or pull requests.

chmod 600 request.curl
request-minimizer import request.curl --validator alibaba-token-plan
request-minimizer info
request-minimizer verify
request-minimizer minimize --min-delay 2 --max-delay 5 --max-requests 120
request-minimizer fetch
request-minimizer fetch --json

request.curl, .env, and minimal-cookies.env contain credentials. Keep them private and inspect every generated file before publishing a working directory.

Command reference

Run request-minimizer --help or any command with --help for the authoritative option list. request-minimizer --version prints the installed version.

import

request-minimizer import FILE --validator NAME [--allow-http] [--timeout SECONDS]

Parses, but never executes, one copied cURL command. It extracts the URL, method, replayable headers, body, and cookies. Non-secret configuration goes to request.json; cookie values, sensitive headers, bodies, and sensitive URL values go to .env.

HTTPS is required unless --allow-http is explicitly used for a controlled target. The imported scheme, hostname, and effective port are locked. Duplicate cookie or header names are rejected rather than resolved ambiguously.

info

request-minimizer info

Shows only safe metadata: target hostname, method, redacted path and query, validator, cookie names and count, fixed header names, body presence, import timestamp, and checkpoint status.

verify

request-minimizer verify

Sends one fresh request with the full cookie set, follows no redirects, and requires both HTTP-level and validator-specific success. Failures produce a structured redacted diagnostic, never a raw response dump.

inspect-response

request-minimizer inspect-response

Sends one fresh full request and prints JSON structure only: HTTP status, media type, non-sensitive key names, nesting paths, list lengths, and scalar type names. It never prints scalar values or writes a response body. Sensitive key names are omitted, depth, breadth, and body size are bounded, and JSON strings containing nested JSON are described as structure only.

This command is for safely adapting a validator when a provider changes its response shape. Its output can still reveal endpoint structure, so review it before sharing.

minimize

request-minimizer minimize [--confirmations N] [--min-delay SECONDS]
                           [--max-delay SECONDS] [--max-requests N]
                           [--resume] [--no-final-cleanup]

Runs the reduction algorithm described above. Defaults are two candidate confirmations, a randomized 1.0–2.5 second delay, and a 150-request budget. Progress contains cookie names and counts only. --no-final-cleanup skips the 1-minimal cleanup pass.

Ctrl+C and safety stops save minimizer-state.json. Resume with:

request-minimizer minimize --resume

Resume verifies a secret-free configuration fingerprint, preserves the request count, reuses completed candidate outcomes, and makes a fresh baseline request before continuing.

test

request-minimizer test --exclude COOKIE_NAME[,COOKIE_NAME...]
request-minimizer test --only COOKIE_NAME[,COOKIE_NAME...]

Makes one diagnostic request for a manually selected cookie-name subset. The two options are mutually exclusive. Unknown names are rejected, and cookie values are never accepted on the command line.

fetch

request-minimizer fetch
request-minimizer fetch --json

Requires the last completed minimization to have a successful fresh final verification and matching imported-request provenance. It reads retained names from the non-secret report and values from the private secret store, then makes one fresh request with only that set.

Missing, failed, incomplete, or stale minimization results produce a clear error. There is no full-cookie fallback. Authentication expiration and provider validation failures also fail closed.

Output and JSON mode

Human-readable request output contains fixed metadata and validator-approved summary fields only. A synthetic example:

Target hostname: example.test
HTTP status: 200
Validation: passed
Cookie count: 1
per5HourPercentage: 0.25
per1WeekPercentage: 0.5

fetch --json writes one valid JSON document to stdout with no progress text or ANSI sequences. Errors that occur before a request produce no stdout and a safe message on stderr. A sent request that fails validation emits a safe structured failure document and exits nonzero. Raw responses, request IDs, trace IDs, session identifiers, and arbitrary provider data are excluded.

{
  "cookie_count": 1,
  "http_status": 200,
  "summary": {
    "per1WeekPercentage": 0.5,
    "per5HourPercentage": 0.25
  },
  "target_hostname": "example.test",
  "validation": "passed"
}

Generated files

File	Contents and handling
.env	Private base64-encoded imported values; mode 0600 on POSIX. Base64 is not encryption.
request.json	Non-secret request structure, stable secret IDs, and binding fingerprint; mode 0600 on POSIX.
minimizer-state.json	Secret-free cookie-name subsets, outcomes, counters, and algorithm state; mode 0600 on POSIX.
minimal-cookies.env	Retained names and values after success; mode 0600 on POSIX.
minimal-cookie-names.txt	Retained cookie names only.
minimization-report.json	Non-secret names, counts, timestamps, results, and provenance.
diagnostic-*.json	Structured redacted failure metadata; mode 0600 on POSIX.

All are ignored by the repository where appropriate. Ignore rules do not prove a file was never committed; inspect Git history before publishing a repository. These files are data for request-minimizer, not shell scripts—do not source or execute them.

Adding a validator

A validator defines the meaningful response contract for an endpoint. It decides whether the provider actually accepted the request, classifies authentication and retryable failures, and returns a small normalized summary safe for display. Add a validator when an endpoint has a different definition of success, authentication failure, retryability, or safe output—not merely because it uses another hostname.

The interface is the ResponseValidator protocol in validators/base.py. Its validate(HttpResponse) -> ValidatorResult method returns:

• valid: whether the expected provider operation succeeded;
• authentication_failed: whether the full or known-good session is likely expired;
• retryable: whether a bounded retry may distinguish a transient malformed response;
• summary: explicitly allowlisted safe scalar fields;
• error: a fixed, non-secret explanation.

Use alibaba_token_plan.py as the canonical implementation. Register a stable CLI name in validators/__init__.py; dynamic plugin loading is intentionally out of scope.

Implementation sequence:

1. Parse only the provider format you expect.
2. Detect 401/403, login redirects or HTML, and provider-specific session-expiration markers as authentication failures.
3. Require provider-specific nested success evidence; HTTP 200 alone is insufficient.
4. Treat internal provider errors and unknown shapes as invalid.
5. Mark only genuinely transient malformed states retryable, if applicable.
6. Build the summary field-by-field from a written allowlist. Never pass through a provider object.
7. Add synthetic success, internal failure, login, malformed, unknown-shape, and secret-nondisclosure tests.
8. Import a controlled request with the new validator and exercise verify, minimize, and fetch through their normal CLI boundaries.

A validator must:

• treat HTTP status alone as insufficient;
• parse only the expected response format;
• require provider-specific evidence of success;
• distinguish authentication failure from ordinary invalid responses;
• distinguish malformed and retryable responses where applicable;
• return only explicitly approved safe summary fields;
• never return raw response bodies;
• never include cookies, tokens, session IDs, request IDs, trace IDs, or arbitrary provider JSON;
• fail closed when the response shape is unknown;
• include synthetic regression tests.

One validator may cover multiple endpoints only when they share the same meaningful response contract.

Alibaba Token Plan validator

alibaba-token-plan supports the undocumented Model Studio console usage endpoint used by the original investigation. Undocumented console endpoints may change without notice.

Success requires HTTP 200, Alibaba's expected nested success markers, inner code == "SUCCESS", a usage object, and at least one allowlisted usage field. The live-compatible response may omit DataV2.success; if present it must be exactly true. The only summary fields are:

• per5HourPercentage
• per5HourResetTime
• per1WeekPercentage
• per1WeekResetTime

Login HTML, redirects, 401/403, malformed JSON, missing success evidence, internal HTTP-200 failures, and responses without usage fields all fail validation. Alibaba request IDs are never retained or reported.

Parser and replay limitations

The parser supports common copied-cURL forms: curl URL, -X/--request, -H/--header, -b/--cookie, --url, --data, --data-raw, and --data-binary. It accepts shell-quoted multiline commands, literal dollar signs inside single quotes, escaped LF/CRLF continuations, and trailing whitespace.

It deliberately rejects:

• pipelines, redirects, command chaining, semicolon-separated or additional commands;
• shell expansion outside single quotes, including inside double quotes;
• backtick and $() command substitution;
• URL credentials, cookie files, body files, unknown options, malformed cookies, and duplicate cookie or header names.

Harmless browser flags such as --compressed are ignored. Unsafe transport headers such as Host, Content-Length, Accept-Encoding, Connection, HTTP/2 pseudoheaders, sec-fetch-*, sec-ch-ua*, and priority are regenerated or omitted. Origin, Referer, Content-Type, and ordinary imported headers are preserved. User-Agent is regenerated as request-minimizer/0.1.

The client disables environment proxies, follows no redirects, enforces the imported scheme/host/effective-port lock, and uses bounded timeouts and retries. This tool does not support every cURL feature and should reject unfamiliar input rather than guess.

Security guidance

• Treat session cookies like passwords; a saved session may permit account access.
• Never commit request.curl, .env, minimized credentials, request configuration, checkpoints, reports, or diagnostics from a real session.
• Never put cookie values in command-line arguments, chat, issue reports, or fixtures.
• Use only accounts and requests you own and control.
• Review safe-looking metadata before publishing it; cookie names and endpoint structure can still reveal operational details.
• Revoke or log out the session after the experiment when appropriate.
• Report suspected vulnerabilities privately as described in SECURITY.md.

Development and testing

Install development dependencies, then run:

pytest
ruff check .
ruff format --check .
mypy src
python -m build

Automated tests use synthetic credentials and fake transports; they never contact Alibaba. New behavior involving requests, validators, storage, or output should include regression coverage for failure paths and secret nondisclosure.

See CONTRIBUTING.md before submitting a change. Never attach a real copied request or generated local artifact to a bug report.

Responsible disclosure

Please do not open a public issue for a vulnerability that could expose credentials or unsafe request behavior. Use GitHub's private vulnerability reporting for this repository, or follow the private reporting instructions in SECURITY.md. Do not send working credentials as evidence.

License

Licensed under the MIT License. Copyright 2026 Brandon Werner.