@caupulican/pi-adaptative 0.81.41 → 0.81.43

package/dist/bundled-resources/runtimes/pi-shell-engine/tokens.py

@@ -13,24 +13,11 @@ import re
 from dataclasses import dataclass
 
 from errors import UnsupportedConstruct
+from escapes import ANSI_C_ESCAPES, decode_backslash_escapes
 from nodes import CmdSub, DQ, Lit, Param, Raw, Segment, Tilde, Word
 
 _IDENT_START_RE = re.compile(r"[A-Za-z_]")
 _IDENT_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
-_ANSI_C_MAP = {
-    "\\": "\\",
-    "a": "\a",
-    "b": "\b",
-    "c": "",  # \c stops output; treated as empty here (bounded, no truncation semantics)
-    "e": "\x1b",
-    "f": "\f",
-    "n": "\n",
-    "r": "\r",
-    "t": "\t",
-    "v": "\v",
-}
-
-
 @dataclass
 class Token:
     kind: str  # "WORD" | "OP"
@@ -45,94 +32,31 @@ def _unterminated(what: str) -> UnsupportedConstruct:
     return UnsupportedConstruct("malformed-syntax", f"Unterminated {what}: the command has an unbalanced quote or bracket.")
 
 
-def _ansi_c_unescape(text: str) -> str:
-    out: list[str] = []
-    i = 0
-    n = len(text)
-    while i < n:
-        c = text[i]
-        if c != "\\" or i + 1 >= n:
-            out.append(c)
-            i += 1
-            continue
-        nxt = text[i + 1]
-        if nxt in _ANSI_C_MAP:
-            out.append(_ANSI_C_MAP[nxt])
-            i += 2
-            continue
-        if nxt == "0":
-            j = i + 2
-            digits = ""
-            while j < n and len(digits) < 3 and text[j] in "01234567":
-                digits += text[j]
-                j += 1
-            out.append(chr(int(digits, 8)) if digits else "\0")
-            i = j
-            continue
-        if nxt == "x":
-            j = i + 2
-            digits = ""
-            while j < n and len(digits) < 2 and text[j] in "0123456789abcdefABCDEF":
-                digits += text[j]
-                j += 1
-            out.append(chr(int(digits, 16)) if digits else "x")
-            i = j
-            continue
-        out.append(nxt)
-        i += 2
-    return "".join(out)
-
-
 def _find_closing_paren(src: str, pos: int) -> int:
     """`pos` is the index right after the opening '('. Returns the index of the matching ')'."""
-    n = len(src)
-    depth = 1
-    i = pos
-    while i < n:
-        c = src[i]
-        if c == "\\" and i + 1 < n:
-            i += 2
-            continue
-        if c == "'":
-            j = src.find("'", i + 1)
-            if j == -1:
-                raise _unterminated("single quote")
-            i = j + 1
-            continue
-        if c == '"':
-            i = _skip_double_quote(src, i + 1)
-            continue
-        if c == "(":
-            depth += 1
-            i += 1
-            continue
-        if c == ")":
-            depth -= 1
-            if depth == 0:
-                return i
-            i += 1
-            continue
-        i += 1
-    raise _unterminated("'('")
+    return _find_closing_group(src, pos, "(", ")")
 
 
 def _skip_double_quote(src: str, pos: int) -> int:
     """`pos` is the index right after the opening '"'. Returns the index right after the closing '"'."""
-    n = len(src)
-    i = pos
-    while i < n:
-        c = src[i]
-        if c == "\\" and i + 1 < n:
-            i += 2
-            continue
-        if c == '"':
-            return i + 1
-        i += 1
-    raise _unterminated('double quote')
+    return _find_unescaped_character(src, pos, '"', "double quote") + 1
 
 
-def _find_closing_brace(src: str, pos: int) -> int:
-    """`pos` is the index right after the opening '{'. Returns the index of the matching '}'."""
+def _find_unescaped_character(src: str, pos: int, closing: str, description: str) -> int:
+    i = src.find(closing, pos)
+    while i != -1:
+        backslashes = 0
+        cursor = i - 1
+        while cursor >= pos and src[cursor] == "\\":
+            backslashes += 1
+            cursor -= 1
+        if backslashes % 2 == 0:
+            return i
+        i = src.find(closing, i + 1)
+    raise _unterminated(description)
+
+
+def _find_closing_group(src: str, pos: int, opening: str, closing: str) -> int:
     n = len(src)
     depth = 1
     i = pos
