DEV Community: Iurii Rogulia

Why 'Two Weeks' Always Means Six — and How to Estimate Honestly

Iurii Rogulia — Wed, 22 Jul 2026 10:00:45 +0000

A developer says "two weeks." Six weeks later, it ships.

This happens so reliably that whole project-management methodologies exist mostly to manage around it. And the standard explanations are wrong, or at least lazy. "Developers are bad at estimating" is the comfortable one — it puts the fault in a personality trait, which means nobody has to change how they ask for numbers. It also doesn't survive contact with the evidence: the same developers estimate their commute, their grocery run, and their weekend renovation with the same optimism, and so does everyone else. The bias isn't a coding skill defect. It's structural.

So here is the question worth answering, because the answer is actionable: how to estimate software projects honestly — knowing in advance why the number bends, and giving a figure your business can actually plan against. I've been giving estimates, and being held to them, for a long time. I've been wrong in every direction. What follows is why "two weeks" becomes six, and the specific things I now do to give numbers that don't.

The iceberg under "the happy path"

When a developer pictures a feature and says "two weeks," they are almost always estimating the happy path. The part they can see. User clicks the button, the data is valid, the third-party API responds, the record saves, the page renders. That mental movie runs in a few seconds and feels like the whole job.

It is maybe a third of the job.

Below the waterline sits everything the demo never shows. Input validation. The empty state, the loading state, the error state — three screens nobody mentioned but all of which have to exist. Authentication and authorization on the new route. The database migration, and the rollback for when it goes wrong. Error handling for the API call that times out. Idempotency for the request the user double-clicks. The deploy. Code review, and the round of changes it produces. QA finding the thing you didn't, and the back-and-forth to fix it. Then the second bug QA finds because the first fix broke something adjacent.

None of that is in the two-week movie, and none of it is optional. A feature that handles only the happy path isn't 90% done; it's a prototype that happens to demo well. The gap between "works when I click through it once" and "works in production for strangers doing things I didn't predict" is where the other four weeks live.

This is the single biggest source of estimate error, and it's not arithmetic. It's a perception problem: the part of the work that's easy to imagine is a small and unrepresentative fraction of the part that has to be built.

Effort is not duration

The second structural error is quieter and just as expensive. A developer estimates effort — "this is about three days of work" — and the number gets recorded, and reported upward, as duration: three calendar days, done Thursday.

Those are not the same quantity, and the conversion factor is brutal. Three "ideal days" of focused work do not fit into three working days. They fit into a working week and a half, because the working day is not eight hours of the estimated activity. It's standups and the sync that ran long. It's the context-switch tax every time someone asks "quick question." It's reviewing someone else's PR because the team blocks if you don't. It's the interview you're on the panel for. It's lunch and the commute that lives in the calendar even when remote.

Industry-wide, the gap between ideal engineering hours and elapsed calendar time tends to land somewhere around half — you get roughly four to five productive hours of the estimated work into a nominal eight-hour day, and less on a meeting-heavy one. So an honest effort estimate of "five days of work" is, before anything goes wrong, closer to two calendar weeks of wall-clock time. The estimate wasn't wrong. The translation was missing.

When I give a number now, I'm explicit about which currency it's in. "Five days of effort" and "ready in two weeks" are different sentences, and conflating them is how a correct estimate produces a broken commitment.

The things you can't estimate because you haven't met them yet

The third reason is the honest one, and it's the reason no technique fully closes the gap: you cannot estimate what you haven't discovered yet.

The payment provider's documentation says the webhook fires once. In production it fires three times, out of order, and one of them arrives before the API call that triggered it has returned. The legacy table has a column called status that's authoritative in three places and ignored in a fourth, and nobody alive knows why. The "simple" integration turns out to rate-limit at a number the docs don't mention, discovered only under real load. The third-party API lies — returns 200 OK with an error nested in the body.

These are unknown-unknowns, and they are not a sign that the estimator was careless. They are genuinely invisible at estimation time. You find them by building, because building is the act of discovery. Every non-trivial feature contains some number of these, and the number is itself unknown. This is exactly why I won't quote a rescue engagement before I've spent time in the codebase — most of the cost lives in things the repository hasn't shown me yet, and I wrote up that whole audit method in technical due diligence before a rewrite.

You cannot estimate these away. But you can estimate their existence — you know they're coming, even if you don't know their shape — and that's what a range is for.

Scope creep and the "while you're in there" tax

Then there's the part that isn't a misperception at all — it's the work genuinely growing under your feet.

"While you're in there, can you also…" is the most expensive sentence in software, because each instance is individually reasonable and collectively unbounded. The feature that was scoped as one form acquires a second field, then validation on that field, then a special case for one customer, then an admin view to manage the special case. Nobody decided to triple the work. It accreted, one defensible request at a time.

The estimate was honest for the feature that was described. It was never updated for the feature that was actually built, because the growth happened in conversation, not in a ticket. An estimate is a statement about a fixed scope; the moment the scope moves, the estimate is stale and almost nobody re-states it.

Optimism, anchoring, and the number that bends

The last reason is psychological, and the cheapest to fix once you see it.

A stakeholder asks, "this is pretty simple, right?" — and the number bends toward the answer they're hoping for. Not through dishonesty. Through anchoring: the word "simple" is now in the room, and "six weeks" feels like a confrontation, so "a couple of weeks" comes out instead. The developer wants to be helpful and competent, and the social path of least resistance is the smaller number.

Optimism bias does the rest. We imagine the version of the project where nothing goes wrong, because that's the version that's easy to imagine — the failures are, by definition, the things we haven't pictured. So we estimate the best case and report it as the expected case.

The fix is not "be more pessimistic." Pessimism is just optimism's equally uncalibrated twin. The fix is structural, and it's the rest of this article.

How to estimate honestly: ranges, not single numbers

The single most important change: stop giving single numbers. A single number is a lie of precision. It claims a confidence the situation doesn't contain.

Give a range, and attach meaning to its ends. Not "two to six weeks" mumbled as a hedge — that's a single number with anxiety. A real range says what each end means:

Two weeks if the payment integration behaves the way the docs claim. Five if it fights us the way these integrations usually do. My honest expectation is three.

That sentence is more useful to a business than any single number, because it tells the recipient what they're betting on and where the risk sits. If they need it in two weeks, the conversation is now about the payment integration specifically — the actual source of uncertainty — instead of about whether the developer is sandbagging.

If your organization speaks the language, frame it as confidence intervals: a P50 (half the time it's done by here) and a P90 (nine times in ten it's done by here). The distance between P50 and P90 is the most honest thing in the estimate — it's a direct measurement of how much you don't yet know. A wide gap isn't incompetence. It's an accurate report of genuine uncertainty, and a narrow gap on a vague feature is the actual red flag.

Decompose until each piece is a day — and time-box what you can't

You cannot estimate a big thing. You can only estimate small things and add them up. So decompose the work until every piece is roughly a day or less. Pieces that small are things you've done shapes of before; your gut is calibrated on them. "Build the reporting feature" is a guess. "Add the date-range picker, write the aggregation query, build the empty state, add the CSV export, handle the no-data case" is five things you can each actually picture.

The decomposition does double duty: the pieces you can't break down are exactly the risky ones. If you can't decompose "integrate the partner's API" into day-sized chunks, that's not an estimate waiting to happen — it's a research spike. So don't estimate it. Time-box it: "I'll spend one day finding out how this API actually behaves, then I'll estimate the integration." A timebox is a commitment to spend a fixed amount of learning, not a guess at the cost of building. Conflating the two — estimating the build of a thing you don't yet understand — is where the worst overruns come from.

Separate the estimate from the commitment

This is the distinction most teams collapse, and collapsing it is why estimates feel like traps to everyone involved.

The estimate is your honest, technical best guess at the effort. It belongs to engineering. It's a probabilistic statement about uncertain work.

The commitment is the date the business promises to a customer, a board, a launch. It belongs to the business, and it should include a buffer for the risk the estimate just quantified.

These are different objects owned by different people. When a developer's raw estimate gets promised verbatim to a customer as a hard date, the buffer that should have absorbed the unknown-unknowns was never added — and the first surprise blows the commitment. The honest move is to make the seam visible: "My estimate is three weeks. Given what we don't know about the integration, I wouldn't promise the customer anything tighter than five." The buffer is stated, owned, and defensible — not smuggled in by secretly tripling the number, which is the dishonest version everyone resorts to when the seam is hidden.

slug="fractional-cto"
text="If your estimates keep arriving as single comforting numbers and landing as overruns, that's a process gap I fix from the inside — separating engineering's estimate from the business's commitment, and putting calibration in place."
/>

Track estimate vs actual, and trust history over your gut

Your gut is uncalibrated until you measure it. The single highest-leverage practice in estimation is also the most neglected: write down what you estimated, then write down what it actually took, and look at the two columns.

After a dozen rows, patterns appear that no amount of careful thinking would have surfaced. You discover you're consistently 2.2x light on anything touching authentication. You discover CRUD features land almost exactly on estimate, but anything involving a third-party API runs triple. That's reference-class forecasting, and it beats fresh judgment every time: "the last three features that looked like this took four weeks each" is worth more than any amount of reasoning about why this one will be different. It usually won't be.

This is also the cheapest competitive edge a team can build. A developer who knows their own historical multiplier gives numbers that come true. One who estimates from scratch every time keeps relearning the same lesson and keeps surprising everyone, including themselves.

The cone of uncertainty: a stale estimate is a lie

There's a well-documented shape to estimation error called the cone of uncertainty. At the very beginning of a project — the idea stage, before anything is built — estimates are reliably off by a factor of around four in either direction. Not because everyone is bad at it; because there's genuinely four-x worth of unknowns still undiscovered. The cone narrows only as you build and learn. By the time you're halfway through, the same estimate might be off by 25%. By the end, it's off by nothing, because it's done.

The operational consequence is blunt: an estimate has a shelf life, and re-estimating at milestones isn't admitting failure — it's the job. The number you gave at the idea stage was your honest best guess given near-total ignorance. Three weeks in, you know things you didn't, and the responsible move is to update the number out loud. A team that holds you to an idea-stage estimate after a month of discovery is asking you to honour a guess made by someone who knew less than you do now.

The opposite failure is just as common: giving the idea-stage estimate, then never revisiting it, and letting it quietly become a broken promise. A stale estimate that nobody updated is, functionally, a lie — not because anyone intended to deceive, but because it stopped describing reality and nobody said so.

Name your assumptions, or the number means nothing

Every estimate rests on assumptions, and an estimate detached from its assumptions is worthless — worse than worthless, because it looks authoritative while being unconditioned.

"Three weeks" means nothing on its own. "Three weeks, assuming the staging environment matches production, the partner's API does what its docs claim, and nobody changes the requirements mid-flight" is a real estimate — because now both sides can see exactly which load-bearing beliefs the number stands on, and watch for the moment one of them fails. When the partner's API turns out to behave differently, you don't have an unexplained overrun; you have a named assumption that broke, and a conversation that starts from "remember assumption two" instead of "why are you late."

I write the assumptions down, next to the number, every time. It's the difference between an estimate someone can interrogate and a number they can only resent when it's wrong.

The honest-CTO framing: who you can plan around

Here is the part that's really about hiring, not arithmetic.

A good engineer — or a good fractional CTO, or a good contractor — gives you a number you can plan around together with its uncertainty. They will tell you the range, name the risk, separate the estimate from the commitment, and update you when the cone narrows. That is not them being evasive or covering themselves. That is them being useful. The uncertainty is real whether or not they tell you about it; the only choice is whether you find out now or in week five. I've written more about what that role actually involves in what a fractional CTO does, and the same posture shows up in the rewrite-or-stabilise decision — the honest answer is the conditional one.

And here is the filter, stated plainly: the client who wants a single small number no matter what the work is — who hears the range and pushes for "just give me one number, just tell me two weeks" — is asking to be lied to. They will get their single small number from someone, because someone will always say what a client wants to hear. That someone will then be late, and the client will be surprised, and the cycle repeats with the next contractor. If you, as a buyer, punish honest ranges and reward confident single numbers, you are training your suppliers to deceive you, and you will get exactly the estimates you've selected for.

The engineer who refuses to compress an honest range into a comforting lie is the one worth keeping. The discomfort of hearing "three to five weeks, here's why" is the price of a number that comes true. I'd rather lose the engagement at the estimate than lose your trust in week six — and a contractor who feels the same way is the one you want holding your timeline.

Takeaways

"Two weeks" is the happy path. The iceberg below — validation, error states, auth, migrations, review, QA — is most of the real work and none of the mental movie. Estimate the iceberg, not the demo.
Effort is not duration. Ideal engineering hours convert to calendar time at roughly half; say which currency your number is in.
You can't estimate unknown-unknowns away — but you can estimate that they exist, which is what a range is for.
Give ranges with meaning attached, not single numbers. The distance between P50 and P90 is an honest measure of what you don't yet know.
Decompose to day-sized pieces. What won't decompose is a research spike — time-box the learning, then estimate the build.
Separate the estimate from the commitment. Engineering owns the honest guess; the business owns the buffered promise. Make the buffer visible, don't hide it in a secret multiplier.
Track estimate vs actual and trust history over gut. Your own multiplier on auth, or on third-party APIs, beats fresh reasoning every time.
Re-estimate at milestones. The cone of uncertainty narrows as you learn; a stale estimate nobody updated is functionally a lie.
Name your assumptions next to the number. An estimate without its assumptions can't be interrogated, only resented.
The honest filter: a contractor who gives you a range with its risk is the one to keep. The client who demands a single small number regardless of the work is training their suppliers to lie.

Resistant AI Alternative: PDF Tamper Detection API

Iurii Rogulia — Wed, 22 Jul 2026 10:00:35 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

If you are searching for a Resistant AI alternative, you are usually in one of two situations. Either you priced out Resistant AI and found that the enterprise contract, the managed onboarding, or the procurement timeline does not fit your stage, or you already use it and want a lighter, self-serve building block for one specific part of your pipeline. This article is honest about both, and about where Resistant AI is the better choice.

HTPBE is not a drop-in replacement for everything Resistant AI does. Resistant AI is a broad financial-crime platform. HTPBE solves one narrower piece — the structural integrity of a PDF’s bytes — and it solves it as a self-serve API you can wire into any workflow, today.

What Resistant AI Does — and Who It Is Built For

Resistant AI is a document-forensics and financial-crime company. Its document product uses machine learning trained on a very large document corpus to detect manipulation across many document types — bank statements, utility bills, tax forms, certificates of incorporation, invoices, and more. It analyses both how a document is built and signals that point to content-level manipulation, and it markets detection of AI-generated and synthetic documents alongside classic edits.

Around that document layer, Resistant AI has built a broader platform: a transaction-monitoring product aimed at money-laundering and payment fraud, and an enterprise delivery model. New customers are typically assigned a customer success manager who handles discovery, technical setup, training, and interpretation of early results. The buyer is a bank, payment processor, insurer, or large fintech with a dedicated fraud-operations team and the budget for a managed, sales-led engagement.

That is a coherent, well-built platform for that buyer. If you process tens of thousands of documents a month, need content-level and AI-generated forgery detection plus transaction monitoring in one managed system, and have a fraud team to run it, Resistant AI is squarely in its lane — and HTPBE is not trying to take that lane.

Why People Look for a Resistant AI Alternative

The search term “Resistant AI alternative” is almost always driven by one of these reasons:

You only need the structural-PDF piece. You already have identity, income, and transaction tooling. You want tampered-PDF detection without buying an entire financial-crime platform on top.
You cannot justify enterprise procurement yet. You are a 30-to-150-person lender, insurer, or platform, and a multi-month sales cycle with a managed-onboarding contract is the wrong shape for your stage.
You are a developer who wants an API, not a managed deployment. You are building the product, and you need a call your own code branches on — not a platform a success manager onboards you into.
You want to prove the signal before you commit budget. You want to run a few hundred documents and see the result before you sign anything.

If any of those describe you, a focused, self-serve PDF tamper detection API is a better-shaped tool than an enterprise platform. That is the gap HTPBE fills.

What HTPBE Is

HTPBE is a PDF tamper detection API. You send it the URL of a PDF, and it runs a structural forensic analysis of the file’s bytes — the document’s internal revision history, the software fingerprints left by whatever generated and last touched it, the consistency of internal timestamps, and the integrity of any digital signature. It returns a verdict and the named markers behind it:

intact — no post-creation modification was found in the file structure.
modified — the file carries structural evidence of being changed after it was first created.
inconclusive — the file was produced by consumer software (a word processor, an export-to-PDF tool, a phone scan), so its structural integrity cannot be established the way it can for a document generated by an institution’s own systems.

There is no numeric “risk score.” You get a verdict plus the specific modification markers that produced it, so your own logic decides what to do next.

To be clear about category: HTPBE is tamper detection, not identity verification. It does not run KYC, biometric ID matching, credit checks, or income verification against a bank or payroll provider, and it does not do transaction monitoring. It does not read the numbers inside the document and tell you whether they are true. It tells you whether the file itself was structurally altered after it left its source. This is a separate question from KYC and identity verification, and it complements them: it covers a layer that identity tools do not check. For the full picture of how these layers fit together, see KYC versus document forensics.

The Comparison That Matters: Scope, Shape, and How You Buy

For a developer or a risk lead evaluating options, the difference is less about a feature checklist and more about scope, the shape of the tool, and how you buy it.

Factor	Resistant AI	HTPBE
Primary form factor	Managed enterprise platform	Developer-first REST API
Detection scope	Structural + content-level + AI-generated + transaction monitoring	Structural PDF tamper detection only
Delivery model	Sales-led, customer-success onboarding	Self-serve — instant, 5 welcome credits
Public pricing	Sales-quoted	Yes — published, self-serve + pay-per-check
Typical buyer	Banks, processors, large fintechs	Lenders, insurers, HR & legal tech, AP teams of any size
Time to first result	Onboarding into the platform	Minutes — first real call after signup

The honest read of this table: if you need a broad, managed financial-crime platform with content-level and AI-generated detection plus transaction monitoring, those rows favour Resistant AI. If you want the structural-PDF layer as a self-serve building block you integrate yourself, with transparent pricing and no onboarding gate, they favour HTPBE.

Different Scope, Stated Plainly

This is the most important section to read before choosing, because the two tools do not overlap as much as a keyword match suggests.

Resistant AI’s document forensics is broad and content-aware. It is designed to reason about manipulation at the content level — what the document shows — and to flag AI-generated and synthetic documents, on top of structural signals. Combined with its transaction product, it spans a large slice of the financial-crime problem.

HTPBE is narrow and structural by design. It answers exactly one question: was this file modified after it was created? It deliberately does not attempt content-truth analysis, AI-generated-document detection, transaction monitoring, KYC/identity, or born-synthetic forgery detection. Doing one layer well, and being honest about its edges, is the point — not a limitation we are working around.

So this is not “cheaper version of the same thing.” It is a different, smaller tool for a different job. The question is not which is better in the abstract; it is which layer you need right now, and how fast and cheaply you need it.

Cross-Vertical: The Same Attack, Outside Banking

The reason HTPBE is not tuned to one industry is that the underlying attack is not industry-specific. A bank statement edited in a PDF editor to change a balance is the same structural event whether it lands on:

A loan application — see bank statement fraud in personal lending and the KYC blind spot it slips through.
An insurance claim — an altered claim or invoice that passes manual review.
An HR onboarding flow — a falsified payslip submitted to a recruiter.
An accounts-payable queue — a tampered invoice before payment.
A legal matter — an exhibit or contract edited after signing.

The same HTPBE API call covers all of them, because the structural analysis does not care what the document claims to be — it reads the file format.

The `inconclusive` Verdict — A Routing Signal, Not a Dead End

When HTPBE returns inconclusive, it is not saying “the tool couldn’t decide.” It is making a specific, useful statement: this file was produced by consumer software, so it was not generated by the kind of institutional system that issues an authoritative bank statement, payslip, or tax form.

For a lending or insurance intake, that is high-value. If an applicant uploads something that claims to be a bank statement but the file was built in a word processor or a generic export-to-PDF tool, inconclusive is the cue to route it to manual review or to ask for the statement through a direct bank connection. You are not rejecting anyone — you are routing on a clear signal instead of taking a consumer-software document at face value.

The mistake teams make on day one is treating inconclusive as a pass. For a document that claims institutional origin, it deserves the same caution as modified: do not auto-accept it.

Integration: One Call, Your Workflow

HTPBE is an API, so integration is a single request. Submit a PDF for analysis:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-storage.com/applicant-statement.pdf"}'

That returns a top-level id. Retrieve the full result with GET /result/{id} and branch on the verdict in your own intake logic — the pattern is identical whether the document is a loan file, a claim, or a new-hire payroll form:

import requests

def screen_document(document_url: str, api_key: str) -> dict:
    """Structural tamper check on an applicant-submitted PDF."""
    analyze = requests.post(
        "https://api.htpbe.tech/v1/analyze",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"url": document_url},
    )
    uid = analyze.json()["id"]

    result = requests.get(
        f"https://api.htpbe.tech/v1/result/{uid}",
        headers={"Authorization": f"Bearer {api_key}"},
    ).json()

    verdict = result["status"]

    if verdict == "modified":
        # Structural evidence of post-creation editing — route to fraud review
        return {"action": "review", "markers": result["modification_markers"]}
    if verdict == "inconclusive":
        # Consumer-software origin — ask for a bank-connected statement
        return {"action": "re_request", "reason": "consumer_software_origin"}
    return {"action": "proceed"}

You submit with POST /analyze, retrieve with GET /result/{id}, and three branches cover the workflow. The result carries the verdict in status and the named markers in modification_markers — there is no managed platform to adopt and no migration. It is a layer inside the product you already run.

When Resistant AI Is the Better Choice

Building trust means saying where the other tool wins. Choose Resistant AI over HTPBE when:

You need content-level and AI-generated forgery detection. If your threat is documents fabricated from scratch or generated by AI — where there is no post-creation edit to find — you need a content-aware platform. That is Resistant AI’s lane, not HTPBE’s.
You need transaction monitoring in the same system. HTPBE does not touch payments or transaction behaviour. Resistant AI bundles a transaction product; HTPBE does not.
You want a managed, enterprise relationship. At very high volumes, with SLAs, dedicated success management, and broad document-type coverage, an enterprise platform offers capabilities a self-serve API does not.
You are a bank or large processor with a fraud-operations team built to run exactly this kind of managed system.

When HTPBE Is the Better Choice

Choose HTPBE when:

You want the structural-fraud layer as an API you control, wired into your own intake instead of a managed platform.
You operate across several verticals — lending, insurance, HR, AP, legal — and need one consistent structural check for all of them.
You want self-serve, transparent pricing with no onboarding gate — sign up, get 5 welcome credits, and make a real call within minutes.
You want to prove the signal before you commit budget. Run a few hundred documents on a low monthly plan or pay-per-check, measure how many come back modified or inconclusive, and decide from data rather than a sales deck.

