Api-Design on Lessons learned

A read with legal effect: listing ISDS messages counts as delivery

Sun, 13 Sep 2026 14:09:00 +0200

Polling an inbox from a cron job looks harmless, since reading has no side effects. In the Czech Data Box system (ISDS, datové schránky) it does: the moment an authorized person logs in to the box is the moment every message waiting in it is legally delivered (doručení). An application counts as that person when it logs in and fetches the list of received messages. A 3 a.m. retrieval of a tax office’s request starts the deadline to answer it, whether anyone reads the message or not.

If your code talks to ISDS, every scheduled retrieval and every copy of your database that still holds the box’s password is a legal act.

Setup

An Odoo 18 addon files incoming Data Box messages into the company’s document store (the OCA dms addon). It talks to ISDS over SOAP with zeep (the parsing bug from that client is here ). A retrieval calls GetListOfReceivedMessages for the last 100 days and downloads each new message with its signed copy.

A possible next feature was a cron job, so that the documents appear without anyone pressing a button.

Why a read starts a deadline

Act No. 300/2008 Sb. delivers a message in one of two ways. Under § 17(3), it is delivered when a person whose permissions cover it logs in to the box. Under § 17(4), if nobody logs in within 10 days of the message’s arrival, it counts as delivered on the last day of that period, which Czech lawyers call delivery by fiction.

People rely on fiction as a buffer. A box that nobody opens for a week gives you up to 10 extra days before a deadline starts running. A nightly cron throws that buffer away. Every message is delivered the night after it arrives, and its deadline starts then, while the documents sit unread in a folder.

Not every call has this effect. GetOwnerInfoFromLogin checks the credentials and returns the box ID and owner without causing delivery. The addon uses it to validate a login before it creates anything.

The design

Once the domain model had the rule written down (“Every Retrieval causes Delivery of the Messages waiting in the box”), the decisions followed from it:

Each connection has a Retrieval Mode, On demand or Scheduled, and On demand is the default.
The “Check data box” button asks for confirmation: “Checking the data box counts as Delivery (doručení) of every Message waiting in it, which starts legal deadlines. Continue?”
Choosing Scheduled shows a warning, and the form keeps showing it for as long as the connection stays Scheduled. The daily cron job skips On demand connections.
The one-step setup wizard says that its first retrieval counts as delivery.

Copies of the production database

The usual way to get a realistic test environment for Odoo is to restore a production backup. That copy holds the ISDS username and password, and possibly a scheduled connection. A staging server that runs the cron, or a developer who presses “Check data box” to see what it does, delivers the production company’s official mail.

Odoo has a hook for this. When you run odoo-bin neutralize, or restore a database with Neutralize checked in the database manager, it runs each installed module’s data/neutralize.sql. Core modules use it to switch off outgoing mail and crons. The ISDS addon adds its own:

-- a neutralized copy must never cause Delivery: drop the Credential passwords
-- and stop Scheduled Retrievals
UPDATE dms_isds_connection
 SET password = NULL,
 retrieval_mode = 'on_demand';

-- unfinished Quick Starts hold a password too, and connecting retrieves at once
DELETE FROM dms_isds_quick_start;

A retrieval on a neutralized copy fails on the missing password before it contacts ISDS. The test checks exactly that. It runs the module’s neutralization queries, presses the button, triggers the cron, and asserts that the ISDS listing was never called:

self._neutralize()

with self.assertRaisesRegex(UserError, "password"):
 self.connection.action_check_data_box()
self.env.ref(CRON).method_direct_trigger()

listing.assert_not_called()

The development setup restores production data and neutralizes it on every refresh, so nobody has to remember.

Neutralization changes only the copy. The original backup still holds the password in plaintext, so restrict access to backups and encrypt them.

Takeaway

Before you schedule a “read-only” integration, find out what reading does on the other side. In ISDS, it is legal delivery, so the integration retrieves on demand by default, and a restored database can’t log in.

List the integrations in your own staging setup that still hold production credentials, and check whether any of their reads change something for someone else.

Reference data published after the period: provisional values, then frozen observations

Sun, 21 Jun 2026 22:00:00 +0200

A tax engine converts foreign-currency trades into the reporting currency. The law allows two methods per tax year: the central bank’s daily rate for each transaction date, or a single annual rate per currency that the tax authority publishes. Conservative mode always uses the annual rate.

The annual rate for a year is published in the first months of the next year. Users also want in-year numbers, so for most of a calendar year, conservative mode needs a value that does not exist yet.

The same thing happens with any reference value fixed after the period it covers: annual average rates, inflation indices used for indexation, final settlement prices, revised statistics. This post covers the design that handled it, and the bug in the first version of its “immutable cache”.

