Skip to content

Releases

v0.8.3 (experimental)

Choose a tag to compare

@github-actions github-actions released this 18 Nov 00:47
97ad9e6

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.interceptorServers offers one.
  • InterceptorInvoker takes 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 its failOpen, and the gateway's audit mode doesn't apply to sinks. Startup stops on a sink declared with mode: "audit" or given it by an override, as the proposal requires. Audit entries mark sinks with sink: true. Closing the gateway waits for dispatched sinks to settle.
  • invalidSinks() and InterceptorInvoker.sinksSettled() are exported. unsupportedInterceptors() no longer lists sinks.

@adtl/interceptors

  • InterceptorDefinition.type accepts "sink", and SinkResult (recorded: boolean) joins InterceptorResult.

Security

  • Updated the transitive hono (4.13.18) and @hono/node-server (2.1.8), pulled in by @modelcontextprotocol/sdk, for published advisories. npm audit is clean, including dev dependencies.

v0.8.3-rc.1 (experimental)

Pre-release

Choose a tag to compare

@github-actions github-actions released this 14 Nov 01:48

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.interceptorServers offers one.
  • InterceptorInvoker takes 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 its failOpen, and the gateway's audit mode doesn't apply to sinks. Startup stops on a sink declared with mode: "audit" or given it by an override, as the proposal requires. Audit entries mark sinks with sink: true. Closing the gateway waits for dispatched sinks to settle.
  • invalidSinks() and InterceptorInvoker.sinksSettled() are exported. unsupportedInterceptors() no longer lists sinks.

@adtl/interceptors

  • InterceptorDefinition.type accepts "sink", and SinkResult (recorded: boolean) joins InterceptorResult.

Security

  • Updated the transitive hono (4.13.18) and @hono/node-server (2.1.8), pulled in by @modelcontextprotocol/sdk, for published advisories. npm audit is clean, including dev dependencies.

v0.8.2 (experimental)

Choose a tag to compare

@github-actions github-actions released this 11 Nov 01:06
44a740c

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.copiesPrivate only applies to rules that use it.
  • Session directories gain a <session>.values file next to each label file: hashes of secret-like values the session read from private sources, never the values.
  • SessionStore has two new optional methods, rememberPrivateValues and hasPrivateValue. A custom store without them still works, but rules using call.copiesPrivate then match every call (they fail closed).

