Upload folder using huggingface_hub

client/app.css

@@ -106,12 +106,23 @@ textarea { resize: vertical; }
 }
 
 /* agents panel */
-#agents-pop {
-  position: fixed; z-index: 60; right: 14px; top: 58px; width: 320px;
+#agents-pop, #share-pop {
+  position: fixed; z-index: 60; right: 14px; top: 58px; width: 340px;
   background: var(--surface); border: 1px solid var(--border); border-radius: 12px;
   box-shadow: var(--shadow-md); padding: 14px 16px;
 }
-#agents-pop h3 { margin: 0 0 4px; font-size: 12px; text-transform: uppercase; letter-spacing: 0.07em; color: var(--text-3); }
+#share-pop { right: 90px; }
+#agents-pop h3, #share-pop h3 { margin: 0 0 4px; font-size: 12px; text-transform: uppercase; letter-spacing: 0.07em; color: var(--text-3); }
+#agents-pop .hint, #share-pop .hint { font-size: 12.5px; color: var(--text-2); margin: 0 0 10px; }
+#share-form { display: flex; gap: 6px; margin-top: 10px; }
+.share-row { display: flex; align-items: center; gap: 8px; padding: 5px 0; font-size: 13.5px; }
+.share-row .iconbtn { margin-left: auto; }
+.key-box {
+  margin-top: 10px; border: 1px solid var(--accent); background: var(--accent-soft);
+  border-radius: 8px; padding: 10px 12px; font-size: 12.5px;
+}
+.key-box code { font-family: var(--mono); font-size: 11.5px; word-break: break-all; display: block; margin: 6px 0; }
+.key-box .row { margin-top: 6px; }
 #agents-pop .hint { font-size: 12.5px; color: var(--text-2); margin: 0 0 10px; }
 .agent-row { display: flex; align-items: center; gap: 8px; padding: 5px 0; font-size: 13.5px; }
 .agent-row .dot { width: 7px; height: 7px; border-radius: 50%; background: var(--border-strong); flex-shrink: 0; }

client/doc.html

@@ -30,10 +30,21 @@
     <div id="header-tools"></div>
     <div class="spacer"></div>
     <div id="presence"></div>
+    <button class="btn ghost small" id="share-btn">Share</button>
     <button class="btn ghost small" id="agents-btn">Agents</button>
     <span id="whoami"></span>
   </header>
 
+  <div id="share-pop" class="hidden">
+    <h3>Share</h3>
+    <p class="hint">People you share with can read, edit, comment — and point their own agents at this doc.</p>
+    <div id="share-list" class="muted">loading…</div>
+    <form id="share-form">
+      <input id="share-user" placeholder="Hugging Face username" />
+      <button class="btn small" type="submit">Share</button>
+    </form>
+  </div>
+
   <div id="agents-pop" class="hidden">
     <h3>Agents</h3>
     <p class="hint">Register a handle for your coding agent, copy its prompt, and mention it in any comment: <b>@handle do something</b>.</p>

client/src/common.js

@@ -106,6 +106,32 @@ export function timeAgo(ts) {
   return `${Math.floor(s / 86400)}d`
 }
 
+// One-time display of a freshly issued agent key, with copy actions.
+export function agentKeyBox({ handle, key, docId }) {
+  const box = el('div', { class: 'key-box' })
+  box.appendChild(el('div', {}, `Key for @${handle} — copy it now, it won't be shown again:`))
+  box.appendChild(el('code', {}, key))
+  const row = el('div', { class: 'row' })
+  const copyKey = el('button', { class: 'btn small', type: 'button' }, 'Copy key')
+  copyKey.addEventListener('click', async () => {
+    await navigator.clipboard.writeText(key)
+    copyKey.textContent = 'Copied'
+    setTimeout(() => (copyKey.textContent = 'Copy key'), 1500)
+  })
+  const copyPrompt = el('button', { class: 'btn small primary', type: 'button' }, 'Copy agent prompt (incl. key)')
+  copyPrompt.addEventListener('click', async () => {
+    const text = await fetch(`/api/agent-prompt?handle=${handle}${docId ? `&doc=${docId}` : ''}`).then(r => r.text())
+    await navigator.clipboard.writeText(text.replace('<the key>', key))
+    copyPrompt.textContent = 'Copied'
+    setTimeout(() => (copyPrompt.textContent = 'Copy agent prompt (incl. key)'), 1500)
+  })
+  const dismiss = el('button', { class: 'btn small ghost', type: 'button' }, 'Done')
+  dismiss.addEventListener('click', () => box.remove())
+  row.append(copyKey, copyPrompt, dismiss)
+  box.appendChild(row)
+  return box
+}
+
 export function statusLabel(status) {
   return { pending: 'pending', claimed: 'seen', done: 'handled', failed: 'failed' }[status] || status
 }

client/src/doc.js

