foldkit-guard 0.6.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +223 -46
  2. package/dist/agent.d.mts +1 -1
  3. package/dist/agent.mjs +1 -1
  4. package/dist/{attach-CRCF5XHS.mjs → attach-CEGlbWu5.mjs} +17 -2
  5. package/dist/attach-CEGlbWu5.mjs.map +1 -0
  6. package/dist/{attach-BepaL930.d.mts → attach-CJl-GtbN.d.mts} +156 -10
  7. package/dist/attach-CJl-GtbN.d.mts.map +1 -0
  8. package/dist/{condition-Dx54lL7v.mjs → condition-dNSbUHzE.mjs} +98 -10
  9. package/dist/condition-dNSbUHzE.mjs.map +1 -0
  10. package/dist/drizzle.d.mts +1 -1
  11. package/dist/drizzle.mjs +8 -6
  12. package/dist/drizzle.mjs.map +1 -1
  13. package/dist/index.d.mts +1 -1
  14. package/dist/index.mjs +34 -17
  15. package/dist/index.mjs.map +1 -1
  16. package/dist/may-DprCmMgK.mjs +200 -0
  17. package/dist/may-DprCmMgK.mjs.map +1 -0
  18. package/dist/{me-BYpuVqJE.mjs → me-C-gX1paZ.mjs} +3 -3
  19. package/dist/{me-BYpuVqJE.mjs.map → me-C-gX1paZ.mjs.map} +1 -1
  20. package/dist/media.d.mts +1 -1
  21. package/dist/{placed-BvdNmZJu.mjs → placed-CGyo-NRR.mjs} +2 -2
  22. package/dist/{placed-BvdNmZJu.mjs.map → placed-CGyo-NRR.mjs.map} +1 -1
  23. package/dist/server.d.mts +54 -20
  24. package/dist/server.d.mts.map +1 -1
  25. package/dist/server.mjs +288 -154
  26. package/dist/server.mjs.map +1 -1
  27. package/dist/sync.d.mts +5 -3
  28. package/dist/sync.d.mts.map +1 -1
  29. package/dist/sync.mjs +18 -8
  30. package/dist/sync.mjs.map +1 -1
  31. package/package.json +20 -19
  32. package/dist/attach-BepaL930.d.mts.map +0 -1
  33. package/dist/attach-CRCF5XHS.mjs.map +0 -1
  34. package/dist/condition-Dx54lL7v.mjs.map +0 -1
  35. package/dist/may-DzCAt_5M.mjs +0 -75
  36. package/dist/may-DzCAt_5M.mjs.map +0 -1
package/dist/server.d.mts CHANGED
@@ -1,8 +1,29 @@
1
- import { S as Policy, k as MeEntity, l as InteractionKey } from "./attach-BepaL930.mjs";
1
+ import { S as Policy, k as MeEntity, l as InteractionKey } from "./attach-CJl-GtbN.mjs";
2
2
  import { Effect, Option } from "effect";
3
3
  import { AnyEntity, AnyQuery } from "foldkit-entity";
4
+ import { Diagnostic, MutationDescriptor, RemoteForbidden, ReportDiagnostic } from "foldkit-remote";
4
5
  import { EntitySource, EntityWriter, MemoryReadable, MutationOutcome, MutationRefused, MutationSource, ReadPlan, RemoteServerError, ServerDefinition } from "foldkit-remote-server";
