@vltpkg/vsr 0.0.0-26

package/info/GRANULAR_ACCESS_TOKENS.md

@@ -0,0 +1,160 @@
+# Granular Access Tokens
+
+All tokens are considered "granular access tokens" (GATs). Token
+entries in the database consist of 3 parts:
+
+- `token` the unique token value
+- `uuid` associative value representing a single user/scope
+- `scope` value representing the granular access/privileges
+
+#### `scope` as a JSON `Object`
+
+A `scope` contains an array of privileges that define both the type(s)
+of & access value(s) for a token.
+
+> [!NOTE] Tokens can be associated with multiple "types" of access
+
+- `type(s)`:
+  - `pkg:read` read associated packages
+  - `pkg:read+write` write associated packages (requires read access)
+  - `user:read` read associated user
+  - `user:read+write` write associated user (requires read access)
+- `value(s)`:
+  - `*` an ANY selector for `user:` or `pkg:` access types
+  - `~<user>` user selector for the `user:` access type
+  - `@<scope>/<pkg>` package specific selector for the `pkg:` access
+    type
+  - `@<scope>/*` glob scope selector for `pkg:` access types
+
+> [!NOTE]
+>
+> - user/org/team management via `@<scope>` is not supported at the
+>   moment
+
+### Granular Access Examples
+
+##### End-user/Subscriber Persona
+
+- specific package read access
+- individual user read+write access
+
+```json
+[
+  {
+    "values": ["@organization/package-name"],
+    "types": {
+      "pkg": {
+        "read": true
+      }
+    }
+  },
+  {
+    "values": ["~johnsmith"],
+    "types": {
+      "user": {
+        "read": true,
+        "write": true
+      }
+    }
+  }
+]
+```
+
+##### Team Member/Maintainer Persona
+
+- scoped package read+write access
+- individual user read+write access
+
+```json
+[
+  {
+    "values": ["@organization/*"],
+    "types": {
+      "pkg": {
+        "read": true
+      }
+    }
+  },
+  {
+    "values": ["~johnsmith"],
+    "types": {
+      "user": {
+        "read": true,
+        "write": true
+      }
+    }
+  }
+]
+```
+
+##### Package Publish CI Persona
+
+- organization scoped packages read+write access
+- individual user read+write access
+
+```json
+[
+  {
+    "values": ["@organization/package-name"],
+    "types": {
+      "pkg": {
+        "read": true
+      }
+    }
+  },
+  {
+    "values": ["~johnsmith"],
+    "types": {
+      "user": {
+        "read": true,
+        "write": true
+      }
+    }
+  }
+]
+```
+
+##### Organization Admin Persona
+
+- organization scoped package read+write access
+- organization users read+write access
+
+```json
+[
+  {
+    "values": ["@company/*"],
+    "types": {
+      "pkg": {
+        "read": true,
+        "write": true
+      },
+      "user": {
+        "read": true,
+        "write": true
+      }
+    }
+  }
+]
+```
+
+##### Registry Owner/Admin Persona
+
+```json
+[
+  {
+    "values": ["*"],
+    "types": {
+      "pkg": {
+        "read": true,
+        "write": true
+      },
+      {
+        "user": {
+          "read": true,
+          "write": true
+        }
+      }
+    }
+  }
+]
+```

package/info/PROJECT_STRUCTURE.md

