> Every UQL docs page, as Markdown: https://uql-orm.dev/llms.txt
> The same docs over MCP: https://uql-orm.dev/mcp
> To know how UQL ORM works, read the skill: https://uql-orm.dev/.well-known/agent-skills/uql-orm/SKILL.md

# Serving an ORM over HTTP without leaking a column

> Mark a field hidden, read-only or write-once on its definition, and every route, filter and relation that reaches it holds to that. How UQL's wire works.

Source: https://uql-orm.dev/blog/wire

You serve your `User` table to the browser, and a hook strips `passwordHash` from every response. The JSON looks clean. Then someone sends this:

```http
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](https://elttam.com/blog/plormbing-your-django-orm), and it works on any API that accepts a filter and hides fields only on the way out.

## 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

```ts
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

| The client sends | The API answers |
| - | - |
| `user/findMany` with no `$select` | `200`, each row without `passwordHash` |
| `user/findMany` filtering by `passwordHash` | `403`, `'passwordHash' cannot be read through this API` |
| `user/findMany` sorting by `passwordHash` | `403`, the same |
| `post/findMany` populating `author` | `200`, each author without `passwordHash` |
| `post/findMany` filtering by `author.passwordHash` | `403`, `'author.passwordHash' cannot be read through this API` |
| `user/insertOne` with `role: 'admin'` | `403`, `'role' cannot be inserted through this API` |
| `user/updateOneById` 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:

```json
{
  "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

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:

```ts
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

- A write needs `content-type: application/json`, which a plain HTML form cannot send, so a cross-site form gets a `415`.
- 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 a `503`, anything unknown a `500`.

## 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](https://uql-orm.dev/multi-tenancy.md) reading the request’s context. Pass `contextOf` to `createApi` and every call runs under it:

```ts
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

- Every API serving an entity shows the same members. An admin tool that needs `passwordHash` calls the pool directly, in a route of its own.
- The client is not typed by `wire`, so selecting a hidden field compiles and answers a `403` naming 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 `$select` still reads it. Hide a secret with `.wire(false)`.

The [HTTP page](https://uql-orm.dev/http.md#what-a-client-may-do) has every rule and the wire protocol, and the [browser client](https://uql-orm.dev/browser.md) sends the same typed queries you write on the server.

---

---

*[UQL](https://uql-orm.dev/index.md) 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.*