@adtl/labels

  • call.copiesPrivate policy condition (#56): matches a call whose arguments hold a secret-like value the session read from a private or secret result. 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, isSecretLike and usesCopiesPrivate. InMemorySessionStore and FileSessionStore keep the fingerprints.
  • A data-class.v1 evidenceRef is read through its sensitive claim; the record itself is ignored until the scheme says where it lives (#54).

@adtl/interceptors and @adtl/gateway

  • adtl.label remembers secret-like values from private results; adtl.policy checks 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_local leaks are still mostly missed, because web pages are labeled public.

Security

  • Updated the test tooling with published advisories: vitest 5.1.0 (from 2.1.9, which pulled in vulnerable vite, esbuild, tinypool and @vitest/mocker), now with vite 8.3.7 as an explicit dev dependency, and @types/node 22.20.5. Dev-only; the published packages don't change. npm audit is clean, including dev dependencies.

v0.8.1 (experimental)

Choose a tag to compare

@github-actions github-actions released this 04 Nov 23:35
22c5176

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/sdk 1.32.2, nodemailer 10.3.1, zod 4.6.7 (a major version), and the transitive body-parser, fast-uri and qs. npm audit --omit=dev is clean.

Upgrading

  • No config changes are needed. gateway.approvals.totp and gateway.openfga only apply when you set them.
  • Config error messages come from zod 4, so their wording changed.
  • evidenceRef on labeled results now carries schema.

@adtl/gateway

  • Authenticator-app approvals (#25): gateway.approvals.totp: true asks 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 setup shows 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.openfga checks 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 alongside roles and cedar; every one must allow.
  • The playground applies gateway.interceptorOverrides from your config, and refuses bad ones. It still ignores interceptorServers, 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

Docs

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)

Choose a tag to compare

@github-actions github-actions released this 02 Nov 03:03
d383fd2

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: true now gets ask when no rule blocks it (policy.honorRequiresReview: false turns that off), and fides-gateway labels on results are now read as server claims.
  • Claude Code: add a SubagentStart hook running adtl-gateway hook, as in the README, so sub-agents are linked to their parent's session.
  • Audit entries for interceptor runs have a new timeoutMs field.

@adtl/gateway

  • Per-interceptor overrides (#50): gateway.interceptorOverrides.<name> sets failOpen, priorityHint, mode, timeoutMs and hooks for 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: audit still wins over a per-interceptor mode, and overrides that relax adtl.policy or adtl.label log a warning.
  • The audit log's interceptors entries now carry timeoutMs, and modeFrom / failOpenFrom say override when 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 the InterceptorOverrides type are exported.
  • The gateway passes a request's _meta on 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-call config. Startup stops on an unreachable server, a missing extension capability or a duplicate interceptor name, and warns about mutators that run after adtl.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 (add SubagentStart to your hooks; see the README). For other frameworks, ADTL_SESSION_ID makes a gateway join a parent's session (it wins over CLAUDE_CODE_SESSION_ID), and ADTL_AGENT_ID / ADTL_AGENT_TYPE tag every audit entry with agent.
  • init drafts egress from a tool's action-metadata destination ahead of readOnlyHint / openWorldHint.

@adtl/labels

  • Draft action-metadata (#52): returnMetadata.source and .sensitivity feed result labels, inputMetadata.destination feeds egress, and outcome / requiresReview are new policy conditions (tool.outcome, tool.requiresReview). Claims from any server can make labels or egress stricter; relaxing needs acceptServerClaims: true and never overrides your rules.
  • requiresReview: true turns an allow into an ask (matched: ["tool.requiresReview"]). Turn it off with policy.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. With fides: { emit: true, readers? }, labeled results also carry the label in that form. toFidesRecord() and fidesEvidenceRef() build the trust-annotations ifc.fides.v1 scheme 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 } }), and unionClaims() is exported.

@adtl/interceptors

  • Record ids (#48): tool rule recordIds: <field> makes adtl.label remember 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 get recordIds: { matched, writers }.
  • With fides.emit, adtl.label puts the session's label on every outgoing tools/call request, as _meta["com.github.ifc/labels"]["$"]. Readers come from fides.readers, else the call's principal, else nobody.
  • adtl.policy reads action-metadata from config.toolAnnotations, which the gateway already passes from tools/list.

Examples

  • examples/fake-memory can act like Mem0's hosted platform as its docs describe it: updateMode: "replace" (--update-replace) replaces metadata on update, and merge: true (--merge) folds a barer record into a fuller one and hides it unless search_memory is called with include_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 of npm test.

v0.7.0 (experimental)

Choose a tag to compare

@github-actions github-actions released this 29 Oct 01:23
f0a90c5

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.cedar only 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>") with server, principalId, listing, time and arguments in 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. With roles and cedar both set, both apply.
  • CedarAuthorizer and gatewayAuthorizers() are exported.

Examples

  • examples/github-real-demo (#27): the GitHub-issue exfiltration attack against github-mcp-server (tested with v2.0.3), with two throwaway repos and a fine-grained token. Run 2's labels come from the github preset via adtl-gateway init, not a hand-written config. Opt-in with npm run demo:github; not part of npm test. It checks for the leak through the GitHub API and deletes the leaked comment afterwards.

v0.6.0 (experimental)

Choose a tag to compare

@github-actions github-actions released this 25 Oct 17:15
545a1a5

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 (or ADTL_SIGNING_KEY).

@adtl/labels

  • Ed25519 signing keys: loadOrCreateSigner() (~/.adtl/signing-key.pem, or ADTL_SIGNING_KEY; created on first use, mode 0600), loadSigner(), signCanonical(), verifyCanonical(), verifySignature(). Public keys are written ed25519:<base64url>.
  • Policy rules with then: ask take approvers: [role, …]: who may answer (#10). The decision carries each winning rule's approver roles.
  • globToRegExp() is exported, for server.name patterns.

@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 outside trustedKeys (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 verify checks the signature, the signer (--key) and, with --log, that no call was left out. receipt list shows sessions; adtl-gateway key prints the public key.
  • The interceptors, the Claude Code hook and ledger declassify sign ledger entries with the machine's key; ledger verify reports signatures. The hook guards the key file like the ledger.
  • adtl-gateway init presets for Slack (@modelcontextprotocol/server-slack, by tool name, and slack-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 the agent_id and agent_type hook 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.approvers gives 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 records approver. 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.roles grants tools and prompts (server.name patterns, 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 mode and failOpen and 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/list and resources/list leave 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.principal sets who runs the gateway (${VAR} works in its id); it is passed to the authorizer and to the interceptors as context.principal.

@adtl/interceptors

  • config.server is optional: without it, adtl.label and adtl.policy use context.target, following SEP-2624's rule that an interceptor invoked without config uses its defaults.

v0.5.1 (experimental)

Choose a tag to compare

@github-actions github-actions released this 21 Oct 00:10
a62b79f

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 single adtl/record-label key 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.label applies scopeInto on the request phase of tools/call, alongside labelInto.

@adtl/gateway

  • Docs: which Mem0 paths carry record labels and which need a strict rule (history(), and list_events / get_event_status on Mem0's hosted MCP server).

Examples

  • examples/fake-memory keeps Mem0's 10-message buffer per scope, resolves "the same place as before" from it, and has get_memory and update_memory (metadata overlaid).

v0.5.0 (experimental)

Choose a tag to compare

@github-actions github-actions released this 20 Oct 10:40
3b9a1d7

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

  • callHash now covers the SEP-2624 call binding { event, phase, target, payload }, so hashes in audit logs differ from 0.4.
  • adtl-gateway ledger declassify requires --reason.
  • ChainOutcome is now PhaseOutcome (@adtl/gateway), since SEP-2624 no longer has a chain concept.
  • adtl.label also hooks the request phase of tools/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 as metadata) and readLabels (join stamps found in results, stricter only), for memory servers that extract facts or merge records, which the ledger can't recognize. stampRecordLabel() and readRecordLabels().
  • callBindingHash().

@adtl/interceptors

  • adtl.policy returns "ask" with a confirmation request (id, reason, callHash, expiresAt, token), as proposed in experimental-ext-interceptors#45, and accepts context.confirmations when 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.label stamps records for tools with labelInto, and joins the stamps it finds for tools with readLabels.

@adtl/ledger

  • declassify() takes a subject (e.g. the file name), kept with the reason. declassifications() lists recent declassifications.

@adtl/gateway

  • Authorizer interface: 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 as new AdtlGateway({ authorizer, principal }); denials are audited as denied: { 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.target to the upstream server, and context.principal to the configured principal, on every interceptor invocation.
  • The audit log is hash-chained: each line carries prev and hash. adtl-gateway audit verify detects 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/Edit on it are blocked, shell commands that mention it ask first.
  • ledger declassify records the file with the reason. New ledger declassified lists 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)

Choose a tag to compare

@github-actions github-actions released this 16 Oct 23:51

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, or ADTL_LEDGER), safe to share between processes. Entries are hash-chained (verify detects 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.label looks 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/Edit content, Task prompts, ...) and lines a shell command added to files (bashEditDiff) are recorded.
  • adtl-gateway ledger stats | verify | declassify <file>....
  • The hook blocks Write/Edit on the ledger file and asks before shell commands that mention it or ledger declassify.
  • Audit log entries have ledger: { chunks, writers } when the ledger matched.
  • The interceptor process gets ADTL_LEDGER from the gateway's environment.
  • Demo: npm run demo:ledger, a delayed injection written on Monday and triggered on Tuesday.