@lyhna/bind

The execution boundary for autonomous AI systems.

bind() is a pre-execution gate that produces cryptographically signed, offline-verifiable receipts on every outcome (APPROVED, REFUSED, ESCALATED). Fail-closed by construction.

Constitutional invariant: no receipt, no execution.

Installation

npm install @lyhna/bind

Quick start

import { bind } from '@lyhna/bind';

const receipt = await bind({
  action_type: 'deploy_service',
  action_payload: { service: 'api', version: 'v3' },
  intent: 'release_v3',
  intent_version: '1.0',
});

if (receipt.outcome === 'APPROVED') {
  // proceed — the receipt is your proof of authority
  await deployService({ license: receipt });
} else if (receipt.outcome === 'REFUSED') {
  console.error('Denied by policy:', receipt.reason);
} else if (receipt.outcome === 'ESCALATED') {
  // authority required; see awaitResolution() below
}

Configuration

bind() requires two environment variables:

If either is missing, bind() throws. There is no local fallback.

The request contract

bind() accepts exactly four fields. All required. No aliases.

interface BindRequest {
  action_type: string;       // what you intend to do
  action_payload: object;    // parameters of the action
  intent: string;            // declared business purpose
  intent_version: string;    // version of the intent
}

You do not send authority_tier. Authority tier is determined exclusively by Lyhna's canonical registry and your tenant authority rules — configured through the dashboard, never by the caller.

Outcomes

bind() returns one of three outcomes, all represented as a signed receipt:

• APPROVED — the action is bound; you may proceed.
• REFUSED — policy denied the action; you must not proceed.
• ESCALATED — authority required; the action waits for a human or higher-tier decision.

Handling ESCALATED

bind() returns immediately on ESCALATED. It does not block. The receipt contains escalate_to metadata identifying who needs to approve.

If your code wants to wait synchronously for the escalation to resolve, use awaitResolution():

import { bind, awaitResolution } from '@lyhna/bind';

const receipt = await bind({
  action_type: 'deploy_production',
  action_payload: { version: 'v3' },
  intent: 'release_v3',
  intent_version: '1.0',
});

if (receipt.outcome === 'ESCALATED') {
  const resolved = await awaitResolution(receipt, {
    pollIntervalMs: 5000,
    timeoutMs: 300_000,
  });
  if (resolved.outcome === 'APPROVED') {
    await deployProduction({ license: resolved });
  }
}

awaitResolution() polls the enforcement core and resolves when:

• The receipt transitions to APPROVED or REFUSED
• The receipt expires (expires_at reached — throws)
• The polling timeout is reached (throws)

Offline receipt verification

Every receipt carries its own signature and public key. You can verify a receipt anywhere, without contacting Lyhna:

import { verifyReceipt } from '@lyhna/bind';

const valid = await verifyReceipt(receipt);
if (!valid) {
  throw new Error('Receipt failed integrity check');
}

When LYHNA_API_KEY and LYHNA_ENDPOINT are set, verifyReceipt() also consults the server for replay, revocation, and tenant-scope checks.

CLI

lyhna verify path/to/receipt.json

Constitutional invariants

• Fail-closed — no license, no execution
• Deterministic — same input, same outcome
• Append-only — receipts are never mutated
• Verifiable offline — Ed25519, no call home required
• Declared deltas — the submitting authority declares material changes
• Tenant-sovereign — data never crosses tenant boundaries

Failure modes

bind() throws — it does not return fake receipts — when:

• LYHNA_API_KEY or LYHNA_ENDPOINT is missing
• Request fields are malformed
• The enforcement core is unreachable
• The server returns a non-200 status
• The response is not valid JSON
• The response does not contain a receipt

A thrown error means the action was not bound. Your code must not proceed as if it had been.

License

MIT