slingit 0.1.1 → 0.2.0

package/README.md

@@ -26,6 +26,9 @@ npx slingit shot analysis.md --public
 # Delete after 7 days
 npx slingit shot analysis.md --expire 7
 
+# Load a note back — prints its Markdown to stdout (decrypts locally, key from #)
+npx slingit pull https://slingit.dev/aX7k2mQp9f#Hk3...
+
 # Skill for Claude Code ("send these findings to X's email")
 npx slingit install-skill
 
@@ -58,6 +61,20 @@ Env takes precedence over the file; the file takes precedence over the built-in
 | `--from <text>` | Optional sender/signature shown on the note page and email | hidden |
 | `--copy` | Copy the link to the clipboard | off |
 
+## Loading a note (`pull`)
+
+```bash
+npx slingit pull <url>
+```
+
+Fetches a published note and prints its Markdown to stdout — handy for pulling an
+analysis another agent slung straight into a session. The note id is read from the URL
+path and, for encrypted notes, the AES key from the `#` fragment: the ciphertext is
+fetched by id alone and decrypted locally, so the key is never sent to the server (same
+zero-knowledge model as the browser reader). Pass the **full link including the part
+after `#`**; `--public` links have no fragment and pull just as well. Expired or missing
+notes produce a clear error and a non-zero exit code.
+
 ## Skill installation
 
 ```bash

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "slingit",
-  "version": "0.1.1",
-  "description": "Fire-and-forget: share formatted Markdown notes via link. Encrypted by default (key in #URL), optional email delivery.",
+  "version": "0.2.0",
+  "description": "Share formatted Markdown notes via link. Encrypted by default (key in #URL), optional email delivery.",
   "type": "module",
   "bin": {
     "slingit": "bin/slingit.js"
   },
+  "scripts": {
+    "test": "node test/unit.mjs"
+  },
   "files": [
     "bin",
     "src",
@@ -26,4 +29,4 @@
   ],
   "author": "BTA Systems",
   "license": "MIT"
-}
+}

package/skill/SKILL.md

@@ -1,14 +1,30 @@
 ---
 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".
+description: Share formatted Markdown notes/analyses via a link (SlingIt), or load one back into the session. 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", "give me a link to this analysis", or to read/load/pull an existing SlingIt link ("load this slingit note", "pull https://slingit.dev/...").
 ---
 
 # 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
+You publish formatted Markdown notes with `npx slingit shot`, and load published
+notes back with `npx slingit pull <url>`. 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.
 
+## Loading a note into the session (`pull`)
+
+When the user gives you a SlingIt link and asks to "load", "read", "pull", or "open"
+the note (e.g. another agent slung an analysis to review), fetch it with:
+
+```bash
+npx slingit pull <url>
+```
+
+It prints the note's Markdown to stdout so you can read it into your context. Pass the
+**full link including the part after `#`** — for encrypted notes the key lives in the
+fragment and decryption happens locally in the CLI (the key is never sent to the
+server). Public links (`--public`) have no key and pull just as well. If the note has
+expired or the link is wrong, `pull` prints a clear error and exits non-zero.
+
 ## Choose the input method first
 
 Use the method that matches the user's request:

package/src/cli.js

@@ -1,12 +1,14 @@
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { shot } from './shot.js';
+import { pull } from './pull.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 pull <url>                 fetch a note by link, print its Markdown to stdout
   slingit install-skill [flags]      install the agent skill
   slingit help                       this help
 
@@ -33,6 +35,10 @@ Configuration (optional — the CLI works out of the box, no config needed):
 
 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.
