commit-guard-protocol 0.1.0

package/dist/chunk-WLDMTPVD.js

@@ -0,0 +1,301 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/next/index.ts
+var next_exports = {};
+__export(next_exports, {
+  createCommitGuardToolkit: () => createCommitGuardToolkit,
+  defineCommitGuardRoute: () => defineCommitGuardRoute,
+  zodSchema: () => zodSchema
+});
+
+// src/commit-context.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function canonicalize(value) {
+  if (value === null) return null;
+  const t = typeof value;
+  if (t !== "object") return value;
+  if (Array.isArray(value)) return value.map(canonicalize);
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  const out = {};
+  for (const k of keys) {
+    const v = obj[k];
+    if (v !== void 0) out[k] = canonicalize(v);
+  }
+  return out;
+}
+function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}
+function base64urlEncode(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64urlDecodeToBuffer(s) {
+  const padLen = (4 - s.length % 4) % 4;
+  const padded = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat(padLen);
+  return Buffer.from(padded, "base64");
+}
+function hmacSha256(secret, data) {
+  return createHmac("sha256", secret).update(data).digest();
+}
+function signCommitContext(secret, ctx) {
+  const payload = canonicalJson(ctx);
+  const sig = base64urlEncode(hmacSha256(secret, payload));
+  return { ctx, sig };
+}
+function validateCommitContextShape(ctx) {
+  return ctx && typeof ctx === "object" && ctx.v === 1 && typeof ctx.action === "string" && "args" in ctx && typeof ctx.idempotency_key === "string" && typeof ctx.expires_at === "number";
+}
+function verifySignedCommitContext(params) {
+  const { secret, signed, expectedAction } = params;
+  const nowMs = params.nowMs ?? Date.now();
+  if (!signed || typeof signed !== "object") {
+    return {
+      ok: false,
+      error: { code: "MALFORMED_COMMIT", message: "Missing commit payload." }
+    };
+  }
+  const { ctx, sig } = signed;
+  if (!validateCommitContextShape(ctx) || typeof sig !== "string") {
+    return {
+      ok: false,
+      error: { code: "MALFORMED_COMMIT", message: "Invalid commit context shape." }
+    };
+  }
+  if (ctx.action !== expectedAction) {
+    return {
+      ok: false,
+      error: {
+        code: "ACTION_MISMATCH",
+        message: "Commit action mismatch.",
+        details: { expected: expectedAction, got: ctx.action }
+      }
+    };
+  }
+  if (nowMs > ctx.expires_at) {
+    return {
+      ok: false,
+      error: { code: "EXPIRED_COMMIT", message: "Commit context expired." }
+    };
+  }
+  const payload = canonicalJson(ctx);
+  const expectedSig = base64urlEncode(hmacSha256(secret, payload));
+  let a;
+  let b;
+  try {
+    a = base64urlDecodeToBuffer(sig);
+    b = base64urlDecodeToBuffer(expectedSig);
+  } catch {
+    return {
+      ok: false,
+      error: { code: "INVALID_SIGNATURE", message: "Invalid commit signature." }
+    };
+  }
+  if (a.length !== b.length) {
+    return {
+      ok: false,
+      error: { code: "INVALID_SIGNATURE", message: "Invalid commit signature." }
+    };
+  }
+  if (!timingSafeEqual(a, b)) {
+    return {
+      ok: false,
+      error: { code: "INVALID_SIGNATURE", message: "Invalid commit signature." }
+    };
+  }
+  return { ok: true, ctx };
+}
+
+// src/cgp.ts
+function fail(error, debug) {
+  return { phase: "FAILED", error, debug };
+}
+async function commit(req, opts) {
+  const now = opts.nowMs ? opts.nowMs() : Date.now();
+  const verified = verifySignedCommitContext({
+    secret: opts.secret,
+    signed: req.commit,
+    expectedAction: opts.action,
+    nowMs: now
+  });
+  if (!verified.ok) return fail(verified.error);
+  let args;
+  try {
+    args = opts.schema.parse(verified.ctx.args);
+  } catch (e) {
+    return fail({
+      code: "SCHEMA_INVALID",
+      message: "Invalid args schema.",
+      details: { cause: String(e?.message ?? e) }
+    });
+  }
+  if (opts.authorize) {
+    const allowed = await opts.authorize({
+      action: opts.action,
+      args,
+      commit: {
+        idempotency_key: verified.ctx.idempotency_key,
+        expires_at: verified.ctx.expires_at
+      }
+    });
+    if (!allowed) {
+      return fail({
+        code: "FORBIDDEN",
+        message: "Commit not allowed."
+      });
+    }
+  }
+  const key = verified.ctx.idempotency_key;
+  let begin;
+  try {
+    begin = await opts.store.begin(key);
+  } catch (e) {
+    return fail({
+      code: "IDEMPOTENCY_STORE_ERROR",
+      message: "Idempotency store begin failed.",
+      details: { cause: String(e?.message ?? e) }
+    });
+  }
+  if (begin.status === "COMPLETED") {
+    return { phase: "COMPLETED", result: begin.value };
+  }
+  if (begin.status === "IN_PROGRESS") {
+    return fail({
+      code: "IDEMPOTENCY_CONFLICT",
+      message: "Commit already in progress."
+    });
+  }
+  try {
+    const result = await opts.execute(args, {
+      action: opts.action,
+      idempotencyKey: key,
+      commitContext: verified.ctx
+    });
+    try {
+      await opts.store.complete(key, result);
+    } catch (e) {
+      return fail({
+        code: "IDEMPOTENCY_STORE_ERROR",
+        message: "Idempotency store complete failed.",
+        details: { cause: String(e?.message ?? e) }
+      });
+    }
+    return { phase: "COMPLETED", result };
+  } catch (e) {
+    const err = {
+      code: "EXECUTION_FAILED",
+      message: "Commit execution failed.",
+      details: { cause: String(e?.message ?? e) }
+    };
+    try {
+      await opts.store.fail?.(key, err);
+    } catch {
+    }
+    return fail(err);
+  }
+}
+
+// src/idempotency/memory-store.ts
+var MemoryIdempotencyStore = class {
+  map = /* @__PURE__ */ new Map();
+  async begin(key) {
+    const existing = this.map.get(key);
+    if (!existing) {
+      this.map.set(key, { status: "IN_PROGRESS" });
+      return { status: "NEW" };
+    }
+    if (existing.status === "COMPLETED") {
+      return { status: "COMPLETED", value: existing.value };
+    }
+    return { status: "IN_PROGRESS" };
+  }
+  async complete(key, value) {
+    this.map.set(key, { status: "COMPLETED", value });
+  }
+  async fail(key, error) {
+    this.map.set(key, { status: "FAILED", error });
+  }
+};
+
+// src/next/toolkit.ts
+function statusFromResponse(res) {
+  if (res.phase === "COMPLETED") return 200;
+  const code = res.error?.code;
+  if (!code) return 400;
+  switch (code) {
+    case "FORBIDDEN":
+      return 403;
+    case "SCHEMA_INVALID":
+    case "MALFORMED_COMMIT":
+    case "ACTION_MISMATCH":
+    case "EXPIRED_COMMIT":
+    case "INVALID_SIGNATURE":
+    case "IDEMPOTENCY_CONFLICT":
+      return 400;
+    case "IDEMPOTENCY_STORE_ERROR":
+    case "EXECUTION_FAILED":
+      return 500;
+    default:
+      return 400;
+  }
+}
+function createCommitGuardToolkit(config) {
+  const store = config.store ?? new MemoryIdempotencyStore();
+  return {
+    define: (def) => {
+      return async function POST(request) {
+        let body;
+        try {
+          body = await request.json();
+        } catch {
+          const res2 = {
+            phase: "FAILED",
+            error: { code: "MALFORMED_COMMIT", message: "Invalid JSON body." }
+          };
+          return globalThis.Response.json(res2, { status: 400 });
+        }
+        const signed = body?.commit;
+        const action = def.tool;
+        const res = await commit(
+          { action, commit: signed },
+          {
+            action,
+            secret: config.secret,
+            schema: def.schema,
+            store,
+            execute: def.execute,
+            nowMs: config.nowMs,
+            authorize: def.authorize ? async ({ action: action2, args }) => def.authorize({ tool: action2, args, request }) : void 0
+          }
+        );
+        return globalThis.Response.json(res, { status: statusFromResponse(res) });
+      };
+    }
+  };
+}
+function zodSchema(zodLike) {
+  return { parse: zodLike.parse };
+}
+
+// src/next/defineCommitGuardRoute.ts
+function defineCommitGuardRoute(handler) {
+  return handler;
+}
+
+export {
+  canonicalize,
+  canonicalJson,
+  signCommitContext,
+  validateCommitContextShape,
+  verifySignedCommitContext,
+  commit,
+  MemoryIdempotencyStore,
+  createCommitGuardToolkit,
+  zodSchema,
+  defineCommitGuardRoute,
+  next_exports
+};

package/dist/index-BjnJWUxR.d.ts

@@ -0,0 +1,230 @@
+type CommitGuardPhase = "COLLECTING" | "CONFIRMING" | "COMMIT_READY" | "COMPLETED" | "FAILED";
+/**
+ * Canonical action identifier.
+ * Examples:
+ * - "checkout.commit"
+ * - "wallet.withdraw.commit"
+ */
+type CommitGuardAction = string;
+/**
+ * A stable identifier for idempotent commit execution.
+ * Must be unique per logical side-effect.
+ */
+type IdempotencyKey = string;
+/** Unix epoch milliseconds */
+type EpochMs = number;
+/**
+ * Commit context envelope that crosses the commit boundary.
+ * This MUST remain minimal and stable.
+ */
+interface CommitContext<A extends CommitGuardAction = CommitGuardAction, Args = unknown> {
+    /** Protocol version for forward compatibility. */
+    v: 1;
+    /** Action being committed (tool name / command). */
+    action: A;
+    /** Arguments to execute. Must match schema at commit time. */
+    args: Args;
+    /** Idempotency key to guarantee execute-exactly-once semantics. */
+    idempotency_key: IdempotencyKey;
+    /** Expiration timestamp (epoch ms). Reject if now > expires_at. */
+    expires_at: EpochMs;
+    /**
+     * Optional nonce to add uniqueness to the signed payload if desired.
+     * Not required for correctness (idempotency_key covers execution semantics).
+     */
+    nonce?: string;
+    /**
+     * Optional metadata for audit/tracing.
+     * Must not affect deterministic execution.
+     */
+    meta?: {
+        trace_id?: string;
+        actor_id?: string;
+        tags?: Record<string, string>;
+    };
+}
+/**
+ * Signed commit context. Signature is computed over a canonical representation of `ctx`.
+ */
+interface SignedCommitContext<A extends CommitGuardAction = CommitGuardAction, Args = unknown> {
+    ctx: CommitContext<A, Args>;
+    sig: string;
+}
+/**
+ * Agent directive returned by Tx phase to instruct what to do next.
+ */
+type AgentDirective = ExecuteDirective | ConfirmDirective;
+/**
+ * Directive to execute a commit (Phase: COMMIT_READY).
+ */
+interface ExecuteDirective<A extends CommitGuardAction = CommitGuardAction, Args = unknown> {
+    type: "EXECUTE";
+    tool: A;
+    idempotency_key: IdempotencyKey;
+    args: Args;
+    /** The signed commit context the server expects for the commit call. */
+    commit: SignedCommitContext<A, Args>;
+}
+/**
+ * Directive to request explicit confirmation from the user/system.
+ * Useful if the host wants a confirm step in Tx (still no side effects).
+ */
+interface ConfirmDirective {
+    type: "CONFIRM";
+    message: string;
+    data?: Record<string, unknown>;
+}
+/**
+ * Structured Commit Guard response returned to the protocol caller.
+ */
+interface CommitGuardResponse<T = unknown> {
+    phase: CommitGuardPhase;
+    /** Present on COMMIT_READY to instruct the agent what to do next. */
+    agent_directive?: AgentDirective;
+    /** Present on COMPLETED. */
+    result?: T;
+    /** Present on FAILED. */
+    error?: CommitGuardError;
+    /** Optional non-contractual debug payload (avoid leaking secrets). */
+    debug?: Record<string, unknown>;
+}
+/**
+ * Stable error model for commit boundary failures.
+ * Keep codes stable. Messages may evolve.
+ */
+interface CommitGuardError {
+    code: CommitGuardErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type CommitGuardErrorCode = "INVALID_SIGNATURE" | "EXPIRED_COMMIT" | "MALFORMED_COMMIT" | "ACTION_MISMATCH" | "SCHEMA_INVALID" | "IDEMPOTENCY_CONFLICT" | "IDEMPOTENCY_STORE_ERROR" | "EXECUTION_FAILED" | "FORBIDDEN";
+/**
+ * Input to the Commit endpoint/handler.
+ */
+interface CommitRequest<A extends CommitGuardAction = CommitGuardAction, Args = unknown> {
+    action: A;
+    commit: SignedCommitContext<A, Args>;
+}
+/**
+ * Minimal schema abstraction to avoid framework coupling.
+ * Adapters may wrap Zod/Ajv/etc.
+ */
+interface Schema<Args = unknown> {
+    parse(input: unknown): Args;
+}
+/**
+ * Idempotency store contract.
+ * Production requires an implementation with atomic begin semantics (e.g., Redis).
+ */
+interface IdempotencyStore {
+    /**
+     * If key is new: atomically mark as IN_PROGRESS and return NEW.
+     * If already completed: return COMPLETED with stored value.
+     * If in progress: return IN_PROGRESS.
+     */
+    begin(key: IdempotencyKey): Promise<IdempotencyBegin>;
+    /** Persist final result for the given key. */
+    complete(key: IdempotencyKey, value: unknown): Promise<void>;
+    /** Optional: persist failure outcome for consistent retries. */
+    fail?(key: IdempotencyKey, error: CommitGuardError): Promise<void>;
+}
+type IdempotencyBegin = {
+    status: "NEW";
+} | {
+    status: "COMPLETED";
+    value: unknown;
+} | {
+    status: "IN_PROGRESS";
+};
+
+type CommitMeta<A extends CommitGuardAction> = {
+    action: A;
+    idempotencyKey: string;
+    commitContext: CommitContext<A, unknown>;
+};
+interface CommitGuardOptions<A extends CommitGuardAction, Args, Result> {
+    /** Expected action/tool name for this commit handler. */
+    action: A;
+    /** HMAC secret used to verify commit signature. */
+    secret: string;
+    /** Args schema validator/parser (throws on invalid). */
+    schema: Schema<Args>;
+    /** Idempotency store (Redis recommended for production). */
+    store: IdempotencyStore;
+    /**
+     * Deterministic side-effect execution.
+     * Must be idempotent with the provided idempotency_key.
+     */
+    execute: (args: Args, meta: CommitMeta<A>) => Promise<Result>;
+    /**
+     * Optional host policy hook (authz, allowlists, feature flags).
+     * Return false to reject with FORBIDDEN.
+     */
+    authorize?: (ctx: {
+        action: A;
+        args: Args;
+        commit: {
+            idempotency_key: string;
+            expires_at: number;
+        };
+    }) => Promise<boolean> | boolean;
+    /**
+     * Optional now provider for tests.
+     * Defaults to Date.now().
+     */
+    nowMs?: () => number;
+}
+declare function commit<A extends CommitGuardAction, Args, Result>(req: CommitRequest<A, unknown>, opts: CommitGuardOptions<A, Args, Result>): Promise<CommitGuardResponse<Result>>;
+
+type CommitGuardNextToolkitConfig = {
+    /**
+     * HMAC signing secret used to verify signed commit contexts.
+     * In Next: process.env.COMMIT_GUARD_SECRET
+     */
+    secret: string;
+    /**
+     * Idempotency store.
+     * Default: Memory store (dev/test only).
+     * Production: pass a Redis-backed IdempotencyStore (recommended).
+     */
+    store?: IdempotencyStore;
+    /**
+     * Optional now provider (tests).
+     */
+    nowMs?: () => number;
+};
+type DefineCommitGuardHandler<A extends CommitGuardAction, Args, Result> = {
+    tool: A;
+    schema: Schema<Args>;
+    execute: (args: Args, meta: CommitMeta<A>) => Promise<Result>;
+    authorize?: (ctx: {
+        tool: A;
+        args: Args;
+        request: globalThis.Request;
+    }) => Promise<boolean> | boolean;
+};
+declare function createCommitGuardToolkit(config: CommitGuardNextToolkitConfig): {
+    define: <A extends CommitGuardAction, Args, Result>(def: DefineCommitGuardHandler<A, Args, Result>) => (request: globalThis.Request) => Promise<globalThis.Response>;
+};
+declare function zodSchema<Args>(zodLike: {
+    parse: (input: unknown) => Args;
+}): Schema<Args>;
+
+/**
+ * Minimal helper for Next.js App Router exports.
+ *
+ * Keeps the integration surface extremely small
+ * and avoids turning the protocol into a framework.
+ */
+declare function defineCommitGuardRoute(handler: (request: Request) => Promise<Response>): (request: Request) => Promise<Response>;
+
+type index_CommitGuardNextToolkitConfig = CommitGuardNextToolkitConfig;
+type index_DefineCommitGuardHandler<A extends CommitGuardAction, Args, Result> = DefineCommitGuardHandler<A, Args, Result>;
+declare const index_createCommitGuardToolkit: typeof createCommitGuardToolkit;
+declare const index_defineCommitGuardRoute: typeof defineCommitGuardRoute;
+declare const index_zodSchema: typeof zodSchema;
+declare namespace index {
+  export { type index_CommitGuardNextToolkitConfig as CommitGuardNextToolkitConfig, type index_DefineCommitGuardHandler as DefineCommitGuardHandler, index_createCommitGuardToolkit as createCommitGuardToolkit, index_defineCommitGuardRoute as defineCommitGuardRoute, index_zodSchema as zodSchema };
+}
+
+export { type AgentDirective as A, type CommitGuardAction as C, type DefineCommitGuardHandler as D, type EpochMs as E, type IdempotencyStore as I, type SignedCommitContext as S, type CommitContext as a, type CommitGuardError as b, type IdempotencyKey as c, type IdempotencyBegin as d, type CommitMeta as e, type Schema as f, type CommitGuardResponse as g, type CommitGuardErrorCode as h, type CommitGuardOptions as i, type CommitGuardPhase as j, type CommitRequest as k, type ConfirmDirective as l, type ExecuteDirective as m, commit as n, index as o, type CommitGuardNextToolkitConfig as p, createCommitGuardToolkit as q, defineCommitGuardRoute as r, zodSchema as z };

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import { C as CommitGuardAction, a as CommitContext, S as SignedCommitContext, b as CommitGuardError, I as IdempotencyStore, c as IdempotencyKey, d as IdempotencyBegin, e as CommitMeta, f as Schema, g as CommitGuardResponse } from './index-BjnJWUxR.js';
+export { A as AgentDirective, h as CommitGuardErrorCode, i as CommitGuardOptions, j as CommitGuardPhase, k as CommitRequest, l as ConfirmDirective, E as EpochMs, m as ExecuteDirective, n as commit, o as next } from './index-BjnJWUxR.js';
+
+/**
+ * Canonical JSON: stable key ordering + recursive canonicalization.
+ * - Removes undefined fields
+ * - Sorts object keys
+ * - Keeps array order
+ *
+ * NOTE: This is the main CPU cost in sign/verify.
+ * Keep commit_context reasonably small (args + meta).
+ */
+declare function canonicalize(value: unknown): unknown;
+declare function canonicalJson(value: unknown): string;
+declare function signCommitContext<A extends CommitGuardAction, Args = unknown>(secret: string, ctx: CommitContext<A, Args>): SignedCommitContext<A, Args>;
+declare function validateCommitContextShape(ctx: any): ctx is CommitContext<CommitGuardAction, unknown>;
+/**
+ * Verify signature + expiration + action match.
+ *
+ * IMPORTANT:
+ * - Returns args as unknown (typed parsing happens later via schema.parse()).
+ * - Node-first implementation (uses node:crypto).
+ */
+declare function verifySignedCommitContext<A extends CommitGuardAction>(params: {
+    secret: string;
+    signed: SignedCommitContext<A, unknown>;
+    expectedAction: A;
+    nowMs?: number;
+}): {
+    ok: true;
+    ctx: CommitContext<A, unknown>;
+} | {
+    ok: false;
+    error: CommitGuardError;
+};
+
+declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private readonly map;
+    begin(key: IdempotencyKey): Promise<IdempotencyBegin>;
+    complete(key: IdempotencyKey, value: unknown): Promise<void>;
+    fail(key: IdempotencyKey, error: CommitGuardError): Promise<void>;
+}
+
+/**
+ * Minimal Redis client shape needed by this store.
+ * This avoids a hard dependency on the "redis" package (even for .d.ts build).
+ *
+ * Compatible with node-redis v4+ client:
+ * - client.get(key)
+ * - client.set(key, value, { NX/XX, EX })
+ */
+type RedisLikeClient = {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, opts?: {
+        NX?: boolean;
+        XX?: boolean;
+        EX?: number;
+    }): Promise<"OK" | null>;
+};
+type RedisIdempotencyStoreOptions = {
+    /**
+     * Prefix for keys stored in Redis.
+     * Default: "cgp:idemp:"
+     */
+    prefix?: string;
+    /**
+     * TTL in seconds for completed results.
+     * Keep it reasonably long to serve duplicate commits safely.
+     * Default: 24h
+     */
+    ttlSeconds?: number;
+    /**
+     * TTL in seconds for in-progress locks.
+     * Should be short to avoid dead locks.
+     * Default: 60s
+     */
+    inProgressTtlSeconds?: number;
+};
+declare class RedisIdempotencyStore implements IdempotencyStore {
+    private readonly client;
+    private readonly prefix;
+    private readonly ttlSeconds;
+    private readonly inProgressTtlSeconds;
+    constructor(client: RedisLikeClient, opts?: RedisIdempotencyStoreOptions);
+    begin(key: IdempotencyKey): Promise<IdempotencyBegin>;
+    complete(key: IdempotencyKey, value: unknown): Promise<void>;
+    fail(key: IdempotencyKey, error: CommitGuardError): Promise<void>;
+}
+
+type TxOptions = {
+    secret: string;
+    expiresInMs?: number;
+    nowMs?: () => number;
+};
+/**
+ * Tx service contract:
+ * - returns COMMIT_READY with signed commit payload
+ * - MUST NOT execute side effects
+ */
+interface TxService<TxInput> {
+    tx(input: TxInput, opts: TxOptions): Promise<CommitGuardResponse>;
+}
+/**
+ * Commit executor contract:
+ * - executes irreversible side effects deterministically
+ * - must be idempotent w.r.t meta.idempotencyKey
+ */
+interface CommitExecutor<A extends CommitGuardAction, Args, Result> {
+    execute(args: Args, meta: CommitMeta<A>): Promise<Result>;
+}
+/**
+ * Optional convenience type for adapters.
+ */
+type CommitHandlerDefinition<A extends CommitGuardAction, Args, Result> = {
+    tool: A;
+    schema: Schema<Args>;
+    executor: CommitExecutor<A, Args, Result>;
+};
+
+type TxReadyInput<A extends CommitGuardAction, Args> = {
+    action: A;
+    args: Args;
+    secret: string;
+    idempotencyKey?: IdempotencyKey;
+    expiresInMs?: number;
+    nowMs?: number;
+    meta?: CommitContext["meta"];
+    nonce?: string;
+};
+/**
+ * Builds a COMMIT_READY response containing a signed commit payload.
+ * No side effects are performed here.
+ */
+declare function txReady<A extends CommitGuardAction, Args>(input: TxReadyInput<A, Args>): CommitGuardResponse;
+
+declare function defineCommitExecutor<A extends CommitGuardAction, Args, Result>(def: {
+    tool: A;
+    schema: Schema<Args>;
+    executor: CommitExecutor<A, Args, Result>;
+}): {
+    tool: A;
+    schema: Schema<Args>;
+    execute: (args: Args, meta: CommitMeta<A>) => Promise<Result>;
+};
+
+export { CommitContext, type CommitExecutor, CommitGuardAction, CommitGuardError, CommitGuardResponse, type CommitHandlerDefinition, CommitMeta, IdempotencyBegin, IdempotencyKey, IdempotencyStore, MemoryIdempotencyStore, RedisIdempotencyStore, type RedisIdempotencyStoreOptions, type RedisLikeClient, Schema, SignedCommitContext, type TxOptions, type TxReadyInput, type TxService, canonicalJson, canonicalize, defineCommitExecutor, signCommitContext, txReady, validateCommitContextShape, verifySignedCommitContext };