@@ -150,21 +74,105 @@ def _find_closing_brace(src: str, pos: int) -> int:
         if c == '"':
             i = _skip_double_quote(src, i + 1)
             continue
-        if src[i : i + 2] == "${":
+        if opening == "{" and src[i : i + 2] == "${":
             depth += 1
             i += 2
             continue
-        if src[i : i + 2] == "$(":
-            i = _find_closing_paren(src, i + 2) + 1
+        if opening == "{" and src[i : i + 2] == "$(":
+            i = _find_closing_group(src, i + 2, "(", ")") + 1
             continue
-        if c == "}":
+        if c == opening:
+            depth += 1
+            i += 1
+            continue
+        if c == closing:
             depth -= 1
             if depth == 0:
                 return i
             i += 1
             continue
         i += 1
-    raise _unterminated("'{'")
+    raise _unterminated(repr(opening))
+
+
+def _find_closing_brace(src: str, pos: int) -> int:
+    """`pos` is the index right after the opening '{'. Returns the index of the matching '}'."""
+    return _find_closing_group(src, pos, "{", "}")
+
+
+def _scan_ansi_c_quote(src: str, pos: int) -> tuple[Lit, int]:
+    j = pos + 2
+    raw_chars: list[str] = []
+    while j < len(src) and src[j] != "'":
+        if src[j] == "\\" and j + 1 < len(src):
+            raw_chars.extend((src[j], src[j + 1]))
+            j += 2
+        else:
+            raw_chars.append(src[j])
+            j += 1
+    if j >= len(src):
+        raise _unterminated("$'...' quote")
+    decoded, _ = decode_backslash_escapes("".join(raw_chars), ANSI_C_ESCAPES)
+    return Lit(text=decoded), j + 1
+
+
+def _flush_buffer(
+    segments: list[Segment], buf: list[str], literal_buffer: bool
+) -> None:
+    if not buf:
+        return
+    text = "".join(buf)
+    segments.append(Lit(text=text) if literal_buffer else Raw(text=text))
+    buf.clear()
+
+
+def _scan_or_append(
+    src: str,
+    pos: int,
+    segments: list[Segment],
+    buf: list[str],
+    *,
+    literal_buffer: bool,
+    unquoted: bool,
+) -> int:
+    c = src[pos]
+    if unquoted and c == "'":
+        close = src.find("'", pos + 1)
+        if close == -1:
+            raise _unterminated("single quote")
+        _flush_buffer(segments, buf, literal_buffer)
+        segments.append(Lit(text=src[pos + 1 : close]))
+        return close + 1
+    if unquoted and c == '"':
+        _flush_buffer(segments, buf, literal_buffer)
+        dq_segments, new_pos = _scan_dq_segments(src, pos + 1)
+        segments.append(DQ(segments=dq_segments))
+        return new_pos
+    if unquoted and c == "$" and src[pos + 1 : pos + 2] == "'":
+        segment, new_pos = _scan_ansi_c_quote(src, pos)
+        _flush_buffer(segments, buf, literal_buffer)
+        segments.append(segment)
+        return new_pos
+    if c == "$":
+        segment, new_pos = _scan_dollar_form(src, pos)
+        if isinstance(segment, Lit) and segment.text == "$" and new_pos == pos + 1:
+            buf.append("$")
+        else:
+            _flush_buffer(segments, buf, literal_buffer)
+            segments.append(segment)
+        return new_pos
+    if c != "`":
+        buf.append(c)
+        return pos + 1
+
+    j = pos + 1
+    while j < len(src) and src[j] != "`":
+        j += 2 if src[j] == "\\" and j + 1 < len(src) else 1
+    if j >= len(src):
+        raise _unterminated("backtick")
+    _flush_buffer(segments, buf, literal_buffer)
+    segments.append(CmdSub(src=src[pos + 1 : j]))
+    return j + 1
 
 
 def _scan_param_arg_word(text: str) -> Word:
