slingit 0.1.0

package/README.md

@@ -0,0 +1,60 @@
+# slingit
+
+Fire-and-forget: share formatted Markdown notes via link.
+**Encrypted end-to-end by default** — the AES-256 key lives only in the URL's `#` fragment,
+the server is physically unable to read the content.
+
+```bash
+# Encrypted note — the CLI prints a link with the key in #
+npx slingit shot analysis.md
+
+# With a pipe
+cat analysis.md | npx slingit shot
+
+# Send the link by email (the email contains the full working link)
+npx slingit shot analysis.md --tomail someone@company.com
+
+# Public note: no encryption, server-side render, SEO
+npx slingit shot analysis.md --public
+
+# Delete after 7 days
+npx slingit shot analysis.md --expire 7
+
+# Skill for Claude Code ("send these findings to X's email")
+npx slingit install-skill
+```
+
+## Configuration
+
+**No configuration is required** — the CLI works out of the box with `npx slingit shot`,
+using a built-in public token (an anti-bot filter, not a secret; the real protection is
+the server's rate limits). Overrides, e.g. for a self-hosted instance:
+
+| Source | Keys |
+|---|---|
+| env | `SLINGIT_TOKEN`, `SLINGIT_URL` (defaults to the official SlingIt instance) |
+| `~/.slingit/config.json` | `{ "token": "...", "url": "...", "defaultToMail": "..." }` |
+
+Env takes precedence over the file; the file takes precedence over the built-in values.
+
+## Flags
+
+| Flag | Description | Default |
+|---|---|---|
+| `--public` | Disables encryption, enables server-side render (SEO/preview) | off (encrypted) |
+| `--tomail [email]` | Send the link by email; without a value, uses `defaultToMail` | off |
+| `--expire <days>` | Delete the note after X days (1-365) | no TTL |
+| `--title <text>` | Title (with `--public`, used for preview/SEO) | first `# H1` |
+| `--copy` | Copy the link to the clipboard | off |
+
+## Privacy model
+
+- **Default (encrypted):** content is encrypted with AES-256-GCM locally; only the
+  ciphertext goes to the server. The key in the `#` URL fragment is never sent by the
+  browser — full zero-knowledge.
+- **`--tomail` + encrypted:** the key passes through the server (in transit, not stored)
+  and the mail — a deliberate decision: since the recipient needs the key anyway, they
+  get the full link. Security model: capability URL — whoever has the link can read it.
+- **`--public`:** a deliberate opt-out from encryption (plaintext, SEO, nice preview).
+
+Backend: Cloudflare Workers + R2. Code: `slingit` repo.

package/bin/slingit.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(`slingit: ${err.message}`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "slingit",
+  "version": "0.1.0",
+  "description": "Fire-and-forget: share formatted Markdown notes via link. Encrypted by default (key in #URL), optional email delivery.",
+  "type": "module",
+  "bin": {
+    "slingit": "bin/slingit.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "markdown",
+    "share",
+    "pastebin",
+    "encrypted",
+    "zero-knowledge",
+    "claude-code",
+    "notes"
+  ],
+  "author": "BTA Systems",
+  "license": "MIT"
+}

package/skill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: slingit
+description: Share formatted Markdown notes/analyses via a link (SlingIt). Use when the user asks to send session findings to an email, share an analysis as a link, "slingit this to X", "send these conclusions to Y's email", or "give me a link to this analysis".
+---
+
+# SlingIt — publish notes from the session
+
+You publish formatted Markdown notes with `npx slingit shot`. Each note gets a short
+link `https://slingit.dev/{id}`; by default it is **end-to-end encrypted** — the AES-256
+key lives only in the `#` fragment of the URL, so the server cannot read the content.
+
+## Steps
+
+1. Collect the session's findings into a `.md` file (in a temp/scratchpad directory).
+   Format it properly: `##` headings, code blocks with a language tag (```php, ```ts etc.),
+   first line as `# Title`.
+2. Run the CLI (works out of the box — no token or configuration required):
+   ```bash
+   npx slingit shot <file.md> [flags]
+   ```
+3. Return the full link from stdout to the user in chat (for an encrypted note the link
+   contains the key after `#` — without it the content cannot be decrypted).
+
+## Choosing flags based on the user's intent
+
+| Intent | Flags |
+|---|---|
+| "send it to X's email" | `--tomail X` (the email contains the full working link) |
+| "maximum privacy" | **no** `--tomail` — the default; the link with the key stays in chat only, the user shares it themselves |
+| "public link" (for a PR, docs, SEO) | `--public` (no encryption, server-side render) |
+| "make it disappear after X days" | `--expire X` |
+| title different from the H1 | `--title "..."` |
+
+Flags can be combined, e.g. `--public --tomail x@y.z --expire 7`.
+
+## Rules (do not break these)
+
+- Encryption is the **default** — there is no `--encrypt` flag; `--public` is a deliberate
+  opt-out (use it only when the user explicitly wants a public/indexable note).
+- The encryption key must **never** end up in files, logs, or storage. With `--tomail`,
+  the CLI passes it to the server only in the `mailFragment` field, used solely to compose
+  the link inside the email (transit only, never stored). Do not print the key separately —
+  only as part of the full link.
+- When the user asks for "maximum privacy", skip `--tomail` even if you know the address —
+  zero-knowledge only holds when the key never leaves the terminal/chat.
+- No token is required — the CLI ships with a built-in one. `SLINGIT_TOKEN` (env) or
+  `"token"` in `~/.slingit/config.json` are optional overrides (e.g. a self-hosted
+  instance) — never invent a token.
+
+## Example
+
+```
+> /slingit boss@company.com
+1. Save the findings to analysis.md (with a # Title and language-tagged code blocks)
+2. npx slingit shot analysis.md --tomail boss@company.com
+3. Reply: "Sent. Link (contains the decryption key): https://slingit.dev/aX7k2mQp9f#Hk3..."
+```

package/src/cli.js

@@ -0,0 +1,55 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { shot } from './shot.js';
+import { installSkill } from './install-skill.js';
+
+const HELP = `slingit — share Markdown notes via link (encrypted by default)
+
+Usage:
+  slingit shot [file.md] [flags]     publish a note (file or stdin)
+  slingit install-skill [--project]  install the Claude Code skill
+  slingit help                       this help
+
+Flags (shot):
+  --public           disable encryption: plaintext, server-side render, SEO
+  --tomail [email]   send the link by email (Resend); if omitted, uses
+                     defaultToMail from ~/.slingit/config.json
+  --expire <days>    delete the note after X days (1-365)
+  --title <text>     note title (with --public, used for preview/SEO)
+  --copy             copy the link to the clipboard
+
+Configuration (optional — the CLI works out of the box, no config needed):
+  SLINGIT_TOKEN      override the built-in bearer token (e.g. self-hosted instance)
+  SLINGIT_URL        server address (defaults to the official SlingIt instance)
+  ~/.slingit/config.json  { "token": "...", "url": "...", "defaultToMail": "..." }
+  (environment variables take precedence over the config file)
+
+By default: the note is encrypted with AES-256-GCM locally, the key only ends up
+in the #URL fragment (the server never sees it). --public is a deliberate opt-out.
+`;
+
+export async function main(argv) {
+  const [command, ...rest] = argv;
+
+  switch (command) {
+    case 'shot':
+      return shot(rest);
+    case 'install-skill':
+      return installSkill(rest);
+    case '--version':
+    case '-v': {
+      const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
+      const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+      console.log(pkg.version);
+      return;
+    }
+    case 'help':
+    case '--help':
+    case '-h':
+    case undefined:
+      console.log(HELP);
+      return;
+    default:
+      throw new Error(`unknown command "${command}". See: slingit help`);
+  }
+}

package/src/clipboard.js

@@ -0,0 +1,25 @@
+import { spawn } from 'node:child_process';
+
+/** Copies text to the clipboard using a system tool; returns true on success. */
+export async function copyToClipboard(text) {
+  const candidates =
+    process.platform === 'win32' ? [['clip', []]]
+    : process.platform === 'darwin' ? [['pbcopy', []]]
+    : [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+
+  for (const [cmd, args] of candidates) {
+    const ok = await pipeTo(cmd, args, text);
+    if (ok) return true;
+  }
+  return false;
+}
+
+function pipeTo(cmd, args, text) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: ['pipe', 'ignore', 'ignore'] });
+    child.on('error', () => resolve(false));
+    child.on('close', (code) => resolve(code === 0));
+    child.stdin.on('error', () => resolve(false));
+    child.stdin.end(text);
+  });
+}

