MorphRules

MorphDB isolates app A from app B with the X-App-Key header. It has no concept of an end-user inside an app. And because the skill tells vibe-coded frontends to ship that key in client JS as window.MORPHDB_APP (SKILL.md:99,163-171), the key is a public bearer secret: anyone who opens DevTools gets full read / write / DELETE over every object — and every schema — in the app. The Lambda Function URL is intentionally public (lambda_function.py:16-17) and CORS reflects any origin, so there is no gateway to lean on. That is the gap this spec closes.

The design — MorphRules v1 — adds a per-end-user authorization layer enforced entirely inside MorphDB, on three foundations:

• A key split. The all-powerful shared key is replaced by a two-tier API key: mdb_sk_ (secret, server-side, bypasses all rules) and mdb_pk_ (publishable, browser-safe, carries no power of its own — every request is rule-gated).
• Real end-users. A per-app user type plus /auth routes mint app-bound opaque session tokens (stdlib scrypt, instant revocation) that populate an auth namespace.
• The rule is the filter. Each type carries five rule slots (list / get / create / update / delete). A list rule lowers to the exact guid IN (SELECT … FROM field_index …) shape MorphDB already emits — so list filtering is index-backed, leak-safe, and dual-backend with zero new SQL and no Postgres RLS. The same parsed expression evaluates as a Python predicate for the single-object actions.

MorphDB's request path is two thin HTTP shims — the stdlib server (server.py:114-168) and the Lambda (lambda_function.py:75-128) — feeding one shared router. Every authed handler in routes.py:70-192 begins with the same line, app = apps.require_app(req), and immediately delegates to objects.*. That uniformity is the good news: a single choke point covers both transports.

The bad news is what require_app does: it validates the app key by a plaintext string compare (apps.py:67-86; the key is stored verbatim, apps.py:46) and returns nothing but the app key. There is no user. Any holder of the key is fully trusted for:

