Security and hooks

restloom decides what can be asked. Your backend decides who may ask it, through hooks.

What restloom enforces

• Exposure: only the schemas and tables you name are served, and only their visible columns.
• Sensitive columns: a column whose name looks like a secret is hidden without being asked, see below.
• Bound values: every value is a bound parameter, checked against its column's type before any SQL runs. Names come from the catalog and are quoted; nothing from a request is written into SQL.
• Bounded requests: every request is limited:

A request over a limit is refused, never quietly cut down.

• Errors: they answer stable codes. A database message never reaches the client. Unexpected errors answer internal and reach your onError hook.

Sensitive columns

restloom reads every column name when it reads the catalog. A name made of a word such as password, hash, salt, secret, token, api_key, private_key, otp, mfa or recovery, alone or between underscores, marks the column as sensitive: password_hash and reset_token are hidden, tokenizer is not. The full list is in Columns.

A hidden column is not served at all. It cannot be read, filtered, sorted or written, select=* leaves it out, and naming it answers as a column that does not exist, so a client cannot even learn it is there:

GET /users?select=name,password_hash

{ "error": "unknown_column", "message": "password_hash" }

The check runs on names, so it guards against the column nobody thought about when the table grew. It does not know what a column holds: hide a sensitive column with a harmless name yourself, with hide.

To serve a column the check hides on purpose, name it in show. It then behaves as any other column, and is writable only if write lists it:

resources: {
    files: { show: ['sha256_hash'] },
    users: { hide: ['phone'] },
}

sensitive replaces the whole pattern, for every resource. Start from DEFAULT_SENSITIVE to add words rather than lose the defaults:

import { createREST, DEFAULT_SENSITIVE } from '@crudy/restloom-postgres';
 
createREST({
    db, // from a database package, see Dialects
    expose: { schemas: ['app'] },
    sensitive: new RegExp(`${DEFAULT_SENSITIVE.source}|(^|_)(iban|ssn)(_|$)`, 'i'),
});

Hooks

import { createREST, RestError } from '@crudy/restloom-postgres';
 
createREST({
    db, // from a database package, see Dialects
    expose: { schemas: ['app'] },
    hooks: {
        authorize(request, target) { /* throw a RestError to refuse */ },
        async transaction(tx, context) { /* session settings, role */ },
        scope(resource, context) { return { tenant_id: context.tenantId }; },
        onError(error, request) { log.error(error); },
    },
});

context is what your adapter builds from the request, usually the authenticated user. restloom never reads it.

Row security

Row security needs PostgreSQL, or SQL Server with security policies (see Dialects). With Postgres, it is the strongest perimeter: the database itself hides the rows a session may not see. Connect as a role without BYPASSRLS, and set what your policies read in the transaction hook:

async transaction(tx, context) {
    await tx.query("SELECT set_config('app.user_id', $1, true)", [context.userId]);
}

Every read and write of the request then runs under those policies, embeds and relation filters included.

Scope

On a database without row security, scope keeps a request inside its perimeter. It returns column values a row must have, and restloom applies them:

• Reads: every query on the resource, and every relation reaching it, only matches rows with those values.
• Inserts: the scoped columns are filled in. A body giving another value is refused with out_of_scope.
• Updates and deletes: only rows with those values are reached. An update moving a row out of scope is refused.