{"record":{"id":"7d6cbae1052cbe76","repo":"paperclipai/paperclip","slug":"cloud-control-assertion-is-not-a-compact-jws","errorCode":null,"errorMessage":"Cloud control assertion is not a compact JWS","messagePattern":"Cloud control assertion is not a compact JWS","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/src/services/cloud-runtime-identity.ts","lineNumber":512,"sourceCode":"\n/**\n * Verify a Cloud control assertion for one exact action on this instance.\n * Signed with the same key set as the runtime identity assertion\n * (PAPERCLIP_CLOUD_RUNTIME_IDENTITY_JWKS) but under its own JWS type and\n * audience. Instances without a Cloud stack identity reject every assertion —\n * the feature is inert when self-hosted.\n */\nexport function verifyCloudControlAssertion(input: {\n  compactJws: string;\n  expectedAction: CloudControlAction;\n  env?: NodeJS.ProcessEnv;\n  now?: Date;\n}): CloudControlClaims {\n  const env = input.env ?? process.env;\n  const now = input.now ?? new Date();\n  const parts = input.compactJws.split(\".\");\n  if (parts.length !== 3 || parts.some((part) => part.length === 0)) {\n    throw new Error(\"Cloud control assertion is not a compact JWS\");\n  }\n  const [encodedHeader, encodedPayload, encodedSignature] = parts;\n  const header = decodeJsonPart(encodedHeader, \"protected header\");\n  if (\n    header.alg !== \"EdDSA\"\n    || header.typ !== CLOUD_CONTROL_JWS_TYPE\n    || typeof header.kid !== \"string\"\n    || !header.kid\n  ) {\n    throw new Error(\"Cloud control protected header is invalid\");\n  }\n  const key = publicKeyForKid(env, header.kid);\n  const signature = Buffer.from(encodedSignature, \"base64url\");\n  const signingInput = Buffer.from(`${encodedHeader}.${encodedPayload}`, \"ascii\");\n  if (!verify(null, signingInput, key, signature)) {\n    throw new Error(\"Cloud control signature is invalid\");\n  }\n","sourceCodeStart":494,"sourceCodeEnd":530,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/server/src/services/cloud-runtime-identity.ts#L494-L530","documentation":"verifyCloudControlAssertion validates an EdDSA-signed compact JWS assertion used for cloud control-plane requests. The very first structural check splits the token on '.' and requires exactly three non-empty parts (header.payload.signature). This error is thrown when the input is not a three-segment, dot-delimited compact JWS at all.","triggerScenarios":"cloudControlMiddleware / verify receives an Authorization header or assertion value that is empty, whitespace, a raw JWT with fewer/more than three segments, a bearer token of another kind, a base64-encoded blob, or a JWS that was truncated or URL-mangled in transit.","commonSituations":"A client sends a PASETO or opaque token instead of the expected compact JWS; a proxy or reverse proxy stripped or rewrote the header; the caller URL-encoded the token introducing percent escapes; a misconfigured SDK sends its own API key instead of a cloud control assertion.","solutions":["Log the received assertion shape (segment count, lengths only — never the token itself) to confirm whether it has 3 dot-separated non-empty parts","Fix the client/signer to emit a proper compact JWS: base64url(header).base64url(payload).base64url(signature) with EdDSA/Ed25519","Check that no intermediary rewrites, trims, or wraps the Authorization header value","Reject at the client before sending: validate the token format locally with the validation snippet below"],"exampleFix":"// before\nawait fetch(api, { headers: { authorization: `Bearer ${assertion.trim()}` } });\n// after\nconst compact = assertion.trim();\nif (compact.split(\".\").length !== 3 || compact.split(\".\").some(p => p.length === 0)) {\n  throw new Error(\"refusing to send: assertion is not a compact JWS\");\n}\nawait fetch(api, { headers: { authorization: `Bearer ${compact}` } });","handlingStrategy":"validation","validationCode":"function isCompactJws(token) {\n  if (typeof token !== \"string\") return false;\n  const parts = token.split(\".\");\n  return parts.length === 3 && parts.every(p => p.length > 0);\n}\nif (!isCompactJws(assertion)) throw new Error(\"assertion must be a compact JWS before sending\");","typeGuard":"const isCompactJws = (v: unknown): v is string =>\n  typeof v === \"string\" && v.split(\".\").length === 3 && v.split(\".\").every(p => p.length > 0);","tryCatchPattern":"try {\n  const claims = await verifyCloudControlAssertion({ compactJws: token, expectedAction });\n} catch (e) {\n  if (e.message === \"Cloud control assertion is not a compact JWS\") {\n    return respond(401, \"malformed assertion\"); // structural problem: do not retry the same token\n  }\n  throw e;\n}","preventionTips":["Never build tokens by string concatenation; use a JWS signing helper that guarantees the three-part form","Log only segment counts/lengths, never the token, when debugging malformed assertions","Reject malformed tokens client-side before network calls"],"tags":["jws","security","authentication","malformed-token"],"backgroundTag":"invalid-argument-format","analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-22T11:17:16.035Z"}