@@ -0,0 +1,291 @@
+# VSR Project Directory Structure
+
+**VSR** is a minimal "npm-compatible" registry that replicates core
+features of `registry.npmjs.org` while adding new capabilities. It's
+built to run on Cloudflare Workers with D1 database and R2 storage.
+
+## 📁 Root Directory
+
+```
+registry/
+├── config.ts                   # Global application configuration
+├── package.json                # NPM package definition & scripts
+├── wrangler.json               # Cloudflare Workers deployment config
+├── drizzle.config.js           # Database ORM configuration
+├── tsconfig.worker.json        # TypeScript config for Workers environment
+├── types.ts                    # Shared TypeScript type definitions
+├── README.md                   # Project documentation & setup guide
+├── CONTRIBUTING.md             # Development guidelines & workflow
+├── LICENSE                     # FSL-1.1-MIT license
+└── src/                        # Source code directory
+```
+
+### Configuration Files
+
+- **`config.ts`** - Central configuration hub containing:
+  - API documentation settings
+  - Upstream registry definitions (npm, local)
+  - Authentication domains and redirect URIs
+  - Cookie options and security settings
+  - Development server configuration
+
+- **`wrangler.json`** - Cloudflare Workers configuration:
+  - D1 database bindings for SQLite storage
+  - R2 bucket bindings for package tarballs
+  - Queue configurations for background processing
+  - Asset serving and development settings
+
+- **`package.json`** - Project metadata and tooling:
+  - Build scripts for dist creation and asset copying
+  - Database management commands (push, migrate, studio)
+  - Development server orchestration
+  - TypeScript compilation for both Node.js and Workers
+
+## 📁 Source Code (`src/`)
+
+```
+src/
+├── index.ts                    # Main application entry point
+├── api.ts                      # OpenAPI specification
+├── routes/                     # HTTP route handlers
+├── utils/                      # Shared utility functions
+├── db/                         # Database layer
+├── assets/                     # Static files & frontend
+├── bin/                        # CLI executables
+└── schemas/                    # Validation schemas
+```
+
+### Core Application
+
+- **`index.ts`** - Main Hono application setup:
+  - Middleware stack (auth, logging, CORS, security)
+  - Route mounting and organization
+  - Queue consumer for background package refreshing
+  - Health checks and API documentation endpoints
+
+- **`api.ts`** - OpenAPI specification:
+  - REST API definitions for all endpoints
+  - Request/response schemas
+  - Authentication requirements
+  - Used by Scalar for auto-generated documentation
+
+## 📁 Route Handlers (`src/routes/`)
+
+```
+routes/
+├── users.ts                    # User profile management
+├── tokens.ts                   # Authentication token CRUD
+├── packages.ts                 # Package operations (45KB - core logic)
+├── search.ts                   # Package search & discovery
+├── auth.ts                     # OAuth authentication flows
+├── access.ts                   # Access control & permissions
+└── static.ts                   # Static asset serving
+```
+
+### Route Responsibilities
+
+- **`packages.ts`** (Primary) - Core package registry functionality:
+  - Package publishing and unpublishing
+  - Version management and dist-tags
+  - Tarball upload/download via R2
+  - Upstream registry proxying for missing packages
+  - Package metadata validation and transformation
+
+- **`tokens.ts`** - Granular Access Token (GAT) management:
+  - Token creation with scoped permissions
+  - CRUD operations for user tokens
+  - Scope validation (pkg:read/write, user:read/write)
+
+- **`auth.ts`** - Authentication workflows:
+  - OAuth callback handling
+  - Session management
+  - Login/logout flows
+
+- **`access.ts`** - Fine-grained access control:
+  - Package-level permissions
+  - Collaborator management
+  - Access list operations
+
+- **`search.ts`** - Package discovery:
+  - Text-based package searching
+  - Filtering and pagination
+  - Integration with upstream registries
+
+- **`users.ts`** - User management:
+  - Profile retrieval (`/-/whoami`)
+  - User information endpoints
+
+- **`static.ts`** - Asset delivery:
+  - Favicon serving
+  - CSS stylesheet delivery
+  - Image asset routing
+  - robots.txt and manifest files
+
+## 📁 Utilities (`src/utils/`)
+
+```
+utils/
+├── auth.ts                     # Authentication & token verification
+├── cache.ts                    # Package caching strategies (13KB)
+├── database.ts                 # Database connection middleware
+├── packages.ts                 # Package validation & processing (13KB)
+├── response.ts                 # HTTP response formatting
+├── routes.ts                   # Route middleware & guards
+├── spa.ts                      # Single Page Application serving
+├── tracing.ts                  # Request monitoring & performance
+└── upstream.ts                 # Registry proxying & fallback
+```
+
+### Utility Functions
+
+- **`cache.ts`** - Intelligent caching system:
+  - Package metadata caching from upstream registries
+  - Version-specific caching strategies
+  - Cache invalidation and refresh logic
+  - Background queue integration for cache warming
+
+- **`packages.ts`** - Package processing utilities:
+  - NPM package validation
+  - Tarball extraction and analysis
+  - Manifest transformation and normalization
+  - Semver handling and version resolution
+
+- **`upstream.ts`** - Multi-registry support:
+  - Configuration-driven upstream definitions
+  - Fallback logic for missing packages
+  - Request proxying and response transformation
+  - Error handling for upstream failures
+
+- **`auth.ts`** - Security utilities:
+  - Bearer token verification
+  - Scope-based authorization
+  - JWT handling and validation
+
+## 📁 Database Layer (`src/db/`)
+
+```
+db/
+├── client.ts                   # Database client & operations
+├── schema.ts                   # Drizzle schema definitions
+└── migrations/                 # Database migrations
+    ├── 0000_initial.sql       # Base schema creation
+    ├── 0001_uuid_validation.sql # UUID constraints
+    ├── drop.sql               # Development reset script
+    └── meta/                  # Drizzle migration metadata
+        ├── _journal.json      # Migration history
+        ├── 0000_snapshot.json # Schema snapshots
+        └── 0001_snapshot.json
+```
+
+### Database Architecture
+
+- **`schema.ts`** - Core data model:
+  - `packages` table: Package metadata and tags
+  - `versions` table: Version-specific manifests
+  - `tokens` table: Authentication tokens with scoped permissions
+  - Origin tracking (local vs upstream)
+  - Caching timestamps for upstream data
+
+- **`client.ts`** - Database operations:
+  - Drizzle ORM integration
+  - CRUD operations for all entities
+  - Transaction management
+  - Connection pooling for Workers environment
+
+## 📁 Static Assets (`src/assets/`)
+
+```
+assets/
+└── public/
+    ├── images/
+    │   ├── bg.png             # Background image
+    │   ├── clients/           # Package manager logos
+    │   │   ├── logo-npm.png
+    │   │   ├── logo-yarn.png
+    │   │   ├── logo-pnpm.png
+    │   │   ├── logo-bun.png
+    │   │   ├── logo-deno.png
+    │   │   └── logo-vlt.png
+    │   └── favicon/           # Browser icons (multiple formats)
+    │       ├── favicon.ico
+    │       ├── favicon.svg
+    │       ├── apple-touch-icon.png
+    │       ├── favicon-96x96.png
+    │       ├── site.webmanifest
+    │       ├── web-app-manifest-192x192.png
+    │       └── web-app-manifest-512x512.png
+    └── styles/
+        └── styles.css         # Application CSS
+```
+
+### Asset Organization
+
+- **`images/clients/`** - Package manager branding:
+  - Logos for supported package managers
+  - Used in web interface for client recognition
+  - Consistent sizing and format
+
+- **`images/favicon/`** - Browser integration:
+  - Multiple icon formats for cross-platform support
+  - Progressive Web App manifest
+  - Apple touch icons for iOS devices
+
+## 📁 CLI Tools (`src/bin/`)
+
+```
+bin/
+├── vsr.ts                      # Main CLI entry point
+└── demo/                       # Demo project workspace
+    ├── package.json           # Demo dependencies
+    └── vlt.json               # VLT configuration
+```
+
+### Command Line Interface
+
+- **`vsr.ts`** - Development server orchestration:
+  - Spawns both the vlt daemon (port 3000) and wrangler dev
+    (port 1337)
+  - Manages local development environment
+  - Debug mode for verbose logging
+  - Automatic path resolution for monorepo structure
+
+- **`demo/`** - Testing workspace:
+  - Minimal project for vlt server requirements
+  - Used during development to simulate real package operations
+  - Contains basic package.json and vlt configuration
+
+## 📁 Validation (`src/schemas/`)
+
+```
+schemas/
+└── [Currently empty - reserved for future validation schemas]
+```
+
+**Purpose**: Reserved directory for request/response validation
+schemas, likely to be populated with Zod or similar validation
+libraries.
+
+## 🏗️ Architecture Overview
+
+### Request Flow
+
+1. **Static Assets** → Direct serving via Cloudflare Workers
+2. **Package Requests** → Local DB check → Upstream fallback if needed
+3. **Authentication** → Bearer token validation → Scope checking
+4. **Publishing** → Validation → R2 storage → DB metadata update
+
+### Data Flow
+
+- **Local Packages**: Stored in D1 (metadata) + R2 (tarballs)
+- **Upstream Packages**: Cached in D1 with TTL, proxied from npm
+- **Background Jobs**: Queue-based cache refresh for popular packages
+
+### Security Model
+
+- **Granular Access Tokens**: Scoped permissions per package/user
+- **Origin Tracking**: Distinguish local vs upstream packages
+- **Scope Validation**: Package-level and user-level access control
+
+This architecture provides a scalable, serverless npm registry that
+can serve as both a private registry and an intelligent proxy to
+upstream registries like npmjs.org.

