@passioncode-ai/fabric-agent-adapter 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.17.0 - 2026-10-12
+
+The organisation's lifecycle rules LC-19 and LC-21 apply to what the adapter ships and checks (FAA-22, FAA-23):
+no plugin starts a stdio MCP server in every session, and no credential travels in argv or a URL query.
+
+### Added
+
+- **`adapt_project.py check`** refuses:
+  - **LC-19:** a Claude Code plugin in the project that declares a stdio MCP server, whether in its `.mcp.json` or in
+    `plugin.json` `mcpServers`, because it starts in every session that enables the plugin. An HTTP entry to a
+    resident service passes.
+  - **LC-21:** a launch argument or a URL that carries a credential, in the manifest's connections and in the plugin
+    servers' argv, URL and env.
+
+  `scaffold` refuses a runtime argument that carries a credential.
+- **`fabric_provider.py`** refuses a credential in `run.mcp.stdio.command` (LC-21, FAC-SEM-057). The key goes in
+  `env` as a secret reference.
+- **`test/validate.py` gate:** the adapter's own plugin declares no MCP server and no hook command carries a
+  credential.
+- The detector is the contract's (`fabric_secrets`, 0.16.0). The adapting skill carries an identical copy, so it
+  works installed alone, and a test keeps the two copies byte-identical.
+- Docs: the adapting skill's check step, `provider-entry.md`, and `surfaces-and-auth.md` (an HTTP registration
+  starts nothing per session). The scenario eval `plugin-and-argv-hygiene` came first. Five planted defects were
+  each caught.
+
 ## 0.16.0 - 2026-10-12
 
 Runner and model profiles in both kits (contract DEC-0046, Fabric ADR-0147; FAA-19). The contract's credential

package/README.md

@@ -230,8 +230,8 @@ FABRIC_CONTRACT_OLD=/path/to/legacy-contract FABRIC_CONTRACT_NEW=/path/to/curren
 ```
 
 Without both environment variables, those tests explicitly skip as `NOT_RUN`.
-This source checkout is 0.16.0. 0.15.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
-were never released); 0.16.0 is published by its `v0.16.0` tag. Source delivery does not update installed skills or live sessions.
+This source checkout is 0.17.0. 0.16.0 is the latest published GitHub/npm release (2026-10-12; 0.7.0 and 0.11.0
+were never released); 0.17.0 is published by its `v0.17.0` tag. Source delivery does not update installed skills or live sessions.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@passioncode-ai/fabric-agent-adapter",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Create Fabric-compatible agents, run them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract. This package is the installer CLI.",
   "scripts": {
     "test": "python3 test/validate.py && python3 -m unittest discover -s test -q && node --test 'test/*.test.mjs'"

package/plugins/fabric-agent-adapter/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "fabric-agent-adapter",
   "displayName": "Fabric Agent Adapter",
   "description": "Create new Fabric-compatible agents, build them as always-alive local services with dashboards (fabric-service/0.1), and adapt existing projects to the Fabric Agent Contract through evidence-backed MCP, A2A, or local-runner provider bundles.",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "author": {
     "name": "PassionCode.ai",
     "url": "https://passioncode.ai/"

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode.
 metadata:
   author: PassionCode.ai
-  version: "0.16.0"
+  version: "0.17.0"
   contract-version: "0.1.0"
   contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
 ---
@@ -173,6 +173,12 @@ python3 <skill-dir>/scripts/adapt_project.py check <project-root> \
   --contract /path/to/fabric-agent-contract --json
 ```
 
+The local check also refuses two lifecycle faults (LC-19, LC-21): a Claude Code plugin in
+the project that declares a stdio MCP server — it starts in every session that enables the
+plugin; serve it over HTTP from one resident process or register it at project scope — and a
+credential in a launch argument or a URL query, where every process and every log can read it.
+Fix both at their cause; never weaken the check.
+
 Load [verification](references/verification.md) before interpreting or publishing the
 result. Fix every local error. Fix every placeholder warning or record why the bundle is
 still a draft. Do not convert `NOT_RUN` or `NOT_VERIFIED` to `PASS` without the named

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/references/provider-entry.md

