@fitzzero/quickdraw-core 5.0.0 → 5.1.0

package/dist/server/index.js

@@ -20,6 +20,8 @@ import {
   accessFormProblem,
   afterCursor,
   allowedScopes,
+  anyOf,
+  anyOfPolicies,
   applyRateLimitMiddleware,
   checkName,
   checkWhenDefined,
@@ -36,7 +38,6 @@ import {
   definePolicy,
   encodeCursor,
   handlerProblem,
-  idFilter,
   inputKeys,
   isAccessPolicy,
   isCustomAccess,
@@ -47,16 +48,20 @@ import {
   markGrantsEditor,
   maxLevel,
   meetsLevel,
+  members,
   membersWhere,
+  membershipOf,
+  narrowKinds,
   orderByOf,
   projectRow,
   projectedOutput,
   registerRuntime,
+  resolver,
   selectWith,
   serviceGrant,
   strip,
   watchAdapterClients
-} from "../chunk-LLLYILEP.js";
+} from "../chunk-A6DJBGOG.js";
 import {
   DevWarningError,
   N_PLUS_ONE_STATEMENTS,
@@ -64,13 +69,13 @@ import {
   currentRev,
   formatDevWarning,
   runBeforeAnyDispatcher
-} from "../chunk-DNCAI3KY.js";
+} from "../chunk-4DIQHASK.js";
 import {
   crud,
   crudSpecOf,
   sharing,
   sharingSpecOf
-} from "../chunk-5IC5VZ7T.js";
+} from "../chunk-2UELNHDD.js";
 import "../chunk-QEKVYG5F.js";
 import {
   abortError,
@@ -79,7 +84,7 @@ import {
   kitRuntimeOf,
   outputSchemaOf,
   schemaOutputOf
-} from "../chunk-2XJFNVHW.js";
+} from "../chunk-2PWMUVC7.js";
 import "../chunk-DD4SKCNO.js";
 import {
   recordSocketSession,
@@ -98,19 +103,19 @@ import {
   adminSpecOf,
   search,
   searchSpecOf
-} from "../chunk-B2UQ27GH.js";
+} from "../chunk-CDKG4TFA.js";
 import {
   ACCESS_LEVELS,
   entityRoom,
   isAccessLevel,
   reservedRoomPrefix
-} from "../chunk-7QIY2DDX.js";
+} from "../chunk-VJTFXHOK.js";
 import {
   CHANNEL_DEFAULT_RATE,
   DEFAULT_COLLECTION_LIMIT,
   DEFAULT_COLLECTION_MAX_LIMIT,
   isScopedStream
-} from "../chunk-5YRQ26LF.js";
+} from "../chunk-RT6OILOI.js";
 import "../chunk-47AEXVDM.js";
 import "../chunk-Z2LZ7IZ7.js";
 import {
@@ -381,7 +386,7 @@ function checkChannelAccess(owner2, access, fail5) {
   }
   return Object.freeze({ service: access.service });
 }
