Repository navigation
Expand file tree
/
Copy pathengine-count-aggregate.ts
More file actions
254 lines (244 loc) · 12.8 KB
/
Copy pathengine-count-aggregate.ts
File metadata and controls
254 lines (244 loc) · 12.8 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
/**
* [#25522 cut 18] Two bodies of the `ObjectQL` "count / aggregate" section:
* `count` (the counting door, `find`'s sequence up to the driver's `count`)
* and `rejectCredentialAggregation` (`aggregate()`'s fail-closed guard against
* grouping or aggregating a field withheld on the generic read path), moved
* out of `engine.ts`.
*
* A MOVE, not a redesign. Each exported function below is the body of the
* `ObjectQL` method of the same name as it stood, re-indented one level and
* otherwise unedited. Each method's docblock stays on the method in
* `engine.ts`, which is still the contract.
*
* ## How the moved bodies reach the class
*
* The shape #23050 set for `rest-server.ts`, applied as
* `engine-driver-options.ts` applies it. The class keeps each method with
* name, modifiers, signature, docblock and position; its body becomes one
* literal of exactly the {@link CountAggregateHost} members it reads, plus a
* `.call`. The fields read (`_registry`, `relatedSchemaOf`) go as GETTERS, so
* each read happens when the body makes it, as it did; no body assigns a
* field. The methods called go as late-bound closures over the instance, so a
* double or spy set on the engine is still the one a call reaches.
* `aggregate` stays in the class: `packages/spec/liveness/query.json` names
* `engine.ts#aggregate` as a producer.
*
* ## Module helpers
*
* `count` reads seven top-level helpers that `find`, `findOne`, `update`,
* `delete` or `aggregate` read too: `foldEngineOptionAliases`,
* `ENGINE_WHERE_SLOTS`, `rejectUnknownEngineOptions`,
* `ENGINE_COUNT_OPTION_KEYS`, `lowerWhereFilterArray`, `mergeReadContext` and
* `declaredDatetimeLowering`. One home each: they stay declared in
* `engine.ts`, exported in place, and are imported here, never copied.
* Nothing re-exports them from the package entry, so the published surface
* does not move.
*
* That import is a run-time module cycle (`engine.ts` imports this module,
* this module imports `engine.ts`). Nothing here runs at module evaluation,
* only declarations, and the helpers are read only when a body runs, after
* both modules have evaluated. `engine.ts` imports this module right after
* `./secret-fields.js`, and the three other modules this one imports
* (`./secret-fields.js`, `./credential-evaluation-guard.js`,
* `./internal-field-evaluation-guard.js`) import nothing
* from `engine.ts`, so the evaluation order of every module is what it was; the
* `@objectstack/spec/api` import that left `engine.ts` with
* `rejectCredentialAggregation` was not that package's first load. The
* published build bundles both files into one, where the cycle does not
* exist.
*
* [#30053 codemod] A PRIVATE method's docblock has since moved here,
* onto its function (`--hand-docs` of `scripts/codemod-split-engine.mjs`),
* and the class keeps none for it; a public or protected method's docblock
* stays on the class, the contract, and its function keeps the placeholder.
*/
import type { EngineAggregateOptions, EngineCountOptions, QueryAST } from '@objectstack/spec/data';
// [#22646] The ADR-0112 catalog — `rejectCredentialAggregation`'s refusal
// envelope carries `INVALID_FIELD` from it rather than a bare `Error`.
import { StandardErrorCode } from '@objectstack/spec/api';
import {
collectInternalReadFields,
collectCredentialFields,
} from './secret-fields.js';
import { rejectCredentialEvaluation } from './credential-evaluation-guard.js';
import { rejectInternalFieldEvaluation } from './internal-field-evaluation-guard.js';
import {
ENGINE_COUNT_OPTION_KEYS,
ENGINE_WHERE_SLOTS,
declaredDatetimeLowering,
foldEngineOptionAliases,
lowerWhereFilterArray,
mergeReadContext,
rejectUnknownEngineOptions,
} from './engine.js';
import type { EngineReadOptions, ObjectQL, OperationContext } from './engine.js';
/**
* The `ObjectQL` members the functions below read — every one of them, and no
* other; each function's `this` is the `Pick` of the members IT reads. Each is
* typed AS the class member (an indexed access on the class), so a change to a
* member's type on the class is a change here too, and naming a member the
* class does not have is a compile error. See the module header for which
* members are getters.
*/
export interface CountAggregateHost {
readonly _registry: ObjectQL['_registry'];
readonly relatedSchemaOf: ObjectQL['relatedSchemaOf'];
resolveObjectName: ObjectQL['resolveObjectName'];
expandSearchOnOptions: ObjectQL['expandSearchOnOptions'];
getDriver: ObjectQL['getDriver'];
resolveWhereTokens: ObjectQL['resolveWhereTokens'];
executeWithMiddleware: ObjectQL['executeWithMiddleware'];
buildDriverOptions: ObjectQL['buildDriverOptions'];
composeReadableIdsAtBoundary: ObjectQL['composeReadableIdsAtBoundary'];
find: ObjectQL['find'];
}
/** The body of `ObjectQL#count`; the method's docblock there is its contract. */
export async function count(
this: Pick<CountAggregateHost, 'resolveObjectName' | '_registry' | 'relatedSchemaOf' | 'expandSearchOnOptions' | 'getDriver' | 'resolveWhereTokens' | 'executeWithMiddleware' | 'buildDriverOptions' | 'composeReadableIdsAtBoundary' | 'find'>,
object: string,
query?: EngineCountOptions,
options?: EngineReadOptions,
): Promise<number> {
object = this.resolveObjectName(object);
// Fold the `filter` alias into `where` (#4346) — the AST below reads
// `query.where` only, so an unfolded `{ filter }` counted the whole table.
query = foldEngineOptionAliases(object, 'count', query, ENGINE_WHERE_SLOTS);
rejectUnknownEngineOptions(object, 'count', query, ENGINE_COUNT_OPTION_KEYS);
query = lowerWhereFilterArray(object, 'count', query, this._registry.getObject(object), this.relatedSchemaOf);
// [ADR-0100] Same internal-field and credential-column refusals as `find`, same position.
rejectInternalFieldEvaluation(object, query, mergeReadContext(query?.context, options?.context), this.relatedSchemaOf);
rejectCredentialEvaluation(object, 'count', query, mergeReadContext(query?.context, options?.context), this.relatedSchemaOf);
// [#22790] ADR-0061 `search` → the rows are searched before they are
// counted, by the one expander `find` runs, at the same point in the
// sequence — so the count is the number of rows `find` returns for the bag.
if (query) query = await this.expandSearchOnOptions(object, query, options);
const driver = this.getDriver(object);
// The AST must ride on the opCtx so the security/sharing middlewares can
// inject their read filters (RLS, OWD/sharing scope) into `ast.where` —
// exactly like find(). Building it locally inside the executor (#2737)
// discarded every injected filter: `total` counted the RAW table while
// `records` were scoped, leaking invisible-row counts and breaking
// pagination.
const opCtx: OperationContext = {
object,
operation: 'count',
ast: { object, where: query?.where },
options: query,
context: mergeReadContext(query?.context, options?.context),
};
// [ADR-0053 D-D1, amended — #5930] Resolve, then lower. [#20802] …with
// the nested-relation step between the two.
await this.resolveWhereTokens(
opCtx.ast as QueryAST,
opCtx.context,
declaredDatetimeLowering(this._registry.getObject(object)),
'where',
'count',
);
// The caller's own `where`, placeholders expanded — captured BEFORE the
// middleware chain scopes `opCtx.ast.where`, so the find() fallback below
// still passes the unscoped filter (find() applies the read filters itself).
const callerWhere = (opCtx.ast as QueryAST).where;
await this.executeWithMiddleware(opCtx, async () => {
const countOpts = this.buildDriverOptions(object, opCtx.context, undefined, { recordedVerdict: opCtx.tenantLayer0Verdict });
if (driver.count) {
// [ADR-0139 D2] The executor boundary, as in `find` (`count` has no
// before-hook): the AST is final once the chain has run. The
// `find()` fallback below composes at its own boundary.
return driver.count(
object,
await this.composeReadableIdsAtBoundary(object, 'count', opCtx.ast as QueryAST, opCtx.context),
countOpts,
);
}
// Fallback to find().length — find() applies the read filters itself,
// so pass the caller's original where, not the already-scoped ast.
const res = await this.find(object, { where: callerWhere, fields: ['id'], context: opCtx.context });
return res.length;
});
return opCtx.result as number;
}
/**
* Fail-closed guard (ADR-0100 / #3171 / #7922): refuse to aggregate over a
* field whose value is withheld on the generic read path. Such fields reach
* this guard through **two independent collectors**, and it needs both:
*
* - {@link collectCredentialFields} — keyed by field TYPE (`secret` /
* `password`). A GROUP BY / MIN / MAX / array_agg over such a column would
* surface the stored `secret:<id>` ref or the password value.
* - {@link collectInternalReadFields} — keyed by the `internal: true` FLAG
* (#7728). ADR-0100's third credential channel is a one-way hash living in
* an ordinary `text` column, which no type-keyed collector can ever reach;
* the flag is that channel's opt-in declaration. Without this half the
* guard had the same type-vs-flag blind spot #7728 fixed on the read path:
* a flagged column was omitted from `find`/`findOne` yet freely groupable
* here, so the flag's promise ("never returned on the generic data path")
* stopped at the edge of `aggregate()`.
*
* Post-hoc masking is not available on this path — the value is already a
* group key by the time there is a row, and masking group keys corrupts the
* result. So we reject instead.
*
* Neither collector carries a `managedBy` exemption, so the union does not
* acquire one, deliberately. Read-masking exempts `password` on better-auth
* objects so login reads still see the stored value; *aggregating* a
* credential is never legitimate, least of all on an identity table, where it
* is an inference oracle over hashes.
*
* Only the two output-bearing positions on `EngineAggregateOptions` carry
* field names: `aggregations[].field` (skip COUNT(*) — undefined or '*') and
* `groupBy[]` (a string, or a `{ field }` bucket object).
*
* The refusal carries the ADR-0112 envelope — `INVALID_FIELD` / 400, located
* at the object and the field(s) named. It used to be a bare `Error` with no
* `code` or `status`, so a 400-class author refusal reached the data door
* 500-shaped (`INTERNAL_ERROR`, an undeclared fault). The code matches the
* analytics door's own refusal of an `internal: true` member and the engine's
* structured-JSON group-by refusal: the verdict is about the NAME being a
* field that is never returned on a generic data exit, which `INVALID_FIELD`
* is the catalog member for. The envelope now binds the `secret` / `password`
* case too, which shared the bare `Error`.
*/
export function rejectCredentialAggregation(
this: Pick<CountAggregateHost, '_registry'>,
object: string,
query: EngineAggregateOptions,
): void {
const schema = this._registry.getObject(object);
// Deduped: one field can be reachable through both collectors (a `secret`
// column that is also flagged `internal`), and it must be named once.
const protectedFields = [
...new Set([...collectCredentialFields(schema), ...collectInternalReadFields(schema)]),
];
if (protectedFields.length === 0) return;
const referenced = new Set<string>();
for (const agg of query?.aggregations ?? []) {
const field = (agg as { field?: string })?.field;
if (field && field !== '*') referenced.add(field);
}
for (const g of query?.groupBy ?? []) {
const field = typeof g === 'string' ? g : g?.field;
if (field) referenced.add(field);
}
const hit = protectedFields.filter((f) => referenced.has(f));
if (hit.length > 0) {
const err = new Error(
`Cannot aggregate credential field(s) ${hit.map((f) => `"${object}.${f}"`).join(', ')}: `
+ 'secret/password fields are masked on read and `internal: true` fields are omitted '
+ 'outright, so the value never leaves the engine on the generic data path; aggregating '
+ 'them (group-by, min/max, array_agg, …) would surface it. '
+ 'Refusing (fail-closed) — see ADR-0100.',
) as Error & { code?: string; status?: number; httpStatus?: number; field?: string; fields?: string[]; object?: string };
// ADR-0112 envelope, the same number under D5's two spellings — `status`
// for the HTTP doors, `httpStatus` for a consumer holding the thrown
// error (the CLI `--json` envelope).
err.code = StandardErrorCode.enum.INVALID_FIELD;
err.status = 400;
err.httpStatus = 400;
err.field = hit[0];
err.fields = hit;
err.object = object;
throw err;
}
}