feat(sdk): add signed manifest helpers

[marmar9615-cloud]

Summary

Second implementation PR for v0.5.0 signed manifests. Adds the
publisher-side signer to @marmarlabs/agentbridge-sdk, building on
the canonicalization + Zod schemas from PR #35. No verifier, no
scanner / MCP / CLI enforcement, no version bump, no behavior change
for unsigned manifests.

• Tracking issue: v0.5.0 — Signed manifests #31
• Design: docs/designs/signed-manifests.md
• ADR: docs/adr/0002-signed-manifests.md
• Predecessor: PR feat(core): add signed manifest schemas and canonicalization #35 (core schemas + canonicalizer) merged at 46adc2c

signManifest(manifest, options)

Returns a NEW manifest with an attached signature block. Input is
never mutated. Any pre-existing signature is stripped before
canonicalization — re-signing produces a fresh signature, never one
over a payload that already contained a stale one.

import { generateKeyPairSync } from "node:crypto";
import { signManifest, createSignedManifest } from "@marmarlabs/agentbridge-sdk";

const { privateKey } = generateKeyPairSync("ed25519");
const signed = signManifest(manifest, {
  kid: "acme-orders-2026-04",
  privateKey,
  // alg defaults to "EdDSA"; pass "ES256" for ECDSA P-256.
  // issuer defaults to new URL(manifest.baseUrl).origin.
  // signedAt defaults to new Date().
  // expiresAt defaults to signedAt + 24h.
});

Algorithms supported

• EdDSA (Ed25519) — default. crypto.sign(null, data, key),
  64-byte raw signature, deterministic.
• ES256 (ECDSA P-256, SHA-256) — crypto.sign("sha256", data, { key, dsaEncoding: "ieee-p1363" }), 64-byte raw r||s output
  (matching JWS ES256, not DER-encoded). For HSM/KMS-bound
  publishers.

RSA-family (RS256, PS256, …) is intentionally excluded per the
v0.5.0 design — adding one in a later release is a non-breaking
enum extension.

Private key input formats

• A Node KeyObject
  (recommended in production).
• A PEM-encoded string.
• A Buffer containing PEM bytes.

Raw 32-byte Ed25519 seeds are not supported in this PR — the
PKCS#8 conversion is non-trivial. Adopters can wrap a seed with their
own KeyObject adapter and pass the result.

Errors never echo private key material; PEM parse failures surface
only the Node error code (ERR_OSSL_BAD_KEY_TYPE etc.).

createSignedManifest(config, options)

Sugar for signManifest(createAgentBridgeManifest(config), options).
Useful for adopters whose build pipeline produces and signs a fresh
manifest each release.

Internals worth flagging

• Canonical bytes match published bytes.
  canonicalizeManifestForSigning now JSON-roundtrips the
  signature-stripped manifest before canonicalizing. SDK-built
  manifests routinely carry undefined in optional slots
  (outputSchema, humanReadableSummaryTemplate, …) when an adopter
  omits them; the publisher's JSON.stringify drops them, and so
  must the signer or no realistic manifest could ever be signed. The
  strict canonicalizeJson is unchanged — it still throws on
  undefined / function / symbol / non-finite numbers when called
  directly. Two new tests in core/canonical.test.ts pin both
  behaviors.
• iss is always a canonical origin. Default is
  new URL(manifest.baseUrl).origin. An explicit options.issuer
  is rejected if URL(s).origin !== s (no trailing slashes, no
  paths, etc.) — this keeps verifier comparisons deterministic.
• Key/algorithm mismatch fails before signing. Ed25519 keys
  paired with alg: "ES256" (or vice versa) reject up front, so
  callers can't accidentally produce a signature with a key the
  verifier expects to be a different curve.

Tests added

packages/sdk/src/tests/signing.test.ts — 39 tests covering:

• Mutation: input manifest unchanged; pre-existing signature
  stripped on re-sign.
• Schema: signature passes ManifestSignatureSchema; alg/iss
  defaults; canonical-origin enforcement.
• Time: signedAt/expiresAt as Date/string; expiresInSeconds;
  default 24h; expiry-before-signedAt rejected; non-positive
  expiresInSeconds rejected.
• Crypto: Ed25519 round-trip via crypto.verify for KeyObject /
  PEM string / PEM Buffer inputs; tamper detection (mutating any
  non-signature field fails verification); cross-key verification
  fails. ES256 round-trip; 64-byte r||s output (not DER).
• Validation: unsupported alg, wrong key type, public KeyObject,
  unparseable PEM (without echoing input), wrong-type
  privateKey, empty kid, malformed manifest.baseUrl with no
  issuer.
• Integration: validateManifest accepts the signed result;
  createSignedManifest end-to-end; signing failures propagate.
• Determinism: re-signing same manifest + same Ed25519 key +
  same signedAt yields identical bytes; createPublicKey
  round-trip.
• Backward compat: unsigned createAgentBridgeManifest still
  validates.

packages/core/src/tests/canonical.test.ts gains 2 new tests for
the canonicalizeManifestForSigning undefined-drop behavior and
the unchanged strict canonicalizeJson.

Confirmations

• Input manifests are not mutated. Verified by mutation
  tests and by structural-clone semantics in the implementation.
• Signed manifests validate through core
  validateManifest. Verified by integration test.
• No verifier / MCP / scanner / CLI enforcement — those
  remain follow-up PRs in the v0.5.0 line.
• Unsigned manifest behavior unchanged. Verified by
  manifest.test.ts, spec-examples.test.ts,
  validateManifest({ ...withoutSignature }) returning the
  same shape, and by re-running the SDK example through
  agentbridge validate.
• No package versions changed. pack:dry-run confirms all
  six @marmarlabs/agentbridge-* packages still at 0.4.0.
• No new dependencies. Pure Node crypto usage.
• package-lock.json untouched.
• No npm publish, no git tag, no GitHub release.
• Dependabot PRs untouched.
• Codex CLI / examples / scripts paths avoided — no
  edits under packages/cli/*, packages/scanner/*,
  examples/*, scripts/*, apps/mcp-server/*,
  docs/releases/*, the root README, or CHANGELOG.md.
• Safety invariants intact — confirmation gate, origin
  pinning, target-origin allowlist, audit redaction, stdio
  stdout hygiene, HTTP transport auth/origin checks all
  unchanged.

Commands run

npm run typecheck:clean                                          # clean
npx vitest run packages/sdk/src/tests/signing.test.ts            # 39/39
npm test                                                         # 339/339 across 21 files (+41 vs 298 on main)
npm run build                                                    # all packages built
npm run pack:dry-run                                             # all six @marmarlabs/agentbridge-* OK at 0.4.0
npx tsx examples/sdk-basic/manifest.ts > /tmp/sdk-basic.agentbridge.json
node packages/cli/dist/bin.js validate /tmp/sdk-basic.agentbridge.json

Test plan

• CI green on Node 20.x and 22.x.
• All package versions remain 0.4.0.
• +41 net new tests (39 SDK signing + 2 core canonical).

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0362c52b3c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".