|
| 1 | +// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license. |
| 2 | + |
| 3 | +/** |
| 4 | + * The mark a service's own write carries for ONE reference value it vouches |
| 5 | + * for: a record the same call has itself authorized and created. |
| 6 | + * |
| 7 | + * ## The rule it answers to |
| 8 | + * |
| 9 | + * A write that is not a system write may name, in a `lookup`, `user` or |
| 10 | + * `master_detail` field, only a record its caller's own read door returns; a |
| 11 | + * record the caller cannot read answers `reference_not_found` |
| 12 | + * (`assertReferencesResolve`, objectql). That rule judges a reference the |
| 13 | + * CALLER chose. Some service verbs write, as the caller, a row that links to a |
| 14 | + * record the verb created a moment earlier in the same call, after asking its |
| 15 | + * own authorization question first. The file-attachments verb is the case: it |
| 16 | + * asks the attach rule (`assertMayAttach`), stores a new `sys_file` for the |
| 17 | + * caller, then inserts the `sys_attachment` naming it AS the caller, so every |
| 18 | + * gate on that insert judges the caller. The caller did not choose that file |
| 19 | + * id, and a caller who may attach files need not read `sys_file` at all, so |
| 20 | + * the read-door question has nothing to judge there; asking it refuses the |
| 21 | + * verb outright. |
| 22 | + * |
| 23 | + * ## What it admits, and what it does not |
| 24 | + * |
| 25 | + * The mark names one `(object, field, id)`. The reference check reads it for |
| 26 | + * exactly that value on a write to that object: the caller's read door is not |
| 27 | + * asked for it, and the elevated, tenant-kept existence probe still is, so an |
| 28 | + * id that names no row of the caller's organization is refused as before. |
| 29 | + * Everything else about the write stays the caller's: every other field and |
| 30 | + * every other value in the same field is judged through the caller's read door, |
| 31 | + * and nothing about RLS, FLS, the owner and audit stamps, the object's hooks |
| 32 | + * or the caller's read of anything changes. It grants no read. |
| 33 | + * |
| 34 | + * ## Where it is set — and where it is never set |
| 35 | + * |
| 36 | + * Only by a service verb, on the one write it makes for the record it just |
| 37 | + * created, after that verb's own authorization: today the file-attachments |
| 38 | + * writer's `sys_attachment` insert (`FileAttachmentService.attachFileAs`, |
| 39 | + * service-storage). ⛔ Never on a context a request, an import, a flow, an |
| 40 | + * agent tool or any other generic data door hands the engine: a reference such |
| 41 | + * a door carries is the caller's choice, and the read-door rule judges it. |
| 42 | + * |
| 43 | + * ## Why a symbol, and why it is not an `ExecutionContext` field |
| 44 | + * |
| 45 | + * The same reasons as `FLOW_WRITE_REFERENCE_CHECK`: no request body, query |
| 46 | + * string, stored row or flow definition can spell a symbol, so no author can |
| 47 | + * set it; it is in no schema; `Symbol.for` keeps it one key across the ESM and |
| 48 | + * CJS builds; and, being undeclared, it does not survive |
| 49 | + * `ExecutionContextSchema.parse`. It rides a spread of the context as any own |
| 50 | + * property does, so a write a hook sets off under the vouched write carries it |
| 51 | + * too, and is admitted only for the same object, field and id. |
| 52 | + */ |
| 53 | + |
| 54 | +/** The context key of the mark. See the module header. */ |
| 55 | +export const VOUCHED_REFERENCES: unique symbol = Symbol.for('objectstack.core.vouchedReferences'); |
| 56 | + |
| 57 | +/** One reference value a service vouches for: `field` of a write to `object`, naming `id`. */ |
| 58 | +export interface VouchedReference { |
| 59 | + readonly object: string; |
| 60 | + readonly field: string; |
| 61 | + readonly id: string; |
| 62 | +} |
| 63 | + |
| 64 | +/** |
| 65 | + * `context` with `reference` added to the references it vouches for — a fresh |
| 66 | + * object; `context` is not changed. Called only by a service verb, for a |
| 67 | + * record the same call created (see the module header). |
| 68 | + */ |
| 69 | +export function vouchForReference<T extends object>( |
| 70 | + context: T, |
| 71 | + reference: VouchedReference, |
| 72 | +): T & { [VOUCHED_REFERENCES]: ReadonlyArray<VouchedReference> } { |
| 73 | + const held = (context as { [VOUCHED_REFERENCES]?: unknown })[VOUCHED_REFERENCES]; |
| 74 | + const prior = Array.isArray(held) ? (held as ReadonlyArray<VouchedReference>) : []; |
| 75 | + const entry: VouchedReference = Object.freeze({ |
| 76 | + object: String(reference.object), |
| 77 | + field: String(reference.field), |
| 78 | + id: String(reference.id), |
| 79 | + }); |
| 80 | + return { ...context, [VOUCHED_REFERENCES]: Object.freeze([...prior, entry]) }; |
| 81 | +} |
| 82 | + |
| 83 | +/** |
| 84 | + * Does `context` vouch for `id` in `field` of a write to `object`? `false` for |
| 85 | + * every other value, field, object and context. |
| 86 | + */ |
| 87 | +export function isVouchedReference(context: unknown, object: unknown, field: unknown, id: unknown): boolean { |
| 88 | + if (context === null || typeof context !== 'object') return false; |
| 89 | + if (typeof object !== 'string' || typeof field !== 'string') return false; |
| 90 | + if (typeof id !== 'string' && typeof id !== 'number') return false; |
| 91 | + const held = (context as { [VOUCHED_REFERENCES]?: unknown })[VOUCHED_REFERENCES]; |
| 92 | + if (!Array.isArray(held)) return false; |
| 93 | + const value = String(id); |
| 94 | + return held.some( |
| 95 | + (r) => r !== null && typeof r === 'object' |
| 96 | + && (r as VouchedReference).object === object |
| 97 | + && (r as VouchedReference).field === field |
| 98 | + && (r as VouchedReference).id === value, |
| 99 | + ); |
| 100 | +} |
0 commit comments