@loradb/lora-graphql 0.23.0 → 0.24.1

package/README.md

@@ -746,18 +746,24 @@ type Claims @jwt {
   roles: [String!] @jwtClaim(path: "app_metadata.roles")
 }
 
+extend schema @authorizationDefaults(requireAuthentication: false)
+
 type Post
   @node
   @mutation
   @authentication(operations: [CREATE, UPDATE, DELETE])
   @authorization(
     filter: [
+      { where: { node: { published: { eq: true } } } }
+      { where: { node: { author: { key: { eq: "$jwt.sub" } } } } }
       {
-        where: { node: { published: { eq: true } } }
-        requireAuthentication: false
+        where: {
+          AND: [
+            { jwt: { sub: { exists: true } } }
+            { node: { tenant: { eq: "$context.tenant" } } }
+          ]
+        }
       }
-      { where: { node: { author: { key: { eq: "$jwt.sub" } } } } }
-      { where: { node: { tenant: { eq: "$context.tenant" } } } }
       { where: { jwt: { roles: { includes: "admin" } } } }
     ]
     validate: [
@@ -791,19 +797,39 @@ type Post
 }
 ```
 
+- A rule takes `operations`, `when` (validate rules) and `where`; any
+  other field is a model error, so a misspelt `operations` cannot fall
+  back to the default unnoticed.
 - A rule is `{ node, jwt, AND, OR, NOT }`. `node` is a filter over the type
   (relationship properties included, through `<field>Connection: { some:
 { node, edge } }`), where `"$jwt.path"` strings become the caller's claims and
   `"$context.path"` strings values from the GraphQL context. `jwt` tests
   claims (`eq`, `in`, `includes`, `contains`, `startsWith`, `endsWith`,
   `lt`, `lte`, `gt`, `gte`, `exists`).
+- **Anonymous callers.** Without a token every rule denies, unless the
+  schema says `@authorizationDefaults(requireAuthentication: false)`. Then
+  a rule with a branch that reads no claims decides that branch for
+  anonymous callers too (the published posts above). A rule that needs
+  claims still denies them, and how depends on the kind of rule: a
+  validate rule asks for a token (`UNAUTHENTICATED`, not `FORBIDDEN`),
+  while a READ filter admits no row, so a signed-out caller reads an
+  empty list and the access matrix calls it `denied`.
+  It is one setting for the schema; a rule has no such field, and it
+  reaches every rule: a CREATE, UPDATE, DELETE or CONNECT rule that
+  reads no claims decides for signed-out callers as well. `check` names
+  each such write rule that no `@authentication` covers. To keep a
+  claim-free rule or branch for signed-in callers, test a claim beside it
+  (`{ jwt: { sub: { exists: true } } }`, as the tenant rule above does),
+  or put `@authentication` on the type or the relationship field.
 - **The caller's own node.** Mark the claim that identifies the caller
   with `@viewer(type: "Person", field: "subject")` (the field is `@key` or
   `@unique`), so the key can stay a slug while the subject is an identity
   provider's opaque id. Rules then say `{ node: { isViewer: true } }` on
   the viewer type, or `{ node: { author: { isViewer: true } } }` through a
   relationship; this expands to `{ subject: { eq: "$jwt.sub" } }` at
-  startup and compiles to exactly the same statement. `viewer: { verified:
+  startup and compiles to exactly the same statement. With `@viewer`
+  declared, writing that expansion out by hand is a model error: the
+  mapping lives in one place. `viewer: { verified:
 { eq: true } }` tests the caller's own node: one seek by the claim. Both
   are unknown without the claim, so `NOT { isViewer: true }` never grants a
   signed-out caller. `isViewer` takes `true` only; use `NOT` for the
@@ -1019,6 +1045,8 @@ deleted: Org.docs has onDelete: RESTRICT`. Replacing a single
   covers an operation, it replaces the default for that operation, never
   merges with it. `check()` fails on a `@mutation` type whose
   writes nothing guards, unless it says `@authorization(public: [...])`.
+  `requireAuthentication` (see "Anonymous callers" above) is the third
+  setting here.
 
 Relationship and `@cypher` fields take field-level `@authorization`
 with READ validate rules: a row failing the rule reads the field as
@@ -1105,7 +1133,10 @@ type Trip @node @mutation {
 - The rules hold whichever side the write comes from: a connect through
   `Person.trips` (the same relationship type, the other direction)
   answers to `Trip.members`' rules, with source and target as declared on
-  `Trip.members`. If both fields carry rules, both apply.
+  `Trip.members`. Declare each operation's rules on one of the two
+  fields: the same operation ruled on both is a model error (combine
+  with `AND` where both must pass); different operations may sit on
+  different sides.
 - A relationship failing `READ_EDGE` reads its properties as `FORBIDDEN`.
   Unless the claims alone settle the rule, nothing may filter, sort or
   aggregate by that relationship's properties.
@@ -1417,17 +1448,32 @@ relationship property (READ, CREATE, UPDATE) and root `@cypher` field,
 each operation as each kind of caller (anonymous, authenticated, and each role
 the rules test, such as `roles:admin`), with the verdict (`allowed`,
 `filtered`, `validated`, `masked`, `denied`, `unauthenticated`) and the
-rules that decide it. A `@key(scope: VIEWER)` type's CREATE reads
+rules that decide it. When rules name the caller's node (`isViewer`),
+`viewer` is the caller on nodes that are theirs: every rule part that
+only names them passes, so it shows the most a related caller gets,
+where `authenticated` shows what any signed-in caller gets. A part under
+`NOT` stays as written and is decided per row, so `viewer` never reads
+below `authenticated`. A relationship field has a CONNECT row when a
+rule or `@authentication(operations: [CREATE_RELATIONSHIP])` guards it,
+and a DISCONNECT row for a rule or `DELETE_RELATIONSHIP`. A
+`@key(scope: VIEWER)` type's CREATE reads
 `unauthenticated` for anonymous callers and `validated` by `key scope`
 for the rest.
 
-`lora.operationAccess(document | persistedId, operationName?)` answers
-the same question for one operation: each root field (fragments
+`lora.operationAccess(document | persistedId, operationName?, variables?)`
+answers the same question for one operation: each root field (fragments
 followed) with its type, the operations it needs (an upsert needs
 `CREATE` and `UPDATE`) and the verdict per caller, plus the most
 restrictive verdict per caller over all root fields. A field over
 several types (`node`, a union) reports the most restrictive member.
-Root fields only: nested selections answer to their own types' rules.
+A mutation's inputs are read for what they write through relationship
+fields: a nested connect or create counts as that field's CONNECT (and
+the target's CREATE), a disconnect or nested delete as its DISCONNECT, an
+`update: { edge }` as UPDATE_EDGE, each named in `by`
+(`Room.chan CONNECT: @authentication`). Pass `variables` for inputs the
+document takes as variables; a variable without a value is not read and
+is listed in the field's `unresolved`. Selections below a root field
+answer to their own types' READ rules.
 To keep admin-only operations out of client bundles:
 
 ````ts
@@ -1441,10 +1487,19 @@ order is stable, so a snapshot in CI turns access changes into diffs.
 `check` lints authorization too:
 
 - a filter rule every signed-in caller passes;
-- a rule whose default `requireAuthentication` refuses anonymous callers
-  a branch that needs no claims;
+- a rule that needs no claims, as a whole or in one `OR` branch, on a
+  type or a field, in a schema that leaves
+  `@authorizationDefaults(requireAuthentication:)` unset: anonymous
+  callers are refused it by default, so say which was meant;
+- once that setting is `false`, each write rule (CREATE, UPDATE, DELETE,
+  CONNECT, DISCONNECT, UPDATE_EDGE) a signed-out caller can pass and no
+  `@authentication` covers. READ rules and operations the type lists in
+  `public` are left alone: those are what the setting and the list are
+  for;
 - field rules the schema's bypass skips, on a type that says neither
-  `@authorization(bypass: false)` nor `bypass: true`;
+  `@authorization(bypass: false)` nor `bypass: true`, and one line naming
+  every type with rules the bypass reaches that way (plus relationship
+  property types, whose rules cannot opt out);
 - an UPDATE rule testing a single relationship the update input can
   re-point (`connect`, `disconnect`, `create`): the rule sees the node
   before (and, validated `AFTER`, after) the write, so a caller passing it

package/dist/analyze/access-lint.d.ts

@@ -0,0 +1,7 @@
+import { GraphQLSchema } from 'graphql';
+import { GraphModel, ModelWarning } from '../model/types.js';
+/**
+ * Authorization lints for `check`: valid rules that are probably not what
+ * was meant.
+ */
+export declare function accessLints(model: GraphModel, schema: GraphQLSchema): ModelWarning[];

package/dist/analyze/access.d.ts

@@ -1,29 +1,6 @@
 import { FragmentDefinitionNode, GraphQLSchema, OperationDefinitionNode } from 'graphql';
-import { AuthOperation, GraphModel, ModelWarning } from '../model/types.js';
-export type AccessVerdict = 
-/** Every row, for this caller. */
-"allowed"
-/** Only rows a filter rule admits; others are invisible. */
- | "filtered"
-/** Checked per row; a failing row is FORBIDDEN. */
- | "validated"
-/** Rows failing a mask read a substitute value. */
- | "masked"
-/** Never, for this caller. */
- | "denied"
-/** Needs a token this caller does not have. */
- | "unauthenticated";
-export interface AccessEntry {
-    type: string;
-    /** The field, for field-level and relationship rules. */
-    field?: string;
-    /** `EXECUTE`: running a Mutation @cypher field. */
-    operation: AuthOperation | "EXECUTE";
-    principal: string;
-    verdict: AccessVerdict;
-    /** What decides it: `filter[0]`, `validate[1]`, `@authentication`, `bypass`, … */
-    by: string[];
-}
+import { AuthOperation, GraphModel } from '../model/types.js';
+import { AccessEntry, AccessVerdict } from './verdicts.js';
 /** One root field of an operation, as each kind of caller. */
 export interface RootFieldAccess {
     /** The root field. */
@@ -46,6 +23,11 @@ export interface RootFieldAccess {
         verdict: AccessVerdict;
         by: string[];
     }>;
+    /**
+     * Variables in the field's arguments that were given no value: what
+     * they would write through relationship fields is not in `access`.
+     */
+    unresolved?: string[];
 }
 export interface OperationAccess {
     operation: "query" | "mutation" | "subscription";
@@ -62,14 +44,12 @@ export interface OperationAccess {
 }
 /**
  * Who may run `operation`: each root field's verdict per principal, read
- * off the same rules as `accessMatrix`. Root fields only: nested
- * selections answer to their own types' READ rules (see the matrix).
+ * off the same rules as `accessMatrix`. A mutation's inputs are read for
+ * the relationship writes they make, each a part of its root field's
+ * verdict; an input given as a variable is read when `variables` has its
+ * value and listed in `unresolved` when it does not. Selections below a
+ * root field answer to their own types' READ rules (see the matrix).
  */
-export declare function operationAccess(model: GraphModel, schema: GraphQLSchema, operation: OperationDefinitionNode, fragments: ReadonlyMap<string, FragmentDefinitionNode>): OperationAccess;
+export declare function operationAccess(model: GraphModel, schema: GraphQLSchema, operation: OperationDefinitionNode, fragments: ReadonlyMap<string, FragmentDefinitionNode>, variables?: Readonly<Record<string, unknown>>): OperationAccess;
 /** The access matrix of `model`, in a stable order. */
 export declare function accessMatrix(model: GraphModel, schema: GraphQLSchema): AccessEntry[];
-/**
- * Authorization lints for `check`: valid rules that are probably not what
- * was meant.
- */
-export declare function accessLints(model: GraphModel, schema: GraphQLSchema): ModelWarning[];

package/dist/analyze/assert-schema.d.ts

@@ -0,0 +1,19 @@
+import { LoraDriver } from '../driver.js';
+import { AssertSchemaOptions } from '../options.js';
+import { CheckReport, SchemaAssertion } from '../results.js';
+import { SchemaRequirement } from './indexes.js';
+export interface SchemaEnv {
+    driver: LoraDriver;
+    /** Timeout for every statement, in milliseconds. */
+    timeoutMs: number;
+    /** Constraints and indexes the API needs. */
+    requirements(): SchemaRequirement[];
+}
+/**
+ * Verify the database has every constraint and index the API needs;
+ * with `create`, add what is missing. Idempotent. Runs one DDL
+ * statement at a time: LoraDB rejects schema commands in transactions.
+ */
+export declare function assertSchema(env: SchemaEnv, options: AssertSchemaOptions): Promise<SchemaAssertion>;
+/** Indexes in the database that no requirement of the API matches. */
+export declare function unusedIndexes(env: SchemaEnv): Promise<CheckReport["unused"]>;

package/dist/analyze/diff.d.ts

@@ -1,5 +1,5 @@
 import { DocumentNode } from 'graphql';
-import { ModelOptions } from '../model/build.js';
+import { ModelOptions } from '../model/build/limits.js';
 import { SchemaRequirement } from './indexes.js';
 export interface ApiChange {
     /** graphql-js change type, e.g. `FIELD_REMOVED`. */

package/dist/analyze/plans.d.ts

@@ -1,5 +1,5 @@
 import { LoraDriver, QueryPlan, Statement } from '../driver.js';
-import { CompiledRead } from '../compile/read.js';
+import { CompiledRead } from '../compile/read/types.js';
 export interface PlanFinding {
     rule: "full-scan" | "mutating-read" | "result-columns" | "scan-expand" | "row-budget";
     message: string;

package/dist/analyze/principals.d.ts

@@ -0,0 +1,25 @@
+import { Field, GraphModel, NodeType, RelationshipPropertiesType } from '../model/types.js';
+export interface Principal {
+    name: string;
+    jwt: Record<string, unknown> | undefined;
+    /** The model this principal's verdicts are read off, when not the schema's. */
+    model?: GraphModel;
+}
+/** `node` (or its field, or a property type's field) as `p` sees the model. */
+export declare const nodeAs: (p: Principal, node: NodeType) => NodeType;
+export declare const fieldAs: <F extends Field>(p: Principal, node: NodeType, f: F) => F;
+export declare const propertyAs: <F extends {
+    name: string;
+}>(p: Principal, props: RelationshipPropertiesType, f: F) => F;
+/**
+ * Anonymous, authenticated (a token with no roles), `viewer` when rules
+ * name the caller's node, and one principal per claim value the rules
+ * test with `includes`, `eq` or `in` (`roles:admin`).
+ */
+export declare function principalsOf(model: GraphModel): Principal[];
+/**
+ * A token carrying `claims` where the `@jwt` type says they live
+ * (`@jwtClaim(path: "app_metadata.roles")`).
+ */
+export declare function token(model: GraphModel, claims: Record<string, unknown>): Record<string, unknown>;
+export declare const isRecord: (x: unknown) => x is Record<string, unknown>;

package/dist/analyze/verdicts.d.ts

@@ -0,0 +1,51 @@
+import { fieldReadGuard, propertyAccess, relationshipRules } from '../compile/auth.js';
+import { CompileContext } from '../compile/context.js';
+import { AuthOperation, CypherField, Field, NodeType, RelationshipOperation } from '../model/types.js';
+export type AccessVerdict = 
+/** Every row, for this caller. */
+"allowed"
+/** Only rows a filter rule admits; others are invisible. */
+ | "filtered"
+/** Checked per row; a failing row is FORBIDDEN. */
+ | "validated"
+/** Rows failing a mask read a substitute value. */
+ | "masked"
+/** Never, for this caller. */
+ | "denied"
+/** Needs a token this caller does not have. */
+ | "unauthenticated";
+export interface AccessEntry {
+    type: string;
+    /** The field, for field-level and relationship rules. */
+    field?: string;
+    /** `EXECUTE`: running a Mutation @cypher field. */
+    operation: AuthOperation | "EXECUTE";
+    principal: string;
+    verdict: AccessVerdict;
+    /** What decides it: `filter[0]`, `validate[1]`, `@authentication`, `bypass`, … */
+    by: string[];
+}
+export declare function rootFieldVerdict(ctx: CompileContext, field: CypherField): Pick<AccessEntry, "verdict" | "by">;
+export declare const PROPERTY_OPS: readonly ["READ", "CREATE", "UPDATE"];
+/** `field` has rules (or `@authentication`) for `op`. */
+export declare function fieldWriteGuarded(field: {
+    authentication?: ReadonlySet<AuthOperation> | undefined;
+    authorization?: NodeType["authorization"];
+}, op: AuthOperation): boolean;
+export declare function fieldWriteVerdict(ctx: CompileContext, node: NodeType, field: Field & {
+    kind: "scalar";
+}, op: "CREATE" | "UPDATE"): Pick<AccessEntry, "verdict" | "by">;
+export declare function propertyVerdict(ctx: CompileContext, field: Parameters<typeof propertyAccess>[1], op: AuthOperation): Pick<AccessEntry, "verdict" | "by">;
+export declare function typeVerdict(ctx: CompileContext, node: NodeType, op: AuthOperation): Pick<AccessEntry, "verdict" | "by">;
+export declare function fieldVerdict(ctx: CompileContext, node: NodeType, field: Parameters<typeof fieldReadGuard>[2] & {
+    name: string;
+    kind: string;
+    authorization?: NodeType["authorization"];
+}): Pick<AccessEntry, "verdict" | "by">;
+/**
+ * The `@authentication` operation a relationship operation answers to: a
+ * connect is checked as CREATE_RELATIONSHIP on the field, a disconnect as
+ * DELETE_RELATIONSHIP. Edge reads and updates have none of their own.
+ */
+export declare function relationshipAuthentication(op: RelationshipOperation): AuthOperation | undefined;
+export declare function relationshipVerdict(ctx: CompileContext, node: NodeType, field: Parameters<typeof relationshipRules>[1], op: RelationshipOperation): Pick<AccessEntry, "verdict" | "by">;

package/dist/cli.js

@@ -3,8 +3,8 @@ import { execFileSync as re } from "node:child_process";
 import { stat as M, readFile as ce, readdir as ue, mkdir as le, writeFile as _ } from "node:fs/promises";
 import { dirname as fe, basename as de, join as O, relative as pe } from "node:path";
 import { parse as j, Kind as p, visit as Y, print as Z, typeFromAST as me, isNonNullType as G, isListType as he, getNamedType as ge, isEnumType as ve, isInputObjectType as we } from "graphql";
-import { d as Ee } from "./diff-B9iDdELF.js";
-import { q as K, e as be, M as Te, a as R, l as X, g as x, u as ee, c as Ne, i as ye, r as Se, w as Ie } from "./driver-C5dSoSD8.js";
+import { d as Ee } from "./diff-K8-GSeKH.js";
+import { q as K, e as be, M as Te, a as R, l as X, g as x, u as ee, c as Ne, i as ye, r as Se, w as Ie } from "./driver-CXKPLfkz.js";
 const $e = /* @__PURE__ */ new Set(["Query", "Mutation", "Subscription"]), W = {
   coalesce: "@coalesce is not supported: it hides predicates from indexes; store a value instead",
   subscriptionsAuthorization: "@subscriptionsAuthorization is not supported: SUBSCRIBE rules go in @authorization",