Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.manthan.systems/llms.txt

Use this file to discover all available pages before exploring further.

Parmana’s core interfaces - Signer, Verifier, and ReplayStore - are designed to be implemented against any infrastructure. The built-in LocalSigner, LocalVerifier, and MemoryReplayStore are the simplest options. This guide shows how to integrate Parmana with AWS KMS, HashiCorp Vault, Redis, and DynamoDB.

​
The interfaces

Everything executeFromSignals needs is expressed through three small interfaces: 
interface Signer {
  sign(payload: string): string | Promise<string>;
}

interface Verifier {
  verify(payload: string, signature: string): boolean | Promise<boolean>;
}

interface ReplayStore {
  reserve(fingerprint: string): Promise<void>;   // claim the slot - reject if already exists
  confirm(fingerprint: string): Promise<void>;   // mark as confirmed
  hasExecuted(fingerprint: string): Promise<boolean>;
  markExecuted(fingerprint: string): Promise<void>;
}
Implement any of these to connect Parmana to your existing infrastructure.

​
Custom Signer - AWS KMS

import { KMSClient, SignCommand, VerifyCommand } from "@aws-sdk/client-kms";
import type { Signer, Verifier } from "@parmanasystems/core";

export class KMSSigner implements Signer {
  private client: KMSClient;
  private keyId:  string;

  constructor(keyId: string, region = "us-east-1") {
    this.client = new KMSClient({ region });
    this.keyId  = keyId;
  }

  async sign(payload: string): Promise<string> {
    const { Signature } = await this.client.send(new SignCommand({
      KeyId:            this.keyId,
      Message:          Buffer.from(payload),
      MessageType:      "RAW",
      SigningAlgorithm: "ECDSA_SHA_256",
    }));
    return Buffer.from(Signature!).toString("base64");
  }
}

export class KMSVerifier implements Verifier {
  private client: KMSClient;
  private keyId:  string;

  constructor(keyId: string, region = "us-east-1") {
    this.client = new KMSClient({ region });
    this.keyId  = keyId;
  }

  async verify(payload: string, signature: string): Promise<boolean> {
    try {
      const { SignatureValid } = await this.client.send(new VerifyCommand({
        KeyId:            this.keyId,
        Message:          Buffer.from(payload),
        MessageType:      "RAW",
        Signature:        Buffer.from(signature, "base64"),
        SigningAlgorithm: "ECDSA_SHA_256",
      }));
      return SignatureValid === true;
    } catch {
      return false;
    }
  }
}
Usage: 
import { executeFromSignals } from "@parmanasystems/core";
import { KMSSigner, KMSVerifier } from "./kms.js";
import { MemoryReplayStore } from "@parmanasystems/core";

const signer   = new KMSSigner(process.env.KMS_KEY_ID!);
const verifier = new KMSVerifier(process.env.KMS_KEY_ID!);

const attestation = await executeFromSignals(
  { policyId: "loan-approval", policyVersion: "1.0.0", signals: { credit_score: 720 } },
  signer,
  verifier,
  new MemoryReplayStore()
);

​
Custom Signer - HashiCorp Vault Transit

import type { Signer } from "@parmanasystems/core";

export class VaultSigner implements Signer {
  constructor(
    private vaultAddr: string,
    private token:     string,
    private keyName:   string
  ) {}

  async sign(payload: string): Promise<string> {
    const input = Buffer.from(payload).toString("base64");
    const res   = await fetch(
      `${this.vaultAddr}/v1/transit/sign/${this.keyName}`,
      {
        method:  "POST",
        headers: { "X-Vault-Token": this.token, "Content-Type": "application/json" },
        body:    JSON.stringify({ input, prehashed: false }),
      }
    );
    if (!res.ok) throw new Error(`Vault sign failed: ${res.status}`);
    const { data } = await res.json() as { data: { signature: string } };
    // Vault returns "vault:v1:<base64>" - strip the prefix
    return data.signature.replace(/^vault:v\d+:/, "");
  }
}

export class VaultVerifier {
  constructor(
    private vaultAddr: string,
    private token:     string,
    private keyName:   string
  ) {}

  async verify(payload: string, signature: string): Promise<boolean> {
    const input = Buffer.from(payload).toString("base64");
    const res   = await fetch(
      `${this.vaultAddr}/v1/transit/verify/${this.keyName}`,
      {
        method:  "POST",
        headers: { "X-Vault-Token": this.token, "Content-Type": "application/json" },
        body:    JSON.stringify({ input, signature: `vault:v1:${signature}` }),
      }
    );
    if (!res.ok) return false;
    const { data } = await res.json() as { data: { valid: boolean } };
    return data.valid;
  }
}

​
Custom ReplayStore - Redis (ioredis)

import Redis from "ioredis";
import type { ReplayStore } from "@parmanasystems/core";

export class RedisReplayStore implements ReplayStore {
  private client: Redis;

  constructor(redisUrl: string) {
    this.client = new Redis(redisUrl);
  }

  async reserve(fingerprint: string): Promise<void> {
    const key    = `parmana:replay:${fingerprint}`;
    const result = await this.client.set(key, "reserved", "NX");
    if (result === null) {
      throw new Error(`[INV-013] Replay detected: ${fingerprint}`);
    }
  }

