papercliped 2.5.0 → 2.5.2

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "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,15 @@
 
 ## Unreleased
 
+## v2.5.2 — join the OpenSourcedd community
+
+- **Join the community.** Papercliped's community is now live as **OpenSourcedd**: the [Discord server](https://discord.gg/cAECU68jSA) and [r/OpenSourcedd](https://www.reddit.com/r/OpenSourcedd) on Reddit. Both are linked from the website footer and community page, GitHub's "New issue" page, the README and the contributing guide.
+
+## v2.5.1 — Paperclip keys renew themselves
+
+- **Connections no longer break after 30 days.** Newer Paperclip versions expire the key Papercliped gets when you approve the sign-in after 30 days. Papercliped now renews it about a week before: it asks your Paperclip for a fresh key (named "Papercliped (your username)", same 30-day expiry), stores it encrypted and revokes the old one. Keys of people who rarely use their connection are renewed by the periodic sweep. If a renewal fails, the current key keeps working and it is tried again later. Older Paperclip versions, whose keys don't expire, work as before. Self-hosters on Postgres: run the database migration before starting this version (`npm run migrate`, or `BRIDGE_AUTO_MIGRATE=1`); keys stored before it are assumed to expire 30 days after they were connected, and the first renewal check reads the real date from Paperclip.
+- **Community cards.** Ready-to-post images for the launch and the new r/OpenSourcedd community, light and dark, 1600×900, in `web/public/brand/community/` (rebuilt by `web/scripts/community-cards.mjs`). Download them from papercliped.co/brand, and the README now opens with the launch card.
+
 ## v2.5.0 — icon pack, launch-ready docs and tester feedback
 
 - **Icon pack.** papercliped.co/brand has a one-click ZIP with every Papercliped icon in light and dark: the app icon from 16 to 1024 px, a favicon, profile pictures safe for circle crops (Discord, X, GitHub, npm, MCP directories), an Android/installable-app icon, an X header, a 16:9 banner and link-preview images. They're built from the real mascot and the site's own components by `web/scripts/icon-pack.mjs`, so they always match. The website now also has a classic favicon, an Apple touch icon and a web app manifest.

package/README.md

@@ -1,5 +1,12 @@
 # Papercliped
 
