Postgres Token State Backend

@caracalai/tokenstate-postgres stores token-state rows in Postgres for TypeScript services that need durable mandate state.

Install

npm install @caracalai/tokenstate-postgres

The package targets Node >=22.

Schema

The package exports MCP_TOKEN_STATE_DDL, which creates:

CREATE TABLE IF NOT EXISTS mcp_token_state (
  zone_id TEXT NOT NULL,
  sub TEXT NOT NULL,
  scope TEXT NOT NULL,
  expires_at TIMESTAMPTZ NOT NULL,
  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  PRIMARY KEY (zone_id, sub)
);

Backend

import { MCP_TOKEN_STATE_DDL, PostgresBackend } from "@caracalai/tokenstate-postgres";

await pool.query(MCP_TOKEN_STATE_DDL);

const backend = new PostgresBackend(pool);
await backend.set({
  zone_id: "zone_prod",
  sub: "agent_123",
  scope: "tickets:read",
  expires_at: new Date(Date.now() + 60_000).toISOString(),
});

Use cases

• Persisting active token state across service restarts.
• Sharing token-state reads across multiple TypeScript resource-server instances.
• Building custom resource-server controls that need a small (zone_id, sub, scope) state table.

Boundary

This package is a token-state backend. It is not the revocation stream consumer. Use Redis Revocation Store when you need to consume caracal.sessions.revoke.