5
- import { MutationDescriptor, RemoteForbidden } from "foldkit-remote";
6
+ /**
7
+ * An operator refused to work out a value a guarded write computes (text
8
+ * holding NUL, an implementation that throws). The write was refused with a
9
+ * fixed message, since the operator's own may say anything.
10
+ */
11
+ interface ComputeRefused extends Diagnostic {
12
+ readonly _tag: 'ComputeRefused';
13
+ readonly entity: string;
14
+ /** The operator's own refusal. */
15
+ readonly error: Error;
16
+ }
17
+ /**
18
+ * Writes through a `GuardServer.writer` given no revision, where a change can
19
+ * come between the check and the write, which is then not seen.
20
+ */
21
+ interface UnpinnedWrites extends Diagnostic {
22
+ readonly _tag: 'UnpinnedWrites';
23
+ readonly mutations: ReadonlyArray<string>;
24
+ }
25
+ /** Every diagnostic `foldkit-guard` reports. */
26
+ type GuardDiagnostic = ComputeRefused | UnpinnedWrites;
6
27
  export declare const GuardServer: {
7
28
  /**
8
29
  * `Guards.me`'s Source: the one row, `me`, as the asker is, with `may`
@@ -41,19 +62,26 @@ export declare const GuardServer: {
41
62
  * `RemoteServer.write`. An update or a delete reads the row first under
42
63
  * the writer's own `read` (its Source's read rule): a row the writer may not
43
64
  * see is refused as one that is not there, and a delete of it changes
44
- * nothing. Then the row's rule for the command must hold over the row (an
45
- * update's over the row as it would be after it too, so a write cannot move
46
- * a row out of its writer's reach), each member it sets must allow setting
47
- * it, and each relation it points elsewhere must allow the unlink and the
48
- * link. A create's rules hold over the values it proposes, where a field the
65
+ * nothing. Then the row's rule for the command must hold over the row, each
66
+ * member it sets must allow setting it, and each relation it points
67
+ * elsewhere must allow the unlink and the link. An update's row rule holds
68
+ * over the row as it would be after it too, so a write cannot move a row out
69
+ * of its writer's reach. Each of its member and `Link` rules holds over the
70
+ * row after with that one change undone (that member's value, or where that
71
+ * relation pointed, as before): the change must be allowed given everything
72
+ * else the write does, so one write cannot set together what each change
73
+ * alone would be refused, while a rule reading its own member ("only while
74
+ * a draft") still allows the change. An increment or a computed assignment
75
+ * to a member is that member's own change. An `Unlink` rule holds over the
76
+ * row before alone. A create's rules hold over the values it proposes, where a field the
49
77
  * create leaves unset matches no guard, not even one for an empty value. A refusal is
50
- * `Forbidden`, with the sentence an `explain` gave; the write never runs.
78
+ * `Forbidden`, with the sentence an `explain` gave, or `Unauthenticated` for a
79
+ * visitor; the write never runs.
51
80
  *
52
- * `presets` are fields a create takes from who is asking, never from the
53
- * client (`ownerId: user => user.id`): set before the rules are checked, so
54
- * a rule over them holds of the creator. A visitor has nothing to preset
55
- * from, and a create whose input sets a preset field is a mistake of the
56
- * server's, refused.
81
+ * What the Entity sets from the write's context (`Entity.sets`: who asks,
82
+ * when) reaches a create or an update already set by `RemoteServer.write`,
83
+ * so a rule over it holds of the creator. A member rule over such a member
84
+ * judges the server's value like any other: declare none there.
57
85
  *
58
86
  * `revision` names a field stored as a number, which the writer moves on by
59
87
  * one with each write it lands. An update or a delete then lands only on the
@@ -61,7 +89,8 @@ export declare const GuardServer: {
61
89
  * between the check and the write is never written over; it is decided
62
90
  * again against the row as it now is, up to three times. A change that does
63
91
  * not move the revision (a handler's, `applyEdits`', raw SQL) is not seen.
64
- * Without `revision`, none is, and `validate` warns. An input that expects a
92
+ * Without `revision`, none is, and `validate` warns of an update, or a delete
93
+ * of an Entity the server updates (an insert has no row). An input that expects a
65
94
  * revision the row read is not at is a `Conflict`, decided before any rule;
66
95
  * an input may expect only the field the writer pins.
67
96
  *
@@ -70,7 +99,6 @@ export declare const GuardServer: {
70
99
  * ```
71
100
  */
72
101
  writer: <E extends AnyEntity, User, R, RW>(entity: E, policy: Policy<User, R>, writer: EntityWriter<Option.Option<User>, RW>, options?: {
73
- readonly presets?: { readonly [K in keyof E['fields']]?: (user: User) => E['fields'][K]['schema']['Type']; };
74
102
  readonly revision?: keyof E['fields'] & string;
75
103
  }) => EntityWriter<Option.Option<User>, R | RW>;
76
104
  /**
@@ -80,8 +108,8 @@ export declare const GuardServer: {
80
108
  * rule must hold over it; a row its writer may not see is refused. With no
81
109
  * `id` (a create), the rule must hold of who is asking alone, a field it
82
110
  * reads matching no guard. `run` is given the row as read: its fields the
83
- * rule reads, its `id`, and `fields`. A refusal is `Forbidden`; `run` never
84
- * runs. What `run` writes is its own: check members it sets there. Each
111
+ * rule reads, its `id`, and `fields`. A refusal is `Forbidden`, or
112
+ * `Unauthenticated` for a visitor; `run` never runs. What `run` writes is its own: check members it sets there. Each
85
113
  * row of `entity` its answer carries is read back through `source`, so the
86
114
  * answer shows its writer only what they may see, a row it hid from them
87
115
  * as deleted.
@@ -120,11 +148,14 @@ export declare const GuardServer: {
120
148
  * `GuardServer.memory`), its Source applies its members' and relations'
121
149
  * (`GuardServer.filter`), and each declared write of it lands through
122
150
  * `GuardServer.writer`, all built from `policy`; and that no query's body
123
- * filters or orders by a member with a Read rule, which would answer for the
124
- * value it hides. A hand-written Source over a guarded Entity would serve
151
+ * filters or orders by a member with a Read rule, its own or one of a row it
152
+ * reaches through a path or an exists, which would answer for the value it
153
+ * hides. A hand-written Source over a guarded Entity would serve
125
154
  * every row, and a bare writer would take every write; this throws instead,
126
155
  * naming each. A handler (`RemoteServer.mutation`) writes what its code
127
- * writes, which no check at startup can read.
156
+ * writes, which no check at startup can read. A write a change can come
157
+ * between, through a writer given no revision, is not refused but reported:
158
+ * `UnpinnedWrites`, a warning, to `diagnostics`.
128
159
  *
129
160
  * ```ts
130
161
  * GuardServer.validate(Policy, { entities: [Todo, Project], domain: Data, server: Server })
@@ -142,6 +173,9 @@ export declare const GuardServer: {
142
173
  };
143
174
  };
144
175
  readonly server: ServerDefinition<any, any>;
176
+ /** Where the `UnpinnedWrites` warning goes; `Diagnostics.Reporter`'s default, the log, when not given. */
177
+ readonly diagnostics?: ReportDiagnostic | undefined;
145
178
  }) => void;
