@agentplat/mesh-crypto
Provider-neutral Web Crypto contracts for hashing, signing and verifying AgentPlat Mesh envelopes.
Installation (developer preview)
Install the coordinated preview explicitly:
npm install @agentplat/mesh-crypto@next
Keep all @agentplat/* packages on the same release version. npm's default
latest tag can point to an older preview. See the
release channels
for distribution status and version selection.
The Alpha 1 implementation provides:
- canonical SHA-256 payload digests;
- Ed25519 signing and verification through Web Crypto;
- stable fail-closed signing and verification errors;
- exact tenant, mesh, peer, key and algorithm binding;
- inclusive
validFrom, exclusivevalidUntiland explicit revocation checks; - a fixed, bounded
StaticMeshKeyResolver; and - public verification fixtures under
fixtures/v0.
Use signMeshEnvelope for the reference outbound path and
verifyMeshEnvelope for the inbound cryptographic boundary. Injectable class
implementations are available through createWebCryptoMeshEnvelopeSigner and
createWebCryptoMeshEnvelopeVerifier.
signMeshEnvelopeExternally supports KMS/HSM custody. AgentPlat canonicalizes
and hashes the envelope locally, then passes only the immutable signing bytes,
algorithm and declared key ID to a MeshExternalSignaturePort. The returned
value must be an exact 64-byte Ed25519 signature and is revalidated as a normal
Mesh envelope. The port never receives or returns a private key. Provider
adapters must still bind workload identity, canonical key ID, audit retention,
timeouts and rotation policy; an arbitrary remote signing service is not by
itself evidence of independent custody.
The protocol proof.keyId remains a bounded opaque Mesh identifier, not a
provider ARN. The external signature port must bind that identifier to the
canonical KMS/HSM resource recorded in deployment evidence; it must never trust
an ARN supplied inside an envelope.
The Beta 1 signer writes v1 by default. Producing a compatibility v0 envelope
requires an immutable construction-bound signingPolicy that lists v0; the
signer never relabels an envelope. The verifier reads v0 and v1 by default and
may be narrowed through allowedWireVersions. Because wireVersion is in the
signing document, copying a valid proof between versions fails verification.
Key resolution is synchronous by design so ordinary inbound verification cannot
trigger network access. StaticMeshKeyResolver rejects duplicate bindings and
configurations above its explicit record limit.
verifiedAt is trusted local time supplied by the caller; key validity and
revocation never depend on the sender-controlled envelope timestamp. Live
verification always rejects revoked keys. A separate historical-verification
API may be introduced later, but historical results must never re-enter live
admission or a reducer.
Public-key import and export use the provider-neutral raw 32-byte Ed25519 representation. Private-key import and export are intentionally outside this package's public surface.
Verification establishes payload integrity, signature validity and authentication of possession of a live locally bound key. It does not provide confidentiality or establish the truth of a sender claim; it does not admit a peer, authorize a message, apply replay state or mutate domain state.
Private keys are never protocol payloads, fixtures or telemetry. Signing tests generate temporary key pairs at runtime; public fixtures contain only a raw public key and its fixed signed envelope.