@@ -12,7 +12,7 @@ import { ySyncPluginKey, yUndoPluginKey, absolutePositionToRelativePosition, rel
 import { markdownToBlocks } from '../../server/md.js'
 import { Plugin, PluginKey, TextSelection } from '@tiptap/pm/state'
 import { Decoration, DecorationSet } from '@tiptap/pm/view'
-import { initAuth, api, el, icon, colorFor, timeAgo, statusLabel, renderMentionText } from './common.js'
+import { initAuth, api, el, icon, colorFor, timeAgo, statusLabel, renderMentionText, agentKeyBox } from './common.js'
 import { wordDiff, flattenMarkdown } from './diff.js'
 
 const docId = location.pathname.split('/').pop()
@@ -56,6 +56,7 @@ async function main() {
   wireComposer()
   wireSuggestComposer()
   wireAgentsPanel()
+  wireSharePanel()
 
   document.getElementById('show-resolved').addEventListener('change', e => {
     state.showResolved = e.target.checked
@@ -84,13 +85,14 @@ async function main() {
 
   // collapse the active card when clicking outside cards / composers / menus
   document.addEventListener('mousedown', e => {
-    if (e.target.closest('.card, .composer-box, #selection-menu, .mention-menu, #agents-pop, #agents-btn, #link-pop')) return
+    if (e.target.closest('.card, .composer-box, #selection-menu, .mention-menu, #agents-pop, #agents-btn, #share-pop, #share-btn, #link-pop')) return
     if (state.activeItem) {
       state.activeItem = null
       renderMargin(editor)
     }
-    const pop = document.getElementById('agents-pop')
-    if (!pop.classList.contains('hidden')) pop.classList.add('hidden')
+    for (const id of ['agents-pop', 'share-pop']) {
+      document.getElementById(id).classList.add('hidden')
+    }
   })
 
   renderMargin(editor)
@@ -968,10 +970,66 @@ function wireAgentsPanel() {
     else {
       input.value = ''
       refreshAgents()
+      if (res.key) pop.appendChild(agentKeyBox({ handle: res.handle, key: res.key, docId }))
     }
   })
 }
 
+// --- sharing ------------------------------------------------------------------
+
+function wireSharePanel() {
+  const btn = document.getElementById('share-btn')
+  const pop = document.getElementById('share-pop')
+  btn.addEventListener('click', () => {
+    pop.classList.toggle('hidden')
+    if (!pop.classList.contains('hidden')) renderShareList()
+  })
+  document.getElementById('share-form').addEventListener('submit', async e => {
+    e.preventDefault()
+    const input = document.getElementById('share-user')
+    const username = input.value.trim()
+    if (!username) return
+    const res = await api(`/api/docs/${docId}/share`, { method: 'POST', body: { username } })
+    if (res.error) return alert(res.error)
+    input.value = ''
+    renderShareList()
+  })
+}
+
+async function renderShareList() {
+  const meta = await api(`/api/docs/${docId}`)
+  const wrap = document.getElementById('share-list')
+  if (meta.error) {
+    wrap.textContent = meta.error
+    return
+  }
+  const isCreator = !meta.created_by || meta.created_by === state.me.username
+  document.getElementById('share-form').classList.toggle('hidden', !isCreator)
+  wrap.className = ''
+  const rows = []
+  if (meta.created_by) {
+    const owner = el('div', { class: 'share-row' })
+    owner.append(el('span', { class: 'handle' }, meta.created_by), el('span', { class: 'muted' }, 'owner'))
+    rows.push(owner)
+  }
+  for (const username of meta.shared_with || []) {
+    const row = el('div', { class: 'share-row' })
+    row.appendChild(el('span', { class: 'handle' }, username))
+    if (isCreator) {
+      const rm = el('button', { class: 'iconbtn', title: 'Remove access' })
+      rm.appendChild(icon('x'))
+      rm.addEventListener('click', async () => {
+        await api(`/api/docs/${docId}/share`, { method: 'POST', body: { username, remove: true } })
+        renderShareList()
+      })
+      row.appendChild(rm)
+    }
+    rows.push(row)
+  }
+  if (!rows.length) rows.push(el('div', { class: 'muted' }, 'Not shared with anyone yet.'))
+  wrap.replaceChildren(...rows)
+}
+
 async function refreshAgents() {
   const res = await api('/api/agents')
   if (!res.agents) return
@@ -998,6 +1056,15 @@ async function refreshAgents() {
         setTimeout(() => copy.replaceChildren(icon('copy'), document.createTextNode('prompt')), 1500)
       })
       row.appendChild(copy)
+      if (a.owner === state.me.username) {
+        const rot = el('button', { class: 'btn small ghost', title: 'Issue a new key (the old one stops working)' }, 'new key')
+        rot.addEventListener('click', async () => {
+          const res = await api(`/api/agents/${a.handle}/rotate`, { method: 'POST' })
+          if (res.error) alert(res.error)
+          else document.getElementById('agents-pop').appendChild(agentKeyBox({ handle: a.handle, key: res.key, docId }))
+        })
+        row.appendChild(rot)
+      }
       return row
     })
   )

client/src/home.js

