happyskills 1.11.0 → 1.12.1

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.12.1] - 2026-06-23
+
+### Changed
+- On a rate-limit `429`, steer anonymous callers to sign in instead of just retrying. When the API flags an anonymous trip on the search/resolve paths (`error.details.login_helps`), the CLI prints "You've hit the anonymous rate limit. Sign in or create a free account for a much higher limit — run `happyskills login`" (rather than a bare "wait and retry"), and `--json` mode emits a `login` `next_step`. Authenticated and `/auth/*` trips are unchanged. (Pairs with API `api-v5.15.3`.)
+
+## [1.12.0] - 2026-06-22
+
+### Added
+
+- Add a `--visibility <private|workspace|public>` flag to `publish` and `release`, making a workspace-visible first publish a single step. Previously the publish path could only emit `public` (via `--public`) or `private`, so shipping a skill as `workspace`-visible (discoverable and installable by every member of the owning workspace, but not public) required a second `visibility` command after publishing. The flag is honored on first publish only — later publishes preserve the existing visibility — and `--visibility` takes precedence over `--public`. `--public` is retained as a backward-compatible shorthand for `--visibility public`; the never-functional `--private` flag (always a silent no-op, since private is the default) is dropped from the documented examples.
+
+### Security
+
+- Cap `.tar.gz` decompression during install — enforce per-file size, total decompressed size, and entry-count limits mid-stream (and reject an oversized download by `Content-Length` before buffering), so a malicious highly-compressible archive can't inflate unbounded and exhaust the consumer's memory/disk. (SSRF-01/SUP-04)
+- Scrub C0/C1 terminal control bytes (`ESC`, `CR`, `BEL`, `DEL`, …) from server-supplied strings at the print boundary, so a crafted skill name or API message can't spoof or attack the terminal. (NEW-C2)
+- Guard server-derived install paths with an `assert_within` check, so a `..` or absolute skill name can't escape the skills directory on install. (NEW-C3)
+- Expand the secret scrubber to redact GitHub tokens (`gh[pousr]_`), AWS access-key IDs (`AKIA`/`ASIA…`), and `postgres://`/`postgresql://` connection strings before feedback context is sent to the backend. (DATA-04)
+- Pin all CLI runtime dependencies to exact locked versions for a reproducible published package. (SUP-09)
+
 ## [1.11.0] - 2026-06-12
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.11.0",
+	"version": "1.12.1",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",
@@ -43,14 +43,14 @@
 		"node": ">=22.0.0"
 	},
 	"dependencies": {
-		"@jimp/core": "^1.6.0",
-		"@jimp/js-jpeg": "^1.6.0",
-		"@jimp/js-png": "^1.6.0",
-		"@jimp/plugin-resize": "^1.6.0",
-		"node-diff3": "^3.2.0",
-		"puffy-core": "^1.3.1",
-		"semver": "^7.6.0",
-		"tar-stream": "^3.1.8"
+		"@jimp/core": "1.6.1",
+		"@jimp/js-jpeg": "1.6.1",
+		"@jimp/js-png": "1.6.1",
+		"@jimp/plugin-resize": "1.6.1",
+		"node-diff3": "3.2.0",
+		"puffy-core": "1.3.1",
+		"semver": "7.7.4",
+		"tar-stream": "3.1.8"
 	},
 	"devDependencies": {
 		"dotenv": "^17.2.4"

package/src/api/client.js

@@ -100,12 +100,22 @@ const request = (method, path, options = {}) => catch_errors(`API ${method} ${pa
 
 		if (res.status === 429) {
 			const retry_after = res.headers.get('retry-after')
-			const retry_msg = retry_after
-				? `API rate limit reached. Please wait ${retry_after} seconds and try again.`
-				: 'API rate limit reached. Please wait and try again.'
+			// The API sets login_helps when the caller is anonymous on a path where
+			// signing in lifts the cap (search/resolve) — turn the dead-end into a
+			// sign-up nudge instead of a bare "wait and retry".
+			const login_helps = !!(err_details && err_details.login_helps)
+			const wait_hint = retry_after ? ` (or wait ${retry_after}s and retry)` : ''
+			const retry_msg = login_helps
+				? `You've hit the anonymous rate limit. Sign in or create a free account for a much higher limit — run \`happyskills login\`${wait_hint}.`
+				: (retry_after
+					? `API rate limit reached. Please wait ${retry_after} seconds and try again.`
+					: 'API rate limit reached. Please wait and try again.')
 			const err = new ApiError(retry_msg, 429, 'RATE_LIMITED')
 			err.retry_after = retry_after ? parseInt(retry_after) : null
 			if (err_details) err.details = { ...err.details, ...err_details }
+			// The JSON-mode marshaller builds next_step from err.context (not details),
+			// so stash the branch inputs there to get the LOGIN vs RETRY next_step.
+			err.context = { login_helps, ...(retry_after ? { retry_after_seconds: parseInt(retry_after) } : {}) }
 			throw err
 		}
 

package/src/commands/publish.js

@@ -36,16 +36,40 @@ Arguments:
 Options:
   --bump <type>          Auto-bump version before publishing (patch, minor, major)
   --workspace <slug>     Target workspace (overrides lock file owner)
-  --public               Publish as public (default is private)
+  --visibility <value>   Visibility on first publish: private (default), workspace, or public
+  --public               Shorthand for --visibility public
   --force                Bypass divergence check (may overwrite remote changes)
 
 Aliases: pub
 
+Visibility (set on first publish; preserved on later publishes):
+  private    (default) Only people you explicitly grant access to.
+  workspace  Every member of the owning workspace can find and install it. Not public.
+  public     Anyone — listed in the public registry.
+
 Examples:
   happyskills publish my-skill
   happyskills publish deploy-aws --bump patch
+  happyskills publish team-deploy --workspace acme --visibility workspace
   happyskills pub my-skill --workspace myorg`
 
+const VALID_VISIBILITIES = ['public', 'private', 'workspace']
+
+// Resolve the target visibility from flags. --visibility wins when present
+// (validated against the closed set); --public stays as a backward-compatible
+// shorthand; the default is private. Visibility only takes effect on FIRST
+// publish — later publishes preserve whatever the registry already has.
+const resolve_visibility = (flags) => {
+	if (flags.visibility) {
+		if (!VALID_VISIBILITIES.includes(flags.visibility)) {
+			throw new UsageError(`Invalid visibility "${flags.visibility}". Must be one of: ${VALID_VISIBILITIES.join(', ')}.`)
+		}
+		return flags.visibility
+	}
+	if (flags.public) return 'public'
+	return 'private'
+}
+
 const choose_workspace = (workspaces, preferred) => {
 	if (preferred) {
 		const found = workspaces.find(w => w.slug === preferred)
@@ -136,7 +160,7 @@ const run = (args) => catch_errors('Publish failed', async () => {
 
 	const spinner = create_spinner('Preparing to publish...')
 
-	const visibility = args.flags.public ? 'public' : 'private'
+	const visibility = resolve_visibility(args.flags)
 
 	let owner = args.flags.workspace
 	if (!owner) {
@@ -348,11 +372,12 @@ const schema = {
 	input: {
 		positional: [ { name: 'skill', required: true, type: 'string', description: 'Name of the installed skill' } ],
 		flags: [
-			{ name: 'bump',      type: 'string',  default: undefined, description: 'Auto-bump version before publishing (patch, minor, major)' },
-			{ name: 'workspace', type: 'string',  default: undefined, description: 'Target workspace (overrides lock file owner)' },
-			{ name: 'public',    type: 'boolean', default: false,     description: 'Publish as public (default is private)' },
-			{ name: 'force',     type: 'boolean', default: false,     description: 'Bypass divergence check (may overwrite remote changes)' },
-			{ name: 'json',      type: 'boolean', default: false,     description: 'Output as JSON' },
+			{ name: 'bump',       type: 'string',  default: undefined, description: 'Auto-bump version before publishing (patch, minor, major)' },
+			{ name: 'workspace',  type: 'string',  default: undefined, description: 'Target workspace (overrides lock file owner)' },
+			{ name: 'visibility', type: 'string',  default: undefined, description: 'Visibility on first publish: private (default), workspace, or public' },
+			{ name: 'public',     type: 'boolean', default: false,     description: 'Shorthand for --visibility public' },
+			{ name: 'force',      type: 'boolean', default: false,     description: 'Bypass divergence check (may overwrite remote changes)' },
+			{ name: 'json',       type: 'boolean', default: false,     description: 'Output as JSON' },
 		],
 	},
 	output: {
@@ -375,7 +400,8 @@ const schema = {
 	examples: [
 		'happyskills publish my-skill',
 		'happyskills publish deploy-aws --bump patch',
+		'happyskills publish team-deploy --workspace acme --visibility workspace',
 	],
 }
 
-module.exports = { run, schema }
+module.exports = { run, schema, resolve_visibility }

package/src/commands/publish.test.js

@@ -2,14 +2,15 @@ const { describe, it } = require('node:test')
 const assert = require('node:assert')
 const fs = require('node:fs')
 const path = require('node:path')
+const { resolve_visibility } = require('./publish')
 
 describe('publish.js — Bug 1 regression: visibility temporal-dead-zone', () => {
 	const src = fs.readFileSync(path.join(__dirname, 'publish.js'), 'utf8')
 
 	it('declares `visibility` before passing it to validate_dependencies', () => {
-		const decl_idx = src.search(/const\s+visibility\s*=\s*args\.flags\.public/)
+		const decl_idx = src.search(/const\s+visibility\s*=\s*resolve_visibility\(/)
 		const use_idx = src.search(/validate_dependencies\([\s\S]*?visibility/)
-		assert.notStrictEqual(decl_idx, -1, '`const visibility = args.flags.public ? ...` declaration not found')
+		assert.notStrictEqual(decl_idx, -1, '`const visibility = resolve_visibility(...)` declaration not found')
 		assert.notStrictEqual(use_idx, -1, '`validate_dependencies(... visibility ...)` call not found')
 		assert.ok(
 			decl_idx < use_idx,
@@ -19,3 +20,30 @@ describe('publish.js — Bug 1 regression: visibility temporal-dead-zone', () =>
 		)
 	})
 })
+
+describe('publish.js — resolve_visibility', () => {
+	it('defaults to private when no visibility flags are given', () => {
+		assert.strictEqual(resolve_visibility({}), 'private')
+	})
+
+	it('maps --public to public (backward-compatible shorthand)', () => {
+		assert.strictEqual(resolve_visibility({ public: true }), 'public')
+	})
+
+	it('accepts --visibility workspace', () => {
+		assert.strictEqual(resolve_visibility({ visibility: 'workspace' }), 'workspace')
+	})
+
+	it('accepts --visibility private and --visibility public', () => {
+		assert.strictEqual(resolve_visibility({ visibility: 'private' }), 'private')
+		assert.strictEqual(resolve_visibility({ visibility: 'public' }), 'public')
+	})
+
+	it('lets --visibility win over --public when both are present', () => {
+		assert.strictEqual(resolve_visibility({ visibility: 'workspace', public: true }), 'workspace')
+	})
+
+	it('throws a usage error on an unknown visibility value', () => {
+		assert.throws(() => resolve_visibility({ visibility: 'team' }), /Invalid visibility/)
+	})
+})

package/src/commands/release.js

@@ -34,13 +34,15 @@ Options:
   --no-bump                       Refuse to bump; require disk to be already ahead
   --changelog-from <auto|file>    Source for the new CHANGELOG entry (default: read from CHANGELOG.md)
   --workspace <slug>              Target workspace
-  --public | --private            Visibility on first publish only
+  --visibility <value>            Visibility on first publish: private (default), workspace, or public
+  --public                        Shorthand for --visibility public
   --dry-run                       Validate + check status, do not mutate
   --json                          Output as JSON
 
 Examples:
   happyskills release my-skill --workspace acme --json
   happyskills release my-skill --bump patch --workspace acme --json
+  happyskills release team-deploy --workspace acme --visibility workspace --json
   happyskills release my-skill --no-bump --json  # disk is already ahead`
 
 const envelope_error = (code_str, message, extra = {}) => ({ error: { code: code_str, message, ...extra } })
@@ -384,6 +386,7 @@ const orchestrate = (args) => catch_errors('Release failed', async () => {
 
 	const { spawn } = require('child_process')
 	const publish_args = [path.resolve(__dirname, '../../bin/happyskills.js'), 'publish', skill_name, '--workspace', resolved_workspace, '--json']
+	if (args.flags.visibility) publish_args.push('--visibility', args.flags.visibility)
 	if (args.flags.public) publish_args.push('--public')
 	if (args.flags.force) publish_args.push('--force')
 
@@ -494,7 +497,8 @@ const schema = {
 			{ name: 'no-bump',        type: 'boolean', default: false,     description: 'Refuse to bump; require disk to already be ahead' },
 			{ name: 'changelog-from', type: 'string',  default: undefined, description: 'Source for the new CHANGELOG entry (auto or file path)' },
 			{ name: 'workspace',      type: 'string',  default: undefined, description: 'Target workspace slug' },
-			{ name: 'public',         type: 'boolean', default: false,     description: 'Publish as public on first publish' },
+			{ name: 'visibility',     type: 'string',  default: undefined, description: 'Visibility on first publish: private (default), workspace, or public' },
+			{ name: 'public',         type: 'boolean', default: false,     description: 'Shorthand for --visibility public' },
 			{ name: 'dry-run',        type: 'boolean', default: false,     description: 'Validate and check status without mutating' },
 			{ name: 'json',           type: 'boolean', default: false,     description: 'Output as JSON' },
 		],

package/src/config/limits.js

@@ -3,9 +3,11 @@
 // validation will be rejected by the API.
 
 const MAX_FILE_SIZE = 1 * 1024 * 1024   // 1 MB per file
-const MAX_TOTAL_SIZE = 1 * 1024 * 1024  // 1 MB per skill bundle
+const MAX_TOTAL_SIZE = 1 * 1024 * 1024  // 1 MB per skill bundle (also the decompressed-archive cap — SUP-04)
+const MAX_FILE_COUNT = 1000             // max entries per archive (zip-bomb / DoS guard; real skills have <100 files) — SUP-04
 
 module.exports = {
 	MAX_FILE_SIZE,
-	MAX_TOTAL_SIZE
+	MAX_TOTAL_SIZE,
+	MAX_FILE_COUNT
 }

package/src/config/paths.js

@@ -22,6 +22,18 @@ const skills_dir = (global = false, project_root) => {
 	return global ? global_skills_dir() : project_skills_dir(project_root)
 }
 
+// NEW-C3 (spec 260603-02 §4 Tier 3). The install-dir name is server-derived; a
+// `..` or absolute component would let it escape the skills directory and write
+// elsewhere on disk. Defense-in-depth: confirm the joined path stays under base.
+const assert_within = (base, full) => {
+	const r_base = path.resolve(base)
+	const r_full = path.resolve(full)
+	if (r_full !== r_base && !r_full.startsWith(r_base + path.sep)) {
+		throw new Error(`Unsafe install path "${full}": escapes the skills directory ${base}`)
+	}
+	return full
+}
+
 const tmp_dir = (base_skills_dir) => path.join(base_skills_dir, '.tmp')
 
 const install_lock_path = (base_skills_dir) => path.join(base_skills_dir, '.install.lock')
@@ -32,7 +44,7 @@ const lock_root = (is_global, project_root) => {
 
 const lock_file_path = (project_root = process.cwd()) => path.join(project_root, 'skills-lock.json')
 
-const skill_install_dir = (base_skills_dir, name) => path.join(base_skills_dir, name)
+const skill_install_dir = (base_skills_dir, name) => assert_within(base_skills_dir, path.join(base_skills_dir, name))
 
 const find_project_root = (start_dir = process.cwd()) => path.resolve(start_dir)
 
@@ -41,8 +53,10 @@ const agent_skills_dir = (agent, global = false, project_root) => {
 	return path.join(project_root || process.cwd(), agent.skills_dir)
 }
 
-const agent_skill_install_dir = (agent, global, project_root, skill_name) =>
-	path.join(agent_skills_dir(agent, global, project_root), skill_name)
+const agent_skill_install_dir = (agent, global, project_root, skill_name) => {
+	const base = agent_skills_dir(agent, global, project_root)
+	return assert_within(base, path.join(base, skill_name))
+}
 
 module.exports = {
 	home_dir,
@@ -59,5 +73,6 @@ module.exports = {
 	skill_install_dir,
 	find_project_root,
 	agent_skills_dir,
-	agent_skill_install_dir
+	agent_skill_install_dir,
+	assert_within
 }

package/src/config/paths.test.js

@@ -143,4 +143,19 @@ describe('paths', () => {
 			assert.strictEqual(paths.find_project_root(), path.resolve(process.cwd()))
 		})
 	})
+
+	// NEW-C3 — the server-derived install-dir name must not escape the skills dir.
+	describe('install-dir path safety (NEW-C3)', () => {
+		const base = path.join(os.tmpdir(), 'hs-skills-base')
+
+		it('allows a normal (possibly nested) skill dir under base', () => {
+			assert.strictEqual(paths.skill_install_dir(base, 'owner/skill'), path.join(base, 'owner/skill'))
+			assert.strictEqual(paths.assert_within(base, path.join(base, 'a', 'b')), path.join(base, 'a', 'b'))
+		})
+
+		it('rejects a name that traverses out of base', () => {
+			assert.throws(() => paths.skill_install_dir(base, '../../etc/evil'), /escapes the skills directory/)
+			assert.throws(() => paths.assert_within(base, '/etc/passwd'), /escapes/)
+		})
+	})
 })

package/src/constants/next_step_by_error_code.js

@@ -74,11 +74,24 @@ const NEXT_STEP_BY_ERROR_CODE = Object.freeze({
 		'A network error interrupted the request. Retry shortly.',
 		{ retry_after_seconds: 5, max_attempts: 3 }
 	),
-	RATE_LIMITED: (msg, ctx = {}) => recovery(
-		RETRY,
-		'Rate limit reached. Retry after the suggested interval.',
-		{ retry_after_seconds: ctx.retry_after_seconds || 30, max_attempts: 3 }
-	),
+	// An anonymous caller throttled on a per-IP bucket gets a much higher cap (and
+	// their own per-user budget) once signed in, so when the API flags `login_helps`
+	// we steer them to authenticate instead of just retrying. Authenticated trips
+	// (and the pre-login /auth/* limiter) fall through to the plain retry recovery.
+	RATE_LIMITED: (_msg, ctx = {}) => ctx.login_helps
+		? recovery(
+			LOGIN,
+			'You hit the anonymous rate limit. Sign in or create a free account for a much higher limit, then re-run.',
+			{
+				retry_after_seconds: ctx.retry_after_seconds || 30,
+				commands: ['npx happyskills login --browser --json'],
+			}
+		)
+		: recovery(
+			RETRY,
+			'Rate limit reached. Retry after the suggested interval.',
+			{ retry_after_seconds: ctx.retry_after_seconds || 30, max_attempts: 3 }
+		),
 	DB_UNAVAILABLE: () => recovery(
 		RETRY,
 		'The registry database is temporarily unavailable. Retry shortly.',

package/src/constants/next_step_by_error_code.test.js

@@ -7,7 +7,7 @@
 const { describe, it } = require('node:test')
 const assert = require('node:assert/strict')
 const { next_step_for_error } = require('./next_step_by_error_code')
-const { DISCOVER_SCHEMA, ROUTING, kind_for_action } = require('./next_step_actions')
+const { DISCOVER_SCHEMA, ROUTING, RECOVERY, LOGIN, RETRY, kind_for_action } = require('./next_step_actions')
 
 describe('next_step_by_error_code — schema discovery routing', () => {
 	it('discover_schema is a routing-kind action', () => {
@@ -28,3 +28,19 @@ describe('next_step_by_error_code — schema discovery routing', () => {
 		})
 	}
 })
+
+describe('next_step_by_error_code — RATE_LIMITED steers anonymous callers to sign in', () => {
+	it('login_helps → a LOGIN recovery that points at `happyskills login`', () => {
+		const ns = next_step_for_error('RATE_LIMITED', 'Too many requests.', { login_helps: true, retry_after_seconds: 42 })
+		assert.strictEqual(ns.kind, RECOVERY)
+		assert.strictEqual(ns.action, LOGIN)
+		assert.ok(ns.context.commands.some(c => c.includes('login')), 'must point at the login command')
+		assert.strictEqual(ns.context.retry_after_seconds, 42)
+	})
+
+	it('without login_helps → a plain RETRY recovery (authenticated / auth-path trips)', () => {
+		const ns = next_step_for_error('RATE_LIMITED', 'Too many requests.', { retry_after_seconds: 30 })
+		assert.strictEqual(ns.kind, RECOVERY)
+		assert.strictEqual(ns.action, RETRY)
+	})
+})

package/src/engine/archive_installer.js

@@ -5,6 +5,7 @@ const { Readable } = require('stream')
 const tar = require('tar-stream')
 const { error: { catch_errors } } = require('puffy-core')
 const repos_api = require('../api/repos')
+const { MAX_FILE_SIZE, MAX_TOTAL_SIZE, MAX_FILE_COUNT } = require('../config/limits')
 
 /**
  * Attempts an archive-based clone. Returns the extracted files or null if no archive is available.
@@ -25,6 +26,12 @@ const install_from_archive = (owner, name, ref, dest_dir) => catch_errors('Archi
 	const resp = await fetch(clone_data.url)
 	if (!resp.ok) throw new Error(`Archive download failed: ${resp.status}`)
 
+	// Bound the download before buffering it (SUP-04): a Content-Length past the
+	// bundle cap is rejected up front; a missing or lying header is still caught
+	// by the streaming decompression caps in extract_tar_gz below.
+	const declared = Number(resp.headers.get('content-length') || 0)
+	if (declared > MAX_TOTAL_SIZE) throw new Error(`Archive too large: ${declared} bytes exceeds the ${MAX_TOTAL_SIZE}-byte limit`)
+
 	const archive_buffer = Buffer.from(await resp.arrayBuffer())
 
 	// Extract tar.gz to dest_dir
@@ -38,33 +45,47 @@ const install_from_archive = (owner, name, ref, dest_dir) => catch_errors('Archi
  */
 const extract_tar_gz = (buffer, dest_dir) => new Promise((resolve, reject) => {
 	const extract = tar.extract()
+	const gunzip = zlib.createGunzip()
+	let total = 0
+	let count = 0
+
+	// Stop decompression immediately on a cap breach (SUP-04) — destroying gunzip
+	// halts inflation so a zip bomb cannot keep expanding onto the consumer's disk
+	// or into memory after the breach.
+	const abort = (message) => {
+		gunzip.destroy()
+		extract.destroy()
+		reject(new Error(message))
+	}
 
 	extract.on('entry', (header, stream, next) => {
 		if (header.type !== 'file') {
 			stream.resume()
 			return next()
 		}
+		if (++count > MAX_FILE_COUNT) return abort(`Archive exceeds the ${MAX_FILE_COUNT}-file limit`)
 
 		// Normalize path: strip leading ./
 		const file_path = header.name.replace(/^\.\//, '')
-
-		// Skip macOS metadata
 		const basename = file_path.split('/').pop()
-		if (basename.startsWith('._') || basename === '.DS_Store') {
-			stream.resume()
-			return next()
-		}
-
-		// Path safety check
 		const resolved = path.resolve(dest_dir, file_path)
-		if (!resolved.startsWith(path.resolve(dest_dir) + path.sep) && resolved !== path.resolve(dest_dir)) {
-			stream.resume()
-			return next()
-		}
+		// Skip macOS metadata + path-traversal entries — but still METER their bytes
+		// against the caps so a bomb hidden in a skipped entry can't slip the cap.
+		const is_meta = basename.startsWith('._') || basename === '.DS_Store'
+		const is_unsafe = !resolved.startsWith(path.resolve(dest_dir) + path.sep) && resolved !== path.resolve(dest_dir)
+		const skip = is_meta || is_unsafe
 
 		const chunks = []
-		stream.on('data', chunk => chunks.push(chunk))
+		let entry_size = 0
+		stream.on('data', chunk => {
+			entry_size += chunk.length
+			total += chunk.length
+			if (entry_size > MAX_FILE_SIZE) return abort(`Archive entry ${header.name} exceeds the ${MAX_FILE_SIZE}-byte per-file limit`)
+			if (total > MAX_TOTAL_SIZE) return abort(`Archive decompresses past the ${MAX_TOTAL_SIZE}-byte total limit (possible zip bomb)`)
+			if (!skip) chunks.push(chunk)
+		})
 		stream.on('end', async () => {
+			if (skip) return next()
 			try {
 				const dir = path.dirname(resolved)
 				await fs.promises.mkdir(dir, { recursive: true })
@@ -79,8 +100,8 @@ const extract_tar_gz = (buffer, dest_dir) => new Promise((resolve, reject) => {
 
 	extract.on('finish', resolve)
 	extract.on('error', reject)
+	gunzip.on('error', reject)
 
-	const gunzip = zlib.createGunzip()
 	Readable.from(buffer).pipe(gunzip).pipe(extract)
 })
 

package/src/engine/archive_installer.test.js

@@ -5,7 +5,8 @@ const path = require('path')
 const os = require('os')
 const zlib = require('zlib')
 const tar = require('tar-stream')
-const { extract_tar_gz } = require('./archive_installer')
+const { extract_tar_gz, install_from_archive } = require('./archive_installer')
+const { MAX_FILE_SIZE, MAX_TOTAL_SIZE, MAX_FILE_COUNT } = require('../config/limits')
 
 const create_tar_gz = (files) => new Promise((resolve, reject) => {
 	const pack = tar.pack()
@@ -118,4 +119,54 @@ describe('extract_tar_gz', () => {
 		const content = await fs.promises.readFile(path.join(tmp_dir, 'file.txt'), 'utf8')
 		assert.equal(content, 'dot-slash content')
 	})
+
+	// Zip-bomb / oversize caps (SUP-04, spec 260603-02 §4.T1-2). { todo: true }
+	// until the streaming caps land — un-todo when implemented.
+	it('rejects a zip bomb that decompresses past the cap (mid-stream)', async () => {
+		const buffer = await create_tar_gz([{ name: 'bomb', content: Buffer.alloc(8 * 1024 * 1024, 0) }])
+		assert.ok(buffer.length < 64 * 1024, 'sanity: tiny compressed')
+		await assert.rejects(extract_tar_gz(buffer, tmp_dir))
+	})
+
+	it('rejects a single entry larger than MAX_FILE_SIZE', async () => {
+		const buffer = await create_tar_gz([{ name: 'big', content: Buffer.alloc(MAX_FILE_SIZE + 1024, 7) }])
+		await assert.rejects(extract_tar_gz(buffer, tmp_dir))
+	})
+
+	it('rejects when the running total decompressed exceeds MAX_TOTAL_SIZE', async () => {
+		const each = Math.ceil(MAX_TOTAL_SIZE * 0.6)
+		const buffer = await create_tar_gz([
+			{ name: 'a', content: Buffer.alloc(each, 1) },
+			{ name: 'b', content: Buffer.alloc(each, 2) }
+		])
+		await assert.rejects(extract_tar_gz(buffer, tmp_dir))
+	})
+
+	it('rejects when the entry count exceeds MAX_FILE_COUNT', async () => {
+		const limit = MAX_FILE_COUNT || 1000
+		const files = Array.from({ length: limit + 1 }, (_, i) => ({ name: `f${i}.txt`, content: 'x' }))
+		const buffer = await create_tar_gz(files)
+		await assert.rejects(extract_tar_gz(buffer, tmp_dir))
+	})
+})
+
+describe('install_from_archive — Content-Length guard before buffering (SUP-04)', () => {
+	it('rejects an oversized download via Content-Length, before calling arrayBuffer()', async () => {
+		const repos_api = require('../api/repos')
+		const orig_clone = repos_api.clone
+		const orig_fetch = global.fetch
+		repos_api.clone = async () => [null, { format: 'archive', url: 'https://example.com/archive.tar.gz', ref: 'refs/tags/v1', commit: 'abc' }]
+		global.fetch = async () => ({
+			ok: true,
+			headers: { get: (k) => (String(k).toLowerCase() === 'content-length' ? String(MAX_TOTAL_SIZE * 4) : null) },
+			arrayBuffer: async () => { throw new Error('must reject before buffering the body') }
+		})
+		try {
+			const [err] = await install_from_archive('owner', 'name', 'refs/tags/v1', '/tmp/nope')
+			assert.ok(err, 'oversized archive rejected before buffering')
+		} finally {
+			repos_api.clone = orig_clone
+			global.fetch = orig_fetch
+		}
+	})
 })

package/src/ui/output.js

@@ -1,28 +1,36 @@
 const { red, green, yellow, cyan, bold, dim, gray, code, enabled } = require('./colors')
 const { is_json_mode } = require('../state')
 
+// NEW-C2 (spec 260603-02 §4 Tier 3). Server-supplied strings (skill names, API
+// error messages) are printed straight to a terminal; a crafted value carrying
+// ESC / control bytes could rewrite the screen, spoof output, or run a terminal
+// escape attack. Strip C0/C1 control bytes (keeping only \t and \n) at the print
+// boundary. The CLI's own ANSI coloring is applied AFTER this scrub, so legitimate
+// colors are unaffected. (NO_COLOR is honored separately in ./colors.)
+const scrub_terminal = (str) => String(str == null ? '' : str).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '')
+
 const print_success = (msg) => {
 	if (is_json_mode()) return
-	console.log(green(`✓ ${msg}`))
+	console.log(green(`✓ ${scrub_terminal(msg)}`))
 }
 
 const print_error = (msg) => {
-	console.error(red(`✗ ${msg}`))
+	console.error(red(`✗ ${scrub_terminal(msg)}`))
 }
 
 const print_warn = (msg) => {
-	console.error(yellow(`⚠ ${msg}`))
+	console.error(yellow(`⚠ ${scrub_terminal(msg)}`))
 }
 
 const print_info = (msg) => {
 	if (is_json_mode()) return
-	console.log(cyan(`ℹ ${msg}`))
+	console.log(cyan(`ℹ ${scrub_terminal(msg)}`))
 }
 
 // Subtle post-command suggestion line
 const print_hint = (msg) => {
 	if (is_json_mode()) return
-	console.log(dim(`  → ${msg}`))
+	console.log(dim(`  → ${scrub_terminal(msg)}`))
 }
 
 // Style help text: bold section headers, dim example lines
@@ -96,7 +104,7 @@ const print_table = (headers, rows) => {
 	console.log(separator)
 	rows.forEach(row => {
 		const line = row.map((cell, i) => {
-			const str = String(cell || '')
+			const str = scrub_terminal(String(cell || ''))   // NEW-C2 — server data into the terminal
 			const t = truncate(str, col_widths[i])
 			return ansi_pad(t, col_widths[i])
 		}).join('  ')
@@ -184,7 +192,7 @@ const print_json = (input) => {
 }
 
 const print_label = (label, value) => {
-	console.log(`${gray(label + ':')} ${value}`)
+	console.log(`${gray(label + ':')} ${scrub_terminal(value)}`)
 }
 
-module.exports = { print_success, print_error, print_warn, print_info, print_hint, print_help, print_table, print_json, print_label, code, format_help, visible_len, ansi_pad, truncate, summarize_warnings }
+module.exports = { print_success, print_error, print_warn, print_info, print_hint, print_help, print_table, print_json, print_label, code, format_help, visible_len, ansi_pad, truncate, summarize_warnings, scrub_terminal }

package/src/ui/output.test.js

@@ -2,7 +2,29 @@
 const { describe, it, before, after, beforeEach, afterEach } = require('node:test')
 const assert = require('node:assert/strict')
 
-const { visible_len, ansi_pad, truncate, format_help, print_table, summarize_warnings } = require('./output')
+const { visible_len, ansi_pad, truncate, format_help, print_table, summarize_warnings, scrub_terminal } = require('./output')
+
+// ─── scrub_terminal (NEW-C2) ──────────────────────────────────────────────────
+
+describe('scrub_terminal — strips terminal control bytes from server strings (NEW-C2)', () => {
+	it('removes ESC and other C0/C1 control bytes (neutralizing escape sequences)', () => {
+		// The ESC byte (0x1b) is stripped, so the leftover "[31m" is inert literal
+		// text the terminal will not interpret — the attack is neutralized.
+		assert.strictEqual(scrub_terminal('a\x1b[31mb\x07c'), 'a[31mbc')   // ESC + BEL bytes gone
+		assert.ok(!scrub_terminal('a\x1b[31mb').includes('\x1b'), 'no ESC byte survives')
+		assert.strictEqual(scrub_terminal('x\x9by'), 'xy')             // C1
+		assert.strictEqual(scrub_terminal('a\rb'), 'ab')               // CR (line-overwrite) stripped
+		assert.strictEqual(scrub_terminal('a\x7fb'), 'ab')             // DEL
+	})
+	it('keeps tabs, newlines, and normal text intact', () => {
+		assert.strictEqual(scrub_terminal('a\tb\nc'), 'a\tb\nc')
+		assert.strictEqual(scrub_terminal('normal skill name'), 'normal skill name')
+	})
+	it('coerces nullish to empty string', () => {
+		assert.strictEqual(scrub_terminal(null), '')
+		assert.strictEqual(scrub_terminal(undefined), '')
+	})
+})
 
 // ─── visible_len ─────────────────────────────────────────────────────────────
 

package/src/utils/scrub_secrets.js

@@ -3,9 +3,11 @@
 //
 // Rules:
 //   1. Strip OpenAI API keys (sk-...)
-//   2. Strip GitHub tokens (ghp_..., gho_...)
+//   2. Strip GitHub tokens (ghp_/gho_/ghu_/ghs_/ghr_...)
 //   3. Strip Cognito JWT-shaped tokens (eyJ...)
-//   4. Strip values for env-var keys ending in _TOKEN, _KEY, _SECRET, _PASSWORD
+//   4. Strip AWS access key IDs (AKIA.../ASIA...)
+//   5. Strip postgres connection strings (postgres://... — carry credentials)
+//   6. Strip values for env-var keys ending in _TOKEN, _KEY, _SECRET, _PASSWORD
 //
 // The replacement is the literal string `<redacted>` so callers can see that
 // a value WAS present and got stripped — vs missing entirely.
@@ -13,9 +15,10 @@
 const REDACTED = '<redacted>'
 
 const PATTERNS = [
-	/sk-[A-Za-z0-9_-]{20,}/g,      // OpenAI keys
-	/ghp_[A-Za-z0-9]{30,}/g,       // GitHub personal access tokens
-	/gho_[A-Za-z0-9]{30,}/g,       // GitHub OAuth tokens
+	/sk-[A-Za-z0-9_-]{20,}/g,                  // OpenAI keys
+	/gh[pousr]_[A-Za-z0-9]{30,}/g,             // GitHub tokens (ghp_/gho_/ghu_/ghs_/ghr_)
+	/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g,          // AWS access key IDs (long-term + temporary)
+	/postgres(?:ql)?:\/\/[^\s'"]+/gi,          // postgres connection strings (may carry user:pass@host)
 	/eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g  // JWT shape
 ]
 

package/src/utils/scrub_secrets.test.js

@@ -0,0 +1,38 @@
+const { describe, it } = require('node:test')
+const assert = require('node:assert/strict')
+
+// DATA-04 (spec 260603-02) — the scrubber must catch the token/key/connection-
+// string shapes that were missing, WITHOUT over-redacting ordinary prose. Keep
+// in lockstep with web/src/lib/scrub-secrets.js.
+const { scrub, scrub_string, REDACTED } = require('./scrub_secrets')
+
+describe('scrub_secrets — DATA-04 expanded patterns', () => {
+	it('redacts all GitHub token prefixes (ghp/gho/ghu/ghs/ghr)', () => {
+		for (const p of ['ghp', 'gho', 'ghu', 'ghs', 'ghr']) {
+			assert.equal(scrub_string(`x ${p}_${'a'.repeat(36)} y`), `x ${REDACTED} y`, `${p}_ token redacted`)
+		}
+	})
+	it('redacts AWS access key IDs (AKIA + ASIA)', () => {
+		assert.equal(scrub_string('id=AKIAIOSFODNN7EXAMPLE.'), `id=${REDACTED}.`)
+		assert.equal(scrub_string('ASIAY34FZKBOKMUTVV7A'), REDACTED)
+	})
+	it('redacts postgres / postgresql connection strings (which carry credentials)', () => {
+		assert.equal(scrub_string('postgres://u:p@host.neon.tech/db?sslmode=require'), REDACTED)
+		assert.equal(scrub_string('postgresql://u:p@h/d'), REDACTED)
+	})
+	it('still redacts the original shapes (OpenAI, JWT)', () => {
+		assert.equal(scrub_string(`sk-${'a'.repeat(24)}`), REDACTED)
+		assert.match(scrub_string('eyJabc.eyJdef.sig'), new RegExp(REDACTED))
+	})
+	it('does NOT over-redact ordinary prose / near-misses', () => {
+		assert.equal(scrub_string('postgresql is a database engine'), 'postgresql is a database engine')
+		assert.equal(scrub_string('AKIANOTAKEY'), 'AKIANOTAKEY') // not 16 trailing chars
+		assert.equal(scrub_string('a normal sentence, email a@b.com'), 'a normal sentence, email a@b.com')
+	})
+	it('recursively redacts inside objects + sensitive keys', () => {
+		const out = scrub({ note: `key ghs_${'z'.repeat(36)}`, DATABASE_URL: 'postgres://u:p@h/d', nested: { token: 'eyJa.eyJb.c' } })
+		assert.equal(out.note, `key ${REDACTED}`)
+		assert.equal(out.DATABASE_URL, REDACTED)
+		assert.match(out.nested.token, new RegExp(REDACTED))
+	})
+})