These are not mutually exclusive. A common, practical path is to deploy the structural layer first — cheaply, this week — measure how much modification it surfaces in your real pipeline, and use that data to decide whether you also need a broader content-aware platform later. The structural layer sits alongside your KYC and transaction stack, not in place of it.

What HTPBE Cannot Catch

No structural tool is complete, and a comparison that hides the gaps is not honest.

Documents fabricated from scratch. If someone builds a fake bank statement in design software with plausible internal details and never edits it afterwards, there may be no post-creation modification to find — the file can read as intact. Detecting whether a from-scratch document’s contents are truthful is a different problem, and one HTPBE does not solve. See forensics without the original file for why this gap exists. This is exactly the content-level and AI-generated territory where a platform like Resistant AI is built to operate.
Content-level lies in an unedited file. If an applicant submits a real, unmodified statement from an account they control that simply does not reflect their true finances, structural analysis correctly returns intact — because the file was not modified. Catching that needs income source-of-truth checks, which structural analysis does not provide.
Image-only PDFs with no structural signal. A photo or scan wrapped into a PDF may lack the internal structure the analysis relies on; those typically land as inconclusive rather than a confident verdict.

These limits are exactly why HTPBE positions itself as one layer — the structural-PDF layer — rather than an end-to-end fraud platform. It catches the most common and fastest-growing attack: post-creation modification of a legitimate document. If you also need content-level forgery detection, AI-generated-document detection, and transaction monitoring in one managed box, Resistant AI is built for that. If you need the structural layer as a self-serve, cross-vertical API you integrate yourself, that is what HTPBE is for. The full product-side breakdown lives on the Resistant AI alternative page.

Snappt Alternative: A Self-Serve PDF Fraud Detection API for Rental & Beyond

Iurii Rogulia — Tue, 21 Jul 2026 10:00:36 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

If you are searching for a Snappt alternative, you are usually in one of two situations. Either you run a property-management or leasing operation that wants document fraud detection without committing to a full screening platform, or you are building something — a tenant-screening product, a lending pipeline, an HR onboarding flow — and you want the structural PDF fraud layer that Snappt does well, but as an API you control. This article is written for the second case, and it is honest about the first.

HTPBE is not a drop-in replacement for everything Snappt does. Snappt is a multifamily-rental platform with a leasing-team dashboard, income verification, identity checks, and human review. HTPBE solves one narrower piece of that picture — structural PDF tamper detection — and it solves it as a self-serve API you can wire into any workflow in any vertical, today.

What Snappt Does — and Who It Is Built For

Snappt is a fraud-detection and income-verification product built for the property-management and multifamily-rental industry. Its core job is to screen rental applications for falsified financial documents — typically pay stubs and bank statements that applicants edit to look like they earn more than they do.

Around that core, Snappt has assembled a leasing-focused platform: document fraud detection (analysing metadata and running authenticity checks), income verification through connected payroll and bank sources, identity and rental-history checks, and a workflow that pairs automated detection with human review and a dashboard for leasing teams. It sells to property managers and leasing operators, and it is designed to plug into the leasing process rather than sit behind a developer’s API.

That is a coherent, well-built product for its buyer. If you are a regional property-management company that wants a turnkey applicant-screening system with a UI your leasing agents log into, Snappt is squarely in its lane and HTPBE is not trying to take that lane.

Why People Look for a Snappt Alternative

The search term “Snappt alternative” is almost always driven by one of these reasons:

You only need the document-fraud piece. You already have your own screening flow, your own identity provider, or your own income data — and you want the tampered-PDF detection without buying an entire leasing platform on top.
You are not in rental at all. The same falsified bank statement that shows up on a rental application also shows up on a loan application, an insurance claim, an expense report, and a new-hire payroll form. A rental-only platform is the wrong shape for a lending or HR workflow.
You are a developer who wants an API, not a dashboard. You are building the product, and you need a programmatic call that returns a result your own code can branch on — not a portal a human logs into.
You want to start small and prove value before committing. You want to run a few hundred documents and see the signal before you sign anything.

If any of those describe you, a structural PDF tamper detection API is a better-shaped tool than a rental screening platform. That is the gap HTPBE fills.

What HTPBE Is

intact — no post-creation modification was found in the file structure.
modified — the file carries structural evidence of being changed after it was first created.
inconclusive — the file was produced by consumer software (a word processor, an export-to-PDF tool, a phone scan), so its structural integrity cannot be established the way it can for a document generated by an institution’s own systems.

There is no numeric “risk score.” You get a verdict plus the specific modification markers that produced it, so your own logic decides what to do next.

To be clear about category: HTPBE is tamper detection, not identity verification. It does not do tenant identity checks, credit checks, biometric ID matching, or income verification against a bank or payroll provider. It does not read the numbers inside the document and tell you whether they are true. It tells you whether the file itself was structurally altered after it left its source. That is a different and complementary question from the KYC/identity category — and an important layer that identity tools do not cover.

The Comparison That Matters: Shape and Buying Experience

For a developer or a risk lead evaluating options, the difference is less about a feature checklist and more about the shape of the tool and how you buy it.

Factor	Snappt	HTPBE
Primary form factor	Leasing platform + dashboard	Developer-first REST API
Industry focus	Multifamily / rental	Cross-vertical (rental, lending, insurance, HR, AP, legal)
Scope	Doc fraud + income + identity + human review	Structural PDF tamper detection only
Self-serve signup	Built for property-management onboarding	Yes — instant, 5 welcome credits
Public pricing	Per-unit, rental-oriented	Yes — published, self-serve + pay-per-check
Human review service	Yes	No — automated API only
Time to first result	Onboarding into the platform	Minutes — first real call after signup

The honest read of this table: if you want a staffed, turnkey leasing product, those rows favour Snappt. If you want a structural-fraud building block you integrate yourself, across more than one vertical, with transparent pricing and no onboarding gate, they favour HTPBE.

Cross-Vertical: The Same Fraud, Outside Rental

The reason HTPBE is not rental-only is that the underlying attack is not rental-only. A bank statement edited in a PDF editor to change a balance is the same structural event whether it lands on:

A rental application — see how tenants falsify bank statements and how tenant-screening platforms add a structural layer.
A loan application — bank statement fraud in personal lending and the KYC blind spot it slips through.
An HR onboarding flow — falsified payslips submitted to recruiters.
An insurance claim — altered claim PDFs that pass manual review.
An accounts-payable queue — tampered invoices before payment.

A rental-only platform gives you one of these. The same HTPBE API call gives you all of them, because the structural analysis does not care what the document claims to be — it reads the file format.

The `inconclusive` Verdict — A Routing Signal, Not a Dead End

For a rental or lending intake, that is high-value. If your applicant uploads something that claims to be a bank statement but the file was built in a word processor or a generic export-to-PDF tool, inconclusive is the cue to route it to manual review or to ask the applicant to provide the statement through a direct bank connection. You are not rejecting anyone — you are routing on a clear signal instead of taking a consumer-software document at face value.

Integration: One Call, Your Workflow

HTPBE is an API, so integration is a single request. Submit a PDF for analysis:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-storage.com/applicant-statement.pdf"}'

Then branch on the verdict in your own intake logic — this pattern is identical whether the document is a rental application, a loan file, or a new-hire payroll form:

import requests

def screen_document(document_url: str, api_key: str) -> dict:
    """Structural fraud check on an applicant-submitted PDF."""
    analyze = requests.post(
        "https://api.htpbe.tech/v1/analyze",
        headers={"Authorization": f"Bearer {api_key}"},
        json={"url": document_url},
    )
    uid = analyze.json()["id"]

    result = requests.get(
        f"https://api.htpbe.tech/v1/result/{uid}",
        headers={"Authorization": f"Bearer {api_key}"},
    ).json()

    verdict = result["status"]

    if verdict == "modified":
        return {"action": "review", "markers": result["modification_markers"]}
    if verdict == "inconclusive":
        # Consumer-software origin — ask for a bank-connected statement
        return {"action": "re_request", "reason": "consumer_software_origin"}
    return {"action": "proceed"}

You submit with POST /analyze, retrieve with GET /result/{id}, and three branches cover the workflow. There is no leasing UI to adopt and no platform to migrate onto — it is a layer inside the product you already run.

When Snappt Is the Better Choice

Building trust means saying where the other tool wins. Choose Snappt over HTPBE when:

You want a turnkey leasing product. If your buyers are leasing agents who need a dashboard to log into, not developers who write code, a platform is the right form factor and an API is not.
You need income and identity verification in the same product. HTPBE does not connect to payroll or banks to verify income, and it does not run identity or rental-history checks. Snappt bundles those; HTPBE does not.
You want a human-review service. Snappt pairs automated detection with human experts. HTPBE is automated only — it returns a verdict, and your team (or your own reviewers) decides what to do with it.
You are exclusively in multifamily rental and want a product purpose-built for that workflow. Snappt is tuned for exactly that buyer.

When HTPBE Is the Better Choice

Choose HTPBE when:

You want the structural-fraud layer as an API you control, wired into your own intake instead of a separate portal.
You operate outside rental, or across several verticals, and need one consistent fraud check for lending, insurance, HR, and AP documents.
You want self-serve, transparent pricing with no onboarding gate — sign up, get 5 welcome credits, and make a real call within minutes.
You want to prove the signal before you commit budget. Run a few hundred documents on a low monthly plan or pay-per-check, measure how many come back modified or inconclusive, and decide from data.

What HTPBE Cannot Catch

No structural tool is complete, and a comparison that hides the gaps is not honest.

Documents fabricated from scratch. If someone builds a fake bank statement in design software with plausible internal details and never edits it afterwards, there may be no post-creation modification to find — the file can read as intact. Detecting whether a from-scratch document’s contents are truthful is a different problem (content and income verification), and one HTPBE does not solve. See forensics without the original file for why this gap exists.
Content-level lies in an unedited file. If an applicant submits a real, unmodified statement from an account they control that simply does not reflect their true finances, structural analysis correctly returns intact — because the file was not modified. Catching that needs income source-of-truth checks, which is Snappt’s lane, not HTPBE’s.
Image-only PDFs with no structural signal. A photo or scan wrapped into a PDF may lack the internal structure the analysis relies on; those typically land as inconclusive rather than a confident verdict.

These limits are exactly why HTPBE positions itself as one layer — the structural-PDF layer — rather than an end-to-end fraud platform. It catches the most common and fastest-growing attack: post-creation modification of a legitimate document. If you also need income verification, identity proofing, and a leasing workflow in one box, Snappt is built for that. If you need the structural layer as a self-serve, cross-vertical API you integrate yourself, that is what HTPBE is for. The full product-side breakdown lives on the Snappt alternative page.

PDF Tamper Detection API for Java: Spring Boot Integration Guide

Iurii Rogulia — Mon, 20 Jul 2026 11:00:37 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

PDF fraud is a backend problem, and in enterprise fintech, lending, banking, and insurance the backend runs on the JVM. A Spring Boot service ingests an uploaded bank statement, a payslip, or a claim packet, writes a row, and hands the document to underwriting — and by the time your @RestController has returned 201, the document’s claims have already propagated into your business logic. Your KYC provider verified that the applicant is a real person with a valid identity. It said nothing about whether the PDF they uploaded was edited after the bank generated it. That structural-tampering layer is invisible to identity verification, and the right place to catch it is at ingress: before your service trusts the file, not after.

This guide walks through integrating the PDF tamper detection API into a Spring Boot application — from the first curl command to an idiomatic @Service built on Spring’s RestClient, with a typed record DTO, @ConfigurationProperties for the API key, error handling that distinguishes a configuration failure from a transient one, and a small bank-statement gate that decides accept / reject / review. The patterns target Spring Boot 3.2+ / Spring Framework 6.1+ (where RestClient is stable); a WebClient variant is included for reactive stacks. Treat the code as a reference architecture — it runs the real request flow against the documented error codes, but you should adapt and harden it for your own traffic profile and threat model. (If you want the conceptual overview first, start with How to Detect PDF Tampering Programmatically. Integrating from another stack? See the Go, Node.js, Python, and Laravel / PHP guides.)

TL;DR

Two API calls, three verdicts: POST /analyze returns a check id, GET /result/{id} returns the flat verdict object whose status is one of intact, modified, or inconclusive.
The minimum integration is a RestClient and two method calls. No extra dependency beyond spring-boot-starter-web.
Production shape: a typed record DTO, @ConfigurationProperties for the key, a custom ResponseErrorHandler that maps status codes to a typed exception, and Spring Retry that backs off on 5xx and 429 only.
A DocumentGate that maps the three verdicts to an ACCEPT / REJECT / REVIEW decision for documents that claim institutional origin.
This is structural PDF tamper and forgery detection — not KYC, not OCR, not AI-text detection. It complements an identity stack; it does not replace one.

Prerequisites

Java 17+ (records, sealed types, switch expressions) — Java 21 if you want virtual threads for batch fan-out
Spring Boot 3.2+ (RestClient is stable from 3.2; the WebClient path works on any 3.x)
spring-boot-starter-web on the classpath
An HTPBE API key (Dashboard → copy key)

Step 1: Test the API with curl

Before writing any Java, confirm your key works. The API uses a two-step flow: POST /analyze submits a PDF URL and returns a check id, then GET /result/{id} retrieves the full verdict. (For a language-agnostic overview of what the API detects, see how PDF tamper detection works.)

Step 1a — submit for analysis:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.htpbe.tech/v1/test/clean.pdf"}'

You will receive: {"id": "00000000-0000-4000-8000-000000000001"}

Step 1b — retrieve the result:

curl https://api.htpbe.tech/v1/result/YOUR_CHECK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

You will receive a flat JSON object with "status": "intact" and the full set of analysis fields:

{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "intact",
  "origin": { "type": "institutional", "software": null },
  "creator": "Adobe Acrobat Pro DC",
  "producer": "Adobe PDF Library 15.0",
  "modification_confidence": "none",
  "has_incremental_updates": false,
  "update_chain_length": 1,
  "signature_removed": false,
  "modifications_after_signature": false,
  "modification_markers": []
}

The same shape comes back for modified and inconclusive verdicts — only the values change. Two fields are conditional: status_reason appears only when status is inconclusive, and outdated_warning only when the check ran against an older algorithm version.

The URL https://api.htpbe.tech/v1/test/clean.pdf is a test mock — it returns a predictable response without consuming quota. Test keys (prefix htpbe_test_) accept only these mock URLs; live keys (prefix htpbe_live_) accept any public PDF URL.

Step 2: Configuration Properties

Keep the key and base URL out of code. Bind them with @ConfigurationProperties so they are typed, validated at startup, and overridable per environment.

package com.example.htpbe;

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
import jakarta.validation.constraints.NotBlank;
import java.time.Duration;

@Validated
@ConfigurationProperties(prefix = "htpbe")
public record HtpbeProperties(
        @NotBlank String apiKey,
        String baseUrl,
        Duration timeout,
        int maxRetries) {

    public HtpbeProperties {
        // Defaults applied to the compact constructor so a partial
        // configuration block still produces a usable instance.
        if (baseUrl == null || baseUrl.isBlank()) {
            baseUrl = "https://api.htpbe.tech/v1";
        }
        if (timeout == null) {
            timeout = Duration.ofSeconds(35);
        }
        if (maxRetries <= 0) {
            maxRetries = 3;
        }
        // Tolerate a trailing slash so either form of the base URL works.
        while (baseUrl.endsWith("/")) {
            baseUrl = baseUrl.substring(0, baseUrl.length() - 1);
        }
    }
}

Enable binding and validation on your configuration class:

@Configuration
@EnableConfigurationProperties(HtpbeProperties.class)
class HtpbeConfig { }

And supply the values in application.yml — the key resolves from an environment variable so it never lands in source control:

htpbe:
  api-key: ${HTPBE_API_KEY}
  base-url: https://api.htpbe.tech/v1
  timeout: 35s
  max-retries: 3

The @NotBlank on apiKey means the application context fails to start if HTPBE_API_KEY is unset — a misconfigured deployment is caught at boot, not on the first document that arrives at 2 a.m.

Step 3: The Result DTO

Model the GET /result/{id} response as a Java record. Jackson maps snake_case JSON to the record components when you enable @JsonNaming(SnakeCaseStrategy.class) (or set spring.jackson.property-naming-strategy: SNAKE_CASE globally). Configure your ObjectMapper to ignore unknown properties so a newly added API field never breaks deserialization. Nullable fields are reference types so “absent” stays distinguishable from a genuine zero.

package com.example.htpbe;

import com.fasterxml.jackson.databind.PropertyNamingStrategies.SnakeCaseStrategy;
import com.fasterxml.jackson.databind.annotation.JsonNaming;
import java.util.List;

@JsonNaming(SnakeCaseStrategy.class)
public record AnalysisResult(
        String id,
        String filename,
        Long fileSize,
        Integer pageCount,

        String algorithmVersion,
        String currentAlgorithmVersion,
        String outdatedWarning,        // present only on an outdated check

        // Primary verdict: "intact" | "modified" | "inconclusive"
        String status,
        // Present only when status == "inconclusive":
        // "consumer_software_origin" | "online_editor_origin" |
        // "scanned_document" | "unverifiable_metadata"
        String statusReason,

        Origin origin,

        // "certain" | "high" | "none" | null
        String modificationConfidence,

        String creator,
        String producer,
        Long creationDate,             // Unix seconds
        Long modificationDate,         // Unix seconds
        String pdfVersion,

        Boolean dateSequenceValid,
        Integer metadataCompletenessScore,

        Integer xrefCount,
        Boolean hasIncrementalUpdates,
        Integer updateChainLength,

        Boolean hasDigitalSignature,
        Integer signatureCount,
        Boolean signatureRemoved,
        Boolean modificationsAfterSignature,

        Integer objectCount,
        Boolean hasJavascript,
        Boolean hasEmbeddedFiles,

        // Stable HTPBE_* marker ids, e.g. ["HTPBE_SIGNATURE_REMOVED"].
        // Empty when status is "intact" or "inconclusive".
        List<String> modificationMarkers) {

    @JsonNaming(SnakeCaseStrategy.class)
    public record Origin(
            // "consumer_software" | "institutional" | "unknown" |
            // "online_editor" | "scanned"
            String type,
            String software) {
    }

    public boolean isIntact() {
        return "intact".equals(status);
    }

    public boolean isModified() {
        return "modified".equals(status);
    }

    public boolean isInconclusive() {
        return "inconclusive".equals(status);
    }
}

Two fields deserve a closer look. statusReason is populated only when status is inconclusive, and it carries one of several values — consumer_software_origin, online_editor_origin, scanned_document, and a few more. The difference matters: a scanned document is benign for a user-submitted handwritten form, but a consumer_software_origin on something that claims to be a payslip is the kind of origin you would not expect from a real payroll system — that class covers both consumer apps and freely available HTML-to-PDF renderers, so it is a strong signal to route for review. Branch on the specific reason, not just on the top-level inconclusive.

modificationMarkers returns stable, machine-readable ids prefixed HTPBE_ — for example HTPBE_SIGNATURE_REMOVED, HTPBE_DATES_DISAGREE, HTPBE_POST_SIGNATURE_EDIT. Branch your integration logic on the id; render the human-readable label from the dictionary published on htpbe.tech/how. These ids are part of the public contract and never change once shipped. The API does not return a numeric risk score — the verdict plus the named markers are the whole signal, by design, so there is no threshold to tune on your side.

A short enum keeps the rest of your codebase from comparing against bare string literals:

public enum Verdict {
    INTACT, MODIFIED, INCONCLUSIVE;

    public static Verdict of(String status) {
        return switch (status) {
            case "intact" -> INTACT;
            case "modified" -> MODIFIED;
            case "inconclusive" -> INCONCLUSIVE;
            default -> throw new IllegalArgumentException("unknown status: " + status);
        };
    }
}

Step 4: A Typed Exception

A 401 means your key is wrong; a 402 means the credit pool is dry; a 500 is transient. Both the retry layer and your business logic need to branch on the status code, so wrap every non-2xx response in a typed exception that carries it.

package com.example.htpbe;

public class HtpbeApiException extends RuntimeException {

    private final int statusCode;
    private final String code;          // machine-readable code from the JSON body
    private final Integer retryAfterSeconds; // parsed from Retry-After on 429; null if absent

    public HtpbeApiException(int statusCode, String code, String message,
                             Integer retryAfterSeconds) {
        super("htpbe: %d %s: %s".formatted(statusCode, code, message));
        this.statusCode = statusCode;
        this.code = code;
        this.retryAfterSeconds = retryAfterSeconds;
    }

    public int statusCode() { return statusCode; }
    public String code() { return code; }
    public Integer retryAfterSeconds() { return retryAfterSeconds; }

    /**
     * Only 5xx and 429 are transient. Every other 4xx is permanent —
     * retrying it burns latency and, for 402, can never succeed until
     * the account is topped up.
     */
    public boolean retryable() {
        return statusCode >= 500 || statusCode == 429;
    }
}

Step 5: The RestClient Service

Here is the complete @Service on RestClient. A custom ResponseErrorHandler converts every non-2xx response into an HtpbeApiException, parsing the JSON error body and the Retry-After header in one place.

package com.example.htpbe;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.client.ClientHttpResponse;
import org.springframework.stereotype.Service;
import org.springframework.web.client.ResponseErrorHandler;
import org.springframework.web.client.RestClient;

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.time.format.DateTimeParseException;
import java.time.Instant;
import java.util.List;
import java.util.Map;

@Service
public class HtpbeClient {

    private final RestClient restClient;
    private final ObjectMapper objectMapper;

    public HtpbeClient(HtpbeProperties props,
                       RestClient.Builder builder,
                       ObjectMapper objectMapper) {
        this.objectMapper = objectMapper;
        this.restClient = builder
                .baseUrl(props.baseUrl())
                .defaultHeader("Authorization", "Bearer " + props.apiKey())
                .defaultHeader("Accept", "application/json")
                .defaultStatusHandler(new HtpbeErrorHandler(objectMapper))
                .build();
    }

    /**
     * Submits a PDF URL and returns the full verdict. The two steps are kept
     * separate on purpose: POST /analyze is the billable, job-creating call,
     * GET /result/{id} is a free read. Retry policy (Step 6) wraps each step
     * independently so a transient read failure never re-submits — and never
     * re-bills — a fresh analysis.
     *
     * @param originalFilename optional; pass it so the result's `filename`
     *                         shows a human-readable name, not a storage key.
     */
    public AnalysisResult verify(String pdfUrl, String originalFilename) {
        String id = submitAnalysis(pdfUrl, originalFilename);
        return getResult(id);
    }

    String submitAnalysis(String pdfUrl, String originalFilename) {
        var body = (originalFilename == null)
                ? Map.of("url", pdfUrl)
                : Map.of("url", pdfUrl, "original_filename", originalFilename);

        JsonNode node = restClient.post()
                .uri("/analyze")
                .body(body)
                .retrieve()
                .body(JsonNode.class);

        if (node == null || node.get("id") == null) {
            throw new HtpbeApiException(502, "BAD_RESPONSE",
                    "analyze response missing id", null);
        }
        return node.get("id").asText();
    }

