@rubytech/create-maxy 1.0.695 → 1.0.696

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rubytech/create-maxy",
-  "version": "1.0.695",
+  "version": "1.0.696",
   "description": "Install Maxy — AI for Productive People",
   "bin": {
     "create-maxy": "./dist/index.js"

package/payload/platform/plugins/admin/skills/unzip-attachment/SKILL.md

@@ -0,0 +1,58 @@
+# Unzip Attachment
+
+Safely extract a zip archive the admin has uploaded, inventory its contents, and propose one concrete follow-up per entry class — refusing archives that attempt path traversal, symlink escape, or decompression-bomb pathologies.
+
+## When to Use
+
+Activate when the `[ATTACHMENTS:]` block of the current turn contains an entry whose MIME is `application/zip` or `application/x-zip-compressed`. Every such attachment line carries an `ID: <uuid>  Path: <storagePath>` pair — the `storagePath` is the absolute path to the `.zip` on disk and is the input to this flow.
+
+Do **not** activate for agent-generated zips (those are already trusted — they originate from `storeGeneratedFile`). The MIME allow-list restricts this skill to admin-uploaded archives by construction: no other code path produces a `[ATTACHMENTS:]` line with a zip MIME.
+
+## Invariants
+
+These are not guidelines. Every one of them is mechanically enforced by the shell primitives below; if any check fails, abort the flow, emit the named log line, and tell the operator verbatim what tripped it.
+
+- **No byte of the archive may land outside `{accountDir}/extracted/{attachmentId}/`.** The destination is fresh per upload. Extraction uses `unzip -oq` into that directory and only that directory.
+- **Sum of declared uncompressed sizes must be ≤ `MAX_ZIP_UNCOMPRESSED_BYTES` (100 MiB, defined in [platform/ui/app/lib/attachments.ts](../../../../ui/app/lib/attachments.ts)).** Checked via `unzip -Zt` *before* any write.
+- **No entry may be a symlink.** Checked via `unzip -Z1v` output parsing before extraction; the post-extraction loop also runs `find <dest> -type l` as a ground-truth backstop.
+- **Every extracted file's `realpath --relative-to <dest>` must not start with `../`.** This is the canonical zip-slip guard — it catches malicious entry names like `../../etc/passwd` that some older `unzip` builds silently accept.
+- **Password-protected archives are refused with a fixed message.** Never prompt for a key.
+
+See [references/safety.md](references/safety.md) for the precise shell commands, attack examples, and refusal templates.
+
+## Flow
+
+1. **Resolve paths.** From the `[ATTACHMENTS:]` line read `attachmentId` and `storagePath`. Set `dest="${ACCOUNT_DIR}/extracted/${attachmentId}"`. Create it with `mkdir -p "$dest"`.
+2. **Pre-scan for password + symlink + byte total.** Run `unzip -Z -1 "$storagePath"` for the entry list; if it exits non-zero, the archive is corrupt or password-protected — refuse. Run `unzip -Z -v "$storagePath"` and scan the permission column for a leading `l` (symlink) — refuse on match. Run `unzip -Zt "$storagePath"` to obtain the summary line and parse the total uncompressed bytes; if > `100 * 1024 * 1024`, refuse.
+3. **Emit the start log line** — `[skill:unzip] start attachmentId=<uuid> dest=<path> declaredBytes=<n>` — exactly once, before the extraction command.
+4. **Extract.** `unzip -oq "$storagePath" -d "$dest"`. Non-zero exit → refuse with the underlying `unzip` stderr quoted.
+5. **Post-extraction realpath check.** For every path emitted by `find "$dest" -mindepth 1 \( -type f -o -type l \)`:
+   - If `-type l`, refuse with `symlink-blocked` (ground-truth guard — pre-scan caught most, this catches the rest).
+   - Else compute `realpath --relative-to "$dest" "<entry>"`; if it begins with `../`, refuse with `zip-slip-blocked`.
+6. **Emit the done log line** — `[skill:unzip] done attachmentId=<uuid> entries=<n> uncompressed=<bytes>`.
+7. **Inventory + propose.** Reply to the operator with: top-level entries (first-level subdirectories and top-level files, up to ~20), total file count, total uncompressed bytes. For each entry class, propose **one** concrete follow-up:
+   - `.md`, `.txt` → "ingest into memory via `memory-ingest`?"
+   - `.png`, `.jpg`, `.pdf` → "re-attach via `file-attach` so the user sees the file?"
+   - unknown / binary / source → list only. No proposal.
+
+On any refusal step the operator gets the refusal message verbatim, no re-try, no silent substitution — per the loud-failure protocol in IDENTITY.md.
+
+## Log lines (grep targets)
+
+| When | Line |
+|------|------|
+| Before extraction | `[skill:unzip] start attachmentId=<uuid> dest=<path> declaredBytes=<n>` |
+| On success | `[skill:unzip] done attachmentId=<uuid> entries=<n> uncompressed=<bytes>` |
+| Oversize refusal | `[skill:unzip] oversize attachmentId=<uuid> uncompressed=<bytes> limit=104857600` |
+| Zip-slip refusal | `[skill:unzip] zip-slip-blocked attachmentId=<uuid> entry=<path>` |
+| Symlink refusal | `[skill:unzip] symlink-blocked attachmentId=<uuid> entry=<path>` |
+| Password / corrupt | `[skill:unzip] unreadable attachmentId=<uuid> reason=<password\|corrupt>` |
+
+One `start` pairs with exactly one of `{done, oversize, zip-slip-blocked, symlink-blocked, unreadable}`. A `start` with no matching terminal line indicates the agent was interrupted mid-extraction — investigate by re-running the flow.
+
+## Out of scope
+
+- `tar`, `tar.gz`, `7z`, `rar` — zip only. The `SUPPORTED_MIME_TYPES` allow-list is the gate.
+- Nested-archive recursion — if an extracted file is itself a zip, the operator may manually re-invoke the skill on that file; no auto-recursion.
+- Password-protected archives — refused, never prompted.
+- Public-chat zip uploads — this skill is admin-only; the public agent never sees attachments of this class.

package/payload/platform/plugins/admin/skills/unzip-attachment/references/safety.md

@@ -0,0 +1,81 @@
+# Zip extraction safety reference
+
+This file is the authoritative source for the exact shell commands, attack examples, and refusal messages referenced by [SKILL.md](../SKILL.md). Changes here propagate to every extraction — the skill file inlines none of this so the reference is the single point of truth.
+
+## Attack classes
+
+### 1. Zip slip (path traversal via entry name)
+
+A malicious archive contains an entry whose name starts with `../` (or uses Windows `..\` on some unzip builds). A naive extractor writing relative paths without validation lands the file *outside* the intended destination.
+
+Example listing (`unzip -Z1`):
+```
+good/readme.md
+../../etc/cron.d/malicious
+```
+
+Ground-truth guard: after extraction, for every path under `$dest`, compute `realpath --relative-to "$dest" "<entry>"`. If the relative path begins with `../`, the entry escaped. Refusal line: `[skill:unzip] zip-slip-blocked attachmentId=<uuid> entry=<path>`.
+
+Refusal message to the operator:
+
+> I rejected this archive because one of its entries tried to write outside the extraction directory (zip-slip attack). Entry: `<path>`. No files were kept.
+
+### 2. Symlink escape
+
+A malicious archive contains a symlink entry — for example, a zero-byte file with permission `lrwxrwxrwx` pointing at `/etc/passwd`. If the extractor materialises it, subsequent operations that follow the symlink read or overwrite the target.
+
+Pre-scan detection:
+```sh
+unzip -Z -v "$zip" | awk 'NR>3 && $1 ~ /^l/ { print $NF; found=1 } END { exit !found }'
+```
+First field beginning with `l` is the POSIX symlink flag in the permission column.
+
+Ground-truth backstop:
+```sh
+find "$dest" -mindepth 1 -type l
+```
+Any hit here → refuse even if the pre-scan missed it (defense in depth against `unzip` versions that normalise symlink entries into regular files with `..` payloads, flipping the attack class).
+
+Refusal line: `[skill:unzip] symlink-blocked attachmentId=<uuid> entry=<path>`.
+
+### 3. Decompression bomb
+
+A 42 KB archive expands to 4.5 GB — the classic `42.zip`. Not filesystem-escape but resource exhaustion: fills the account disk, causes OOM on downstream processing.
+
+Pre-scan gate:
+```sh
+unzip -Zt "$zip"
+# → "N files, X bytes uncompressed, Y bytes compressed: Z%"
+```
+Parse the `X bytes uncompressed` field. If `X > 100 * 1024 * 1024` (the `MAX_ZIP_UNCOMPRESSED_BYTES` export from `attachments.ts`), refuse *before* calling `unzip -oq`.
+
+Refusal line: `[skill:unzip] oversize attachmentId=<uuid> uncompressed=<bytes> limit=104857600`.
+
+Note: a hostile archive can lie in its declared sizes. The post-extraction realpath loop runs regardless; if the extraction step itself exhausts disk, `unzip -oq` exits non-zero and the skill refuses with the underlying stderr.
+
+### 4. Password-protected archive
+
+Refused without prompting. `unzip -Z -1` exits non-zero for encrypted entries (or the `-v` listing shows `E` in the attribute column).
+
+Refusal line: `[skill:unzip] unreadable attachmentId=<uuid> reason=password`.
+
+Refusal message:
+
+> This archive is password-protected. Please extract it locally and upload the individual files you want me to look at.
+
+## Canonical commands
+
+| Purpose | Command |
+|---------|---------|
+| Entry list (names only, exits non-zero on password/corrupt) | `unzip -Z -1 "$zip"` |
+| Verbose listing with permission + size columns | `unzip -Z -v "$zip"` |
+| Summary totals parsed for byte-sum gate | `unzip -Zt "$zip"` |
+| Extract | `unzip -oq "$zip" -d "$dest"` |
+| Post-extraction symlink backstop | `find "$dest" -mindepth 1 -type l` |
+| Per-entry zip-slip check | `realpath --relative-to "$dest" "<entry>"` → must not start with `../` |
+
+All of these are from `unzip` (InfoZIP) + `coreutils` — installed on every Pi image by the installer. No additional dependency.
+
+## Why this is a skill, not a tool
+
+Doctrine (Task 664 precedent): the admin agent has `Bash`; the security-critical code path is a sequence of shell commands whose determinism is enforced by the shell primitives themselves, not by LLM reasoning. Wrapping this in an MCP tool would add a translation layer without adding enforcement — and per [feedback_deterministic_means_remove_llm.md](../../../../../.claude/projects/-Users-neo-getmaxy/memory/feedback_deterministic_means_remove_llm.md), a tool wrapper is still LLM-mediated at the decision boundary. The shell script is the deterministic primitive; the skill tells the agent which primitive to invoke, in which order, against which argument.

package/payload/platform/plugins/docs/references/attachments.md

@@ -0,0 +1,44 @@
+# Admin Chat Attachments
+
+What you can drag-and-drop into the admin chat window, what happens to each file, and the size caps.
+
+## Accepted file types
+
+| Type | MIME | Notes |
+|------|------|-------|
+| Images | `image/jpeg`, `image/png`, `image/gif`, `image/webp` | Rendered inline by the agent when relevant. |
+| PDF | `application/pdf` | The agent reads the text; scanned PDFs go via OCR if available. |
+| Plain text, Markdown, CSV, HTML | `text/plain`, `text/markdown`, `text/csv`, `text/html` | Read directly. |
+| Calendar | `text/calendar` | Ingested into the graph if the agent finds a reason to keep it. |
+| Voice note | `audio/*` | Transcribed before the message is routed to the agent. |
+| **Zip archive** | `application/zip`, `application/x-zip-compressed` | Unpacked by the agent after safety checks. See below. |
+
+Anything else is refused at upload time with a message naming the type.
+
+## Size caps
+
+- **Per file:** 20 MB. Enforced at the upload endpoint — files over this limit never reach disk.
+- **Per message:** up to 5 files.
+- **Uncompressed contents of a single zip:** 100 MB. A zip whose declared uncompressed total is over this limit is refused before any byte is extracted (decompression-bomb guard).
+
+## What happens with a zip archive
+
+When you drop a `.zip` into chat, the agent:
+
+1. **Checks the archive is safe.** It refuses archives that try to write outside their own extraction folder, contain symlinks, are password-protected, or declare more than 100 MB of uncompressed content. You'll see the exact reason in chat if any check fails.
+2. **Extracts it to a fresh folder.** Contents land under `{your-account-dir}/extracted/{id}/` — one folder per archive, never mixed.
+3. **Lists what's in it.** The agent tells you the top-level entries, the total file count, and the uncompressed size.
+4. **Asks before doing anything else.** For each class of file (text/markdown, images, PDFs, other), it proposes one next step — for example "ingest these notes into memory" or "re-attach the images back to chat so you can see them" — and waits for you to say yes.
+
+Nothing is ingested, sent, or acted on automatically. The extraction is local and visible; you decide what happens next.
+
+## What is **not** supported
+
+- `tar`, `tar.gz`, `7z`, `rar` — zip only. If you have one of these, unzip/convert locally and upload the zip (or the extracted files directly).
+- Nested archives — a zip-inside-a-zip is extracted one level; you can ask the agent to unpack the inner one afterwards.
+- Password-protected zips — the agent will tell you to unlock locally and re-upload.
+- Uploads larger than 20 MB — split the archive, or upload the individual files.
+
+## Where the files live
+
+Uploads go to `{install-dir}/data/uploads/{account-id}/{file-id}/` — outside the platform wipe zone, so they survive re-installs. Extracted zip contents go to `{account-dir}/extracted/{file-id}/`. Both are local to your device.