package/src/config.js

@@ -0,0 +1,25 @@
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const DEFAULT_URL = 'https://slingit.dev';
+
+// Built-in public token — this is an anti-bot filter, NOT a secret (the npm
+// package is public, so it hides nothing; the real protection is the Worker's rate limits).
+// SLINGIT_TOKEN from env or "token" from ~/.slingit/config.json take precedence.
+const DEFAULT_TOKEN = 'cnViYmVkanVtcGhhcHBlbmVkaG91c2VmbGV3Z2Fzb2xpbmVzaGVsbHNkb2dzdHJpbmc=';
+
+/** Loads ~/.slingit/config.json (optional). Env takes precedence. */
+export async function loadConfig() {
+  let file = {};
+  try {
+    file = JSON.parse(await readFile(join(homedir(), '.slingit', 'config.json'), 'utf8'));
+  } catch {
+    // no file or bad JSON — configuration comes from env only
+  }
+  return {
+    url: (process.env.SLINGIT_URL || file.url || DEFAULT_URL).replace(/\/+$/, ''),
+    token: process.env.SLINGIT_TOKEN || file.token || DEFAULT_TOKEN,
+    defaultToMail: file.defaultToMail || null,
+  };
+}

package/src/crypto.js

@@ -0,0 +1,22 @@
+import { webcrypto as crypto } from 'node:crypto';
+
+/**
+ * Encrypts a note with AES-256-GCM using a random key generated locally.
+ * The key never leaves this process — it's returned to the caller as
+ * base64url to be appended to the #URL fragment.
+ */
+export async function encryptNote(plaintext) {
+  const keyBytes = crypto.getRandomValues(new Uint8Array(32));
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const key = await crypto.subtle.importKey('raw', keyBytes, 'AES-GCM', false, ['encrypt']);
+  const ciphertext = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    new TextEncoder().encode(plaintext)
+  );
+  return {
+    ciphertextB64: Buffer.from(ciphertext).toString('base64'),
+    ivB64: Buffer.from(iv).toString('base64'),
+    keyB64url: Buffer.from(keyBytes).toString('base64url'),
+  };
+}