@@ -35,7 +35,8 @@ python3 scripts/fabric_provider.py remove example-agent      # the uninstaller
 `--stdio` takes the rest of the line as the argument array; there is no shell string. An entry may carry
 `run.mcp.stdio.scope` (DEC-0044): `project` (started for the sessions of a project that binds it) or `on-demand`;
 `session` — a server in every coding session — is refused (FAC-SEM-056, LC-19). The validator accepts the field; the
-writer does not set it until Fabric reads it.
+writer does not set it until Fabric reads it. An argument that carries a credential is refused
+(LC-21, FAC-SEM-057): a key goes in `env` as a `secret-ref:<name>`, never in argv.
 
 It refuses, with one sentence that never quotes a value:
 

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/adapt_project.py

@@ -15,6 +15,9 @@ import sys
 from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple
 from urllib.parse import urlparse
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import fabric_secrets as _secrets  # noqa: E402 - the contract's credential detector (DEC-0044, LC-21), beside this file
+
 
 CONTRACT_VERSION = "0.1.0"
 CONTRACT_REPOSITORY = "https://github.com/passioncode-ai/fabric-agent-contract"
@@ -230,6 +233,8 @@ def _generated_files(args: argparse.Namespace) -> Dict[str, str]:
         lowered = runtime_arg.lower().replace("_", "").replace("-", "")
         if any(term in lowered for term in ("password", "apikey", "accesstoken", "clientsecret")):
             raise AdaptationError("runtime arguments must not contain secret-like values or names")