146
179
  };
180
+ export type { ComputeRefused, GuardDiagnostic, UnpinnedWrites };
147
181
  //# sourceMappingURL=server.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.mts","names":[],"sources":["../src/server.ts"],"mappings":";;;;;qBA4Ea;;;;;;;;;;EAUX,KAAK,MAAM,GAAC,QACF,UAAQ,QACR,OAAO,MAAM,OACpB,aAAa,OAAO,OAAO,OAAO;;;;;;;;;;EA6CrC,SAAS,MAAM,GAAC,QAAU,WAAS,QAAU,OAAO,MAAM,QAAE,WAG3C,OAAO,OAAO,OAAK,8BAE7B,OAAO,OAAO,iBAAiB;;;;;;;EAuEtC,SAAS,MAAI,QAAU,OAAO,OAAK,UAAY,cAAc;IAC3D,WAAQ,WAEO,OAAO,OAAO,OAAK,MACxB,gBAAgB,eAAe,OAAO,OAAO,SAAS,8BAC3D,OAAO,OAAO;IA4CnB;OAzHY,aAAA,WAAA,OAAA,OAAA,OAAA,8BAAiB,OAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+J/B,SAAS,UAAU,WAAW,MAAM,GAAG,IAAE,QAC/B,GAAC,QACD,OAAO,MAAM,IAAE,QACf,aAAa,OAAO,OAAO,OAAO,KAAG;aAElC,sBACG,WAAW,gBAAgB,MAAM,SAAS,YAAY;aAEzD,iBAAiB;QAE3B,aAAa,OAAO,OAAO,OAAO,IAAI;;;;;;;;;;;;;;;;;;;;;EA6hBzC,WAAW,MAAM,GAAG,IAAI,IAAI,qBAAqB,OAAO,QAAQ,SAAO,UAC3D,mBAAmB,MAAM,OAAO,QAAQ,UAAQ;aAE/C,QAAQ;aACR,QAAQ,OAAO,MAAM;aACrB,8CAA8C;;;;;;aAM9C,OAAO,OAAO,mBAAmB,OAAO;;aAExC,QAAQ,aAAa,OAAO,OAAO,OAAO;;aAE1C,SAAS;KACnB,MACK;aACK,OAAO;aACP,WAAW,OAAO,OAAO;aACzB;aACA,KAAK,OAAO,OAAO,SAAS;QACjC,OAAO,OACX,gBAAgB,SAChB,oBAAoB,kBAAkB,iBACtC,QAED,eAAe,OAAO,OAAO,OAAO,IAAI,KAAK;;;;;;;;;;;;;;;;;;EA6FhD,WAAW,MAAM,GAAC,QACR,OAAO,MAAM,IAAE;aAEZ,UAAU,cAAc;;aAExB;eACE;iBACE,SAAS;mBAEL;mBAA0B,OAAO;;;;aAIzC,QAAQ"}