Make the status part of the value

While the annual rate is unpublished, conservative mode computes on the daily rate as a proxy. Without a label, a reviewer who sees conservative mode using daily rates in September reports it as a bug. So every conversion carries its status:

type Conversion =
 | { ok: true; amount: Decimal; status: "provisional"; rateRefs: RateKey[] } // daily proxy
 | { ok: true; amount: Decimal; status: "final"; rateRefs: [RateKey] } // annual rate published
 | { ok: true; amount: Decimal; status: "frozen"; frozenFrom: "provisional" | "final";
 rateObservations: RateObservation[] } // pinned at handoff
 | { ok: false; reason: "missing-rate"; needed: RateKey[] };

The dashboard shows a provisional badge next to each figure computed that way.

Publication is not a stored flag. The annual rate counts as published when its rate record exists:

const annual = await readRate(tx, annualRateKey(currency, taxYear));
if (annual) return { ok: true, amount: multiply(amount, annual.rate), status: "final", rateRefs: [annualKey] };
await requestAnnualRate(tx, annualKey); // enqueue a fetch job, deduplicated per key
return daily; // the provisional proxy

An open assessment always reads through this function. Once the fetch job stores the annual rate, the next read returns final. No “rate published” boolean can disagree with the data.

While the case is open, everything recomputes live. When it is handed to an advisor, the conversions freeze. That gives two rules: open assessments track the newest data, and handed-off assessments stay reproducible forever.

“Immutable, keyed by the rate’s identity” cannot store a correction

The first schema followed the design doc literally: a rate is a historical fact, so store it once and never refetch.

create table rate (
 source text, base text, quote text, rate_date date,
 rate numeric not null,
 fetched_at timestamptz not null default now(),
 primary key (source, base, quote, rate_date)
);
grant select, insert on rate to app; -- no UPDATE, no DELETE
-- writes: insert ... on conflict do nothing

The same design doc also said: “a correction is a new record, not an overwrite.” The primary key makes that impossible. A provider that corrects a published value sends a second row with the same key, and on conflict do nothing drops it without an error. The cache stays immutable by losing the corrected value.

The second migration separated the two requirements. Observations are append-only, and a small pointer table says which observation is current:

create table rate_observation (
 id uuid primary key default gen_random_uuid(),
 source text, base text, quote text, rate_date date,
 rate numeric not null, fetched_at timestamptz not null
);

create table rate_canonical (
 source text, base text, quote text, rate_date date,
 observation_id uuid not null references rate_observation(id) on delete restrict,
 primary key (source, base, quote, rate_date)
);

create view rate as
 select o.* from rate_canonical c join rate_observation o on o.id = c.observation_id;

A security definer function performs every write. It takes a per-key advisory lock. A retry with an equal value returns the existing observation. A different value inserts a new observation and moves the pointer. Open assessments read the rate view and pick up the correction. A frozen assessment stores the observation IDs it used, one per conversion leg, and never reads the pointer again. A currency that the central bank doesn’t list converts through a pivot currency, so its conversion pins two observations.

Three Postgres gotchas from making it immutable

The first implementation of the freeze broke 10 tests. One fix commit covered three defects:

No NUL in text. The advisory lock key concatenated the key parts with chr(0) as a separator. Postgres text cannot contain a null byte, so every write raised an error. Use a separator that cannot appear in the parts and is legal in text, such as chr(31):

perform pg_advisory_xact_lock(hashtextextended(
 concat_ws(chr(31), p_source, p_base, p_quote, p_rate_date::text), 0));

FOR SHARE needs UPDATE privilege. At handoff, the freeze must not race a correction that moves the pointer. The first version locked the pointer row with select ... for share. In Postgres, every row-locking clause requires UPDATE privilege on the table, and the app role has none, on purpose. The fix takes the same advisory lock the writer takes, so the advisory lock becomes the single point of serialization. When one handoff freezes many conversions, it acquires the locks in a fixed order (sorted by conversion id), so two concurrent handoffs cannot deadlock.

node-postgres turns date into a shifted Date. By default, pg parses a date column (OID 1082) into a JavaScript Date at local midnight. Serialized back as UTC in a timezone east of Greenwich, 2026-03-02 becomes 2026-03-01T23:00:00.000Z, the previous day. The schema types already said string. Keep the literal:

import { types } from "pg";
types.setTypeParser(1082, (value) => value); // 'YYYY-MM-DD' stays a string; timestamptz unaffected

Two smaller rules