@@ -180,79 +188,21 @@ def _scan_param_arg_word(text: str) -> Word:
     buf: list[str] = []
     i = 0
 
-    def flush() -> None:
-        if buf:
-            segments.append(Raw(text="".join(buf)))
-            buf.clear()
-
     while i < n:
         c = text[i]
         if c == "\\":
             if i + 1 < n:
-                flush()
+                _flush_buffer(segments, buf, False)
                 segments.append(Lit(text=text[i + 1]))
                 i += 2
             else:
                 buf.append(c)
                 i += 1
             continue
-        if c == "'":
-            j = text.find("'", i + 1)
-            if j == -1:
-                raise _unterminated("single quote")
-            flush()
-            segments.append(Lit(text=text[i + 1 : j]))
-            i = j + 1
-            continue
-        if c == '"':
-            flush()
-            dq_segments, newpos = _scan_dq_segments(text, i + 1)
-            segments.append(DQ(segments=dq_segments))
-            i = newpos
-            continue
-        if c == "$" and text[i + 1 : i + 2] == "'":
-            j = i + 2
-            raw_chars: list[str] = []
-            while j < n and text[j] != "'":
-                if text[j] == "\\" and j + 1 < n:
-                    raw_chars.append(text[j])
-                    raw_chars.append(text[j + 1])
-                    j += 2
-                else:
-                    raw_chars.append(text[j])
-                    j += 1
-            if j >= n:
-                raise _unterminated("$'...' quote")
-            flush()
-            segments.append(Lit(text=_ansi_c_unescape("".join(raw_chars))))
-            i = j + 1
-            continue
-        if c == "$":
-            seg, newpos = _scan_dollar_form(text, i)
-            if isinstance(seg, Lit) and seg.text == "$" and newpos == i + 1:
-                buf.append("$")
-                i = newpos
-                continue
-            flush()
-            segments.append(seg)
-            i = newpos
-            continue
-        if c == "`":
-            j = i + 1
-            while j < n and text[j] != "`":
-                if text[j] == "\\" and j + 1 < n:
-                    j += 2
-                else:
-                    j += 1
-            if j >= n:
-                raise _unterminated("backtick")
-            flush()
-            segments.append(CmdSub(src=text[i + 1 : j]))
-            i = j + 1
-            continue
-        buf.append(c)
-        i += 1
-    flush()
+        i = _scan_or_append(
+            text, i, segments, buf, literal_buffer=False, unquoted=True
+        )
+    _flush_buffer(segments, buf, False)
     return Word(segments=segments)
 
 
@@ -294,6 +244,8 @@ def _scan_dollar_form(src: str, pos: int) -> tuple[Segment, int]:
             )
         close = _find_closing_paren(src, pos + 2)
         return CmdSub(src=src[pos + 2 : close]), close + 1
+    if nxt == "?":
+        return Param(name="?", op=None, arg=None), pos + 2
     if nxt and (_IDENT_START_RE.match(nxt)):
         m = _IDENT_RE.match(src, pos + 1)
         assert m is not None
@@ -309,15 +261,10 @@ def _scan_dq_segments(src: str, pos: int) -> tuple[list[Segment], int]:
     buf: list[str] = []
     i = pos
 
-    def flush() -> None:
-        if buf:
-            segments.append(Lit(text="".join(buf)))
-            buf.clear()
-
     while i < n:
         c = src[i]
         if c == '"':
-            flush()
+            _flush_buffer(segments, buf, True)
             return segments, i + 1
         if c == "\\" and i + 1 < n:
             nxt = src[i + 1]
@@ -331,37 +278,18 @@ def _scan_dq_segments(src: str, pos: int) -> tuple[list[Segment], int]:
                 buf.append(nxt)
                 i += 2
             continue