package/dist/index.js

@@ -0,0 +1,120 @@
+import {
+  MemoryIdempotencyStore,
+  canonicalJson,
+  canonicalize,
+  commit,
+  next_exports,
+  signCommitContext,
+  validateCommitContextShape,
+  verifySignedCommitContext
+} from "./chunk-WLDMTPVD.js";
+
+// src/idempotency/redis-store.ts
+function keyFor(prefix, key) {
+  return `${prefix}${key}`;
+}
+var RedisIdempotencyStore = class {
+  constructor(client, opts = {}) {
+    this.client = client;
+    this.prefix = opts.prefix ?? "cgp:idemp:";
+    this.ttlSeconds = opts.ttlSeconds ?? 60 * 60 * 24;
+    this.inProgressTtlSeconds = opts.inProgressTtlSeconds ?? 60;
+  }
+  prefix;
+  ttlSeconds;
+  inProgressTtlSeconds;
+  async begin(key) {
+    const redisKey = keyFor(this.prefix, key);
+    const existing = await this.client.get(redisKey);
+    if (existing) {
+      const parsed2 = JSON.parse(existing);
+      if (parsed2.status === "COMPLETED") {
+        return { status: "COMPLETED", value: parsed2.value };
+      }
+      return { status: "IN_PROGRESS" };
+    }
+    const lockValue = { status: "IN_PROGRESS" };
+    const setOk = await this.client.set(redisKey, JSON.stringify(lockValue), {
+      NX: true,
+      EX: this.inProgressTtlSeconds
+    });
+    if (setOk === "OK") return { status: "NEW" };
+    const after = await this.client.get(redisKey);
+    if (!after) return { status: "IN_PROGRESS" };
+    const parsed = JSON.parse(after);
+    if (parsed.status === "COMPLETED") {
+      return { status: "COMPLETED", value: parsed.value };
+    }
+    return { status: "IN_PROGRESS" };
+  }
+  async complete(key, value) {
+    const redisKey = keyFor(this.prefix, key);
+    const payload = { status: "COMPLETED", value };
+    await this.client.set(redisKey, JSON.stringify(payload), {
+      XX: true,
+      // only if key exists (must have been begin()'d)
+      EX: this.ttlSeconds
+    });
+  }
+  async fail(key, error) {
+    const redisKey = keyFor(this.prefix, key);
+    const payload = { status: "FAILED", error };
+    await this.client.set(redisKey, JSON.stringify(payload), {
+      XX: true,
+      EX: this.ttlSeconds
+    });
+  }
+};
+
+// src/helpers/txReady.ts
+import { randomUUID } from "crypto";
+function txReady(input) {
+  const now = input.nowMs ?? Date.now();
+  const expiresInMs = input.expiresInMs ?? 6e4;
+  const idempotencyKey = input.idempotencyKey ?? randomUUID();
+  const ctx = {
+    v: 1,
+    action: input.action,
+    args: input.args,
+    idempotency_key: idempotencyKey,
+    expires_at: now + expiresInMs,
+    meta: input.meta,
+    nonce: input.nonce
+  };
+  const signed = signCommitContext(input.secret, ctx);
+  const directive = {
+    type: "EXECUTE",
+    tool: input.action,
+    idempotency_key: idempotencyKey,
+    args: input.args,
+    commit: signed
+  };
+  return {
+    phase: "COMMIT_READY",
+    agent_directive: directive
+  };
+}
+
+// src/helpers/defineCommitExecutor.ts
+function defineCommitExecutor(def) {
+  return {
+    tool: def.tool,
+    schema: def.schema,
+    execute: async (args, meta) => {
+      return def.executor.execute(args, meta);
+    }
+  };
+}
+export {
+  MemoryIdempotencyStore,
+  RedisIdempotencyStore,
+  canonicalJson,
+  canonicalize,
+  commit,
+  defineCommitExecutor,
+  next_exports as next,
+  signCommitContext,
+  txReady,
+  validateCommitContextShape,
+  verifySignedCommitContext
+};

package/dist/next/index.d.ts

@@ -0,0 +1 @@
+export { p as CommitGuardNextToolkitConfig, D as DefineCommitGuardHandler, q as createCommitGuardToolkit, r as defineCommitGuardRoute, z as zodSchema } from '../index-BjnJWUxR.js';

package/dist/next/index.js

@@ -0,0 +1,10 @@
+import {
+  createCommitGuardToolkit,
+  defineCommitGuardRoute,
+  zodSchema
+} from "../chunk-WLDMTPVD.js";
+export {
+  createCommitGuardToolkit,
+  defineCommitGuardRoute,
+  zodSchema
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "commit-guard-protocol",
+  "version": "0.1.0",
+  "description": "Commit Guard Protocol - a minimal deterministic commit boundary for irreversible actions.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./next": {
+      "import": "./dist/next/index.js",
+      "types": "./dist/next/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/next/index.ts --format esm --dts --clean",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "agents",
+    "llm",
+    "commit",
+    "idempotency",
+    "protocol",
+    "hmac",
+    "deterministic",
+    "nextjs",
+    "production-safety"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "tsup": "^8.0.0"
+  },
+  "peerDependencies": {
+    "redis": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "redis": {
+      "optional": true
+    }
+  }
+}