@crashcontinuum/crashcart-stamp 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# @crashcontinuum/crashcart-stamp
+
+License stamping tool for CrashCart game bundles.
+
+Stamps your `.crashcart` files with a license from [Crash BASIC Arcade](https://arcade.crashbasic.com), embedding your subscription tier and commercial use rights directly into the game.
+
+## Installation
+
+```bash
+# Use directly with npx (no install required)
+npx @crashcontinuum/crashcart-stamp mygame.crashcart
+
+# Or install globally
+npm install -g @crashcontinuum/crashcart-stamp
+crashcart-stamp mygame.crashcart
+```
+
+## Usage
+
+```bash
+crashcart-stamp <crashcart-file> [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-o, --output <file>` | Output file path (default: `<input>.stamped.crashcart`) |
+| `--arcade-url <url>` | Arcade base URL (default: `https://arcade.crashbasic.com`) |
+| `-h, --help` | Show help message |
+| `-v, --version` | Show version number |
+
+### Examples
+
+```bash
+# Stamp a crashcart (creates mygame.stamped.crashcart)
+npx @crashcontinuum/crashcart-stamp mygame.crashcart
+
+# Stamp with custom output filename
+npx @crashcontinuum/crashcart-stamp mygame.crashcart -o mygame-licensed.crashcart
+
+# Use a local development server
+npx @crashcontinuum/crashcart-stamp mygame.crashcart --arcade-url http://localhost:3000
+```
+
+## How It Works
+
+1. **Reads** your CrashCart file and computes its SHA-256 checksum
+2. **Opens** your browser for authentication with Crash BASIC Arcade
+3. **Fetches** a signed license stamp from the Arcade API
+4. **Creates** a stamped copy of your CrashCart (original file unchanged)
+
+The stamp is cryptographically signed and bound to your specific build via the checksum. Any modifications to the CrashCart will invalidate the stamp.
+
+**Note:** The original file is never modified. A new `.stamped.crashcart` file is created.
+
+## License Tiers
+
+| Tier | Commercial Use | Splash Screen | Subscription |
+|------|----------------|---------------|--------------|
+| **Free** | No | 3 seconds, required | Free |
+| **Indie** | Yes | 2 seconds, skippable | Premium ($4.99/mo) |
+| **Studio** | Yes | Removable | Multiplayer ($9.99/mo) |
+
+Upgrade your license at: https://arcade.crashbasic.com/pricing
+
+## Stamped File Format
+
+The stamp is appended to the end of the CrashCart file:
+
+```
+[Original CrashCart Data]
+[CRSTAMP\0 magic - 8 bytes]
+[Stamp length - 4 bytes uint32 LE]
+[JSON stamp data]
+```
+
+The original CrashCart content is not modified, ensuring the stamp can be verified by computing:
+
+```
+checksum = SHA256(file[0:metadataOffset + metadataLength + 64])
+```
+
+## Requirements
+
+- Node.js 18.0.0 or later
+- A Crash BASIC Arcade account (free or paid)
+
+## License
+
+© 2026 Crash Continuum LLC. All rights reserved.

package/bin/crashcart-stamp.mjs

@@ -0,0 +1,739 @@
+#!/usr/bin/env node
+/**
+ * CrashCart License Stamping Tool
+ *
+ * Stamps a .crashcart file with a license from Crash BASIC Arcade.
+ * Opens a browser for authentication, then fetches and applies the license stamp.
+ *
+ * Usage:
+ *   npx crashcart-stamp <crashcart-file> [options]
+ *
+ * Options:
+ *   --arcade-url <url>   Arcade base URL (default: https://arcade.crashbasic.com)
+ *   --output <file>      Output file path (default: <input>.stamped.crashcart)
+ *   --help               Show this help message
+ */
+
+import fs from 'fs';
+import http from 'http';
+import { URL } from 'url';
+import crypto from 'crypto';
+import { exec } from 'child_process';
+import readline from 'readline';
+
+// Configuration
+const DEFAULT_ARCADE_URL = 'https://arcade.crashbasic.com';
+const AUTH_CALLBACK_PORT = 19847; // Random high port for callback
+const STAMP_MAGIC = Buffer.from('CRSTAMP\0'); // 8 bytes: license stamp marker
+
+// CrashCart constants
+const CRASHCART_MAGIC = Buffer.from('CRSHCART');
+const HEADER_SIZE = 96;
+const SIGNATURE_SIZE = 64;
+const NONCE_SIZE = 12;
+const TAG_SIZE = 16;
+const HKDF_INFO = new TextEncoder().encode('crashcart-aes-key');
+
+// Version
+const VERSION = '1.0.0';
+
+/**
+ * Parse command line arguments
+ */
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const options = {
+    inputFile: null,
+    outputFile: null,
+    arcadeUrl: DEFAULT_ARCADE_URL,
+    help: false,
+    version: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+    } else if (arg === '--version' || arg === '-v') {
+      options.version = true;
+    } else if (arg === '--arcade-url' && args[i + 1]) {
+      options.arcadeUrl = args[++i];
+    } else if ((arg === '--output' || arg === '-o') && args[i + 1]) {
+      options.outputFile = args[++i];
+    } else if (!arg.startsWith('-') && !options.inputFile) {
+      options.inputFile = arg;
+    }
+  }
+
+  return options;
+}
+
+/**
+ * Show help message
+ */
+function showHelp() {
+  console.log(`
+CrashCart License Stamping Tool v${VERSION}
+
+Stamps a .crashcart file with a license from Crash BASIC Arcade.
+This embeds your subscription tier and commercial use rights into the game.
+
+USAGE:
+  npx crashcart-stamp <crashcart-file> [options]
+  crashcart-stamp <crashcart-file> [options]
+
+OPTIONS:
+  --arcade-url <url>   Arcade base URL (default: ${DEFAULT_ARCADE_URL})
+  -o, --output <file>  Output file path (default: <input>.stamped.crashcart)
+  -h, --help           Show this help message
+  -v, --version        Show version number
+
+NOTE: The original file is never modified. A stamped copy is always created.
+
+EXAMPLES:
+  # Stamp a crashcart (creates mygame.stamped.crashcart)
+  npx crashcart-stamp mygame.crashcart
+
+  # Stamp with custom output
+  npx crashcart-stamp mygame.crashcart -o mygame-licensed.crashcart
+
+  # Use a different Arcade server (for development)
+  npx crashcart-stamp mygame.crashcart --arcade-url http://localhost:3000
+
+LICENSE TIERS:
+  Free      - Non-commercial use, 3-second splash screen
+  Indie     - Commercial use allowed, 2-second skippable splash
+  Studio    - Commercial use allowed, splash screen removable
+
+Upgrade your license at: ${DEFAULT_ARCADE_URL}/pricing
+`);
+}
+
+/**
+ * Derive AES-256 key from game secret using HKDF-SHA256
+ */
+function deriveKey(gameSecret, salt) {
+  // HKDF extract
+  const prk = crypto.createHmac('sha256', salt).update(gameSecret).digest();
+
+  // HKDF expand (we only need 32 bytes for AES-256)
+  const info = Buffer.concat([HKDF_INFO, Buffer.from([0x01])]);
+  const okm = crypto.createHmac('sha256', prk).update(info).digest();
+
+  return okm.subarray(0, 32);
+}
+
+/**
+ * Decrypt data using AES-256-GCM
+ */
+function decrypt(ciphertext, key, nonce) {
+  // Ciphertext includes the 16-byte auth tag at the end
+  const tag = ciphertext.subarray(ciphertext.length - TAG_SIZE);
+  const encrypted = ciphertext.subarray(0, ciphertext.length - TAG_SIZE);
+
+  const decipher = crypto.createDecipheriv('aes-256-gcm', key, nonce);
+  decipher.setAuthTag(tag);
+
+  const decrypted = Buffer.concat([decipher.update(encrypted), decipher.final()]);
+  return decrypted;
+}
+
+/**
+ * Read and decrypt the CrashCart manifest
+ */
+function readManifest(filePath, gameSecret = null) {
+  const fd = fs.openSync(filePath, 'r');
+  const headerBuf = Buffer.alloc(HEADER_SIZE);
+  fs.readSync(fd, headerBuf, 0, HEADER_SIZE, 0);
+
+  // Verify magic
+  const magic = headerBuf.subarray(0, 8);
+  if (!magic.equals(CRASHCART_MAGIC)) {
+    fs.closeSync(fd);
+    throw new Error('Invalid CrashCart file');
+  }
+
+  const metadataOffset = Number(headerBuf.readBigUInt64LE(16));
+  const metadataLength = Number(headerBuf.readBigUInt64LE(24));
+  const salt = headerBuf.subarray(32, 64);
+
+  // Read encrypted metadata
+  const metadataBuf = Buffer.alloc(metadataLength);
+  fs.readSync(fd, metadataBuf, 0, metadataLength, metadataOffset);
+  fs.closeSync(fd);
+
+  // Extract nonce (first 12 bytes) and ciphertext
+  const nonce = metadataBuf.subarray(0, NONCE_SIZE);
+  const ciphertext = metadataBuf.subarray(NONCE_SIZE);
+
+  // Use provided secret or default to all zeros
+  const secret = gameSecret || Buffer.alloc(32);
+
+  // Derive decryption key
+  const key = deriveKey(secret, salt);
+
+  // Decrypt
+  try {
+    const plaintext = decrypt(ciphertext, key, nonce);
+    return JSON.parse(plaintext.toString('utf8'));
+  } catch (err) {
+    if (!gameSecret) {
+      // If using default (all zeros) failed, the cart might be encrypted
+      throw new Error('ENCRYPTED');
+    }
+    throw new Error('Failed to decrypt manifest - wrong game secret?');
+  }
+}
+
+/**
+ * Prompt for game secret
+ */
+async function promptForSecret() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question('Enter game secret (hex or base64): ', (answer) => {
+      rl.close();
+      const trimmed = answer.trim();
+      if (!trimmed) {
+        resolve(null);
+        return;
+      }
+      // Try to parse as hex first, then base64
+      if (/^[0-9a-fA-F]+$/.test(trimmed) && trimmed.length === 64) {
+        resolve(Buffer.from(trimmed, 'hex'));
+      } else {
+        resolve(Buffer.from(trimmed, 'base64'));
+      }
+    });
+  });
+}
+
+/**
+ * Read and parse CrashCart header to extract game info
+ */
+function readCrashCartHeader(filePath) {
+  const fd = fs.openSync(filePath, 'r');
+  const headerBuf = Buffer.alloc(HEADER_SIZE);
+  fs.readSync(fd, headerBuf, 0, HEADER_SIZE, 0);
+  fs.closeSync(fd);
+
+  // Verify magic bytes
+  const magic = headerBuf.subarray(0, 8);
+  if (!magic.equals(CRASHCART_MAGIC)) {
+    throw new Error('Invalid CrashCart file: bad magic bytes');
+  }
+
+  // Parse header
+  const version = headerBuf.readUInt16LE(8);
+  const flags = headerBuf.readUInt16LE(10);
+  const fileCount = headerBuf.readUInt32LE(12);
+  const metadataOffset = headerBuf.readBigUInt64LE(16);
+  const metadataLength = headerBuf.readBigUInt64LE(24);
+  const salt = headerBuf.subarray(32, 64);
+  const authorKeyHash = headerBuf.subarray(64, 96);
+
+  return {
+    version,
+    flags,
+    fileCount,
+    metadataOffset: Number(metadataOffset),
+    metadataLength: Number(metadataLength),
+    salt: salt.toString('hex'),
+    authorKeyHash: authorKeyHash.toString('hex'),
+  };
+}
+
+/**
+ * Calculate the original CrashCart size from its header.
+ *
+ * The CrashCart format is:
+ *   [Header: 96 bytes]
+ *   [Data section: variable]
+ *   [Metadata section: at metadataOffset, metadataLength bytes]
+ *   [Signature: 64 bytes]
+ *
+ * So original size = metadataOffset + metadataLength + 64
+ *
+ * This is what we checksum, and what the runtime will checksum to verify.
+ */
+function getOriginalCrashCartSize(filePath) {
+  const fd = fs.openSync(filePath, 'r');
+  const headerBuf = Buffer.alloc(HEADER_SIZE);
+  fs.readSync(fd, headerBuf, 0, HEADER_SIZE, 0);
+  fs.closeSync(fd);
+
+  // Verify magic
+  const magic = headerBuf.subarray(0, 8);
+  if (!magic.equals(CRASHCART_MAGIC)) {
+    throw new Error('Invalid CrashCart file');
+  }
+
+  const metadataOffset = headerBuf.readBigUInt64LE(16);
+  const metadataLength = headerBuf.readBigUInt64LE(24);
+
+  // Original size = metadata end + signature
+  return Number(metadataOffset) + Number(metadataLength) + SIGNATURE_SIZE;
+}
+
+/**
+ * Check if crashcart already has a stamp appended
+ */
+function hasExistingStamp(filePath) {
+  const stats = fs.statSync(filePath);
+  const originalSize = getOriginalCrashCartSize(filePath);
+
+  // If file is larger than original CrashCart, there's extra data (stamp)
+  return stats.size > originalSize;
+}
+
+/**
+ * Compute SHA-256 checksum of the original CrashCart content.
+ *
+ * We hash exactly [0, originalSize) bytes - the CrashCart without any stamp.
+ * The runtime does the same calculation to verify the stamp.
+ *
+ * File structure after stamping:
+ *   [Original CrashCart: header + data + metadata + signature] ← checksum this
+ *   [CRSTAMP\0 magic + length + JSON stamp]
+ */
+function computeChecksum(filePath) {
+  const originalSize = getOriginalCrashCartSize(filePath);
+
+  // Read only the original CrashCart bytes
+  const fd = fs.openSync(filePath, 'r');
+  const data = Buffer.alloc(originalSize);
+  fs.readSync(fd, data, 0, originalSize, 0);
+  fs.closeSync(fd);
+
+  const hash = crypto.createHash('sha256');
+  hash.update(data);
+  return hash.digest('hex');
+}
+
+/**
+ * Open browser for authentication
+ */
+function openBrowser(url) {
+  const platform = process.platform;
+
+  let cmd;
+  if (platform === 'darwin') {
+    cmd = `open "${url}"`;
+  } else if (platform === 'win32') {
+    cmd = `start "" "${url}"`;
+  } else {
+    cmd = `xdg-open "${url}"`;
+  }
+
+  exec(cmd, (err) => {
+    if (err) {
+      console.log(`\nCould not open browser automatically.`);
+      console.log(`Please open this URL manually:\n  ${url}\n`);
+    }
+  });
+}
+
+/**
+ * Start local server and wait for auth callback
+ */
+function waitForAuthCallback(arcadeUrl, state) {
+  return new Promise((resolve, reject) => {
+    let timeoutHandle = null;
+
+    const cleanup = () => {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+        timeoutHandle = null;
+      }
+    };
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, `http://localhost:${AUTH_CALLBACK_PORT}`);
+
+      if (url.pathname === '/callback') {
+        const token = url.searchParams.get('token');
+        const returnedState = url.searchParams.get('state');
+        const error = url.searchParams.get('error');
+
+        // Send response to browser
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+
+        if (error) {
+          res.end(`
+            <!DOCTYPE html>
+            <html>
+              <head><meta charset="utf-8"><title>Authentication Failed</title></head>
+              <body style="font-family: system-ui, -apple-system, sans-serif; margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center; background: #f8fafc; color: #1e293b;">
+                <div style="text-align: center; padding: 40px; background: #fff; border-radius: 12px; box-shadow: 0 4px 6px rgba(0,0,0,0.05); max-width: 400px;">
+                  <div style="width: 64px; height: 64px; background: rgba(220, 38, 38, 0.1); border-radius: 50%; display: flex; align-items: center; justify-content: center; margin: 0 auto 20px;">
+                    <span style="font-size: 32px; color: #dc2626;">✕</span>
+                  </div>
+                  <h1 style="color: #dc2626; margin: 0 0 12px; font-size: 24px;">Authentication Failed</h1>
+                  <p style="margin: 0 0 16px; color: #1e293b;">${escapeHtml(error)}</p>
+                  <p style="color: #64748b; margin: 0; font-size: 14px;">You can close this window.</p>
+                </div>
+              </body>
+            </html>
+          `);
+          cleanup();
+          server.close();
+          reject(new Error(error));
+          return;
+        }
+
+        if (returnedState !== state) {
+          res.end(`
+            <!DOCTYPE html>
+            <html>
+              <head><meta charset="utf-8"><title>Security Error</title></head>
+              <body style="font-family: system-ui, -apple-system, sans-serif; margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center; background: #f8fafc; color: #1e293b;">
+                <div style="text-align: center; padding: 40px; background: #fff; border-radius: 12px; box-shadow: 0 4px 6px rgba(0,0,0,0.05); max-width: 400px;">
+                  <div style="width: 64px; height: 64px; background: rgba(220, 38, 38, 0.1); border-radius: 50%; display: flex; align-items: center; justify-content: center; margin: 0 auto 20px;">
+                    <span style="font-size: 32px; color: #dc2626;">✕</span>
+                  </div>
+                  <h1 style="color: #dc2626; margin: 0 0 12px; font-size: 24px;">Security Error</h1>
+                  <p style="margin: 0 0 16px; color: #1e293b;">State mismatch - possible CSRF attack. Please try again.</p>
+                  <p style="color: #64748b; margin: 0; font-size: 14px;">You can close this window.</p>
+                </div>
+              </body>
+            </html>
+          `);
+          cleanup();
+          server.close();
+          reject(new Error('State mismatch'));
+          return;
+        }
+
+        res.end(`
+          <!DOCTYPE html>
+          <html>
+            <head><meta charset="utf-8"><title>Authenticated!</title></head>
+            <body style="font-family: system-ui, -apple-system, sans-serif; margin: 0; min-height: 100vh; display: flex; align-items: center; justify-content: center; background: #f8fafc; color: #1e293b;">
+              <div style="text-align: center; padding: 40px; background: #fff; border-radius: 12px; box-shadow: 0 4px 6px rgba(0,0,0,0.05); max-width: 400px;">
+                <div style="width: 64px; height: 64px; background: rgba(20, 184, 166, 0.1); border-radius: 50%; display: flex; align-items: center; justify-content: center; margin: 0 auto 20px;">
+                  <span style="font-size: 32px; color: #14b8a6;">✓</span>
+                </div>
+                <h1 style="color: #14b8a6; margin: 0 0 12px; font-size: 24px;">Authenticated!</h1>
+                <p style="margin: 0 0 16px; color: #1e293b;">You can close this window and return to your terminal.</p>
+                <p style="color: #64748b; margin: 0; font-size: 14px;">This window will close automatically...</p>
+              </div>
+              <script>setTimeout(() => window.close(), 2000);</script>
+            </body>
+          </html>
+        `);
+
+        cleanup();
+        server.close();
+        resolve(token);
+      } else {
+        res.writeHead(404);
+        res.end('Not found');
+      }
+    });
+
+    server.listen(AUTH_CALLBACK_PORT, '127.0.0.1', () => {
+      console.log(`Waiting for authentication...`);
+    });
+
+    server.on('error', (err) => {
+      cleanup();
+      if (err.code === 'EADDRINUSE') {
+        reject(new Error(`Port ${AUTH_CALLBACK_PORT} is already in use. Please close any other instances.`));
+      } else {
+        reject(err);
+      }
+    });
+
+    // Timeout after 5 minutes
+    timeoutHandle = setTimeout(() => {
+      server.close();
+      reject(new Error('Authentication timed out (5 minutes)'));
+    }, 5 * 60 * 1000);
+  });
+}
+
+/**
+ * Escape HTML to prevent XSS in error messages
+ */
+function escapeHtml(text) {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Authenticate with the Arcade
+ */
+async function authenticate(arcadeUrl) {
+  // Generate state for CSRF protection
+  const state = crypto.randomBytes(16).toString('hex');
+
+  // Build auth URL
+  const callbackUrl = `http://127.0.0.1:${AUTH_CALLBACK_PORT}/callback`;
+  const authUrl = `${arcadeUrl}/auth/cli?callback=${encodeURIComponent(callbackUrl)}&state=${state}`;
+
+  console.log(`\nOpening browser for authentication...`);
+  console.log(`If the browser doesn't open, visit:\n  ${authUrl}\n`);
+
+  openBrowser(authUrl);
+
+  // Wait for callback
+  const token = await waitForAuthCallback(arcadeUrl, state);
+  return token;
+}
+
+/**
+ * Fetch license stamp from Arcade API
+ */
+async function fetchLicenseStamp(arcadeUrl, token, gameId, gameName, checksum) {
+  const stampResponse = await fetch(`${arcadeUrl}/api/license/stamp`, {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${token}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({ gameId, gameName, checksum }),
+  });
+
+  if (!stampResponse.ok) {
+    const error = await stampResponse.json().catch(() => ({}));
+
+    if (stampResponse.status === 401) {
+      throw new Error('Authentication failed. Please try again.');
+    }
+
+    throw new Error(error.error || `Failed to fetch license: ${stampResponse.status}`);
+  }
+
+  return stampResponse.json();
+}
+
+/**
+ * Apply stamp to crashcart file
+ */
+function applyStamp(inputPath, outputPath, stamp) {
+  // Get the original CrashCart size (excludes any existing stamp)
+  const originalSize = getOriginalCrashCartSize(inputPath);
+
+  // Read only the original CrashCart content
+  const fd = fs.openSync(inputPath, 'r');
+  const data = Buffer.alloc(originalSize);
+  fs.readSync(fd, data, 0, originalSize, 0);
+  fs.closeSync(fd);
+
+  // Serialize the stamp
+  const stampJson = JSON.stringify(stamp);
+  const stampData = Buffer.from(stampJson, 'utf8');
+
+  // Build stamp section: [CRSTAMP\0][4-byte length][JSON]
+  const stampLength = Buffer.alloc(4);
+  stampLength.writeUInt32LE(stampData.length, 0);
+
+  const stampSection = Buffer.concat([
+    STAMP_MAGIC,
+    stampLength,
+    stampData,
+  ]);
+
+  // Append stamp to original CrashCart
+  const outputData = Buffer.concat([data, stampSection]);
+
+  // Write output
+  fs.writeFileSync(outputPath, outputData);
+}
+
+/**
+ * Display stamp info
+ */
+function displayStampInfo(stamp) {
+  const tierColors = {
+    free: '\x1b[33m',    // Yellow
+    indie: '\x1b[36m',   // Cyan
+    studio: '\x1b[35m',  // Magenta
+  };
+  const reset = '\x1b[0m';
+  const green = '\x1b[32m';
+  const red = '\x1b[31m';
+  const dim = '\x1b[2m';
+
+  console.log(`\n${'─'.repeat(60)}`);
+  console.log(`License Stamp Applied`);
+  console.log(`${'─'.repeat(60)}`);
+  console.log(`  Game:         ${stamp.gameName}`);
+  console.log(`  Licensee:     ${stamp.licensee}`);
+  console.log(`  Tier:         ${tierColors[stamp.tier] || ''}${stamp.tier.toUpperCase()}${reset}`);
+  console.log(`  Commercial:   ${stamp.features.commercialUse ? green + 'Yes' : red + 'No'}${reset}`);
+  console.log(`  Splash:       ${stamp.features.removeSplash ? green + 'Removable' : stamp.features.skippableSplash ? '2s (skippable)' : '3s (required)'}${reset}`);
+  console.log(`  Build ID:     ${stamp.buildId}`);
+  console.log(`  Checksum:     ${dim}${stamp.gameChecksum.substring(0, 16)}...${reset}`);
+  console.log(`  Built:        ${new Date(stamp.builtAt).toLocaleString()}`);
+  console.log(`${'─'.repeat(60)}\n`);
+}
+
+/**
+ * Display upgrade info for free users
+ */
+function displayUpgradeInfo(arcadeUrl) {
+  console.log(`
+┌─────────────────────────────────────────────────────────────┐
+│                     UPGRADE YOUR LICENSE                     │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Your game has been stamped with a FREE tier license.       │
+│  This means:                                                │
+│    • Non-commercial use only                                │
+│    • 3-second splash screen required                        │
+│                                                             │
+│  Upgrade to unlock:                                         │
+│                                                             │
+│  PREMIUM ($4.99/mo)                                         │
+│    ✓ Commercial use allowed                                 │
+│    ✓ 2-second skippable splash                              │
+│    ✓ Sell your games                                        │
+│                                                             │
+│  MULTIPLAYER ($9.99/mo)                                     │
+│    ✓ Everything in Premium                                  │
+│    ✓ Removable splash screen                                │
+│    ✓ Publish CrashNet multiplayer games                     │
+│                                                             │
+│  Visit: ${arcadeUrl}/pricing
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+`);
+}
+
+
+/**
+ * Main entry point
+ */
+async function main() {
+  const options = parseArgs();
+
+  if (options.version) {
+    console.log(`crashcart-stamp v${VERSION}`);
+    process.exit(0);
+  }
+
+  if (options.help) {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (!options.inputFile) {
+    console.error('Error: No input file specified\n');
+    showHelp();
+    process.exit(1);
+  }
+
+  // Verify input file exists
+  if (!fs.existsSync(options.inputFile)) {
+    console.error(`Error: File not found: ${options.inputFile}`);
+    process.exit(1);
+  }
+
+  // Set default output file
+  if (!options.outputFile) {
+    const inputBase = options.inputFile.replace(/\.crashcart$/i, '');
+    options.outputFile = `${inputBase}.stamped.crashcart`;
+  }
+
+  // Resolve to absolute paths for comparison
+  const inputPath = fs.realpathSync(options.inputFile);
+  const outputPath = fs.existsSync(options.outputFile)
+    ? fs.realpathSync(options.outputFile)
+    : options.outputFile;
+
+  // Never overwrite the input file
+  if (inputPath === outputPath) {
+    console.error(`Error: Output file cannot be the same as input file.`);
+    console.error(`Use -o to specify a different output path.\n`);
+    process.exit(1);
+  }
+
+  console.log(`\n🎮 CrashCart License Stamping Tool v${VERSION}\n`);
+  console.log(`Input:  ${options.inputFile}`);
+  console.log(`Output: ${options.outputFile} (original file unchanged)`);
+
+  try {
+    // Read and validate crashcart
+    console.log(`\nReading CrashCart header...`);
+    const header = readCrashCartHeader(options.inputFile);
+    console.log(`  Version: ${header.version}`);
+    console.log(`  Files: ${header.fileCount}`);
+    console.log(`  Author Key Hash: ${header.authorKeyHash.substring(0, 16)}...`);
+
+    // Check for existing stamp
+    if (hasExistingStamp(options.inputFile)) {
+      console.log(`\n⚠️  This CrashCart already has a license stamp.`);
+      console.log(`   The existing stamp will be replaced.\n`);
+    }
+
+    // Compute checksum of the CrashCart (binds stamp to this specific build)
+    console.log(`\nComputing file checksum...`);
+    const checksum = computeChecksum(options.inputFile);
+    console.log(`  SHA-256: ${checksum.substring(0, 16)}...`);
+
+    // Read manifest to get game info
+    console.log(`\nReading manifest...`);
+    let manifest;
+    try {
+      manifest = readManifest(options.inputFile);
+    } catch (err) {
+      if (err.message === 'ENCRYPTED') {
+        console.log(`  CrashCart is encrypted. Please provide the game secret.`);
+        const secret = await promptForSecret();
+        if (!secret) {
+          console.error('Error: Game secret is required for encrypted CrashCarts');
+          process.exit(1);
+        }
+        manifest = readManifest(options.inputFile, secret);
+      } else {
+        throw err;
+      }
+    }
+
+    const gameId = manifest.gameId;
+    const gameName = manifest.name || manifest.gameId;
+    console.log(`  Game: ${gameName} (${gameId})`);
+
+    if (!gameId) {
+      console.error('Error: Could not read game ID from manifest');
+      process.exit(1);
+    }
+
+    // Authenticate
+    const token = await authenticate(options.arcadeUrl);
+    console.log(`\n✓ Authenticated successfully`);
+
+    // Fetch license stamp (includes checksum)
+    console.log(`\nFetching license stamp for "${gameName}"...`);
+    const stamp = await fetchLicenseStamp(options.arcadeUrl, token, gameId, gameName, checksum);
+
+    // Apply stamp
+    console.log(`Applying stamp to CrashCart...`);
+    applyStamp(options.inputFile, options.outputFile, stamp);
+
+    // Display results
+    displayStampInfo(stamp);
+
+    // Show upgrade info for free tier
+    if (stamp.tier === 'free') {
+      displayUpgradeInfo(options.arcadeUrl);
+    }
+
+    console.log(`✓ Successfully stamped: ${options.outputFile}\n`);
+
+  } catch (error) {
+    console.error(`\n❌ Error: ${error.message}\n`);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@crashcontinuum/crashcart-stamp",
+  "version": "1.0.0",
+  "description": "License stamping tool for CrashCart game bundles",
+  "type": "module",
+  "bin": {
+    "crashcart-stamp": "./bin/crashcart-stamp.mjs"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ],
+  "keywords": [
+    "crashcart",
+    "crashbasic",
+    "crash-basic",
+    "game",
+    "license",
+    "stamp"
+  ],
+  "author": {
+    "name": "Crash Continuum LLC",
+    "url": "https://crashcontinuum.com"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://arcade.crashbasic.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}