URL encoding bugs: calls से पहले agent API inputs को test करें

URL कोई harmless string नहीं है। यह एक structured instruction है, जिसमें delimiters host, route, parameter names और values तय करते हैं। अगर agent user की दी हुई text को URL के साथ गलत तरीके से जोड़ता है, तो वह developer द्वारा review किए गए endpoint के बजाय किसी दूसरे endpoint को call कर सकता है।

मैंने teams को ऐसा request approve करते देखा है जो tool transcript में GET /records/alice जैसा दिखता था। बाद में पता चला कि server को extra slash, duplicate query parameter या decoded traversal sequence वाला route मिला। Agent को किसी असाधारण exploit की ज़रूरत नहीं थी। a+b, %2F, &admin=true या किसी non-ASCII script में लिखा नाम जैसी सामान्य text ही पर्याप्त थी।

URL encoding bugs को अक्सर इसलिए नज़रअंदाज़ कर दिया जाता है क्योंकि HTTP client आम तौर पर «encoding संभाल लेता है»। वह अपनी API और defaults के अनुसार कुछ serialization संभालता है। लेकिन वह यह तय नहीं कर सकता कि user value path segment, query value, form body या कहीं भी नहीं जानी चाहिए। यह निर्णय action definition और उसके tests में होना चाहिए।

Call का फैसला visible string नहीं, request target करता है

Software जब URL को parse या फिर से बनाता है, तब हर चरण पर request का अर्थ बदल सकता है। Agent द्वारा बनाई गई character sequence केवल शुरुआत है। Client library उसे normalize कर सकती है, reverse proxy उसे rewrite कर सकता है और application framework route matching या parameter binding से पहले उसे decode कर सकता है।

RFC 3986 URI को scheme, authority, path, query और fragment में बाँटता है। Path के भीतर / delimiter है। Query में & और = आम conventions में अर्थ रखते हैं, भले ही RFC 3986 कोई universal query grammar तय नहीं करता। यही अंतर उन अधिकांश failures को समझाता है जिन्हें लोग लापरवाही से «encoding issues» कहते हैं।

मान लीजिए action का काम एक project लाना है:

GET https://api.example.test/projects/{project_id}

अगर project_id का मान north/ops है, तो ये दो request targets समान नहीं हैं:

/projects/north/ops
/projects/north%2Fops

पहले में projects के बाद दो path segments हैं। दूसरे में literal slash को एक segment के भीतर रखने की कोशिश की गई है। दूसरा रूप client से application तक के पूरे route पर निर्भर करता है। कुछ stacks matching से पहले %2F decode करके उसे पहले रूप में बदल देते हैं। कुछ उसे reject कर देते हैं। केवल «URL encoded था» assert करने वाला client test बहुत कम साबित करता है।

Queries में भी यही समस्या आती है। Literal phrase खोजने वाले action को raw text डालकर यह URL नहीं बनाना चाहिए:

/search?q=USER_TEXT

USER_TEXT को red&limit=500 से बदलने पर target यह बन सकता है:

/search?q=red&limit=500

अब application को दो query parameters दिखते हैं। अगर code query object बनाकर red&limit=500 को q की value देता है, तो उसे यह बनाना चाहिए:

/search?q=red%26limit%3D500

यही boundary test करनी है: semantic field अंदर जाए, exact request target निकले और destination पर वही semantic field parse हो।

केवल letters और numbers से test न करें। ऐसे values वही bugs छिपा देते हैं जिन्हें agents उजागर करते हैं। Agent support tickets, issue titles, branch names, file paths, copied URLs और prose प्राप्त करता है। Real input में delimiters होते हैं।

Path parameter एक segment है, अधूरा URL नहीं

Path parameter को single segment मानें, जब तक API contract साफ तौर पर यह न कहे कि वह पूरा path स्वीकार करता है। यह एक नियम काफी ambiguity दूर कर देता है।

Developers अक्सर paths को इस तरह जोड़ते हैं क्योंकि code पढ़ने में आसान लगता है:

const target = base + "/projects/" + projectId + "/builds";

इस code में projectId का component-specific अर्थ तय नहीं है। अगर value में /, ?, # या % हो, तो परिणाम इस बात पर निर्भर करेगा कि बाद का code target के साथ क्या करता है। इससे दूसरी गलती भी आम होती है: log में encoded value देखकर कोई «सुरक्षा के लिए» फिर से encodeURIComponent चला देता है और identifier बदल जाता है।