+<a href="https://papercliped.co">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/OpenSourcx/papercliped/main/web/public/brand/community/papercliped-launch-dark.png">
+    <img alt="Papercliped: run your Paperclip from any AI app. Claude, ChatGPT, Codex or any MCP app. Connector: https://mcp.papercliped.co/mcp" src="https://raw.githubusercontent.com/OpenSourcx/papercliped/main/web/public/brand/community/papercliped-launch-light.png">
+  </picture>
+</a>
+
 **Run your [Paperclip](https://github.com/paperclipai/paperclip) from any AI app.** Papercliped connects Claude, ChatGPT, Codex and any MCP app to your Paperclip, the open-source orchestrator for companies of AI agents. Check on agents, pause or wake them, assign issues, decide approvals and get status, cost and activity reports, without opening the dashboard.
 
 [![CI](https://github.com/OpenSourcx/papercliped/actions/workflows/ci.yml/badge.svg)](https://github.com/OpenSourcx/papercliped/actions/workflows/ci.yml)
@@ -115,7 +122,8 @@ npm install && npm test
 
 ## Community and contributing
 
-- Questions and ideas: [GitHub Discussions](https://github.com/OpenSourcx/papercliped/discussions) and Discord ([papercliped.co/community](https://papercliped.co/community))
+- Questions and chat: the OpenSourcedd [Discord](https://discord.gg/cAECU68jSA) and [GitHub Discussions](https://github.com/OpenSourcx/papercliped/discussions)
+- Ideas, project shares and feedback: [r/OpenSourcedd](https://www.reddit.com/r/OpenSourcedd)
 - Bugs and feature requests: [issues](https://github.com/OpenSourcx/papercliped/issues/new/choose)
 - Contributing (setup, checks, the path from first PR to maintainer): [CONTRIBUTING.md](CONTRIBUTING.md)
 - Code of conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)

package/dist/oauth/paperclip-login.js

@@ -3,6 +3,15 @@ const APPROVAL_PATH = /^\/cli-auth\/[0-9a-f-]{36}\?token=[A-Za-z0-9_\-.~%]{8,300
 /** 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
+/** How long Paperclip keeps a board key it issued without an explicit expiry (its BOARD_API_KEY_TTL_MS). */
+export const PAPERCLIP_KEY_TTL_MS = 30 * 24 * 3600 * 1000;
+/** null = never expires; undefined = not said. Anything unreadable counts as not said. */
+function expiryOf(v) {
+    if (v === null)
+        return null;
+    const t = typeof v === "string" ? Date.parse(v) : NaN;
+    return Number.isFinite(t) ? t : undefined;
+}
 export class LoginError extends Error {
     status;
     constructor(message, status) {
@@ -118,6 +127,38 @@ export class PaperclipLogin {
             throw new LoginError("Paperclip installed something other than the Papercliped plugin");
         return "installed";
     }
+    /**
+     * The calling key's id and expiry, from Paperclip's own key listing. `unsupported` = this Paperclip has no key
+     * listing (versions from before board keys expired). expiresAt: null = never expires, undefined = not listed.
+     */
+    async keyInfo(token) {
+        const auth = { headers: { Authorization: `Bearer ${token}`, Accept: "application/json" } };
+        const me = await json(await this.t.fetch(`${this.t.apiUrl}/cli-auth/me`, { ...auth, ...this.sig() }));
+        const keyId = typeof me?.keyId === "string" && UUID.test(me.keyId) ? me.keyId : null;
+        const res = await this.t.fetch(`${this.t.apiUrl}/board-api-keys`, { ...auth, ...this.sig() });
+        if (res.status === 404)
+            return { state: "unsupported" };
+        const list = await json(res);
+        if (!Array.isArray(list))
+            throw new LoginError("Paperclip returned an unexpected key list");
+        const mine = keyId ? list.find((k) => k && typeof k === "object" && k.id === keyId) : undefined;
+        return { state: "ok", keyId, expiresAt: mine ? expiryOf(mine.expiresAt) : undefined };
+    }
+    /** A new board key for the same Paperclip user, with Paperclip's default expiry. `unsupported` = no key API there. */
+    async createKey(token, name) {
+        const res = await this.t.fetch(`${this.t.apiUrl}/board-api-keys`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", Accept: "application/json" },
+            body: JSON.stringify({ name: name.slice(0, 120) }),
+            ...this.sig(),
+        });
+        if (res.status === 404)
+            return { state: "unsupported" };
+        const k = await json(res);
+        if (typeof k?.token !== "string" || !TOKENISH.test(k.token))
+            throw new LoginError("Paperclip returned an invalid credential");
+        return { state: "created", keyId: typeof k.id === "string" && UUID.test(k.id) ? k.id : null, token: k.token, expiresAt: expiryOf(k.expiresAt) };
+    }
     /** Best effort: invalidate the board key we were issued when a grant is revoked. */
     async revoke(token) {
         try {

package/dist/oauth/pg-store.js

@@ -23,6 +23,7 @@ const toGrant = (r) => ({
     resource: r.resource,
     instanceUrl: r.instance_url,
     sealedCredential: r.sealed_credential,
+    credentialExpiresAt: r.credential_expires_at == null ? null : num(r.credential_expires_at),
     accountId: r.account_id ?? null,
     username: r.username ?? null,
     createdAt: num(r.created_at),
@@ -69,9 +70,9 @@ export class PgStore {
                order by last_used_at desc offset $2))`, [t - CLIENT_IDLE_MS, MAX_CLIENTS]);
     }
     async putGrant(g) {
-        await this.q(`insert into bridge.grants (id, client_id, client_name, user_id, scopes, resource, instance_url, sealed_credential, created_at, last_used_at, revoked, account_id, username)
-       values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13)
-       on conflict (id) do update set sealed_credential = excluded.sealed_credential, scopes = excluded.scopes, revoked = excluded.revoked, last_used_at = excluded.last_used_at`, [g.id, g.clientId, g.clientName, g.userId, g.scopes, g.resource, g.instanceUrl, g.sealedCredential, g.createdAt, g.lastUsedAt, g.revoked, g.accountId ?? null, g.username ?? null]);
+        await this.q(`insert into bridge.grants (id, client_id, client_name, user_id, scopes, resource, instance_url, sealed_credential, created_at, last_used_at, revoked, account_id, username, credential_expires_at)
+       values ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14)
+       on conflict (id) do update set sealed_credential = excluded.sealed_credential, credential_expires_at = excluded.credential_expires_at, scopes = excluded.scopes, revoked = excluded.revoked, last_used_at = excluded.last_used_at`, [g.id, g.clientId, g.clientName, g.userId, g.scopes, g.resource, g.instanceUrl, g.sealedCredential, g.createdAt, g.lastUsedAt, g.revoked, g.accountId ?? null, g.username ?? null, g.credentialExpiresAt ?? null]);
     }
     async getGrant(id) {
         const r = await this.q("select * from bridge.grants where id = $1", [id]);
@@ -178,7 +179,7 @@ export class PgStore {
         return { id: x.id, username: x.username, usernameKey: x.username_key, secretHash: x.secret_hash, createdAt: num(x.created_at), lastLoginAt: x.last_login_at == null ? null : num(x.last_login_at), disabled: x.disabled, anonymous: !!x.anonymous, alias: x.alias ?? null, beta: !!x.beta, policy: x.policy ?? null };
     }
     static toLink(x) {
-        return { accountId: x.account_id, instanceUrl: x.instance_url, paperclipUserId: x.paperclip_user_id, sealedCredential: x.sealed_credential, createdAt: num(x.created_at), connectedAt: num(x.connected_at), lastUsedAt: num(x.last_used_at), instanceLabel: x.instance_label ?? null };
+        return { accountId: x.account_id, instanceUrl: x.instance_url, paperclipUserId: x.paperclip_user_id, sealedCredential: x.sealed_credential, credentialExpiresAt: x.credential_expires_at == null ? null : num(x.credential_expires_at), createdAt: num(x.created_at), connectedAt: num(x.connected_at), lastUsedAt: num(x.last_used_at), instanceLabel: x.instance_label ?? null };
     }
     async createAccount(a) {
         try {
@@ -283,8 +284,8 @@ export class PgStore {
     }
     async putLink(l) {
         try {
-            await this.q(`insert into bridge.account_links (account_id, instance_url, paperclip_user_id, sealed_credential, created_at, connected_at, last_used_at, instance_label) values ($1,$2,$3,$4,$5,$6,$7,$8)
-         on conflict (account_id) do update set instance_url = excluded.instance_url, paperclip_user_id = excluded.paperclip_user_id, sealed_credential = excluded.sealed_credential, connected_at = excluded.connected_at, last_used_at = excluded.last_used_at, instance_label = excluded.instance_label`, [l.accountId, l.instanceUrl, l.paperclipUserId, l.sealedCredential, l.createdAt, l.connectedAt, l.lastUsedAt, l.instanceLabel ?? null]);
+            await this.q(`insert into bridge.account_links (account_id, instance_url, paperclip_user_id, sealed_credential, created_at, connected_at, last_used_at, instance_label, credential_expires_at) values ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+         on conflict (account_id) do update set instance_url = excluded.instance_url, paperclip_user_id = excluded.paperclip_user_id, sealed_credential = excluded.sealed_credential, credential_expires_at = excluded.credential_expires_at, connected_at = excluded.connected_at, last_used_at = excluded.last_used_at, instance_label = excluded.instance_label`, [l.accountId, l.instanceUrl, l.paperclipUserId, l.sealedCredential, l.createdAt, l.connectedAt, l.lastUsedAt, l.instanceLabel ?? null, l.credentialExpiresAt ?? null]);
             return true;
         }
         catch (e) {
@@ -312,6 +313,18 @@ export class PgStore {
     async listIdleLinks(cutoff) {
         return (await this.q("select * from bridge.account_links where sealed_credential is not null and last_used_at < $1", [cutoff])).rows.map(PgStore.toLink);
     }
+    async listExpiringLinks(before) {
+        return (await this.q("select * from bridge.account_links where sealed_credential is not null and credential_expires_at < $1", [before])).rows.map(PgStore.toLink);
+    }
+    async listExpiringGrants(before) {
+        return (await this.q("select * from bridge.grants where not revoked and sealed_credential is not null and credential_expires_at < $1", [before])).rows.map(toGrant);
+    }
+    async swapCredential(h, expect, next, expiresAt) {
+        const sql = h.kind === "link"
+            ? "update bridge.account_links set sealed_credential = $3, credential_expires_at = $4 where account_id = $1 and sealed_credential = $2"
+            : "update bridge.grants set sealed_credential = $3, credential_expires_at = $4 where id = $1 and sealed_credential = $2 and not revoked";
+        return ((await this.q(sql, [h.id, expect, next, expiresAt])).rowCount ?? 0) === 1;
+    }
     async revokeAccountGrants(accountId) {
         const c = await this.pool.connect();
         try {

package/dist/oauth/provider.js

@@ -7,11 +7,11 @@ import { hostAllowed } from "../config.js";
 import { UnsafeUrlError, createSafeFetch, parseInstanceUrl } from "../net/safe-fetch.js";
 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 { LoginError, PAPERCLIP_KEY_TTL_MS, PaperclipLogin } from "./paperclip-login.js";
 import { parseAccountPolicy, parseSessionPolicy, readAccountPolicy, readSessionPolicy, surfaceOfTool } from "../access/policy.js";
 import { tools as ALL_TOOLS } from "../tools.js";
 import { VERSION } from "../version.js";
-import { MemoryStore } from "./store.js";
+import { MemoryStore, credentialExpiry } 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]"]);
 const PENDING_TTL_MS = 10 * 60_000;
@@ -28,6 +28,12 @@ const PLUGIN_KEY = "papercliped.remote-control";
 const PLUGIN_INSTALL_MS = 120_000;
 const MAX_FORM_BYTES = 16 * 1024;
 const DAY_MS = 24 * 3600 * 1000;
+/** Renew a stored Paperclip key this long before Paperclip expires it. */
+const ROTATE_BEFORE_MS = 7 * DAY_MS;
+/** After a rotation attempt, wait this long before trying that key again (shared across processes). */
+const ROTATE_RETRY_MS = 10 * 60_000;
+/** Revoke the replaced key only after this, so calls already under way with it (here or in another process) finish. */
+const ROTATE_GRACE_MS = 60_000;
 class OAuthError extends Error {
     code;
     status;
@@ -75,6 +81,10 @@ export class OAuthProvider {
     background = new Set();
     multi;
     accounts;
+    /** Key rotations under way in this process, by holder: callers wait for one instead of starting another. */
+    rotations = new Map();
+    /** Holder → when this process may try a failed rotation again. */
+    rotateRetryAt = new Map();
     constructor(deps) {
         this.deps = deps;
         this.now = deps.now ?? Date.now;
@@ -158,7 +168,8 @@ export class OAuthProvider {
     /** The Paperclip client for a grant. In account mode the credential and instance come from the account's link. */
     async resolveClient(grant) {
         if (!this.accounts || !grant.accountId) {
-            const apiKey = grant.sealedCredential ? this.keyring.unseal(grant.sealedCredential) : null;
+            const sealed = grant.sealedCredential ? await this.currentKey(this.heldOnGrant(grant, grant.sealedCredential)) : null;
+            const apiKey = sealed ? this.keyring.unseal(sealed) : null;
             if (!this.multi)
                 return { client: new PaperclipClient({ ...this.deps.config, apiKey }) };
             if (!grant.instanceUrl)
@@ -171,7 +182,7 @@ export class OAuthProvider {
             throw new ReconnectRequired("This account's Paperclip connection has expired; reconnect to continue.");
         const origin = this.checkedInstance(link.instanceUrl).origin; // re-validated on every use (policy can tighten)
         await this.store.touchLink(grant.accountId);
-        const apiKey = this.keyring.unseal(link.sealedCredential);
+        const apiKey = this.keyring.unseal(await this.currentKey(this.heldOnLink(link, link.sealedCredential)));
         return { client: new PaperclipClient({ ...this.deps.config, apiUrl: `${origin}/api`, apiKey, companyId: null }, this.safeFetch), instanceHost: link.instanceLabel ?? new URL(origin).host };
     }
     /** Convenience for callers that only need the client. */
@@ -201,22 +212,23 @@ export class OAuthProvider {
             /* instance no longer allowed / key gone: nothing more we can do */
         }
     }
-    /** Revoke idle grants and idle account connections, delete their stored credentials, prune telemetry. Run periodically. */
+    /** Revoke idle grants and idle account connections, delete their stored credentials, renew Paperclip keys close to expiry, prune telemetry. Run periodically. */
     async sweep() {
         const days = this.deps.oauth.idleRevokeDays;
         await this.store.prune();
-        if (!days)
-            return 0;
-        const cutoff = this.now() - days * DAY_MS;
         let n = 0;
-        const idle = await this.store.listIdleGrants(cutoff);
-        for (const g of idle)
-            await this.revokeGrant(g.id);
-        n += idle.length;
-        for (const l of await this.store.listIdleLinks(cutoff)) {
-            await this.dropConnection(l, "idle");
-            n += 1;
+        if (days) {
+            const cutoff = this.now() - days * DAY_MS;
+            const idle = await this.store.listIdleGrants(cutoff);
+            for (const g of idle)
+                await this.revokeGrant(g.id);
+            n += idle.length;
+            for (const l of await this.store.listIdleLinks(cutoff)) {
+                await this.dropConnection(l, "idle");
+                n += 1;
+            }
         }
+        await this.rotateExpiring();
         return n;
     }
     /** Forget an account's stored Paperclip credential (the username stays) and tell its Paperclip to revoke the key. */
@@ -237,6 +249,125 @@ export class OAuthProvider {
             /* best effort */
         }
     }
+    // ───────────── Paperclip key rotation ─────────────
+    // Paperclip expires the board keys it issues (30 days by default). Each stored key is renewed about a week before
+    // that: the old key asks Paperclip for a new one, the new one is swapped in only if the old one is still stored
+    // (compare-and-swap), and only then is the old one revoked. Any failure leaves the working key in place.
+    heldOnLink(l, sealed) {
+        return { kind: "link", id: l.accountId, instanceUrl: l.instanceUrl, sealed, expiresAt: credentialExpiry(l.credentialExpiresAt, l.connectedAt) };
+    }
+    heldOnGrant(g, sealed) {
+        return { kind: "grant", id: g.id, instanceUrl: g.instanceUrl, sealed, expiresAt: credentialExpiry(g.credentialExpiresAt, g.createdAt) };
+    }
+    /** The sealed key to call Paperclip with: the stored one, or its replacement when it was due and got renewed. */
+    async currentKey(k) {
+        if (k.expiresAt === null || k.expiresAt - this.now() > ROTATE_BEFORE_MS)
+            return k.sealed;
+        const slot = `${k.kind}:${k.id}`;
+        let run = this.rotations.get(slot);
+        if (!run) {
+            if ((this.rotateRetryAt.get(slot) ?? 0) > this.now())
+                return k.sealed;
+            run = this.rotate(k, slot).finally(() => this.rotations.delete(slot));
+            this.rotations.set(slot, run);
+        }
+        return (await run) ?? k.sealed;
+    }
+    /** Renew every stored key that expires within the rotation window, so keys of people who rarely call get renewed too. */
+    async rotateExpiring() {
+        const before = this.now() + ROTATE_BEFORE_MS;
+        for (const l of await this.store.listExpiringLinks(before))
+            if (l.sealedCredential)
+                await this.currentKey(this.heldOnLink(l, l.sealedCredential));
+        for (const g of await this.store.listExpiringGrants(before))
+            if (g.sealedCredential)
+                await this.currentKey(this.heldOnGrant(g, g.sealedCredential));
+    }
+    /** One rotation. Resolves to the new sealed key, or null to keep using the stored one. Never throws. */
+    async rotate(k, slot) {
+        let outcome = null;
+        let who = null;
+        try {
+            // One rotation per key across every process: whoever takes the claim does it; the others keep the old key, which still works.
+            if (!(await this.store.hit(`rotate:${slot}`, 1, ROTATE_RETRY_MS))) {
+                this.rotateRetryAt.set(slot, this.now() + ROTATE_RETRY_MS);
+                return null;
+            }
+            const token = this.keyring.unseal(k.sealed);
+            if (k.kind === "grant" && token === this.deps.config.apiKey) {
+                // The operator's own PAPERCLIP_API_KEY (bridge admin token sign-in): not ours to replace.
+                await this.store.swapCredential(k, k.sealed, k.sealed, null);
+                return null;
+            }
+            let name = "Papercliped";
+            if (k.kind === "link") {
+                const a = await this.store.getAccount(k.id);
+                if (a)
+                    name = `Papercliped (${a.username})`;
+                who = a ? { accountId: a.id, username: displayName(a) } : { accountId: k.id, username: "" };
+            }
+            else {
+                const g = await this.store.getGrant(k.id);
+                if (g)
+                    name = `Papercliped (${g.username ?? g.clientName})`;
+                who = g ? { accountId: g.accountId ?? null, username: g.username ?? null } : null;
+            }
+            const login = this.loginFor(k.instanceUrl);
+            outcome = "failed";
+            const info = await login.keyInfo(token);
+            if (info.state === "unsupported" || info.expiresAt === null) {
+                // Older Paperclip, or a key that never expires: nothing to renew, now or later.
+                outcome = null;
+                await this.store.swapCredential(k, k.sealed, k.sealed, null);
+                return null;
+            }
+            if (info.expiresAt !== undefined && info.expiresAt - this.now() > ROTATE_BEFORE_MS) {
+                outcome = null; // the stored expiry was an estimate; Paperclip's own is later
+                await this.store.swapCredential(k, k.sealed, k.sealed, info.expiresAt);
+                return null;
+            }
+            const made = await login.createKey(token, name);
+            if (made.state === "unsupported") {
+                outcome = null;
+                await this.store.swapCredential(k, k.sealed, k.sealed, null);
+                return null;
+            }
+            const next = this.keyring.seal(made.token);
+            if (!(await this.store.swapCredential(k, k.sealed, next, made.expiresAt === undefined ? this.now() + PAPERCLIP_KEY_TTL_MS : made.expiresAt))) {
+                // Reconnected, rotated elsewhere or disconnected meanwhile: what is stored now wins; drop the key we just made.
+                outcome = null;
+                await login.revoke(made.token);
+                return null;
+            }
+            outcome = "rotated";
+            this.revokeReplaced(login, token);
+            return next;
+        }
+        catch (e) {
+            outcome = "failed";
+            this.rotateRetryAt.set(slot, this.now() + ROTATE_RETRY_MS);
+            // Paperclip no longer accepts this key (expired or revoked): it can never be renewed, so stop trying. Using it
+            // still gets the reconnect hint, and reconnecting stores a fresh key with a fresh expiry.
+            if (e instanceof LoginError && e.status === 401)
+                await this.store.swapCredential(k, k.sealed, k.sealed, null).catch(() => false);
+            return null;
+        }
+        finally {
+            if (outcome)
+                await this.event("key", who, outcome);
+        }
+    }
+    /** Revoke a key that rotation replaced, after a grace period for calls still using it. Best effort: it expires on its own anyway. */
+    revokeReplaced(login, token) {
+        const grace = this.deps.rotationGraceMs ?? ROTATE_GRACE_MS;
+        if (grace <= 0) {
+            const run = login.revoke(token);
+            const tracked = run.finally(() => this.background.delete(tracked));
+            this.background.add(tracked);
+            return;
+        }
+        setTimeout(() => void login.revoke(token), grace).unref();
+    }
     // ───────────── account management (the Paperclip plugin's connection manager) ─────────────
     // Everything here acts on ONE account and is reached only through ManageRoutes, with a plugin token or the secret key.
     /** Username + secret key, throttled exactly like the sign-in page (shared counters, so there is no cheaper way to guess). */
@@ -918,7 +1049,7 @@ export class OAuthProvider {
         const t = this.now();
         const acct = await this.store.getAccount(accountId);
         const instanceLabel = acct ? this.instanceLabelFor(acct, instanceUrl, old) : new URL(instanceUrl).host;
-        const ok = await this.store.putLink({ accountId, instanceUrl, paperclipUserId, sealedCredential: this.keyring.seal(credential), createdAt: old?.createdAt ?? t, connectedAt: t, lastUsedAt: t, instanceLabel });
+        const ok = await this.store.putLink({ accountId, instanceUrl, paperclipUserId, sealedCredential: this.keyring.seal(credential), credentialExpiresAt: t + PAPERCLIP_KEY_TTL_MS, createdAt: old?.createdAt ?? t, connectedAt: t, lastUsedAt: t, instanceLabel });
         if (ok && old?.sealedCredential) {
             let same = false;
             try {
@@ -1163,7 +1294,7 @@ export class OAuthProvider {
         }
         if (!created)
             return this.renderStage(res, rid, p, "Could not reserve an anonymous name right now. Please try again.", { value: typed });
-        const linked = await this.store.putLink({ accountId: account.id, instanceUrl: p.instanceUrl, paperclipUserId: p.paperclipUserId, sealedCredential: this.keyring.seal(ch.boardApiToken), createdAt: t, connectedAt: t, lastUsedAt: t, instanceLabel: this.instanceLabelFor(account, p.instanceUrl) });
+        const linked = await this.store.putLink({ accountId: account.id, instanceUrl: p.instanceUrl, paperclipUserId: p.paperclipUserId, sealedCredential: this.keyring.seal(ch.boardApiToken), credentialExpiresAt: t + PAPERCLIP_KEY_TTL_MS, createdAt: t, connectedAt: t, lastUsedAt: t, instanceLabel: this.instanceLabelFor(account, p.instanceUrl) });
         if (!linked) {
             await this.store.deleteAccount(account.id); // lost a race for this Paperclip identity
             p.stage = "choose";
@@ -1291,6 +1422,8 @@ export class OAuthProvider {
             resource: this.resource,
             instanceUrl: entry.instanceUrl,
             sealedCredential: entry.sealedCredential,
+            // A key from an approved sign-in expires with Paperclip's default; the operator's own PAPERCLIP_API_KEY is never rotated.
+            credentialExpiresAt: entry.sealedCredential && this.keyring.unseal(entry.sealedCredential) !== this.deps.config.apiKey ? t + PAPERCLIP_KEY_TTL_MS : null,
             accountId: entry.accountId ?? null,
             username: entry.username ?? null,
             createdAt: t,

package/dist/oauth/store.js

@@ -1,7 +1,12 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { AliasTakenError } from "../accounts/types.js";
+import { PAPERCLIP_KEY_TTL_MS } from "./paperclip-login.js";
 import { HIST_EDGES, isFault } from "../telemetry/types.js";
+/** A stored credential's expiry; old rows without one are assumed to carry Paperclip's default TTL from `issuedAt`. */
+export function credentialExpiry(expiresAt, issuedAt) {
+    return expiresAt === undefined ? issuedAt + PAPERCLIP_KEY_TTL_MS : expiresAt;
+}
 const MAX_USER_EVENTS = 20_000;
 const MAX_CLIENTS = 1000;
 const CLIENT_IDLE_MS = 7 * 24 * 3600 * 1000;
@@ -134,6 +139,21 @@ export class MemoryStore {
     async listIdleGrants(cutoff) {
         return Object.values(this.d.grants).filter((g) => !g.revoked && g.lastUsedAt < cutoff);
     }
+    async listExpiringGrants(before) {
+        return Object.values(this.d.grants).filter((g) => {
+            const exp = g.sealedCredential && !g.revoked ? credentialExpiry(g.credentialExpiresAt, g.createdAt) : null;
+            return exp !== null && exp < before;
+        });
+    }
+    async swapCredential(h, expect, next, expiresAt) {
+        const row = h.kind === "link" ? this.lnks[h.id] : this.d.grants[h.id];
+        if (!row || row.sealedCredential !== expect || (h.kind === "grant" && row.revoked))
+            return false;
+        row.sealedCredential = next;
+        row.credentialExpiresAt = expiresAt;
+        this.save();
+        return true;
+    }
     async putAccess(hash, r) {
         this.d.access[hash] = r;
         this.save();
@@ -358,6 +378,12 @@ export class MemoryStore {
     async listIdleLinks(cutoff) {
         return Object.values(this.lnks).filter((l) => l.sealedCredential && l.lastUsedAt < cutoff);
     }
+    async listExpiringLinks(before) {
+        return Object.values(this.lnks).filter((l) => {
+            const exp = l.sealedCredential ? credentialExpiry(l.credentialExpiresAt, l.connectedAt) : null;
+            return exp !== null && exp < before;
+        });
+    }
     async revokeAccountGrants(accountId) {
         let n = 0;
         for (const g of Object.values(this.d.grants)) {

package/docs/COMMUNITY.md

@@ -1,6 +1,6 @@
 # Community: Discord, Discussions and socials
 
-A ready-to-follow setup for the Papercliped Discord, plus where everything else lives. Links show up on the website only once they're set (`web/src/config/community.ts`, or `VITE_DISCORD_URL`, `VITE_X_URL`, `VITE_DISCUSSIONS_URL`, `VITE_FORUM_URL` at build time). Nothing here needs a bot.
+A ready-to-follow setup for the Discord, plus where everything else lives. Papercliped's community is **OpenSourcedd**: the Discord server (https://discord.gg/cAECU68jSA) and r/OpenSourcedd on Reddit, both set in `web/src/config/community.ts`. Other links show up on the website only once they're set (`VITE_X_URL`, `VITE_DISCUSSIONS_URL`, `VITE_FORUM_URL` at build time; `VITE_DISCORD_URL` / `VITE_REDDIT_URL` override the defaults). Nothing here needs a bot.
 
 ## 1. Create the server (about 20 minutes)
 

package/docs/LAUNCH-KIT.md

@@ -7,7 +7,7 @@ Everything for the public launch: what must be true first, how to get the first
 | | Check | How |
 | --- | --- | --- |
 | ☐ | The latest release is live | `https://mcp.papercliped.co/api/public/v1/info` shows the version in `package.json`; papercliped.co/prompts and docs.papercliped.co/hosting load. If not, Render → **Manual Deploy → Deploy latest commit**. |
-| ☐ | Connections survive past 30 days | Paperclip expires approved keys after 30 days; ship key rotation before inviting people, or every tester drops off a month later. |
+| ☐ | Connections survive past 30 days | Paperclip expires approved keys after 30 days; the bridge renews each key a week before (v2.5.1). Run the `008_key_rotation.sql` migration (`npm run migrate`) on the production database when deploying it. |
 | ☐ | A full run-through on a fresh Paperclip | Follow [Host your Paperclip](https://docs.papercliped.co/hosting) start to finish on one guide (Railway or a VPS), connect Claude **and** ChatGPT, run five prompts from the gallery, flip the access switch in the control room. Fix anything that trips you up. |
 | ☐ | Discord and X exist | Create them with the icon pack (below), then set `VITE_DISCORD_URL` / `VITE_X_URL` on Render and rebuild. Set up Discord per [COMMUNITY.md](COMMUNITY.md), plus a `#testers` channel. |
 | ☐ | GitHub is launch-ready | Turn on Discussions, set the repository social preview to `social-light-1200x630.png`, pin a "Start here" discussion, add topics: `mcp`, `paperclip`, `ai-agents`, `claude`, `chatgpt`, `codex`, `mcp-server`. |

package/docs/supabase-schema.sql

@@ -285,6 +285,23 @@ alter table bridge.grants   add column if not exists policy jsonb;
 -- Audit rows now also record calls the policy refused (error_class = policy_blocked).
 comment on column bridge.audit_events.error_class is 'invalid_input | insufficient_scope | read_only | policy_blocked | upstream_4xx | upstream_5xx | upstream_unreachable | rate_limited | unauthorized | internal';
 
+-- ───── 008_key_rotation.sql ─────
+-- Paperclip key rotation: Paperclip expires the board keys it issues (30 days by default), so the bridge renews
+-- each stored key about a week before it lapses. credential_expires_at is when Paperclip expires the stored key
+-- (ms epoch); null = it never expires (older Paperclip, or a key Paperclip did not issue us), so it is never rotated.
+alter table bridge.account_links add column if not exists credential_expires_at bigint;
+alter table bridge.grants        add column if not exists credential_expires_at bigint;
+
+-- Keys stored before this migration came from an approved sign-in: assume Paperclip's default 30 days from then.
+-- The first rotation check reads the real expiry from Paperclip and corrects it (or clears it if the key never expires).
+update bridge.account_links set credential_expires_at = connected_at + 2592000000
+ where sealed_credential is not null and credential_expires_at is null;
+update bridge.grants set credential_expires_at = created_at + 2592000000
+ where sealed_credential is not null and not revoked and credential_expires_at is null;
+
+create index if not exists account_links_expiry_idx on bridge.account_links (credential_expires_at) where sealed_credential is not null;
+create index if not exists grants_expiry_idx on bridge.grants (credential_expires_at) where sealed_credential is not null and not revoked;
+
 -- ───── migration bookkeeping ─────
 create table if not exists bridge.schema_migrations (version text primary key, applied_at timestamptz not null default now());
 alter table bridge.schema_migrations enable row level security;
@@ -294,6 +311,6 @@ do $$ declare r text; begin
     if exists (select 1 from pg_roles where rolname = r) then execute format('revoke all on bridge.schema_migrations from %I', r); end if;
   end loop;
 end $$;
-insert into bridge.schema_migrations (version) values ('001_init.sql'), ('002_audit.sql'), ('003_accounts.sql'), ('004_privacy_panel.sql'), ('005_beta.sql'), ('006_two_levels.sql'), ('007_control_room.sql') on conflict (version) do nothing;
+insert into bridge.schema_migrations (version) values ('001_init.sql'), ('002_audit.sql'), ('003_accounts.sql'), ('004_privacy_panel.sql'), ('005_beta.sql'), ('006_two_levels.sql'), ('007_control_room.sql'), ('008_key_rotation.sql') on conflict (version) do nothing;
 
 commit;

package/migrations/008_key_rotation.sql

@@ -0,0 +1,15 @@
+-- Paperclip key rotation: Paperclip expires the board keys it issues (30 days by default), so the bridge renews
+-- each stored key about a week before it lapses. credential_expires_at is when Paperclip expires the stored key
+-- (ms epoch); null = it never expires (older Paperclip, or a key Paperclip did not issue us), so it is never rotated.
+alter table bridge.account_links add column if not exists credential_expires_at bigint;
+alter table bridge.grants        add column if not exists credential_expires_at bigint;
+
+-- Keys stored before this migration came from an approved sign-in: assume Paperclip's default 30 days from then.
+-- The first rotation check reads the real expiry from Paperclip and corrects it (or clears it if the key never expires).
+update bridge.account_links set credential_expires_at = connected_at + 2592000000
+ where sealed_credential is not null and credential_expires_at is null;
+update bridge.grants set credential_expires_at = created_at + 2592000000
+ where sealed_credential is not null and not revoked and credential_expires_at is null;
+
+create index if not exists account_links_expiry_idx on bridge.account_links (credential_expires_at) where sealed_credential is not null;
+create index if not exists grants_expiry_idx on bridge.grants (credential_expires_at) where sealed_credential is not null and not revoked;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.5.0",
+  "version": "2.5.2",
   "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/security.md

@@ -14,6 +14,7 @@ What Papercliped does to protect you, and what it cannot.
 - **OAuth 2.1 with PKCE**, short-lived access tokens, rotating refresh tokens with reuse detection.
 - **Rate limits** on sign-in, secret-key attempts and tool calls.
 - **A separate operator dashboard** (an access-controlled service, not part of the open-source bridge) reads the database through a read-only role that can see only safe views: never your key, secret hash or an anonymous account's real name.
+- **Keys are renewed, not made permanent.** Paperclip expires the keys it issues (30 days on newer versions). About a week before that, Papercliped asks Paperclip for a fresh key with the same expiry, stores it encrypted, and revokes the old one. It never asks for a key that doesn't expire. In Paperclip the key is named "Papercliped (your username)". If renewal fails, the current key keeps working and Papercliped tries again later.
 - Revocation is immediate on disconnect, and idle keys are removed after 30 days.
 
 ## What it cannot do

package/site/docs/troubleshooting.md

@@ -4,7 +4,7 @@
 
 **"This hostname is not allowed for this Paperclip instance."** Paperclip doesn't recognise the address. Set `PAPERCLIP_DEPLOYMENT_EXPOSURE=public` and `PAPERCLIP_PUBLIC_URL` to exactly the address you use, then restart Paperclip. See [What every option needs](/docs/hosting#what-every-option-needs).
 
-**It stopped working after about a month.** Newer Paperclip versions make keys approved through the sign-in prompt expire after 30 days. When the AI says the Paperclip credential was rejected, disconnect and connect again from your AI app, then approve in Paperclip.
+**"The Paperclip credential behind this connection was rejected."** Newer Paperclip versions expire keys after 30 days. Papercliped renews yours automatically about a week before that, so this should not happen on its own. It does if the key was revoked in Paperclip, the renewal kept failing until the key expired (for example, Paperclip was unreachable that whole week), or your Paperclip account lost access. Disconnect and connect again from your AI app, then approve in Paperclip.
 
 **Agents stop mid-task now and then.** Something restarted Paperclip: an update, a redeploy, or a host that sleeps. Runs in progress end on every restart. Use an always-on host and update when agents are idle.