Exact decimals end to end. The central bank quotes some currencies per 100 units. The parser divides the listed rate by the quoted quantity in exact decimal arithmetic, and rejects a result that would not terminate rather than rounding it. No rate passes through an IEEE float.
Crypto is an asset, not a currency. The coding agent’s first plan gave crypto its own rate subsystem. I corrected that during the design session: crypto is priced through its trading pair (BTC/EUR, ETH/USD), like a stock, and the pair’s quote currency converts through an ordinary rate. Only a crypto-to-crypto swap needs a separate market valuation, and that is asset valuation, not currency conversion.

Takeaway

When a reference value is published after the period it describes, put the status in the value (provisional, final, frozen) so that a proxy cannot pass for the real number. Let the existence of the record mean “published”. Treat “immutable” and “correctable” as two tables, not one primary key: append observations, point to the current one, and let frozen results pin observation IDs.

If your cache is immutable through ON CONFLICT DO NOTHING, send it a corrected value for an existing key and check whether anything records that the value changed.

Before building a reference catalog, check whether the attribute reaches the computation

Sun, 21 Jun 2026 21:00:00 +0200

A tax engine for investment accounts has to put every instrument into a category, because the category decides the rules. A real share sold after the holding period can be exempt. A CFD on the same stock is a derivative and is taxed no matter how long you hold it. Brokers don’t make this easy. One reports CFDs under “stocks”. A position can be a fractional share or a whole one. An ETF’s ISIN doesn’t say whether the fund pays out dividends or reinvests them.

During the design session, the coding agent recommended a central instrument catalog: ISIN → {category, asset class, accumulating/distributing, derivative, fractional, …}, seeded from a market data provider and maintained over time. Per-broker adapters would propose a category and reconcile it against the catalog, and anything unresolved would go to a review queue. It argued that the accumulating/distributing flag in particular had to come from the catalog.

I rejected it in two sentences:

If we get the dividend, we have to deal with it. If the fund gets the dividend, it’s non-taxable for the individual.

The attribute decides whether an event exists

A distributing fund pays the investor a dividend, and the broker reports it as a dividend event, which is taxed. An accumulating fund keeps the dividend inside the fund. The investor receives nothing, and the broker reports nothing, so nothing is taxed until the units are sold, and the sale is an ordinary sell event.

The flag the catalog was meant to supply only decides whether an event exists, and the transaction ledger already records whether one did. Removing the flag from the catalog changes no input to the engine. It was also the catalog’s main justification.

The reusable check: for every attribute you are about to maintain as reference data, flip its value and ask which computation input changes.

Attribute	What changes if it flips	Already in the events?	Source
Accumulating / distributing	Whether a dividend event exists	Yes: the event is present or absent	None needed
CFD / real share	The rules applied to the same sell event	No	The broker’s own export (instrument type, leverage)
Fractional / whole share	Whether an exemption is arguable	No	The broker’s idiom
Crypto / token / derivative on crypto	Which rules and caps apply	No	The broker’s idiom

The remaining attributes do change the computation. All of them can be read from the broker that produced the record, so classification belongs in the per-broker adapter. The adapter already parses that broker’s export and knows its quirks. A global catalog would only reconcile against them afterward.

Classify where the source idiom lives, and refuse to guess

The adapter for the broker that labels CFDs as stocks classifies by the type and leverage columns of its own export:

function classify(type: unknown, leverage: unknown): Category | { explanation: string } {
 const kind = header(type);
 if (/cfd|contract for difference/.test(kind)) return "derivative";
 const multiplier = Number(text(leverage).replace(/x$/i, ""));
 if (!kind || !Number.isFinite(multiplier) || multiplier < 1) return { explanation: "Type or Leverage is missing or invalid." };
 if (kind.includes("crypto")) {
 return multiplier === 1 ? "crypto" : { explanation: `Crypto Type conflicts with leveraged position (${text(leverage)}).` };
 }
 if (multiplier > 1 && /(stock|etf|real|cfd|contract)/.test(kind)) return "derivative";
 if (multiplier === 1 && /(stock|etf|real|share|security)/.test(kind)) return "security";
 return { explanation: `Type ${text(type)} and Leverage ${text(leverage)} cannot be classified.` };
}

No default branch picks the most likely category. A row the rules cannot classify becomes a review item (AMBIGUOUS_CATEGORY with the raw row reference) and stays out of the tax computation. A misclassified instrument produces a wrong filing with no warning sign, which is worse than an incomplete one.

The ISIN and ticker stay on the record for cross-checking and audit, but nothing uses them to decide a category.

What dropping the catalog removed

A licensed data feed and the work of keeping up with new listings, delistings, and corrections.
A reconciliation layer between adapter output and catalog values, plus the conflict UI that goes with it.
A global table keyed by ISIN that every user’s trades would look up. In this design, real instrument identity is visible only inside the adapter at ingestion, and the stored record carries a pseudonymous ID. That design is described in When the server must compute on confidential data, split the data by who may read it .