1
+ {"version":3,"file":"server.d.mts","names":[],"sources":["../src/diagnostics.ts","../src/server.ts"],"mappings":";;;;;;;;;;UAciB,uBAAuB;WAC7B;WACA;;WAEA,OAAO;;;;;;UAOD,uBAAuB;WAC7B;WACA,WAAW;;;KAIV,kBAAkB,iBAAiB;qBC8FlC;;;;;;;;;;EAUX,KAAK,MAAM,GAAC,QACF,UAAQ,QACR,OAAO,MAAM,OACpB,aAAa,OAAO,OAAO,OAAO;;;;;;;;;;EA6CrC,SAAS,MAAM,GAAC,QAAU,WAAS,QAAU,OAAO,MAAM,QAAE,WAG3C,OAAO,OAAO,OAAK,8BAE7B,OAAO,OAAO,iBAAiB;;;;;;;EAuEtC,SAAS,MAAI,QAAU,OAAO,OAAK,UAAY,cAAc;IAC3D,WAAQ,WAEO,OAAO,OAAO,OAAK,MACxB,gBAAgB,eAAe,OAAO,OAAO,SAAS,8BAC3D,OAAO,OAAO;IA4CnB;OAzHY,aAAA,WAAA,OAAA,OAAA,OAAA,8BAAiB,OAAA,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAuK/B,SAAS,UAAU,WAAW,MAAM,GAAG,IAAE,QAC/B,GAAC,QACD,OAAO,MAAM,IAAE,QACf,aAAa,OAAO,OAAO,OAAO,KAAG;aAElC,iBAAiB;QAE3B,aAAa,OAAO,OAAO,OAAO,IAAI;;;;;;;;;;;;;;;;;;;;;EAymBzC,WAAW,MAAM,GAAG,IAAI,IAAI,qBAAqB,OAAO,QAAQ,SAAO,UAC3D,mBAAmB,MAAM,OAAO,QAAQ,UAAQ;aAE/C,QAAQ;aACR,QAAQ,OAAO,MAAM;aACrB,8CAA8C;;;;;;aAM9C,OAAO,OAAO,mBAAmB,OAAO;;aAExC,QAAQ,aAAa,OAAO,OAAO,OAAO;;aAE1C,SAAS;KACnB,MACK;aACK,OAAO;aACP,WAAW,OAAO,OAAO;aACzB;aACA,KAAK,OAAO,OAAO,SAAS;QACjC,OAAO,OACX,gBAAgB,SAChB,oBAAoB,kBAAkB,iBACtC,QAED,eAAe,OAAO,OAAO,OAAO,IAAI,KAAK;;;;;;;;;;;;;;;;;;;;;EAgGhD,WAAW,MAAM,GAAC,QACR,OAAO,MAAM,IAAE;aAEZ,UAAU,cAAc;;aAExB;eACE;iBACE,SAAS;mBAEL;mBAA0B,OAAO;;;;aAIzC,QAAQ;;aAER,cAAc"}