@lyhna/gate

Express adapter for Lyhna's bind() authority boundary. Every request goes through Lyhna's enforcement core before your handler runs. Approved requests continue; refused and escalated requests are blocked with a structured receipt.

Install

npm install @lyhna/gate

Set your API key in the environment:

export LYHNA_API_KEY=sk-...

Usage

import express from 'express';
import { lyhnaGate } from '@lyhna/gate';

const app = express();
app.use(express.json());

app.post(
  '/api/transfer',
  lyhnaGate({
    action_type: 'financial_transfer',
    intent: 'initiate_transfer',
    intent_version: 'v1',
    payloadFrom: (req) => ({
      amount: req.body.amount,
      recipient: req.body.recipient,
    }),
  }),
  (req, res) => {
    // Only reached when Lyhna returns APPROVED
    const receipt = req.lyhna_receipt;
    res.json({ ok: true, receipt_id: receipt?.receipt_id });
  },
);

Configuration

| Field | Type | Required | Description | |---|---|---|---| | action_type | string | Yes | Canonical action identifier registered with Lyhna | | intent | string | Yes | Intent name for this bind call | | intent_version | string | Yes | Intent version string (e.g. "v1") | | payloadFrom | (req) => Record<string, unknown> | Yes | Synchronous function that extracts the action payload from the request | | attachAs | string | No | Key to attach the receipt on req. Defaults to "lyhna_receipt" |

The adapter does not accept apiKey or baseUrl. Key and endpoint are read from environment variables by @lyhna/bind:

| Env var | Default | Description | |---|---|---| | LYHNA_API_KEY | — | Required. Your tenant API key | | LYHNA_ENDPOINT | https://api.lyhna.com | Optional. Override the enforcement core URL |

Response envelopes

APPROVED — your route handler runs; req.lyhna_receipt contains the full LyhnaReceiptV2.

REFUSED (403):

{
  "outcome": "REFUSED",
  "execution": "blocked_refused",
  "receipt": { "...": "..." },
  "reason": "Action refused by Lyhna governance policy",
  "escalate_to": null
}

ESCALATED (202):

{
  "outcome": "ESCALATED",
  "execution": "blocked_pending_authority",
  "receipt": { "...": "..." },
  "reason": "Higher authority required",
  "escalate_to": "human_governor"
}

GATE_ERROR (503) — configuration or transport failure:

{
  "outcome": "GATE_ERROR",
  "execution": "blocked_gate_error",
  "receipt": null,
  "reason": "gate_transport_unavailable",
  "escalate_to": null
}

TypeScript

The req.lyhna_receipt type is automatically augmented on Express.Request:

import type { LyhnaReceiptV2 } from '@lyhna/gate';
// or directly from @lyhna/bind

Links

• Lyhna documentation
• Dashboard