Serving an ORM over HTTP without leaking a column
You serve your User table to the browser, and a hook strips passwordHash from every response. The JSON looks clean. Then someone sends this:
GET /api/v1/user/findMany?q={"query":{"$where":{"passwordHash":{"$startsWith":"a"}}}}An empty list means no, a row means yes. Then ab, then ac. The response never shows the column, and the filter reads it anyway, one character at a time. Security researchers call it an ORM leak, and it works on any API that accepts a filter and hides fields only on the way out.
The usual fixes
Section titled “The usual fixes”| Where the rule lives | Hides it in responses | Refuses filters and sorts on it | Holds through relations | Guards writes | Declared once |
|---|---|---|---|---|---|
| A hook stripping responses | yes | no | if you remember | no | yes |
| A response DTO or serializer | yes | no | per DTO | with input DTOs | no |
| A field allowlist per route | yes | yes | per route | yes | no |
UQL wire |
yes | yes | yes | yes | yes |
The allowlist is the safe one, and it is also a second copy of the model per route, kept in step by hand. Add a relation and every route reaching the entity through it needs the same list again.
Declared on the definition
Section titled “Declared on the definition”import { defineEntity, f } from 'uql-orm';import { createApi, toFetchHandler } from 'uql-orm/http';
export const User = defineEntity({ name: 'User', fields: { id: f.number().autoIncrement(), name: f.string(), email: f.string().wire(['read', 'insert']), passwordHash: f.string().wire(false), role: f.string().default('member').wire(['read']), },});
export interface User extends InstanceType<typeof User> {}
export const Post = defineEntity({ name: 'Post', fields: { id: f.number().autoIncrement(), title: f.string(), authorId: f.number().wire(['read']), },}).relations((rel) => ({ author: () => rel.manyToOne(User, { references: (post) => post.authorId }),}));
export interface Post extends InstanceType<typeof Post> {}
const api = createApi({ pool, include: [User, Post] });
export const handler = toFetchHandler(api);A field’s wire lists what a client may do with it: 'read', 'insert', 'update', or false for nothing. So email is set once at sign-up and never changed through the API, role and a post’s authorId are read-only, and passwordHash does not exist as far as a client can tell. An entity takes a wire too, listing the operations it serves, and wire: false keeps it off every API. Nothing is served until an API’s include names it.
Decorated classes say the same thing: @Field(f.string().wire(false)), @Entity({ wire: ['read'] }).
What a client gets back
Section titled “What a client gets back”| The client sends | The API answers |
|---|---|
user/ with no $select |
200, each row without password |
user/ filtering by password |
403, 'password |
user/ sorting by password |
403, the same |
post/ populating author |
200, each author without password |
post/ filtering by author. |
403, 'author. |
user/ with role: 'admin' |
403, 'role' cannot be inserted through this API |
user/ changing email |
403, 'email' cannot be updated through this API |
Every answer above came from toFetchHandler on PGlite under uql-orm 0.116.3 before this was published. A refusal names the path in the call that caused it, so a form can point at the field:
{ "error": { "message": "'passwordHash' cannot be read through this API", "status": 403, "kind": "security", "path": ["query", "$where", "passwordHash"] }}read covers every way of reading a value: $select, $where, $sort, $count and a populated relation, and a JSON path into a hidden column ('meta.plan') counts as reading the column.
Why on the field
Section titled “Why on the field”A secret is a secret wherever it is served. A rule kept beside the definition, per API or per route, is one more place to update when the model changes, and one more for every relation that reaches the entity. On the field, the rule follows the entity everywhere: hide address on Employee, and /company/findMany populating employees leaves it out too, with nothing written for that route.
The check runs on the client’s call before any middleware, so what a middleware adds is the server’s own. A client sending authorId gets a 403, and the author comes from the session instead:
import { type EntityMiddleware, serve } from 'uql-orm/http';
const stamped: EntityMiddleware<Post, Request> = (call, request, next) => call.op === 'insertOne' ? next({ ...call, payload: { ...call.payload, authorId: userOf(request) } }) : next(call);
const api = createApi({ pool, include: [User, serve(Post, { use: [stamped] })],});The smaller doors
Section titled “The smaller doors”- A write needs
content-type: application/json, which a plain HTML form cannot send, so a cross-site form gets a415. - A key the operation does not take is a
400, and values are never coerced:"$limit": "10"is refused. - A write the querier would drop, to a computed field or an update of an
updatable(false)one, is refused instead of ignored, so a client learns its change did nothing. - A driver’s error message never leaves the server. A duplicate answers a generic
409, a deadlock a503, anything unknown a500.
Columns and rows
Section titled “Columns and rows”wire decides which columns and operations a client may touch, the same for every user. Which rows a user may touch is a policy reading the request’s context. Pass contextOf to createApi and every call runs under it:
const api = createApi<Request>({ pool, include: [User, Post], contextOf: async (request) => { const session = await getSession(request.headers.get('cookie')); return session && { tenantId: session.tenantId, userId: session.userId }; },});Limits
Section titled “Limits”- Every API serving an entity shows the same members. An admin tool that needs
passwordHashcalls the pool directly, in a route of its own. - The client is not typed by
wire, so selecting a hidden field compiles and answers a403naming it. Typing the client by the server’s exposure cost about 26% more type instantiations per call, to turn an error that already names the field into a compile error. .eager(false)is no guard: it leaves a field out of a read that names no fields, and a client’s$selectstill reads it. Hide a secret with.wire(false).
The HTTP page has every rule and the wire protocol, and the browser client sends the same typed queries you write on the server.
UQL is a JSON-native TypeScript ORM for Node.js and Bun. Supports PostgreSQL, PGlite, MySQL, MariaDB, MSSQL, SQLite, CockroachDB, Turso, Neon, Cloudflare D1 and MongoDB. Queries are plain JSON, typed to the leaf.