moss-java

Overview

Cryptographic Parameters (ML-DSA-44 / FIPS 204)

Installation

Maven

<dependency>
    <groupId>com.mosscomputing</groupId>
    <artifactId>moss-sdk</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle

implementation 'com.mosscomputing:moss-sdk:0.1.0'

Quick Start

Local signing (no API key required)

import com.mosscomputing.moss.*;

public class Example {
    public static void main(String[] args) throws MossException {
        // Generate an ML-DSA-44 key pair (pub=1312 bytes, sec=2560 bytes)
        MossKeyPair keyPair = MossSigner.generateKeyPair();
        
        byte[] message = "hello world".getBytes();
        
        // Sign — produces a 2420-byte ML-DSA-44 signature
        byte[] signature = MossSigner.sign(message, keyPair);
        System.out.println("Signature length: " + signature.length); // 2420
        
        // Verify — real cryptographic verification (not a length check)
        boolean valid = MossSigner.verify(message, keyPair.getPublicKey(), signature);
        System.out.println("Valid: " + valid); // true
        
        // Tampered message — verification fails
        byte[] tampered = "hello world!".getBytes();
        boolean tamperedValid = MossSigner.verify(tampered, keyPair.getPublicKey(), signature);
        System.out.println("Tampered valid: " + tamperedValid); // false
    }
}

Enterprise mode (with API key)

import com.mosscomputing.moss.*;
import java.util.Map;

public class EnterpriseExample {
    public static void main(String[] args) throws MossException {
        MossClient client = MossClient.builder()
            .apiKey(System.getenv("MOSS_API_KEY"))
            .build();
        
        // Sign any agent output
        SignResult result = client.sign(SignRequest.builder()
            .payload(Map.of("action", "transfer", "amount", 500))
            .agentId("agent-finance-01")
            .build());
        
        System.out.println("Signed! Hash: " + result.getEnvelope().getPayloadHash());

        // Verify offline
        VerifyResult verifyResult = client.verify(
            Map.of("action", "transfer", "amount", 500),
            result.getEnvelope()
        );
        
        if (verifyResult.isValid()) {
            System.out.println("Verified! Signed by: " + verifyResult.getSubject());
        }
    }
}

Features

API Reference

MossSigner (ML-DSA-44 primitives)

// Generate key pair
MossKeyPair keyPair = MossSigner.generateKeyPair();
// keyPair.getPublicKey().length == 1312
// keyPair.getSecretKey().length == 2560

// Sign
byte[] signature = MossSigner.sign(message, keyPair);
// signature.length == 2420

// Verify
boolean valid = MossSigner.verify(message, keyPair.getPublicKey(), signature);
// true for honest signatures, false for tampered/zero signatures

MossClient

// Create client
MossClient client = MossClient.builder()
    .apiKey(System.getenv("MOSS_API_KEY"))
    .baseUrl("https://api.mosscomputing.com") // optional
    .build();

Sign

SignResult result = client.sign(SignRequest.builder()
    .payload(payload)           // Any serializable object
    .agentId("agent-id")       // Agent identifier
    .action("action-name")     // Optional action type
    .context(Map.of(...))      // Optional metadata
    .build());

Verify

VerifyResult verifyResult = client.verify(payload, envelope);
// verifyResult.isValid(): true if signature valid
// verifyResult.getSubject(): signing agent ID

Envelope

Envelope envelope = result.getEnvelope();
envelope.getSpec();        // "moss-0001"
envelope.getVersion();     // 1
envelope.getAlg();         // "ML-DSA-44"
envelope.getSubject();     // Agent ID
envelope.getKeyVersion();  // Key version for rotation
envelope.getSeq();         // Sequence number
envelope.getIssuedAt();    // Unix timestamp
envelope.getPayloadHash(); // SHA-256 of payload
envelope.getSignature();   // ML-DSA-44 signature (base64url, 2420 bytes raw)

Configuration

Links

License