The cost moved into the adapters: classification is now only as correct as each adapter. Every adapter has its own test suite for its broker’s export format, and adding a broker means writing its classification rules and tests.

Caveat: some tax systems tax events that never happened

The shortcut holds where tax follows money the investor actually receives. Some tax systems tax deemed income on fund holdings that paid nothing out. Germany’s Vorabpauschale, UK reporting funds’ excess reportable income and the US PFIC regime are examples. There, the accumulating flag produces an income line that no event carries, and you need the attribute from somewhere. That is exactly the case the flip test catches: the computation input changes even though no event changes.

Takeaway

Before you maintain reference data for an attribute, flip it and see which input of your computation changes. If the only effect is whether an event happens, and your event stream already records that, you don’t need the attribute. If an input does change, get the value from whoever produced the record, and send anything it can’t classify to review.

The agent’s recommendation was internally consistent and sounded responsible. It took someone who knew where the taxable event comes from to see that the attribute changed nothing. When an agent proposes reference data, run the flip test on every attribute before accepting it.

When the server must compute on confidential data, split the data by who may read it

Sun, 21 Jun 2026 20:00:00 +0200

I designed a web app that computes a person’s tax on their investment trades. Professional advisory firms run it for their own clients. Clients connect broker APIs or upload statements, and the server runs lot matching, currency conversion, and the holding-period tests. A client with a messy case can hand it to an advisor.

The confidentiality requirement may sound contradictory. The advisor owes the client professional secrecy from the first contact. The platform operator should not be able to read client data at rest, and the same goes for a stolen backup, a tenant boundary bug, or a subpoena served on the platform. The server still has to compute on all of it, including in background jobs while the user is offline.

Neither usual answer works:

Disk or database encryption protects against a stolen disk. The operator, its DBAs, and a subpoena still get plaintext.
Client-side end-to-end encryption fails because the server is the calculator. Background sync, recomputation after new data, and the advisor’s view all need plaintext on the server. In a web app it is weaker than it sounds anyway: the server ships the JavaScript on every load, so an operator that serves malicious code gets the password.

What worked was a question I had skipped: which fields does the computation actually read?

List what the engine needs

For every realized event, the tax engine needs a date, a quantity, amounts in the reporting currency, fees, an event type, and an asset category (security, crypto, derivative). To match lots, it has to know that two trades are the same instrument. It doesn’t need the instrument’s name, ticker, or ISIN, and it doesn’t need the broker, account number, or person.

One step needs real identity: classifying an instrument into a category. A broker may report a CFD under “stocks”, and a share can be fractional or whole. That happens once, at ingestion, inside a per-broker adapter. The adapter sees identity in memory, emits a de-identified, categorized record, and the identity goes elsewhere.

So the data splits into two zones, each with its own readers:

	Zone 1: tax skeleton	Zone 2: identity vault
Contents	surrogate instrument ID, category, dates, quantity, amounts, fees, event type	surrogate → name/ticker/ISIN, broker, account, personal data
Encrypted under	per-tenant key encryption key in a KMS (envelope encryption)	key chain rooted in the user’s password
Readers	engine (in memory, during compute), the firm after handoff	the user in session, the firm after handoff
Platform operator	ciphertext at rest; if it decrypts, it gets anonymous arithmetic	ciphertext only
Background jobs	read and write	write only, through a public-key layer
Lost password	survives; the case can still be computed and filed	lost unless the user has the recovery code

Zone 1 is intentionally not under the user’s key. Under the user’s key, the background sync, the in-year recompute, and the advisor’s computation would all stop working as soon as the user logged out. Background jobs write to Zone 2 by encrypting to the user’s public key. Only a logged-in user can decrypt.

Surrogate IDs: a keyed hash, scoped per user

Lot matching groups trades by instrument, so the skeleton needs a stable ID that is not the instrument. The design is an HMAC with a per-user key held in the KMS:

// Stable across one user's accounts and years, unlinkable across users.
export async function deriveSurrogateInstrumentId(userId: string, instrument: string, broker: string) {
 if (!instrument || !broker) throw new Error("surrogate requires instrument identity and broker");
 return kmsHmac(`surrogate:user:${userId}`, JSON.stringify([instrument, broker]));
}

Each alternative breaks one requirement:

A plain hash of the ISIN falls to a dictionary attack. The set of listed instruments is small, so hashing them all takes seconds.
One global HMAC key makes the same instrument correlate across every user in a dump.
A random ID per trade cannot be recomputed. Next year’s sync, or a second account at another broker, has to land on the same ID without reading the vault, or carried-in lots stop matching.