-function checkChannel(service, name, def, entry, fail5) {
+function checkChannel(service, name, def, entry, kinds, fail5) {
   const owner2 = `channel "${name}"`;
   const implementation = typeof entry === "function" ? { handler: entry } : entry;
   if (!isRecord2(implementation) || typeof implementation.handler !== "function") {
@@ -403,10 +408,11 @@ function checkChannel(service, name, def, entry, fail5) {
     burst: def.burst ?? Math.max(1, ratePerSecond * 2),
     requires: compileRequires(def),
     access: checkChannelAccess(owner2, implementation.access, fail5),
+    kinds,
     handler: implementation.handler
   });
 }
-function compileChannels(contract, value, fail5) {
+function compileChannels(contract, value, kinds, fail5) {
   const declared = Object.entries(contract.channels);
   if (value === void 0 && declared.length === 0) {
     return /* @__PURE__ */ new Map();
@@ -419,12 +425,13 @@ function compileChannels(contract, value, fail5) {
     fail5(`channels has no implementation for ${missing2.map((name) => `"${name}"`).join(", ")}`);
   }
   const channels = /* @__PURE__ */ new Map();
+  const admitted = kinds === void 0 ? void 0 : new Set(kinds);
   for (const [name, entry] of Object.entries(value)) {
     const def = Object.hasOwn(contract.channels, name) ? contract.channels[name] : void 0;
     if (def === void 0) {
       fail5(`"${name}" is not a channel of the contract`);
     }
-    channels.set(name, checkChannel(contract.name, name, def, entry, fail5));
+    channels.set(name, checkChannel(contract.name, name, def, entry, admitted, fail5));
   }
   return channels;
 }
@@ -611,7 +618,24 @@ function checkWatchAccess(value, fail5) {
   }
   return Object.freeze({ service: value.service });
 }
-function checkServiceData(definition, fail5) {
+function checkAppKinds(value) {
+  return narrowKinds(value, void 0, (message) => {
+    throw new TypeError(`initQuickdraw: ${message}`);
+  });
+}
+function checkMethodKinds(owner2, entry, data, fail5) {
+  if (entry.kinds !== void 0 && entry.access === "public") {
+    fail5(
+      `${owner2} is "public", so kinds cannot narrow who may call it: a caller of a kind it left out would call it signed out. Leave kinds out, or give it a form that needs a principal`
+    );
+  }
+  return narrowKinds(
+    entry.kinds,
+    { kinds: data.kinds, by: "its service" },
+    (message) => fail5(`${owner2}: ${message}`)
+  );
+}
+function checkServiceData(definition, appKinds, fail5) {
   const { model, access, versionColumn } = definition;
   if (model !== void 0 && !isName(model)) {
     fail5('model must be the database model the rows live in, as the client names it ("task")');
@@ -631,7 +655,8 @@ function checkServiceData(definition, fail5) {
     writes: checkWrites(definition.writes, fail5),
     affects: Object.freeze(checkAffects(definition.affects, model, fail5)),
     versionColumn,
-    watchAccess: checkWatchAccess(definition.watchAccess, fail5)
+    watchAccess: checkWatchAccess(definition.watchAccess, fail5),
+    kinds: narrowKinds(definition.kinds, { kinds: appKinds, by: "initQuickdraw" }, fail5)
   };
 }
 function checkWatchedModels(contract, name, models, data, fail5) {
@@ -667,7 +692,8 @@ var DEFINITION_KEYS = /* @__PURE__ */ new Set([
   "channels",
   "streams",
   "onRoomLeave",
-  "adminBypass"
+  "adminBypass",
+  "kinds"
 ]);
 var METHOD_KEYS = /* @__PURE__ */ new Set([
   "access",
@@ -676,7 +702,8 @@ var METHOD_KEYS = /* @__PURE__ */ new Set([
   "ttlMs",
   "timeoutMs",
   "version",
-  "rowless"
+  "rowless",
+  "kinds"
 ]);
 function isRecord4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -723,7 +750,7 @@ function checkQueryOptions(owner2, entry, kind, fail5) {
     fail5(`${owner2}: version must be a function of (input, ctx)`);
   }
 }
-function checkMethod(contract, projections, name, entry, fail5) {
+function checkMethod(contract, projections, data, name, entry, fail5) {
   const owner2 = `method "${name}"`;
   const def = contract.methods[name];
   if (def === void 0) {
@@ -749,6 +776,7 @@ function checkMethod(contract, projections, name, entry, fail5) {
     fail5(`${owner2}: rowless must be true, or left out`);
   }
   checkQueryOptions(owner2, entry, def.kind, fail5);
+  const kinds = checkMethodKinds(owner2, entry, data, fail5);
   const projection = projectedOutput(def.output, projections);
   return Object.freeze({
     name,
@@ -758,6 +786,7 @@ function checkMethod(contract, projections, name, entry, fail5) {
     projection,
     schemaOutput: projection === void 0 ? schemaOutputOf(def.output) : void 0,
     access: entry.access,
+    kinds,
     handler: entry.handler,
     share: entry.share,
     ttlMs: entry.ttlMs,
@@ -766,7 +795,7 @@ function checkMethod(contract, projections, name, entry, fail5) {
     rowless: entry.rowless === true
   });
 }
-function checkMethods(contract, projections, value, fail5) {
+function checkMethods(contract, projections, data, value, fail5) {
   if (!isRecord4(value)) {
     fail5("methods must be an object with one implementation per contract method");
   }
@@ -776,7 +805,7 @@ function checkMethods(contract, projections, value, fail5) {
   }
   const methods = {};
   for (const [name, entry] of Object.entries(value)) {
-    methods[name] = checkMethod(contract, projections, name, entry, fail5);
+    methods[name] = checkMethod(contract, projections, data, name, entry, fail5);
   }
   return methods;
 }
@@ -847,6 +876,23 @@ function checkHandlers(service, fail5) {
     }
   }
 }
+function createRuntime(options, adopt) {
+  if (options === void 0) {
+    return Object.freeze({ extendContext: void 0, kinds: void 0, adopt });
+  }
+  if (typeof options !== "object" || options === null) {
+    throw new TypeError("initQuickdraw: options must be an object");
+  }
+  const { context, kinds } = options;
+  if (context !== void 0 && typeof context !== "function") {
+    throw new TypeError("initQuickdraw: context must be a function of the base context");
+  }
+  return Object.freeze({
+    extendContext: context,
+    kinds: checkAppKinds(kinds),
+    adopt
+  });
+}
 function buildService(runtime, contract, definition) {
   const checked2 = checkContract(contract);
   const fail5 = (message) => {
@@ -863,7 +909,7 @@ function buildService(runtime, contract, definition) {
   if (onRoomLeave !== void 0 && typeof onRoomLeave !== "function") {
     fail5("onRoomLeave must be a function of the leave and a run context");
   }
-  const data = checkServiceData(definition, fail5);
+  const data = checkServiceData(definition, runtime.kinds, fail5);
   const projections = compileProjections(checked2, definition.project, fail5);
   const collections = compileCollections(
     checked2,
@@ -873,7 +919,7 @@ function buildService(runtime, contract, definition) {
     fail5
   );
   checkWatches(checked2, collections, data, fail5);
-  const methods = checkMethods(checked2, projections, definition.methods, fail5);
+  const methods = checkMethods(checked2, projections, data, definition.methods, fail5);
   checkRowForms(methods, data, fail5);
   checkRowless(methods, data, fail5);
   const service = Object.freeze({
@@ -884,7 +930,7 @@ function buildService(runtime, contract, definition) {
     collections,
     adminBypass,
     methods: Object.freeze(methods),
-    channels: compileChannels(checked2, definition.channels, fail5),
+    channels: compileChannels(checked2, definition.channels, data.kinds, fail5),
     streams: compileStreams(
       checked2,
       { model: data.model, hasPolicy: data.access !== void 0 },
@@ -899,19 +945,6 @@ function buildService(runtime, contract, definition) {
 }
 
 // src/server/init.ts
-function contextOption(options) {
-  if (options === void 0) {
-    return void 0;
-  }
-  if (typeof options !== "object" || options === null) {
-    throw new TypeError("initQuickdraw: options must be an object");
-  }
-  const { context } = options;
-  if (context !== void 0 && typeof context !== "function") {
-    throw new TypeError("initQuickdraw: context must be a function of the base context");
-  }
-  return context;
-}
 var NEEDS = Object.freeze({
   "qd.collections.reset": "send through",
   "qd.stream": "push through",
@@ -972,11 +1005,8 @@ function roomsOf(current) {
 }
 function initQuickdraw(...args) {
   let current;
-  const runtime = Object.freeze({
-    extendContext: contextOption(args[0]),
-    adopt: (dispatcher) => {
-      current = dispatcher;
-    }
+  const runtime = createRuntime(args[0], (dispatcher) => {
+    current = dispatcher;
   });
   const qd = {
     defineService: ((contract, definition) => buildService(runtime, contract, definition)),
@@ -1084,60 +1114,6 @@ function jsonAcl(field, options = {}) {
   return policy;
 }
 
-// src/server/access/policies/members.ts
-function membershipOf(policy) {
-  return policy.kind === "members" ? policy.reads.memberships[0] : void 0;
-}
-function checkLevels(levels) {
-  if (levels === void 0) {
-    return void 0;
-  }
-  const valid = typeof levels === "object" && levels !== null && !Array.isArray(levels) && Object.values(levels).every(isAccessLevel);
-  if (!valid) {
-    throw new TypeError(
-      'members({ levels }): levels must map stored roles to access levels, as in { editor: "Moderate" }'
-    );
-  }
-  return Object.freeze({ ...levels });
-}
-function rolesAtLeast(read, level) {
-  const enough = new Set(levelsAtLeast(level));
-  if (read.levels === void 0) {
-    return [...enough];
-  }
-  return Object.entries(read.levels).filter(([, mapped]) => enough.has(mapped)).map(([role]) => role);
-}
-function members(options) {
-  if (typeof options !== "object" || options === null) {
-    throw new TypeError("members(options): options must be { model, entry, user, level }");
-  }
-  const read = Object.freeze({
-    model: checkName("members({ model })", "model", options.model),
-    entry: checkName("members({ entry })", "entry", options.entry),
-    user: checkName("members({ user })", "user", options.user),
-    level: checkName("members({ level })", "level", options.level),
-    levels: checkLevels(options.levels)
-  });
-  return definePolicy({
-    kind: "members",
-    membership: read,
-    reads: { columns: [], memberships: [read], inherits: [], storage: true },
-    levelsFor: (principal, ids, tools) => tools.memberships(read, principal.userId, ids),
-    async accessWhere(principal, level, tools) {
-      const roles = rolesAtLeast(read, level);
-      if (roles.length === 0) {
-        return "none";
-      }
-      const rows = await tools.storage.findMany(read.model, {
-        where: { [read.user]: principal.userId, [read.level]: { in: roles } },
-        select: { [read.entry]: true }
-      });
-      const entries = rows.map((row) => row[read.entry]);
-      return idFilter(entries.filter((entry) => typeof entry === "string"));
-    }
-  });
-}
-
 // src/server/access/policies/inherit.ts
 function isContract3(value) {
   return typeof value === "object" && value !== null && typeof value.name === "string" && Object.isFrozen(value);
@@ -1185,101 +1161,6 @@ function inherit(options) {
   });
 }
 
-// src/server/access/policies/anyOf.ts
-function unionReads(policies) {
-  const memberships = /* @__PURE__ */ new Set();
-  for (const policy of policies) {
-    for (const read of policy.reads.memberships) {
-      memberships.add(read);
-    }
-  }
-  return {
-    columns: [...new Set(policies.flatMap((policy) => policy.reads.columns))],
-    memberships: [...memberships],
-    inherits: [...new Set(policies.flatMap((policy) => policy.reads.inherits))],
-    parents: policies.flatMap((policy) => policy.reads.parents ?? []),
-    storage: policies.some((policy) => policy.reads.storage)
-  };
-}
-var MEMBERS = /* @__PURE__ */ new WeakMap();
-function anyOfPolicies(policy) {
-  return MEMBERS.get(policy);
-}
-function anyOf(...policies) {
-  if (policies.length === 0 || !policies.every(isAccessPolicy)) {
-    throw new TypeError("anyOf(...policies): pass one or more access policies");
-  }
-  const all = Object.freeze([...policies]);
-  const combined = definePolicy({
-    kind: "anyOf",
-    policies: all,
-    reads: unionReads(all),
-    async levelsFor(principal, ids, tools) {
-      const each = await Promise.all(all.map((policy) => policy.levelsFor(principal, ids, tools)));
-      const levels = /* @__PURE__ */ new Map();
-      for (const id of ids) {
-        levels.set(
-          id,
-          each.reduce((level, granted) => maxLevel(level, granted.get(id)), null)
-        );
-      }
-      return levels;
-    },
-    async accessWhere(principal, level, tools) {
-      const filters = await Promise.all(
-        all.map((policy) => policy.accessWhere(principal, level, tools))
-      );
-      const matching = filters.filter((filter) => filter !== "none");
-      if (matching.some((filter) => Object.keys(filter).length === 0)) {
-        return {};
-      }
-      if (matching.length <= 1) {
-        return matching[0] ?? "none";
-      }
-      return { OR: matching };
-    }
-  });
-  MEMBERS.set(combined, all);
-  return combined;
-}
-
-// src/server/access/policies/resolver.ts
-function levelIn(levels, id) {
-  let level;
-  if (levels instanceof Map) {
-    level = levels.get(id);
-  } else if (Object.hasOwn(levels, id)) {
-    level = levels[id];
-  }
-  return isAccessLevel(level) ? level : null;
-}
-function resolver(options) {
-  const valid = typeof options === "object" && options !== null && typeof options.levelsFor === "function" && (options.where === void 0 || typeof options.where === "function");
-  if (!valid) {
-    throw new TypeError("resolver({ levelsFor, where? }): levelsFor and where must be functions");
-  }
-  const { levelsFor, where } = options;
-  return definePolicy({
-    kind: "resolver",
-    reads: { columns: [], memberships: [], inherits: [], storage: false },
-    async levelsFor(principal, ids, tools) {
-      const levels = await levelsFor(principal, ids, tools);
-      if (typeof levels !== "object" || levels === null) {
-        return levelsById(ids, () => null);
-      }
-      return levelsById(ids, (id) => levelIn(levels, id));
-    },
-    async accessWhere(principal, level, tools) {
-      if (where === void 0) {
-        return "none";
-      }
-      const filter = await where(principal, level, tools);
-      const isFilter = typeof filter === "object" && filter !== null && !Array.isArray(filter);
-      return isFilter ? filter : "none";
-    }
-  });
-}
-
 // src/server/access/policies/everyone.ts
 function everyone(level) {
   if (!isAccessLevel(level) || level === "Public") {
@@ -2483,7 +2364,7 @@ function parseList(value) {
   }
   return Array.isArray(value) && value.every(isEntry) ? value : void 0;
 }
-function levelIn2(entries, userId) {
+function levelIn(entries, userId) {
   return entries.filter((entry) => entry.userId === userId).reduce((level, entry) => maxLevel(level, entry.level), null);
 }
 function entriesOf(entries, userId) {
@@ -2792,7 +2673,7 @@ function refusal2(listed, change, model) {
       `That user owns this ${model}: an owner's access cannot be shared, changed or taken away`
     );
   }
-  if (change.listed && levelIn2(listed.entries, change.userId) === null) {
+  if (change.listed && levelIn(listed.entries, change.userId) === null) {
     return new QuickdrawError("NOT_FOUND", `This ${model} is not shared with that user`);
   }
   return void 0;
@@ -2819,7 +2700,7 @@ async function changeList(call, context, change) {
       throw problem;
     }
     await checkLastAdmin(call, tx, listed, change);
-    const before = levelIn2(listed.entries, change.userId);
+    const before = levelIn(listed.entries, change.userId);
     if (before === change.level && entriesOf(listed.entries, change.userId) === 1) {
       return sharesOf(listed.entries);
     }
@@ -3335,6 +3216,53 @@ function checkOverrides(fieldOverrides, names, hidden, fail5) {
   }
   return fieldOverrides;
 }
+function quoted(names) {
+  return names.map((name) => `"${name}"`).join(", ");
+}
+function checkEditable(editable, declared, shown, fail5) {
+  const named = (label, list2) => {
+    for (const name of list2) {
+      if (ADMIN_NEVER_WRITABLE.includes(name)) {
+        fail5(`${label}: "${name}" is never editable; the database sets it`);
+      }
+      if (!shown(name)) {
+        fail5(`${label}: "${name}" is not a field of the entity the kit shows`);
+      }
+    }
+    return new Set(list2);
+  };
+  if (editable === void 0) {
+    return declared === void 0 ? void 0 : named("admin.contract's editable", declared);
+  }
+  const valid = Array.isArray(editable) && editable.every((name) => typeof name === "string") && new Set(editable).size === editable.length;
+  if (!valid) {
+    fail5("editable must be a list of distinct field names");
+  }
+  const list = named("editable", editable);
+  if (declared !== void 0 && (declared.length !== list.size || !declared.every((name) => list.has(name)))) {
+    fail5(
+      `editable names ${quoted(editable)}, but admin.contract was given ${quoted(declared)}: give both halves the same fields`
+    );
+  }
+  return list;
+}
+function checkAgreement(overrides, editable, fail5) {
+  if (editable === void 0) {
+    return;
+  }
+  for (const [name, override] of Object.entries(overrides)) {
+    if (override.editable === true && !editable.has(name)) {
+      fail5(
+        `fieldOverrides: "${name}" is editable: true, which editable leaves out; name it in editable instead`
+      );
+    }
+    if (override.editable === false && editable.has(name)) {
+      fail5(
+        `fieldOverrides: "${name}" is editable: false, which editable names; leave it out of editable instead`
+      );
+    }
+  }
+}
 function derived(field, grants) {
   const fixed = Object.hasOwn(DEFAULT_FIELDS, field.name) ? DEFAULT_FIELDS[field.name] : void 0;
   if (fixed !== void 0) {
@@ -3372,10 +3300,18 @@ function adminFieldsOf(serviceName, spec, options, fail5) {
     fail5(`"${listed}" is hidden, so adminList may not filter or sort on it`);
   }
   const overrides = checkOverrides(options.fieldOverrides, names, hidden, fail5);
+  const editable = checkEditable(
+    options.editable,
+    spec.editable,
+    (name) => names.includes(name) && !hidden.has(name),
+    fail5
+  );
+  checkAgreement(overrides, editable, fail5);
   const fields = ordered(spec.fields).filter((field) => !hidden.has(field.name)).map(
     (field) => frozenConfig({
       ...derived(field, grants),
       ...overrides[field.name],
+      ...editable === void 0 ? {} : { editable: editable.has(field.name) },
       sortable: spec.sort.includes(field.name),
       filterable: spec.filter.includes(field.name)
     })
@@ -3701,6 +3637,7 @@ var OPTION_KEYS4 = [
   "access",
   "displayName",
   "hiddenFields",
+  "editable",
   "fieldOverrides",
   "rowless",
   "grants",
@@ -3741,7 +3678,7 @@ function checkOptions3(options) {
   }
   if (!isRecord11(options)) {
     fail4(
-      "options must be { access?, displayName?, hiddenFields?, fieldOverrides?, rowless?, grants?, onWrite?, onCommitted? }"
+      "options must be { access?, displayName?, hiddenFields?, editable?, fieldOverrides?, rowless?, grants?, onWrite?, onCommitted? }"
     );
   }
   const unknownKey = Object.keys(options).find((key) => !OPTION_KEYS4.includes(key));
@@ -3768,13 +3705,28 @@ function checkAccess3(access, names) {
   }
   return access;
 }
+function contractEditable(contract, specs) {
+  const lists = /* @__PURE__ */ new Map();
+  for (const { editable } of specs) {
+    if (editable !== void 0) {
+      lists.set([...editable].sort().join("\0"), editable);
+    }
+  }
+  if (lists.size > 1) {
+    fail4(
+      `admin.contract was given two editable lists for ${contract.name}: give its write methods one`
+    );
+  }
+  return [...lists.values()][0];
+}
 function fieldsOf(contract, kit, options) {
   const specs = kit.map(([, spec2]) => spec2);
   const [first] = specs;
   const spec = {
     fields: first?.fields ?? [],
     filter: [...new Set(specs.flatMap((one) => one.filter))],
-    sort: [...new Set(specs.flatMap((one) => one.sort))]
+    sort: [...new Set(specs.flatMap((one) => one.sort))],
+    editable: contractEditable(contract, specs)
   };
   return adminFieldsOf(
     contract.name,
@@ -3782,6 +3734,7 @@ function fieldsOf(contract, kit, options) {
     {
       displayName: options.displayName,
       hiddenFields: options.hiddenFields,
+      editable: options.editable,
       fieldOverrides: options.fieldOverrides,
       grants: options.grants
     },