API reference

The core authorize() function and the types it uses. Everything an agent needs to check whether an action is allowed before it runs.

Plain-English model: a request is what the agent wants to do. A policy is your local checklist for what is allowed. A decisionis Shotoku’s answer — approved, denied, or pending. The ledger is the append-only local audit log.

authorize(request, options)

The main function. Describe what the agent wants to do, point it at your policy file and ledger, and it returns a decision.

import { authorize } from "@shotoku/core";

const response = await authorize(
  {
    actor:    "agent-001",
    action:   "api_call",
    resource: "api.openai.com",
    amount:   0.02,
  },
  {
    policyPath: "./policy.yaml",
    ledgerPath: "./data/decisions.jsonl",
  },
);

Under the hood it:

1. Loads your policy file
2. Reads rolling 24-hour spend totals from the ledger
3. Evaluates the request against your rules
4. Writes the decision to the ledger
5. Returns the result

Shotoku fails closed. If the request is malformed, the policy file is missing or invalid, or the ledger is corrupt, Shotoku does not approve the action.

Options

AuthorizeRequest

Describes the action an agent wants to take.

interface AuthorizeRequest {
  readonly actor:    string;
  readonly action:   AgentAction;
  readonly resource: string;
  readonly rail?:    ExecutionRail;
  readonly amount?:  number;
  readonly context?: Record<string, unknown>;
}

AuthorizeResponse

What authorize() gives back.

interface AuthorizeResponse {
  readonly approved:    boolean;
  readonly status:      AuthorizationStatus;
  readonly reasons:     readonly ReasonItem[];
  readonly explanation: Explanation;
  readonly decisionId:  string;
  readonly timestamp:   string;
}

AuthorizationStatus

The three possible outcomes of an authorization check.

type AuthorizationStatus = "approved" | "denied" | "pending_approval";

AgentAction

The type of thing an agent wants to do.

type AgentAction =
  | "purchase"
  | "api_call"
  | "execute_code"
  | "send_email"
  | "mcp_tool"
  | "custom";

Use custom for anything that does not fit the other categories.

ExecutionRail

The channel through which an action would be executed. Optional — include it when you want to write rules that apply to a specific channel only.

type ExecutionRail = "x402" | "mcp" | "api" | "code" | "custom";

ReasonItem

One specific check that ran during policy evaluation. A decision always includes one or more of these.

interface ReasonItem {
  readonly type:
    | "policy_match"
    | "budget_check"
    | "limit_check"
    | "blocked"
    | "escalated";
  readonly text: string;
}

LedgerEntry

One recorded decision. Stored as a single line in decisions.jsonl — one JSON object per line, append-only. Each line is a self-contained record of one decision. You can inspect the file directly in any text editor.

interface LedgerEntry {
  readonly decisionId: string;
  readonly timestamp:  string;
  readonly request:    AuthorizeRequest;
  readonly response:   AuthorizeResponse;
}

Every new ledger record includes an integrity object that links it to the previous ledger hash:

interface LedgerIntegrity {
  readonly version:      1;
  readonly sequence:     number;
  readonly previousHash: string;
  readonly hash:         string;
}

If a ledger line is malformed, Shotoku reports the ledger as corrupt instead of skipping the bad line. Skipping would make budgets and approval state hard to trust.

Signed snapshots

A signed snapshot records the hash of the policy file, the current ledger head hash, and a keyed signature over those fields. Use snapshots when you want to prove later that the policy and ledger head have not changed since a point in time.

import { createSignedSnapshot, verifySignedSnapshot } from "@shotoku/core";

const snapshot = await createSignedSnapshot({
  policyPath: "./policy.yaml",
  ledgerPath: "./data/decisions.jsonl",
  secret:     process.env.SHOTOKU_SNAPSHOT_SECRET!,
});

const result = await verifySignedSnapshot(snapshot, {
  secret: process.env.SHOTOKU_SNAPSHOT_SECRET!,
});

Shotoku uses HMAC-SHA256 for local snapshots. It does not create, store, or manage signing keys — the secret comes from the caller.