Request-Bound HMAC Assertions with SQLite Replay Store

    1

    A static bearer token between two of your services proves only that the caller once knew a secret; whoever copies it can send any request anywhere until you rotate it.

    $39

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Request-Bound HMAC Assertions with SQLite Replay Store

    Example session with this skill installed

    Show me how to set up the SQLite replay store and verify an incoming request assertion against a specific tenant and purpose.

    • Read your context and instructions
    • Compiled the request-bound hmac assertions

    The following implementation initializes the atomic replay store and verifies a request bound to a specific tenant and purpose.

    Service Verification Logic

    import { createSqliteReplayStore } from './scripts/sqlite-replay-store.mjs';
    import { createAssertionProfile, verifyAssertion } from './scripts/assertion.mjs';
    
    // 1. Initialize the host-wide replay store
    const replayCache = createSqliteReplayStore({ 
      filename: '/var/lib/my-service/replay-store.db' 
    });
    
    // 2. Define the service profile
    const profile = createAssertionProfile({
      purposes: ['process-payment', 'refund-order'],
      methods: ['POST'],
      maxTtlMs: 60000 // 60 second expiry
    });
    
    async function handleRequest(req, bodyBytes) {
      const header = req.headers['x-request-assertion'];
      const sharedKey = process.env.CLIENT_SECRET; // Load from secure source
    
      try {
        // 3. Verify assertion against expected scope
        const claims = await verifyAssertion(profile, header, {
          key: sharedKey,
          body: bodyBytes,
          replayCache,
          expected: {
            appId: 'payment-gateway',
            tenantId: 'tenant-1234',
            purpose: 'process-payment',
            method: 'POST',
            path: '/v1/charge'
          }
        });
    
        // Success: assertions are frozen and verified
        return { status: 200, data: { subject: claims.subjectBinding } };
      } catch (err) {
        // 4. Map internal error codes to HTTP responses
        // err.code will be REPLAYED_ASSERTION, ASSERTION_SCOPE_MISMATCH, etc.
        const status = err.status || 500;
        console.error(`Auth failed: ${err.code}`);
        return { status, error: err.code };
      }
    }
    

    Next steps

    • Run node --test scripts/assertion.test.mjs to verify the BEGIN IMMEDIATE locking works on your filesystem.
    • Ensure the state directory has 0700 permissions and the key file is restricted to the service user.
    • Review reference/design.md for the full list of AssertionError codes to implement detailed logging.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    A static bearer token between two of your services proves only that the caller once knew a secret; whoever copies it can send any request anywhere until you rotate it. This kit replaces it with a per-request proof and a host-wide one-use guarantee.

    Assertions (assertion.mjs): the caller signs exactly this client, app, tenant, subject binding, purpose, HTTP method, path and SHA-256 of the body, plus issue time, an expiry of at most 60 seconds and a 24-byte nonce. The payload must equal its own canonical re-serialization, so a claim set has exactly one encoding. The verifier checks the HMAC with a constant-time compare, every scope claim against the handler's own scope, the hash of the bytes it actually received, and the time window, and only then consumes the nonce. A forged or mis-scoped token never burns a legitimate nonce. Profiles fix the purposes, methods, path shape and lifetime per service.

    Replay store (sqlite-replay-store.mjs, node:sqlite): consumption is one BEGIN IMMEDIATE transaction (sweep expired, check, insert), WAL with synchronous=FULL, so two processes racing one token get exactly one success and a consumed nonce survives a crash. Only digests reach the disk. Any store fault raises REPLAY_STORE_UNAVAILABLE (503) instead of silently falling back to memory. Also consumes JWT ids and webhook event ids.

    10 tests including a real two-process race, a corrupt-database refusal and an end-to-end verification through the store; a loopback demo (demo.mjs) that shows one accept and three refusals; reference/design.md with the threat model, error codes and a deployment checklist (LoadCredential, state directory, rotation).

    Node 22.5+, no packages, no network.

    Requires Node 22.5+. Replay protection is limited to a single host via shared SQLite file. Symmetric keys mean both sides can sign; requires one key per client to isolate.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Money-back guarantee

    Doesn't do what its page promises? You get your money back.

    Trust & safety

    Security scan

    Security scan passed 17 days ago

    Requires

    Node.js 22.5+

    Permissions

    Network Access
    Read Files
    Write Files
    Listed17 days ago

    What's inside

    Frequently Asked Questions

    Unlike standard API keys, this skill binds the HMAC signature to the specific HTTP method, path, and request body. This ensures that even if a token is intercepted, it cannot be reused for a different endpoint or modified to change the request payload.

    The skill is built for Node.js 22.5+ using native modules (`node:sqlite` and `node:crypto`). It is compatible with any AI agent or backend framework running on modern Node.js environments that support filesystem access for the SQLite replay store.

    The SQLite-backed replay store uses `BEGIN IMMEDIATE` locking and `WAL` mode to ensure nonces are consumed 'exactly once' even across multiple processes on the same host, effectively preventing replay attacks even if a process crashes.

    You will receive the full skill logic including the profile initialization, signing, and verification modules, along with documentation on integrating the `x-request-assertion` header into your existing service-to-service workflows.

    The replay store is designed for single-host environments (including multi-process setups). For multi-host clusters, the replay store would need a shared filesystem, as the current implementation relies on local SQLite persistence for its atomicity guarantees.

    Setup is straightforward: you initialize your assertion profiles, provide a 32-character shared key, and point the verifier to a local SQLite database path. The skill handles the database schema creation and maintenance automatically.

    New in APIs & Backend