The keyed hash protects a database dump. An operator who can call the KMS live can still test “does this user hold this instrument”. That is past the threat model’s at-rest boundary, so write it down instead of claiming more.

Access and liability begin at the same instant

Before handoff, the firm’s advisors have no access to a prospect’s case. For identity, the user’s key enforces that cryptographically. The anonymous skeleton sits under the firm’s own key, so for it, access control is the barrier. It matches the legal position: no engagement contract, no professional liability, only precontractual confidentiality.

Handoff is one atomic event. The engagement contract forms, the firm’s anti-money-laundering (AML) and know-your-customer (KYC) duties start, and the vault’s relevant portion is rewrapped to the firm’s key. Data access and liability start together, so neither exists without the other.

The coding agent’s first draft at this step was wrong. It proposed default-minimal disclosure: share only the vault fields the flagged items needed. I rejected it because an advisor who takes on liability and an AML duty cannot sign off on a case half-blind. The boundary that held was purpose, not field sensitivity: everything the past outcome was built from transfers in full, and anything forward-looking (plans, rebalancing ideas, notes) never transfers. Data minimization still applies, but the line runs between past and future, not through the case.

One password, auto-unlock, never transmitted: pick an aPAKE

The first plan was standard session login plus a client-side KDF for the vault key, with OPAQUE as a later upgrade. That leaves two bad choices:

Two passwords: one for login, sent to the server, and one for the vault, used only in the browser. Users hate it.
One password, still POSTed for login, also used to derive the vault key. It gives auto-unlock, and it quietly hands the operator the vault password on every login. Zone 2 stops protecting anything.

With a standard login, one password cannot also stay off the server. An asymmetric PAKE fixes the login side. OPAQUE (RFC 9807) authenticates without the server learning the password, and gives the client an export_key that the server never sees. Root the vault in it:

// K_vault = HKDF(export_key); unwraps user key → RSA private key → vault entries
function deriveVaultKeyBytes(exportKey: Uint8Array): Uint8Array {
 if (exportKey.length === 0) throw new Error("export_key is required");
 return hkdf(sha256, exportKey, new Uint8Array(0), K_VAULT_INFO, 32);
}

A password reset is a new OPAQUE registration with a new export_key. The mandatory recovery code rewraps the vault chain to the new root, and Zone 1 is untouched. Use a vetted library: the registration and login flows and the export_key handling are now part of the vault’s security.

The tenant boundary belongs in the database

Each firm is a tenant, and one firm’s prospects must never show up in another firm’s queries. A forgotten WHERE firm_id = ? should return nothing, not another tenant’s rows. With Postgres row-level security, three details decide whether it fails closed:

alter table client owner to app_migrator; -- the app role is not the owner
alter table client force row level security; -- the owner obeys policies too
create policy firm_isolation on client
 using (firm_id = current_setting('app.firm_id')::uuid)
 with check (firm_id = current_setting('app.firm_id')::uuid);

await db.transaction().execute(async (tx) => {
 await sql`select set_config('app.firm_id', ${firmId}, true)`.execute(tx); // true = transaction-local
 return work(tx);
});

Table owners bypass RLS unless it is forced. Superusers and BYPASSRLS roles bypass it always, so the app must connect as neither.
current_setting without missing_ok, plus the ::uuid cast, raises when the tenant was never set or is empty. A missing tenant is an error, not an empty match.
set_config(..., true) resets at commit or rollback. With false, a pooled connection carries one firm’s ID into the next request, and a transaction-mode pooler can hand the setting to a different client.

Write down the floors

The design makes specific claims and lists what it does not cover. That list is part of the design:

Plaintext exists in memory during ingestion and compute. The claim is “zero to the operator at rest”, never “the platform never sees it”.
amount ÷ quantity approximates a unit price that can be matched against market data. It is exploitable only by someone who already decrypted Zone 1.
The web JavaScript trust gap stays open. OPAQUE stops offline cracking of a stolen verifier table, not a malicious bundle. A native client is the eventual fix.
An API-connected account reveals which broker it is, because the token names it. A manual upload keeps the broker in Zone 2. The user gets that choice in the UI.
A forgotten password without the recovery code loses the labels. The skeleton survives, and the user is told to keep their own copies of the source statements.

Takeaway

When the server has to be the calculator, don’t choose between “encrypt the disk” and “encrypt everything client-side”. List the readers (user, professional, engine, operator) and what each one needs. Then check whether the computation can run without identity. When it can, identity moves into a zone the computation never opens, and the remaining decisions follow from that: keyed surrogates, a handoff that rewraps keys, an aPAKE for the single password.