+        if _secrets.secret_argument(runtime_arg):
+            raise AdaptationError("a runtime argument carries a credential; argv is visible to every process (LC-21): read it from a secret reference instead")
 
     created_at = dt.datetime.now(dt.timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
     manifest = {
@@ -465,6 +470,58 @@ import {SCHEMA_PREFIX} from './src/contract.ts';
     return "PASS", ["manifest validated by selected contract schema at %s" % selected_commit]
 
 
+def _credential_problems(manifest: Dict[str, Any]) -> List[str]:
+    """LC-21 (FAA-23): no credential in a launch argument or in a URL the manifest names."""
+    problems: List[str] = []
+    for index, capability in enumerate(manifest.get("capabilities") or []):
+        connection = ((capability or {}).get("profile") or {}).get("connection") if isinstance(capability, dict) else None
+        if not isinstance(connection, dict):
+            continue
+        for arg in connection.get("args") or []:
+            if isinstance(arg, str) and _secrets.secret_argument(arg):
+                problems.append("LC-21: capability[%d] passes a credential in a launch argument; argv is visible to every process" % index)
+        for field in ("url", "agentCardUrl"):
+            if isinstance(connection.get(field), str) and _secrets.secret_url(connection[field]):
+                problems.append("LC-21: capability[%d].%s carries a credential in the URL; a query lands in every log" % (index, field))
+    return problems
+
+
+_PLUGIN_SKIP = {".git", "node_modules", ".venv", "venv", "__pycache__", "dist", "build", ".worktrees"}
+
+
+def _plugin_problems(root: Path) -> List[str]:
+    """LC-19 (FAA-22) and LC-21 for the Claude Code plugins in the project: a plugin's stdio MCP server starts in
+    every session that enables the plugin; serve it over HTTP from one resident process, or register it at project
+    scope instead. No server entry carries a credential in its argv, URL or env."""
+    problems: List[str] = []
+    for top, dirs, files in os.walk(root):
+        dirs[:] = [d for d in dirs if d not in _PLUGIN_SKIP]
+        here = Path(top)
+        if here.name != ".claude-plugin" or "plugin.json" not in files:
+            continue
+        plugin = here.parent
+        name = plugin.relative_to(root).as_posix() or "."
+        servers: Dict[str, Any] = {}
+        for source in (here / "plugin.json", plugin / ".mcp.json"):
+            try:
+                doc = json.loads(source.read_text(encoding="utf-8")) if source.is_file() else {}
+            except (OSError, ValueError):
+                continue
+            block = doc.get("mcpServers") if isinstance(doc, dict) else None
+            if isinstance(block, dict):
+                servers.update({k: v for k, v in block.items() if isinstance(v, dict)})
+        for server, entry in sorted(servers.items()):
+            if "command" in entry:
+                problems.append("LC-19: plugin %s declares the stdio MCP server %s, which starts in every session that enables the plugin; serve it over HTTP from one resident process or register it at project scope" % (name, server))
+            argv = [entry.get("command")] + list(entry.get("args") or [])
+            if any(isinstance(a, str) and _secrets.secret_argument(a) for a in argv) or (isinstance(entry.get("url"), str) and _secrets.secret_url(entry["url"])):
+                problems.append("LC-21: plugin %s's MCP server %s carries a credential in its argv or URL" % (name, server))
+            env = entry.get("env") if isinstance(entry.get("env"), dict) else {}
+            if any(isinstance(v, str) and _secrets.secret_value(v) for v in env.values()):
+                problems.append("LC-21: plugin %s's MCP server %s writes a credential value in env; reference it instead" % (name, server))
+    return problems
+
+
 def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
     errors: List[str] = []
     warnings: List[str] = []
@@ -534,6 +591,7 @@ def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
                 errors.append("secret-like field is forbidden in manifest: %s" % key)
             if isinstance(value, str) and ("replace-me" in value or ".invalid" in value):
                 warnings.append("placeholder:%s" % key)
+        errors.extend(_credential_problems(manifest))
         provider = manifest.get("provider")
         if isinstance(provider, dict) and provider.get("contentHash") == "sha256:" + ("0" * 64):
             warnings.append("placeholder:provider.contentHash")
@@ -545,6 +603,7 @@ def check_project(root: Path, contract: Optional[Path]) -> Dict[str, Any]:
     elif contract is not None and manifest_path.is_file():
         shape_status, shape_receipts = _contract_shape(manifest_path, contract, lock["commit"])
 
+    errors.extend(_plugin_problems(root))
     local_status = "PASS" if not errors else "FAIL"
     ready = local_status == "PASS" and shape_status == "PASS" and not warnings
     return {

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/fabric_provider.py

@@ -29,6 +29,9 @@ import sys
 import tempfile
 from typing import Any, Dict, List, Optional
 
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+import fabric_secrets as _secrets  # noqa: E402 - the contract's credential detector (DEC-0044, LC-21), beside this file
+
 PROTOCOL = "fabric-provider/0.1"
 _ID = re.compile(r"^[a-z][a-z0-9-]{1,62}$")
 _ENV_NAME = re.compile(r"^[A-Z_][A-Z0-9_]*$")
@@ -124,6 +127,8 @@ def _run_problems(run: Any) -> List[str]:
     command = stdio["command"]
     if not isinstance(command, list) or not 1 <= len(command) <= 32 or not all(isinstance(a, str) and a for a in command):
         problems.append("run.mcp.stdio.command is an argument array, never a shell string")
+    elif any(_secrets.secret_argument(a) for a in command):
+        problems.append("run.mcp.stdio.command carries a credential in an argument; argv is visible to every process (LC-21, FAC-SEM-057): pass it as a secret reference in env")
     env = stdio.get("env", {})
     if not isinstance(env, dict):
         return problems + ["run.mcp.stdio.env is an object"]

package/plugins/fabric-agent-adapter/skills/adapting-projects-to-fabric/scripts/fabric_secrets.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""The contract's one credential detector (Fabric Agent Contract DEC-0044, `src/secret-shape.ts` at the pin): a name
+that can only carry a credential, a value shaped like one, a launch argument that carries one, and a URL that does
+(LC-21). A port held to the contract's own answers by test/fixtures/contract/profile-vectors.json. Standard library
+only. The dashboard kit's fabric-button.js carries its own copy of the name and value checks (FL-4)."""
+
+from __future__ import annotations
+
+import re
+from typing import Dict, List
+import urllib.parse
+
+CREDENTIAL_WORDS = (
+    "token", "secret", "password", "passwd", "pass", "passphrase", "credential", "credentials", "cookie", "authorization",
+    "bearer", "jwt", "otp", "apikey", "signature", "sig",
+    "accesstoken", "idtoken", "authtoken", "refreshtoken", "sessionid", "sessiontoken", "logincode", "authcode", "privatekey",
+    "clientsecret", "secretkey", "accesskey",
+)
+CREDENTIAL_PAIRS: Dict[str, tuple] = {
+    "key": ("private", "api", "access", "secret", "session", "auth", "signing", "encryption", "master", "client", "login", "refresh"),
+    "auth": ("token", "code", "header"),
+    "session": ("token", "id"),
+    "code": ("login", "auth", "access", "session"),
+}
+JWT_SHAPE = re.compile(r"eyJ[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]{2,}\.[A-Za-z0-9_-]*")
+SECRET_VALUE = re.compile(r"(^bearer\s.+|sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|xox[abposr]-[A-Za-z0-9-]{10,}|AKIA[0-9A-Z]{16}|glpat-[A-Za-z0-9_-]{20,})",
+                          re.IGNORECASE | re.DOTALL)
+_LONG_RUN = re.compile(r"[A-Za-z0-9+/=_-]{40,}")
+_BEARER_INSIDE = re.compile(r"\bbearer\s+(?=[A-Za-z0-9._~+/-]*\d)[A-Za-z0-9._~+/-]{12,}=*", re.IGNORECASE)
+_PATH_LIKE = re.compile(r"^(?:[/~.]|[A-Za-z]:[\\/]|[a-z][a-z0-9+.-]*://)", re.IGNORECASE)
+_SCHEME = re.compile(r"^[A-Za-z][A-Za-z0-9+.-]*:")
+
+
+def name_words(name: str) -> List[str]:
+    """A name's words: split at `.`, `_`, `-` and camelCase humps, lowercased (`APIKey` is `api key`)."""
+    spaced = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", name)
+    spaced = re.sub(r"([A-Z]+)([A-Z][a-z])", r"\1 \2", spaced)
+    return [w.lower() for w in re.split(r"[\s._-]+", spaced) if w]
+
+
+def _with_singulars(words: List[str]) -> List[str]:
+    return words + [w[:-1] for w in words if len(w) > 2 and w.endswith("s")]
+
+
+def credential_name(name: str) -> bool:
+    """Whether a name — a parameter, a header, an environment variable, a config key — can only carry a credential."""
+    split = name_words(name)
+    words = _with_singulars(split)
+    if any(w in CREDENTIAL_WORDS for w in words):
+        return True
+    if len(split) == 1 and any(w in CREDENTIAL_PAIRS for w in words):
+        return True
+    return any(word in words and any(p in words for p in partners) for word, partners in CREDENTIAL_PAIRS.items())
+
+
+def _long_secret(value: str) -> bool:
+    return any(re.search(r"[a-z]", run) and re.search(r"[A-Z]", run) and re.search(r"[0-9]", run) for run in _LONG_RUN.findall(value))
+
+
+def secret_value(value: str) -> bool:
+    """A JWT anywhere, a provider key or `Bearer …`, or a long base64 run mixing upper case, lower case and digits."""
+    return bool(JWT_SHAPE.search(value) or SECRET_VALUE.search(value) or _long_secret(value))
+
+
+def _path_like(piece: str) -> bool:
+    return bool(_PATH_LIKE.match(piece)) or (
+        bool(re.search(r"[\\/]", piece))
+        and (bool(re.search(r"\.[A-Za-z0-9]{1,8}$", piece)) or any(re.fullmatch(r"[a-z][a-z0-9_-]{2,}", s) for s in re.split(r"[\\/]", piece))))
+
+
+def secret_argument(value: str) -> bool:
+    """The same for a launch argument or a server's command and URL: a long run is looked for between path separators,
+    so a folder path holding a session id is not taken for a key."""
+    if JWT_SHAPE.search(value) or SECRET_VALUE.search(value) or _BEARER_INSIDE.search(value):
+        return True
+    for piece in re.split(r"[\s=]", value):
+        if _path_like(piece):
+            if any(_long_secret(part) for part in re.split(r"[\\/]", piece)):
+                return True
+        elif _long_secret(piece):
+            return True
+    return False
+
+
+def _decode_keeping_plus(raw: str) -> str:
+    """decodeURIComponent: a malformed escape or bytes that are not UTF-8 leave the raw text."""
+    if re.search(r"%(?![0-9A-Fa-f]{2})", raw):
+        return raw
+    try:
+        return urllib.parse.unquote_to_bytes(raw).decode("utf-8")
+    except UnicodeDecodeError:
+        return raw
+
+
+def _form_name(text: str) -> str:
+    pairs = urllib.parse.parse_qsl(text, keep_blank_values=True)
+    return pairs[0][0] if pairs else ""
+
+
+def raw_values(query: str) -> Dict[str, List[str]]:
+    """Each query or fragment piece's raw value by its decoded name, with `+` kept."""
+    values: Dict[str, List[str]] = {}
+    for piece in query.split("&"):
+        if piece == "":
+            continue
+        at = piece.find("=")
+        name = _form_name(piece if at < 0 else piece[:at])
+        values.setdefault(name, []).append("" if at < 0 else _decode_keeping_plus(piece[at + 1:]))
+    return values
+
+
+def secret_url(value: str) -> bool:
+    """Whether a URL an MCP entry or a launch names carries a credential (LC-21): anything secret_argument finds, a
+    password in its user information, or a query or fragment parameter whose name can only carry a credential and has
+    a value, or whose value is shaped like one. A string that is not an absolute URL is checked as an argument only."""
+    if secret_argument(value):
+        return True
+    if not _SCHEME.match(value.strip()):
+        return False  # not an absolute URL (WHATWG URL parsing refuses it)
+    try:
+        parts = urllib.parse.urlsplit(value.strip())
+    except ValueError:
+        return False
+    if not parts.scheme:
+        return False
+    if parts.password:
+        return True
+    for part in (parts.query, parts.fragment):
+        for name, raws in raw_values(part).items():
+            if any((raw != "" and credential_name(name)) or secret_value(raw) for raw in raws):
+                return True
+    return False

package/plugins/fabric-agent-adapter/skills/building-fabric-services/SKILL.md

@@ -16,7 +16,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Python 3.9+ or Node.js 20+ for the kits; the probe needs Python 3.9+. launchd steps are macOS-only (Linux services use lifecycle manager none until a systemd adapter exists). Dashboard handoff optionally uses Fabric Dashboards MCP link/host_status/open; without it, report unresolved host capability. The contract checkout is optional.
 metadata:
   author: PassionCode.ai
-  version: "0.16.0"
+  version: "0.17.0"
   contract-version: "0.1.0"
   extension: "fabric-service/0.1"
   extension-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"

package/plugins/fabric-agent-adapter/skills/building-fabric-services/references/surfaces-and-auth.md

@@ -21,7 +21,9 @@
   (`<tool> mcp-register`), which writes `{"type":"http","url":"http://127.0.0.1:<port>/mcp","headers":{...}}`
   atomically, aborts if the file changed meanwhile, and keeps one 0600 backup. The token
   goes in `headers`, never in the URL — every log that records a URL prints its query
-  string.
+  string. An HTTP registration starts nothing per session: every client session talks to the
+  one resident service (LC-19). A stdio server, by contrast, is a process per session — keep
+  one only at project scope.
 - Ship server `instructions` that tell a caller where to start and that every answer
   carries `degraded`.
 

package/plugins/fabric-agent-adapter/skills/creating-fabric-agents/SKILL.md

@@ -5,7 +5,7 @@ license: AGPL-3.0-only OR LicenseRef-PassionCode-Commercial
 compatibility: Requires filesystem access and Python 3.9+. Exact schema checks additionally need git, Node.js, pnpm, and the pinned fabric-agent-contract checkout (a public repository). Works without those tools in an explicitly degraded structural-check mode. Ships in one plugin with adapting-projects-to-fabric, whose scripts it reuses.
 metadata:
   author: PassionCode.ai
-  version: "0.16.0"
+  version: "0.17.0"
   contract-version: "0.1.0"
   contract-commit: "0cacd08b0e95b6abf131eae1206b60792138bc3c"
 ---