aits

Record and verify execution lineage against a local or hosted AITS ledger.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0
Author: Bastion One

Available Nodes

Documentation generating…

Documentation

AITS for n8n

Record an execution trace in an AITS ledger and verify the resulting content
identifier (CID) from an n8n workflow. The AITS API credential selects the
ledger. Use the same node with a local or hosted AITS server.

Install

On self-hosted n8n, open Settings → Community Nodes → Install and enter
n8n-nodes-aits after the package is published. For a local development build,
run npm ci, npm run build, and npm pack from this checkout. Transfer the
tarball to the n8n host or container. From the nodes directory inside your n8n
user folder, install the tarball with npm install --offline --legacy-peer-deps /path/to/n8n-nodes-aits-0.1.0.tgz, then restart n8n. Create the nodes directory
if this is your first manual install. In Docker, use the persistent n8n user
volume.

The compatibility baseline is n8n 2.47.5 and AITS 0.3.0. n8n Cloud availability
requires approval through the n8n Creator Portal.

Credentials

Create an AITS API credential and enter:

  • Server URL — the HTTP or HTTPS base URL as seen from the n8n runtime.
  • Service Key — the bearer key issued by that AITS server. With a
    self-hosted server, use the secret portion of its AUTH_SERVICE_KEYS entry.
Where AITS runs Server URL example
Same Compose network as n8n, on a service named aits http://aits:8000
On the same machine as a non-containerized n8n process http://127.0.0.1:8000
On the host of an n8n Docker Desktop container http://host.docker.internal:8000
On a hosted server reachable by n8n https://aits.example.com

Keep AITS authentication enabled in both setups. Save one credential per
destination and select it in the node. On self-hosted n8n with SSRF protection
enabled, the administrator may need to allowlist the local AITS service.

Try the example

  1. Start the local stack below, or use an existing AITS API endpoint.
  2. Import offline-record-and-verify.json
    into n8n.
  3. Select the same AITS API credential in Record Execution and
    Verify Record.
  4. Run the workflow. The example creates a synthetic trace, writes it to AITS,
    and verifies the resulting lineage CID. A recording error goes to Review
    Recording Warning
    .

For offline use, have the n8n, AITS, and PostgreSQL images and the packaged
node available before disconnecting. The example runs against the local ledger
without any model provider. A workflow that generates a live trace offline
also needs a local model or another local source for its trace.

Start a local stack

  1. While online, build or obtain the AITS server image from the
    AITS server repository and tag it
    aits-server:0.3.0. Preload postgres:16-alpine and
    n8nio/n8n:2.47.5, and build or obtain the node tarball. Set
    AITS_IMAGE or N8N_IMAGE if your local image tags differ.

  2. Set AITS_SERVICE_KEY to a generated secret in the shell or in an
    untracked .env at the package root. Start the stack with
    docker compose -f examples/compose.yaml up -d. Compose uses the local
    images and binds the editor to localhost:5680.

  3. Install the tarball in the n8n container's persistent user folder:

    docker compose -f examples/compose.yaml cp n8n-nodes-aits-0.1.0.tgz n8n:/tmp/aits-node.tgz
    docker compose -f examples/compose.yaml exec n8n sh -c 'mkdir -p "$HOME/.n8n/nodes" && cd "$HOME/.n8n/nodes" && npm install --offline --legacy-peer-deps /tmp/aits-node.tgz'
    docker compose -f examples/compose.yaml restart n8n
    
  4. In the editor, create an AITS API credential with Server URL
    http://aits:8000 and the same service key. Import the fixture workflow.
    The stack keeps AITS records and n8n settings in named Docker volumes.

Operations

Record Execution

Supply the trace using Execution Trace, which defaults to the incoming
item's trace field. Every trace has a root event and an ordered steps
array. Each event needs actor_id, step_id, transformation, and
occurred_at. Use an ISO 8601 timestamp with an explicit timezone. Each
step follows the previous step, starting from the root.

For a model call, add a dut object to the step with agent_uuid,
config_cid, span_id, input_context, and agent_output. Optionally
include a list of business_object_keys. Register the agent and its
configuration on the destination AITS server first. Supplying the config CID
explicitly pins the model call to that configuration when the trace is replayed.

The node adds aits to the original item. On success, it contains
status: "recorded", rootCid, lineageCid, stepCids, and dutCids.
lineageCid identifies the last step, or the root for a trace with no steps.
Turn on Verify After Recording to set aits.verified: true before
reporting the trace as recorded. An invalid verdict returns an integrity
failure. The written CID remains available for investigation.

By default, Recording Failure → Continue With Warning keeps the item
flowing and sets status: "error", stage, warning, code, and
retryable in aits. HTTP failures also include httpStatus. Branch on
aits.status to alert or send work for recovery. Transport failures,
rate limits, and server failures are marked retryable. Configuration, input,
and authentication errors need attention. Fail the Node sends the failure
through n8n's On Error setting. Use Stop Workflow there if recording
must succeed before downstream work starts.