In practice, I ran the design as an interview with a coding agent. It asked one question at a time, proposed options with a recommendation, and recorded each decision as an ADR with a “Why this is non-obvious” section: the design a reader would expect, and why it was rejected here. Several recommendations were reasonable but wrong. Two of my corrections removed whole planned pieces: the default-minimal handoff, and an instrument catalog that event-driven classification made unnecessary.

An MCP server has more outputs than tool results

Tue, 19 May 2026 20:00:00 +0200

I designed a local stdio MCP server in Go that gives an LLM scoped access to a shared password vault. Two facts set the threat model. Any member of a shared vault can write an entry comment that another member’s agent later reads, so stored text is attacker-controlled. And the model can call every tool in the manifest, so whoever steers the model gets that authority too.

The plan started with a prompt-injection fence around user strings. Most of the work ended up elsewhere.

Keep the secret off the transcript

Once get_password returns plaintext, the value sits in the model’s context and the host’s chat history, and no scope rule can take it back. So the everyday path never crosses that boundary:

copy_password_to_clipboard takes an ID, writes the value to the OS clipboard from inside the server, and returns Password (id=42) copied to clipboard. Auto-clear compares a SHA-256 of the current clipboard first, so it can’t wipe something the user copied later.
create_password_generated generates the value server-side and returns only the new row’s ID.
get_password returns the literal <redacted; revealPlaintext=never> by default, and its description points the model at the clipboard tool.

The confirmation first included the fenced entry title. That was removed: the model already has the title, and “action just completed” is a bad moment to hand it attacker-written text. A tool result should echo as little as possible.

Plaintext in chat remains for cases where the model has to reason about the value, such as a reuse audit. It sits behind a setting: never, per_call or always.

That setting began as a boolean, and the trap was in the annotations. A read is correctly readOnlyHint=true, so the host’s confirmation never fires, and one injected instruction could walk list_passwords → get_password across every entry in scope. Marking the read as destructive doesn’t help: annotations are static at registration, and hosts may ignore the cue on a read-only tool.

So per_call is an OS-native modal raised inside the server before the value is serialized, with a 30-second timeout that fails closed. If no GUI is available, the server refuses to start in that mode.

Two more manifest details matter. destructiveHint and openWorldHint default to true in the spec, which is why the Go SDK types them as *bool, and every tool here sets them explicitly. And the manifest itself is a control: if the clipboard probe fails, the tool is never registered, so the model can’t try it.

Authority lives in code

Tool descriptions are instructions to something an attacker may be steering, so they count as guidance, not control. Scope is a deterministic filter on (vault, [tags], mode), and the type system gates writes:

func (s *scopedOps) DeletePassword(ctx context.Context, rule *scope.ResolvedRule, id ID) error

A rule only comes from the scope resolver, so a handler that skips the check has nothing to pass and doesn’t compile. A runtime check catches the wrong rule: another vault, or a read-only mode. The scope itself lives in the OS keychain, and the server only reads it so that no tool call can widen it.

The input schema enforces less than it looks like

With the Go SDK, mcp.AddTool derives the input schema from struct tags. An earlier tag format, jsonschema:"required,description=...", failed at registration because the jsonschema tag is now the property description and nothing else. The tags were rewritten as prose:

Mode string `json:"mode,omitempty" jsonschema:"Strategy. (Schema hints: enum=memorable; enum=random.)"`
Length int `json:"length,omitempty" jsonschema:"Length. (Schema hints: minimum=6; maximum=32.)"`

That reads like a constraint and enforces nothing. The generated schema has only type and description, and a call with mode=evil, length=999 reaches the handler. The handler’s own validation is the only check, and it has to reject: the generator below it silently clamps, so the model would ask for one thing and get another.

The schema does give you types, required fields, and additionalProperties: false. When it rejects a call, the SDK answers before your handler runs, so your audit middleware never sees it, and the message echoes the offending value.

Beyond that, arguments are IDs, enums, and bounded integers. Omitted and [] mean different things on an update, so that field is a *[]int64. The model can’t push a row out of its own visibility, because one allowed tag must remain.

Stored content is deliberately not filtered. A comment reading “ignore previous instructions” is legal data, and the regular clients show it verbatim. Escaping happens when text leaves for the model.

The fence, and the encoder after it

Read tools wrap each user string, and their descriptions tell the model that fenced text is data:

<user_content>{escaped}</user_content>

&, < and > are HTML-escaped so a stored payload can’t close the tag. C0 controls are escaped too, because a stored ESC paints ANSI sequences on the terminal of anyone inspecting raw traffic, and the nine bidi overrides are replaced so stored text can’t reorder what a human approves.