-        if c == "$":
-            seg, newpos = _scan_dollar_form(src, i)
-            if isinstance(seg, Lit) and seg.text == "$" and newpos == i + 1:
-                buf.append("$")
-                i = newpos
-                continue
-            flush()
-            segments.append(seg)
-            i = newpos
-            continue
-        if c == "`":
-            j = i + 1
-            while j < n and src[j] != "`":
-                if src[j] == "\\" and j + 1 < n:
-                    j += 2
-                else:
-                    j += 1
-            if j >= n:
-                raise _unterminated("backtick")
-            flush()
-            segments.append(CmdSub(src=src[i + 1 : j]))
-            i = j + 1
-            continue
-        buf.append(c)
-        i += 1
+        i = _scan_or_append(
+            src, i, segments, buf, literal_buffer=True, unquoted=False
+        )
     raise _unterminated("double quote")
 
 
 _WORD_BOUNDARY_CHARS = set("|&;()<> \t\n")
 _EXTGLOB_PREFIX_CHARS = set("@!?*+")
-_DRIVE_PREFIX_RE = re.compile(r"^[A-Za-z]:")
+
+
+def _is_drive_path_prefix(buf: list[str]) -> bool:
+    return len(buf) >= 2 and len(buf[0]) == 1 and buf[0].isalpha() and buf[1] == ":"
 
 
 def _scan_word(src: str, pos: int) -> tuple[Word, int]:
@@ -370,11 +298,7 @@ def _scan_word(src: str, pos: int) -> tuple[Word, int]:
     buf: list[str] = []
     i = pos
     at_word_start = True
-
-    def flush() -> None:
-        if buf:
-            segments.append(Raw(text="".join(buf)))
-            buf.clear()
+    preserve_backslashes = False
 
     while i < n:
         c = src[i]
@@ -423,80 +347,28 @@ def _scan_word(src: str, pos: int) -> tuple[Word, int]:
             # drive-letter path ('C:\...') or a UNC path ('\\server\...') is preserved
             # literally rather than treated as a POSIX escape of the next character.
             # Mirrors the TS router's identical heuristic (shell-contract-router.ts).
-            buf_text = "".join(buf)
-            if _DRIVE_PREFIX_RE.match(buf_text) or buf_text.startswith("\\\\"):
+            if preserve_backslashes or _is_drive_path_prefix(buf):
+                preserve_backslashes = True
                 buf.append(c)
                 i += 1
                 continue
             if not buf and not segments and src[i + 1 : i + 2] == "\\":
                 buf.append("\\\\")
+                preserve_backslashes = True
                 i += 2
                 continue
             if i + 1 < n:
-                flush()
+                _flush_buffer(segments, buf, False)
                 segments.append(Lit(text=src[i + 1]))
                 i += 2
             else:
                 buf.append(c)
                 i += 1
             continue
-        if c == "'":
-            j = src.find("'", i + 1)
-            if j == -1:
-                raise _unterminated("single quote")
-            flush()
-            segments.append(Lit(text=src[i + 1 : j]))
-            i = j + 1
-            continue
-        if c == '"':
-            flush()
-            dq_segments, newpos = _scan_dq_segments(src, i + 1)
-            segments.append(DQ(segments=dq_segments))
-            i = newpos
-            continue
-        if c == "$" and src[i + 1 : i + 2] == "'":
-            j = i + 2
-            raw_chars: list[str] = []
-            while j < n and src[j] != "'":
-                if src[j] == "\\" and j + 1 < n:
-                    raw_chars.append(src[j])
-                    raw_chars.append(src[j + 1])
-                    j += 2
-                else:
-                    raw_chars.append(src[j])
-                    j += 1
-            if j >= n:
-                raise _unterminated("$'...' quote")
-            flush()
-            segments.append(Lit(text=_ansi_c_unescape("".join(raw_chars))))
-            i = j + 1
-            continue
-        if c == "$":
-            seg, newpos = _scan_dollar_form(src, i)
-            if isinstance(seg, Lit) and seg.text == "$" and newpos == i + 1:
-                buf.append("$")
-                i = newpos
-                continue
-            flush()
-            segments.append(seg)
-            i = newpos
-            continue
-        if c == "`":
-            j = i + 1
-            while j < n and src[j] != "`":
-                if src[j] == "\\" and j + 1 < n:
-                    j += 2
-                else:
-                    j += 1
-            if j >= n:
-                raise _unterminated("backtick")
-            flush()
-            segments.append(CmdSub(src=src[i + 1 : j]))
-            i = j + 1
-            continue
-        buf.append(c)
-        i += 1
-    flush()
+        i = _scan_or_append(
+            src, i, segments, buf, literal_buffer=False, unquoted=True
+        )
+    _flush_buffer(segments, buf, False)
     return Word(segments=segments), i
 
 