    AnalysisResult getResult(String id) {
        return restClient.get()
                .uri("/result/{id}", id)
                .retrieve()
                .body(AnalysisResult.class);
    }

    /** Maps every non-2xx response to a typed HtpbeApiException. */
    static final class HtpbeErrorHandler implements ResponseErrorHandler {

        private final ObjectMapper mapper;

        HtpbeErrorHandler(ObjectMapper mapper) {
            this.mapper = mapper;
        }

        @Override
        public boolean hasError(ClientHttpResponse response) throws IOException {
            return response.getStatusCode().isError();
        }

        @Override
        public void handleError(ClientHttpResponse response) throws IOException {
            HttpStatusCode status = response.getStatusCode();
            String raw = new String(response.getBody().readAllBytes(), StandardCharsets.UTF_8);

            String code = "UNKNOWN";
            String message = status.toString();
            try {
                JsonNode body = mapper.readTree(raw);
                if (body.hasNonNull("code")) code = body.get("code").asText();
                if (body.hasNonNull("error")) message = body.get("error").asText();
            } catch (Exception ignore) {
                // body was not JSON — keep the status-derived defaults
            }

            Integer retryAfter = null;
            int sc = status.value();
            switch (sc) {
                case 401 -> message = "invalid API key — check HTPBE_API_KEY";
                case 402 -> message = "no credits available for this key — top up or subscribe";
                case 403 -> message = "test key sent to a live URL, or vice versa";
                case 413 -> message = "PDF exceeds the 10 MB size limit";
                case 422 -> message = "the URL did not return a valid PDF file";
                case 429 -> retryAfter = parseRetryAfter(
                        response.getHeaders().getFirst("Retry-After"));
                default -> { /* keep parsed message */ }
            }
            throw new HtpbeApiException(sc, code, message, retryAfter);
        }

        /**
         * Handles both the delay-seconds form ("30") and the HTTP-date form,
         * clamped to [1, 600]. Returns null when absent or unparseable so the
         * caller can fall back to its own backoff.
         */
        private static Integer parseRetryAfter(String header) {
            if (header == null || header.isBlank()) return null;
            try {
                return clamp(Integer.parseInt(header.trim()));
            } catch (NumberFormatException ignore) {
                // not a plain number — try HTTP-date
            }
            try {
                ZonedDateTime when = ZonedDateTime.parse(
                        header, DateTimeFormatter.RFC_1123_DATE_TIME);
                long secs = when.toEpochSecond() - Instant.now().getEpochSecond();
                return clamp((int) secs);
            } catch (DateTimeParseException ignore) {
                return null;
            }
        }

        private static int clamp(int v) {
            return Math.max(1, Math.min(600, v));
        }
    }
}

Two status codes deserve explicit handling in your own code:

402 (Payment Required) — the key has no credit source left. Credits are universal: a subscription’s monthly quota, a one-time top-up batch, and the welcome credits all draw from one pool. A 402 means all three are exhausted (or there is no active plan on a live key). HtpbeApiException.retryable() returns false for it — surface it to your billing path rather than retrying, because retrying fails identically until the account is topped up at the pricing page.
429 (Too Many Requests) — this is server-wide concurrency, not per-key rate limiting. The response carries a Retry-After header, which the handler parses (both delay-seconds and HTTP-date forms, clamped to [1, 600]) and stashes on the exception. Your retry policy reads that value before falling back to exponential backoff.

Step 6: Retry on Transient Failures Only

The error handler classifies failures; the retry policy acts on that classification. Spring Retry (spring-retry plus @EnableRetry) is the idiomatic fit. Retry only the billable submitAnalysis step and only when the exception is retryable() — never wrap the whole verify in one retry, or a transient getResult failure would replay the POST and bill a second analysis.

package com.example.htpbe;

import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Component;

@Component
public class HtpbeVerificationService {

    private final HtpbeClient client;

    public HtpbeVerificationService(HtpbeClient client) {
        this.client = client;
    }

    public AnalysisResult verify(String pdfUrl, String originalFilename) {
        // submit (billable, retried) → read (free, retried separately)
        String id = submitWithRetry(pdfUrl, originalFilename);
        return readWithRetry(id);
    }

    @Retryable(
            retryFor = HtpbeApiException.class,
            // Only retry when the exception says it is transient.
            // exceptionExpression evaluates retryable() on the thrown instance.
            exceptionExpression = "#{#root instanceof T(com.example.htpbe.HtpbeApiException) "
                    + "&& #root.retryable()}",
            maxAttempts = 4,
            backoff = @Backoff(delay = 1000, multiplier = 2.0, maxDelay = 8000))
    String submitWithRetry(String pdfUrl, String originalFilename) {
        return client.submitAnalysis(pdfUrl, originalFilename);
    }

    @Retryable(
            retryFor = HtpbeApiException.class,
            exceptionExpression = "#{#root instanceof T(com.example.htpbe.HtpbeApiException) "
                    + "&& #root.retryable()}",
            maxAttempts = 4,
            backoff = @Backoff(delay = 1000, multiplier = 2.0, maxDelay = 8000))
    AnalysisResult readWithRetry(String id) {
        return client.getResult(id);
    }
}

Spring Retry’s annotation backoff is fixed at configuration time, so the @Backoff above applies a generic exponential curve. If you want to honour the server’s exact Retry-After on a 429, drop the annotation in favour of a programmatic RetryTemplate whose BackOffPolicy reads HtpbeApiException.retryAfterSeconds() from the last failure — the typed exception already carries the parsed value, clamped to a safe range. For most integrations the annotation form is enough; the server-supplied delay matters most under sustained capacity pressure.

Step 7: The Bank-Statement Gate

The service returns facts. Turning those facts into an ACCEPT / REJECT / REVIEW decision is a policy choice that depends on what the document claims to be. A bank statement, a payslip, or a diploma claims institutional origin, so anything other than intact should stop the automated path. A user-generated form is held to a looser standard.

package com.example.htpbe;

public final class DocumentGate {

    public enum Decision { ACCEPT, REJECT, REVIEW }

    private DocumentGate() { }

    /**
     * Maps a verdict to a decision for documents that claim institutional
     * origin (bank statements, payslips, diplomas). For these, "inconclusive"
     * is treated as strictly as "modified": a document that should have come
     * from a bank's own system but looks like it was built in Word does not
     * get the benefit of the doubt.
     */
    public static Decision forInstitutional(AnalysisResult r) {
        return switch (Verdict.of(r.status())) {
            case MODIFIED -> Decision.REJECT;
            // A bank statement that comes back inconclusive should not be
            // auto-accepted: it typically came from consumer software rather
            // than a bank's own system — a signal to route for review, not
            // proof of tampering. Send it to a human.
            case INCONCLUSIVE -> Decision.REVIEW;
            case INTACT -> Decision.ACCEPT;
        };
    }
}

Wire the service and the gate into a controller that accepts a JSON body with a reachable URL. The handler runs the check before any business logic touches the file:

package com.example.htpbe;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

@RestController
@RequestMapping("/api/documents")
public class DocumentController {

    private final HtpbeVerificationService verification;

    public DocumentController(HtpbeVerificationService verification) {
        this.verification = verification;
    }

    public record VerifyRequest(String documentUrl, String originalFilename) { }

    @PostMapping
    public ResponseEntity<?> verify(@RequestBody VerifyRequest req) {
        if (req.documentUrl() == null || req.documentUrl().isBlank()) {
            return ResponseEntity.badRequest()
                    .body(Map.of("error", "document_url is required"));
        }

        AnalysisResult result;
        try {
            result = verification.verify(req.documentUrl(), req.originalFilename());
        } catch (HtpbeApiException e) {
            return mapApiError(e);
        }

        return switch (DocumentGate.forInstitutional(result)) {
            case REJECT -> ResponseEntity.unprocessableEntity().body(Map.of(
                    "decision", "reject",
                    "reason", "document modified after creation",
                    "modification_markers", result.modificationMarkers()));
            case REVIEW -> ResponseEntity.accepted().body(Map.of(
                    "decision", "review",
                    "status_reason", result.statusReason()));
            case ACCEPT -> ResponseEntity.ok(Map.of(
                    "decision", "accept",
                    "check_id", result.id()));
        };
    }

    private ResponseEntity<?> mapApiError(HtpbeApiException e) {
        return switch (e.statusCode()) {
            // Configuration / billing errors — never leak the cause to the caller.
            case 401, 402 -> ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE)
                    .body(Map.of("error", "verification temporarily unavailable"));
            case 422 -> ResponseEntity.unprocessableEntity()
                    .body(Map.of("error", "the URL did not return a valid PDF"));
            case 413 -> ResponseEntity.status(HttpStatus.PAYLOAD_TOO_LARGE)
                    .body(Map.of("error", "PDF must be under 10 MB"));
            default -> ResponseEntity.status(HttpStatus.BAD_GATEWAY)
                    .body(Map.of("error", "verification failed"));
        };
    }
}

An inconclusive result should not be auto-accepted — it typically indicates the file came from consumer software, an online editor, an HTML renderer, or a scanner rather than an institutional generator. That is a signal to route for review, not proof of tampering. For a deeper explanation, see what “inconclusive” really means. For documents that claim institutional origin, treat inconclusive with the same caution as modified: do not accept automatically, route to a human reviewer. Inverting that policy — treating inconclusive as a pass — is the single most common integration mistake, because it hands an automatic accept to exactly the consumer-software-built documents a bank statement should never be.

Step 8: The Reactive Variant (WebClient)

If your service is built on Spring WebFlux, swap RestClient for WebClient and return a Mono<AnalysisResult>. The two-step flow becomes a flatMap, and onStatus plays the role the ResponseErrorHandler played above. The retry semantics are the same: retry the submit and the read independently, and only on a retryable() exception.

package com.example.htpbe;

import org.springframework.stereotype.Service;
import org.springframework.web.reactive.function.client.WebClient;
import reactor.core.publisher.Mono;
import reactor.util.retry.Retry;

import java.time.Duration;
import java.util.Map;

@Service
public class ReactiveHtpbeClient {

    private final WebClient webClient;

    public ReactiveHtpbeClient(HtpbeProperties props, WebClient.Builder builder) {
        this.webClient = builder
                .baseUrl(props.baseUrl())
                .defaultHeader("Authorization", "Bearer " + props.apiKey())
                .build();
    }

    public Mono<AnalysisResult> verify(String pdfUrl, String originalFilename) {
        return submit(pdfUrl, originalFilename)
                .retryWhen(transientBackoff())     // billable step
                .flatMap(id -> read(id).retryWhen(transientBackoff())); // free read
    }

    private Mono<String> submit(String pdfUrl, String originalFilename) {
        var body = (originalFilename == null)
                ? Map.of("url", pdfUrl)
                : Map.of("url", pdfUrl, "original_filename", originalFilename);
        return webClient.post()
                .uri("/analyze")
                .bodyValue(body)
                .retrieve()
                .onStatus(s -> s.isError(), resp -> resp.createException()
                        .map(ex -> new HtpbeApiException(
                                resp.statusCode().value(), "ERROR", ex.getMessage(), null)))
                .bodyToMono(Map.class)
                .map(m -> (String) m.get("id"));
    }

    private Mono<AnalysisResult> read(String id) {
        return webClient.get()
                .uri("/result/{id}", id)
                .retrieve()
                .onStatus(s -> s.isError(), resp -> resp.createException()
                        .map(ex -> new HtpbeApiException(
                                resp.statusCode().value(), "ERROR", ex.getMessage(), null)))
                .bodyToMono(AnalysisResult.class);
    }

    private Retry transientBackoff() {
        return Retry.backoff(3, Duration.ofSeconds(1))
                .filter(t -> t instanceof HtpbeApiException e && e.retryable());
    }
}

The reactive path is worth it only if the rest of your stack is reactive. For a conventional Spring MVC service, the blocking RestClient in Step 5 is simpler and easier to reason about — the 2–5 seconds the analysis takes is no worse on a platform thread than any other outbound call, and on Java 21 virtual threads remove even that cost.

Step 9: Giving the API a Reachable URL

The API does not accept file uploads — it downloads the PDF from a URL you supply, so the file must be publicly reachable for the few seconds the analysis takes. The cleanest pattern is a short-lived presigned URL from your object store: you never expose the bucket, the link expires in minutes, and passing originalFilename keeps the audit trail readable instead of showing an opaque storage key.

// Store the upload privately, mint a 5-minute presigned GET URL, verify.
String key = "incoming/" + UUID.randomUUID() + ".pdf";
s3Client.putObject(PutObjectRequest.builder()
        .bucket(bucket).key(key).contentType("application/pdf").build(),
        RequestBody.fromBytes(pdfBytes));

GetObjectPresignRequest presignRequest = GetObjectPresignRequest.builder()
        .signatureDuration(Duration.ofMinutes(5))
        .getObjectRequest(b -> b.bucket(bucket).key(key))
        .build();
String presignedUrl = s3Presigner.presignGetObject(presignRequest).url().toString();

AnalysisResult result = verification.verify(presignedUrl, originalFilename);

The same pattern works with Google Cloud Storage (Storage.signUrl), Azure Blob (a SAS token), or Cloudflare R2 (S3-compatible — reuse the AWS SDK with the R2 endpoint). One security note: the API fetches whatever URL you give it, so if a URL ever comes from untrusted input (a user-pasted link, a webhook payload), validate that it resolves to a public host first — reject localhost, 169.254.169.254 (cloud metadata), and the RFC 1918 private ranges to close the SSRF surface. When you mint the URL yourself from a private bucket the risk is minimal, but the validation belongs in the request flow either way.

Step 10: Testing Without Burning Quota

Every plan includes a test API key (prefix htpbe_test_) that accepts only mock URLs of the form https://api.htpbe.tech/v1/test/{filename}.pdf and returns deterministic responses — like Stripe test cards, with no quota cost. Point an integration test at these fixtures to cover every branch of the gate:

@SpringBootTest
@TestPropertySource(properties = "htpbe.api-key=${HTPBE_TEST_API_KEY}")
class HtpbeClientIntegrationTest {

    @Autowired
    HtpbeVerificationService verification;

    @Test
    void cleanDocumentReturnsIntact() {
        AnalysisResult r = verification.verify(
                "https://api.htpbe.tech/v1/test/clean.pdf", null);
        assertThat(r.status()).isEqualTo("intact");
        assertThat(r.modificationMarkers()).isEmpty();
        assertThat(DocumentGate.forInstitutional(r))
                .isEqualTo(DocumentGate.Decision.ACCEPT);
    }

    @Test
    void signatureRemovedIsRejected() {
        AnalysisResult r = verification.verify(
                "https://api.htpbe.tech/v1/test/signature-removed.pdf", null);
        assertThat(r.status()).isEqualTo("modified");
        assertThat(r.signatureRemoved()).isTrue();
        assertThat(DocumentGate.forInstitutional(r))
                .isEqualTo(DocumentGate.Decision.REJECT);
    }

    @Test
    void inconclusiveIsRoutedToReview() {
        AnalysisResult r = verification.verify(
                "https://api.htpbe.tech/v1/test/inconclusive.pdf", null);
        assertThat(r.status()).isEqualTo("inconclusive");
        assertThat(r.statusReason()).isNotNull();
        assertThat(DocumentGate.forInstitutional(r))
                .isEqualTo(DocumentGate.Decision.REVIEW);
    }
}

Useful fixtures: clean.pdf → intact, signature-removed.pdf → modified, dates-mismatch.pdf → modified, and inconclusive.pdf → inconclusive. For pure unit tests of the controller and gate without any network, stub the HtpbeVerificationService with Mockito and return a canned AnalysisResult. Keep test and live keys in separate property sources and never commit either.

For audit dashboards, GET /api/v1/checks returns a paginated list of every result for your key — filter by status and limit (/checks?status=modified&limit=50, same Authorization header). When you reach your monthly quota, further requests return 402 PAYMENT_REQUIRED until it resets — add a one-time credit pack or move to a higher tier to keep going, and handle the 402 so a quota boundary never silently drops a check.

What This Does Not Catch

Structural analysis has honest limits, and a Spring service making automated decisions should encode them rather than overstate the verdict:

Content fabricated in one pass. If someone opens Word, types a false salary, and exports once, the file was never modified after creation — it is structurally consistent. The fraud happened at authorship, not at the byte level. This is exactly why a payslip from a consumer tool tends to return inconclusive rather than intact: the analysis cannot vouch for a document anyone could have produced from scratch. The verdict is honest about what it can and cannot establish, which is why inconclusive is a routing signal, not a pass.
Born-synthetic forgeries. A fake document generated programmatically with a valid-looking account number and a real logo — never derived from a genuine original — has no post-creation edit to detect. Catching that is a content-verification problem (does this account number exist, does this employer match payroll records), a different product category from structural tamper detection.
Documents rebuilt from scratch in the original’s software. A determined attacker who recreates a document in the same institutional tool and matches the metadata leaves few structural signals. This is rare and high-effort, but possible.
Encrypted or password-protected PDFs. The service cannot parse a file it cannot open; remove the password before submitting.

These limits are why structural tamper detection works as one layer in a fraud-detection stack, not the whole stack. Pair the structural verdict with domain checks — amount validation, account-number lookups, sender authentication, and your KYC or OCR provider — for a layered defence. The structural layer answers a question identity verification cannot: was this file edited after it was issued? See PDF Fraud Prevention Best Practices.

Decisions Before You Ship

The integration surface is intentionally small: one POST, one GET, three verdicts, the typed exception above. The complexity lives on the Spring side, and two choices matter most:

Where verification runs. Synchronous inside the request handler gives the caller an immediate decision but blocks for a few seconds; a @Async method or a message-driven consumer returns instantly and defers the verdict. Sync suits low-volume B2B onboarding; async suits high-volume portals. On Java 21, virtual threads make the synchronous path cheap enough that most teams never need the async one.
inconclusive routing. For documents that claim institutional origin (bank statements, diplomas, payslips), treat inconclusive with the same caution as modified and route to human review — that is what DocumentGate.forInstitutional encodes. For genuinely user-generated content it may be acceptable as-is, so you may want a second gate with a looser policy.

To start, sign up for HTPBE — new accounts get five checks to try, then pay-per-check credits or a subscription from $15/mo — copy your test key, and run the curl call from Step 1. The full API reference documents every response field, error code, and the marker dictionary the Spring client branches on.

Feature Flags Without LaunchDarkly: A 100-Line Solution

Iurii Rogulia — Mon, 20 Jul 2026 10:00:44 +0000

You want to merge a half-finished checkout redesign into main without breaking checkout for everyone. You want to ship a risky billing change but keep a kill switch in case it misbehaves at 2am. You want to turn a new dashboard on for one beta customer and nobody else. The first instinct, reading the docs, is to reach for LaunchDarkly or Flagsmith or Split. But for a small team or an early-stage SaaS, feature flags without LaunchDarkly is not a compromise — it's about a hundred lines of code you fully own.

This is the same kind of decision I keep helping founders make: which piece of infrastructure to actually buy, and which to build because the build is small and the buy is a recurring tax. Feature flags, for a team that has eight of them, land firmly on the build side. Let me show you why, and then show you the code.

What Feature Flags Actually Buy You

Strip away the marketing and a feature flag is one thing: a runtime switch that decides whether a piece of code runs, without redeploying. That single capability unlocks several distinct workflows, and it's worth being precise about them because they're often blurred together.

Decoupling deploy from release. Today, for most teams, deploying code and releasing a feature are the same event — the moment the new bundle goes live, users get the new behaviour. Flags split those apart. You deploy the code dark on Tuesday, verify it's healthy in production, and flip it on for users on Thursday. The deploy is a low-stress engineering event; the release is a separate, deliberate product decision.

Kill switches for risky code. A new payment path, a rewritten search index, a third-party integration you don't fully trust yet — wrap it in a flag and you have an off switch that doesn't require a rollback deploy. When something misbehaves, you flip the flag instead of reverting commits and waiting for CI. Mean-time-to-recovery drops from "however long a deploy takes" to "a database write."

Gradual percentage rollout. Instead of shipping a change to 100% of users at once, you turn it on for 5%, watch your error rates and latency, then 20%, then 50%, then everyone. If something breaks, it broke for 5% of traffic, not all of it. This is the feature that's genuinely fiddly to build correctly, and most of the technical interest in this article lives here.

Per-user and per-tenant targeting. Turn a feature on for one specific beta tenant, your own internal accounts, or everyone on the enterprise plan — regardless of the rollout percentage. This is how you dogfood, how you run private betas, and how you honour "customer X explicitly asked to opt out."

Trunk-based development. You can merge unfinished work into main behind a flag that defaults to off. The code is in the codebase, getting integrated and built continuously, but it's inert until you decide otherwise. This kills long-lived feature branches and the merge hell that comes with them.

That's the value. Notice that none of it inherently requires a vendor.

Why a SaaS Is Often the Wrong First Choice

I want to be fair here, because LaunchDarkly is a genuinely good product and there's a point where it earns its price. But for an early-stage team, buying it first is usually backwards, for four concrete reasons.

Cost that scales with the wrong thing. Flag platforms price on seats and monthly active users — the very numbers a growing product wants to grow. You start paying more precisely as you succeed, for a capability whose complexity didn't change. A team with eight flags is paying a per-MAU rate for infrastructure they could express in one database table.

A network dependency in your hot path. This is the one engineers underestimate. Every flag evaluation is conceptually a question — "is feature X on for this user?" — and a SaaS answers it either via a remote call or via an SDK that has to initialize, stream updates, and stay in sync. Their SDKs work hard to make this fast and local, but you've still introduced a third-party system into the path of rendering your pages. When their edge has a bad day, or the SDK fails to init, you need a sane fallback — and now you're writing flag-evaluation fallback logic anyway.

Data-residency and privacy surface. To do per-user targeting, the platform needs to know about your users — identifiers, attributes, sometimes more. For an EU product that's another processor in your data-flow diagram, another DPA to sign, another thing your privacy policy has to account for. Keeping flag evaluation inside your own Postgres sidesteps all of it.

Massively over-featured for where you are. Audit logs, approval workflows, multivariate experiments, twelve-attribute segmentation, a polished UI for non-engineers — that's a lot of product. It's the right product for a 60-engineer org with PMs flipping flags. It's dead weight for a three-person team whose "flag UI" can be a SQL UPDATE.

None of these are dealbreakers forever. They're reasons not to start there.

The 100-Line Solution

Here's the whole design. A Postgres table holds the flags. A small evaluation function answers isEnabled(key, context). An in-memory cache keeps you off the database on the hot path. That's it.

I'm using Postgres-backed flags as the primary version on purpose, because the entire point of a flag is to flip it without a deploy. If your flags live in a TypeScript config file, changing one means a commit, a build, and a deploy — which defeats the kill-switch and gradual-rollout use cases. A static config is fine for the simplest case (a permanent on/off toggle that rarely changes), and I'll note that variant at the end, but the database version is the one that earns its keep.

The flags table