Segments को data की तरह बनाएँ, हर segment को एक बार encode करें और केवल route के अपने separators को जोड़ें। JavaScript में यह छोटा helper contract को स्पष्ट करता है:

function pathSegment(value) {
  if (typeof value !== "string" || value.length === 0) {
    throw new Error("project id must be a nonempty string");
  }
  return encodeURIComponent(value);
}

const path = "/projects/" + pathSegment(projectId) + "/builds";

यहाँ encodeURIComponent सही है क्योंकि यह /, ?, #, & और = को encode करता है, जो path बदल सकते हैं या query अथवा fragment शुरू कर सकते हैं। यह apostrophes और parentheses सहित RFC 3986 के कुछ छोटे set को unescaped छोड़ता है। आम तौर पर इससे path structure नहीं बदलता, लेकिन strict API contract को अधिक सख्त encoder की ज़रूरत हो सकती है। यह निर्णय API specification से लें, आदत से नहीं।

Single segment के लिए encodeURI इस्तेमाल न करें। यह URI delimiters को बचाए रखता है क्योंकि इसे complete URI के लिए बनाया गया है। north/ops को इससे गुजारने पर slash बचा रहेगा और route बदल जाएगा। Function का नाम सही लगता है, लेकिन उसका scope यहाँ गलत है।

किसी path में सचमुच कई segments हो सकते हैं, जैसे /{owner}/{repository}। इसे एक free-form resourcePath string के बजाय दो fields की तरह model करें। अगर endpoint को ऐसे opaque identifier की ज़रूरत है जिसमें slash आ सकते हैं, तो उसे query parameter या JSON request body में रखने पर विचार करें।

Client encoding routing का हर निर्णय ठीक नहीं कर सकता। कई proxies और frameworks . तथा .. जैसे dot segments को normalize करते हैं, repeated slashes को collapse करते हैं या encoded separators reject करते हैं। Endpoint owner से सीधे पूछें: route matching percent decoding से पहले होती है या बाद में? Deployed route और उसके proxy के विरुद्ध test करें। अकेले developer machine पर चल रहे framework का documentation इस सवाल का उत्तर नहीं देता।

Query strings के लिए घोषित grammar चाहिए

Query string एक escaped blob नहीं है। यह fields का collection है और उसकी grammar API तय करती है। Agent को endpoint सुरक्षित रूप से call कराने से पहले repeated names, empty values, arrays, booleans, spaces और duplicate handling पर निर्णय लें।

WHATWG URL Standard और browser-oriented URLSearchParams APIs form-style query serialization इस्तेमाल करते हैं। इस convention में space अक्सर + बन जाता है और literal plus %2B। कई server parsers भी यही convention अपनाते हैं। RFC 3986 खुद generic URI में + को space नहीं कहता। जब एक component generic parser और दूसरा form parser इस्तेमाल करे, तो दोनों तथ्य महत्वपूर्ण हैं।

String templates के बजाय query builder इस्तेमाल करें:

const query = new URLSearchParams();
query.set("q", userText);
query.set("include_archived", "false");
for (const label of labels) query.append("label", label);

const url = "https://api.example.test/search?" + query.toString();

userText = "C++ & systems" के लिए exact spelling q=C%2B%2B+%26+systems हो सकती है। Form decoding करने वाला server C++ & systems वापस पाएगा। Regression test को API की semantic value पर आधारित होना चाहिए, हर library से %20 की अपेक्षा नहीं करनी चाहिए। Query conventions में %20 और + दोनों space दर्शा सकते हैं, लेकिन parsing के बाद literal plus literal ही रहना चाहिए।

Repeated fields के बारे में स्पष्ट निर्णय लें:

?label=bug&label=security
?label=bug,security
?label=["bug","security"]

पहला repeated name है। दूसरा comma वाली एक value है, जब तक API कुछ और न कहे। तीसरा JSON जैसा दिखने वाला string है, JSON नहीं, जब तक server जानबूझकर उसे parse न करे। Agent से «labels URL में भेजो» कहना पर्याप्त नहीं है। Action को array argument दें और उसे endpoint द्वारा स्वीकार किए जाने वाले एक तय रूप में serialize करें।

Duplicate scalar parameters भी शांत failure पैदा करते हैं। ?role=user&role=admin पर framework के अनुसार पहला मान, आखिरी मान, array या error मिल सकता है। अगर security check पहला मान पढ़े और downstream service आखिरी, तो निर्णय अलग हो सकता है। जिन fields की एक ही occurrence होनी चाहिए, उनके duplicates को अपने नियंत्रण वाले सबसे शुरुआती component पर reject करें।