• POST/GET/PUT/PATCH/DELETE /objects/* — read & mutate every row;
• PUT/DELETE /schema/* — rewrite or drop any type;
• DELETE /app/{key} — wipe the entire tenant (routes.py:82-84).

What MorphDB already has that we will reuse: a derived index, field_index (db.py:82-94), that turns ?status=active from a blob-scan into an index probe via _indexed_field_clause (objects.py:386-443), emitting guid IN (SELECT object_id FROM field_index WHERE app=? AND object_type=? AND field_name=? AND str_val=?). Every fragment is plain ANSI SQL with ? placeholders that the backend seam rewrites to %s for Postgres (backend.py:327-334). This is the exact template an owner-filter pushes down through — no RLS required.

2.1Goals

• Add per-end-user authorization within an app, enforced at the MorphDB level.
• Never leak across tenants when a rule is injected: every compiled fragment is wrapped in one outer paren and constant-folds never emit a bare TRUE/FALSE token, so a top-level OR cannot escape the app/object_type guards.
• List never fetch-all-then-filter: the predicate pushes down through field_index and is injected before COUNT and LIMIT, so totals and pagination reveal only visible rows.
• Make hidden/private_owner a real confidentiality boundary — blocking filter and sort, not just projection — killing the count/ordering/binary-search oracle.
• Replace the in-browser all-powerful key with a rule-bound publishable key + a rules-bypassing secret key, and lock the control plane to the secret key from day one.
• Give each app real end-users with stdlib-only credentials: app-bound opaque tokens, scrypt hashing, constant-time compare, enumeration-resistant login.
• Server-stamp and protect _owner/role/reserved fields so a client can never forge ownership or escalate role.
• Keep the guarantee byte-identical on SQLite and Postgres (COLLATE C, ASCII-only contains, a per-operator parity matrix).
• Stay incrementally adoptable: default-deny engages only when a type has a rule or a publishable key is used; the bare app key stays legacy-open on rule-less types so live demos keep working.

2.2Non-goals (v1/v2)

• No Postgres RLS as the mechanism — SQLite has none, so the portable guarantee lives in MorphDB's query layer.
• No record sharing with other users/groups and no folder/org hierarchies — deferred to v3 ReBAC. The v1 grammar has no cross-object joins, keeping the get-vs-list implication solver decidable.
• No full per-(role,type,action) column allow-list matrix — its config weight fights MorphDB's constant-edit workflow. Only a flat hidden/server_set/private_owner flag.
• No hand-written DSL with functions, arithmetic, or let-bindings — a small non-Turing-complete evaluator covers owner/role/public.
• No JWTs in v1 — opaque server-side sessions give instant revocation and app-binding.
• No change to the plaintext app key or the no-auth gateway — authz is enforced inside MorphDB.

Five production systems and the authz literature were studied in primary docs. The throughline: for a list endpoint, the rule must become a query predicate — anything that fetches-then-filters either leaks counts (a per-object check) or fails the whole query (Firebase). MorphDB sits closest to PocketBase: a single binary with schema-attached rules over an embedded DB.

The cross-cutting lesson from all five: a list authorization that is not a query predicate is either slow, leaky, or brittle. PocketBase already proved the “rule = WHERE clause” model for a single-binary embedded DB; MorphDB's field_index makes it portable to Postgres too.

Three principals, one expression language, one choke point.

4.1The spine

For each object type, the schema gains a rules block with five slots. A slot is one expression in a tiny boolean grammar over three namespaces — auth (the current user), the row's own fields, and new (the incoming write). That single expression does double duty:

• For list it is lowered to SQL — the same guid IN (SELECT … FROM field_index …) shape MorphDB already emits — wrapped in one outer paren and injected before COUNT/LIMIT. Rows a user can't see never leave the database, and counts can't leak them.
• For get/create/update/delete the same parsed AST evaluates as a Python predicate against the loaded (or incoming) row.

4.2One choke point, fail-closed

Identity resolution and rule evaluation hook in at exactly one place. require_app is extended to return (app, principal), and a required principal argument is threaded into objects.list/get/create/upsert/delete — with no default. A handler that forgets it raises a TypeError, so a missing check is a loud call error, not a silent open. CI tests fail the build on bypass.

5.1The key hierarchy

5.2Users & tokens (stdlib only)

End-users are ordinary objects rows of a per-app user type — so they inherit app isolation, projection, and the field index — but are managed only via /auth routes. The generic POST/PUT/PATCH/DELETE /objects/user door is hard-blocked, so there is no second path to tamper with role or password_hash.

• Password hashing: hashlib.scrypt(pw, salt, n=2¹⁵, r=8, p=2, dklen=32), salt from secrets.token_bytes(16); verify with hmac.compare_digest. (pbkdf2_hmac 600k is the documented memory-capped fallback.)
• Login is constant-time & enumeration-resistant: a fixed-parameter decoy scrypt runs on unknown email and on a locked account (run the KDF, then decide), so latency doesn't fork. One generic “invalid email or password”, identical status for every failure, per-account auto-clearing lockout.
• Tokens are opaque, not JWTs: secrets.token_urlsafe(32), returned once; the server stores only sha256(app + ":" + token) in a _session table. Folding the app into the hash means a token cannot validate under another tenant even if an app=? filter is ever dropped. Expiry is checked inside the resolve SELECT; the live role is re-read every request.

Roles are deliberately not a first-class primitive — no role table, no role endpoints, no join. A role is just the server-side role string on the user row, read into auth.role at resolve time from the live row (never a snapshot) and referenced as auth.role == "admin". It rides the session lookup the request already does, so a demotion takes effect on the next request and a ban is instant via session delete + a disabled flag.

Custom roles are arbitrary strings (trainer, staff, …) set only by the secret key or an existing admin — role is a server_set field, so a normal user patching its own role is rejected by the unconditional strip in the access layer.

Rules live in the schema JSON for each type, a sibling key to fields — persisted in the same object_schemas.fields blob (schema.py:89-167), no new table. Each of the five slots is nullable:

7.1Actions & namespaces

Four namespaces are available: auth (auth.id, auth.role, any auth.<field> from the live user row), the bare row fields (plus _owner, _guid), new (the incoming write — create/update only, e.g. new._owner == _owner for immutability), and method (the HTTP verb, literals only).

7.2Grammar — small, safe, decidable

A tiny boolean grammar (recursive descent, ~150 lines): a disjunction of conjunctions of optionally-negated comparisons. Exactly seven comparison operators, mapped one-to-one onto the engine's existing filter ops. No function calls, no arithmetic, no subqueries, no in-lists, no regex, no arbitrary code — guaranteeing linear-time, side-effect-free evaluation (safe for author-supplied rules in the shared process) and keeping the list ⊆ get implication check decidable.

rule grammar (EBNF-ish)expr        = disjunction
disjunction = conjunction { "||" conjunction }
conjunction = unary { "&&" unary }
unary       = [ "!" ] primary
primary     = comparison | "(" expr ")" | boollit
comparison  = operand CMP operand
CMP         = "==" | "!=" | ">" | ">=" | "<" | "<=" | "~"   // ~ = ASCII contains
operand     = field | auth | new | method | literal
field       = IDENT | "row" "." IDENT            // declared scalar, or _owner / _guid
auth        = "auth" "." IDENT                   // auth.id, auth.role, auth.<field>
new         = "new" "." IDENT                    // create / update only
literal     = STRING | NUMBER | "true" | "false" | "null"

IDENT is validated against the schema, so nothing client-controlled is ever interpolated into SQL; only resolved auth/method values and literals become bound params. ~ (contains) is contractually ASCII-case-insensitive via db.like_ci(), so it behaves identically on both backends.

7.3Presets

Authors rarely write raw rules — they pick a preset (expanded at schema-PUT):

7.4Signature — evaluate a rule, live

Below is the owner preset on a task type. The row under test belongs to Alice. Each cell is the real decision for that principal × action; click one to see why, and — for list — the compiled WHERE clause.

This is the engineering heart. A list rule becomes an index-backed WHERE in five steps:

1. Parse the rule into an AST once, cached per (app, type, schema-version). At schema-PUT, validate every bare identifier is a declared indexed scalar field — else reject, so a rule can't silently fall back to a blob scan.
2. Resolve auth.* once per request from the live user row into bound params; anonymous auth.id is the None sentinel.
3. Lower each leaf via the same _indexed_field_clause (objects.py:386-443): _owner == auth.id becomes a field_index subquery on field_name='_owner'; A && B → (A AND B), A || B → (A OR B), !A → NOT (A).
4. Constant-fold auth/method-only sub-expressions — but never emit a bare TRUE/FALSE token: drop a true conjunct; collapse a true disjunct so the whole authz clause vanishes (query unfiltered but still app/type-scoped); compile false to a self-contained empty-set probe.
5. Wrap & inject: the whole clause gets one outer paren and is AND-combined with client filters before COUNT (objects.py:549-551) and LIMIT/OFFSET.

list: _owner == auth.id || auth.role == "admin"  →  lowered for a non-admin user "alice"(
  guid IN (
    SELECT object_id FROM field_index
    WHERE app = ? AND object_type = 'task'
      AND field_name = '_owner' AND str_val = ? COLLATE C   // ? = "alice"
  )
)
// the admin disjunct folded AWAY (not "OR FALSE") — no bare token escapes the outer paren
// injected as: WHERE app=? AND object_type=? AND ( …above… )  — before COUNT and LIMIT

8.1Dual-backend parity

Every fragment is plain ANSI SQL with ? placeholders that backend.translate rewrites to %s; booleans bind as 0/1; contains routes through db.like_ci(). The one real divergence is string ordering — SQLite compares str_val BINARY while Neon's ICU collation reorders, so a tier > "gold" rule or any ordering oracle could return different sets. Fix: emit COLLATE "C" on Postgres str_val comparisons, limit ~ to ASCII, and prove it with a per-operator test matrix asserting identical row sets on both engines (including NULL, default, and boundary cases).

8.2Enumeration defenses — four side-channels closed

_owner is a dedicated owner_guid TEXT column on objects — not a blob field. It has to be a column: validate_member_name bans underscore names and _split_body silently drops underscore keys (fieldtypes.py:91, objects.py:73), so a column dodges unknown-field rejection and survives schema churn. It is set from auth.id before INSERT, immutable thereafter (never from a body except by the secret key), and mirrored as one synthetic field_index row so owner filters push down.

Reserved & server-controlled fields are stripped before validation for every principal except the secret key (admin for role only): all _-prefixed keys, role and any server_set field, and owner_guid. Today role is an ordinary writable field (the red-team confirmed validate_against_schema accepts {"role":"admin"}), so this unconditional strip — plus closing the generic /objects/user door — is the entire defense against self-promotion.

v1 ships a flat per-field flag — not a per-(role,type,action) matrix — carried inside each field's JSON (an extended normalize_field_def, fieldtypes.py:41-77, which today drops unknown keys, so this must land before any /auth rollout or hidden is a no-op and password_hash leaks):

• hidden:true — projected out of every non-secret read, and excluded from filter/sort.
• server_set:true — rejected on client writes.
• private_owner:true — hidden + filter/sort-blocked for everyone except owner / admin / secret key.

11.1Gym — members, trainers, owner

Types: user (phone private), class (public-read; trainer/admin writes), booking (owner preset + a denormalized trainer guid). A scraped publishable key is powerless where a scraped app key returns everything.

11.2Storefront — customers, staff, card data

Types: order (card_last4 hidden; owner = customer; list/get also allow staff/admin), product (public-read), user (phone private).

12.1Data model

12.2API surface

Storage is untouched: the owner_guid column and two new tables are added idempotently, no object blob is rewritten, and the field-flag parser ships in the same release as /auth. The data plane is a three-state, per-type model:

The adversary holds the publishable key (it ships in the frontend). The red-team verdict on the first draft was “reject as a security guarantee” — five criticals, two reproduced as live SQLite leaks. All are fixed in this revision; the verdict is what makes the design trustworthy.

14.1The five criticals (reproduced & fixed)

14.2High / medium findings

1. Create-deny status. 403 for a logged-in-but-unauthorized author vs the 404 mask for anon/unknown — confirm the split and that adding a 403 helper to errors.py is acceptable.
2. Control-plane editor in v2. Schema/rule edits are secret-key-only in v1. Should an admin-roled session edit them in v2? How does the MCP-over-app-key path present credentials? (Safe default: secret-key-only.)
3. Both-credentials precedence. Confirm X-Api-Key-wins (opt-into-secure) vs a stricter reject-on-disagreement.
4. Share-with-N before v3? A small fixed-cap multi-value half-step (a JSON list scanned in Python for get + a denormalized recipient index for list) vs hold at 1:1.
5. Anonymous ownerless rows are disallowed by default — confirm no app needs anonymous create on an owner-ruled type (else the per-row random-sentinel path is opt-in).
6. Rate-limiting beyond login — where does the v2 token bucket live (in-process dict vs a tiny table) without breaking zero-dep, and should the Function URL sit behind a WAF?
7. Legacy-row attribution — run the one-time secret-key assign-owner pass on the kept tenants before flipping owner rules on, or leave legacy rows secret-key-only?
8. Hard cutover. Once any rule exists in an app, reject the bare app key on object routes (forcing the frontend migration), or keep it optional indefinitely? The X-Api-Key-wins precedence softens but doesn't close the window.