The number one flaw

OWASP, the open community that tracks web application security, ranks broken access control first in its Top 10: a signed-in user reaching data or actions their role should not ^[1]. It tops the list not because it is clever but because it is easy to get wrong. Most applications write the same rule in three places: the screen hides a button, the server checks a role, the database limits rows. Each copy is written by hand, at a different time, often by a different person or agent.

On a plant platform the gaps have names. A line 2 operator can read line 3's quality holds. A contractor who left still has a login that can export work orders. A supervisor approves their own downtime entry. An AI agent given an administrator key can change records it was only meant to read. Each is a rule that existed somewhere, but not everywhere.

Reading the matrix

A Role and Exposure Matrix is a table. Each row is a role: a job, not a person. Each column is a set of data (a table) or a screen. Each cell is the exposure: what that role may do with that data. A blank cell means no access at all.

There is no delete exposure in this matrix. Plant records are append-only: a mistake is corrected by a new entry that reverses or replaces it, so the history can be trusted and audited. If a role ever needs to remove data, that is a decision for the matrix's owner, written down with a reason.

Scope: own line, own area, whole site

Roles alone are not enough. Two operators share a role but work on different lines. Scope says which rows a role's exposure applies to, using the same hierarchy as the naming standard from Session 5: site, area, line.

Least privilege and default deny

Two principles shape every cell. Least privilege: each role gets the minimum access its job needs, and no more. NIST defines it as restricting each user or process to the privileges needed for its tasks ^[2]. Default deny: anything not explicitly granted is refused, so a forgotten cell fails closed, not open. OWASP's authorization guidance recommends both ^[3].

Roles are jobs, not people

Write supervisor, not Dana. People are assigned to roles and scopes; when someone changes job, their assignment changes and the matrix stays the same. A person with two jobs holds two roles, and gets the union of both. Avoid a role per person and avoid a catch-all admin role for daily work: administration is a separate, rarely used role with its own sign-in.

Five steps from intent to matrix

1. List the roles that touch the decision. Start from the intent's who decides, then add who supplies the data and who reviews it.
2. List the data: every table in your Session 3 schema, plus each screen.
3. Fill each cell with the smallest exposure the job needs: read, insert, update, approve, or blank.
4. Add scope to each role: line, area or site.
5. Add the rules a cell cannot express: separation of duties, and the machine accounts.

Role-based access control, where rights attach to roles and people are assigned to roles, is a long-established model with a NIST standard behind it ^[1]. The matrix is that model written as one readable table.

A worked example

The intent from Session 2: the shift supervisor decides, every hour, which line gets the next maintenance technician, from downtime by reason and open work orders. The schema has four tables: readings, downtime_events, work_orders and quality_checks, plus a people table for assignments.

Read down a column to see who can reach a table; read across a row to see everything one job can do. Both views matter. IT will read columns ("who can see work orders?"); a supervisor will read their row ("what can I do?").

Separation of duties

Some rules involve two people. The supervisor may approve downtime entries, but not one they recorded themselves, even if they also hold the operator role. NIST lists separation of duties as a standard access control (AC-5 in SP 800-53) ^[2]. A cell cannot express it, so the matrix carries it as a named rule that the generator turns into a database condition in Session 7.

Machine accounts are roles too

The connector from Session 5B, an AI agent, a nightly report: each acts on the platform and so needs a role in the matrix, with the narrowest rights for its one job. Never let a machine borrow a person's login, and never give it the database's master key. A service key that bypasses all row rules belongs only in server code that a person reviews, never in a connector, a browser or an agent ^[3].

Writing it as a file

The matrix lives in the repository as access/matrix.json, so it is versioned and reviewed, and so generators can read it. JSON is fussy about commas but every tool reads it; your agent can keep it tidy. Anything not listed is denied.

{
  "version": 1,
  "owner": "operations manager",
  "roles": {
    "operator":    { "scope": "line" },
    "supervisor":  { "scope": "area" },
    "manager":     { "scope": "site" },
    "maintenance": { "scope": "area" },
    "connector":   { "scope": "site", "machine": true },
    "access_admin":{ "scope": "site" }
  },
  "data": {
    "readings":        { "operator": "read", "supervisor": "read", "manager": "read", "maintenance": "read", "connector": "insert" },
    "downtime_events": { "operator": "insert read", "supervisor": "read approve", "manager": "read", "maintenance": "read" },
    "work_orders":     { "supervisor": "insert read update", "manager": "read", "maintenance": "read update" },
    "quality_checks":  { "operator": "insert read", "supervisor": "read approve", "manager": "read" },
    "people":          { "access_admin": "insert read update" }
  },
  "rules": [
    { "name": "no_self_approval", "applies_to": ["downtime_events", "quality_checks"],
      "says": "approve is refused when the approver created the record" }
  ],
  "screens": {
    "/operator":  ["operator"],
    "/review":    ["supervisor"],
    "/dashboard": ["supervisor", "manager"],
    "/work":      ["supervisor", "maintenance"],
    "/people":    ["access_admin"]
  }
}

One source, five outputs

Once the matrix is a file, a small script (the generator) reads it and writes everything that depends on it. Your AI coding agent writes the generator; you review what it produces. The outputs are never edited by hand: to change one, change the matrix and run the generator again.

Nothing outside the matrix

Default deny protects you when a cell is blank. A completeness test protects you when a whole table or route is missing from the matrix. It lists every table in the database and every route in the application, and fails if any is not in the matrix. A new table added by an agent without a matrix entry fails CI on the same pull request.

// test/matrix-complete.test.mjs — nothing exists outside the matrix.
import { readFileSync, readdirSync } from "node:fs";
import assert from "node:assert/strict";

const matrix = JSON.parse(readFileSync("access/matrix.json", "utf8"));
const roles = Object.keys(matrix.roles);

// Every exposure names a known role and a known action.
for (const [table, cells] of Object.entries(matrix.data))
  for (const [role, actions] of Object.entries(cells)) {
    assert.ok(roles.includes(role), `${table}: unknown role ${role}`);
    for (const a of actions.split(" ")) assert.ok(["read", "insert", "update", "approve"].includes(a), `${table}.${role}: unknown action ${a}`);
  }

// Every table created by a migration is in the matrix.
const sql = readdirSync("supabase/migrations").map((f) => readFileSync(`supabase/migrations/${f}`, "utf8")).join("\n");
for (const [, table] of sql.matchAll(/create table (?:if not exists )?(?:public\.)?(\w+)/gi))
  assert.ok(matrix.data[table], `table ${table} is not in access/matrix.json`);
console.log("every table is in the matrix");

Folder names such as supabase/migrations follow the Supabase command-line tool's layout ^[2]; your agent will adjust them to your repository. Session 8 adds the same check for routes.

The review sheet

The owner of the matrix (usually the operations manager) and IT both need to read it without reading JSON. The generator writes a review sheet: one table per role, listing each data set and exposure in plain words, plus the rules. It is regenerated on every change, so the sheet the owner signs is always the one that runs.

Changing access

Access changes are ordinary pull requests. The change to access/matrix.json is one line; the generated SQL and menu change with it; the tests prove the new cell; the owner approves. Months later, "who gave maintenance the right to update work orders, and why?" is answered by the repository's history in seconds.

People join and leave

Assigning a person to a role and a scope is data, not a change to the matrix: the access admin adds the assignment in the people table. When someone leaves, removing the assignment removes every right at once, and their personal login is disabled the same day. Review the assignments quarterly with each area owner ^[3].