package/src/install-skill.js

@@ -0,0 +1,24 @@
+import { copyFile, mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Copies SKILL.md to ~/.claude/skills/slingit/ (default)
+ * or ./.claude/skills/slingit/ with --project.
+ */
+export async function installSkill(args) {
+  const project = args.includes('--project');
+  const source = fileURLToPath(new URL('../skill/SKILL.md', import.meta.url));
+  const targetDir = project
+    ? join(process.cwd(), '.claude', 'skills', 'slingit')
+    : join(homedir(), '.claude', 'skills', 'slingit');
+
+  await mkdir(targetDir, { recursive: true });
+  const target = join(targetDir, 'SKILL.md');
+  await copyFile(source, target);
+
+  console.log(`✔ Skill installed: ${target}`);
+  console.log('  In a Claude Code session, ask e.g.: "send these findings to X\'s email" or "/slingit".');
+  console.log('  Works out of the box — no token or configuration needed.');
+}

package/src/shot.js

@@ -0,0 +1,151 @@
+import { readFile } from 'node:fs/promises';
+import { encryptNote } from './crypto.js';
+import { loadConfig } from './config.js';
+import { copyToClipboard } from './clipboard.js';
+
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export async function shot(args) {
+  const opts = parseArgs(args);
+  const config = await loadConfig();
+
+  let sentTo = null;
+  if (opts.tomail !== undefined) {
+    sentTo = opts.tomail || config.defaultToMail;
+    if (!sentTo) {
+      throw new Error('--tomail given without an address and no defaultToMail in ~/.slingit/config.json');
+    }
+    if (!EMAIL_RE.test(sentTo)) throw new Error(`invalid email address: ${sentTo}`);
+  }
+
+  const markdown = await readInput(opts.file);
+  if (!markdown.trim()) throw new Error('empty note — nothing to publish');
+
+  const title = opts.title || extractTitle(markdown);
+
+  const body = {
+    mode: opts.public ? 'public' : 'encrypted',
+    expireDays: opts.expire ?? null,
+    sentTo,
+    sourceSession: process.env.CLAUDE_SESSION_ID || null,
+    sourceCwd: process.cwd(),
+  };
+
+  let key = null;
+  if (opts.public) {
+    body.content = markdown;
+    body.title = title;
+  } else {
+    const { ciphertextB64, ivB64, keyB64url } = await encryptNote(markdown);
+    key = keyB64url;
+    body.content = ciphertextB64;
+    body.encryption = { alg: 'AES-GCM', iv: ivB64, keyDerivation: 'raw-256' };
+    // The key goes to the server ONLY when the user requests email — in transit for the mail body.
+    if (sentTo) body.mailFragment = keyB64url;
+  }
+
+  const res = await postShare(config, body);
+  const link = key ? `${res.url}#${key}` : res.url;
+
+  console.log(link);
+
+  if (sentTo) {
+    if (res.mail?.sent) {
+      console.error(`✉ link sent to ${sentTo}`);
+      if (key) {
+        console.error('  (note: when sending by email, the encryption key passed through the server and the mail — the "anyone with the link can read it" model)');
+      }
+    } else {
+      const reason = res.mail?.detail || res.mail?.error || 'unknown error';
+      console.error(`⚠ mail to ${sentTo} was not sent (${reason}) — share the link manually`);
+    }
+  }
+  if (res.expiresAt) {
+    console.error(`⏳ note expires: ${res.expiresAt}`);
+  }
+  if (opts.copy) {
+    const ok = await copyToClipboard(link);
+    console.error(ok ? '⧉ link copied to clipboard' : '⚠ failed to copy to clipboard');
+  }
+}
+
+function parseArgs(args) {
+  const opts = { file: null, public: false, copy: false, tomail: undefined, expire: null, title: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '--public':
+        opts.public = true;
+        break;
+      case '--copy':
+        opts.copy = true;
+        break;
+      case '--tomail':
+        if (args[i + 1] && !args[i + 1].startsWith('-')) {
+          opts.tomail = args[++i];
+        } else {
+          opts.tomail = null; // use defaultToMail from the config
+        }
+        break;
+      case '--expire': {
+        const days = Number(args[++i]);
+        if (!Number.isInteger(days) || days < 1 || days > 365) {
+          throw new Error('--expire requires a number of days in the range 1-365');
+        }
+        opts.expire = days;
+        break;
+      }
+      case '--title':
+        opts.title = args[++i];
+        if (opts.title === undefined) throw new Error('--title requires a value');
+        break;
+      default:
+        if (a.startsWith('-')) throw new Error(`unknown flag "${a}". See: slingit help`);
+        if (opts.file) throw new Error('only one file can be given');
+        opts.file = a;
+    }
+  }
+  return opts;
+}
+
+async function readInput(file) {
+  if (file) return readFile(file, 'utf8');
+  if (process.stdin.isTTY) {
+    throw new Error('provide a file or pipe content via stdin (e.g. cat note.md | slingit shot)');
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+}
+
+function extractTitle(markdown) {
+  const m = markdown.match(/^#\s+(.+?)\s*$/m);
+  return m ? m[1] : '';
+}
+
+async function postShare(config, body) {
+  let res;
+  try {
+    res = await fetch(`${config.url}/api/share`, {
+      method: 'POST',
+      headers: {
+        authorization: `Bearer ${config.token}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    throw new Error(`could not connect to ${config.url} (${err.cause?.code || err.message})`);
+  }
+  if (!res.ok) {
+    let detail = `HTTP ${res.status}`;
+    try {
+      const err = await res.json();
+      if (err.error) detail = `${err.error} (HTTP ${res.status})`;
+    } catch { /* not JSON — keep just the status */ }
+    if (res.status === 401) detail += ' — token rejected (check SLINGIT_TOKEN or update the slingit package)';
+    if (res.status === 413) detail += ' — note exceeds the 1 MB limit';
+    throw new Error(`server rejected the publish: ${detail}`);
+  }
+  return res.json();
+}