{"record":{"id":"9327967e1453bc44","repo":"coleam00/Archon","slug":"malformed-embedded-checksum-checksum","errorCode":null,"errorMessage":"Malformed embedded checksum: \"${checksum}\"","messagePattern":"Malformed embedded checksum: \"(.+?)\"","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/serve.ts","lineNumber":32,"sourceCode":"\n/**\n * Upper bound on the `tar` child. Extracting the ~2 MB release archive takes\n * tens of milliseconds, so this leaves three orders of magnitude of headroom for\n * a slow disk. Its only job is to stop a stalled child from turning\n * `archon serve` into a silent permanent hang: the parent-owned stdin channel\n * that caused the observed stall is gone (#2924), but filesystem-side stalls on\n * windows were never ruled out, and there is no budget in production to end one.\n */\nconst EXTRACTION_TIMEOUT_MS = 60_000;\n\nfunction toError(err: unknown): Error {\n  return err instanceof Error ? err : new Error(String(err));\n}\n\nexport function parseEmbeddedChecksum(checksum: string): string {\n  const normalized = checksum.trim();\n  if (!/^[0-9a-f]{64}$/.test(normalized)) {\n    throw new Error(`Malformed embedded checksum: \"${checksum}\"`);\n  }\n  return normalized;\n}\n\nexport interface ServeOptions {\n  /** TCP port to bind. Ignored when downloadOnly is true. Range: 1–65535. */\n  port?: number;\n  /** Download the web UI and exit without starting the server. */\n  downloadOnly?: boolean;\n}\n\nexport async function serveCommand(opts: ServeOptions): Promise<number> {\n  if (\n    opts.port !== undefined &&\n    (!Number.isInteger(opts.port) || opts.port < 1 || opts.port > 65535)\n  ) {\n    console.error(`Error: --port must be an integer between 1 and 65535, got: ${opts.port}`);\n    return 1;","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/coleam00/Archon/blob/0773b9745896ef0612e709c80845a0f7db315b19/packages/cli/src/commands/serve.ts#L14-L50","documentation":"parseEmbeddedChecksum validates the checksum string embedded in the built CLI binary. It throws when the value is not exactly 64 lowercase hex characters (a SHA-256 hex digest) after trimming, guarding against corrupted or stale embedded build metadata before it is used to verify the downloaded web dist tarball.","triggerScenarios":"Calling parseEmbeddedChecksum (via downloadWebDist during serve --download) with an embedded checksum that is empty, truncated, uppercase, or contains non-hex characters — typically a binary built without the web-dist checksum injection step.","commonSituations":"Building the CLI with a custom/modified build script that skips checksum embedding; stale binary from before the checksum feature; hand-edited binary constants; running a dev build where the placeholder was never replaced.","solutions":["Rebuild the CLI through the official build pipeline (scripts/build-binaries.sh / owning package scripts) so the real SHA-256 checksum is embedded.","Download the latest released binary instead of a locally modified or dev one.","Inspect the embedded constant to confirm what value is actually baked in, and compare against the generated checksums file.","As an operator workaround on dev builds, rely on the non-embedded path (remote checksums download) rather than the embedded one."],"exampleFix":"// before: dev binary with placeholder\nconst embedded = 'PLACEHOLDER';\n// after: rebuild so the build script injects the digest\nconst embedded = '9f2c...64-hex-sha256...';","handlingStrategy":"validation","validationCode":"function isValidSha256Hex(s: string): boolean {\n  return /^[0-9a-f]{64}$/.test(s.trim());\n}\nif (!isValidSha256Hex(embeddedChecksum)) {\n  throw new Error('Embedded checksum missing or malformed; rebuild via official pipeline');\n}","typeGuard":"function isSha256Hex(value: unknown): value is string {\n  return typeof value === 'string' && /^[0-9a-f]{64}$/.test(value);\n}","tryCatchPattern":"try {\n  await serveCommand({ downloadOnly: true });\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Malformed embedded checksum')) {\n    // fall back to remote-checksums mode or rebuild the binary\n  }\n}","preventionTips":["Always build the CLI via the owning build script so checksums are injected.","Verify the embedded constant in CI before publishing binaries.","Never hand-edit built binaries."],"tags":["checksum","sha256","build","validation"],"backgroundTag":"invalid-checksum-format","analyzedSha":"0773b9745896ef0612e709c80845a0f7db315b19","analyzedAt":"2026-09-01T02:28:07.064Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}