“Ignore previous instructions” passes through unchanged. Against natural-language injection, the fence makes the boundary explicit. The real limit is what a steered model can reach.

Two gaps remain, both visible only by running it:

The tags don’t arrive as written. Returning a typed Out lets the SDK serialize it with encoding/json, which HTML-escapes by default. A title reaches the model’s text block as <user_content>..., and & becomes &. The payload still can’t close the fence, but the literal the tool description promises isn’t the literal on the wire. To control it, set result.Content yourself using an encoder with SetEscapeHTML(false).
The escape table works on bytes. It covers bytes below 0x20, so DEL and U+009B, the 8-bit CSI encoded as C2 9B, pass through. A rune-based check with unicode.IsControl catches both.

Each sink needs its own treatment

Sink	Data	Treatment
Tool result	Free text	Escape, replace bidi overrides, fence. Keep ZWJ and RLM, which Arabic, Indic scripts, and emoji need
Tool result	Vault and tag names	Strip control and format runes, cap at 256, then fence, which still protects a handler that forgets the fence
Startup error	Backend-supplied version	Allowlist regex, otherwise `unknown`
Consent dialog	Entry title	Reject controls, line separators and bidi; truncate to 80 runes
Subprocess	Entry title	Environment variable, never script source
Audit log	Content fields	Dropped; a search query is logged as its length
Tool error	Anything	Fixed text

The consent dialog shows why one sanitizer isn’t enough. The AppleScript is a constant, and the title arrives as data:

set t to system attribute "ENTRY_TITLE"
display dialog "Reveal password \"" & t & "\" to your AI assistant?" -- ...

That stops code injection and leaves another problem. The dialog still renders the title, so newlines, bidi overrides, or a long payload could bury the warning and harvest a click on Allow. Data-not-code and safe-to-display are separate properties. The interpreter is called by absolute path as well, because a PATH-shadowed binary would receive the title in its environment.

The error path talks to the model

In the Go SDK, a non-nil error from a tool handler becomes isError content, so err.Error() goes to the model. Every handler here runs through a middleware that classifies the error, returns fixed text, and sends the reason to the audit log:

func wrapHandler[In, Out any](s *Server, name string,
	inner func(context.Context, In) (Out, error),
) mcp.ToolHandlerFor[In, Out] {
	return func(ctx context.Context, _ *mcp.CallToolRequest, args In) (
		result *mcp.CallToolResult, out Out, err error, // named: recover writes these
	) {
		defer func() {
			if r := recover(); r != nil {
				result, out, err = errGeneric(), *new(Out), nil
			}
		}()
		// deadline, session check, inner(), classify, audit
	}
}

The named returns matter. Without them, a recovered panic returns (nil, zero, nil), which the host reads as an empty success. The panic value is logged by type, and by content only if it’s a string or error, because %v on a struct could print a password.

What still had to leave the error text:

Scope details. A bypass error included the rule’s vault ID and mode, so a steered model could map the scope one call at a time. Those fields moved to a typed error for the audit log.
Subprocess output. fmt.Errorf("pbcopy: %w: %s", err, out) could carry clipboard content. Stdout now goes to /dev/null, and stderr never joins the error.
Identity. An “account changed” error named the username and backend. It can fire on every tool call, putting N copies of an email address into a transcript that may get exported or summarized. The final text names nobody.
Tamperable integers. A version-mismatch error quoted a schema number from a local file, whose author then controlled a value the model reads as authoritative.

The audit log is an output too. Its redactor is a key-name denylist over any, and it needed six fixes: nested maps, []map[string]any, pointers and typed maps, nested structs, Password/URL casing, and map keys in result metadata. A new field called token would still be logged. An allowlist of loggable fields changes that failure from a leaked secret to a missing log value.

The host spawns the server once and keeps it alive for the chat. An ADR said the session is read on every call, so a login as a different account gets refused. The implementation read it once at startup, and the error sentinels existed with no code path producing them. A second login with a chat open left the server acting as the old account, with no warning.

The check now runs in the middleware, before each handler. It came with a race: a check could pass, then a sibling refresh could swap the credentials before the handler used them. The check and the credential snapshot now happen in one critical section, and the handler receives that snapshot through its context.

What stays open

Natural-language injection is contained, not solved. The scope rules limit the blast radius.
The tag filter runs on the server after the backend returns the whole vault, so the binary is trusted. A server-issued scoped token is the real fix.
Auto-clear dies with the process, and clipboard managers keep their own history.

Takeaway

Treat the SDK as part of your attack surface: read what your schema really contains, and look at the bytes a tool result becomes. Then list every place a value can go, including errors, dialogs, and logs. Remove the sinks you can, as the clipboard tool did for secrets, and give each remaining sink the treatment its grammar calls for.