+
+pull decrypts locally too: it reads the note id from the URL path and the key from
+the #fragment, fetches the ciphertext by id alone, and prints the Markdown. The key
+is never sent to the server. Pass the full link, including the part after #.
 `;
 
 export async function main(argv) {
@@ -41,6 +47,8 @@ export async function main(argv) {
   switch (command) {
     case 'shot':
       return shot(rest);
+    case 'pull':
+      return pull(rest);
     case 'install-skill':
       return installSkill(rest);
     case '--version':

package/src/crypto.js

@@ -20,3 +20,21 @@ export async function encryptNote(plaintext) {
     keyB64url: Buffer.from(keyBytes).toString('base64url'),
   };
 }
+
+/**
+ * Decrypts a note fetched from the server. Mirrors the browser reader:
+ * the AES-256-GCM key comes from the URL #fragment (base64url) and never
+ * touches the server; the IV lives in the note's public metadata (base64).
+ *
+ * @param {ArrayBuffer|Uint8Array} ciphertext raw bytes from GET /{id}.blob
+ * @param {string} keyB64url  32-byte key, base64url, from the #fragment
+ * @param {string} ivB64      12-byte IV, base64, from meta.encryption.iv
+ * @returns {Promise<string>} the decrypted Markdown
+ */
+export async function decryptNote(ciphertext, keyB64url, ivB64) {
+  const keyBytes = Buffer.from(keyB64url, 'base64url');
+  const iv = Buffer.from(ivB64, 'base64');
+  const key = await crypto.subtle.importKey('raw', keyBytes, 'AES-GCM', false, ['decrypt']);
+  const plaintext = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ciphertext);
+  return new TextDecoder().decode(plaintext);
+}

package/src/pull.js

@@ -0,0 +1,109 @@
+import { decryptNote } from './crypto.js';
+
+// Same id shape the Worker route accepts (10–14 url-safe chars).
+const ID_RE = /^[A-Za-z0-9_-]{10,14}$/;
+
+/**
+ * `slingit pull <url>` — fetch a published note and print its Markdown to stdout.
+ *
+ * The note id comes from the URL path and the AES key from the #fragment. The
+ * blob is fetched by id alone (public read, no token) exactly like the browser
+ * reader, so the key never reaches the server — the iron rule stays intact.
+ */
+export async function pull(args) {
+  const { url } = parseArgs(args);
+  const { id, origin, key } = parseUrl(url);
+
+  const meta = await fetchMeta(origin, id);
+  const blob = await fetchBlob(origin, id);
+
+  let markdown;
+  if (meta.mode === 'public') {
+    // Public notes store plaintext Markdown — nothing to decrypt.
+    markdown = Buffer.from(blob).toString('utf8');
+  } else {
+    if (!key) {
+      throw new Error(
+        'this note is encrypted but the link has no key after "#" — you need the full link (including the #fragment) to read it'
+      );
+    }
+    if (!meta.encryption?.iv) {
+      throw new Error('note metadata is missing encryption parameters — cannot decrypt');
+    }
+    try {
+      markdown = await decryptNote(blob, key, meta.encryption.iv);
+    } catch {
+      throw new Error(
+        'could not decrypt the note — the key in the link is wrong or the content is corrupted'
+      );
+    }
+  }
+
+  process.stdout.write(markdown.endsWith('\n') ? markdown : `${markdown}\n`);
+}
+
+function parseArgs(args) {
+  let url = null;
+  for (const a of args) {
+    if (a.startsWith('-')) throw new Error(`unknown flag "${a}". See: slingit help`);
+    if (url) throw new Error('only one URL can be given');
+    url = a;
+  }
+  if (!url) throw new Error('usage: slingit pull <url>');
+  return { url };
+}
+
+function parseUrl(input) {
+  let url;
+  try {
+    url = new URL(input);
+  } catch {
+    throw new Error(`not a valid URL: ${input}`);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new Error(`unsupported URL scheme "${url.protocol}" — expected http(s)`);
+  }
+  const segment = url.pathname.split('/').filter(Boolean).pop() || '';
+  const id = segment.replace(/\.(blob|json|raw)$/, '');
+  if (!ID_RE.test(id)) {
+    throw new Error(`could not find a note id in the URL: ${input}`);
+  }
+  // The key is the whole #fragment, matching the reader's location.hash.slice(1).
+  const key = url.hash ? url.hash.slice(1) : '';
+  return { id, origin: url.origin, key };
+}
+
+async function fetchMeta(origin, id) {
+  const res = await httpGet(`${origin}/${id}.json`);
+  assertNotExpired(res);
+  if (!res.ok) throw new Error(`server returned HTTP ${res.status} for the note metadata`);
+  try {
+    return await res.json();
+  } catch {
+    throw new Error('unexpected response from the server (invalid note metadata)');
+  }
+}
+
+async function fetchBlob(origin, id) {
+  const res = await httpGet(`${origin}/${id}.blob`);
+  assertNotExpired(res);
+  if (!res.ok) throw new Error(`server returned HTTP ${res.status} for the note content`);
+  return res.arrayBuffer();
+}
+
+function assertNotExpired(res) {
+  if (res.status === 410) {
+    throw new Error('this note has expired and is no longer available');
+  }
+  if (res.status === 404) {
+    throw new Error('note not found — the link may be wrong or the note has expired');
+  }
+}
+
+async function httpGet(target) {
+  try {
+    return await fetch(target);
+  } catch (err) {
+    throw new Error(`could not connect to ${new URL(target).origin} (${err.cause?.code || err.message})`);
+  }
+}