Repository navigation
Releases
v0.8.3 (experimental)
Interceptor servers can offer sinks. Unchanged from 0.8.3-rc.1.
Upgrading
- No config changes are needed. Sinks only run when an interceptor server in
gateway.interceptorServersoffers one. InterceptorInvokertakes an optional fifth argument,onSinkError. The gateway logs sink failures with it.
@adtl/gateway
- Sinks (#53, following the proposal in experimental-ext-interceptors#28): interceptors with
type: "sink"now run instead of being skipped with a warning. They are dispatched in parallel once validation has passed (sending: mutate, validate, then sinks; receiving: validate, sinks, then mutate) and never awaited, each with its own copy of the payload. A sink that fails or times out is logged and never blocks, whatever itsfailOpen, and the gateway's audit mode doesn't apply to sinks. Startup stops on a sink declared withmode: "audit"or given it by an override, as the proposal requires. Audit entries mark sinks withsink: true. Closing the gateway waits for dispatched sinks to settle. invalidSinks()andInterceptorInvoker.sinksSettled()are exported.unsupportedInterceptors()no longer lists sinks.
@adtl/interceptors
InterceptorDefinition.typeaccepts"sink", andSinkResult(recorded: boolean) joinsInterceptorResult.
Security
- Updated the transitive
hono(4.13.18) and@hono/node-server(2.1.8), pulled in by@modelcontextprotocol/sdk, for published advisories.npm auditis clean, including dev dependencies.
v0.8.3-rc.1 (experimental)
A release candidate for testing: interceptor servers can offer sinks.
Upgrading
- No config changes are needed. Sinks only run when an interceptor server in
gateway.interceptorServersoffers one. InterceptorInvokertakes an optional fifth argument,onSinkError. The gateway logs sink failures with it.
@adtl/gateway
- Sinks (#53, following the proposal in experimental-ext-interceptors#28): interceptors with
type: "sink"now run instead of being skipped with a warning. They are dispatched in parallel once validation has passed (sending: mutate, validate, then sinks; receiving: validate, sinks, then mutate) and never awaited, each with its own copy of the payload. A sink that fails or times out is logged and never blocks, whatever itsfailOpen, and the gateway's audit mode doesn't apply to sinks. Startup stops on a sink declared withmode: "audit"or given it by an override, as the proposal requires. Audit entries mark sinks withsink: true. Closing the gateway waits for dispatched sinks to settle. invalidSinks()andInterceptorInvoker.sinksSettled()are exported.unsupportedInterceptors()no longer lists sinks.
@adtl/interceptors
InterceptorDefinition.typeaccepts"sink", andSinkResult(recorded: boolean) joinsInterceptorResult.
Security
- Updated the transitive
hono(4.13.18) and@hono/node-server(2.1.8), pulled in by@modelcontextprotocol/sdk, for published advisories.npm auditis clean, including dev dependencies.
v0.8.2 (experimental)
Ask when a call copies a private value. Session labels can't tell a leaking write from a normal one, because nearly every session is already private; copied values can.
Upgrading
- No config changes are needed.
call.copiesPrivateonly applies to rules that use it. - Session directories gain a
<session>.valuesfile next to each label file: hashes of secret-like values the session read from private sources, never the values. SessionStorehas two new optional methods,rememberPrivateValuesandhasPrivateValue. A custom store without them still works, but rules usingcall.copiesPrivatethen match every call (they fail closed).
@adtl/labels
call.copiesPrivatepolicy condition (#56): matches a call whose arguments hold a secret-like value the session read from aprivateorsecretresult. Secret-like means 16 or more letters, digits,_,-or+in a row, with both letters and digits, not plain hex (git commit ids, hashes, UUIDs) and not a folder name in a path. Only verbatim copies match.secretFingerprints,secretLikeTokens,isSecretLikeandusesCopiesPrivate.InMemorySessionStoreandFileSessionStorekeep the fingerprints.- A
data-class.v1evidenceRefis read through itssensitiveclaim; the record itself is ignored until the scheme says where it lives (#54).
@adtl/interceptors and @adtl/gateway
adtl.labelremembers secret-like values from private results;adtl.policychecks each call's arguments against them. The Claude Code hooks do the same, and check a sub-agent's values with its parent's.
Evaluation
- The MCPHunt replay (
examples/mcphunt-eval) now runs the real condition: with the example policy it stops 78.0% of leaks while interrupting 12.7% of clean runs (0.3 asks per clean run). The 0.8.1 prototype stopped 79.2% and interrupted 44.7%; asking before every write stops 95.2% and interrupts 95.7%.browser_to_localleaks are still mostly missed, because web pages are labeledpublic.
Security
- Updated the test tooling with published advisories:
vitest5.1.0 (from 2.1.9, which pulled in vulnerablevite,esbuild,tinypooland@vitest/mocker), now withvite8.3.7 as an explicit dev dependency, and@types/node22.20.5. Dev-only; the published packages don't change.npm auditis clean, including dev dependencies.
v0.8.1 (experimental)
Authenticator-app approvals and OpenFGA authorization, a first outside measurement of what ADTL does and doesn't catch, and fixes for gaps left in 0.8.0.
Security
- Updated dependencies with published advisories:
@modelcontextprotocol/sdk1.32.2,nodemailer10.3.1,zod4.6.7 (a major version), and the transitivebody-parser,fast-uriandqs.npm audit --omit=devis clean.
Upgrading
- No config changes are needed.
gateway.approvals.totpandgateway.openfgaonly apply when you set them. - Config error messages come from zod 4, so their wording changed.
evidenceRefon labeled results now carriesschema.
@adtl/gateway
- Authenticator-app approvals (#25):
gateway.approvals.totp: trueasks for a 6-digit code in the MCP client instead of Allow or Deny, so a client that accepts prompts by itself can't approve anything.adtl-gateway totp setupshows a QR code and stores the secret in the macOS Keychain, or elsewhere in a private file (ADTL_TOTP_FILE). A code works once, within one 30-second step either way, even across restarts.adtl-gateway totp check <code>tests a code. The hooks protect the secret. New dependency:qrcode-terminal. - OpenFGA (#12):
gateway.openfgachecks each call against OpenFGA's HTTP API, with per-tool objects built from the call's arguments (object: "repo:{owner}/{repo}"). Errors and timeouts deny. Works alongsiderolesandcedar; every one must allow. - The playground applies
gateway.interceptorOverridesfrom your config, and refuses bad ones. It still ignoresinterceptorServers, so a web page can't start commands. - Interceptors of a type the gateway doesn't run (such as the proposed
sink) are named in a startup warning instead of being skipped silently.
@adtl/labels
evidenceRef.schemanow names the publishedadtl.label.v1JSON Schema.
Docs
SPEC.mdupdated for the above.docs/interceptor-state-proposal.md(#22): the case for interceptor state across calls, a draft for the Interceptors WG.
Examples
examples/mcphunt-eval(#37): replays MCPHunt's 3,615 recorded runs through ADTL's labels and policy. The example policy would have stopped 0.6% of policy-violating leaks, which are mostly copies into local files. Asking on every write stops 95.2% and interrupts 95.7% of clean runs. Follow-up: #56.
v0.8.0 (experimental)
Labels follow data across more hops: into sub-agents, over A2A, and to and from FIDES / fides-gateway. The gateway catches up with the latest SEP-2624 and Tool Annotations IG drafts: per-interceptor overrides, interceptors from several servers, and tools that describe themselves with action-metadata.
Upgrading
- No config changes are needed. Everything new is opt-in, with two exceptions that only make things stricter: a tool whose action-metadata says
requiresReview: truenow getsaskwhen no rule blocks it (policy.honorRequiresReview: falseturns that off), and fides-gateway labels on results are now read as server claims. - Claude Code: add a
SubagentStarthook runningadtl-gateway hook, as in the README, so sub-agents are linked to their parent's session. - Audit entries for interceptor runs have a new
timeoutMsfield.
@adtl/gateway
- Per-interceptor overrides (#50):
gateway.interceptorOverrides.<name>setsfailOpen,priorityHint,mode,timeoutMsandhooksfor one interceptor, as SEP-2624's Invoker Overrides describe. Hooks can only be narrowed; an override that widens them, or names an interceptor the server doesn't offer, stops startup.gateway.mode: auditstill wins over a per-interceptormode, and overrides that relaxadtl.policyoradtl.labellog a warning. - The audit log's
interceptorsentries now carrytimeoutMs, andmodeFrom/failOpenFromsayoverridewhen an override applies. - The invoker enforces each interceptor's timeout itself, so an interceptor client that ignores the timeout can no longer hang a call.
checkOverrides(),resolvePriority()and theInterceptorOverridestype are exported.- The gateway passes a request's
_metaon to the upstream when a mutator sets it (used for fides-gateway labels). - More interceptor servers (#51):
gateway.interceptorServers.<id>adds stdio or Streamable HTTP interceptor servers whose interceptors run beside ADTL's, each invoked on the server that advertised it. They don't get ADTL's per-callconfig. Startup stops on an unreachable server, a missing extension capability or a duplicate interceptor name, and warns about mutators that run afteradtl.label. - Sub-agents (#17): a sub-agent shares its parent's session label. The Claude Code hook handles
SubagentStart, linking each sub-agent to the session it was started in, so its built-in tool calls use the parent's label even if they report a session id of their own (addSubagentStartto your hooks; see the README). For other frameworks,ADTL_SESSION_IDmakes a gateway join a parent's session (it wins overCLAUDE_CODE_SESSION_ID), andADTL_AGENT_ID/ADTL_AGENT_TYPEtag every audit entry withagent. initdrafts egress from a tool's action-metadatadestinationahead ofreadOnlyHint/openWorldHint.
@adtl/labels
- Draft action-metadata (#52):
returnMetadata.sourceand.sensitivityfeed result labels,inputMetadata.destinationfeeds egress, andoutcome/requiresRevieware new policy conditions (tool.outcome,tool.requiresReview). Claims from any server can make labels or egress stricter; relaxing needsacceptServerClaims: trueand never overrides your rules. requiresReview: trueturns anallowinto anask(matched: ["tool.requiresReview"]). Turn it off withpolicy.honorRequiresReview: false.readActionMetadata()and the mapping helpers are exported;toolEgress()takes the tool's annotations as an optional fourth argument.- FIDES interop (#19): fides-gateway labels on results (
_meta["com.github.ifc/labels"]) are read as server claims, stricter-only unless the server is allowlisted. Withfides: { emit: true, readers? }, labeled results also carry the label in that form.toFidesRecord()andfidesEvidenceRef()build the trust-annotationsifc.fides.v1scheme record. - A2A trust labels (#18): a draft A2A extension,
docs/a2a-trust-labels-v1.md, carries the sender's session label on A2A Messages and Artifacts, signed with its Ed25519 key and bound to the parts by digest.signA2ALabel()attaches it;readA2ALabel()checks it: a trusted key's label is used as is, another key's can only make things stricter, and a missing, malformed or broken one falls back to a restrictive label. attachLabel()takes an options argument ({ fides: { readers } }), andunionClaims()is exported.
@adtl/interceptors
- Record ids (#48): tool rule
recordIds: <field>makesadtl.labelremember a tainted session's writes by record id in the ledger (ids the write tool was given and returned), and join the label back on reads that return those ids. Labels on records now survive servers whose update replaces the metadata, as Mem0's hosted docs describe. Audit entries getrecordIds: { matched, writers }. - With
fides.emit,adtl.labelputs the session's label on every outgoingtools/callrequest, as_meta["com.github.ifc/labels"]["$"]. Readers come fromfides.readers, else the call's principal, else nobody. adtl.policyreads action-metadata fromconfig.toolAnnotations, which the gateway already passes fromtools/list.
Examples
examples/fake-memorycan act like Mem0's hosted platform as its docs describe it:updateMode: "replace"(--update-replace) replaces metadata on update, andmerge: true(--merge) folds a barer record into a fuller one and hides it unlesssearch_memoryis called withinclude_merged. New tests cover both. Records added in one call now get distinct ids.examples/a2a-labels: two agents pass a tainted summary over A2A; the receiver inherits the label and asks before posting, and a tampered message fails closed.examples/fides-interop: an opt-in check that runs ADTL's emitted labels through fides-gateway's own models and label resolution, in your local fides-gateway checkout. Not part ofnpm test.
v0.7.0 (experimental)
The exfiltration attack now runs against GitHub's real MCP server, and Cedar policies can decide who may use which tools.
Upgrading
- No config changes are needed.
gateway.cedaronly applies when you set it, and its engine (@cedar-policy/cedar-wasm) is an optional dependency you install yourself.
@adtl/gateway
- Cedar authorization (#11):
gateway.cedar: { policies, entities?, timeZone? }. Each call becomes a Cedar request (User::"<id>",Action::"tools/call",Tool::"<server>.<tool>") withserver,principalId,listing,timeandargumentsin the context, for rules such as working hours or "only repos in your org". Policies that don't parse stop startup; evaluation errors deny. Tool arguments can't name Cedar entities. - The gateway takes several authorizers (
authorizer: [a, b]); every one must allow, and the first denial is reported. Withrolesandcedarboth set, both apply. CedarAuthorizerandgatewayAuthorizers()are exported.
Examples
examples/github-real-demo(#27): the GitHub-issue exfiltration attack againstgithub-mcp-server(tested with v2.0.3), with two throwaway repos and a fine-grained token. Run 2's labels come from thegithubpreset viaadtl-gateway init, not a hand-written config. Opt-in withnpm run demo:github; not part ofnpm test. It checks for the leak through the GitHub API and deletes the leaked comment afterwards.
v0.6.0 (experimental)
Authorization and stronger evidence: roles in the config decide who may use which tools, policy rules can name who may approve an "ask", approvals can come from inside the MCP client, and session receipts, ledger entries and declassifications are signed.
Upgrading
- No config changes are needed: roles, named approvers and elicitation only apply when you set them.
- The ledger file gets two columns (
sig,signer) the first time 0.6 opens it; 0.5 can still use it. Entries written before signing are reported as such, not as problems. - The first ledger write or receipt creates
~/.adtl/signing-key.pem(orADTL_SIGNING_KEY).
@adtl/labels
- Ed25519 signing keys:
loadOrCreateSigner()(~/.adtl/signing-key.pem, orADTL_SIGNING_KEY; created on first use, mode 0600),loadSigner(),signCanonical(),verifyCanonical(),verifySignature(). Public keys are writtened25519:<base64url>. - Policy rules with
then: asktakeapprovers: [role, …]: who may answer (#10). The decision carries each winning rule's approver roles. globToRegExp()is exported, forserver.namepatterns.
@adtl/ledger
- Signed entries (#29): with a
signer, every entry, declassifications included, carries an Ed25519 signature over its hash and the signer's public key.verify()reports bad signatures, entries signed by keys outsidetrustedKeys(default: the signer's own), and unsigned entries after signed ones. Older ledgers get the new columns automatically; their entries count as written before signing.
@adtl/gateway
adtl-gateway playground [--port 4317] [--no-open]: a local web UI that runs the real gateway in front of fake GitHub and memory servers, with three test cases, every call's label and decision, approvals as Allow / Deny buttons, an editable config and the audit log. Listens on 127.0.0.1 only. A broken config on Apply is reported and the playground keeps running; a port in use gets a message instead of a crash.- Docs: a click-through mock of the playground for GitHub Pages (
docs/playground/), with results recorded from real gateway runs. - Session receipts (#26):
adtl-gateway receipt <session>writes a signed summary of every call a session made (tool, outcome, decision, approver, call hash, result label, audit line hash, counts), built from the verified audit log.receipt verifychecks the signature, the signer (--key) and, with--log, that no call was left out.receipt listshows sessions;adtl-gateway keyprints the public key. - The interceptors, the Claude Code hook and
ledger declassifysign ledger entries with the machine's key;ledger verifyreports signatures. The hook guards the key file like the ledger. adtl-gateway initpresets for Slack (@modelcontextprotocol/server-slack, by tool name, andslack-mcp-server, by its tool hints) and Gmail (@gongrzhe/server-gmail-autoauth-mcp) (#28): messages and email are untrusted and private; posting, sending, and filters that can forward mail are external egress.- The Claude Code hook records which subagent made a call (
agent: { id, type }in the audit entry), from theagent_idandagent_typehook fields (part of #17). - Approvals in the MCP client (#6): with
gateway.approvals.elicitation: true, an "ask" is also shown in clients that support elicitation, with Allow and Deny; the first answer from any channel wins. Declining or dismissing denies. Off by default, and never used for rules with named approvers. - Named approvers (#10):
gateway.approvals.approversgives each person their own ntfy topic. An "ask" whose rules name approver roles goes only to those people, with tokens signed for each of them, and an answer counts only on the same person's reply topic, so the audit log recordsapprover. Startup checks that every named role exists, has named members, and that each member has a channel. - Role-based authorization in the config (#8):
gateway.rolesgrants tools and prompts (server.namepatterns, as in policy rules) and resources (URI patterns) to principal ids, or to"*". Once present, anything no role grants is denied. Config errors name the role and field. - Audit entries list every interceptor that ran, with its resolved
modeandfailOpenand whether each came from an override or the interceptor's default, as SEP-2624 recommends (#36):interceptors: [{ name, phase, mode, modeFrom, failOpen, failOpenFrom, failed? }]. tools/list,prompts/listandresources/listleave out what the authorizer would deny, so the agent doesn't try it (#13). Calls are still checked; nothing is hidden in audit mode.gateway.principalsets who runs the gateway (${VAR}works in itsid); it is passed to the authorizer and to the interceptors ascontext.principal.
@adtl/interceptors
config.serveris optional: without it,adtl.labelandadtl.policyusecontext.target, following SEP-2624's rule that an interceptor invoked without config uses its defaults.
v0.5.1 (experimental)
Record labels now hold up on memory servers that resolve references from recent messages and overlay updates, such as Mem0 (#41). Thanks to Edward Izgorodin for the analysis of Mem0's message buffer.
@adtl/labels
- Record stamps are written under a key per session,
adtl/record-label/<session>, and stamp keys the agent supplies are dropped. On servers that lay an update's metadata over the stored metadata (Mem0), a clean session's update no longer replaces a tainted stamp. Stamps written by 0.5.0 under the singleadtl/record-labelkey are still read. - Tool rule
scopeInto(e.g.run_id): a tainted session's writes get a scope id named after its label, so servers that resolve references from recent messages of the same scope (Mem0) don't build a clean session's facts from a tainted session's text. Clean sessions can't name a tainted scope.scopeRecord().
@adtl/interceptors
adtl.labelappliesscopeIntoon the request phase oftools/call, alongsidelabelInto.
@adtl/gateway
- Docs: which Mem0 paths carry record labels and which need a strict rule (
history(), andlist_events/get_event_statuson Mem0's hosted MCP server).
Examples
examples/fake-memorykeeps Mem0's 10-message buffer per scope, resolves "the same place as before" from it, and hasget_memoryandupdate_memory(metadata overlaid).
v0.5.0 (experimental)
Labels now survive memory servers that rewrite what they store, the audit log is tamper-evident, "ask" follows the confirmation proposal for SEP-2624, and the gateway can check who may use a tool before the policy runs.
Breaking changes
callHashnow covers the SEP-2624 call binding{ event, phase, target, payload }, so hashes in audit logs differ from 0.4.adtl-gateway ledger declassifyrequires--reason.ChainOutcomeis nowPhaseOutcome(@adtl/gateway), since SEP-2624 no longer has a chain concept.adtl.labelalso hooks the request phase oftools/call. This only matters if you run ADTL's interceptors behind your own invoker.
@adtl/labels
- Tool rules take
labelInto(stamp the session label into a per-record argument such asmetadata) andreadLabels(join stamps found in results, stricter only), for memory servers that extract facts or merge records, which the ledger can't recognize.stampRecordLabel()andreadRecordLabels(). callBindingHash().
@adtl/interceptors
adtl.policyreturns "ask" with aconfirmationrequest (id,reason,callHash,expiresAt,token), as proposed in experimental-ext-interceptors#45, and acceptscontext.confirmationswhen invoked again. Each confirmation allows one call, in one session, before it expires. A confirmation never turns a block into an allow.info["adtl/decision"]is still set.adtl.labelstamps records for tools withlabelInto, and joins the stamps it finds for tools withreadLabels.
@adtl/ledger
declassify()takes a subject (e.g. the file name), kept with the reason.declassifications()lists recent declassifications.
@adtl/gateway
Authorizerinterface: decides whether the caller may use a tool, resource or prompt at all, before the policy runs. A denial wins over any policy decision; failures deny; audit mode only logs. Pass it asnew AdtlGateway({ authorizer, principal }); denials are audited asdenied: { by, reason }. No config support yet (#8).- After a human approves a call, the gateway checks it again with the confirmation and runs it only if every validator allows it and the call still matches the approved hash. The confirmation token never reaches the agent.
- Sets
context.targetto the upstream server, andcontext.principalto the configured principal, on every interceptor invocation. - The audit log is hash-chained: each line carries
prevandhash.adtl-gateway audit verifydetects edited, removed, reordered and inserted lines and prints the last hash. The gateway and the Claude Code hook append through a lock file so the chain doesn't fork. Logs from 0.4 are continued, with their lines reported as written before the chain. - The Claude Code hook guards the audit log like the ledger:
Write/Editon it are blocked, shell commands that mention it ask first. ledger declassifyrecords the file with the reason. Newledger declassifiedlists recent declassifications: when, who, which file, why.- Audit entries get
records: { stamps, writers }when a result carried record stamps. - The npm README shows the architecture sketch.
Examples and docs
examples/fake-memory: a memory server that extracts facts on write, keeps per-item metadata and consolidates records, used in the tests.- The README has a diagram of a label following content through a memory server.
v0.4.0 (experimental)
Requires Node.js 22.13 or later (for the built-in node:sqlite).
@adtl/ledger (new)
- The label ledger: when a session that has read untrusted or private data sends text anywhere, the text's chunk hashes are recorded with the session's label; results containing that text are re-labeled when read back, in any session. Clean sessions record nothing.
- Chunks: the whole text, paragraphs and lines of 32+ characters, normalized (NFC, lowercase, whitespace collapsed).
- One SQLite file (
~/.adtl/ledger.db, orADTL_LEDGER), safe to share between processes. Entries are hash-chained (verifydetects edits and deletions) and pruned after 90 days. Damaged labels count as untrusted and private. - Declassify: a person can clear the label of specific content.
@adtl/labels
ledger:config section:enabled(default true),path,retentionDays(default 90).
@adtl/interceptors
adtl.labellooks results up in the ledger and joins any match into the label (info.ledger), and records the call's arguments when the session is tainted.
@adtl/gateway
- The Claude Code hook uses the ledger too: tool output is looked up; tool input (
Write/Editcontent,Taskprompts, ...) and lines a shell command added to files (bashEditDiff) are recorded. adtl-gateway ledger stats | verify | declassify <file>....- The hook blocks
Write/Editon the ledger file and asks before shell commands that mention it orledger declassify. - Audit log entries have
ledger: { chunks, writers }when the ledger matched. - The interceptor process gets
ADTL_LEDGERfrom the gateway's environment. - Demo:
npm run demo:ledger, a delayed injection written on Monday and triggered on Tuesday.