checkpoint

Author: mgoldsborough

.github/workflows/ci.yml

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Lint
+        run: pnpm lint
+
+      - name: Typecheck
+        run: pnpm typecheck
+
+  test-typescript:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Test
+        run: pnpm test
+
+  test-scanner:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: apps/scanner
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Run tests
+        run: uv run pytest

ASSESSMENT.md

@@ -0,0 +1,98 @@
+# mpak Technical Assessment
+
+**Date:** 2026-02-10
+**Assessor:** Cold-start codebase analysis
+**Scope:** Full project (schemas, SDK, CLI, registry, web, scanner, docs, deploy)
+
+## Reconciliation
+
+**Reconciled:** 2026-02-10, code review against codebase.
+
+Findings:
+- 5 items already fixed in code (#3, #4, #7, #9, #10) that the original assessment missed
+- CI pipeline (#2) exists with lint/typecheck/test jobs
+- TOCTOU (#6) mitigated with pre-check + transaction wrapping
+
+Work completed in this session:
+- #1: Registry test suite added (62 tests across 5 files: errors, oidc, bundles, scanner, health)
+- #5: Filename sanitization added to announce endpoint (path traversal, extension, length checks)
+- #8: ZIP bomb protection added to CLI bundle extraction (500MB uncompressed size limit)
+- #12: CODE_OF_CONDUCT.md created (SECURITY.md already existed)
+- #15: Shell completions added for bash, zsh, fish
+- #16: Rate limiting added (global 100/min, scoped 10/min for /v1/bundles and /v1/skills)
+- 6 items remain open (#11, #13, #14, #17, #18, #19, #20, #21)
+
+## Executive Summary
+
+mpak is a purpose-built package registry for MCP servers with security scanning as a first-class feature. The architecture is thoughtful (layered monorepo, OIDC-only publishing, 25-control trust framework), but the project is pre-launch (14 commits, single contributor, v0.0.0). Core gaps are: no registry tests, no CI pipeline, and several security hardening items that should be resolved before production traffic.
+
+## Strengths
+
+- Clean layered architecture (schemas -> SDK -> CLI, registry standalone)
+- OIDC-only publishing eliminates long-lived API keys
+- Sophisticated scanner with MCP-specific controls (prompt injection detection, undeclared permission scoping)
+- Production deployment story (Helm chart with HPA, security contexts, rate limiting)
+- Comprehensive documentation (36 Starlight pages)
+- Skills concept (knowledge distribution alongside tool distribution)
+
+## Gaps by Priority
+
+### P0: Ship-Blocking
+
+| # | Issue | Location | Effort | Status |
+|---|-------|----------|--------|--------|
+| 1 | Registry server has ~0 test coverage | `apps/registry/tests/` | Large | DONE |
+| 2 | No CI pipeline beyond docs deploy | `.github/workflows/` | Small | DONE |
+| 3 | Scanner callback uses non-constant-time string comparison | `apps/registry/src/routes/scanner.ts` | Trivial | FIXED |
+
+### P1: Pre-Production Quality
+
+| # | Issue | Location | Effort | Status |
+|---|-------|----------|--------|--------|
+| 4 | JWKS not cached in OIDC verification | `apps/registry/src/lib/oidc.ts` | Trivial | FIXED |
+| 5 | Announce endpoint accepts unvalidated os/arch/filename | `apps/registry/src/routes/v1/bundles.ts` | Small | DONE |
+| 6 | TOCTOU race in web publish flow | `apps/registry/src/routes/packages.ts` | Small | MITIGATED |
+| 7 | Search endpoints accept negative limit/offset | `apps/registry/src/routes/v1/bundles.ts` | Trivial | FIXED |
+
+### P2: Security Hardening
+
+| # | Issue | Location | Effort | Status |
+|---|-------|----------|--------|--------|
+| 8 | ZIP extraction has no decompression bomb protection | `packages/cli/src/commands/packages/run.ts` | Small | DONE |
+| 9 | Scanner callback has no idempotency check | `apps/registry/src/routes/scanner.ts` | Trivial | FIXED |
+| 10 | README rendering should explicitly disable HTML | `apps/web/src/pages/PackageDetailPage.tsx` | Trivial | FIXED |
+| 11 | 10 of 25 scanner controls are stubs | `apps/scanner/` | Large | OPEN |
+
+### P3: DX & OSS Readiness
+
+| # | Issue | Location | Effort | Status |
+|---|-------|----------|--------|--------|
+| 12 | Missing SECURITY.md and CODE_OF_CONDUCT.md | repo root | Small | DONE |
+| 13 | Web app has zero tests | `apps/web/` | Medium | OPEN |
+| 14 | CSR-only web app hurts discoverability | `apps/web/` | Large | OPEN |
+| 15 | No shell completions for CLI | `packages/cli/` | Small | DONE |
+| 16 | No API rate limiting at application level | `apps/registry/` | Small | DONE |
+| 17 | No release cut (v0.1.0) | repo root | Trivial | OPEN |
+
+### P4: Polish
+
+| # | Issue | Location | Effort | Status |
+|---|-------|----------|--------|--------|
+| 18 | CLI error messages lack suggestions | `packages/cli/` | Small | OPEN |
+| 19 | Download count tracking not transactional | `apps/registry/src/routes/` | Trivial | OPEN |
+| 20 | Missing package.json metadata on schemas | `packages/schemas/package.json` | Trivial | OPEN |
+| 21 | No architecture decision records | repo root | Medium | OPEN |
+
+## Quick Wins (< 1 hour each)
+
+Items 17, 19, 20 remain as quick wins. Items 2, 3, 4, 7, 9, 10 were already resolved before this session. Items 1, 5, 8, 12, 15, 16 were resolved in this session.
+
+## Architecture Notes
+
+- **Monorepo:** pnpm workspaces + Turborepo
+- **Dep graph:** schemas -> SDK -> CLI; schemas -> registry; web standalone; scanner standalone Python
+- **Auth:** Clerk (web), GitHub OIDC (publish)
+- **Storage:** Local (dev) / S3+CloudFront (prod)
+- **Scanner:** Python 3.13+, runs as K8s Job, 25 MTF controls across 5 domains
+- **Web:** React SPA (Vite + Tailwind 4 + TanStack Query + Clerk)
+- **Docs:** Astro Starlight on GitHub Pages

CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-10
+
+Initial public release of mpak, the open-source MCP bundle registry.
+
+### Added
+
+- **Registry API** (Hono/Bun): package publishing, versioning, scoped namespaces, signed download URLs (S3/CloudFront)
+- **CLI** (`mpak`): `run`, `publish`, `search`, `config`, and `skills install` commands for managing MCP bundles
+- **Web UI** (React Router): search, package detail pages, publish flow, user dashboard
+- **TypeScript SDK** (`@nimblebrain/mpak-sdk`): typed client for the registry API
+- **Security scanner**: automated bundle scanning via Kubernetes jobs with callback-based results
+- **Skill bundles**: `.skill` format for distributing Claude Code skills through the registry
+- **MCPB v0.3 support**: `manifest.json` with `user_config` field definitions and `${user_config.*}` substitution
+- **Zip bomb protection**: uncompressed size check before extraction (500MB limit)
+- **Platform-aware bundles**: per-platform (os/arch) bundle resolution and download
+
+### Known Limitations
+
+- Web UI has no end-to-end test coverage
+- Scanner requires Kubernetes cluster access (not usable in local dev without mocking)

CODE_OF_CONDUCT.md

@@ -0,0 +1,58 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a welcoming experience for everyone, regardless of background or
+identity.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported to the community leaders
+responsible for enforcement at **security@mpak.dev**.
+
+All complaints will be reviewed and investigated promptly and fairly. All
+community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

CONTRIBUTING.md

@@ -115,20 +115,6 @@ chore(ci): update Node.js version in workflows
 
 **Scopes:** `schemas`, `sdk`, `cli`, `registry`, `web`, `scanner`, `docs`, `deploy`, `ci`, `root`
 
-### License Headers
-
-All source files must include an SPDX license header:
-
-```typescript
-// SPDX-License-Identifier: Apache-2.0
-// Copyright 2024 NimbleBrain Inc.
-```
-
-```python
-# SPDX-License-Identifier: Apache-2.0
-# Copyright 2024 NimbleBrain Inc.
-```
-
 ## Reporting Issues
 
 - Use [GitHub Issues](https://github.com/NimbleBrainInc/mpak/issues)