package/dist/bundled-resources/skills/authorized-web-security-audit/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: authorized-web-security-audit
+description: "Plan, execute, and verify defensive web-security assessments inside explicit authorization, target, technique, rate, credential, and data-handling boundaries. Use for approved web/API security reviews, scanner orchestration, vulnerability triage, false-positive reduction, authenticated test planning, or requests to turn scan candidates into reproducible regression evidence."
+---
+
+# Authorized Web Security Audit
+
+## How to use the skill
+
+Use this skill only for defensive assessment of systems the user owns or has
+explicit permission to test. It does not grant scanning authority.
+
+**Freedom Dial: High Freedom.** Selecting probes and interpreting evidence need
+judgment. Authorization, scope, stop conditions, resource budgets, credential
+handling, and evidence promotion are rigid gates.
+
+Choose one mode:
+
+- **Review**: inspect supplied code, configuration, logs, or reports without
+  sending traffic.
+- **Plan**: produce a scope manifest and test matrix without sending traffic.
+- **Lab**: test an intentionally vulnerable local fixture or user-provided lab.
+- **Active**: send bounded requests only when written authorization and the
+  complete scope manifest are present in the active request or trusted project
+  policy.
+
+Before any active work, read
+[references/assessment-contract.md](references/assessment-contract.md). Pair
+confirmed code defects with `evidence-gated-tdd`.
+
+## North Star
+
+Find security defects without becoming an uncontrolled attacker: every request
+must be attributable to one approved engagement, confined to its scope, bounded
+in impact, reproducible against a safe control, and converted into an owner-level
+regression rather than an unverified scanner claim.
+
+Think before acting, use the least invasive probe that can answer the question,
+make surgical changes, define observable success, and keep humans at the edge
+for credentials, destructive probes, external side effects, authority expansion,
+publication, and material risk acceptance.
+
+## Core Sections
+
+### 1. Establish authority and scope
+
+Create a scope manifest before network access. It must identify:
+
+- the approving owner and written authorization evidence;
+- exact hosts, schemes, ports, environments, accounts, and excluded assets;
+- allowed techniques and whether state-changing requests are permitted;
+- start/end window, maximum requests per second, concurrency, request timeout,
+  total tool timeout, and response/body limits;
+- credential source and handling rules without placing secrets in prompts,
+  reports, command lines, or logs;
+- data retention, evidence directory, cleanup, and emergency stop contact.
+
+Do not infer authorization from reachability, a public hostname, a prior scan,
+an `active_scan_accepted` boolean, a stored engagement, a tool description, or
+the model's assertion. Missing or ambiguous authority means Review or Plan mode.
+
+Resolve and validate every destination at the network boundary. Apply the same
+scope rules after redirects and DNS resolution. Reject userinfo URLs, alternate
+IP encodings, unexpected ports, redirect escapes, and private, loopback,
+link-local, multicast, or metadata destinations unless that exact range is in
+the manifest. Pin or revalidate resolution to prevent DNS rebinding and
+time-of-check/time-of-use changes.
+
+### 2. Progress from passive to active
+
+Use the smallest stage that can falsify the hypothesis:
+
+1. inspect source, configuration, schemas, routes, and supplied captures;
+2. map the approved surface with passive or read-only discovery;
+3. calibrate normal behavior with safe baseline requests;
+4. run one bounded candidate probe and one negative control;
+5. replay only after confirming the request remains in scope and idempotent;
+6. request explicit human approval before any destructive, state-changing,
+   high-volume, credential-changing, persistence, or exfiltration-style probe.
+
+Do not start with `all`, broad crawling, port sweeps, credential spraying, race
+loads, custom payload floods, or arbitrary external scanners. Treat scanner
+selection as executable authority, not a convenience option.
+
+### 3. Constrain the execution contract
+
+At the tool boundary:
+
+- use typed schemas, allowlists, canonical URL parsing, and validated builders;
+- separate read-only, mutation-capable, and destructive capabilities;
+- cap request count, rate, concurrency, redirects, body bytes, response bytes,
+  recursion/crawl depth, custom payload count/length, and elapsed time;
+- require cancellation and a terminal status for every tool;
+- move work exceeding the harness foreground budget into an owner-session
+  background task with event-driven completion and a bounded result handoff;
+- never pass caller text to a shell, template engine, query interpreter, or
+  deserializer without the owning adapter's structural validation;
+- never send authorization headers or cookies across an origin change.
+
+Timeout is not cancellation proof. Verify that child processes, sockets,
+browsers, temporary credentials, and background tasks are actually released.
+
+### 4. Verify findings before promotion
+
+Treat each detection as a hypothesis. Capture a sanitized request identity,
+response shape/hash, environment, tool version, timestamp, and raw-artifact
+pointer outside model context. Then require:
+
+- a deterministic reproduction;
+- a negative control or calibrated baseline;
+- a security invariant and authoritative owner;
+- evidence that the signal is not a catch-all page, static asset, cache effect,
+  generic server error, reflection already present in the baseline, or transient
+  latency;
+- confidence separate from impact severity.
+
+Do not promote response equality alone as proof of exploitability. For
+authorization defects, compare two deliberately separated identities and prove
+the forbidden resource or action. For timing findings, replay multiple bounded
+trials with controls. Blind findings without an independently correlated signal
+remain `needs_review`.
+
+### 5. Fix and report defensively
+
+Fix the lowest authoritative validation, authorization, parsing, or state owner.
+Add a focused regression and negative control before changing behavior. Remove
+the competing unsafe path once the mandatory path is proven.
+
+Reports must separate confirmed, rejected, incomplete, and residual findings.
+Redact secrets and sensitive bodies; store exact evidence in a protected bounded
+artifact and expose only a digest/pointer to the model. Include affected scope,
+reproduction preconditions, impact, owner, fix, tests, scanner errors, skipped
+probes, and cleanup status.
+
+### 6. Stop safely
+
+Stop immediately on scope escape, unexpected mutation, account lockout, service
+degradation, secret exposure, runaway traffic, missing cancellation, uncertain
+tenant identity, or owner revocation. Preserve bounded evidence, cancel owned
+work, emit a terminal status, and report what may still be running. Do not widen
+scope or increase intensity to overcome a blocker.
+
+## Anti-Patterns
+
+- Treating a checkbox or tool argument as authorization.
+- Sending probes before a scope manifest exists.
+- Following redirects or DNS changes without revalidation.
+- Replaying stored raw requests against a host chosen from untrusted evidence.
+- Logging cookies, authorization headers, payload bodies, or extracted secrets.
+- Calling a scanner finding confirmed from status code, latency, reflection, or
+  body similarity alone.
+- Raising rate, concurrency, timeout, or payload volume to force a result.
+- Loading raw captures or full reports into the model when a bounded index works.
+
+## Examples
+
+**Authorized API review:** record the exact staging host, two test identities,
+read-only object endpoints, 2 requests/second, concurrency 1, and a 15-minute
+window. Compare owner and non-owner requests plus a nonexistent-object control.
+Promote only a deterministic cross-identity disclosure.
+
+**Ambiguous request:** "scan this public site" has no written authorization or
+scope manifest. Stay in Plan mode and return the manifest fields needed to
+proceed; do not send traffic.
+
+**Catch-all route:** `/admin` and a random nonexistent path return the same SPA
+shell. Reject the candidate, retain the baseline evidence, and do not report an
+access-control defect.
+
+## Self-Check
+
+- Written authorization and the complete scope manifest are present for Active mode.
+- Every destination and redirect remains inside canonical approved scope.
+- Read-only and state-changing capabilities are separated.
+- Rate, concurrency, size, depth, timeout, cancellation, and cleanup are bounded.
+- Credentials and sensitive evidence never enter model-visible output or logs.
+- Every promoted finding has a deterministic reproduction and negative control.
+- Scanner omissions and tool errors remain visible.
+- Background work is owner-session scoped and event-driven.
+- The handoff separates confirmed, rejected, incomplete, and residual findings.
+
+## Known Gaps
+
+- This skill cannot establish legal authority; the operator must provide it.
+- Some blind vulnerabilities require an approved out-of-band correlation system.
+- Defensive guidance cannot prove the absence of vulnerabilities outside the
+  declared scope or tested techniques.