package/info/ROADMAP.md

@@ -0,0 +1,27 @@
+### Roadmap
+
+#### v1.0.0
+
+| Status | Feature                                               |
+| :----: | :---------------------------------------------------- |
+|   ⏳   | web: user login (ex. `npm login` / `--auth-type=web`) |
+|   ⏳   | web: user account management (`hosted`)               |
+|   ⏳   | web: user registration (`hosted`)                     |
+|   ⏳   | web: admin user management (`hosted`)                 |
+|   ⏳   | web: package pages                                    |
+|   ⏳   | web: search                                           |
+|   ⏳   | api: rate-limiting                                    |
+
+#### v1.x
+
+| Status | Feature                                   |
+| :----: | :---------------------------------------- |
+|   🕤   | api: package insights (powered by socket) |
+|   🕤   | api: audit (powered by socket)            |
+|   🕤   | mfa access provisioning                   |
+|   🕤   | orgs                                      |
+|   🕤   | teams                                     |
+|   🕤   | staging                                   |
+|   🕤   | events/hooks                              |
+|   🕤   | plugins/middleware                        |
+|   🕤   | variants/distributions                    |

package/info/SUPPORT.md

@@ -0,0 +1,39 @@
+# Supported `npm` Client Commands
+
+| Support | Commannd                                                                                |
+| :-----: | :-------------------------------------------------------------------------------------- |
+|   ✅    | `access`                                                                                |
+|   ✅    | `access list packages`                                                                  |
+|   ✅    | `access get status`                                                                     |
+|   ✅    | `access set status`                                                                     |
+|   🕤    | `access set mfa`                                                                        |
+|   ✅    | `access grant`                                                                          |
+|   ✅    | `access revoke`                                                                         |
+|   🕤    | `adduser` - `PUT /-/org/@<org>/<user>`: Adds/updates a user (requires admin privileges) |
+|   ⏳    | `audit`                                                                                 |
+|   ✅    | `bugs`                                                                                  |
+|   ✅    | `dist-tag add`                                                                          |
+|   ✅    | `dist-tag rm`                                                                           |
+|   ✅    | `dist-tag ls`                                                                           |
+|   ✅    | `deprecate`                                                                             |
+|   ✅    | `docs`                                                                                  |
+|   ✅    | `exec`                                                                                  |
+|   ✅    | `install`                                                                               |
+|   ⏳    | `login`                                                                                 |
+|   ⏳    | `logout`                                                                                |
+|   🕤    | `org`                                                                                   |
+|   ✅    | `outdated`                                                                              |
+|   🕤    | `owner add`                                                                             |
+|   🕤    | `owner rm`                                                                              |
+|   🕤    | `owner ls`                                                                              |
+|   ✅    | `ping`                                                                                  |
+|   🕤    | `profile enable-2fa`                                                                    |
+|   🕤    | `profile disable-2fa`                                                                   |
+|   ✅    | `profile get`                                                                           |
+|   🕤    | `profile set` - `PUT /-/npm/v1/user`: Updates a user (requires auth)                    |
+|   ✅    | `publish`                                                                               |
+|   ✅    | `repo`                                                                                  |
+|   ✅    | `search`                                                                                |
+|   🕤    | `team`                                                                                  |
+|   ✅    | `view`                                                                                  |
+|   ✅    | `whoami`                                                                                |