papercliped 2.6.1 → 2.7.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.6.1",
+  "version": "2.7.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,10 @@
 
 ## Unreleased
 
+## v2.7.0 — Ed25519-signed Connect account claims
+
+- **Connect claims can be signed with an Ed25519 key.** Set `CONNECT_CLAIM_ED25519_PRIVATE_KEY` (PKCS#8 PEM; `node scripts/gen-claim-key.mjs <file>` makes a pair) and optionally `CONNECT_CLAIM_KEY_ID`; Connect then verifies with the public key only and can no longer forge claims. The shared `CONNECT_CLAIM_SIGNING_KEY` still works for one more release. Nothing to do unless you run Connect claims; they stay off by default.
+
 ## v2.6.1 — docs: mention the upcoming managed address
 
 - **Docs:** the "At home, with a tunnel" guide now mentions that a managed address from Papercliped Connect (for ePaperclip on Proxmox) is being built and is not available yet. Nothing to do.

package/dist/accounts/connect-claim.js

@@ -1,9 +1,14 @@
-import { createHash, createHmac, randomBytes } from "node:crypto";
+import { createHash, createHmac, createPrivateKey, randomBytes, sign as edSign } from "node:crypto";
 /**
  * This service-only assertion proves ownership of one EXISTING Papercliped
  * account for a particular (already verified on Connect) OIDC identity.
  * Disabled unless CONNECT_CLAIM_SIGNING_KEY is configured explicitly.
  * It is NOT a login session, MCP grant, or Proxmox permission.
+ *
+ * Two signature formats (Connect accepts both during the rollout release):
+ *  - EdDSA (Ed25519), header { alg: "EdDSA", v: 2, kid }: signed with a private key held only here; Connect verifies with a
+ *    public key, so Connect can no longer forge claims. Preferred; used whenever an Ed25519 key is configured.
+ *  - HS256, header { alg: "HS256", v: 1 }: the legacy shared secret.
  */
 export const CLAIM_TTL_SECONDS = 60;
 const ASSERTION_ISSUER = "https://papercliped.co";
@@ -23,21 +28,35 @@ export function claimIdentityBinding(issuer, subject) {
         throw new Error("Invalid verified identity");
     return createHash("sha256").update(JSON.stringify([issuer, subject]), "utf8").digest("base64url");
 }
-export function signConnectClaim({ accountId, issuer, subject, signingKey, nowMs = Date.now(), }) {
+/** Parses CONNECT_CLAIM_ED25519_PRIVATE_KEY (PKCS#8 PEM; literal "\\n" sequences are accepted for single-line env vars). Throws unless it is Ed25519. */
+export function parseClaimEdKey(pem, kid) {
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(kid))
+        throw new Error("Invalid claim key id");
+    const key = createPrivateKey(pem.replace(/\\n/g, "\n"));
+    if (key.asymmetricKeyType !== "ed25519")
+        throw new Error("Claim signing key must be Ed25519");
+    return { key, kid };
+}
+/** The configured Ed25519 key, or null when unset. A set-but-invalid key throws at startup instead of silently falling back to HS256. */
+export function claimEdKeyFromEnv(env = process.env) {
+    const pem = env.CONNECT_CLAIM_ED25519_PRIVATE_KEY?.trim();
+    return pem ? parseClaimEdKey(pem, env.CONNECT_CLAIM_KEY_ID?.trim() || "pcd-claim-1") : null;
+}
+export function signConnectClaim({ accountId, issuer, subject, signingKey, edKey, nowMs = Date.now(), }) {
     if (!ACCOUNT_ID.test(accountId) || !validClaimIdentity(issuer, subject))
         throw new Error("Invalid claim subject");
-    if (typeof signingKey !== "string" || Buffer.byteLength(signingKey, "utf8") < 32)
+    if (!edKey && (typeof signingKey !== "string" || Buffer.byteLength(signingKey, "utf8") < 32))
         throw new Error("Signing key not configured");
     if (!Number.isSafeInteger(nowMs) || nowMs < 0)
         throw new Error("Invalid time");
     const iat = Math.floor(nowMs / 1000);
-    const header = Buffer.from(JSON.stringify({ alg: "HS256", typ: "PCD-ACCOUNT-ASSERTION", v: 1 })).toString("base64url");
+    const header = Buffer.from(JSON.stringify(edKey ? { alg: "EdDSA", typ: "PCD-ACCOUNT-ASSERTION", v: 2, kid: edKey.kid } : { alg: "HS256", typ: "PCD-ACCOUNT-ASSERTION", v: 1 })).toString("base64url");
     const payload = Buffer.from(JSON.stringify({
         iss: ASSERTION_ISSUER, aud: CLAIM_AUDIENCE, sub: accountId,
         jti: randomBytes(24).toString("base64url"), iat, exp: iat + CLAIM_TTL_SECONDS,
         binding: claimIdentityBinding(issuer, subject),
     })).toString("base64url");
     const signed = header + "." + payload;
-    const mac = createHmac("sha256", signingKey).update(signed).digest("base64url");
-    return { assertion: signed + "." + mac, expiresIn: CLAIM_TTL_SECONDS };
+    const sig = edKey ? edSign(null, Buffer.from(signed), edKey.key).toString("base64url") : createHmac("sha256", signingKey).update(signed).digest("base64url");
+    return { assertion: signed + "." + sig, expiresIn: CLAIM_TTL_SECONDS };
 }

package/dist/http.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { supabaseIdentityVerifier } from "./accounts/supabase-session.js";
+import { claimEdKeyFromEnv } from "./accounts/connect-claim.js";
 import { readConfig, readHttpConfig } from "./config.js";
 import { migrate } from "./migrate.js";
 import { OAuthProvider } from "./oauth/provider.js";
@@ -76,7 +77,7 @@ async function main() {
     const web = webDir ? new WebAppRoutes({ dir: webDir, hosts, forumUrl: process.env.FORUM_URL?.trim() || null }) : undefined;
     if (web)
         console.error(`website: ${webDir}${process.env.PUBLIC_HOSTS ? ` (hosts: ${process.env.PUBLIC_HOSTS})` : ""}`);
-    const manage = provider && http.oauth?.mode === "multi" ? new ManageRoutes(provider, { connectClaimSigningKey: process.env.CONNECT_CLAIM_SIGNING_KEY?.trim() || null, verifyIdentity: process.env.CONNECT_SUPABASE_PUBLISHABLE_KEY?.trim() ? supabaseIdentityVerifier(process.env.CONNECT_SUPABASE_PUBLISHABLE_KEY.trim()) : null }) : undefined;
+    const manage = provider && http.oauth?.mode === "multi" ? new ManageRoutes(provider, { connectClaimSigningKey: process.env.CONNECT_CLAIM_SIGNING_KEY?.trim() || null, connectClaimEdKey: claimEdKeyFromEnv(), verifyIdentity: process.env.CONNECT_SUPABASE_PUBLISHABLE_KEY?.trim() ? supabaseIdentityVerifier(process.env.CONNECT_SUPABASE_PUBLISHABLE_KEY.trim()) : null }) : undefined;
     const server = createHttpServer(config, http, { oauth: provider, recorder, site, manage, publicApi, web });
     server.listen(http.port, http.host, () => {
         const o = http.oauth;

package/dist/manage/routes.js

@@ -74,9 +74,10 @@ export class ManageRoutes {
         // The returned 60-second token is bound to the browser identity separately
         // verified by Connect, and can be consumed only once there.
         if (route === "/connect-claim") {
-            const key = this.options.connectClaimSigningKey;
+            const hmacKey = this.options.connectClaimSigningKey;
+            const edKey = this.options.connectClaimEdKey ?? null;
             const verify = this.options.verifyIdentity;
-            if (!key || key.length < 32 || !verify)
+            if ((!edKey && (!hmacKey || hmacKey.length < 32)) || !verify)
                 return this.json(res, 404, { error: "Not found" });
             if (m !== "POST")
                 return this.json(res, 405, { error: "Method not allowed" }, { Allow: "POST" });
@@ -102,7 +103,7 @@ export class ManageRoutes {
                 return this.json(res, 409, { error: "This account or sign-in is already linked to another" });
             const claim = signConnectClaim({
                 accountId: login.account.id, issuer: who.issuer, subject: who.subject,
-                signingKey: key, nowMs: now,
+                signingKey: hmacKey, edKey, nowMs: now,
             });
             return this.json(res, 200, claim);
         }

package/docs/connect-account-claim.md

@@ -6,6 +6,8 @@ The new `POST /api/manage/connect-claim` route is **disabled unless** the server
 
 The route also needs `CONNECT_SUPABASE_PUBLISHABLE_KEY` (the Paperclipped project's public key; without it the route stays 404). The caller sends `{username, secret, accessToken}`: the bridge asks Supabase Auth who the `accessToken` belongs to (confirmed email, not anonymous, not banned), so issuer and subject are never taken from the request. It then verifies the owner's existing username + secret key via the throttled `manageLogin` function, binds the identity to the account in `bridge.account_identities` (409 if the account or the identity is already bound to another), and returns a 60-second HMAC-SHA256 assertion with `iss=https://papercliped.co`, `aud=papercliped-connect`, canonical account `sub`, unique `jti`, and an SHA256 binding to the claimed OIDC issuer + subject. Connect must independently verify the authenticated OIDC principal, check exact binding and atomically consume the `jti` in `connect.account_assertion_replays`.
 
+**Asymmetric signing (preferred).** With `CONNECT_CLAIM_ED25519_PRIVATE_KEY` set (Ed25519, PKCS#8 PEM, `\n` escapes allowed) the assertion is signed `EdDSA` with header `{alg:"EdDSA", typ:"PCD-ACCOUNT-ASSERTION", v:2, kid}` (`CONNECT_CLAIM_KEY_ID`, default `pcd-claim-1`); Connect verifies with the matching public JWK (`CLAIM_PUBLIC_JWKS`) and rotates keys by kid. If both keys are set the Ed25519 key is used. An invalid Ed25519 key stops startup. `CONNECT_CLAIM_SIGNING_KEY` (HS256, `v:1`) remains for one release and is then removed.
+
 **Security boundaries:** This is **not** an OIDC provider, browser session, Connect entitlement, MCP grant, or Proxmox access. The issuer does not itself verify third-party OIDC identities. The bridge now verifies the Supabase session itself; Connect must still verify binding and consume the `jti`. Do not enable this route until a proper account-claiming UX, CSRF defenses, secret rotation and privacy handling are reviewed. No code is deployed from this branch.
 
 This route does not modify stored accounts or grants. It never stores or returns the user's secret key. Existing plugin sign-in and MCP OAuth behavior are unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papercliped",
-  "version": "2.6.1",
+  "version": "2.7.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",