Fragments भी debugging को भ्रमित करते हैं। #section सामान्यतः HTTP request के हिस्से के रूप में client से बाहर नहीं जाता। Raw user input में # आने पर URL object request भेजने से पहले उसके बाद का भाग हटा सकता है। अगर वह data है, तो उसे path या query value के भीतर encode करें। Source string का log server तक पहुँची चीज़ नहीं बताता।

Percent signs और decode order अलग identifiers बना सकते हैं

Percent escapes को एक तय boundary पर एक ही बार decode करें। अगर दो components एक ही input decode करें, तो पहली जाँच पास कर चुका inert-looking value दूसरे चरण में delimiter बन सकता है।

%252F पर एक percent decode %2F देता है। दूसरा decode / देता है। Validation इन दोनों operations के बीच हो तो समस्या पैदा होती है। Gateway raw / को identifier में reject और %252F को allow कर सकता है, फिर upstream application दोबारा decode करके route बाँट सकती है। यही pattern %252e के %2e और फिर . बनने पर भी लागू होता है।

Design और tests में इन तीन values को अलग रखें:

1. Raw wire spelling, जैसे %252F।
2. एक percent decode के बाद की value, जैसे %2F।
3. हर parser और rewrite के बाद application value, जैसे /।

Teams अक्सर इन तीनों को «URL» कह देती हैं। यह अस्पष्ट भाषा खराब reviews कराती है, क्योंकि लोग अलग stages की तुलना करते हैं और अंतर देखते नहीं।

RFC 3986 URI producers को एक ही string को एक से अधिक बार encode या decode न करने की सलाह देता है। यह सही सलाह है, लेकिन implementation plan नहीं। तय करें कि action serializer decoded application strings स्वीकार करेगा और server raw request bytes कहाँ स्वीकार करेगा। इन boundaries के बीच escaping preserve करें या उन forms को reject करें जिन्हें preserve नहीं कर सकते।

Convenience के लिए पहले से encoded input स्वीकार न करें। Agent prompt में «URL-encoded project ID दो» कहना model से यह अनुमान लगवाता है कि %2F data है या instruction। अगली layer नहीं जान सकती कि percent sign बचाना है या उसे %25 में encode करना है। Plain text fields स्वीकार करें, action layer में एक बार encode करें और malformed percent escapes को वहीं reject करें जहाँ raw URLs सचमुच स्वीकार किए जाते हैं।

Unicode भी एक boundary जोड़ता है। URL client आम तौर पर text को UTF-8 bytes में बदलकर चुने गए component में सीधे न आ सकने वाले bytes को percent encode करता है। Server frameworks user या resource lookup से पहले Unicode को अलग तरह normalize कर सकते हैं। यदि आपके domain को canonical form चाहिए, तो identifiers को application layer पर canonical रूप में रखें। URL escaping से Unicode identity हल नहीं होती। Escaping bytes को transport करता है, यह तय नहीं करता कि देखने में समान दो strings एक ही account का नाम हैं या नहीं।

सामान्य लेकिन adversarial inputs से पूरे route को test करें

अच्छे encoding test में दो observations होते हैं: client ने कौन-सा request target निकाला और receiver ने कौन-सी values parse कीं। केवल एक side test करने पर proxy rewrite या framework decoder बीच में अर्थ बदल सकता है।

अपने test environment में controlled echo handler से शुरुआत करें। जहाँ server runtime raw request target देता हो, वहाँ उसे record करें और parsed path तथा query fields वापस करें। इस endpoint में credentials न रखें। इसका काम serialization दिखाना है, authentication नहीं।

यह छोटा Node handler response shape दिखाता है:

import http from "node:http";

http.createServer((req, res) => {
  const url = new URL(req.url, "http://local.test");
  const pairs = [...url.searchParams.entries()];
  res.setHeader("content-type", "application/json");
  res.end(JSON.stringify({
    requestTarget: req.url,
    pathname: url.pathname,
    queryPairs: pairs
  }, null, 2));
}).listen(8787);

Known cases भेजें और expected output सुरक्षित रखें। उदाहरण के लिए, C++ & systems पाने वाला query builder ऐसा output दे जिसमें एक q pair हो और parsed value ठीक C++ & systems हो। Hand-built query अक्सर दो pairs लौटाकर या plus signs को spaces में बदलकर अपनी गलती दिखाती है।

{
  "requestTarget": "/search?q=C%2B%2B+%26+systems",
  "pathname": "/search",
  "queryPairs": [["q", "C++ & systems"]]
}

