Data access and identity

stigbord

Callers do not reach a backend. They reach stigbord. Every answer carries the hash of the rules that decided it.

STB · 5B7D74AB sha-256 of the rules file on this page

Fig. 1. A stop-log weir in section, silt settled behind the logs. Cut in basalt.

stigbord

noun, Swedish

The stop logs of a weir: heavy timbers dropped into grooves in the stone to set how much water passes. The level is not adjusted at the gate. It is set by the logs, and anyone on the bank can count them.

Stigbord is a data gateway, in Rust. One binary, one SQLite file. It stands in front of a web service, and every call to that service goes through it. What it lets through is set in one rules file, kept in git.

Four goals, in order

  1. I

    Authentication with physical constraints

    Things a password cannot stand in for. A key on the caller's device: a high-tier token is useless without it. Signatures from named people: rules nobody signed do not start.

  2. II

    Policy as the source of truth

    One YAML rules file, in git, where colleagues can read it. An unknown key is refused, not ignored.

  3. III

    Scalable, and cheap to run

    Stigbord keeps what it needs in SQLite, and nothing else. For more, three store copies and any number of gateways.

  4. IV

    Audit logging

    One line per read, two per change, chained by hash. There is no log level and no setting that reduces what is written.

Every request

The same steps, in the same order. None of them has a setting.

  1. 1.

    Verify the token

    Signature, issuer, audience, expiry. Asymmetric keys only. Stigbord signs nobody in; your identity provider does that.

  2. 2.

    Check the revocation list

    A revoked caller gets 401.

  3. 3.

    Find the grant

    No grant, no access: 403.

  4. 4.

    Hold the grant to its tier

    A grant that can read special category data needs a token bound to the caller's key, a second factor and a recent sign-in.

  5. 5.

    Fix whose rows

    The value comes from the verified sign-in. The request cannot set it.

  6. 6.

    Refuse fields the caller may not write

    The whole request, not the one field.

  7. 7.

    Write the audit record

    A change is written before it is passed on, and again with the result.

  8. 8.

    Forward

    To the web service behind it, with a credential only stigbord holds.

  9. 9.

    Check what came back

    A record outside the caller's rows is not theirs. One in a list is a fault, and the whole answer is refused.

  10. 10.

    Cut the answer down

    To the fields the caller may read, one record at a time.

No record, no data. No record, no change.

The rules file

Five kinds of document: App, Identity, Backend, Entity, Grant. This one puts stigbord in front of a salon's bookings service and lets a customer read their own bookings.

apiVersion: stigbord.dev/v1alpha1
kind: App
metadata: {name: salon}
spec:
  url: https://data.salon.example
  description: Bookings for a hair salon.
---
apiVersion: stigbord.dev/v1alpha1
kind: Identity
metadata: {name: people}
spec:
  issuer: https://login.salon.example
  audience: salon-app
  type: person
---
apiVersion: stigbord.dev/v1alpha1
kind: Backend
metadata: {name: bookings-api}
spec:
  type: http
  baseUrl: http://bookings.internal:8080
  credentialsFrom: {file: /var/run/secrets/bookings-api/token, header: Authorization, scheme: Bearer}
  region: eu-north-1
---
apiVersion: stigbord.dev/v1alpha1
kind: Entity
metadata: {name: booking}
spec:
  description: One appointment for one customer.
  category: personal
  purpose: appointment booking
  about: customer_id
  backend: bookings-api
  path: /v1/customers/{customer_id}/bookings
  scope: [customer_id]
  fields:
    id:          {type: id}
    customer_id: {type: string, labels: [personal.contact]}
    starts_at:   {type: datetime, labels: []}
    status:      {type: enum, values: [booked, cancelled, done], labels: []}
    staff_note:  {type: text, labels: [], optional: true}
  operations: [get, list]
---
apiVersion: stigbord.dev/v1alpha1
kind: Grant
metadata: {name: my-bookings}
spec:
  description: A customer reads their own bookings.
  identity: people
  access:
    booking:
      operations: [get, list]
      fromSignIn: {customer_id: login}
      read: [id, starts_at, status]

Stigbord-Rules: sha-256:5b7d74ab22d28bff387fd26fa23a8b1f7414e3978fa6c83b5e75209a82766860

fromSignIn: {customer_id: login} is the line that matters. The customer id is the subject of the verified token, and the address has no place for one.

Label a field special.health and every grant that reads it is high tier. stb check then refuses the grant until it requires a key-bound token, a second factor and a recent sign-in. The label comes first and the requirement follows from it. Nobody has to remember it.

One request

The token's subject is u-1881.

# the caller sends
curl -H "Authorization: Bearer $TOKEN" https://data.salon.example/e/booking

# stigbord sends the service, with its own credential
GET /v1/customers/u-1881/bookings HTTP/1.1

The caller gets id, starts_at and status of each booking. It does not get staff_note, because the grant does not list it. There is no masking.

The works

Stigbord is growing from a gateway into an identity system. One binary, stb, one role per process. The gateway and the store run today. The rest is designed and built in order.

RoleJobState
gatewayVerifies tokens, enforces grants, serves data cut down to what the caller may read.Running
storeThree copies, Raft over SQLite. Revocations and the audit chain, the same on every copy.Running
loginSign-in for people: passwords, one-time codes, passkeys, recovery.Designed
issuerOAuth 2.1, OpenID Connect and FAPI 2.0.Designed
signerThe only role that holds signing keys. It parses nothing from outside.Designed
permissionsRelation checks, answered at request time.Designed
federationSAML, both sides. The one XML parser in the system.Designed
provisioningSCIM from an outside directory.Designed
courierThe only way out: mail, fetches and pushes.Designed

What it does not claim

Worth reading before the rest.

  • It does not protect against its own operator. Signed rules raise the bar for whoever can change the rules file. They do not remove it.
  • It does not make bypass impossible. Whether the backend can be reached around stigbord is your network and credential setup.
  • It does not see what the web service behind it does.
  • A stolen bearer token works until it expires or is revoked. A stolen key-bound token does not work without the key.
  • The tiers are not compliance. They are worked out from the labels you put on fields. Label a field wrong and the tier is wrong.

On being strict

There is no flag that turns a check off.

You may loosen a rule. You write it in the rules file, in git, where your colleagues can read it. The audit log records the hash of each file that was loaded and, with a trust file, who signed it.

Security was weighed against convenience once, at design time. Convenience lost.