Any CIDs confirmed before the failure are still available in warning mode.
An identical trace with the same timestamps, agent,
and config can be replayed against the same server. AITS returns the same
record CIDs and appends new observations to its commit log. Changing a
timestamp or any other content can create a new CID.

Verify Record

Enter a 64-character hexadecimal CID or map it from another node. The
response supplies aits.cid, aits.valid, aits.propertyViolated, and
aits.message. An invalid verdict is returned as data. Require
aits.valid === true before proceeding if verification is a gate. A request failure,
such as an unknown CID or an unreachable endpoint, follows n8n's node error
settings. Use the ledger that holds the record you want to verify.

Durable delivery for audit workflows

For flows that must account for each trace, enqueue it before acknowledging
the source event. Use a durable PostgreSQL instance and install
production-outbox.sql once. Use a separate
outbox database for each destination ledger, grant only the database access
needed by the workflows, and monitor and back up the database.

In the producer workflow, use a PostgreSQL Execute Query node with bound
parameters. Provide a stable, unique delivery key and a redacted, fully mapped
trace. Keep the original timestamps, agent ID, and config CID on replay.

SELECT aits_delivery.enqueue($1::text, $2::jsonb) AS state;

For an incoming item with deliveryKey and trace, use
={{ [$json.deliveryKey, JSON.stringify($json.trace)] }} as Query Parameters.
Reusing the same key with the same trace returns its existing state. A
different trace under an existing key raises an error. If the business change
and outbox use the same PostgreSQL database, enqueue in the business
transaction. For an external side effect, reconcile by source event ID if a
crash could occur between that side effect and the enqueue.

Import production-worker.json, select the
outbox PostgreSQL credential for both database nodes, and select the destination
ledger's AITS API credential. Run it manually first. Once activated, the
example claims one delivery per minute. Add an n8n error workflow to notify
operators when delivery requires attention.

The worker marks a trace delivered only after AITS verifies the final CID.
Transient failures retry with backoff, and crashed workers release their claim
when the five-minute lease expires. A stale worker's acknowledgement cannot
finish a newer claim. After eight attempts or a permanent error, the trace
stays in the outbox as dead for investigation. Monitor dead rows and overdue
deliveries independently of workflow alerts, especially for workers that exit
before reporting a result. Recovery is at least once. A retried trace can add
commit-log observations even when it returns the same CIDs. Set retention for
delivered rows according to your audit policy.

Load and time limits

The node sends one request at a time per execution. Each trace needs one root
write and one write per step, plus a read when Verify After Recording is
enabled. Limit concurrent executions separately in n8n, and benchmark against
the target AITS instance with representative traces.

Options exposes a 10-second request timeout and a 60-second budget shared
by all items and requests in the node run. The maximum budget is 240 seconds.
When it runs out, warning mode returns execution_budget_exceeded for
unfinished and skipped items. Treat an interrupted write as potentially
committed and replay the original trace and timestamps. The durable worker's
five-minute lease leaves time to acknowledge after the node's request budget.

The default limit is 200 steps per trace and can be raised to 1,000. Trace JSON
is capped at 4 MiB and buffered responses at 8 MiB. Oversize traces fail before
the root write. Split workloads at meaningful trace boundaries.

Data sent to AITS

The node sends the mapped event fields and the optional model-call fields to
the selected endpoint. Options → Model Text can send the supplied model
input and output, replace them with an omission marker, or store a
sha256: digest of each. AITS verifies the record containing the digest.
Model Text only applies to those two fields. Review labels, step IDs, and
business object keys for sensitive data as well.

Result Only strips the source JSON and binary data from this node's output.
Upstream nodes, n8n execution history, and the durable outbox may still retain
their inputs. Redact before enqueueing or before the data enters n8n if those
copies are out of scope for retention. If the producer already sends digests,
leave the worker's Model Text on As Provided to keep the original trace
stable across attempts. Keep Result Only off in the durable worker so it
can pass the delivery key and lease token to PostgreSQL.

Development and release

Run npm ci, npm run lint, npm test, and npm pack --dry-run before
cutting a release. Use npm run dev to open the node in a local editor.
To check outbox recovery on an empty disposable PostgreSQL database, run
psql -X -v ON_ERROR_STOP=1 -f examples/production-outbox.sql -f test/outbox.test.sql.

Configure npm Trusted Publishing for the public Bastion One repository and
publish.yml. The workflow publishes a version-matched tag such as
v0.1.0 with npm provenance. For a first release that requires a token,
use the repository's NPM_TOKEN Actions secret. Once the package is on npm,
scan the published version, install it on clean self-hosted n8n, and submit
it through the n8n Creator Portal.

MIT © Bastion One

Discussion