CREATE TABLE feature_flags (
  key                 TEXT PRIMARY KEY,
  enabled             BOOLEAN     NOT NULL DEFAULT false,
  rollout_percentage  SMALLINT    NOT NULL DEFAULT 0
                        CHECK (rollout_percentage BETWEEN 0 AND 100),
  enabled_tenants     TEXT[]      NOT NULL DEFAULT '{}',
  disabled_tenants    TEXT[]      NOT NULL DEFAULT '{}',
  updated_at          TIMESTAMPTZ NOT NULL DEFAULT now()
);

The columns map directly to the use cases above. enabled is the master switch — false means off for everyone, full stop, which is your kill switch. rollout_percentage drives gradual rollout. enabled_tenants and disabled_tenants are the targeting allow-lists: a tenant in enabled_tenants gets the feature regardless of percentage, and a tenant in disabled_tenants never gets it regardless of percentage. (For per-user rather than per-tenant targeting, the same columns hold user IDs — the evaluation logic is identical; pick whichever identifier your product keys on.)

Deterministic percentage rollout

This is the part worth slowing down for. The naive way to roll a flag out to 20% of users is to roll a die per request:

// ANTI-PATTERN: do not do this — recomputes per request
function isInRollout(percentage: number): boolean {
  return Math.random() * 100 < percentage;
}

That's broken in a way that's easy to miss. The same user gets a different answer on every request — feature on, page reload, feature off, reload, feature on again. The UI flickers, sessions are inconsistent, and your error rates become impossible to attribute. A 20% rollout has to mean "a stable 20% of users always get it," not "every request has a 20% chance."

The fix is to make the decision a deterministic function of the user and the flag, with no randomness at request time. Hash flagKey + userId into a number in [0, 100) and compare it to the rollout percentage. Same user, same flag, same answer — forever, until you change the percentage. This is the same deterministic-hashing trick I used to make a viral web toy wrong the same way every time: unpredictable to a human, perfectly reproducible from the input alone.

You need a fast, well-distributed hash — not a cryptographic one, since this isn't a security boundary, just a bucketing function. FNV-1a is a good fit: tiny, fast, and spreads inputs evenly across the output range.

// FNV-1a, 32-bit. Small, fast, well-distributed — not cryptographic.
function fnv1a(input: string): number {
  let hash = 0x811c9dc5; // FNV offset basis
  for (let i = 0; i < input.length; i++) {
    hash ^= input.charCodeAt(i);
    // 32-bit FNV prime multiply, kept in uint32 range
    hash = Math.imul(hash, 0x01000193) >>> 0;
  }
  return hash >>> 0;
}

// Map any string to a stable bucket in [0, 100).
function bucket(flagKey: string, userId: string): number {
  // Salt with the flag key so a user isn't always in the same
  // percentile across every flag — otherwise the unlucky 5% of
  // user A's first rollout are the unlucky 5% of every rollout.
  return fnv1a(`${flagKey}:${userId}`) % 100;
}

The salting detail matters more than it looks. If you hash the user ID alone, the user who lands in bucket 3 is in bucket 3 for every flag — so the same unlucky cohort is always first into every rollout, and your "20% of users" are always the same 20% of users across unrelated features. Mixing the flag key in re-shuffles the buckets per flag, so each rollout samples an independent slice.

The evaluation function

Now the whole decision, in the order the rules apply:

type FlagRecord = {
  key: string;
  enabled: boolean;
  rolloutPercentage: number;
  enabledTenants: string[];
  disabledTenants: string[];
};

type Context = {
  tenantId?: string; // or userId — whatever you bucket on
};

function evaluate(flag: FlagRecord | undefined, ctx: Context): boolean {
  // Unknown flag → off. Fail closed, never crash on a typo'd key.
  if (!flag) return false;

  // Master kill switch wins over everything.
  if (!flag.enabled) return false;

  const id = ctx.tenantId;

  // Explicit overrides beat the percentage roll, both directions.
  if (id && flag.disabledTenants.includes(id)) return false;
  if (id && flag.enabledTenants.includes(id)) return true;

  // No identity to bucket on → treat as a plain on/off at 100%.
  if (!id) return flag.rolloutPercentage >= 100;

  // Deterministic percentage rollout.
  return bucket(flag.key, id) < flag.rolloutPercentage;
}

Read the order of the rules, because the order is the semantics. Kill switch first, then explicit per-tenant overrides (force-off beats force-on by convention — the safer direction wins ties), then the percentage bucket. An unknown flag key returns false rather than throwing: a typo in a flag name should make the feature quietly stay off, never take down the request. That fail-closed default is deliberate, and it's the kind of small decision that separates a flag system you can trust from one that becomes its own source of incidents.

Caching: stay off the database

If evaluate hit Postgres on every flag check, you'd add a query to the hot path of every request — exactly the network dependency I criticized the SaaS for. So you don't. Load all flags into memory once, refresh on an interval, and serve every evaluation from the in-memory snapshot.

import type { Pool } from "pg";

const REFRESH_MS = 30_000; // flips propagate within this window

export class FlagStore {
  private cache = new Map<string, FlagRecord>();

  constructor(private pool: Pool) {}

  async start(): Promise<void> {
    await this.refresh();
    // unref so the timer never keeps the process alive on shutdown
    setInterval(() => {
      this.refresh().catch((err) => console.error("flag refresh failed", err));
    }, REFRESH_MS).unref();
  }

  private async refresh(): Promise<void> {
    const { rows } = await this.pool.query<FlagRecord>(
      `SELECT key,
              enabled,
              rollout_percentage AS "rolloutPercentage",
              enabled_tenants    AS "enabledTenants",
              disabled_tenants   AS "disabledTenants"
       FROM feature_flags`
    );
    const next = new Map<string, FlagRecord>();
    for (const row of rows) next.set(row.key, row);
    this.cache = next; // atomic swap — readers never see a half-built map
  }

  isEnabled(key: string, ctx: Context = {}): boolean {
    return evaluate(this.cache.get(key), ctx);
  }
}

Call flags.start() once at boot, then flags.isEnabled("new_checkout", { tenantId }) anywhere — it's a synchronous map lookup plus an integer hash, with no I/O. Note the failure handling: a failed refresh logs and keeps serving the previous snapshot, so a transient database blip degrades to slightly-stale flags rather than an outage. And building the new map fully before swapping it in means a reader mid-refresh sees either the complete old state or the complete new state, never a partial one.