Use public SDK integration tests to find API coverage questions

Mon, 20 Apr 2026 00:00:00 +0000

A well-tested API can still leave you unsure where to investigate next. Compare its exposed operations with the vendor’s public SDK integration tests, then inspect what those tests actually assert. The result is a list of coverage questions you can investigate within an authorized scope.

The starting assumption in one review was that the system was well tested, so ordinary scenarios were unlikely to reveal much. Reading the SDK tests changed the next question: which behaviors did this particular suite demonstrate? That comparison produced candidate leads. It did not provide a complete coverage audit or confirm a vulnerability.

Build an operation inventory before searching tests

Start with the documented API operations available to the account or environment under review. Record the API version and the SDK release or commit beside that inventory. An operation introduced after the SDK release should not be counted as an unexplained omission.

Map each operation to SDK methods and then to integration tests. Follow wrappers and shared fixtures; a test name does not have to match an operation name. Keep unresolved mappings marked as unknown.

Text searches help locate candidates, but they do not measure runtime coverage. A matching method name might appear only in setup, a comment, or an assertion about a mock. A missing name might be hidden behind a helper or parameterized test. Check whether each test calls the service, what inputs it supplies, and which results it verifies.

Record assertions, not just test presence

This clean-room fixture is invented. Its operation names and test behavior do not describe any real service:

Operation	Evidence in the fictional public suite	Next coverage question
`create_item`	Creates an item and asserts that an ID exists	Does an invalid field produce the documented rejection?
`update_item`	Updates an item owned by the test account and reads it back	Does a different test account lack permission to update it?
`get_item`	No direct test located; helper usage unresolved	Does a shared fixture exercise retrieval and assert its result?

The last row stays unresolved until someone reads the helper. It would be premature to label it “untested.”

For each mapped test, note its credentials’ role without recording secrets, fixture ownership, expected failure behavior, and assertions. A successful request under one account says little about authorization under another. A negative test that merely catches any exception may pass on a network failure without demonstrating the intended denial.

Use precise notes such as “no assertion for this behavior found in the inspected public suite.” Vendors may have private service tests, separate security suites, or tests in another SDK. Public test omissions cannot prove those checks are absent.

Follow the data to its consumer

A coverage gap can justify a closer look at an input field if an API accepts and returns a string, which proves only acceptance and retrieval. Storage may legitimately preserve arbitrary text.

For a rendering-related hypothesis, maintain a small dataflow record: input field, stored representation, consuming component, output context, and observed handling. The consumer determines whether it treats the string safely. An API response alone cannot demonstrate unsafe rendering or a security impact.

Before any live follow-up, confirm the allowed scope, test accounts, and rate limits; use owned test data and the least disruptive check that answers the question.

If the consumer cannot be inspected or exercised within that scope, leave the hypothesis unresolved. Do not turn a stored value into a vulnerability claim to make the investigation sound complete.

Verify the map before choosing a lead

Have another pass through the fixtures and shared helpers, reconcile SDK and API versions, and separate source inspection from tests actually executed. For every proposed follow-up, write down the missing assertion and the observation that would settle it.

Pick one unresolved row in your own operation map and trace it through the test’s assertions before sending another request.

Api-Design on Lessons learned

A read with legal effect: listing ISDS messages counts as delivery

Setup

Why a read starts a deadline

The design

Copies of the production database

Other reads with side effects

Takeaway

Reference data published after the period: provisional values, then frozen observations

Make the status part of the value

“Immutable, keyed by the rate’s identity” cannot store a correction

Three Postgres gotchas from making it immutable

Two smaller rules

Takeaway

Before building a reference catalog, check whether the attribute reaches the computation

The attribute decides whether an event exists

Classify where the source idiom lives, and refuse to guess

What dropping the catalog removed

Caveat: some tax systems tax events that never happened

Takeaway

When the server must compute on confidential data, split the data by who may read it

List what the engine needs

Surrogate IDs: a keyed hash, scoped per user

Access and liability begin at the same instant

One password, auto-unlock, never transmitted: pick an aPAKE

The tenant boundary belongs in the database

Write down the floors

Takeaway

An MCP server has more outputs than tool results

Keep the secret off the transcript

Annotations are hints, so consent lives in the server

Authority lives in code

The input schema enforces less than it looks like

The fence, and the encoder after it

Each sink needs its own treatment

The error path talks to the model

A stdio child outlives the login

What stays open

Takeaway

Use public SDK integration tests to find API coverage questions

Build an operation inventory before searching tests

Record assertions, not just test presence

Follow the data to its consumer

Verify the map before choosing a lead