@@ -1,12 +1,12 @@
-import { initAuth, api, el, icon, timeAgo } from './common.js'
+import { initAuth, api, el, icon, timeAgo, agentKeyBox } from './common.js'
 
 main()
 
 async function main() {
   const me = await initAuth('/')
   if (!me) return
-  renderDocs()
-  renderAgents()
+  renderDocs(me)
+  renderAgents(me)
 
   document.getElementById('new-doc').addEventListener('click', async () => {
     const title = prompt('Document title?', 'Untitled') || 'Untitled'
@@ -23,12 +23,13 @@ async function main() {
     if (res.error) alert(res.error)
     else {
       input.value = ''
-      renderAgents()
+      renderAgents(me)
+      if (res.key) document.getElementById('agent-form').after(agentKeyBox({ handle: res.handle, key: res.key }))
     }
   })
 }
 
-async function renderDocs() {
+async function renderDocs(me) {
   const res = await api('/api/docs')
   const wrap = document.getElementById('docs-list')
   if (!res.docs?.length) {
@@ -40,7 +41,8 @@ async function renderDocs() {
     ...res.docs.map(d => {
       const a = el('a', { class: 'doc-card', href: `/d/${d.id}` })
       a.appendChild(el('span', { class: 'title' }, d.title || 'Untitled'))
-      a.appendChild(el('span', { class: 'meta' }, `updated ${timeAgo(d.updatedAt)} ago`))
+      const who = d.createdBy && d.createdBy !== me.username ? `by ${d.createdBy} · ` : ''
+      a.appendChild(el('span', { class: 'meta' }, `${who}updated ${timeAgo(d.updatedAt)} ago`))
       const del = el('button', { class: 'iconbtn', title: 'Delete document' })
       del.appendChild(icon('trash'))
       del.addEventListener('click', async e => {
@@ -57,7 +59,7 @@ async function renderDocs() {
   )
 }
 
-async function renderAgents() {
+async function renderAgents(me) {
   const res = await api('/api/agents')
   const wrap = document.getElementById('agents-list')
   if (!res.agents?.length) {
@@ -71,6 +73,15 @@ async function renderAgents() {
       row.appendChild(el('span', { class: `dot${a.online ? ' on' : ''}` }))
       row.appendChild(el('span', { class: 'handle' }, `@${a.handle}`))
       row.appendChild(el('span', { class: 'muted' }, `${a.owner} · ${a.online ? 'online' : 'offline'}`))
+      if (a.owner === me.username) {
+        const rot = el('button', { class: 'btn small ghost' }, 'new key')
+        rot.addEventListener('click', async () => {
+          const res = await api(`/api/agents/${a.handle}/rotate`, { method: 'POST' })
+          if (res.error) alert(res.error)
+          else row.after(agentKeyBox({ handle: a.handle, key: res.key }))
+        })
+        row.appendChild(rot)
+      }
       const copy = el('button', { class: 'btn small ghost copy' })
       copy.append(icon('copy'), document.createTextNode('prompt'))
       copy.addEventListener('click', async () => {

server/api.js

@@ -1,9 +1,15 @@
 import express from 'express'
-import { requireUser, HOST, OAUTH_ENABLED } from './auth.js'
+import { requireUser, requireHuman, HOST, OAUTH_ENABLED } from './auth.js'
 import { HANDLE_RE, DOC_ID_RE } from './util.js'
 import * as store from './store.js'
 import * as collab from './collab.js'
 
+function requireDocAccess(req, res, next) {
+  if (!store.getRegistry()[req.params.id]) return res.status(404).json({ error: 'doc not found' })
+  if (!store.canAccessDoc(req.params.id, req.user.username)) return res.status(404).json({ error: 'doc not found' })
+  next()
+}
+
 export function apiRouter() {
   const router = express.Router()
   router.use(express.json({ limit: '2mb' }))
@@ -13,21 +19,20 @@ export function apiRouter() {
   router.get('/docs', requireUser, (req, res) => {
     const reg = store.getRegistry()
     const docs = Object.entries(reg)
+      .filter(([id]) => store.canAccessDoc(id, req.user.username))
       .map(([id, meta]) => ({ id, ...meta }))
       .sort((a, b) => (b.updatedAt || 0) - (a.updatedAt || 0))
     res.json({ docs })
   })
 
-  router.post('/docs', requireUser, async (req, res) => {
+  router.post('/docs', requireUser, requireHuman, async (req, res) => {
     const title = String(req.body?.title || 'Untitled').slice(0, 120)
     const id = await collab.createDoc(title, req.user.username)
     res.json({ id })
   })
 
-  router.delete('/docs/:id', requireUser, checkDocId, async (req, res) => {
-    const reg = store.getRegistry()
-    const meta = reg[req.params.id]
-    if (!meta) return res.status(404).json({ error: 'doc not found' })
+  router.delete('/docs/:id', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => {
+    const meta = store.getRegistry()[req.params.id]
     if (meta.createdBy && meta.createdBy !== req.user.username) {
       return res.status(403).json({ error: 'only the creator can delete a doc' })
     }
@@ -35,11 +40,36 @@ export function apiRouter() {
     res.json({ ok: true })
   })
 
-  router.get('/docs/:id', requireUser, checkDocId, async (req, res) => {
-    const reg = store.getRegistry()
-    if (!reg[req.params.id]) return res.status(404).json({ error: 'doc not found' })
+  // share / unshare (creator only)
+  router.post('/docs/:id/share', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => {
+    const meta = store.getRegistry()[req.params.id]
+    if (meta.createdBy && meta.createdBy !== req.user.username) {
+      return res.status(403).json({ error: 'only the creator can share a doc' })
+    }
+    const username = String(req.body?.username || '').trim()
+    const remove = req.body?.remove === true
+    if (!/^[a-zA-Z0-9_.-]{2,40}$/.test(username)) return res.status(400).json({ error: 'invalid username' })
+    if (username === req.user.username) return res.status(400).json({ error: 'that is you' })
+    if (!remove && OAUTH_ENABLED) {
+      const check = await fetch(`https://huggingface.co/api/users/${encodeURIComponent(username)}/overview`)
+      if (!check.ok) return res.status(400).json({ error: `no Hugging Face user named "${username}"` })
+    }
+    const current = meta.sharedWith || []
+    const sharedWith = remove ? current.filter(u => u !== username) : [...new Set([...current, username])]
+    store.upsertRegistry(req.params.id, { sharedWith })
+    res.json({ ok: true, shared_with: sharedWith })
+  })
+
+  router.get('/docs/:id', requireUser, checkDocId, requireDocAccess, async (req, res) => {
+    const meta = store.getRegistry()[req.params.id]
     const snapshot = await collab.getDocSnapshot(req.params.id)
-    res.json({ id: req.params.id, title: reg[req.params.id].title, ...snapshot })
+    res.json({
+      id: req.params.id,
+      title: meta.title,
+      created_by: meta.createdBy || null,
+      shared_with: meta.sharedWith || [],
+      ...snapshot,
+    })
   })
 
   // --- image uploads ---
@@ -48,6 +78,7 @@ export function apiRouter() {
     '/docs/:id/upload',
     requireUser,
     checkDocId,
+    requireDocAccess,
     express.raw({ type: 'image/*', limit: '10mb' }),
     (req, res) => {
       if (!Buffer.isBuffer(req.body) || !req.body.length) return res.status(400).json({ error: 'send the image bytes as the request body with an image/* content-type' })
@@ -59,7 +90,7 @@ export function apiRouter() {
 
   // --- comments / replies ---
 
-  router.post('/docs/:id/threads/:tid/reply', requireUser, checkDocId, async (req, res) => {
+  router.post('/docs/:id/threads/:tid/reply', requireUser, checkDocId, requireDocAccess, async (req, res) => {
     const { text, as_agent, mention_id } = req.body || {}
     if (!text || typeof text !== 'string') return res.status(400).json({ error: 'text required' })
     const identity = agentIdentity(req, as_agent)
@@ -78,7 +109,7 @@ export function apiRouter() {
 
   // --- suggestions ---
 
-  router.post('/docs/:id/suggestions', requireUser, checkDocId, async (req, res) => {
+  router.post('/docs/:id/suggestions', requireUser, checkDocId, requireDocAccess, async (req, res) => {
     const { anchor_start, anchor_end, block_index, replacement_markdown, rationale, as_agent, mention_id, thread_id, supersedes } = req.body || {}
     if (typeof replacement_markdown !== 'string') return res.status(400).json({ error: 'replacement_markdown (string) required' })
     if (anchor_start == null && block_index == null && !supersedes) return res.status(400).json({ error: 'pass block_index or anchor_start/anchor_end (from GET /api/docs/:id blocks), or supersedes' })
@@ -102,7 +133,7 @@ export function apiRouter() {
     res.json({ ok: true, suggestion_id: result.suggestion.id })
   })
 
-  router.post('/docs/:id/suggestions/:sid/:action', requireUser, checkDocId, async (req, res) => {
+  router.post('/docs/:id/suggestions/:sid/:action', requireUser, requireHuman, checkDocId, requireDocAccess, async (req, res) => {
     if (!['accept', 'reject', 'reopen'].includes(req.params.action)) return res.status(404).json({ error: 'unknown action' })
     const result = await collab.resolveSuggestionAction(req.params.id, req.params.sid, req.params.action, req.user.username, {
       markOnly: req.body?.mark_only === true,
@@ -117,19 +148,35 @@ export function apiRouter() {
     res.json({ agents: collab.agentPresence() })
   })
 
-  router.post('/agents', requireUser, (req, res) => {
+  router.post('/agents', requireUser, requireHuman, (req, res) => {
     const handle = String(req.body?.handle || '').toLowerCase()
     if (!HANDLE_RE.test(handle)) return res.status(400).json({ error: 'handle must match ' + HANDLE_RE })
     const agents = store.getAgents()
     if (agents[handle] && agents[handle].owner !== req.user.username) {
       return res.status(409).json({ error: 'handle already registered by another user' })
     }
-    agents[handle] = { owner: req.user.username, createdAt: agents[handle]?.createdAt || Date.now() }
+    const key = store.newAgentKey()
+    agents[handle] = {
+      owner: req.user.username,
+      createdAt: agents[handle]?.createdAt || Date.now(),
+      keyHash: store.hashAgentKey(key),
+    }
+    store.saveAgents(agents)
+    res.json({ ok: true, handle, key })
+  })
+
+  router.post('/agents/:handle/rotate', requireUser, requireHuman, (req, res) => {
+    const agents = store.getAgents()
+    const handle = req.params.handle
+    if (!agents[handle]) return res.status(404).json({ error: 'not found' })
+    if (agents[handle].owner !== req.user.username) return res.status(403).json({ error: 'not your handle' })
+    const key = store.newAgentKey()
+    agents[handle].keyHash = store.hashAgentKey(key)
     store.saveAgents(agents)
-    res.json({ ok: true, handle })
+    res.json({ ok: true, handle, key })
   })
 
-  router.delete('/agents/:handle', requireUser, (req, res) => {
+  router.delete('/agents/:handle', requireUser, requireHuman, (req, res) => {
     const agents = store.getAgents()
     const handle = req.params.handle
     if (!agents[handle]) return res.status(404).json({ error: 'not found' })
@@ -143,7 +190,7 @@ export function apiRouter() {
 
   router.get('/mentions', requireUser, async (req, res) => {
     const wait = Math.max(0, Math.min(Number(req.query.wait) || 0, 55))
-    const result = await collab.pollMentions(req.user.username, wait)
+    const result = await collab.pollMentions(req.user.username, wait, req.agent?.handle)
     if (result.error) return res.status(400).json(result)
     res.json(result)
   })
@@ -170,8 +217,15 @@ function checkDocId(req, res, next) {
   next()
 }
 
-// Resolve who a write is attributed to. Agents must own the handle they act as.
+// Resolve who a write is attributed to. Requests authenticated with an
+// app-issued agent key ARE that agent; otherwise as_agent must be owned by the caller.
 function agentIdentity(req, asAgent) {
+  if (req.agent) {
+    if (asAgent && String(asAgent).toLowerCase() !== req.agent.handle) {
+      return { error: `this key belongs to @${req.agent.handle}, not @${asAgent}` }
+    }
+    return { author: req.agent.handle, authorType: 'agent' }
+  }
   if (!asAgent) return { author: req.user.username, authorType: 'user' }
   const handle = String(asAgent).toLowerCase()
   const agents = store.getAgents()
@@ -182,16 +236,17 @@ function agentIdentity(req, asAgent) {
 
 function agentPrompt(docId, handle) {
   const tokenHint = OAUTH_ENABLED
-    ? 'your Hugging Face token (usually already in $HF_TOKEN)'
-    : `the dev token "dev:<your-username>" (no real HF token needed on this dev server)`
+    ? `the agent key that was shown when "@${handle}" was registered (an "ak_..." string; rotate it in the app if lost). It only works for this editor — it is not a Hugging Face credential.`
+    : `the dev token "dev:<your-username>" (no real key needed on this dev server)`
   return `You are the collaborative-editor agent "@${handle}" for the document ${docId} at ${HOST}.
 
 You participate in a shared document, but you NEVER edit the text directly. You only:
   1. reply to comment threads, and
   2. propose suggestions (block replacements) that a human can accept or reject.
 
-Authenticate every request with ${tokenHint}:
-  AUTH='-H "Authorization: Bearer $HF_TOKEN"'
+Authenticate every request with ${tokenHint}
+  export AGENT_KEY=<the key>
+  AUTH='-H "Authorization: Bearer $AGENT_KEY"'
 
 Work loop — repeat until the user tells you to stop:
 

server/auth.js

@@ -54,14 +54,36 @@ export function bearerFromRequest(req) {
   return null
 }
 
-// Express middleware: resolves req.user from session cookie or bearer token.
+// Express middleware: resolves req.user from session cookie, app-issued agent
+// key (Bearer ak_...), or HF token. Agent keys also set req.agent = { handle }.
 export function resolveUser() {
   return async (req, res, next) => {
-    req.user = sessionFromCookieHeader(req.headers.cookie) || (await userFromToken(bearerFromRequest(req)))
+    const session = sessionFromCookieHeader(req.headers.cookie)
+    if (session) {
+      req.user = session
+      return next()
+    }
+    const bearer = bearerFromRequest(req)
+    if (bearer?.startsWith('ak_')) {
+      const { agentByKey } = await import('./store.js')
+      const agent = agentByKey(bearer)
+      if (agent) {
+        req.user = { username: agent.owner, name: agent.owner, avatar: null }
+        req.agent = { handle: agent.handle }
+      }
+      return next()
+    }
+    req.user = await userFromToken(bearer)
     next()
   }
 }
 
+// Some routes are for humans only (accepting suggestions, creating docs, sharing…)
+export function requireHuman(req, res, next) {
+  if (req.agent) return res.status(403).json({ error: 'agent keys cannot perform this action — it requires a signed-in human' })
+  next()
+}
+
 export function requireUser(req, res, next) {
   if (!req.user) return res.status(401).json({ error: 'authentication required (sign in, or pass an HF token as Authorization: Bearer)' })
   next()

server/collab.js

@@ -25,10 +25,18 @@ function persistMentions() {
 
 async function authenticate({ requestHeaders, token, documentName }) {
   if (documentName && !DOC_ID_RE.test(documentName)) throw new Error('bad document name')
-  const user =
-    (await userFromToken(token && token !== 'cookie' ? token : null)) ||
-    sessionFromCookieHeader(requestHeaders?.cookie || requestHeaders?.get?.('cookie'))
+  let user = null
+  if (token && token !== 'cookie') {
+    if (token.startsWith('ak_')) {
+      const agent = store.agentByKey(token)
+      if (agent) user = { username: agent.owner, name: agent.owner, avatar: null }
+    } else {
+      user = await userFromToken(token)
+    }
+  }
+  if (!user) user = sessionFromCookieHeader(requestHeaders?.cookie || requestHeaders?.get?.('cookie'))
   if (!user) throw new Error('unauthorized')
+  if (documentName && !store.canAccessDoc(documentName, user.username)) throw new Error('no access to this document')
   return { user }
 }
 
@@ -108,7 +116,9 @@ function scanDocForMentions(docName, document) {
       const key = `${docName}:${threadId}:${msg.id}`
       if (mentionState.processed[key]) return
       mentionState.processed[key] = true
-      let handles = explicitHandles(msg.text)
+      // an agent only ever receives work for docs its owner can access
+      const ownerCanAccess = h => store.canAccessDoc(docName, agents[h]?.owner)
+      let handles = explicitHandles(msg.text).filter(ownerCanAccess)
       let implicit = false
       if (!handles.length) {
         // No explicit tag: deliver to the ONE agent clearly involved in this
@@ -125,7 +135,7 @@ function scanDocForMentions(docName, document) {
           for (const h of explicitHandles(prev.text)) candidates.add(h)
         }
         if (candidates.size === 1) {
-          handles = [...candidates]
+          handles = [...candidates].filter(ownerCanAccess)
           implicit = true
         }
       }
@@ -292,8 +302,9 @@ async function claimAndEnrich(tasks) {
   return out
 }
 
-export function pollMentions(username, waitSeconds) {
-  const handles = handlesOwnedBy(username)
+export function pollMentions(username, waitSeconds, onlyHandle = null) {
+  let handles = handlesOwnedBy(username)
+  if (onlyHandle) handles = handles.filter(h => h === onlyHandle)
   if (!handles.length) return Promise.resolve({ error: 'no agent handles registered for your account — POST /api/agents first' })
   for (const h of handles) agentLastPoll.set(h, Date.now())
 

server/store.js

@@ -101,7 +101,18 @@ export function upsertRegistry(id, patch) {
   return reg[id]
 }
 
-// --- agent handles ---
+// --- doc access control ---
+
+export function canAccessDoc(id, username) {
+  const meta = getRegistry()[id]
+  if (!meta || !username) return false
+  if (!meta.createdBy) return true // legacy docs created before ACLs
+  return meta.createdBy === username || (meta.sharedWith || []).includes(username)
+}
+
+// --- agent handles + app-issued keys ---
+// agents.json: { handle: { owner, createdAt, keyHash } } — only the sha256 of
+// the key is stored; the plaintext is shown once at registration/rotation.
 
 export function getAgents() {
   return readJSON(AGENTS, {})
@@ -111,6 +122,23 @@ export function saveAgents(agents) {
   writeJSON(AGENTS, agents)
 }
 
+export function hashAgentKey(key) {
+  return crypto.createHash('sha256').update(key).digest('hex')
+}
+
+export function newAgentKey() {
+  return 'ak_' + crypto.randomBytes(24).toString('hex')
+}
+
+export function agentByKey(key) {
+  if (!key?.startsWith('ak_')) return null
+  const hash = hashAgentKey(key)
+  for (const [handle, info] of Object.entries(getAgents())) {
+    if (info.keyHash && info.keyHash === hash) return { handle, owner: info.owner }
+  }
+  return null
+}
+
 // --- mention tasks ---
 // shape: { processed: { [messageId]: true }, tasks: { [mentionId]: task } }
 

test/browser.js

@@ -55,8 +55,22 @@ async function main() {
   await page.fill('#agent-handle', 'ui-agent')
   await page.click('#agent-form button')
   await page.waitForSelector('.agent-row')
+  // registration issues a one-time agent key
+  await page.waitForSelector('.key-box code', { timeout: 5000 })
+  const shownKey = await page.textContent('.key-box code')
+  assert.ok(shownKey.startsWith('ak_'), 'agent key shown once: ' + shownKey.slice(0, 6))
   await page.click('#agents-btn') // close
-  console.log('✓ agent registered via header panel')
+  console.log('✓ agent registered via header panel, key issued')
+
+  // --- sharing UI ---
+  await page.click('#share-btn')
+  await page.waitForSelector('#share-pop:not(.hidden)')
+  await waitFor(async () => (await page.textContent('#share-list')).includes('owner'), 'share list shows owner')
+  await page.fill('#share-user', 'bob')
+  await page.click('#share-form button')
+  await waitFor(async () => (await page.textContent('#share-list')).includes('bob'), 'bob added to share list')
+  await page.click('#share-btn') // close
+  console.log('✓ share panel: add collaborator')
 
   // --- type into the editor ---
   await page.click('.tiptap')

test/prod.js

@@ -57,6 +57,14 @@ async function main() {
 
   const reg = await api('/api/agents', { method: 'POST', body: { handle: HANDLE } })
   assert.equal(reg.ok, true, JSON.stringify(reg))
+  assert.ok(reg.key?.startsWith('ak_'), 'agent key issued')
+  const AGENT = reg.key
+  const agentApi = (path, opts = {}) =>
+    fetch(BASE + path, {
+      method: opts.method || 'GET',
+      headers: { authorization: `Bearer ${AGENT}`, ...(opts.body ? { 'content-type': 'application/json' } : {}) },
+      body: opts.body ? JSON.stringify(opts.body) : undefined,
+    }).then(r => r.json())
 
   const threadId = 'prodth' + Math.random().toString(36).slice(2, 8)
   doc.transact(() => {
@@ -74,28 +82,27 @@ async function main() {
     doc.getMap('threads').set(threadId, t)
   })
 
-  const poll = await api('/api/mentions?wait=15')
+  const poll = await agentApi('/api/mentions?wait=15')
   assert.equal(poll.mentions?.length, 1, JSON.stringify(poll))
   console.log('✓ mention delivered via long-poll')
 
   const snap = await api(`/api/docs/${docId}`)
   assert.ok(snap.blocks?.length >= 2)
 
-  const sugg = await api(`/api/docs/${docId}/suggestions`, {
+  const sugg = await agentApi(`/api/docs/${docId}/suggestions`, {
     method: 'POST',
     body: {
       block_index: 1,
       replacement_markdown: 'Rewritten by the **prod** smoke agent.',
       rationale: 'prod test',
-      as_agent: HANDLE,
       mention_id: poll.mentions[0].mention_id,
       thread_id: threadId,
     },
   })
   assert.equal(sugg.ok, true, JSON.stringify(sugg))
-  const reply = await api(`/api/docs/${docId}/threads/${threadId}/reply`, {
+  const reply = await agentApi(`/api/docs/${docId}/threads/${threadId}/reply`, {
     method: 'POST',
-    body: { text: 'done — see suggestion', as_agent: HANDLE, mention_id: poll.mentions[0].mention_id },
+    body: { text: 'done — see suggestion', mention_id: poll.mentions[0].mention_id },
   })
   assert.equal(reply.ok, true)
   console.log('✓ agent reply + suggestion')
@@ -118,16 +125,15 @@ async function main() {
   )
   const up = await fetch(`${BASE}/api/docs/${docId}/upload`, {
     method: 'POST',
-    headers: { authorization: `Bearer ${TOKEN}`, 'content-type': 'image/png' },
+    headers: { authorization: `Bearer ${AGENT}`, 'content-type': 'image/png' },
     body: pngBytes,
   }).then(r => r.json())
   assert.ok(up.url?.startsWith('/files/'), 'agent upload: ' + JSON.stringify(up))
-  const figSugg = await api(`/api/docs/${docId}/suggestions`, {
+  const figSugg = await agentApi(`/api/docs/${docId}/suggestions`, {
     method: 'POST',
     body: {
       block_index: 1,
       replacement_markdown: `A paragraph with a figure.\n\n![test figure](${up.url})`,
-      as_agent: HANDLE,
     },
   })
   assert.equal(figSugg.ok, true, JSON.stringify(figSugg))

test/smoke.js

@@ -1,5 +1,5 @@
-// End-to-end smoke test: runs the real server, a real Yjs client, and a fake
-// agent talking over the HTTP API. No browser needed.
+// End-to-end smoke test: runs the real server, real Yjs clients, and a fake
+// agent talking over the HTTP API with an app-issued agent key. No browser needed.
 import { spawn } from 'node:child_process'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -70,12 +70,53 @@ async function main() {
   await startServer()
   console.log('✓ server started')
 
-  // 1. create a doc as alice
+  // 1. alice creates a doc
   const { id: docId } = await api('dev:alice', '/api/docs', { method: 'POST', body: { title: 'Smoke Test Doc' } })
   assert.ok(docId, 'doc created')
-  console.log('✓ doc created:', docId)
 
-  // 2. connect as alice over websocket, add a paragraph
+  // 2. ACL: bob cannot see or join the doc before it is shared
+  const denied = await api('dev:bob', `/api/docs/${docId}`)
+  assert.ok(denied.error, 'unshared doc hidden from bob')
+  const bobList = await api('dev:bob', '/api/docs')
+  assert.equal(bobList.docs.length, 0, 'doc list filtered')
+  const sneaky = connect(docId, 'dev:bob')
+  await new Promise(r => setTimeout(r, 1500))
+  assert.equal(sneaky.doc.getXmlFragment('default').length, 0, 'ws sync denied for unshared doc')
+  sneaky.provider.destroy()
+  console.log('✓ ACL: unshared doc invisible to others (list, read, websocket)')
+
+  // 3. alice shares with bob; bob cannot re-share
+  const share = await api('dev:alice', `/api/docs/${docId}/share`, { method: 'POST', body: { username: 'bob' } })
+  assert.equal(share.ok, true, 'share: ' + JSON.stringify(share))
+  const reshare = await api('dev:bob', `/api/docs/${docId}/share`, { method: 'POST', body: { username: 'carol' } })
+  assert.ok(reshare.error, 'only creator can share')
+  const bobRead = await api('dev:bob', `/api/docs/${docId}`)
+  assert.ok(bobRead.markdown != null, 'bob can read after share')
+  console.log('✓ sharing: creator adds bob, bob can read, bob cannot re-share')
+
+  // 4. bob registers an agent handle -> gets an app-issued key
+  const reg = await api('dev:bob', '/api/agents', { method: 'POST', body: { handle: 'test-agent' } })
+  assert.equal(reg.ok, true, 'agent registered: ' + JSON.stringify(reg))
+  assert.ok(reg.key?.startsWith('ak_'), 'agent key issued')
+  const KEY = reg.key
+
+  const steal = await api('dev:alice', '/api/agents', { method: 'POST', body: { handle: 'test-agent' } })
+  assert.ok(steal.error, 'cannot steal a handle')
+
+  // agent keys are agents, not humans
+  const agentDoc = await api(KEY, '/api/docs', { method: 'POST', body: { title: 'nope' } })
+  assert.ok(agentDoc.error, 'agent key cannot create docs')
+  console.log('✓ agent key issued; human-only actions blocked for keys')
+
+  // key rotation invalidates the old key
+  const rotated = await api('dev:bob', '/api/agents/test-agent/rotate', { method: 'POST' })
+  assert.ok(rotated.key?.startsWith('ak_'), 'rotated')
+  const oldKeyPoll = await fetch(`${BASE}/api/mentions`, { headers: { authorization: `Bearer ${KEY}` } })
+  assert.equal(oldKeyPoll.status, 401, 'old key dead after rotation')
+  const AGENT = rotated.key
+  console.log('✓ key rotation works, old key revoked')
+
+  // 5. alice connects over websocket, edits, creates a thread mentioning the agent
   const alice = connect(docId, 'dev:alice')
   const frag = alice.doc.getXmlFragment('default')
   await waitFor(() => frag.length >= 2, 'initial sync')
@@ -87,16 +128,6 @@ async function main() {
   })
   console.log('✓ collab sync + edit works')
 
-  // 3. bob registers an agent handle
-  const reg = await api('dev:bob', '/api/agents', { method: 'POST', body: { handle: 'test-agent' } })
-  assert.equal(reg.ok, true, 'agent registered: ' + JSON.stringify(reg))
-
-  // handle ownership is enforced
-  const steal = await api('dev:alice', '/api/agents', { method: 'POST', body: { handle: 'test-agent' } })
-  assert.ok(steal.error, 'cannot steal a handle')
-  console.log('✓ agent registration + ownership')
-
-  // 4. alice creates a comment thread mentioning the agent (client-side write)
   const threads = alice.doc.getMap('threads')
   const anchorStart = Buffer.from(Y.encodeRelativePosition(Y.createRelativePositionFromTypeIndex(frag, 1))).toString('base64url')
   const anchorEnd = Buffer.from(Y.encodeRelativePosition(Y.createRelativePositionFromTypeIndex(frag, 2))).toString('base64url')
@@ -116,109 +147,82 @@ async function main() {
     threads.set(threadId, t)
   })
 
-  // 5. server should detect the mention and set a pending chip
   await waitFor(() => {
     const msgs = threads.get(threadId)?.get('messages')?.toArray() || []
-    return msgs[0]?.mentions?.length === 1 && ['pending', 'claimed'].includes(msgs[0].mentions[0].status)
+    return msgs[0]?.mentions?.length === 1
   }, 'mention chip')
   console.log('✓ mention detected, chip set')
 
-  // 6. agent (bob) long-polls and receives the mention
-  const poll = await api('dev:bob', '/api/mentions?wait=10')
+  // 6. the agent long-polls with its key
+  const poll = await api(AGENT, '/api/mentions?wait=10')
   assert.equal(poll.mentions?.length, 1, 'mention delivered: ' + JSON.stringify(poll))
   const mention = poll.mentions[0]
   assert.equal(mention.handle, 'test-agent')
-  assert.equal(mention.doc_id, docId)
-  assert.ok(mention.instruction.includes('improve'))
-  console.log('✓ mention long-poll delivery')
-
-  // chip should now read claimed
   await waitFor(() => threads.get(threadId).get('messages').toArray()[0].mentions[0].status === 'claimed', 'claimed chip')
-  console.log('✓ claim acknowledged in doc (👀)')
-
-  // presence: agent should be online
   const agents = await api('dev:alice', '/api/agents')
   assert.equal(agents.agents.find(a => a.handle === 'test-agent')?.online, true, 'agent online')
-  console.log('✓ agent presence online')
-
-  // alice can't poll for bob's agent
-  const wrongPoll = await api('dev:alice', '/api/mentions')
-  assert.ok(wrongPoll.error, 'alice has no handles')
+  console.log('✓ mention long-poll with agent key + claim chip + presence')
 
-  // 7. agent reads the doc
-  const snapshot = await api('dev:bob', `/api/docs/${mention.doc_id}`)
+  // 7. the agent reads the doc with its key
+  const snapshot = await api(AGENT, `/api/docs/${mention.doc_id}`)
   assert.ok(snapshot.markdown.includes('Smoke Test Doc'), 'doc markdown')
-  assert.ok(snapshot.blocks.length >= 2, 'blocks listed')
   assert.ok(snapshot.blocks[1].markdown.includes('quite bad'), 'target block found')
-  console.log('✓ agent doc read (markdown + blocks)')
 
-  // 8. agent proposes a suggestion + replies
-  const sugg = await api('dev:bob', `/api/docs/${docId}/suggestions`, {
+  // 8. suggestion + reply — identity comes from the key, no as_agent needed
+  const sugg = await api(AGENT, `/api/docs/${docId}/suggestions`, {
     method: 'POST',
     body: {
       anchor_start: snapshot.blocks[1].anchor_start,
       anchor_end: snapshot.blocks[1].anchor_end,
       replacement_markdown: 'This **improved** intro cites [Hugging Face](https://huggingface.co) properly.\n\n- one\n- two',
       rationale: 'Clearer wording, added a source.',
-      as_agent: 'test-agent',
       mention_id: mention.mention_id,
       thread_id: mention.thread_id,
     },
   })
   assert.equal(sugg.ok, true, 'suggestion created: ' + JSON.stringify(sugg))
-
-  const reply = await api('dev:bob', `/api/docs/${docId}/threads/${mention.thread_id}/reply`, {
+  const reply = await api(AGENT, `/api/docs/${docId}/threads/${mention.thread_id}/reply`, {
     method: 'POST',
-    body: { text: 'Proposed a rewrite with a source — see suggestions.', as_agent: 'test-agent', mention_id: mention.mention_id },
+    body: { text: 'Proposed a rewrite with a source — see suggestions.', mention_id: mention.mention_id },
   })
   assert.equal(reply.ok, true, 'reply posted')
 
-  // agents cannot act as handles they don't own
   const forged = await api('dev:alice', `/api/docs/${docId}/threads/${mention.thread_id}/reply`, {
     method: 'POST',
     body: { text: 'fake', as_agent: 'test-agent' },
   })
   assert.ok(forged.error, 'as_agent forgery blocked')
-  console.log('✓ suggestion + reply posted, forgery blocked')
+  console.log('✓ suggestion + reply via agent key, forgery blocked')
 
-  // 9. chip flips to done; agent message visible in alice's doc
   await waitFor(() => threads.get(threadId).get('messages').toArray()[0].mentions[0].status === 'done', 'done chip')
   const msgs = threads.get(threadId).get('messages').toArray()
   assert.ok(msgs.some(m => m.authorType === 'agent' && m.author === 'test-agent'), 'agent message in thread')
-  console.log('✓ mention marked done (✅), agent reply in thread')
+  console.log('✓ mention marked done, agent reply attributed to the handle')
 
-  // 9b. implicit follow-up: alice replies in the thread WITHOUT tagging;
-  // the one involved agent gets it anyway, and can dismiss it silently
+  // 9. implicit follow-up + dismiss (still via key)
   alice.doc.transact(() => {
     threads.get(threadId).get('messages').push([
       { id: 'msg-followup', author: 'alice', authorType: 'user', text: 'hmm, can you double check the link?', ts: Date.now() },
     ])
   })
-  const followPoll = await api('dev:bob', '/api/mentions?wait=10')
-  assert.equal(followPoll.mentions?.length, 1, 'follow-up delivered: ' + JSON.stringify(followPoll))
+  const followPoll = await api(AGENT, '/api/mentions?wait=10')
+  assert.equal(followPoll.mentions?.length, 1, 'follow-up delivered')
   assert.equal(followPoll.mentions[0].implicit_follow_up, true, 'marked implicit')
-  const dismissed = await api('dev:bob', `/api/mentions/${followPoll.mentions[0].mention_id}/dismiss`, { method: 'POST' })
-  assert.equal(dismissed.ok, true, 'dismiss works: ' + JSON.stringify(dismissed))
-  await waitFor(() => {
-    const msgs = threads.get(threadId).get('messages').toArray()
-    const follow = msgs.find(m => m.id === 'msg-followup')
-    return follow?.mentions?.[0]?.status === 'done'
-  }, 'follow-up chip done after dismiss')
-  console.log('✓ implicit follow-up delivered + dismissable')
+  const dismissed = await api(AGENT, `/api/mentions/${followPoll.mentions[0].mention_id}/dismiss`, { method: 'POST' })
+  assert.equal(dismissed.ok, true, 'dismiss works')
+  console.log('✓ implicit follow-up delivered + dismissable via key')
 
-  // 10. suggestion visible in client doc, then alice accepts it
+  // 10. agents cannot accept; alice accepts server-side
   const suggMap = alice.doc.getMap('suggestions')
   await waitFor(() => suggMap.size === 1, 'suggestion synced')
   const suggestion = [...suggMap.values()][0]
-  assert.equal(suggestion.status, 'open')
-  assert.ok(suggestion.originalMarkdown.includes('quite bad'), 'original snapshot captured')
-
+  const agentAccept = await api(AGENT, `/api/docs/${docId}/suggestions/${suggestion.id}/accept`, { method: 'POST' })
+  assert.ok(agentAccept.error, 'agent key cannot accept suggestions')
   const accepted = await api('dev:alice', `/api/docs/${docId}/suggestions/${suggestion.id}/accept`, { method: 'POST' })
   assert.equal(accepted.ok, true, 'accept: ' + JSON.stringify(accepted))
-
   await waitFor(() => [...suggMap.values()][0].status === 'accepted', 'suggestion accepted state')
 
-  // 11. the doc content changed and still validates against the tiptap schema
+  // 11. content applied with exact marks, schema-valid
   await waitFor(() => {
     try {
       return yXmlFragmentToProseMirrorRootNode(frag, schema).textContent.includes('improved')
@@ -236,38 +240,32 @@ async function main() {
       if (mark.type.name === 'bold') boldTexts.push(node.text)
     }
   })
-  // marks must cover exactly the marked-up spans — no bleed into following text
-  assert.deepEqual(boldTexts, ['improved'], 'bold covers exactly the bold span: ' + JSON.stringify(boldTexts))
-  assert.deepEqual(linkTexts, ['Hugging Face'], 'link covers exactly the link span: ' + JSON.stringify(linkTexts))
-  assert.ok(pmRoot.textContent.includes('one'), 'list items applied')
-  console.log('✓ accept applied replacement; doc validates against tiptap schema (marks + lists ok)')
+  assert.deepEqual(boldTexts, ['improved'], 'bold covers exactly the bold span')
+  assert.deepEqual(linkTexts, ['Hugging Face'], 'link covers exactly the link span')
+  console.log('✓ accept applied replacement; schema + exact marks ok')
 
-  // 12. double accept is rejected
   const again = await api('dev:alice', `/api/docs/${docId}/suggestions/${suggestion.id}/accept`, { method: 'POST' })
   assert.ok(again.error, 'double accept rejected')
 
-  // 13. persistence across restart
+  // 12. persistence across restart (registry keeps ACL)
   alice.provider.destroy()
   await stopServer()
   await startServer()
-  const after = await api('dev:alice', `/api/docs/${docId}`)
-  assert.ok(after.markdown.includes('improved'), 'content survived restart')
-  assert.ok(after.threads.length === 1 && after.threads[0].messages.length >= 2, 'threads survived restart')
-  console.log('✓ persistence across restart')
-
-  // 14. doc deletion (creator-only)
-  const denied = await api('dev:bob', `/api/docs/${docId}`, { method: 'DELETE' })
-  assert.ok(denied.error, 'non-creator cannot delete')
+  const after = await api('dev:bob', `/api/docs/${docId}`)
+  assert.ok(after.markdown.includes('improved'), 'content + share survived restart')
+  assert.deepEqual(after.shared_with, ['bob'], 'ACL persisted')
+  const afterKey = await api(AGENT, `/api/docs/${docId}`)
+  assert.ok(afterKey.markdown, 'agent key survives restart')
+  console.log('✓ persistence across restart (content, ACL, agent key)')
+
+  // 13. deletion + auth
+  const deniedDel = await api('dev:bob', `/api/docs/${docId}`, { method: 'DELETE' })
+  assert.ok(deniedDel.error, 'non-creator cannot delete')
   const deleted = await api('dev:alice', `/api/docs/${docId}`, { method: 'DELETE' })
   assert.equal(deleted.ok, true, 'creator deletes doc')
-  const gone = await api('dev:alice', `/api/docs/${docId}`)
-  assert.ok(gone.error, 'doc gone after delete')
-  console.log('✓ doc deletion (creator-only)')
-
-  // 15. unauthenticated requests are rejected
   const anon = await fetch(`${BASE}/api/docs`).then(r => r.status)
   assert.equal(anon, 401, 'unauthenticated rejected')
-  console.log('✓ auth required')
+  console.log('✓ deletion (creator-only) + auth required')
 
   await stopServer()
   fs.rmSync(DATA, { recursive: true, force: true })