Suite में random strings की दर्जनों सूची के बजाय compact matrix रखें:

• Space, literal plus, percent sign, ampersand, equals sign, question mark और hash।
• Single segment के लिए बने identifier के भीतर slash और encoded slash।
• Empty strings, missing optional fields और repeated query names।
• Unicode value और ऐसी value जिसके percent escapes दूसरे decoding pass जैसे दिखें।
• Identifier वाले field में paste किया गया पूरा URL।

अगर team property-based tests पहले से इस्तेमाल करती है तो उनका उपयोग करें, लेकिन named cases को generated examples के पीछे न छिपाएँ। ये cases बताते हैं कि boundary क्यों मौजूद है। Regression में encoded slash stays inside project_id किसी seed number से अधिक उपयोगी है।

Production traffic वाले पूरे path से वही integration tests चलाएँ। Application process के direct test से पता नहीं चलेगा कि proxy %2F reject करता है, duplicate slashes rewrite करता है या duplicate query value चुनता है। Local tests में production edge शामिल न हो सके तो समान configuration वाले staging route पर test चलाएँ और उसे release check बनाएं।

Agents को structured arguments दें, URL बनाने की स्वतंत्रता नहीं

Agent को action चुनना और typed arguments देना चाहिए। Action implementation HTTP method, allowed origin, route template, query grammar, headers और encoding चुने। Agent को complete URL देने देना इन सभी controls को एक अस्पष्ट string में मिला देता है।

एक narrow action contract ऐसा हो सकता है:

{
  "name": "get_project_builds",
  "input": {
    "project_id": "north/ops",
    "branch": "release+candidate",
    "limit": 25
  }
}

Action code को project_id को identifier की तरह validate करना चाहिए, उसे single path segment के रूप में encode करना चाहिए, branch को query builder में रखना चाहिए, limit को API की allowed range में integer के रूप में validate करना चाहिए और fixed origin से URL बनाना चाहिए। Model को bearer token देखने या ampersand की जगह तय करने की ज़रूरत नहीं होनी चाहिए।

यह separation origin confusion भी रोकता है। https://other.example से शुरू होने वाली string का identifier field में कोई स्थान नहीं है। अगर action को सचमुच user-supplied URL fetch करना है, तो उसे अलग action बनाएं जिसमें written allowlist, DNS और redirect behavior तथा स्पष्ट उद्देश्य हो। Arbitrary fetch capability को callback या file नाम वाले field से छिपाकर न दें।

Query parameters में filter languages स्वीकार करने वाले APIs के साथ सावधान रहें। filter=status:open AND owner:me जैसे field में दो grammars होती हैं: URL query serialization और filter language। URL encoding filter को एक query value में रखता है, लेकिन filter को safe नहीं बनाता। Inner language को अलग parse या constrain करें, अथवा typed filter fields दें।

Secrets को URLs में न रखें। Query strings access logs, कुछ contexts में browser history, telemetry और error reports में पहुँचती हैं। Credentials API के अपेक्षित authorization mechanism में रहने चाहिए। API token को encode करने से query में रखना सुरक्षित नहीं हो जाता।

Approval उपयोगी है, लेकिन malformed request ठीक नहीं कर सकता

Human authorization और सही serialization अलग समस्याएँ हल करते हैं। Approval यह पुष्टि कर सकता है कि पहचानी हुई agent process credential इस्तेमाल कर सकती है। वह यह नहीं बता सकता कि percent sequence downstream router पर slash बनेगा या duplicate parameter parsing के बाद privilege बदलेगा।

जब कोई कहे कि prompts या approval cards strict request construction को अनावश्यक बनाते हैं, तो इस अंतर को याद रखें। https://api.example.test/projects/%252Fadmin review करने वाले व्यक्ति को पूरे route के हर decoder का मानसिक simulation करना पड़ेगा। यह उचित security control नहीं है, खासकर तब जब agent एक session में कई calls कर सकता हो।

Approval surface तक पहुँचने से पहले deterministic checks रखें:

• Preassembled request target के बजाय structured fields स्वीकार करें।
• Origin, method और route template action definition में fix करें।
• हर path segment और query value को एक बार serialize करें।
• ऐसे duplicate या malformed fields reject करें जिन्हें endpoint define नहीं करता।
• Deployed request path से final target test करें।

Sallyport credentials को MCP-capable agent से बाहर रख सकता है और agent process या selected credential के हर उपयोग के लिए authorization मांग सकता है। यह human control तब सबसे अच्छा काम करता है जब action layer पहले ही एक unambiguous request बना चुकी हो।

