@openlatch/tool-sdk

Standard Webhooks v1 verify/sign + Express + Hono middleware for OpenLatch detection tools. Pairs with openlatch-provider listen (HMAC verification happens there) or stands on its own when the tool server is exposed publicly.

Install

npm install @openlatch/tool-sdk
# Peer-dep one of:
npm install express
# or
npm install hono

Express

import express from 'express';
import { tool } from '@openlatch/tool-sdk/express';

const app = express();

app.post(
  '/event',
  tool(
    {
      // Drop `secret` when running behind `openlatch-provider listen` —
      // that daemon does HMAC verify for you. Include it for standalone
      // public deployments.
      secret: process.env.OPENLATCH_WHSEC,
      category: 'credential_detection',
    },
    async (event) => {
      const text = JSON.stringify(event.tool_call?.input ?? {});
      if (/AKIA[0-9A-Z]{16}/.test(text)) {
        return {
          riskScore: 99,
          severityHint: 'critical',
          verdictHint: 'deny',
          ruleId: 'aws.access_key',
          rationaleSummary: 'AWS access key detected',
        };
      }
      return { riskScore: 5, severityHint: 'low', verdictHint: 'allow' };
    },
  ),
);

app.listen(8081);

Hono

import { Hono } from 'hono';
import { tool } from '@openlatch/tool-sdk/hono';

const app = new Hono();
app.post('/event', tool({ secret: process.env.OPENLATCH_WHSEC }, async (event) => {
  return { riskScore: 5, severityHint: 'low', verdictHint: 'allow' };
}));

Direct API

import { computeSignature, signResponse, verify } from '@openlatch/tool-sdk';

Verdict shape

The Verdict type is the camelCase subset of provider-call.schema.json:

| Field | Type | |---|---| | riskScore | int 0-100 | | severityHint | 'low' \| 'medium' \| 'high' \| 'critical' | | verdictHint | 'allow' \| 'approve' \| 'deny' | | ruleId | string ≤120 | | rationaleSummary | string ≤500 | | userFacing | { headline, body, evidence[], remediation } | | enrichment | arbitrary JSON | | latencyMs | int ≥0 (auto-filled if omitted) |

Per-action scoring + config state

Optional v2 contract additions:

import { scoreToSeverity, type ActionScore, type Verdict } from '@openlatch/tool-sdk';

async (event) => {
  // Stateful config/integrity detectors: prior artifact state arrives as
  // the `priorconfigstate` CloudEvents extension when the capability
  // declares `needs_prior_config_state: true` in the manifest.
  const prior = event.priorconfigstate;
  const risk = 87;
  return {
    riskScore: risk,
    severityHint: scoreToSeverity(risk),
    verdictHint: 'deny',
    actions: [
      {
        actionRef: 'cmd:0',                 // "{kind}:{index}" join key
        riskScore: risk,
        severity: scoreToSeverity(risk),
        threatCategory: 'shell_dangerous',  // routing 12-category
        axes: { destructive: 18, exfil: 0, secret: 0, privesc: 0, reversibility: 20 },
      },
    ] satisfies ActionScore[],
  } satisfies Verdict;
};

• Verdict.actions — optional ActionScore[] (≤256). Absent ⇒ the platform records per-action risk as null (gap-tolerant).
• CloudEvent.priorconfigstate — the prior_config_state CloudEvents extension (lowercase per the CloudEvents ^[a-z0-9]+$ rule); populated only for capabilities declaring needs_prior_config_state: true.
• scoreToSeverity(riskScore) — canonical <40 / 40-69 / 70-89 / 90+ buckets. First-party tools MUST derive severity from this so the bucket invariant holds by construction (the platform trusts the provider-reported severity verbatim).

Releases

@openlatch/tool-sdk is released in lock-step with openlatch-provider via release-please. Land conventional-commit PRs against main; release-please opens a Release PR bumping all three packages (openlatch-provider on crates.io + npm, openlatch-tool-sdk on PyPI, @openlatch/tool-sdk on npm). Merging the Release PR creates a v* tag and the unified publish.yml workflow publishes everything via OIDC trusted publishing.