papercliped 2.1.0 → 2.2.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Run your Paperclip from Claude: control agents, sync with them and get reports, at the access level you choose.",
   "author": {
     "name": "KpnWorld"

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## v2.2.0 — install the Papercliped plugin while connecting
+
+- **The Papercliped plugin can install itself while you connect.** The "Connect your Paperclip" step has a new box, ticked by default: *Also install the Papercliped plugin in my Paperclip*. After you approve the sign-in, Papercliped asks your Paperclip to install `papercliped-paperclip-plugin` through Paperclip's own installer, using your own approved key. It installs one fixed package at the exact version that matches the service, only if you are the instance admin, and does nothing if the plugin is already there, you are not an admin, or your Paperclip has no plugin support. It never delays or fails your connection, and the outcome is logged as a short `plugin` event (installed, already, denied, unsupported or failed). Untick the box to skip it; installing by hand from Settings → Plugins still works.
+- **Docs tidy-up:** the OAuth flow diagram and the security notes no longer mention a third "Admin" level (there are exactly two: Read only and Full control), and the repository ignores generated files (`openapi.json`, `.wrangler/`, coverage output) so they can't be committed by accident.
+- **Fixed:** the website’s changelog date test only allowed 5–6 October 2026 and would have failed every later release; it now accepts any real date between the first release and today. The package check (`scripts/check-packages.mjs`) also runs on Windows now.
+
 ## v2.1.0 — two access levels, manage in Paperclip, new website
 
 - **Dependencies up to date:** Zod 4 (tool schemas and the ChatGPT Actions OpenAPI now come from Zod's built-in JSON Schema; the published contract is unchanged), the latest MCP SDK, undici 8, TypeScript 7, Vitest 5, React 19 and esbuild 0.28 in the plugin, and GitHub Actions v7. No known vulnerabilities in either package. Dependabot now also watches the website and groups minor and patch updates into one pull request per package.

package/dist/oauth/pages.js

@@ -86,6 +86,10 @@ export function instancePage(v) {
        <label class="f" for="inst">Paperclip address</label>
        <input id="inst" name="instance" type="text" inputmode="url" autocomplete="off" spellcheck="false" placeholder="https://paperclip.example.com" value="${esc(v.value ?? "")}" required>
        <small class="hint">The bridge contacts this address to sign you in and to run what you allow. Only enter an address you own.</small>
+       <label class="f" style="display:flex;gap:10px;align-items:flex-start;margin-top:16px;font-weight:400">
+         <input id="plug" name="install_plugin" type="checkbox" value="on" style="width:auto;margin-top:3px"${v.installPlugin === false ? "" : " checked"}>
+         <span>Also install the Papercliped plugin in my Paperclip<br><small class="hint">Adds a Papercliped page to Paperclip for managing connected apps. It is installed through Paperclip's own installer, only if you are its instance admin, and you can remove it any time from Settings &rarr; Plugins.</small></span>
+       </label>
        <div class="row"><button class="btn" name="action" value="continue">Continue</button>${cancel}</div>
      </form>
      <p class="fine">You'll return to <code>${esc(v.redirectHost)}</code> afterwards.</p>`);

package/dist/oauth/paperclip-login.js

@@ -1,5 +1,7 @@
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 const APPROVAL_PATH = /^\/cli-auth\/[0-9a-f-]{36}\?token=[A-Za-z0-9_\-.~%]{8,300}$/i;
+/** Paperclip runs npm install server-side, which can take a while. */
+const PLUGIN_INSTALL_TIMEOUT_MS = 120_000;
 const TOKENISH = /^[\x21-\x7e]{8,600}$/; // printable ASCII, no whitespace
 export class LoginError extends Error {
     status;
@@ -80,6 +82,42 @@ export class PaperclipLogin {
         const r = await json(await this.t.fetch(`${this.t.apiUrl}/cli-auth/me`, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }, ...this.sig() }));
         return { userId: typeof r?.userId === "string" ? r.userId.slice(0, 200) : null };
     }
+    /**
+     * The Papercliped plugin's state in this Paperclip: absent, or installed with its version.
+     * `unsupported` = no plugin system there (older Paperclip) or the key may not manage plugins.
+     */
+    async pluginState(token, pluginKey) {
+        const res = await this.t.fetch(`${this.t.apiUrl}/plugins`, { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }, ...this.sig() });
+        if (res.status === 403 || res.status === 404)
+            return { state: "unsupported" };
+        const list = await json(res);
+        if (!Array.isArray(list))
+            throw new LoginError("Paperclip returned an unexpected plugin list");
+        const hit = list.find((x) => x && typeof x === "object" && x.pluginKey === pluginKey);
+        if (!hit)
+            return { state: "absent" };
+        return { state: "installed", version: typeof hit.version === "string" ? hit.version.slice(0, 40) : null };
+    }
+    /**
+     * Install one fixed npm package at one exact version through Paperclip's own installer. Only an instance
+     * admin's key is accepted there; anyone else gets a 403, reported as "denied". Nothing user-supplied reaches this call.
+     */
+    async installPlugin(token, packageName, version) {
+        const res = await this.t.fetch(`${this.t.apiUrl}/plugins/install`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify({ packageName, version }),
+            signal: AbortSignal.timeout(Math.max(this.t.timeoutMs, PLUGIN_INSTALL_TIMEOUT_MS)),
+        });
+        if (res.status === 403)
+            return "denied";
+        if (res.status === 404)
+            return "unsupported";
+        const out = await json(res);
+        if (out?.packageName !== packageName)
+            throw new LoginError("Paperclip installed something other than the Papercliped plugin");
+        return "installed";
+    }
     /** Best effort: invalidate the board key we were issued when a grant is revoked. */
     async revoke(token) {
         try {

package/dist/oauth/provider.js

@@ -8,6 +8,7 @@ import { UnsafeUrlError, createSafeFetch, parseInstanceUrl } from "../net/safe-f
 import { Keyring, isValidCodeChallenge, randomToken, safeEqual, sha256Hex, verifyPkce } from "./crypto.js";
 import { approvePage, choosePage, consentPage, errorPage, instancePage, scopePage, secretPage, usernamePage, welcomePage } from "./pages.js";
 import { LoginError, PaperclipLogin } from "./paperclip-login.js";
+import { VERSION } from "../version.js";
 import { MemoryStore } from "./store.js";
 import { SCOPES, grantableScopes, isScope, maxRank, normalizeScope, normalizeScopes, scopeAllows, scopesUpTo } from "./scopes.js";
 const LOOPBACK = new Set(["localhost", "127.0.0.1", "[::1]"]);
@@ -15,6 +16,12 @@ const PENDING_TTL_MS = 10 * 60_000;
 const CODE_TTL_MS = 60_000;
 const MAX_PENDING = 5000;
 const MAX_INSTANCE_ATTEMPTS = 5;
+/** The plugin offered on the instance step: one fixed package, pinned to this bridge's own version (both are released together). */
+const PLUGIN_PACKAGE = "papercliped-paperclip-plugin";
+/** Its id inside Paperclip (the manifest id), used to see whether it is already installed. */
+const PLUGIN_KEY = "papercliped.remote-control";
+/** Paperclip runs npm on its side for an install; allow it more time than ordinary calls. */
+const PLUGIN_INSTALL_MS = 120_000;
 const MAX_FORM_BYTES = 16 * 1024;
 const DAY_MS = 24 * 3600 * 1000;
 class OAuthError extends Error {
@@ -58,6 +65,10 @@ export class OAuthProvider {
     keyring;
     now;
     safeFetch;
+    /** Longer-lived egress-guarded fetch for the plugin install, which makes Paperclip run npm. */
+    installFetch;
+    /** Plugin installs running after a sign-in finished, so tests (and shutdown) can wait for them. */
+    background = new Set();
     multi;
     accounts;
     constructor(deps) {
@@ -68,6 +79,7 @@ export class OAuthProvider {
         this.multi = deps.oauth.mode === "multi";
         this.accounts = deps.oauth.accounts && this.multi;
         this.safeFetch = deps.safeFetch ?? createSafeFetch({ timeoutMs: deps.config.timeoutMs, maxBytes: 2_000_000 });
+        this.installFetch = deps.safeFetch ?? createSafeFetch({ timeoutMs: PLUGIN_INSTALL_MS, maxBytes: 200_000 });
         this.resource = `${deps.oauth.issuer}/mcp`;
         this.metadataUrl = `${deps.oauth.issuer}/.well-known/oauth-protected-resource`;
     }
@@ -389,6 +401,46 @@ export class OAuthProvider {
             throw new UnsafeUrlError("This service is not open to that host yet.");
         return u;
     }
+    /** Wait for plugin installs that are still running (tests and graceful shutdown). */
+    async drainBackground() {
+        await Promise.allSettled([...this.background]);
+    }
+    /**
+     * Install the Papercliped plugin into the user's Paperclip after they approved the sign-in and ticked the box.
+     * Runs after the page has been answered: npm can take a while on their side, and the connection must not wait for it
+     * or fail because of it. The outcome is recorded as a "plugin" event and never carries anything but a short word.
+     */
+    installPluginLater(p, token) {
+        const instanceUrl = p.instanceUrl;
+        if (!instanceUrl)
+            return;
+        const accountId = p.accountId ?? null;
+        const run = (async () => {
+            let outcome = "failed";
+            try {
+                const login = this.pluginLoginFor(instanceUrl);
+                const now = await login.pluginState(token, PLUGIN_KEY);
+                if (now.state === "unsupported")
+                    outcome = "unsupported";
+                else if (now.state === "installed")
+                    outcome = "already";
+                else
+                    outcome = await login.installPlugin(token, PLUGIN_PACKAGE, VERSION);
+            }
+            catch {
+                outcome = "failed";
+            }
+            await this.event("plugin", await this.who(accountId), outcome);
+        })();
+        const tracked = run.finally(() => this.background.delete(tracked));
+        this.background.add(tracked);
+    }
+    pluginLoginFor(instanceUrl) {
+        if (this.deps.loginFor)
+            return this.deps.loginFor(instanceUrl);
+        const origin = this.checkedInstance(instanceUrl).origin; // re-validated: policy can tighten between steps
+        return new PaperclipLogin({ apiUrl: `${origin}/api`, publicOrigin: origin, fetch: this.installFetch, timeoutMs: PLUGIN_INSTALL_MS });
+    }
     loginFor(instanceUrl) {
         if (this.deps.loginFor)
             return this.deps.loginFor(instanceUrl);
@@ -753,7 +805,7 @@ export class OAuthProvider {
         const c = this.ctx(rid, p, error);
         switch (p.stage) {
             case "instance":
-                return this.page(res, status, instancePage({ ...c, value: extra.value, notice: extra.notice }), p);
+                return this.page(res, status, instancePage({ ...c, value: extra.value, notice: extra.notice, installPlugin: p.installPlugin }), p);
             case "approve": {
                 const ch = this.unsealChallenge(p);
                 if (!ch || !p.instanceUrl) {
@@ -912,6 +964,7 @@ export class OAuthProvider {
             return this.html(res, 429, errorPage("Too many attempts", "Too many addresses tried. Start again from the app."));
         }
         p.attempts += 1;
+        p.installPlugin = f.get("install_plugin") === "on";
         const typed = (f.get("instance") ?? "").slice(0, 300);
         const fail = async (why, detail) => {
             await this.store.putPending(rid, p);
@@ -978,6 +1031,8 @@ export class OAuthProvider {
         }
         if (!userId)
             return this.renderStage(res, rid, p, "Paperclip did not say who you are, so we can't link a username to it.");
+        if (p.installPlugin)
+            this.installPluginLater(p, ch.boardApiToken);
         const owner = await this.store.getLinkByIdentity(p.instanceUrl, userId);
         if (p.accountId) {
             // Reconnecting an account the user already signed in to with their secret key.

package/docs/SECURITY.md

@@ -3,7 +3,7 @@
 Read this before running the bridge for people other than yourself.
 
 ## What you are holding
-For every connected user the bridge stores a **Paperclip board API key**. In Paperclip that key is bound to the *user*, not to a company, and carries **all** of that user's board power (verified in Paperclip's source: `board_api_keys` has no scope column, and the challenge's `requestedCompanyId` is only used to attribute activity-log entries, not to restrict the key). The bridge's scopes (read/control/admin) limit what *connected AI clients* may do through the bridge. They do **not** limit what the stored key can do if the bridge itself is compromised.
+For every connected user the bridge stores a **Paperclip board API key**. In Paperclip that key is bound to the *user*, not to a company, and carries **all** of that user's board power (verified in Paperclip's source: `board_api_keys` has no scope column, and the challenge's `requestedCompanyId` is only used to attribute activity-log entries, not to restrict the key). The bridge's two access levels (Read only and Full control) limit what *connected AI clients* may do through the bridge. They do **not** limit what the stored key can do if the bridge itself is compromised.
 
 > **Headline risk:** a full compromise of the running bridge (code execution on the Render service *and* access to its environment) exposes every connected user's Paperclip with full board access, until those keys are revoked. Everything below reduces the likelihood or blast radius; none of it removes that risk. Until Paperclip offers scoped/short-lived keys, tell users plainly, encourage a dedicated Paperclip user for the connection, and keep the user base small enough to be comfortable with that.
 

package/docs/oauth.md

@@ -7,7 +7,7 @@ client ──401 + resource_metadata──▶ bridge /mcp
 client ──DCR /register──────────────▶ bridge
 client ──/authorize (PKCE S256)─────▶ bridge ──create challenge──▶ Paperclip /api/cli-auth/challenges
 user   ── opens approvalUrl, signs in to Paperclip, approves ─────▶ Paperclip
-user   ── picks Read / Control / Admin, presses Allow ───────────▶ bridge (verifies approval, checks token)
+user   ── picks Read only / Full control, presses Allow ────────▶ bridge (verifies approval, checks token)
 client ──/token (code + verifier)───▶ bridge ──▶ opaque access + rotating refresh token
 client ──/mcp  Bearer pcb_at_…──────▶ bridge ──user's board token──▶ Paperclip
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "Papercliped — connect Claude, ChatGPT and any MCP app to your Paperclip: control agents, sync, report. MCP server + hosted multi-tenant OAuth bridge + public stats API.",
   "license": "MIT",
   "type": "module",

package/site/docs/paperclip-plugin.md

@@ -5,7 +5,11 @@ The Papercliped plugin is where you manage Papercliped, right inside Paperclip:
 It manages your Papercliped account only. It never reads or controls your Paperclip itself, and AI apps still connect through Papercliped as before.
 
 ## Install (Paperclip admin)
-Install the npm package `papercliped-paperclip-plugin` from **Settings → Plugins** in Paperclip. Installing is done by the person who runs the Paperclip instance, never remotely. The plugin asks for these capabilities: store its own data, make outbound web requests (to Papercliped), and add a sidebar entry and a page.
+**Automatic (recommended).** When you connect your Paperclip from an AI app, the address step has a box, ticked by default: **Also install the Papercliped plugin in my Paperclip**. After you approve the sign-in, Papercliped asks your Paperclip to install it using Paperclip's own installer and your own approved key. It installs one fixed package, `papercliped-paperclip-plugin`, at the exact version that matches the service, and only when you are the Paperclip's instance admin. If you are not an admin, if it is already installed, or if your Paperclip can't install plugins, nothing happens and your connection works as usual. Untick the box to skip it.
+
+**By hand.** Install the npm package `papercliped-paperclip-plugin` from **Settings → Plugins** in Paperclip (instance admin only). You can remove it there at any time, whichever way it was installed.
+
+The plugin asks for these capabilities: store its own data, make outbound web requests (to Papercliped), and add a sidebar entry and a page.
 
 The bridge address defaults to `https://papercliped.co`. If you host your own bridge, change **Papercliped bridge URL** in the plugin's settings. It must be `https`.
 
@@ -27,6 +31,6 @@ Lost your secret key? Connect from your AI app again and choose **Connect your P
   - **Delete my account.** Removes your username, stored key and every connection. Type your username to confirm.
 
 ## Good to know
-- The plugin runs as trusted code inside Paperclip, so install it only from the official package.
+- The plugin runs as trusted code inside Paperclip, so install it only from the official package. The automatic install is limited to that one package and to the version that matches the service, and it is always your choice on the connect screen.
 - The link token stays on your Paperclip server and is never shown on the page. It can only manage your account: it can't call any Paperclip tool.
 - There is no separate website page for this any more; the old `/manage` address points here.