The honest tradeoff is right there in REFRESH_MS: a flag flip takes up to one refresh interval to propagate to every running instance. At 30 seconds, flipping a kill switch in SQL takes up to half a minute to fully take effect across your fleet. For most teams that's completely fine — half a minute to disable a misbehaving feature is still dramatically faster than a rollback deploy. If you genuinely need sub-second propagation, that's a real reason to want something more, which is the next section. (You can also shorten the interval or add a LISTEN/NOTIFY push to invalidate on write — but now you're adding lines, and the whole pitch was that this stays small.)

That's the system. The table, the hash, the evaluation function, and the cached store come to roughly a hundred lines, and you own every one of them.

slug="mvp-development"
text="Building an MVP and weighing build-versus-buy on every piece of infrastructure? Knowing which 100-line solution beats a subscription — and which doesn't — is exactly the kind of early call I help founders get right."
/>

When You Should Actually Buy LaunchDarkly

I'm not going to pretend the 100-line version scales to every org, because it doesn't, and pretending otherwise would be the kind of dishonesty that makes the rest of this article less trustworthy. There's a clear line where a SaaS earns its price. You're over it when:

Non-engineers need to flip flags themselves. The moment a PM or a marketing lead wants to turn a feature on without a developer running SQL, you need a real UI with roles and permissions. Building and maintaining that UI is its own product — buy it.
You need a rich audit trail with approvals. Who changed which flag, when, why, and who approved it. Regulated industries and larger orgs need this for compliance, not vanity. An updated_at column doesn't cut it.
Segmentation gets genuinely complex. Targeting by plan tier and country and signup date and twelve other attributes, with reusable segments — that's a rules engine, and writing your own rules engine is exactly the over-engineering this article argues against, just in the other direction.
You need true real-time propagation. Sub-second streaming updates instead of a polling interval. If a flag flip has to reach every client in under a second, a vendor's streaming SDK is built for it and your 30-second poll isn't.
You're running real experiments. Multivariate testing with built-in statistical significance, conversion tracking, and guardrail metrics. That's an experimentation platform, not a flag system, and it's a lot to build well.

If you need those things, LaunchDarkly is worth every euro. The point of the 100-line version isn't that the SaaS is bad — it's that most early-stage teams have none of these needs yet, and buying a platform to solve problems you don't have is how MVPs accrete cost and complexity before they've found product-market fit. Build the small thing now; buy the big thing when the big thing's problems are actually yours.

This is also why feature flags fit so naturally into a multi-tenant SaaS schema: the per-tenant allow-lists above are just another tenant-scoped concern, evaluated against the same tenant_id you're already threading through everything. And if you're standing up a new product, the flag table slots cleanly into the broader build-a-SaaS-with-Next.js checklist — it's a small, early piece of plumbing that pays for itself the first time you need to ship something dark.

The static-config variant

For completeness: if a flag is a permanent on/off you change maybe twice a year, you don't even need the table. A typed config object works:

// Simplest case only — changing a flag here requires a deploy.
const FLAGS = {
  newCheckout: false,
  legacyExportApi: true,
} as const;

export const isEnabled = (key: keyof typeof FLAGS): boolean => FLAGS[key];

It's type-safe, it's zero-infrastructure, and it's honest about its one limitation: flipping a flag means a deploy. That rules out kill switches and gradual rollout, which is most of the value. Use it for the genuinely static toggles and use the database version for everything that needs to move at runtime.

Takeaways

Feature flags decouple deploy from release — kill switches, gradual rollout, per-tenant targeting, and trunk-based development all fall out of one runtime switch.
For a small team, building beats buying. A SaaS prices on MAU, adds a dependency to your hot path, and ships features you won't use for years.
Deterministic percentage rollout is the one non-trivial idea. Hash flagKey + userId to a stable bucket — never Math.random(), or the same user flickers on and off every request.
Salt the hash with the flag key so each rollout samples an independent slice instead of always picking on the same unlucky cohort.
Cache in memory, refresh on an interval, and own the tradeoff: flips propagate within one refresh window, which is still far faster than a rollback deploy.
Fail closed. An unknown flag returns off and never throws; a failed refresh serves the last good snapshot.
Buy the SaaS when its problems are actually yours — non-engineers flipping flags, audit trails with approvals, complex segmentation, sub-second propagation, or real experimentation. Most early teams have none of these yet.

Adobe Producer Spoofing: A PDF Metadata Forgery Case Study

Iurii Rogulia — Sun, 19 Jul 2026 10:00:34 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

A fraud reviewer opens a PDF bank statement. The first thing many manual checks look at is the document’s Producer field — the line of metadata that records which software last wrote the file. This one says Adobe PDF Library 23.1. To a human, and to most lightweight metadata checks, that reads as reassuring: Adobe is professional software, the kind a bank’s back office or a law firm would use. The reviewer moves on.

That is exactly the reaction the forger was counting on.

The document was not produced by Adobe. It was edited in a free browser-based PDF editor, then passed through a step that overwrote the Producer string to say Adobe. The metadata now lies about the file’s own origin — and it lies in the most credibility-laundering direction available, because “Adobe” is the producer string people trust most. This is producer identity forgery, and it is one of the most common ways a tampered PDF tries to talk its way past a metadata-only review.

This is a case study in how that attack works at a conceptual level, why a metadata-only check waves it through, and how a structural approach — the one behind the public marker HTPBE_PRODUCER_IDENTITY_FORGED — catches the contradiction the forger left behind.

If you want to see the Producer string for yourself, the free PDF metadata viewer reads it — along with every other field — straight out of any PDF.

Why the Producer field is the obvious thing to forge

Every PDF carries internal records about how it was made. Two fields matter most to a reviewer:

producer — the software that wrote the final bytes of the file.
creator — the application the content originated in.

Fraud-detection lore, repeated in countless “how to spot a fake bank statement” guides, says the same thing: a real institutional document is generated by an automated back-end system, so if the producer says Microsoft Word, Canva, or some online PDF tool, you are probably looking at a forgery. (For the full breakdown of what these fields contain and what they reveal, see the PDF metadata fields reference and what PDF metadata reveals.) That advice is correct as far as it goes.

The problem is that it is public advice. Forgers read the same guides. So the natural next move is not to leave an incriminating producer string in place — it is to overwrite it. And if you are going to overwrite it, you do not write LibreOffice. You write the most trusted name you can: Adobe.

Overwriting a metadata string is trivial. A producer value is just text inside the file; dozens of free tools and one-line scripts will set it to anything you like. So the field that fraud guides tell reviewers to trust is also the field that is cheapest for a forger to fake. A metadata-only check that stops at “the producer says Adobe, looks fine” is checking the one thing the attacker fully controls.

What a metadata-only review actually verifies (almost nothing)

Reading the producer and creator strings tells you what the file claims about itself. It does not tell you whether those claims are true. A self-reported field is a self-reported field, whether it says Canva or Adobe PDF Library.

This is the gap. The reviewer who rejects a statement because its producer says Canva is doing the right thing — but a forger who has done their homework will never present that file. They present the version that says Adobe. Now the same reviewer, applying the same rule, accepts the worse forgery. The rule rewards the more careful attacker.

To catch producer identity forgery you cannot ask “what does the file say?” You have to ask “does the rest of the file behave the way a file from that producer actually behaves?” That is a structural question, not a metadata-string question.

The contradiction a forged Adobe claim leaves behind

Genuine Adobe software does not just stamp a producer string and stop. When real Adobe products write a PDF, they leave a coherent set of structural fingerprints throughout the file — the byproduct of how that software actually assembles, describes, and saves a document. These fingerprints are consistent across genuine Adobe output because they fall out of the software’s real internals, not from any single field a user types.

A forger who only overwrites the producer text gets none of that for free. They have changed the label on the box without changing what is inside it. The result is a file whose metadata announces “Adobe produced me” while its underlying structure tells a different, internally inconsistent story — the structure of an online editor or a consumer re-save tool wearing an Adobe name tag.

That contradiction — an Adobe origin claim that the file’s own structure does not support — is the signal. When HTPBE sees a document asserting Adobe origin while the structural fingerprints that genuine Adobe output reliably carries are absent or mutually inconsistent, it treats the Adobe claim as forged and returns the public marker HTPBE_PRODUCER_IDENTITY_FORGED. The verdict for such a file is modified: the metadata has been edited to misrepresent the file’s origin, which is precisely a post-creation modification.

We deliberately do not publish the exact byte-level checklist of which fingerprints are checked or how they relate. That list would be a bypass recipe — a map of exactly which fields a forger would need to forge in lockstep to defeat the check. The principle is the part that’s safe to state plainly: real Adobe output leaves structural fingerprints that a string-overwrite, a consumer re-save tool, or a metadata editor does not reliably reproduce. The forger faked the easy part and skipped the hard part, because the hard part is invisible to them.

A worked example, in business terms

Picture two files crossing a lending team’s desk in the same week.

File A is a real PDF statement from a bank’s document system. Its producer reflects the institutional pipeline that generated it. Its internal timestamps, structure, and origin signals all line up. HTPBE returns intact. Accept.

File B looks nicer. Its producer proudly says Adobe PDF Library, which the reviewer reads as a green flag. But File B started life as a PDF that someone opened in a browser editor, changed the closing balance on, and then ran through a step that rewrote the producer to Adobe. The Adobe claim is bolted onto a body that was never anywhere near Adobe software. HTPBE returns modified with HTPBE_PRODUCER_IDENTITY_FORGED. Reject.

To the human eye, File B is the more trustworthy of the two — it name-drops Adobe; File A just has some institutional toolchain string nobody recognizes. Structural forensics inverts that intuition, which is the whole point. The forger optimized for the human reviewer’s heuristic and walked straight into the structural one.

Where `inconclusive` fits — and why it isn’t a failure

Not every non-Adobe file is a forged-Adobe file. Plenty of legitimate documents are simply produced by consumer software: someone exports a perfectly honest letter from a word processor or a print-to-PDF driver. Those files don’t claim a false institutional origin; they just aren’t the kind of file whose integrity can be cryptographically vouched for after the fact.

For those, HTPBE returns inconclusive. That verdict is not a tool failure and it is not an accusation — it means the file was made with consumer software, so there is no institutional structural baseline to verify the file against. inconclusive is itself a useful signal: if your process expected a document from an institution and the result is inconclusive, the file wasn’t generated by an institutional system, and that mismatch is something your workflow should act on. Producer identity forgery is the opposite case: a file actively claiming the institutional/Adobe origin it doesn’t have. The first is a quiet gap; the second is a loud lie.

The honest limit

This detector raises the cost of the attack; it does not make it impossible. A forger who fully understands what genuine Adobe output looks like, and who reproduces the entire coherent fingerprint — not just the producer string, but every structural detail that has to agree with it — can in principle still present a file that asserts Adobe origin without contradicting itself. No structural check that relies on fingerprints can claim absolute immunity against an attacker who perfectly reproduces those fingerprints.

What the detector does is move the bar from “edit one text field, which any free tool does in a second” to “reconstruct a complete, internally consistent Adobe production fingerprint by hand.” The overwhelming majority of producer-spoofing forgeries are the first kind, because the second kind requires deep, document-internals knowledge that the casual forger — the one buying a “fake bank statement” off a Telegram channel — simply does not have. Catching the cheap, common attack while being honest that a determined expert can still get through is the realistic standard for forensics, and it is the standard we hold this check to.

One more boundary worth stating: HTPBE is structural PDF tamper detection. It reasons about the file’s bytes and structure — whether the document was modified after creation and whether its origin claims hold up. It is not a KYC or identity-verification platform, and it does not read the document’s content to decide whether the named account holder is a real person or whether the balance is plausible. It complements an identity and risk stack; it does not replace one. Producer identity forgery is firmly in its lane: a structural contradiction between what the file says made it and what actually did.

Detecting it in your own pipeline

Producer identity forgery is one of 61 forensic checks (as of this writing) that run on every document submitted to the PDF tamper detection API. You don’t request it specifically — you submit a PDF and read the verdict.

Submit a document for analysis:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer $HTPBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/statement.pdf"}'

That returns a check id. Retrieve the verdict:

curl https://api.htpbe.tech/v1/result/CHECK_ID \
  -H "Authorization: Bearer $HTPBE_API_KEY"

A file whose Adobe claim doesn’t survive structural scrutiny comes back like this:

{
  "status": "modified",
  "modification_markers": ["HTPBE_PRODUCER_IDENTITY_FORGED"],
  "origin_type": "consumer_software"
}

In your gate, the rule is simple: a modified verdict carrying HTPBE_PRODUCER_IDENTITY_FORGED on a document that claims institutional origin is a strong, conclusive structural finding — hold the document, route it to a reviewer, and request a fresh copy directly from the issuer. The file has told you, in its own structure, that its origin label is fake. Don’t make it the sole basis for an automatic decision against the person who sent it: a structural verdict describes the file, not their intent, which is why the API ships a usage_caution object on every result to keep a human or an issuer re-request in the loop. (For the full request/response contract, see the API documentation; for the conceptual model behind the verdicts, see how PDF tamper detection works.)

If you want to test the behavior without wiring up live traffic first, a test key returns deterministic synthetic results for documented scenarios, so you can build and verify your gate logic before pointing it at production documents.

Who should care about this check

If you run fraud or risk operations at an alternative lender, a fintech, an insurer, or any business that accepts customer-supplied PDFs claiming to come from a bank, an employer, or a government body, producer identity forgery is being used against you right now — specifically because your team has been trained to read the producer field as a trust signal. The forgers know that, which is why they forge it.

The fix is not to stop reading metadata; it’s to stop trusting self-reported metadata on its own. (If you want a broader catalog of what tampering leaves behind, see 5 signs a PDF was tampered with.) Put a structural check between the uploaded file and the decision, so that an Adobe claim has to survive more than a glance. You can wire that into your existing flow through the PDF tamper detection API, or start with pay-per-check on the web tool if you want to run a batch of suspicious documents before committing to an integration. Either way, the next forged-Adobe statement that lands in your queue should come back modified — not waved through on the strength of a string anyone can type.

Isomorphic Canvas Rendering: One draw() in Browser and Node

Iurii Rogulia — Sat, 18 Jul 2026 10:00:42 +0000

A user types 64+5 into Wrongulator, gets back 67 — "the only correct number" — laughs, and pastes the link into a group chat. Twitter, WhatsApp, Slack, Discord: each one fetches the URL, finds an Open Graph image, and unfurls a 1080×1080 card right there in the feed. That card is the joke. If it looks even slightly different from the card the user saw in their browser — different font, missing emoji, wrong line break — the joke breaks in transit.

The share card is the unit of virality, so it has exactly one job: be byte-for-byte the same picture wherever it renders. The problem is that "wherever it renders" means two completely different environments — a browser <canvas> and a Node process — and the obvious way to support both is to write the card twice. That's the trap. This post is about isomorphic canvas rendering: writing one drawing routine and running it unchanged in both runtimes, so the two pictures can't drift because there's only one of them.

Why You Need a Server Render at All

The instinct for a client-side toy is to keep everything in the browser. The engine that computes Wrongulator's wrong answer does exactly that — it's a pure function, no server call, and why the same input always returns the same wrong answer is its own story. So why involve a server in the picture at all?

Because social crawlers don't run JavaScript.

When you paste a link into a chat app, the crawler that fetches it — Twitterbot, facebookexternalhit, Slack's unfurler — reads the raw HTML response and stops. It does not boot a JS runtime, it does not wait for <canvas> to paint, it does not execute your engine. It looks for <meta property="og:image"> and fetches whatever URL it finds. That means the 1080×1080 PNG has to already exist in the server's response, fully rendered, before a single line of client JS runs.

So the card lives a double life. In the browser, it's painted live on a real <canvas> element the moment the user lands on a result. On the server, the same card has to be produced as a static PNG by an endpoint a crawler can fetch — no browser, no DOM, no JS execution on the crawler's side. Two environments, one picture, and they have to match.

The Two-Renderer Trap

The naïve way to satisfy both is to build two renderers. A browser one that draws to <canvas>, and a server one that produces the OG image somehow — maybe an SVG template, maybe an HTML-to-image library, maybe a headless browser screenshotting the page.

Every one of those splits your card into two sources of truth. The browser renderer says the headline sits at y: 120 with 48px Russo One; the SVG template says y: 118 because SVG text baselines work differently. The browser wraps the reason at 40 characters; the server library wraps at 38 because it measures glyphs differently. None of these are bugs, exactly — they're two implementations of "the same" layout that were never going to agree on every pixel. And the drift compounds: every time you tweak the card in one place, you have to remember to mirror it in the other, forever. Miss one, and the shared image quietly diverges from the one users see.

For a product whose entire growth loop is "the picture I shared is the picture you see," that drift isn't cosmetic. It's the failure mode.

The fix is to refuse the premise. Don't write two renderers that try to agree. Write one renderer that runs in both places.

One UMD Core, Two Runtimes

Canvas 2D is the right common denominator because both worlds speak it. The browser gives you a CanvasRenderingContext2D from a real <canvas>. On the server, @napi-rs/canvas — a Rust-backed, Skia-powered Node binding — gives you a context with the same API surface: fillRect, fillText, measureText, drawImage, the lot. If you write your drawing code against that bare API and touch nothing browser-specific (no document, no window, no DOM measurement), the exact same function runs in both.

So the card is a single module, card-core.js, written against the Canvas 2D API and exported as UMD so it loads cleanly in either environment:

// public/card-core.js — environment-agnostic UMD; same draw() in both runtimes
(function (root, factory) {
  if (typeof module === "object" && module.exports) module.exports = factory();
  else root.WrongCardCore = factory();
})(typeof self !== "undefined" ? self : this, function () {
  // ... drawCard(ctx, { expr, answer, reason, headline, emoji })
});

The UMD wrapper is the whole trick. In Node, module.exports exists, so the factory's return value becomes the module — require('./public/card-core.js') gives you { W, H, drawCard }. In the browser, there's no module, so it hangs the same object off self as WrongCardCore, and a <script src="card-core.js"> tag makes it global. One file, zero build step, no bundler required, and critically: the drawCard function inside is identical in both cases because it's literally the same source.

The browser side feeds it a real canvas context. The server side feeds it a Node canvas context — and that's the entire OG endpoint:

// server.js — the OG endpoint feeds the identical core a node canvas
app.get('/api/og', async (req, res) => {
  const canvas = createCanvas(core.W, core.H);
  const r = wrongulate(expr, tone, lang);
  core.drawCard(canvas.getContext('2d'), { expr, answer: r.answer, reason: r.reason, ... });
  res.setHeader('Cache-Control', 'public, immutable, max-age=31536000'); // output is deterministic
  res.end(canvas.toBuffer('image/png'));
});

Read that endpoint and notice what it doesn't do. It doesn't lay out text. It doesn't pick colors, position the headline, or wrap the reason. All of that lives in core.drawCard, the same function the browser calls. The server's job shrinks to three lines: make a canvas of core.W × core.H, hand the context to the shared core, serialize the result with canvas.toBuffer('image/png'). The dimensions come from the core too (core.W, core.H), so even the canvas size can't drift between environments.

This is the payoff of isomorphism stated plainly: the OG endpoint has no rendering logic of its own to get wrong. There's nothing to keep in sync because there's nothing duplicated. When I change how the card looks, I change one function, and both the in-app card and every future unfurl move together.

slug="mvp-development"
text="If your MVP's growth depends on shareable artifacts — cards, certificates, generated images that unfurl in feeds — the server render is not an afterthought. I build the whole loop: engine, isomorphic render, OG endpoint, caching."
/>

The Font Problem: Where Isomorphism Actually Costs You

I want to be honest about where this approach gets hard, because "one function, two runtimes" makes it sound free. It isn't. The seam shows up in fonts.

In the browser, font fallback is automatic and invisible. You ask for a font, and if a glyph isn't in it — say the user's reason contains Japanese and an emoji — the browser silently walks its own fallback chain and finds something that can render サ and 🙏. The OS has fonts installed; the browser knows how to reach them. You never think about it.

A Node process has none of that. @napi-rs/canvas will only draw glyphs from fonts you have explicitly registered, and it will not invent a fallback chain for you. Ask it to render "サンキュー 🙏" with only a Latin font loaded and you get tofu boxes, or nothing, where the Japanese and the emoji should be. The browser hid an entire subsystem from you, and on the server you have to rebuild it by hand.

Wrongulator runs in 17 languages, including RTL Arabic, so a card's text can mix Latin, Cyrillic, Thai, Arabic, Japanese, Korean, and emoji in a single string. To make that render server-side, the OG renderer carries a per-glyph font fallback chain: Russo One for Latin and Cyrillic, the appropriate Noto faces for Thai, Arabic, Japanese, and Korean, and Noto Color Emoji for the pictographs. Each of those font files has to be present in the runtime, so they're fetched at build time — the Dockerfile pulls the OFL-licensed fonts and bakes them into the image, registering each with the canvas library before any card is drawn. That's real work the browser did for free, and it's the part of "isomorphic" that has an asterisk.

Determinism Makes the Cache Free

Here's where the rendering story meets the engine story, and the two reinforce each other.

The wrong answer for 64+5 is a pure function of 64+5. It's 67, forever, for everyone — that determinism is the whole reason the toy is shareable. Now layer the isomorphic render on top: because the card is drawn by a pure function of the same inputs, the PNG for /api/og?expr=64+5 is also a pure function of its query. Same query in, same bytes out, every time.

Which means the image never needs to be re-rendered. So the endpoint sets:

res.setHeader("Cache-Control", "public, immutable, max-age=31536000");

A full year, marked immutable. The CDN fetches each card once and serves it from the edge forever. There's no invalidation logic, no cache-busting, no "did the source change" check — the output can't change for a given input, so caching it permanently is not a risk, it's the correct behavior. Determinism plus isomorphism turns the OG endpoint from a per-request renderer into a write-once asset factory. The first crawler to unfurl 64+5 pays for the render; every subsequent one, across every platform, gets a CDN hit.

That's the combination I want to underline: a deterministic engine alone gives you a cacheable answer; an isomorphic render gives you a cacheable picture that's guaranteed to match what users see. Together they make the share card free to serve at scale.

The Honest Edge Cases

"Byte-for-byte identical" is the goal and the day-to-day reality of this design, but I'd be lying if I called it a mathematical guarantee across every platform. The browser's Canvas implementation and @napi-rs/canvas are different engines — Skia under the Node binding, the browser's own compositor in front. Antialiasing can differ at the sub-pixel level. Text metrics from measureText can disagree by a fraction, which on a long wrapped line can occasionally push a word to the next row in one environment and not the other.

So what does isomorphism actually buy if it's not a bit-exact promise? It removes the structural source of drift — the second renderer with its own layout opinions. Both environments run the same drawCard against the same Canvas 2D API with the same fonts and the same dimensions, so they agree on everything the code decides: positions, sizes, colors, wrap points computed from the same measureText logic. What's left to disagree on is the rendering engine's own pixel-level rasterization, and that's a far smaller, far more bounded gap than "two people wrote two layouts." In practice, on the platforms that matter, the cards are indistinguishable. The mitigation is the architecture: one function, one API, one set of inputs.

A few reasonable alternatives, and why I passed on them:

Satori / SVG-to-image. Satori is excellent for OG images, but it renders a subset of CSS flexbox to SVG — it's a different rendering model from Canvas 2D. Adopting it for the server would mean the in-browser card (Canvas) and the OG card (Satori) are two renderers again, with the exact drift I was trying to kill. The whole point was one routine; Satori reintroduces two.
Headless browser screenshots. Spinning up Chromium per OG request would give pixel-perfect parity with the browser card — at the cost of hundreds of megabytes of runtime, slow cold starts, and a fragile dependency for a toy that's meant to ship as one small Docker container. The card is a few shapes and some text; paying for a whole browser to draw it is the wrong trade.
A static SVG template. Cheapest to render, but SVG text layout, wrapping, and font handling diverge from Canvas, and you're back to maintaining a second layout that has to chase the first.

@napi-rs/canvas won because it's the only option that lets the server run the same code as the browser. Every alternative trades that away for something else.

Results

Metric	Value
Renderers	1 — single `drawCard()` routine, run in browser and on the server
Module format	UMD (`card-core.js`) — `module.exports` in Node, global in the browser
Server canvas	`@napi-rs/canvas` — Skia-backed, same Canvas 2D API as the browser
OG endpoint logic	3 lines — create canvas, call shared core, `toBuffer('image/png')`
Card size	1080×1080 PNG, dimensions from `core.W` / `core.H` (single source)
Font fallback	Per-glyph chain — Russo One, Noto (Thai/Arabic/JP/KR), Noto Color Emoji
Fonts	OFL faces fetched at build time, baked into the Docker image
OG image cache	`immutable, max-age=31536000` — deterministic output never re-renders
Runtime deps	3 total (Express, @napi-rs/canvas, ioredis)
Deploy	Single Docker container on Coolify

Takeaways

If two outputs must match, generate them from one source. The reliable way to make the browser card and the unfurl card identical isn't to carefully keep two renderers in sync — it's to have one renderer. Any time you find yourself mirroring layout logic across environments, ask whether a shared routine can replace both.
Pick the API both runtimes already speak. Canvas 2D works in the browser and, via @napi-rs/canvas, in Node. Writing against that bare common API — and nothing environment-specific — is what makes the same function portable. UMD packaging is the small glue that lets one file load in both places with no build step.
The browser hides whole subsystems; the server makes you rebuild them. Font fallback is the classic example. What's automatic and invisible in a browser becomes an explicit per-glyph fallback chain plus a build step to ship the font files. Budget for the seams — isomorphism removes duplicated logic, not duplicated environments.
Determinism and isomorphism compound. A deterministic engine gives you a cacheable answer; an isomorphic render gives you a picture that provably matches what users see. Together they let you cache the OG image immutable for a year — write once, serve from the edge forever.
"Identical" is an architecture, not a guarantee. Two rendering engines can still differ at the antialiasing and text-metrics level. You can't eliminate that by writing more code — you eliminate the structural drift by running one routine against one API with one set of inputs, and accept that the residual gap is bounded and, in practice, invisible.

The full project — the deterministic Wrong Engine, 17-language i18n, server-side per-link SEO, and a spoof-proof Hall of Fame — is written up in the Wrongulator project card. For the engine half of this story, see why the wrong answer is the same every time.

PDF Tamper Detection API for Go: Integration Guide

Iurii Rogulia — Sat, 18 Jul 2026 10:00:35 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

PDF fraud is a backend problem. The forged bank statement, the altered invoice, the doctored payslip — none of it reaches a human reviewer untouched. By the time your Go handler has written a row to the database and returned 201, the document’s claims have already propagated into your business logic. The right place to catch the structural-tampering layer is at ingress: before your service trusts the file, not after.

This guide walks through integrating the PDF tamper detection API into a Go service — from the first curl command to an idiomatic client built on net/http, encoding/json, and context, with a typed result struct, error handling that distinguishes retryable failures from permanent ones, and a small bank-statement gate that decides accept / reject / review. The code compiles and runs the real request flow against the documented error codes; adapt and harden it for your own traffic profile and threat model. (If you want the conceptual overview first, start with How to Detect PDF Tampering Programmatically. If you are integrating from Node.js, Python, or PHP instead, see the Node.js, Python, and Laravel / PHP guides.)

TL;DR

Two API calls, three verdicts: POST /analyze returns a check id, GET /result/{id} returns the flat verdict object with status being one of intact, modified, or inconclusive.
Minimum integration is the standard library — net/http plus encoding/json, no third-party dependency.
Production-grade client: a typed Result struct, context.Context timeouts, a retry loop that backs off on 5xx and 429 only, and a parsed Retry-After.
A Gate example that maps the three verdicts to an Accept / Reject / Review decision for documents that claim institutional origin.
This is structural PDF tamper and forgery detection — not KYC, not OCR, not AI-text detection. It complements an identity stack; it does not replace one.

Prerequisites

Go 1.21+ (for errors.Join, slog, and the stable context ergonomics used below)
An HTPBE API key (Dashboard → copy key)
No external modules — everything below is standard library

Step 1: Test the API with curl

Before writing any Go, confirm your key works. The API uses a two-step flow: POST /analyze submits a PDF URL and returns a check id, then GET /result/{id} retrieves the full verdict. (For a language-agnostic overview of what the API detects, see how PDF tamper detection works.)

Step 1a — submit for analysis:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://api.htpbe.tech/v1/test/clean.pdf"}'

You will receive: {"id": "00000000-0000-4000-8000-000000000001"}

Step 1b — retrieve the result:

curl https://api.htpbe.tech/v1/result/YOUR_CHECK_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

You will receive a flat JSON object with "status": "intact" and the full set of analysis fields:

{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "intact",
  "origin": { "type": "institutional", "software": null },
  "creator": "Adobe Acrobat Pro DC",
  "producer": "Adobe PDF Library 15.0",
  "modification_confidence": "none",
  "has_incremental_updates": false,
  "update_chain_length": 1,
  "signature_removed": false,
  "modifications_after_signature": false,
  "modification_markers": []
}

(The real response carries every field documented in the struct below.) The same shape comes back for modified and inconclusive verdicts — only the values change. Two fields are conditional: status_reason appears only when status is inconclusive, and outdated_warning only when the check ran against an older algorithm version.

Step 2: The Result Struct

Define a struct that mirrors the GET /result/{id} response. Go’s encoding/json ignores unknown fields by default, so new API fields never break unmarshalling. Use pointer types (*int64, *string) for the fields the API documents as nullable — that lets you distinguish “absent” from a genuine zero value, which matters for timestamps and the producer string.

package htpbe

// Result mirrors the flat GET /result/{id} response.
// Nullable fields use pointers so "absent" is distinguishable from zero.
type Result struct {
    ID       string `json:"id"`
    Filename string `json:"filename"`
    FileSize int64  `json:"file_size"`
    PageCount int   `json:"page_count"`

    AlgorithmVersion        string `json:"algorithm_version"`
    CurrentAlgorithmVersion string `json:"current_algorithm_version"`
    OutdatedWarning         string `json:"outdated_warning"`

    // Primary verdict: "intact" | "modified" | "inconclusive"
    Status string `json:"status"`
    // StatusReason is present only when Status == "inconclusive":
    // "consumer_software_origin" | "online_editor_origin" |
    // "scanned_document" | "unverifiable_metadata"
    StatusReason string `json:"status_reason"`

    Origin struct {
        // "consumer_software" | "institutional" | "unknown" |
        // "online_editor" | "scanned"
        Type     string  `json:"type"`
        Software *string `json:"software"`
    } `json:"origin"`

    // "certain" | "high" | "none" | null
    ModificationConfidence *string `json:"modification_confidence"`

    Creator          *string `json:"creator"`
    Producer         *string `json:"producer"`
    CreationDate     *int64  `json:"creation_date"`     // Unix seconds
    ModificationDate *int64  `json:"modification_date"` // Unix seconds
    PDFVersion       *string `json:"pdf_version"`

    DateSequenceValid         bool `json:"date_sequence_valid"`
    MetadataCompletenessScore int  `json:"metadata_completeness_score"`

    XrefCount            int  `json:"xref_count"`
    HasIncrementalUpdates bool `json:"has_incremental_updates"`
    UpdateChainLength    int  `json:"update_chain_length"`

    HasDigitalSignature        bool `json:"has_digital_signature"`
    SignatureCount             int  `json:"signature_count"`
    SignatureRemoved           bool `json:"signature_removed"`
    ModificationsAfterSignature bool `json:"modifications_after_signature"`

    ObjectCount      int  `json:"object_count"`
    HasJavascript    bool `json:"has_javascript"`
    HasEmbeddedFiles bool `json:"has_embedded_files"`

    // Stable HTPBE_* marker ids, e.g. ["HTPBE_SIGNATURE_REMOVED"].
    // Empty when Status is "intact" or "inconclusive".
    ModificationMarkers []string `json:"modification_markers"`
}

Two fields deserve a closer look. StatusReason is populated only when Status is inconclusive, and it carries one of several values — consumer_software_origin, online_editor_origin, scanned_document, and a few more. The difference matters: a scanned document is benign for a user-submitted handwritten form, but a consumer_software_origin on something that claims to be a payslip is a strong signal to route for review — the kind of origin you would not expect from a real payroll system, covering both consumer apps and freely available HTML-to-PDF renderers. Branch on the specific reason, not just on the top-level inconclusive.

ModificationMarkers returns stable machine-readable ids prefixed HTPBE_ — for example HTPBE_SIGNATURE_REMOVED, HTPBE_DATES_DISAGREE, HTPBE_MULTIPLE_REVISION_LAYERS, HTPBE_POST_SIGNATURE_EDIT. Branch your integration logic on the id; render the human-readable label from the dictionary published on htpbe.tech/how. These ids are part of the public contract and never change once shipped.

It is worth defining named constants for the verdicts so the rest of your codebase never compares against bare string literals:

const (
    StatusIntact       = "intact"
    StatusModified     = "modified"
    StatusInconclusive = "inconclusive"
)

Step 3: A Typed Error

A 401 means your key is wrong; a 402 means the credit pool is dry; a 500 is transient. The retry loop and your business logic both need to branch on the status code, so wrap every non-2xx response in a typed error that carries it.

package htpbe

import "fmt"

// APIError is returned for any non-2xx response from the API.
type APIError struct {
    StatusCode      int
    Code            string // machine-readable code from the JSON body, when present
    Message         string
    RetryAfterSecs  int // parsed from Retry-After on 429; 0 when absent
}

func (e *APIError) Error() string {
    return fmt.Sprintf("htpbe: %d %s: %s", e.StatusCode, e.Code, e.Message)
}

// Retryable reports whether retrying the same request could succeed.
// Only 5xx and 429 are transient; 4xx (other than 429) are permanent.
func (e *APIError) Retryable() bool {
    return e.StatusCode >= 500 || e.StatusCode == 429
}

Step 4: The Client

Here is a complete client on the standard library. Verify chains both calls and returns the full result; callers pass a context.Context so the whole round trip honours a deadline or a cancelled request.

A subtlety the retry logic gets right: POST /analyze is the billable, job-creating step. Each successful POST starts a new analysis and draws a credit. GET /result/{id} is a free read. So the two steps are retried independently — the POST is retried on its own until it yields an id, and once that id is in hand a failed GET is retried by re-reading the same result, never by replaying the POST. Wrapping the whole flow in one retry loop would re-submit (and re-bill) a fresh analysis every time a transient GET failure occurred; this client never does that.

package htpbe

import (
    "bytes"
    "context"
    "encoding/json"
    "errors"
    "fmt"
    "io"
    "net/http"
    "strconv"
    "strings"
    "time"
)

const defaultBaseURL = "https://api.htpbe.tech/v1"

// Client is a reusable, concurrency-safe HTPBE API client.
type Client struct {
    apiKey     string
    baseURL    string
    httpClient *http.Client
    maxRetries int
}

// Option configures a Client.
type Option func(*Client)

// WithHTTPClient overrides the default *http.Client. A nil value is ignored
// so the option can never produce a nil-deref at request time.
func WithHTTPClient(hc *http.Client) Option {
    return func(c *Client) {
        if hc != nil {
            c.httpClient = hc
        }
    }
}
func WithBaseURL(u string) Option { return func(c *Client) { c.baseURL = u } }
func WithMaxRetries(n int) Option { return func(c *Client) { c.maxRetries = n } }

// New constructs a Client. The apiKey is required.
func New(apiKey string, opts ...Option) (*Client, error) {
    if apiKey == "" {
        return nil, errors.New("htpbe: API key is required")
    }
    c := &Client{
        apiKey:     apiKey,
        baseURL:    defaultBaseURL,
        httpClient: &http.Client{Timeout: 35 * time.Second},
        maxRetries: 3,
    }
    for _, opt := range opts {
        opt(c)
    }
    // Tolerate a trailing slash so callers can pass either form of the base URL.
    c.baseURL = strings.TrimRight(c.baseURL, "/")
    return c, nil
}

type analyzeRequest struct {
    URL              string `json:"url"`
    OriginalFilename string `json:"original_filename,omitempty"`
}

type analyzeResponse struct {
    ID string `json:"id"`
}

type errorBody struct {
    Error string `json:"error"`
    Code  string `json:"code"`
}

// Verify submits a PDF URL and returns the full verdict. The two steps are
// retried independently: POST /analyze (the billable step) is retried until
// it yields an id, then GET /result/{id} (a free read) is retried on its own.
// A failed GET never replays the POST, so a transient read failure cannot
// create a duplicate analysis job. The context governs cancellation and the
// overall deadline.
//
// originalFilename is optional; pass it so the result's `filename` field
// shows a human-readable name instead of an opaque storage key.
func (c *Client) Verify(ctx context.Context, pdfURL, originalFilename string) (*Result, error) {
    if pdfURL == "" {
        return nil, errors.New("htpbe: pdfURL is required")
    }

    // Step 1: submit for analysis (billable — retried in isolation).
    id, err := c.withRetry(ctx, func() (string, error) {
        return c.submitAnalysis(ctx, pdfURL, originalFilename)
    })
    if err != nil {
        return nil, err
    }

    // Step 2: read the result (free — retried in isolation, never replays POST).
    var result *Result
    _, err = c.withRetry(ctx, func() (string, error) {
        r, e := c.getResult(ctx, id)
        if e != nil {
            return "", e
        }
        result = r
        return id, nil
    })
    if err != nil {
        return nil, err
    }
    return result, nil
}

// withRetry runs op until it succeeds, backing off only on Retryable() API
// errors (5xx, 429). It honours a parsed Retry-After and the context deadline.
func (c *Client) withRetry(ctx context.Context, op func() (string, error)) (string, error) {
    var lastErr error
    for attempt := 0; attempt <= c.maxRetries; attempt++ {
        if attempt > 0 {
            // Honour a server-supplied Retry-After on 429; otherwise
            // exponential backoff: 1s, 2s, 4s.
            delay := time.Duration(1<<(attempt-1)) * time.Second
            var apiErr *APIError
            if errors.As(lastErr, &apiErr) && apiErr.RetryAfterSecs > 0 {
                delay = time.Duration(apiErr.RetryAfterSecs) * time.Second
            }
            select {
            case <-ctx.Done():
                return "", ctx.Err()
            case <-time.After(delay):
            }
        }

        v, err := op()
        if err == nil {
            return v, nil
        }
        lastErr = err
        if apiErr := asAPIError(err); apiErr != nil && !apiErr.Retryable() {
            return "", err // permanent — do not retry
        }
    }
    return "", fmt.Errorf("htpbe: exhausted retries: %w", lastErr)
}

func (c *Client) submitAnalysis(ctx context.Context, pdfURL, originalFilename string) (string, error) {
    body, err := json.Marshal(analyzeRequest{URL: pdfURL, OriginalFilename: originalFilename})
    if err != nil {
        return "", fmt.Errorf("htpbe: marshal request: %w", err)
    }

    req, err := http.NewRequestWithContext(ctx, http.MethodPost,
        c.baseURL+"/analyze", bytes.NewReader(body))
    if err != nil {
        return "", err
    }
    req.Header.Set("Authorization", "Bearer "+c.apiKey)
    req.Header.Set("Content-Type", "application/json")

    resp, err := c.httpClient.Do(req)
    if err != nil {
        return "", fmt.Errorf("htpbe: analyze request: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode/100 != 2 {
        return "", parseError(resp)
    }

    var ar analyzeResponse
    if err := json.NewDecoder(resp.Body).Decode(&ar); err != nil {
        return "", fmt.Errorf("htpbe: decode analyze response: %w", err)
    }
    if ar.ID == "" {
        return "", errors.New("htpbe: analyze response missing id")
    }
    return ar.ID, nil
}

func (c *Client) getResult(ctx context.Context, id string) (*Result, error) {
    req, err := http.NewRequestWithContext(ctx, http.MethodGet,
        c.baseURL+"/result/"+id, nil)
    if err != nil {
        return nil, err
    }
    req.Header.Set("Authorization", "Bearer "+c.apiKey)

    resp, err := c.httpClient.Do(req)
    if err != nil {
        return nil, fmt.Errorf("htpbe: result request: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode/100 != 2 {
        return nil, parseError(resp)
    }

    var result Result
    if err := json.NewDecoder(resp.Body).Decode(&result); err != nil {
        return nil, fmt.Errorf("htpbe: decode result: %w", err)
    }
    return &result, nil
}

// parseError builds a typed APIError from a non-2xx response.
func parseError(resp *http.Response) error {
    raw, _ := io.ReadAll(io.LimitReader(resp.Body, 1<<16))

    var eb errorBody
    _ = json.Unmarshal(raw, &eb) // best effort — body may not be JSON

    apiErr := &APIError{
        StatusCode: resp.StatusCode,
        Code:       eb.Code,
        Message:    eb.Error,
    }
    if apiErr.Message == "" {
        apiErr.Message = http.StatusText(resp.StatusCode)
    }

    switch resp.StatusCode {
    case http.StatusUnauthorized: // 401
        apiErr.Message = "invalid API key — check the HTPBE_API_KEY environment variable"
    case http.StatusPaymentRequired: // 402
        apiErr.Message = "no credits available for this key — top up or subscribe"
    case http.StatusRequestEntityTooLarge: // 413
        apiErr.Message = "PDF exceeds the 10 MB size limit"
    case http.StatusUnprocessableEntity: // 422
        apiErr.Message = "the URL did not return a valid PDF file"
    case http.StatusTooManyRequests: // 429
        apiErr.RetryAfterSecs = parseRetryAfter(resp.Header.Get("Retry-After"))
    }
    return apiErr
}

// parseRetryAfter handles the delay-seconds form ("30") and the HTTP-date
// form, clamping the result to a sane [1, 600] range. Returns 0 when absent
// or unparseable so callers fall back to their own backoff.
func parseRetryAfter(h string) int {
    if h == "" {
        return 0
    }
    if secs, err := strconv.Atoi(h); err == nil {
        return clamp(secs, 1, 600)
    }
    if t, err := http.ParseTime(h); err == nil {
        return clamp(int(time.Until(t).Seconds()), 1, 600)
    }
    return 0
}

func clamp(v, lo, hi int) int {
    if v < lo {
        return lo
    }
    if v > hi {
        return hi
    }
    return v
}

func asAPIError(err error) *APIError {
    var apiErr *APIError
    if errors.As(err, &apiErr) {
        return apiErr
    }
    return nil
}

Two status codes deserve explicit handling in your own code:

402 (Payment Required) — the key has no credit source left. Credits are universal: a subscription’s monthly quota, a one-time top-up batch, and the welcome credits all draw from one pool. A 402 means all three are exhausted (or there is no active plan on a live key). APIError.Retryable() returns false for it — surface it to your billing logic rather than retrying, because retrying fails identically until the account is topped up at the pricing page.
429 (Too Many Requests) — this is server-wide concurrency, not per-key rate limiting. The response carries a Retry-After header, which parseError parses (handling both delay-seconds and HTTP-date forms, clamped to [1, 600]) and stashes on APIError.RetryAfterSecs. The retry loop reads that value before falling back to exponential backoff.

Step 5: The Bank-Statement Gate

The client returns facts. Turning those facts into an accept / reject / review decision is a policy choice that depends on what the document claims to be. A bank statement, a payslip, or a diploma claims institutional origin, so anything other than intact should stop the automated path. A user-generated form is held to a looser standard.

package htpbe

// Decision is the routing outcome for a verified document.
type Decision string

const (
    Accept Decision = "accept"
    Reject Decision = "reject"
    Review Decision = "review"
)

// GateInstitutional maps a verdict to a decision for documents that
// claim institutional origin (bank statements, payslips, diplomas).
// For these, "inconclusive" is treated as strictly as "modified":
// a document that should have come from a bank's system but looks
// like it was built in Word does not get the benefit of the doubt.
func GateInstitutional(r *Result) Decision {
    switch r.Status {
    case StatusModified:
        return Reject
    case StatusInconclusive:
        // A bank statement that comes back inconclusive should not be
        // auto-accepted: it typically came from consumer software rather
        // than a bank's own system, which is a signal to route for review
        // — not proof of tampering. Route to a human.
        return Review
    default: // StatusIntact
        return Accept
    }
}

Wire the client and the gate into an HTTP handler that accepts a JSON body with a reachable URL. The handler runs the check before any business logic touches the file:

package main

import (
    "context"
    "encoding/json"
    "errors"
    "log/slog"
    "net/http"
    "os"
    "time"

    "yourapp/htpbe"
)

type verifyRequest struct {
    DocumentURL      string `json:"document_url"`
    OriginalFilename string `json:"original_filename"`
}

func main() {
    client, err := htpbe.New(os.Getenv("HTPBE_API_KEY"))
    if err != nil {
        slog.Error("htpbe init failed", "err", err)
        os.Exit(1)
    }

    http.HandleFunc("POST /api/documents", func(w http.ResponseWriter, req *http.Request) {
        var body verifyRequest
        if err := json.NewDecoder(req.Body).Decode(&body); err != nil || body.DocumentURL == "" {
            http.Error(w, `{"error":"document_url is required"}`, http.StatusBadRequest)
            return
        }

        // Bound the whole two-step round trip to 40 seconds.
        ctx, cancel := context.WithTimeout(req.Context(), 40*time.Second)
        defer cancel()

        result, err := client.Verify(ctx, body.DocumentURL, body.OriginalFilename)
        if err != nil {
            var apiErr *htpbe.APIError
            if errors.As(err, &apiErr) {
                switch apiErr.StatusCode {
                case http.StatusUnauthorized, http.StatusPaymentRequired:
                    // Configuration / billing error — never expose details to the caller.
                    slog.Error("htpbe misconfigured", "code", apiErr.Code)
                    http.Error(w, `{"error":"verification temporarily unavailable"}`, http.StatusServiceUnavailable)
                    return
                case http.StatusUnprocessableEntity:
                    http.Error(w, `{"error":"the URL did not return a valid PDF"}`, http.StatusUnprocessableEntity)
                    return
                case http.StatusRequestEntityTooLarge:
                    http.Error(w, `{"error":"PDF must be under 10 MB"}`, http.StatusRequestEntityTooLarge)
                    return
                }
            }
            slog.Error("htpbe verify failed", "err", err)
            http.Error(w, `{"error":"verification failed"}`, http.StatusBadGateway)
            return
        }

        switch htpbe.GateInstitutional(result) {
        case htpbe.Reject:
            writeJSON(w, http.StatusUnprocessableEntity, map[string]any{
                "decision":             "reject",
                "reason":               "document modified after creation",
                "modification_markers": result.ModificationMarkers,
            })
        case htpbe.Review:
            writeJSON(w, http.StatusAccepted, map[string]any{
                "decision":      "review",
                "status_reason": result.StatusReason,
            })
        default: // Accept
            writeJSON(w, http.StatusOK, map[string]any{
                "decision": "accept",
                "check_id": result.ID,
            })
        }
    })

    slog.Info("listening on :8080")
    _ = http.ListenAndServe(":8080", nil)
}

func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    _ = json.NewEncoder(w).Encode(v)
}

Step 6: Giving the API a Reachable URL

The API does not accept file uploads — it downloads the PDF from a URL you supply, so the file must be publicly reachable for the 2–5 seconds the analysis takes. The cleanest pattern is a short-lived presigned URL from your object store: you never expose the bucket, the link expires in minutes, and passing originalFilename keeps the audit trail readable instead of showing the opaque storage key.

// Store the upload privately, mint a 5-minute presigned GET URL, verify.
key := "incoming/" + uuid.NewString() + ".pdf"
if _, err := s3Client.PutObject(ctx, &s3.PutObjectInput{
    Bucket: &bucket, Key: &key,
    Body: bytes.NewReader(data), ContentType: aws.String("application/pdf"),
}); err != nil {
    return nil, err
}
presigned, err := presigner.PresignGetObject(ctx, &s3.GetObjectInput{
    Bucket: &bucket, Key: &key,
}, s3.WithPresignExpires(5*time.Minute))
if err != nil {
    return nil, err
}
return client.Verify(ctx, presigned.URL, originalFilename)

The same pattern works with Google Cloud Storage (SignedURL on a bucket handle) or Cloudflare R2 (S3-compatible — reuse this with the R2 endpoint). One security note: the API fetches whatever URL you give it, so if a URL ever comes from untrusted input (a user-pasted link, a webhook payload), validate that it resolves to a public host first — reject localhost, 169.254.169.254 (cloud metadata), and RFC 1918 ranges to close the SSRF surface.

Batch Processing, Test Mode, and Quota

A few operational details, kept short.

Synchronous flow. Analysis is synchronous: POST /analyze blocks until the verdict is computed, then returns the id, and the response also carries a Location header pointing at the result URL. There is no queue to poll and no webhook to register — by the time analyze returns, GET /result/{id} is ready. Verify chains both, so one call gives you the full verdict.

Batch work. For a backlog of statements or a portfolio of claims, fan out across a bounded number of goroutines and let the shared Client reuse its connection pool. Keep the worker count modest: the client retries on 429, but capping concurrency means you rarely hit capacity in the first place.

func verifyBatch(ctx context.Context, client *htpbe.Client, urls []string) map[string]*htpbe.Result {
    const workers = 8 // stay within your plan's concurrency comfort zone
    sem := make(chan struct{}, workers)
    results := make(map[string]*htpbe.Result)
    var mu sync.Mutex
    var wg sync.WaitGroup

    for _, u := range urls {
        wg.Add(1)
        sem <- struct{}{}
        go func(pdfURL string) {
            defer wg.Done()
            defer func() { <-sem }()
            r, err := client.Verify(ctx, pdfURL, "")
            if err != nil {
                slog.Warn("verify failed", "url", pdfURL, "err", err)
                return
            }
            mu.Lock()
            results[pdfURL] = r
            mu.Unlock()
        }(u)
    }
    wg.Wait()
    return results
}

Test mode. Every plan includes a test API key (prefix htpbe_test_) that accepts only mock URLs of the form https://api.htpbe.tech/v1/test/{filename}.pdf and returns deterministic responses — like Stripe test cards, with no quota cost. Useful fixtures: clean.pdf → intact, signature-removed.pdf → modified, dates-mismatch.pdf → modified, and inconclusive.pdf → inconclusive. Point Verify at these in your testing suite to cover every branch of the gate; for handler unit tests without the network, point the client at an httptest.Server via WithBaseURL and serve canned JSON for /analyze and /result/{id}. Keep test and live keys in separate environment files and never commit either.

Reviewing past checks. GET /api/v1/checks returns a paginated list of every result for your key — filter by status and limit for audit dashboards or weekly reports (c.baseURL+"/checks?status=modified&limit=50", same Authorization header as the other calls).

Quota. When you reach your monthly quota, further requests return 402 PAYMENT_REQUIRED until it resets — add a one-time credit pack or move to a higher tier to keep going. Handle the 402 so a quota boundary never silently drops a check, and watch consumption on the dashboard.

What This Does Not Catch

Structural analysis has honest limits, and a Go service making automated decisions should encode them:

Content fabricated in one pass. If someone opens Word, types a false salary, and exports once, the file was never modified post-creation — it is structurally intact. The fraud happened at authorship, not at the byte level. This is why a payslip from a consumer tool tends to return inconclusive rather than intact: the analysis cannot vouch for a document anyone could have created from scratch.
Documents rebuilt from scratch in the original’s software. A determined attacker who recreates a document in the same institutional tool and matches the metadata fields leaves few structural signals. This is rare and high-effort, but possible.
Encrypted or password-protected PDFs. The service cannot parse a file it cannot open; remove the password before submitting.

Decisions Before You Ship

The integration surface is intentionally small: one POST, one GET, three verdicts, the typed error above. The complexity lives on the Go side, and two choices matter most:

Where verification runs. Synchronous inside the request handler gives the caller an immediate decision but blocks for 2–5 seconds; a goroutine or queue consumer returns instantly and defers the verdict. Sync suits low-volume B2B onboarding; async suits high-volume portals.
inconclusive routing. For documents that claim institutional origin (bank statements, diplomas, payslips), treat inconclusive with the same caution as modified and route to human review. For genuinely user-generated content it may be acceptable as-is — that is what GateInstitutional encodes, and you may want a second gate with a looser policy.

Adding Semantic Search to Internal Docs in 200 Lines

Iurii Rogulia — Fri, 17 Jul 2026 10:00:48 +0000

Someone on your team asks in chat: "how do I cancel a customer's order after it shipped?" Your wiki has the answer. It's a page titled Returns and reversals — post-fulfilment procedure. Nobody finds it, because they searched for "cancel order" and the document never uses the word "cancel." So they ping a colleague, who re-explains a process that was already written down two years ago.

That gap is what semantic search over internal docs closes. Keyword search matches strings; people ask questions in their own words. This article is a compact, working recipe — chunk, embed, query by meaning — built on Postgres and pgvector, in roughly two hundred lines. It is strictly about retrieval: finding the right document. Not generating an answer on top of it. That distinction is the whole point, and I'll come back to why it matters.

Why Keyword Search Runs Out

LIKE '%cancel%' and even Postgres full-text search both match tokens. They are excellent when the searcher and the author happen to use the same words. They fall apart the moment they don't:

"how do I cancel a shipped order" vs. a doc titled "cancellation policy" — the policy page might never contain the verb the user typed.
"the app is slow after login" vs. "performance degradation on session initialization" — zero shared content words, same meaning.
"expense reimbursement" vs. "travel claims" — synonyms a keyword index treats as unrelated.

You can paper over some of this with synonym dictionaries and stemming, and full-text search with a good tsvector configuration genuinely helps. But you are maintaining a hand-curated thesaurus forever, and it still misses paraphrases nobody anticipated. Semantic search attacks the problem from the other side: it compares the meaning of the query to the meaning of each document, not the surface words.

The mechanism is embeddings. An embedding model maps a piece of text to a vector — a list of numbers — such that texts with similar meaning land close together in that space. "Cancel a shipped order" and "post-fulfilment reversal procedure" end up near each other even with no shared words. Search then becomes: embed the query, find the nearest document vectors, return those documents.

The Pipeline in Three Steps

The entire system is three moves:

Chunk each document into pieces of a sensible size, with a little overlap.
Embed every chunk once, at ingest time, and store the vectors.
Query: embed the incoming question, find the top-k nearest chunks by cosine distance, return them with a link back to the source.

That's it. There's no model being asked to write prose, no agent loop, no streaming. Just "given this question, here are the five most relevant passages and where they came from."

Storage: Postgres + pgvector

If you already run Postgres, you do not need a separate vector database to start. pgvector is a Postgres extension that adds a vector column type and distance operators. It keeps your documents and their embeddings in the same database you already back up, query, and monitor — which is reason enough for most internal-tooling cases. (I keep the rest of my Postgres habits in PostgreSQL production patterns; the same indexing discipline applies here.)

The schema. I'm using OpenAI's text-embedding-3-small, which produces 1536-dimensional vectors, so the column is vector(1536):

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE doc_chunks (
  id          BIGSERIAL PRIMARY KEY,
  source      TEXT NOT NULL,        -- file path, page ID, or ticket URL
  title       TEXT NOT NULL,        -- for citation in results
  url         TEXT,                 -- link back to the original
  chunk_index INTEGER NOT NULL,     -- position within the source doc
  content     TEXT NOT NULL,        -- the raw chunk text, returned to the user
  embedding   VECTOR(1536) NOT NULL,
  created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

The vector index is the part people get wrong. pgvector offers two index types. ivfflat partitions vectors into lists and is fast to build but needs you to set the list count and probes at query time. hnsw builds a graph, is slower to build and uses more memory, but gives better recall at a given speed and needs no list tuning. For an internal corpus that fits comfortably in memory, I default to hnsw. Crucially, the index operator class must match the distance operator you query with — cosine distance is <=>, so the index uses vector_cosine_ops:

CREATE INDEX ON doc_chunks
  USING hnsw (embedding vector_cosine_ops);

A note on honesty: for a corpus of a few hundred chunks, you don't even need an index — or pgvector — at all. A sequential scan over a few hundred vectors is milliseconds, and you could hold the whole thing in memory and compute cosine similarity in plain TypeScript. The Postgres path earns its keep when the corpus grows, when you want the data sitting next to the rest of your application state, and when concurrent queries matter.

Chunking

Chunking turns each document into the units you'll actually retrieve. The goal: each chunk should be a coherent, self-contained passage, big enough to carry meaning, small enough that its embedding represents one topic rather than a blur of several.

I split on structure first (headings, then paragraphs) and only fall back to a hard token cap when a section is too long. Overlap carries a little context across boundaries so a sentence split across two chunks still retrieves. This is illustrative — paragraph-aware, not exhaustive — but it's the shape I actually use:

// chunk.ts
import { encoding_for_model } from "tiktoken";

const MAX_TOKENS = 400; // target chunk size
const OVERLAP_TOKENS = 60; // carry-over between adjacent chunks

const enc = encoding_for_model("text-embedding-3-small");

function tokenLength(text: string): number {
  return enc.encode(text).length;
}

export interface Chunk {
  content: string;
  index: number;
}

export function chunkDocument(markdown: string): Chunk[] {
  // Split on blank lines (paragraphs / heading blocks) first.
  const blocks = markdown
    .split(/\n{2,}/)
    .map((b) => b.trim())
    .filter(Boolean);

  const chunks: string[] = [];
  let current: string[] = [];
  let currentTokens = 0;

  for (const block of blocks) {
    const blockTokens = tokenLength(block);

    // A single oversized block: hard-split it on token count.
    if (blockTokens > MAX_TOKENS) {
      if (current.length) {
        chunks.push(current.join("\n\n"));
        current = [];
        currentTokens = 0;
      }
      chunks.push(...splitOversized(block));
      continue;
    }

    if (currentTokens + blockTokens > MAX_TOKENS) {
      chunks.push(current.join("\n\n"));
      // Start the next chunk with a tail of the previous one for overlap.
      current = overlapTail(current, OVERLAP_TOKENS);
      currentTokens = tokenLength(current.join("\n\n"));
    }

    current.push(block);
    currentTokens += blockTokens;
  }

  if (current.length) chunks.push(current.join("\n\n"));

  return chunks.map((content, index) => ({ content, index }));
}

function splitOversized(block: string): string[] {
  const tokens = enc.encode(block);
  const out: string[] = [];
  for (let start = 0; start < tokens.length; start += MAX_TOKENS - OVERLAP_TOKENS) {
    const slice = tokens.slice(start, start + MAX_TOKENS);
    out.push(new TextDecoder().decode(enc.decode(slice)));
  }
  return out;
}

function overlapTail(blocks: string[], targetTokens: number): string[] {
  const tail: string[] = [];
  let count = 0;
  for (let i = blocks.length - 1; i >= 0 && count < targetTokens; i--) {
    tail.unshift(blocks[i]);
    count += tokenLength(blocks[i]);
  }
  return tail;
}

Embedding and Ingesting

Embed each chunk once, at ingest, and store the vector alongside its source metadata. Batch the calls — the embeddings endpoint accepts many inputs per request, which is both faster and cheaper than one call per chunk:

// ingest.ts
import OpenAI from "openai";
import { Pool } from "pg";
import { chunkDocument } from "./chunk";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const EMBEDDING_MODEL = "text-embedding-3-small";

interface SourceDoc {
  source: string;
  title: string;
  url?: string;
  body: string;
}

async function embedBatch(texts: string[]): Promise<number[][]> {
  const res = await openai.embeddings.create({
    model: EMBEDDING_MODEL,
    input: texts,
  });
  return res.data.map((d) => d.embedding);
}

export async function ingest(doc: SourceDoc): Promise<void> {
  const chunks = chunkDocument(doc.body);
  const embeddings = await embedBatch(chunks.map((c) => c.content));

  const client = await pool.connect();
  try {
    await client.query("BEGIN");
    // Re-ingest cleanly: drop the old chunks for this source first.
    await client.query("DELETE FROM doc_chunks WHERE source = $1", [doc.source]);

    for (let i = 0; i < chunks.length; i++) {
      await client.query(
        `INSERT INTO doc_chunks (source, title, url, chunk_index, content, embedding)
         VALUES ($1, $2, $3, $4, $5, $6)`,
        [
          doc.source,
          doc.title,
          doc.url ?? null,
          chunks[i].index,
          chunks[i].content,
          // pgvector accepts a vector literal: '[0.1,0.2,...]'
          `[${embeddings[i].join(",")}]`,
        ]
      );
    }
    await client.query("COMMIT");
  } catch (err) {
    await client.query("ROLLBACK");
    throw err;
  } finally {
    client.release();
  }
}

The DELETE-then-INSERT per source makes re-ingesting a single edited document idempotent: change a wiki page, re-run ingest for that one source, and its old chunks are replaced. For a large corpus where most documents are unchanged between runs, hash the content and skip embedding when the hash matches the stored one — embedding calls are cheap individually but add up across thousands of chunks. I cover that and the rest of the embedding-cost surface in reducing OpenAI API costs in production.

Query: Nearest Neighbours by Cosine Distance

At query time, embed the question with the same model used at ingest, then ask Postgres for the nearest chunks. The <=> operator is cosine distance — smaller is closer — so you ORDER BY embedding <=> $1 and LIMIT k:

// search.ts
import OpenAI from "openai";
import { Pool } from "pg";

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export interface SearchHit {
  title: string;
  url: string | null;
  source: string;
  content: string;
  distance: number; // 0 = identical direction, 2 = opposite
}

export async function search(query: string, k = 5): Promise<SearchHit[]> {
  const res = await openai.embeddings.create({
    model: "text-embedding-3-small", // must match the ingest model
    input: query,
  });
  const queryVector = `[${res.data[0].embedding.join(",")}]`;

  const { rows } = await pool.query<SearchHit>(
    `SELECT title, url, source, content,
            embedding <=> $1 AS distance
     FROM doc_chunks
     ORDER BY embedding <=> $1
     LIMIT $2`,
    [queryVector, k]
  );

  return rows;
}

That is the whole retrieval system. Chunking, ingest, and search together land in the low hundreds of lines — call it the order of two hundred — because the hard parts of a full RAG stack are deliberately absent. No answer generation, no reranker, no UI, no streaming. The output is a ranked list of real passages with a title, a url, and a distance you can show as a relevance hint. Wire it to a search box and a list of links, and people find documents by meaning.

Chunking Is Where the Quality Lives

If you take one thing from this article: the embedding model is rarely your bottleneck. Chunking is. A worse model with good chunks beats a great model with bad ones.

Chunks that are too large blur multiple topics into one vector, so the chunk matches everything weakly and nothing strongly. Chunks that are too small lose the context that made them meaningful — a sentence retrieved without its surrounding paragraph is often useless to whoever reads it. Split a procedure in the middle of a numbered list and the retrieved fragment answers half a question.

The levers that move relevance more than model choice:

Split on structure, not character count. Honour headings and paragraph boundaries. A chunk that maps to one section of a doc retrieves far better than one cut at an arbitrary 500-character mark.
Carry metadata. Store title and url with every chunk. You need them to cite the source and link back — the entire value proposition is "here's the document," not "here's an orphan paragraph."
Tune overlap. A small overlap (10–15% of chunk size) keeps boundary-straddling ideas retrievable. Too much overlap inflates storage and returns near-duplicate hits.

There is no universal chunk size. 400 tokens is a reasonable default for prose handbooks; dense reference material or short FAQ entries want different settings. You find yours by running real queries from your team against the index and reading what comes back.

slug="ai-integration"
text="Have the docs but can't find them by meaning? I build semantic search over internal wikis, handbooks, and ticket history — Postgres-native, retrieval-first, no hallucinated answers."
/>

Where Semantic Search Falls Short — Honestly

Pure vector search is a tool, not a search oracle. The places it disappoints are predictable, so plan for them.

It loses to keyword matching on exact terms. Error codes, function names, SKUs, ticket IDs, acronyms — embeddings generalize, which is exactly wrong when the user wants ERR_2043 and not "errors that feel similar." For any corpus where exact tokens matter, the answer is a hybrid: run vector search and keyword (Postgres full-text or BM25) in parallel and combine the rankings. Add a reranking step when the stakes justify the extra latency and cost. If your internal docs are full of identifiers, treat hybrid as the baseline, not an upgrade.

Chunking is fragile and has no settled answer. Too coarse and you retrieve noise; too fine and you retrieve context-free fragments. The right size depends on your content, and you only learn it by testing against your own queries. Expect to re-tune it after you see real usage.

Embeddings go stale, and re-embedding has a cost. Edit a document and its old chunks no longer match the new text — you must re-embed that source. Worse: if you switch embedding models, vectors from the old model and the new one live in incompatible spaces and cannot be compared. Changing models means re-embedding the entire corpus. Pin your model version and treat a model change as a migration, not a config tweak.

It returns similar, not correct. Nearest-neighbour search gives you the passages closest in meaning to the query. "Closest" is not "right." The top hit can be a confidently-worded but outdated policy; the embedding has no notion of which document is authoritative or current. You must validate ranking quality on real queries from your team and keep the source documents trustworthy — garbage in, confidently-ranked garbage out.

Sometimes you don't need it at all. A few dozen documents? Ctrl+F and Postgres full-text search are simpler, free, and good enough — adding an embedding pipeline is over-engineering. When exact matching matters more than meaning, keyword search is the right primary, not a fallback. Reach for semantic search when the corpus is large enough that browsing fails and paraphrase is the actual problem.

Every one of these is manageable. None of them is hidden if you go in expecting it.

Search Returns Documents. A Chatbot Writes Answers.

This is the line worth drawing clearly. Everything above retrieves — it hands back real passages and links, and it never invents anything, because there's no generation step to invent with. That's a feature: a search box that returns the actual returns-policy page cannot hallucinate a returns policy. For "nobody can find the doc," retrieval alone solves the problem.

If you want a bot that reads those passages and writes a natural-language answer on top of them — "To cancel a shipped order, create a reversal in the admin panel, then…" — that's the next layer: retrieval-augmented generation. It adds an LLM, a confidence threshold so it escalates instead of guessing, source citation, and a streaming UI, plus a new failure mode the search-only version doesn't have (a model can phrase a wrong answer fluently). I built that end to end for an e-commerce support desk — across 25 languages, resolving 70% of tickets without a human — in the RAG chatbot architecture write-up. The semantic search here is the retrieval half of that system, useful entirely on its own.

Most teams I talk to think they need the chatbot. They need the search. Build the retrieval layer first, watch what people actually ask, and only add generation if returning documents turns out not to be enough.

Takeaways

Keyword search matches words; people ask by meaning. Semantic search closes that gap by comparing the meaning of the query to the meaning of each chunk.
The pipeline is three steps: chunk with overlap, embed once at ingest, query by cosine distance (<=>) for the top-k nearest chunks. On Postgres + pgvector it's roughly two hundred lines.
Chunking, not the model, decides quality. Split on structure, carry title/url metadata for citation, tune overlap, and test against your own queries.
Go hybrid for exact terms. Error codes, SKUs, and acronyms need keyword/BM25 alongside vectors; pin your embedding model, because changing it means re-embedding everything.
Retrieval ≠ generation. Search returns documents and cannot hallucinate. A RAG chatbot writes an answer on top and can. Build search first.

If you're sitting on a wiki, a handbook, and years of tickets that your team can't search by meaning, that's exactly the kind of AI integration I do — retrieval-first, on the Postgres you already run, with the honest limits built in from the start rather than discovered later.

SBA-7a Loan Stip Fraud Detection: Post-PPP Lessons

Iurii Rogulia — Fri, 17 Jul 2026 10:00:39 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

The PPP wave was, in retrospect, the largest controlled experiment in small-business stip-doc fraud the lending industry has ever observed. The DOJ has publicly disclosed thousands of prosecutions; the SBA Office of the Inspector General has publicly estimated PPP and EIDL fraud losses in the tens of billions across the program. Whatever the exact number turns out to be after all enforcement and recovery cycles close, two facts are no longer in dispute: small-business document fraud is large, and the dominant attack pattern was not synthetic identity. It was real people uploading altered or fabricated PDFs — bank statements, tax returns, payroll registers, voided checks — built with mainstream consumer tools.

That has reshaped how fintech business lenders and SBA-7a preferred lenders run stip-doc review for the products that came after: 7(a) term loans, EIDL successors, working-capital lines, conventional small-business loans. Across fintech business lenders, SBA-7a preferred lenders, and platforms such as Funding Circle, Lendio, Bluevine, OnDeck, Fundbox, Square Capital, Stripe Capital, Live Oak, Newtek, and Celtic Bank, post-PPP review playbooks have converged on four recurring fraud patterns. This article walks through each one, the structural signals that flag it, and the honest limits of what file-level forensics can and cannot resolve.

Pattern 1 — Altered Business Bank Statements

The most common pattern, and the one closest to the consumer-lending playbook. A borrower downloads a real PDF statement from Wells Fargo Business, Chase Business, Bluevine, Mercury, or Brex, opens it in Adobe Acrobat or an online editor, and changes the figures that matter: average daily balance, ending balance, deposit count, NSF lines.

Structurally the editor leaves the same fingerprints it leaves on consumer statements:

The producer field shifts from the bank’s server-side engine to a consumer editor — Adobe Acrobat, iLovePDF, PDF24, Smallpdf, Preview. Public marker: HTPBE_ONLINE_EDITOR_ORIGIN or HTPBE_EDITING_TOOL_FINGERPRINT.
A second cross-reference layer appears, because every save-after-edit appends a new xref. Public marker: HTPBE_MULTIPLE_REVISION_LAYERS.
The modification timestamp lands hours or days after the declared creation timestamp. Public marker: HTPBE_DATES_DISAGREE.

A statement from Chase Business that was generated by chase.com server-side and re-saved through Acrobat on Tuesday afternoon will carry all three signals. The verdict comes back modified with high confidence. The consumer-side analogue is covered in bank statement fraud in lending, and the broader workflow context is in PDF fraud detection in loan origination.

Caveat that matters in practice: smaller business banking apps and credit unions sometimes export through generic print drivers. A inconclusive verdict on a statement claimed to be from one of the major business banks is itself a flag — route to verification. The same verdict on a small community-bank statement is closer to noise.

Pattern 2 — Fabricated Business Tax Returns

The most loss-prone document class and the one where honesty about scope matters most.

Business tax returns — Form 1120, 1120-S, and 1065 — were the structurally weakest control during PPP. Thousands of borrowers submitted returns that had never been filed with the IRS, because nothing in the upload-and-review workflow ever crossed back to the IRS to confirm filing. Two distinct attack types showed up in the post-loss reviews:

Type A — Edited real returns. The borrower starts from a genuine filed return and uses Acrobat to inflate gross receipts, net income, or owner compensation. This is structurally identical to bank-statement editing and produces the same markers: editor fingerprint, second revision layer, date disagreement. Structural forensics catches this type cleanly.

Type B — Clean rebuilds from scratch. The borrower (or a paid forger) generates a tax return from scratch using a programmatic PDF library — PDFKit, ReportLab, or a one-off Puppeteer template. The output is born synthetic: no editing history, no producer mismatch, no incremental updates. The fields are made up but the file looks pristine. Structural forensics returns inconclusive because the document was generated by a consumer-class toolchain, which is the correct verdict for what the byte layer actually reveals.

The IRS Form 4506-C tax-transcript request is the ground-truth verification for U.S. business tax returns — it pulls the IRS’s own record of what was actually filed and reconciles the borrower-supplied figures against it. In higher-control SBA-7a workflows, 4506-C is often treated as a hard gate on every tax return. The role of structural forensics on this document class is to catch Type A cheaply on day one and to sequence 4506-C ordering more efficiently — the modified files go to the front of the queue; the intact files still need 4506-C but the structural record adds context to the file.

Pattern 3 — Forged Voided Checks and Banking Attestations

A small document class with disproportionate downside. The voided check or bank-letter attestation supplied at funding determines which routing and account number the loan proceeds get wired to. A successful swap at this stage moves the money to an account the borrower controls but the lender has never seen mentioned in the application.

Two attack flavours:

Edited voided check. Borrower opens a screenshot or PDF of their own check in Acrobat and overwrites the routing or account digits. Structural signals fire as on any edited document: editor producer, incremental update layer, glyph-level edits if individual digits were replaced (HTPBE_GLYPH_LEVEL_EDIT, HTPBE_CHARACTER_OVERLAY_EDIT).
Rebuilt voided check. Borrower generates the image in any drawing tool, exports to PDF. Born-synthetic, returns inconclusive for the same reason as tax returns above.

The compensating control here is operational, not structural: a callback to the bank using a phone number from an independent source — the bank’s public website, not a number printed on the document. Structural forensics catches the editor-altered version on day one and reduces the queue that needs callback verification. It does not replace the callback for a born-synthetic rebuild.

Pattern 4 — PPP Forgiveness Applications (Retrospective)

This pattern is unusual because it is backward-looking, but it is now a live workstream at multiple SBA-7a lenders. The SBA Office of the Inspector General continues to audit PPP forgiveness decisions, and lenders defending those audits need to demonstrate the documentary basis on which forgiveness was approved.

For lenders that kept the original PDF application files, running structural forensics on those files now produces an audit-trail artifact: a persistent check_id, the verdict at the time of analysis, the markers present, the producer string, the timestamp layers. If a particular forgiveness file later becomes the subject of an OIG question, the lender has a contemporaneous structural record alongside the underwriter’s notes.

This is not a fraud-detection use case in the live-pipeline sense — the loans are already funded and forgiven. It is an audit-defence and discovery use case. Most of the lenders running this work batch-process the historical application files through the API once, store the check_id against the loan record, and surface it on demand when an OIG inquiry lands.

Where the Check Fits in an SBA-7a Stip Workflow

SBA-7a and conventional small-business loan files move on a 30–60 day clock. Adding a 1–4 second per-document structural check does not move the critical path. The integration points that have worked in production:

At stip-doc receipt — every uploaded business bank statement, tax return, voided check, and payroll register is sent to the API immediately. The verdict and markers attach to the document record in the LOS. modified files route to a fraud-ops queue before the credit decision; inconclusive files route based on what was claimed to be uploaded; intact files proceed.
Before funding wire — the voided check or bank-letter on file is re-checked at funding. This is the last point at which an account number could have been swapped between underwriting and disbursement.
Before SBA-7a guarantee package finalisation — for 7(a) loans, the package submitted to SBA for the guarantee includes the underlying stip docs. Running the check immediately before package assembly ensures the documents in the guarantee file match the structural record from intake.

A minimal integration call:

curl -X POST https://api.htpbe.tech/v1/analyze \
  -H "Authorization: Bearer $HTPBE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://files.example-lender.com/stips/1120-2025-borrower-12345.pdf",
    "tool": "sba-7a-stip-review"
  }'

The response carries a verdict (intact, modified, or inconclusive), public marker IDs, and a persistent check_id that becomes the audit-trail anchor.

Calibrating the Queue

Public datasets on small-business document tamper rates are thin, and lenders that have measured internally rarely publish. As planning assumptions — not benchmarks — lenders building a queue capacity model have used these ranges:

Subprime business lending (MCAs, alternative term loans, high-risk EIDL successors): plan for roughly 5–10% of stip docs to return modified.
Prime small-business lending (Live Oak / Celtic / Newtek SBA-7a books, conventional small-business term loans at major banks): plan for roughly 1–2% of stip docs to return modified.
inconclusive rates depend on the document mix — expect higher rates on tax returns (more rebuild attacks, more legitimate consumer-tool exports from accountants) than on bank statements from major business-banking platforms.

Treat these as planning numbers. The real distribution at your shop is a function of channel, broker mix, product, and ticket size. Re-measure after the first quarter of live data.

What Structural Forensics Cannot Do

Stated plainly so it does not have to be guessed at:

Clean rebuilds return inconclusive, not modified. A tax return generated from scratch in PDFKit, a voided check rebuilt in a drawing tool, a bank statement assembled in a templated forgery service — none of these will be caught by structural-byte analysis. They will be caught by 4506-C (for tax returns), by bank callback (for routing numbers), and by document-content rules at other vendors.
intact does not mean the figures are real. It means the document was not modified after creation. A real bank statement with real fraudulent transactions inside it (kiting, structured deposits) is structurally intact. Behavioural fraud at the transaction layer is not the file layer.
inconclusive is not a verdict against the borrower. Many legitimate small-business documents return inconclusive — accountants exporting from Drake or Lacerte through generic print drivers, bookkeepers re-saving QuickBooks reports, small banks that use consumer-class PDF pipelines. The right action on inconclusive is calibrated escalation based on what was claimed to be uploaded, not auto-decline.

Audit Trail and Loss-Cause Attribution

Every analyze call returns a persistent check_id queryable through GET /api/v1/result/{check_id}. Storing it against the loan record adds two operational signals beyond the live fraud-screening use case (the retrospective PPP-forgiveness pattern above is the third):

Loss-cause attribution. When a loan defaults and the post-mortem asks “were the documents real,” the structural record from intake answers part of that question alongside underwriter notes and the 4506-C on file.
Broker performance review. Aggregated by submitting broker, the modified and inconclusive rates surface which channels are sending higher-risk paper.

Integration documentation lives at /api; pricing scales with monthly check volume.

Who This Is For

This article is written for the people who actually own this decision:

Head of Credit Risk at a fintech small-business lender deciding whether to add a structural-forensics layer on top of an existing KYB + bank-data + 4506-C stack.
Director of Fraud Operations at an SBA-7a preferred lender building a stip-doc review playbook that has to defend audit positions years after origination.
VP Origination at a regional bank with a small-business book asking what the post-PPP review cycles actually changed about the way loan files should be screened.

The same four attack patterns surface across adjacent SMB lending verticals — merchant cash advance and revenue-based finance underwriting (where bank statements are the primary signal), equipment finance (where forged voided checks at funding are the high-leverage attack), invoice factoring (where altered invoices and aging schedules play the role tax returns play here), and conventional non-SBA term loans at regional banks. The 4506-C control is especially central in SBA-7a tax-return review; the structural-forensics layer is not SBA-specific. The end-to-end view of how the same filter fits across these flows is in the document fraud detection fintech workflow.

FAQ

How does structural forensics differ from a 4506-C tax-transcript pull?
4506-C asks the IRS what the borrower actually filed; structural forensics asks whether the PDF supplied to the lender was edited after it was generated. They answer different questions. 4506-C is the ground-truth control for tax-return content; structural forensics catches the edited-real-return subset cheaply on day one and lets you sequence 4506-C orders more efficiently. Use both for tax returns; structural-only is often sufficient as a first-pass screen for bank statements, where the bank’s own portal is the institutional reference and structural signals reliably identify post-portal editing.

Will this slow down our 30–60 day SBA-7a clock?
A typical analyze call returns in 1–4 seconds. At stip-doc receipt the result is back before the document has been routed to a human reviewer. There is no measurable impact on the funding clock.

What happens on a clean PDFKit rebuild of a forged tax return?
The verdict is inconclusive. The document was generated by a consumer-class toolchain, so structural integrity cannot be evaluated against an institutional baseline. The right downstream action is 4506-C verification, which is the ground-truth control for whether the return was filed at all.

Is the historical-PPP audit-defence use case actually useful, given the loans are closed?
For lenders defending active OIG inquiries, yes — the structural record from the original application files becomes a contemporaneous artifact in the audit response. For lenders with closed and clean books, it is optional. The batch-process cost is one-time and small relative to even a single OIG dispute.

My Checklist for Reviewing AI-Generated Code

Iurii Rogulia — Thu, 16 Jul 2026 10:01:05 +0000

The agent handed me a function that fetched a Stripe customer, read customer.tax_ids.data[0].value, and used it as the VAT number for an invoice. Clean code. Typed. Named well. It read perfectly. It also assumed every customer has exactly one tax ID at index zero, that the array is never empty, and that the first entry is the VAT number rather than, say, an Australian ABN. None of those assumptions hold. The function would work in every test I'd bother to write by eye and break the first time a real customer had two tax IDs or none. I almost merged it, because nothing about reading it told me to stop.

That is the entire problem with reviewing AI-generated code, and it's why I keep a separate checklist for it. When I decided where to delegate to an agent in the first place, I closed with a line: how to review what the agent produces is a whole discipline of its own. This is that discipline. The companion to it is the prompts that prevent bad output before generation — that's the upstream half. This is the downstream half: what to look for once the code already exists, when prevention didn't catch everything, because it never does.

Why AI Code Fails in a Different Place

Human code and AI code fail in different places, and that difference is the whole reason a generic review is the wrong tool.

When a person writes code, the defects cluster where the person struggled. The awkward function reads awkwardly. The half-understood API gets used hesitantly, with a comment that says "not sure this is right." The reviewer's instinct — slow down where the code looks uncertain — works, because the code's surface correlates with the author's confidence.

AI code has no such tell. It is uniformly fluent. The function that's subtly wrong reads exactly as smoothly as the function that's correct, because fluency is what the model optimizes — it produces the most plausible-looking continuation, and plausible-looking is the entire failure mode. The defect doesn't sit where the prose got awkward. There is no awkward prose. This is the class I call confidently wrong: code that is articulate, idiomatic, well-named, and incorrect in a way its own surface will never reveal.

So the reviewer's normal instinct actively misfires. "It reads well" is evidence of nothing. The model is good at exactly the signal you were using as a proxy for correctness. A review tuned for human code — skim the clean parts, slow down at the messy ones — sails straight past the bugs, because for AI code there are no messy parts to slow down at.

The checklist below is ordered by cost of error, not by how often each defect appears. That ordering is the opinion in this article. You will not catch everything — review never does, and some defects only surface under production load — so spend your attention where being wrong is most expensive. A cosmetic naming miss in a one-off script and a missing tenant filter in a billing query are not the same risk, and a checklist that treats them equally wastes the scarce thing, which is your attention.

1. Hallucinated APIs and Signatures

Highest on the list because it's the most AI-specific defect and the cheapest to catch — if you actually run the code instead of reading it.

Models invent. They produce method names that should exist, config fields that sound right, function arguments in a plausible order, package versions that were never published. The invention is confident and consistent — the model will use the hallucinated helper three times in the same file, which makes it look deliberate.

// The model "remembered" a method that doesn't exist.
// zod has .parse() and .safeParse() — there is no .validate().
const result = schema.validate(input);

// Plausible argument order, wrong reality. Stripe's
// charges.create takes one params object, not positional args.
await stripe.charges.create(amount, currency, customer);

The fix is not "read more carefully." You cannot read your way to catching a hallucinated API, because the whole point is that it looks like a real one. The fix is mechanical: let the type checker and the compiler do the reading. A hallucinated method on a typed library fails tsc instantly. A wrong argument shape fails type-checking. For untyped surfaces — a config key, a CLI flag, an environment variable the model invented — there is no substitute for actually running the code path, not eyeballing it and nodding. If the line never executed in front of you, you don't know the API exists. Treat "I read it and it looked fine" as equivalent to "I didn't check."

2. Missing Domain Invariants

This is the most dangerous category and the hardest to automate, because the defect is the absence of something the model could not have known to include.

Your domain has rules that live nowhere in public training data. Orders are scoped by tenant_id. Soft-deleted rows must be filtered. A refund can't exceed the captured amount. A user can only see their own organization's records. The model writes a flawless query against your schema and silently omits the invariant, because the invariant exists in your head and your migrations, not in the millions of repositories it learned from.

// The model wrote a correct, well-formed query.
// It is also a cross-tenant data leak, because it
// doesn't know this table is multi-tenant.
const orders = await db.select().from(ordersTable).where(eq(ordersTable.status, "paid"));

// What your domain actually requires:
const orders = await db
  .select()
  .from(ordersTable)
  .where(and(eq(ordersTable.tenantId, ctx.tenantId), eq(ordersTable.status, "paid")));

The compiler is no help here — both versions type-check, both run, both return rows. The first one returns the wrong rows, and in a demo with one tenant it looks identical to the correct one. This is why I review every data-access path the agent writes against a question the model can't answer for itself: what is true about this data that isn't written in the code? Tenant scoping, ownership checks, status guards, monetary bounds. If your invariants live only in tribal knowledge, the agent will violate them every time, and so will every new hire — which is an argument for writing them into the agent's persistent context so the prevention layer catches what it can before the code reaches review.

3. Security Defaults

The model learned from public code, and a lot of public code is insecure. It reproduces the common patterns it saw, and the common pattern is frequently the unsafe one.

# String interpolation straight into SQL — the model has
# seen this thousands of times in tutorials and answers.
query = f"SELECT * FROM users WHERE email = '{email}'"
cursor.execute(query)

# Parameterized — what you actually want.
cursor.execute("SELECT * FROM users WHERE email = %s", (email,))

The recurring offenders, in order of how often I find them: SQL built by string concatenation instead of parameters; missing input validation on anything that crosses a trust boundary; secrets hardcoded or logged in plaintext; insecure defaults (permissive CORS, verify=False on TLS, debug mode left on); and IDOR — an endpoint that takes a resource ID from the request and never checks the caller owns it. That last one overlaps with the missing-invariant category, and it's worth flagging twice precisely because it's invisible in a read: the code that fetches order/:id and returns it looks complete. The authorization check that should be there is, again, an absence, and absences don't show up when you're reading what's present.

Run new code mentally against the OWASP Top 10 — not as a compliance ritual, but because the model's training-data priors point at exactly those failure modes.

slug="fractional-cto"
text="Standing up the review discipline for AI-assisted teams — what gets read line by line, what a CI gate rejects automatically, who owns the merge decision — is the kind of structure my fractional CTO engagements put in place early."
/>

4. Edge Cases and Error Handling

The model writes the happy path beautifully and stops there. It was trained on code that demonstrates the intended use, not code that survives the inputs nobody intended.

The specific gaps, every time: empty collections (the [0] access from my opening, the .reduce with no initial value on an empty array); null and undefined where the model assumed a value; swallowed exceptions; happy-path-only logic with no else; missing timeouts and retries on external calls; numeric boundaries — zero, negative, overflow, floating-point money.

// The model writes this and considers the task done.
try {
  await chargeCustomer(order);
} catch {
  // Silent. The charge failed, the order is marked paid,
  // and nobody will know until the books don't reconcile.
}

A swallowed exception is the worst of these because it doesn't just fail to handle the error — it actively hides it, turning a loud, recoverable failure into a silent, expensive one. When I see an empty catch {} or a catch that logs and returns null, I reject it. Errors propagate or they're handled concretely; there is no third option. The model adds these defensively because it has seen a lot of code that does, and almost all of that code was wrong, too.

5. Tests That Assert Nothing

The agent is good at producing green tests. Green is not the same as meaningful, and a test suite that passes while testing nothing is worse than no suite, because it manufactures false confidence.

// This passes. It also tests nothing — the mock returns
// what the assertion checks for. It's a tautology dressed
// as a test.
it("returns the user", async () => {
  const repo = { findById: vi.fn().mockResolvedValue({ id: 1, name: "Test" }) };
  const result = await getUser(repo, 1);
  expect(result).toEqual({ id: 1, name: "Test" });
});

That test verifies that a mock returns what you told the mock to return. The real logic — how getUser handles a missing user, a repo error, an invalid ID — is untested, and the green checkmark says otherwise. So I review the tests themselves, not their presence or their pass/fail. The questions: does this test fail if I break the behavior it claims to cover? Does it mock the exact thing it's supposed to verify? Does it assert on the contract that matters, or on an incidental shape? A test you can't make fail by introducing the bug it's named after is decoration. Asking the model to test code it just wrote tends to produce exactly this — it tests the implementation's assumptions back to itself, bugs included.

6. Codebase Conventions and Consistency

The model writes code that is generically correct and locally foreign. It doesn't know your patterns, so it invents reasonable-looking new ones that quietly fork your codebase.

The signs: it duplicates a helper that already exists instead of importing it; it introduces a new error-handling style alongside your established one; it logs with console.log when you have a structured logger; it picks a different naming or file-placement convention than the surrounding code. None of it is wrong in isolation. All of it is drift, and drift compounds — three sessions downstream you have two ways to do everything and no one decided to.

This is where the prevention layer earns its keep: most of this is catchable before review by feeding the agent your conventions up front and by lint rules that reject the divergence deterministically. What review adds on top is the judgment a linter can't encode — "this is technically fine but it's not how we do it here." When I see a reinvented helper, the fix is one line back to the model: check lib/ for an existing one and use it.

7. Over-Engineering

The model loves to build for a future you didn't ask about. A factory where a function would do. A configuration object with options nobody will set. An abstraction layer wrapping a single concrete call, justified by "flexibility" and "extensibility" that no requirement demanded.

This is the inverse failure of the others — not a missing safeguard but a surplus of architecture. It's lower on the list because it's not a correctness bug; it's a maintenance tax. But it's an AI-specific tendency worth naming, because the model has read a lot of "enterprise-grade" code and reaches for its ceremonies by default. The reviewer's job here is subtraction. If an abstraction has exactly one implementation and no concrete second use case on the roadmap, it's speculative — inline it. The cost of a premature abstraction is paid by every person who later has to understand the indirection to change behavior that was never variable to begin with.

8. Dependencies and Licenses

When the agent reaches for a package, three things need checking, and none of them are visible in the diff that adds the import line.

Is the package real and the version published — or did the model hallucinate it (back to category one, now in package.json)? Is it maintained, or an abandoned repo whose last commit was four years ago? Is the license compatible with yours — a GPL dependency pulled into a closed-source product is a legal problem, not a technical one? And what does it drag in transitively — a one-line utility that pulls a hundred packages and three megabytes is rarely worth it when the standard library or six lines of your own would do.

Adding a dependency is a project-level decision the model makes as a per-task convenience. That asymmetry is exactly why the agent shouldn't add packages without a human deciding the trade-off — preferably enforced by a CI check on package.json diffs rather than left to catch at review.

9. Hidden Performance Problems

Last because it's the most context-dependent — what's a problem at scale is invisible at demo size, so this is the category most likely to pass review and surface in production. The model optimizes for "works," not "works at ten thousand rows."

The classic is the N+1: a loop that runs a query per iteration, correct and fast with three records, a self-inflicted denial of service with three thousand.

// Correct output. One query per order. With 5,000 orders,
// 5,000 round-trips to the database.
for (const order of orders) {
  const customer = await db.query.customers.findFirst({
    where: eq(customers.id, order.customerId),
  });
  order.customer = customer;
}

// One query. The model rarely reaches for this on its own.
const ids = orders.map((o) => o.customerId);
const customers = await db.query.customers.findMany({ where: inArray(customers.id, ids) });

The other recurring offenders: rendering work inside loops that triggers re-renders per item, building a data structure with the wrong access pattern (a linear scan where a Map lookup belonged), loading a whole table to count it. Catching these requires asking a question the model doesn't ask itself — what happens to this when the input is a thousand times bigger? — and that question is a senior reflex, not a thing you read off the page. The code is correct. It just doesn't scale, and correctness is the only thing its surface advertises.

The Honest Caveats

Three, because a checklist sold as a guarantee is a lie.

It doesn't catch everything. Review is a filter, not a proof. Race conditions, defects that only appear under concurrent load, the bug that needs production data volume to manifest — these survive any read-through and surface in production regardless of how disciplined the review was. The checklist lowers the rate and the cost of escaped defects. It doesn't drive them to zero, and anyone who tells you their review process does is selling something.

Reviewing this code can cost more than writing it. This is the uncomfortable one. When I already hold the full solution in my head, checking the model's version of it line by line — hunting the one subtle deviation from what I intended — can take longer than just typing my own. On those tasks the delegation is a net loss even though generation felt instant. That cost is precisely why the checklist matters: if review is the expensive part, it has to be done well, and done well means systematic rather than vibes. Cheap review on cheap-to-verify tasks; expensive, structured review on expensive-to-verify ones. The checklist is for the second kind.

This is a 2026 snapshot. Every item here describes a current-model tendency, and the models move. Hallucinated APIs are already less frequent than a year ago. Some categories will shrink; the root ones — missing domain invariants, security priors, the absence of consequence-modeling — depend on things a public-data interpolation engine structurally can't have, so I expect them to age slowest. Re-run the list as the tools change; the priorities will drift, the top of the list less than the bottom. And to be clear: good AI code exists. Most of what the agent writes for me on well-trodden tasks is fine, and paranoia applied uniformly is just slow. The whole point of ordering by cost of error is to not review everything as if it were a billing query.

The Copy-Paste Checklist

Priority-ordered, by cost of error. Attach it to your PR template for AI-generated changes.

## AI Code Review Checklist

Read order: top items first — they're ordered by cost of error, not frequency.
"It reads well" is not evidence. The model is fluent; fluency is the failure mode.

1.  [ ] Hallucinated APIs — does it type-check AND actually run?
        (Don't trust untyped configs/flags/env vars by reading.)
2.  [ ] Domain invariants present — tenant scoping, ownership checks,
        status guards, monetary bounds. What's true about this data
        that isn't written in the code?
3.  [ ] Security — parameterized queries (no string-built SQL),
        input validated at trust boundaries, no secrets in code/logs,
        no IDOR (does it check the caller owns the resource?).
4.  [ ] Edge cases — empty collections, null/undefined, no swallowed
        catch {}, timeouts + retries on external calls, numeric bounds.
5.  [ ] Tests assert behavior — does each test FAIL if I break the
        thing it names? Not testing mocks back to themselves?
6.  [ ] Conventions — uses existing helpers, your error layer, your
        logger, your naming. No reinvented patterns.
7.  [ ] No over-engineering — abstractions with one implementation
        and no concrete second use case get inlined.
8.  [ ] Dependencies — package real, maintained, license-compatible,
        not dragging heavy transitives. Human approved the add.
9.  [ ] Performance — no per-iteration DB queries (N+1), right data
        structure, no loading a table to count it. Scales past demo size.

If review costs more than rewriting would have: rewrite.

Takeaways

AI code fails where it reads best. Fluency is what the model optimizes, so "it looks clean" is evidence of nothing. A review tuned for human code — slow down at the messy parts — sails past AI defects because there are no messy parts.
Order by cost of error, not frequency. Attention is the scarce resource. A missing tenant filter and a cosmetic naming miss are not the same risk; review them differently.
Hallucinated APIs are caught by running, not reading. The type checker and an actual execution path catch what no careful read can, because the whole defect is that it looks real.
Missing invariants are the dangerous class. The model can't know your domain rules, so it omits them silently and the compiler won't complain. Review every data path for what's true but unwritten.
The checklist is a filter, not a proof — and that's exactly why it's needed. Review never catches everything, and on some tasks it costs more than rewriting. When review is the expensive part, do it systematically.

PDF Integrity Report: June 2026

Iurii Rogulia — Thu, 16 Jul 2026 10:00:50 +0000

Originally published at htpbe.tech. The version on htpbe.tech stays in sync with the latest detection algorithm — refer to it for the canonical text.

Every month we look at aggregate, anonymized data from checks processed by HTPBE and write up what the structural signals tell us about the state of PDF tampering. No file contents, no personally identifiable information — only the structural and metadata patterns the algorithm uses to classify documents.

This report is about proportions and movement, not raw counts. What share of documents came back flagged, which signals fired more or less often than the month before, which origins shifted, and what the recurring tampering shapes looked like. Those are the numbers that mean something; an absolute file count for a single month is noise by comparison.

The Shape of the Verdicts

Last month the flagged share climbed past seven in ten and, for the first time, "certain" verdicts overtook "high-confidence" ones. In June both of those moves reversed. The flagged share fell back to just under half — near where it sat in March — and "high-confidence" reclaimed the lead inside the flagged set.

Verdict	Direction vs. May
Not flagged	▲ back to just over half
High-confidence modification	▲ retook the largest flagged bucket
Certain modification	▼ slipped back below "high"

The reversal is almost entirely a traffic-mix effect, and it is the cleanest illustration we have yet published of why the flagged share is not a fraud rate. In May the traffic leaned hard toward the API, where callers skew toward files that are already modified — developers testing an integration with known-bad documents, and forger-bridge uploads probing whether a fake gets caught. That population stacks converging evidence, which lands in the "certain" tier and pushes the flagged share up.

In June the mix flipped: roughly four in five submissions came through the browser-based free checker rather than the API. Web traffic is a broader, messier population — curious first-time users, ordinary documents, genuine intake. A larger slice of it comes back clean, and the files that do flag tend to trip one strong signal rather than a stack of them, so they land in "high-confidence" rather than "certain."

Same engine, same thresholds, a very different headline number — driven by who showed up, not by any change in how documents are made. Read the flagged share every month as a statement about the submitting population, never as a population-wide fraud rate.

Signals That Moved

Under the shifting headline number, the evidence mix among flagged documents kept moving in the direction we have tracked all year: the classical first-order tells stayed common, while newer second-order checks kept widening what gets caught.

Up, or newly firing:

Generator-identity forgery — a document whose stated origin has been rewritten to disguise where it actually came from. A dedicated check shipped early in June and a late-June broadening extended it to files rebuilt after issue but still dressed up as untouched originals. It fires whenever the declared producer and the structural fingerprint tell two different stories.
Overlay and cover-and-replace edits — substitute values layered on top of, or concealing, otherwise-untouched original content to change what a page reads. New detection classes this month moved a long-standing hard case from "occasionally caught" toward routinely caught.
Edited-in-an-editor — a document reopened in an interactive PDF editor after creation, a value changed, and saved back. New coverage this month recognises that round-trip independently of which editing application did it.

Flat or down in share:

Date-field inconsistencies — still the most common single finding, but no longer growing; the easy timestamp tells are increasingly being cleaned before submission.
Missing creation date — eased back to roughly a fifth of all files, down from the near-quarter it reached in May. Still elevated, still worth watching, but the monotonic climb paused.
Post-signature modification — down in share, mostly because signed documents were again a thin slice of the month.

The year-long pattern held: a forger who has learned to scrub creation dates and avoid an incremental-update trail does not necessarily know to reconcile the structural fingerprint of the tool they rebuilt the file with against the origin they claim. The second-order checks are where those cases surface.

Incremental Updates: Still Almost Every Time

The cleanest signal we track stayed the cleanest. Files carrying incremental updates were flagged in the vast majority of cases — roughly seven in eight — easing only slightly from May's near-total rate. The average revision chain on those files sat around three appends.

The mechanism is unchanged: incremental updates let content be appended after the original write. Legitimate workflows produce them — signature application, annotation, form-fill — but on the population reaching the tool, those clean cases remain a small minority. When an incremental update shows up on a document submitted for tamper detection, it is still very close to synonymous with post-creation editing.

Representative Cases

These are composite, anonymized illustrations of the recurring shapes the engine resolved this month — not specific files. Each maps to the structural markers that actually drove the verdict.

The editor round-trip (verdict: certain). A "bank statement" looks clean to the eye. Structurally it was opened in an interactive PDF editor after its original creation, a figure was changed, and it was saved back — leaving the fingerprint of an editing pass over what claims to be an untouched issuer original. Edited-in-an-editor: the newer coverage this month recognises that round-trip no matter which editor did it.

The overlay patch (verdict: high → certain). A payslip reads correctly, cell by cell. Structurally, substitute values were layered on top of the original page content — the underlying figures are still there, quietly covered by the numbers the forger wanted shown. Overlay and cover-and-replace detection targets exactly this: the page you see is not the page underneath.

The borrowed generator identity (verdict: certain). A document declares an institutional producer in its origin fields, but the binary structure carries the fingerprint of a consumer tool that rebuilt it. The stated origin has been rewritten to disguise where the file actually came from. Generator-identity forgery — the check that treats "claims one origin, structurally is another" as a flag in its own right.

The render dressed as a scan (verdict: modified). A file arrives looking like a camera or scanner capture — one full-page image, no born-digital text. Structurally it was digitally rendered into that single image and then presented as a scan, a way a fabricated file is made to look like an innocent photograph of a paper original. A new June check separates that synthetic render from a genuine scan, including ordinary phone captures, which continue to pass into the not-certifiable ceiling rather than being flagged.

Document Origin

The origin mix partly unwound May's shift. Scanned documents fell back to roughly an eighth of submissions, slipping below consumer-software exports again, while institutional documents remained the plurality at a little over four in ten.

Origin classification	Direction
Institutional (server-side / enterprise generators)	plurality, ~four in ten
Consumer software ("Cannot Verify")	▲ back above scanned
Scanned ("Cannot Verify")	▼ eased to ~an eighth
Online editor / unknown / other	small shares

Scans and consumer-software exports fall into a "Cannot Verify" bucket where the structural layer deliberately returns a conservative inconclusive verdict rather than an intact-or-modified call — forcing a binary verdict on those formats would generate false positives in both directions. Several of June's releases sharpened that boundary in both directions: extending scanned-document recognition to more multifunction copier and companion-app output that had been misread as born-digital, while sparing genuine machine-issued bills that carry lightweight postal-mailing marks from being mistaken for a full-page scan. A scan can still never earn an "intact" verdict here — re-scanning a tampered printout is a known way to launder edits out of the structural record.

Digital Signatures

Signed documents were again a thin slice of the month — too small a base to quote a meaningful rate, so we keep it qualitative. The pattern that did appear is the one we report every month: a signature valid in the viewer does not guarantee the bytes were not altered, because incremental updates appended after signing fall outside the signed scope. Checking integrity at the structural layer, not the signature-validation layer, is what catches that.

Algorithm Development

June shipped sixteen versions — a steadier month than May's twenty-nine, and weighted toward broadening detection rather than the release-a-day pace of the previous month. The work split the usual three ways, with two firsts worth calling out.

New detection categories — generator-identity forgery, overlay and cover-and-replace edits, edited-in-an-editor round-trips, a synthetic-render-dressed-as-a-scan check, files rebuilt inside a graphics-design tool from a source held on the operator's own machine, and dangling internal references left behind by a rebuild. Several of these closed cases that had previously slipped through certified as originals.
The first deliberately-undisclosed signal. For the first time the catalogue carries a proprietary integrity check whose mechanism we do not describe — we acknowledge it exists and that it is strong, corroborated evidence when it fires, but we hold back how it works so a forger cannot read the description and engineer around it. Every other check stays described in plain outcome terms.
A retirement. We removed a standalone document-identifier consistency check: reviewed against a large corpus of genuine files, those identifier records were found to differ legitimately on a single clean render across many established generators, so on their own they produced false positives while adding nothing the structural checks did not already cover. Every modification it could ever evidence remains caught independently.
False-positive reductions — roughly half the releases narrowed heuristics misfiring on legitimate document classes: genuine scanner hardware output, single-pass institutional renders, print-rendered layouts, table-layout documents, machine-composed financial and retirement statements, and government forms with long author-to-issue gaps.

Wider coverage cuts against the falling flagged share, not with it: a share of the documents flagged in June would have passed under the early-June algorithm. The headline number fell anyway — which is exactly why the traffic-mix framing above matters.

The Software Ecosystem

The recurring fingerprints held. Online manipulation services as intermediate steps — a service in the producer field with a different application in the creator field, the signature of a compress / merge / page-extract step between creation and submission. Design-tool origin — vector- and consumer-design applications appearing where a system-generated producer belongs, on documents that purport to be business records; June added a specific check for files rebuilt inside a graphics tool from a locally-held source, a construction pattern no institution uses to issue its own statements. Programmatic manipulation libraries — where the signal is no longer the spoofable producer string but the structural fingerprint the library leaves at the binary level, which is where the generator-identity-forgery work is aimed.

PDF Version Landscape

Concentration loosened slightly. PDF 1.7 slipped just under half the sample, down from over half in May, with 1.4 taking a larger second share and 1.3, 1.6 and 1.5 splitting most of the rest. PDF 2.0, despite nearly a decade of availability, stayed a rounding-error share.

Summary

June 2026, in relative terms:

The flagged share fell back to just under half — and the reversal is the clearest example yet that this number tracks who submitted documents (a web-dominated month), not a population fraud rate.
"High-confidence" verdicts reclaimed the lead from "certain" as the traffic mix flipped from API-heavy to browser-heavy.
Incremental-update files were still flagged in the vast majority of cases — roughly seven in eight, the cleanest single signal we track.
Newer second-order checks — generator-identity forgery, overlay and cover-and-replace edits, edited-in-an-editor — kept widening coverage against the classical date and incremental-update tells.
Scanned share eased back to roughly an eighth; missing creation dates paused their climb at about a fifth.
Sixteen algorithm versions shipped, including the first deliberately-undisclosed proprietary signal and the retirement of an unreliable identifier check.

Every pattern here comes from the same forensic engine teams run on their own intake stream through the PDF tamper detection API. If you want to run a single document through the same analysis by hand, the free checker does it in the browser.

This report covers checks processed by HTPBE in June 2026. File contents are not stored or analyzed; only structural metadata signals are retained. All figures are aggregate and anonymized.

DEV Community: Iurii Rogulia

Why 'Two Weeks' Always Means Six — and How to Estimate Honestly

The iceberg under "the happy path"

Effort is not duration

The things you can't estimate because you haven't met them yet

Scope creep and the "while you're in there" tax

Optimism, anchoring, and the number that bends

How to estimate honestly: ranges, not single numbers

Decompose until each piece is a day — and time-box what you can't

Separate the estimate from the commitment

Track estimate vs actual, and trust history over your gut

The cone of uncertainty: a stale estimate is a lie

Name your assumptions, or the number means nothing

The honest-CTO framing: who you can plan around

Takeaways

Resistant AI Alternative: PDF Tamper Detection API

What Resistant AI Does — and Who It Is Built For

Why People Look for a Resistant AI Alternative

What HTPBE Is

The Comparison That Matters: Scope, Shape, and How You Buy

Different Scope, Stated Plainly

Cross-Vertical: The Same Attack, Outside Banking

The inconclusive Verdict — A Routing Signal, Not a Dead End

Integration: One Call, Your Workflow

When Resistant AI Is the Better Choice

When HTPBE Is the Better Choice

What HTPBE Cannot Catch

Snappt Alternative: A Self-Serve PDF Fraud Detection API for Rental & Beyond

What Snappt Does — and Who It Is Built For

Why People Look for a Snappt Alternative

What HTPBE Is

The Comparison That Matters: Shape and Buying Experience

Cross-Vertical: The Same Fraud, Outside Rental

The inconclusive Verdict — A Routing Signal, Not a Dead End

Integration: One Call, Your Workflow

When Snappt Is the Better Choice

When HTPBE Is the Better Choice

What HTPBE Cannot Catch

PDF Tamper Detection API for Java: Spring Boot Integration Guide

TL;DR

Prerequisites

Step 1: Test the API with curl

Step 2: Configuration Properties

Step 3: The Result DTO

Step 4: A Typed Exception

Step 5: The RestClient Service

Step 6: Retry on Transient Failures Only

Step 7: The Bank-Statement Gate

Step 8: The Reactive Variant (WebClient)

Step 9: Giving the API a Reachable URL

Step 10: Testing Without Burning Quota

What This Does Not Catch

Decisions Before You Ship

Feature Flags Without LaunchDarkly: A 100-Line Solution

What Feature Flags Actually Buy You

Why a SaaS Is Often the Wrong First Choice

The 100-Line Solution

The flags table

Deterministic percentage rollout

The evaluation function

Caching: stay off the database

When You Should Actually Buy LaunchDarkly

The static-config variant

Takeaways

Adobe Producer Spoofing: A PDF Metadata Forgery Case Study

Why the Producer field is the obvious thing to forge

What a metadata-only review actually verifies (almost nothing)

The contradiction a forged Adobe claim leaves behind

A worked example, in business terms

Where inconclusive fits — and why it isn’t a failure

The honest limit

Detecting it in your own pipeline

Who should care about this check

Isomorphic Canvas Rendering: One draw() in Browser and Node

Why You Need a Server Render at All

The Two-Renderer Trap

One UMD Core, Two Runtimes

The Font Problem: Where Isomorphism Actually Costs You

Determinism Makes the Cache Free

The Honest Edge Cases

The `inconclusive` Verdict — A Routing Signal, Not a Dead End

The `inconclusive` Verdict — A Routing Signal, Not a Dead End

Where `inconclusive` fits — and why it isn’t a failure