Logs में दोनों स्तरों का detail रखें। Approved action और उसके safe arguments record करें, फिर actual request target और HTTP result का redacted representation रखें। Sensitive query field हो तो उसकी value redact करें, लेकिन parameter name और accidental duplication पहचानने लायक structure रखें। Request failure होने पर authorization headers कभी log न करें।

Route normalization सही client को भी विफल कर सकती है

Client का perfectly serialized request infrastructure boundaries पर फिर भी बदल सकता है। Proxies, load balancers, web application firewalls और application servers duplicate slashes, dot segments, encoded separators और invalid escapes के बारे में अलग व्यवहार रखते हैं। पूरे chain के लिए route contract चाहिए।

मान लें client यह path भेजता है:

/files/reports%2F2025%2Fnotes

अगर API को एक opaque file ID चाहिए, तो desired application parameter reports/2025/notes है। लेकिन forwarding से पहले decode करने वाला proxy /files/reports/2025/notes भेज सकता है। /files/:id वाला router इसे reject कर सकता है। दूसरा router /files/:folder/:year/:name match करके अलग handler चला सकता है। इससे यह सिद्ध नहीं होता कि client encoder विफल था।

हर sensitive route के लिए निर्णय लें। Edge पर encoded slashes reject करके document करें कि IDs में slash नहीं हो सकते। या उन्हें handler तक पूरी तरह preserve करें और इस property को test करें। या endpoint redesign करके opaque data को path से बाहर रखें। Behavior को version-specific defaults पर छोड़कर उसे security boundary न कहें।

Redirects पर भी ध्यान दें। HTTP clients redirects अपने-आप follow कर सकते हैं और redirected URL का path या query अलग तरह normalize हो सकता है। Credentials वाले actions के लिए तय करें कि redirects allowed हैं या नहीं, destination origin का match ज़रूरी है या नहीं और origin बदलने पर authorization headers हटेंगे या नहीं। यह percent encoding से अलग विषय है, लेकिन दोनों अक्सर उसी request code में मिलते हैं।

अगर कई services चलाते हैं, तो disagreement को जानबूझकर test करें। Nonproduction environment में वही encoded path edge और application तक सीधे भेजें। Parsed path values अलग हों तो agent को route access देने से पहले ठीक करें। Split parser operational problem है, भले attacker कभी उसे न छुए।

Regression suite को intended meaning सुरक्षित रखना चाहिए

URL tests का उद्देश्य किसी एक escaping spelling को थोपना नहीं है। उद्देश्य action arguments और request के server-side meaning के बीच संबंध को सुरक्षित रखना है, ताकि libraries और infrastructure बदलने पर भी अर्थ न बदले।

Assertions तीन layers पर लिखें। Unit tests देखें कि path segment encoder a/b को single encoded segment बनाता है और query serialization value के भीतर & बचाती है। Action tests exact method, origin, path और echo handler को भेजे गए query pairs capture करें। Integration tests production-जैसे edge से चलाकर देखें कि handler को expected route और parameters मिले।

API contract अस्पष्ट हो तो ambiguity लिखें और हटाएँ। «URL में search text support करता है» contract नहीं है। बताएँ कि empty q स्वीकार है या नहीं, q=a+b plus है या space, repeated tag allowed हैं या नहीं और IDs में %2F मान्य है या नहीं। Agent को arbitrary human text से calls बनाने देने के बाद ये details incidental नहीं रहतीं।

Failing test को input पहले decode करके छिपाएँ नहीं। Earlier decoding case को सामान्य दिखा सकती है, लेकिन ambiguity को कम दिखाई देने वाली layer में भेज देती है। Raw user text को component-specific serializer तक data की तरह रखें। फिर देखें कि receiver ने वास्तव में क्या parse किया।

Sallyport का Activity journal agent के approved call और लौटे परिणाम की तुलना आसान बना सकता है, जबकि उसकी audit chain को sp audit verify से offline verify किया जा सकता है। Mismatch की जाँच के लिए उस trail का उपयोग करें, endpoint क्या स्वीकार करता है यह तय करने के विकल्प के रूप में नहीं।

मैं सबसे पहले एक बेहद साधारण test जोड़ूँगा: / वाला identifier, + और & वाली query value और ऐसा percent sign जिसे literal रहना है। अगर आपका action इन inputs के लिए ठीक-ठीक नहीं बता सकता कि server को क्या मिलेगा, तो वह agent से user-supplied text लेने के लिए तैयार नहीं है।