  async confirm(fingerprint: string): Promise<void> {
    const key = `parmana:replay:${fingerprint}`;
    await this.client.set(key, "confirmed", "XX");
  }

  async hasExecuted(fingerprint: string): Promise<boolean> {
    const val = await this.client.get(`parmana:replay:${fingerprint}`);
    return val === "confirmed";
  }

  async markExecuted(fingerprint: string): Promise<void> {
    await this.confirm(fingerprint);
  }

  async disconnect(): Promise<void> {
    await this.client.quit();
  }
}
The key NX flag on SET is atomic in Redis - two concurrent requests with the same fingerprint will result in exactly one succeeding and the other receiving null. This is the replay protection guarantee.

​
Custom ReplayStore - DynamoDB

import {
  DynamoDBClient,
  PutItemCommand,
  GetItemCommand,
} from "@aws-sdk/client-dynamodb";
import type { ReplayStore } from "@parmanasystems/core";

export class DynamoReplayStore implements ReplayStore {
  private client: DynamoDBClient;

  constructor(
    private tableName: string,
    region = "us-east-1",
    private ttlDays  = 30
  ) {
    this.client = new DynamoDBClient({ region });
  }

  private ttl(): number {
    return Math.floor(Date.now() / 1000) + this.ttlDays * 86400;
  }

  async reserve(fingerprint: string): Promise<void> {
    try {
      await this.client.send(new PutItemCommand({
        TableName: this.tableName,
        Item: {
          fingerprint: { S: fingerprint },
          status:      { S: "reserved" },
          ttl:         { N: String(this.ttl()) },
        },
        ConditionExpression: "attribute_not_exists(fingerprint)",
      }));
    } catch (err: unknown) {
      if (err instanceof Error && err.name === "ConditionalCheckFailedException") {
        throw new Error(`[INV-013] Replay detected: ${fingerprint}`);
      }
      throw err;
    }
  }

  async confirm(fingerprint: string): Promise<void> {
    await this.client.send(new PutItemCommand({
      TableName: this.tableName,
      Item: {
        fingerprint: { S: fingerprint },
        status:      { S: "confirmed" },
        ttl:         { N: String(this.ttl()) },
      },
    }));
  }

  async hasExecuted(fingerprint: string): Promise<boolean> {
    const { Item } = await this.client.send(new GetItemCommand({
      TableName: this.tableName,
      Key: { fingerprint: { S: fingerprint } },
    }));
    return Item?.status?.S === "confirmed";
  }

  async markExecuted(fingerprint: string): Promise<void> {
    await this.confirm(fingerprint);
  }
}
DynamoDB table setup (CloudFormation): 
Type: AWS::DynamoDB::Table
Properties:
  TableName: parmana-replay
  BillingMode: PAY_PER_REQUEST
  AttributeDefinitions:
    - AttributeName: fingerprint
      AttributeType: S
  KeySchema:
    - AttributeName: fingerprint
      KeyType: HASH
  TimeToLiveSpecification:
    AttributeName: ttl
    Enabled: true

​
Wiring it together

import { executeFromSignals, verifyAttestation } from "@parmanasystems/core";
import { KMSSigner, KMSVerifier } from "./kms.js";
import { DynamoReplayStore } from "./dynamo-store.js";

async function main() {
  const signer   = new KMSSigner(process.env.KMS_KEY_ID!);
  const verifier = new KMSVerifier(process.env.KMS_KEY_ID!);
  const store    = new DynamoReplayStore(process.env.DYNAMO_TABLE!);

  const attestation = await executeFromSignals(
    {
      policyId:      "loan-approval",
      policyVersion: "1.0.0",
      signals:       { credit_score: 720, loan_amount: 15000 },
    },
    signer,
    verifier,
    store
  );

  console.log(attestation.decision);
  // { action: "approve", requires_override: false, reason: "Credit score meets standard threshold." }

  // Verify locally - no round trip needed
  const result = await verifyAttestation(attestation, verifier);
  console.log(result.valid); // true
}

main().catch(console.error);

​
Lambda integration

Parmana works in AWS Lambda without modification. Initialize outside the handler to reuse connections across warm invocations: 
import { executeFromSignals } from "@parmanasystems/core";
import { KMSSigner, KMSVerifier } from "./kms.js";
import { DynamoReplayStore } from "./dynamo-store.js";

// Initialize once outside the handler
const signer   = new KMSSigner(process.env.KMS_KEY_ID!);
const verifier = new KMSVerifier(process.env.KMS_KEY_ID!);
const store    = new DynamoReplayStore(process.env.DYNAMO_TABLE!);

export const handler = async (event: { signals: Record<string, unknown> }) => {
  const attestation = await executeFromSignals(
    {
      policyId:      "payment-approval",
      policyVersion: "1.0.0",
      signals:       event.signals,
    },
    signer,
    verifier,
    store
  );

  return {
    decision:    attestation.decision,
    executionId: attestation.executionId,
    signature:   attestation.signature,
  };
};

​
See also